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):
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):
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):
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):
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.
        
API Documentation for planes, generated by pydoctor at 2013-03-05 14:16:20.