# cocos.layer.scrolling module

This module defines the `ScrollableLayer` and `ScrollingManager` classes.

This module helps to handle what will be visible on screen when the game world does not fit in the window area.

It models this concept: the game world is a big volume. We have a camera that follows the actor moving parallel to one of the volume faces, without rotations. What the camera sees is what will be seen on the app window. Also, the camera’s movements can be restricted in order not to show parts outside of the world. This technique is usually named ‘scrolling’.

It has support for parallax rendering, that is, faking perspective by using layers that slide slower the farther they are.

The important concepts are:

  - The coordinator, implemented as `ScrollingManager` which enforces the view limits imposed by the managed layers, accounts for layer’s parallax.

  - The managed layers, implemented each by a `ScrollableLayer`, which as a group holds all the entities in the world and each one can define what area of the x-y plane should be shown on camera.

  -The focus, tied to ScrollingManager `fx` and `fy` attributes, which

    indicates that point (fx, fy) in world coordinates is the point of interest, and should show at the center of the screen view if no restriction is violated.

class `ScrollableLayer`(parallax=1)

  Bases: `cocos.layer.base_layers.Layer`

  Layer that supports scrolling.

  If `px_width` is defined, then `px_height` must also be defined; scrolling will be limited to only show areas with origin_x <= x < = px_width and origin_y <= y <= px_height).

  If `px_width` is not defined, then the layer will not limit the scrolling.

  A layer may have a `parallax` value which is used to scale the position (and not the dimensions) of the view for 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

  The scrolling is managed by the parent node of `ScrollingManager` class.

  Warning

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

  Parameters

    parallax (float) – the parallax for this layer. Defaults to 1.

  `draw`()

    Draws itself

  `on_cocos_resize`(usable_width, usable_height)

    Event handler for window resizing.

  `on_enter`()

    Called every time just before the node enters the stage.

  `on_exit`()

    Called every time just before the node exits the stage.

  `set_dirty`()

    The viewport has changed in some way.

  `set_view`(x, y, w, h, viewport_ox=0, viewport_oy=0)

    Sets the position of the viewport for this layer.

    Parameters

      - x (float) – The view x position

      - y (float) – The view y position

      - w (float) – The width of the view

      - h (float) – The height of the view

      - viewport_ox (float) – The viewport x origin

      - viewport_oy (float) – The viewport y origin

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

  Bases: `cocos.layer.base_layers.Layer`

  Handles scrolling for his children, which should be ScrollableLayer instances.

  Restricts the scrolling so that all the visibility restriction imposed by the children are honored; at least one child should define a constraint for the scrolling to be limited.

  The drawing can be limited to a specific window’s rectangle by passing the `viewport` parameter.

  The scrolling manager also provides coordinate changes between screen coords and world coords.

  Parameters

    - viewport (Rect) – A rectangle defining the viewport. [Optional]

    - do_not_scale (bool) – Whether the `ScrollingManager` should scale the view during Window resizes. (Defaults to None, meaning it takes the same value as `director.autoscale`)

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

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

    Parameters

      - child (CocosNode) – The node to add. Normally it’s a `ScrollableLayer`.

      - z (int) – z-order for this child.

      - name (str) – The name of this child. [Optional]

  `force_focus`(fx, fy)

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

    Parameters

      - fx (int) – the focus point x coordinate

      - fy (int) – the focus point y coordinate

  `on_cocos_resize`(usable_width, usable_height)

    Event handler for Window resize.

  `on_enter`()

    “Called every time just before the node enters the stage.

  `on_exit`()

    Called every time just before the node exits the stage.

  `pixel_from_screen`(x, y)

    deprecated, was renamed as screen_to_world

  `pixel_to_screen`(x, y)

    deprecated, was renamed as world_to_screen

  `refresh_focus`()

    Resets the focus at the focus point.

  `screen_to_world`(x, y)

    Translates screen coordinates to world coordinates.

    Account for viewport, layer and screen transformations.

    Parameters

      - x (int) – x coordinate in screen space

      - y (int) – y coordinate in screen space

    Returns

      tuple[int, int] – coordinates in world-space

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

    Makes the point (fx, fy) show as near the view’s center as possible.

    Changes his children so that the point (fx, fy) in world coordinates will be seen as near the view center as possible, while at the same time not displaying out-of-bounds areas in the children.

    Parameters

      - fx (int) – the focus point x coordinate

      - fy (int) – the focus point y coordinate

      - force (bool) – If True, forces the update of the focus, eventhough the focus point or the scale did not change. Defaults to False.

  `set_state`()

    Sets OpenGL state for using scissor test.

  `unset_state`()

    Unsets OpenGL state for using scissor test.

  `update_view_size`()

    Updates the view size based on the director usable width and height, and on the optional viewport.

  `visit`()

    Draws itself and its children into the viewport area.

    Same as in `CocosNode.visit()`, but will restrict drawing to the rect viewport.

  `world_to_screen`(x, y)

    Translates world coordinates to screen coordinates.

    Account for viewport, layer and screen transformations.

    Parameters

      - x (int) – x coordinate in world space

      - y (int) – y coordinate in world space

    Returns

      tuple[int, int] – coordinates in screen space

  property `scale`

    The scaling factor of the object.

    Type

      float