# p.Plane : class documentation

Part of planes View In Hierarchy

Known subclasses: planes.Display, planes.gui.Container, planes.gui.Label, planes.gui.PlusMinusBox, planes.gui.ProgressBar, planes.gui.ScrollingPlane

    A Plane is a surface in a hierarchy of surfaces.
    Concept-wise it bears some similarities to pygame.sprite.Sprite.

    Planes are currently not thread safe! Accessing a Plane from several
    threads may produce unexpected results and errors.

    Attributes:

    Plane.name
        Name of the plane.

    Plane.image
        The pygame.Surface for this Plane.

    Plane.rendersurface
        A pygame.Surface displaying the composite of this plane and all
        subplanes.

    Plane.rect
        The render position of this Plane on the parent Plane.

    Plane.parent
        The parent plane. Initially None.

    Plane.subplanes
        Dict of subplanes, identified by their name.

    Plane.subplanes_list
        A list of subplane names, in order of their addition

    Plane.draggable
        Boolean flag. If True, this Plane can be dragged and dropped.

    Plane.grab
        Boolean flag. If True, this Plane will remove dropped Planes from
        their parent Plane and make it a subplane of this one.
        Handled in Plane.dropped_upon()

    Plane.highlight
        Boolean flag. If True, the Plane be highlighted when the mouse cursor
        moves over it.

    Plane.last_image_id
        Caches object id of the image at last rendering for efficiency.

    Plane.last_rect
        Caches rect at last rendering for efficiency.

    Plane.left_click_callback
        Callback function when this plane has been clicked with the left
        mouse button.

    Plane.right_click_callback
        Callback function when this plane has been clicked with the right
        mouse button.

    Plane.up_click_callback
        Callback function when the mouse wheel has been moved up above this
        Plane.

    Plane.down_click_callback
        Callback function when the mouse wheel has been moved down above this
        Plane.

    Plane.dropped_upon_callback
        Callback function when a plane has been dropped upon this plane.

    Plane.mouseover_callback
        Callback function when the mouse cursor moves over this plane.

    Plane.mouseout_callback
        Callback function when the mouse cursor has left this plane.

    Plane.mouseover
        Flag indicating whether the mouse cursor is over this Plane.
        Initially False.

    Plane.sync_master_plane
       A Plane that this Plane's position will sync to. Initally None.

    Plane.offset
       A tuple (x, y) describing the offset to the sync master plane.
       Initially None.

Method | __init__ | No summary
Method | sub | `Remove the Plane given from its current parent and add it as a subplane of this Plane.`
Method | remove | `Remove subplane by name or Plane instance.`
Method | remove_all | `Convenience method to call Plane.remove() for all subplanes.`
Method | __getattr__ | `Access subplanes as attributes.`
Method | render | `Draw a composite surface of this plane and all subplanes, in order of their addition.`
Method | get_plane_at | `Return the (sub)plane and the succeeding parent coordinates at the given coordinates. Subplanes are tested in reverse order of their addition (i.e. latest first).`
Method | update | No summary
Method | clicked | `Called when there is a MOUSEDOWN event on this plane. If click callbacks are set, the appropriate one is called with this Plane as argument.`
Method | dropped_upon | `If a plane is dropped on top of this one, call dropped_upon_callback() and conditionally grab it.`
Method | destroy | `Remove this Plane from the parent plane, remove all subplanes and delete all pygame Surfaces.`
Method | sync | `Save the Plane given as master Plane and the position offset to that Plane for position synchronisation in Plane.update().`
Method | unsync | `Remove the position synchronisation to the sync master Plane.`
Method | mouseover_callback | `Callback function when the mouse cursor moves over this plane. The default implementation sets Plan.mouseover to True when Plane.highlight is set.`
Method | mouseout_callback | `Callback function when the mouse cursor has left this plane. The default implementation sets Plan.mouseover to False.`
Method | __repr__ | `Readable string representation.`

def __init__(self, name, rect, draggable=False, grab=False, highlight=False, left_click_callback=None, right_click_callback=None, up_click_callback=None, down_click_callback=None, dropped_upon_callback=None):
overridden in planes.Display, planes.gui.Container, planes.gui.Label, planes.gui.PlusMinusBox, planes.gui.ProgressBar, planes.gui.ScrollingPlane

    Initialize the Plane.
    name is the name of the plane which can also be used
    as an attribute.
    rect is an instance of pygame.Rect giving width, height
    and render position.
    draggable is a flag indicating whether this plane can be dragged.
    grab is a flag indicating whether other planes can be dropped
    on this one.
    clicked_callback and dropped_upon_callback, if given, must be
    functions.
    Planes are filled with solid black color by default.

def sub(self, plane, insert_after=None):
overridden in planes.gui.Container

    Remove the Plane given from its current parent and add it as a subplane of this Plane.

    If insert_after is given, the new subplane will be inserted
    immediately after the subplane with that name in Plane.subplanes_list,
    else it will simply be appended.

    If a subplane with the same name already exists, it is silently
    replaced by the new plane.

def remove(self, plane_identifier):
overridden in planes.gui.Container

    Remove subplane by name or Plane instance.

def remove_all(self):
overridden in planes.gui.Container

    Convenience method to call Plane.remove() for all subplanes.

def __getattr__(self, name):

    Access subplanes as attributes.

def render(self, displayrect=None):
overridden in planes.Display, planes.gui.FadingContainer

    Draw a composite surface of this plane and all subplanes, in order of their addition.

    displayrect is the Rect of the Display, displaced relatively to this
    Plane's Rect, so collision of subplanes can be tested using
    Rect.colliderect(displayrect).

    Returns True if anything has been rendered (i.e. when
    Plane.rendersurface has changed), False otherwise.

    This method will highlight subplanes that have the Plane.mousover
    flag set.

def get_plane_at(self, coordinates):

    Return the (sub)plane and the succeeding parent coordinates at the given coordinates.
    Subplanes are tested in reverse order of their addition (i.e. latest first).

def update(self):
overridden in planes.gui.FadingContainer, planes.gui.Label, planes.gui.ProgressBar

    Update hook.
    The default implementation calls update() on all subplanes. If
    Plane.sync_master_plane is not None, the position of this Plane will
    be synced to that of the master Plane, using Plane.offset.
    Compare pygame.sprite.Sprite.update.

def clicked(self, button_name):
overridden in planes.gui.Button, planes.gui.Option

    Called when there is a MOUSEDOWN event on this plane.
    If click callbacks are set, the appropriate one is called with this
    Plane as argument.

def dropped_upon(self, plane, coordinates):

    If a plane is dropped on top of this one, call dropped_upon_callback() and conditionally grab it.

    If Plane.grab is True, the default implementation will remove the
    dropped Plane from its parent and make it a subplane of this one.

    If the dropped Plane is already a subplane of this one, its position
    is updated.

    If Plane.dropped_upon_callback is set, it is called with
    Plane.dropped_upon_callback(self, plane, coordinates)

def destroy(self):

    Remove this Plane from the parent plane, remove all subplanes and delete all pygame Surfaces.

def sync(self, master_plane):

    Save the Plane given as master Plane and the position offset to that Plane for position synchronisation in Plane.update().

def unsync(self):

    Remove the position synchronisation to the sync master Plane.

def mouseover_callback(self):

    Callback function when the mouse cursor moves over this plane.
    The default implementation sets Plan.mouseover to True when
    Plane.highlight is set.

def mouseout_callback(self):

    Callback function when the mouse cursor has left this plane.
    The default implementation sets Plan.mouseover to False.

def __repr__(self):

    Readable string representation.