# cocos.layer.scrolling module

This module defines the ScrollableLayer and ScrollingManager classes.

## Controlling Scrolling

You have two options for scrolling:

1. automatically scroll the map but stop at the map edges, and
2. scroll the map an allow the edge of the map to be displayed.

The ScrollingManager has a concept of “focus” which is the pixel position of the player’s view focus (usually the center of the player sprite itself, but the player may be allowed to move the view around, or you may move it around for them to highlight something else in the scene). The ScrollingManager is clever enough to manage many layers and handle scaling them.

Two methods are available for setting the map focus:

set_focus(x, y)
  Attempt to set the focus to the pixel coordinates given. The layer(s) contained in the ScrollingManager are moved accordingly. If a layer would be moved outside of its define px_width, px_height then the scrolling is restricted. The resultant restricted focal point is stored on the ScrollingManager as restricted_fx and restricted_fy.
force_focus(x, y)
  Force setting the focus to the pixel coordinates given. The layer(s) contained in the ScrollingManager are moved accordingly regardless of whether any out-of-bounds cells would be displayed. The .fx and .fy attributes are still set, but they’ll always be set to the supplied x and y values.

class `ScrollableLayer`(parallax=1)

  Bases: `cocos.layer.base_layers.Layer`

  A Cocos Layer that is scrollable in a Scene.

  A layer may have a “parallax” value which is used to scale the position (and not the dimensions) of the view of the layer - the layer’s view (x, y) coordinates are calculated as:

      my_view_x = parallax * passed_view_x
      my_view_y = parallax * passed_view_y

  Scrollable layers have a view which identifies the section of the layer currently visible.

  The scrolling is usually managed by a ScrollingManager.

  Don’t change scale_x , scale_y from the default 1.0 or scrolling and coordinate changes will fail

  `draw`()
  `on_cocos_resize`(usable_width, usable_height)
  `on_enter`()
  `on_exit`()
  `set_dirty`()

    The viewport has changed in some way.

  `set_view`(x, y, w, h, viewport_ox=0, viewport_oy=0)
  `origin_x` = 0
  `origin_y` = 0
  `origin_z` = 0
  `view_h` = 0
  `view_w` = 0
  `view_x` = 0
  `view_y` = 0

class `ScrollingManager`(viewport=None, do_not_scale=None)

  Bases: `cocos.layer.base_layers.Layer`

  Manages scrolling of Layers in a Cocos Scene.

  Each ScrollableLayer that is added to this manager (via standard list methods) may have pixel dimensions .px_width and .px_height. Tile module MapLayers have these attribtues. The manager will limit scrolling to stay within the pixel boundary of the most limiting layer.

  If a layer has no dimensions it will scroll freely and without bound.

  The manager is initialised with the viewport (usually a Window) which has the pixel dimensions .width and .height which are used during focusing.

  A ScrollingManager knows how to convert pixel coordinates from its own pixel space to the screen space.

  `add`(child, z=0, name=None)

    Add the child and then update the manager’s focus / viewport.

  `force_focus`(fx, fy)

    Force the manager to focus on a point, regardless of any managed layer visible boundaries.

  `on_cocos_resize`(usable_width, usable_height)
  `on_enter`()
  `on_exit`()
  `pixel_from_screen`(x, y)

    Look up the Layer-space pixel matching the screen-space pixel.

    Account for viewport, layer and screen transformations.

  `pixel_to_screen`(x, y)

    Look up the screen-space pixel matching the Layer-space pixel.

    Account for viewport, layer and screen transformations.

  `refresh_focus`()
  `set_focus`(fx, fy, force=False)

    Determine the viewport based on a desired focus pixel in the Layer space (fx, fy) and honoring any bounding restrictions of child layers.

    The focus will always be shifted to ensure no child layers display out-of-bounds data, as defined by their dimensions px_width and px_height.

  `set_scale`(scale)
  `set_state`()
  `unset_state`()
  `update_view_size`()
  `visit`()
  `scale`