Appendix A: LiveWires Reference
This appendix includes almost everything you ever wanted to know about the 
livewires package but were afraid to ask. I do leave out a few details for simplicity. If you want the ultimate "documentation," you can always check out the source code of the modules themselves. On a Windows machine, you should find the modules in the C:\Python22\Lib\site-packages\livewires folder. And remember, as I said in Chapter 11, this book uses a modified version of livewires.
games Module Classes
games is a module of the livewires package that contains a group of classes for game programming: Screen, Games_Object, Text, Message, Sprite, and Animation.
The Screen Class
A Screen object provides a region on which graphics objects can exist. You create a new Screen object with
Screen([width][, height])
Table A.1 describes the attributes defined in Screen.
| Attribute | Description |
|---|---|
| width | Width of the graphics screen. The default value is 640. |
| height | Height of the graphics screen. The default value is 480. |
Table A.2 describes useful Screen methods.
| Method | Description |
|---|---|
| init_screen ([width] [, height]) | Initializes a Screen object. Automatically invoked in Screen's constructor. You would only directly invoke this method if you subclassed Screen, to initialize a new object. |
| set_background(image) | Sets the background of a Screen object to image object image. |
| mouse_pos() | Returns the x- and y-coordinates of the mouse pointer on a Screen object as a two-element tuple. |
| mouse_visible(on) | Sets the mouse pointer to visible or invisible. on can be True or False. |
| is_pressed(key) | Returns a value that can be treated as True or False based on whether the key key is being pressed. You can use one of the many key constants for key that games provides. |
| objects_overlapping(box) | Returns a list of all the objects whose bounding boxes overlap the bounding box box. A bounding box is a rectangle, which completely encloses an image. A bounding box is represented as a four-element tuple. The first and second elements are the x- and y-coordinates of the box's upper-left corner. The third and fourth elements are the box's width and height. |
| mainlooop([fps]) | Starts the loop that draws all of the graphics objects associated with the Screen object. fps is the number of frames per second to update the Screen object. The default value is 50. |
| tick() | Executes every mainloop() cycle. It does nothing by default. You might override this method if you subclass Screen. |
| all_objects() | Returns a list of all objects associated with the Screen object. |
| clear() | Destroys all objects associated with the Screen object. |
| quit() | Stops mainloop() and destroys the Screen object and all objects associated with it. |
The Games_Object Class
Games_Object is an abstract class for graphics objects, so you shouldn't directly create instances of it. Instead, you should create instances of its subclasses: Text, Message, Sprite, and Animation. When you instantiate an object of one of these subclasses, the subclass passes values (directly or indirectly) to the Games_Object constructor, which uses the values to set attributes for the new object. Table A.3 describes how these values are used.
| Parameter | Description |
|---|---|
| screen | Determines the Screen object for the Games_Object object. |
| x | Determines the object's x-coordinate. |
| y | Determines the object's y-coordinate. |
| image | Determines the object's image. |
| a | Determines the object's angle of rotation. The default value is 0. |
| dx | Determines the object's velocity in the x direction. The default value is 0. |
| dy | Determines the object's velocity in the y direction. The default value is 0. |
| da | Determines the object's angular velocity. The default value is 0. |
| interval | Determines the object's tick() interval. The default value is 1. |
Many of the attributes set by Games_Object's constructor are not meant to be directly accessed. As a result, most Games_Object methods facilitate getting and setting these values. Table A.4 lists many of these important methods.
| Method | Description |
|---|---|
| get_pos() | Returns the object's x- and y-coordinates as a two-element tuple. |
| get_xpos() | Returns the object's x-coordinate. |
| get_ypos() | Returns the object's y-coordinate. |
| get_left() | Returns the x-coordinate of the object's left edge. |
| get_right() | Returns the x-coordinate of the object's right edge. |
| get_top() | Returns the y-coordinate of the object's top edge. |
| get_bottom() | Returns the y-coordinate of the object's bottom edge. |
| get_bbox() | Returns the object's bounding box as a four-element tuple. |
| get_velocity() | Returns the object's x velocity and y velocity as a two-element tuple. |
| get_angular_speed() | Returns the object's angular velocity. |
| get_angle() | Returns the object's current angle in degrees. |
| set_left(x) | Moves the object horizontally so that its left edge is at the new coordinate x. |
| set_right(x) | Moves the object horizontally so that its right edge is at the new coordinate x. |
| set_top(y) | Moves the object vertically so that its top edge is at the new coordinate y. |
| set_bottom(y) | Moves the object vertically so that its bottom edge is at the new coordinate y. |
| set_velocity(dx,dy) | Sets the object's x velocity to dx and its y velocity to dy. |
| set_angular_speed(da) | Sets the object's angular velocity to da. |
| move_to(x,y) | Moves the object to the new coordinates (x,y). |
| move_by(dx,dy) | Moves the object by dx pixels in the x direction and dy pixels in the y direction. |
| rotate_by(angle) | Rotates the object by angle degrees. |
| rotate_to(angle) | Rotates the object to the angle angle. |
| overlaps(other) | Returns a value that can be treated as True if the object overlaps other. Otherwise, it returns a value that can be treated as False. |
| overlapping_objects() | Returns a list of objects that overlap the object. |
| tick() | Executes every interval mainloop() cycles. It does nothing by default. You might override this method in subclasses of Games_Object. |
| destroy() | Removes all of the associated Screen object's references to an object. |
The Text Class
The Text class is a subclass of Games_Object. A Text object represents text on a Screen object. You create a new Text object with
Text(screen, x, y, text, size, color [, a] [, dx] [, dy][, da] [, interval])
Text defines additional attributes, which are listed in Table A5.
| Attribute | Description |
|---|---|
| text | Text to be placed on the screen. |
| size | Font size of the text. |
| color | Color of the text. |
The Text class uses text, size, and color to create an image object for the text that is displayed.
Text defines additional methods, which are described in Table A.6
| Method | Description |
|---|---|
|
init_text(screen, x, y, text, size, color [, a] [, dx] [, dy][, da] [, interval]) | Initializes a Text object. Automatically invoked in Text's constructor. You would only directly invoke this method if you subclassed Text, to initialize a new object. |
| set_text(text) | Sets the object's text attribute to the string text. |
| get_text() | Returns the object's text attribute. |
The Message Class
The Message class is a subclass of Text. A Message object represents a message on the graphics screen that disappears after a set period of time. A Message object can also specify an event to occur after it disappears. You create a new Message object with
Message(screen, x, y, text, size, color [, a] [, dx] [, dy][, da] [, lifetime], [, afterdeath])
Message defines additional attributes, which I list in Table A.7.
| Attribute | Description |
|---|---|
| lifetime | Amount of time, in mainloop() cycles, the object exists before it disappears. A value of 0 means the object will never disappear. The default value is 0. |
| afterdeath | Callable code to execute after the object disappears, such as a function or method. The default value is None. |
Message defines an important additional method, init_message(screen, x, y, text, size, color [, a] [, dx] [, dy][, da] [, lifetime], [, afterdeath]), which initializes a Message object. This method is automatically invoked in Message's constructor. You would only directly invoke this method if you subclassed Message, to initialize a new object.
The Sprite Class
The Sprite class is a subclass of Games_Object, useful for creating an object with an image from a graphics file. You create a new Sprite object with
Sprite(screen, x, y, image [, a] [, dx] [, dy][, da] [, interval])
Sprite doesn't define additional attributes, but it does define an important additional method, init_sprite(screen, x, y, image [, a] [, dx] [, dy][, da] [, interval]), which initializes a Sprite object. This method is automatically invoked in Sprite's constructor. You directly invoke this method when you subclass Sprite, to initialize a new object.
The Animation Class
The Animation class is a subclass of Sprite. Animation objects are animations—a series of images shown in succession. You create a new Animation object with
Animation(screen, x, y, images, [, a] [, dx] [, dy] [, da] [, n_repeats] [, repeat_interval])
Animation defines additional attributes, which are described in Table A.8
| Attribute | Description |
|---|---|
| images | List of either image objects or file names as strings from which to create image objects. |
| n_repeats | Number of times the complete animation cycle should repeat. A value of 0 means repeat forever. The default value is 0. |
| repeat_interval | Object's tick() interval. The default value is 1. |
Animation defines an important additional method, init_animation(screen, x, y, images, [, a] [, dx] [, dy] [, da] [, n_repeats] [, repeat_interval]), which initializes an Animation object. This method is automatically invoked in Animation's constructor. You directly invoke this method when you subclass Animation, to initialize a new object.
EAN: 2147483647
Pages: 194