gillcup_graphics.objects

Drawable objects

This module provides basic objects you can draw and animate.

Perhaps the most important of these is the Layer, which does not have a graphical representation by itself, but can contain other objects, such as a Rectangle, Sprite or another Layer. Graphics objects are thus arranged in a scene tree. The tree is rooted at a parent-less Layer [1], which will usually be shown in a Window.

Each object has a lot of AnimatedProperties that control its position on the screen (relative to its parent), and properties like color and opacity.

The objects are compatible with 3D transformations, but anything outside the z=0 plane needs custom OpenGL camera setup. Refer to Pyglet documentation for details.

[1]	To be precise, the root may be any object. It’s just that non-Layers aren’t terribly useful here.

class gillcup_graphics.GraphicsObject(parent=None, to_back=False, name=None, **kwargs)

Base class for gillcup_graphics scene objects

Parameters:

• parent – The parent Layer in the scene tree
• to_back – If false (default), the object is inserted at the end of the parent’s children list, and thus is drawn after (in front of) its existing siblings. If true, it will be is drawn before (behind) them.
• name – An optional name of the object. It is stored in the name attribute.
• kwargs – Any animated property (including those from subclasses) can be initialized by passing a value as a keyword argument to __init__.

draw(**kwargs)

Draw this object. Overridden in subclasses.

Parameters:

• transformation – A GlTransformation object controlling the current OpenGL matrix.
• window – A Window for which the drawing is done.

Additional keyword arguments might be present. Unknown ones should be passed to child objects unchanged.

reparent(new_parent, to_back=False)

Set a new parent

Remove this object from the current parent (if there is one) and attech to a new one (if new_parent is not None. The to_back argument is the same as for __init__().

Beware that reparenting may throw off the pointer tracking mechanism. Specifically, ‘leave’ and ‘release’ events might not fire properly.

Animated Properties:

position

The object’s position in space

This is an offset between the parent’s anchor and this object’s own anchor, in the parent’s coordinates.

The individual components are in the x, y, z attributes.

anchor

A point that represents this object for positioning.

The individual components are in the anchor_x, anchor_y, anchor_z attributes.

relative_anchor

Anchor of the object relative to the object’s size

When relative_anchor is (1, 1), the anchor is in the object’s upper right corner. When relative_anchor is (0.5, 0.5), anchor will me in the middle.

This property is only effective if anchor is not set by other means.

The individual components are in the relative_anchor_x, relative_anchor_y, relative_anchor_z attributes.

scale

The object’s scale.

The individual components are in the scale_x, scale_y, scale_z attributes.

size

The object’s natural size

The individual components are in the width and height attributes.

rotation

Rotation about the object’s anchor

Event handlers:

pointer_event(event_type, pointer, x, y, z, **kwargs)

Handle a pointer (mouse) event

Dispatches to on_pointer_<event> methods. See Layer for the available handlers.

on_pointer_motion(pointer, x, y, z, **kwargs)

Handle pointer (mouse) movement

Called when a pointer moves to point (x, y, z) of the object. The coordinates are in the object’s own coordinate space.

Return a true value to stop the event from propagating to objects further down.

Remember to override the hit_test method so the object’s shape is known to the pointer handling machinery.

on_pointer_leave(pointer, x, y, z, **kwargs)

Handle pointer (mouse) leaving the object

Called when a pointer moves to point (x, y, z), which is outside the object. The coordinates are in the object’s own coordinate space.

If the pointer left without known coordinates (this can happen, for example, when the object’s transformation matrix becomes singular), all of x, y, z will be set to False (which is equal to 0).

All objects that recieved a ‘motion’ event for a pointer will recieve a ‘leave’ event for that pointer, unless they (or their parent chains) are destroyed first.

on_pointer_press(pointer, x, y, z, button, **kwargs)

Handle a pointer (mouse) button press on this object

Called when a pointer button is pressed on point (x, y, z) of the object. The coordinates are in the object’s own coordinate space.

Return a true value to “claim” the resulting drag operation. The claiming object will receive ‘drag’ and ‘release’ pointer events. Returning true also stops the event’s propagation to objects further below.

Subsequent drag and release events follow the pointer even outside the object, including outside the window itself.

on_pointer_drag(pointer, x, y, z, button, **kwargs)

Handle a pointer (mouse) drag on this object

Called when a pointer is dragged (with a button pressed) on point (x, y, z) of the object. The coordinates are in the object’s own coordinate space, and may be outside the object (or even the window).

Drag events are only triggered for objects that “claimed” a press event.

on_pointer_release(pointer, x, y, z, button, **kwargs)

Handle a pointer (mouse) button release on this object

Called when a pointer button is released on point (x, y, z) of the object. The coordinates are in the object’s own coordinate space, and may be outside the object (or even the window).

Release events are only triggered for objects that “claimed” a press event. The object that claimed a ‘press’ event for a pointer will recieve a ‘release’ event for that pointer/button combination, unless it (or its parent chain) is destroyed first.

Other subclassable methods:

is_hidden()

Return true if this object (and any children) aren’t active

Hidden objects are not shown and do not handle events.

If the hidden attribute of self is true, this method will return true. Otherwise, it checks self.dead and other properties that can hide the object, such as zero scale.

hit_test(_x, _y, _z)

Perform a hit test on this object

Return false if the given point (in local coordinates) is “outside” the object.

transform(transformation)

Set up the transformation matrix for object

Parameters:transformation – The BaseTransformation object to modify in-place.

No push() or pop() calls should be made, only transformations.

die()

Destroy this object

Sets up to detach from the parent on the next frame, and calls die() on all children.

Internal methods:

set_animated_properties(kwargs)

Initializes animated properties with keyword arguments

Raises an error if any extra arguments are found.

die()

Destroy this object

Sets up to detach from the parent on the next frame, and calls die() on all children.

class gillcup_graphics.Layer(parent=None, **kwargs)

A container for GraphicsObjects

The Layer is unique in that it can contain child objects.

Init arguments are the same as for GraphicsObject.

draw(transformation, **kwargs)

Draw all of the layer’s children

class gillcup_graphics.DecorationLayer(parent=None, **kwargs)

A Layer that does not respond to hit tests

Objects in this layer will not be interactive.

class gillcup_graphics.Rectangle(parent=None, to_back=False, name=None, **kwargs)

A box of color

hit_test(x, y, _z)

Perform a hit test on the rectangle

Animated Properties:

color

Color or tint of the object

The individual components are in the red, green, blue attributes.

opacity

Opacity of the object

class gillcup_graphics.Sprite(parent, texture, **kwargs)

An image

Parameters:texture – A Pyglet image to show in this sprite. You can use the pyglet.image.load() to obtain one.

Other init arguments are the same as for GraphicsObject.

hit_test(x, y, _z)

Perform a hit test on this object. Uses the sprite size.

Does not take e.g. alpha into account

Animated Properties:

color

Color or tint of the object

The individual components are in the red, green, blue attributes.

opacity

Opacity of the object

class gillcup_graphics.Text(parent, text, font_name=None, **kwargs)

A text label

Parameters:

• text – A string to display n this label
• font_name – Name of the font to use. See Pyglet documentation for more info on using fonts.

Other init arguments are the same as for GraphicsObject.

Note

The API regarding font size is experimental.

hit_test(x, y, _z)

Perform a hit test on this object. Uses the bounding rectangle.

size

The natural size of the text

This property is not animated, and cannot be changed.

Returns the size of the entire text, i.e. doesn’t take characters_displayed into account.

The width and height attributes contain the size’s individual components.

Animated Properties:

color

Color or tint of the object

The individual components are in the red, green, blue attributes.

opacity

Opacity of the object

font_size

The size of the font

characters_displayed

The maximum number of characters displayed