documentation index ◦ reference manual ◦ function index
It's possible for a user to define displayables that extend Ren'Py's behavior. This section will explain the steps that are involved in defining your own displayables, and how to use them with Ren'Py.
A displayable is an object that inherits from renpy.Displayable, a class that has several methods that can be overridden to control the behavior of the displayable. Probably the most important of these is render, a method that must be overridden to return a renpy.Render object, which contains the result of drawing the displayable. The event method can be overridden to respont to events, and to terminate the interaction when necessary. Other methods allow a displayable to respond to a variety of events.
Displayables must be capable of being serialized. This means that they must not contain references to objects that are incapable of being serialized. Of particular note is that the renpy.Render object is incapable of being serialized.
Displayables have a number of methods and fields, not all of which are documented here. We strongly recommend you use a unique prefix for the names of fields and methods you add, to minimize the chance of conflicts.
Contents |
This is the base class for user-defined displayables. It has the following fields and methods.
Since you will be implementing many of these methods, rather than calling them, we include the normally hidden self parameter in the definition.
| Field: | focusable | = False |
This field should be True if it's possible for the displayable to gain focus, and false otherwise.
| Field: | style | = ... |
The style of this displayable. This is automatically created by the default constructor.
| Field: | delay | = undefined |
If this displayable is used as a transition, then delay should be set to the number of seconds that the transition will take.
| Method: | renpy.Displayable.__init__ | (self, default=False, focus=None, style='default', **properties): |
The __init__ method may be overridden with your own parameter list, but the default method must be called to properly initialize a Displayable. The parameters the default methods take are:
focus - if given, a string giving the name of the focus group in the object. The focus group is used to determine which displayable should be focused after an interaction. For example, if the third displayable in focus group "foo" has focus at the end of an interaction, the third displayable in "foo" will have focus at the start of the next interaction, even if the two displayables are not the same.
default - determines if this object can be focused by default. This is only used if no object with the same focus name is found in an interaction.
style - The name of the default style, used to construct a style object that is placed in the style field.
properties - Additional keyword arguments are treated as style properties when constructing the style.
| Method: | renpy.Displayable.focus | (self, default=False): |
Called to indicate that this displayable has been given the focus. default is true if the focus has been given to this displayable at the start of an interaction.
The default implementation sets the style prefix of this displayable and its children to 'hover_'.
If this returns a non-None value, the current interaction is terminated and the value is returned.
| Method: | renpy.Displayable.unfocus | (self): |
Called to indicate this displayable has lost focus.
The default implementation resets the style prefix of this displayable and its children to 'idle_'.
This should return None.
| Method: | renpy.Displayable.is_focused | (self): |
This method determines if the current displayable has focus. It probably doesn't make sense to override it.
| Method: | renpy.Displayable.set_style_prefix | (self, prefix): |
Sets the style prefix of this displayable and its children to one of: "insensitive_", "idle_", "hover_", "activate_", "selected_insensitive_", "selected_idle_", "selected_hover_", or "selected_activate_".
| Method: | renpy.Displayable.render | (self, width, height, st, at): |
This is responsible for drawing the displayable. This is done by creating a renpy.Render object, blitting other objects to that object in appropriate places, and then returning that Render.
width, height - The area allocated to this displayable. The created displayable may be bigger or smaller than this, without consequence.
st - The displayable timebase, the number of seconds this displayable has been shown for.
at - The animation timebase, the number of seconds an image with the same tag as this displayable has been shown for.
This method should not be called directly on child displayables. (See renpy.render instead.)
| Method: | renpy.Displayable.event | (self, ev, x, y, st): |
This is called when an event occurs.
ev - The pygame event object. This can be read to get the type of event and other parameters.
x, y - The position of the mouse at the time of the event. This is relative to the upper-left corner of this displayable, and should be used in preference to similar data contained in ev.
st - The displayable timebase.
If this method returns a non-None value, then that value is returned from ui.interact. If it returns None, processing of the event is continued by the other displayables. If renpy.IgnoreEvent is raised, then no other displayables will see the event.
It may make sense to call this method on child displayables.
| Method: | renpy.Displayable.get_placement | (self): |
Returns a tuple of (xpos, ypos, xalign, yalign, xoffset, yoffset), that is used to place this displayable on the screen.
This defaults to getting the proper values out of style.
| Method: | renpy.Displayable.visit | (self): |
This should be overridden to return a list of all the child displayables fo this displayable.
| Method: | renpy.Displayable.per_interact | (self): |
This is called once per interaction, to inform the displayable that a new interaction has begun.
Often, this should call renpy.redraw(self, 0), to make sure that the displayable is redrawn for each interaction. This is especially useful if the displayable participates in rollback.
Since one will not be subclassing renpy.Render, we omit the self parameter from method descriptions.
| Function: | renpy.Render | (width, height): |
Constructs a new render object with the given width and height.
| Method: | renpy.Render.blit | (source, pos): |
Copies the contents of the source render to this one. Pos is a 2-element tuple giving the position of the upper-left-hand corner of the source render, relative to the upper-left-hand corner of this render, in pixels.
| Method: | renpy.Render.fill | (color): |
Fills the render with the given color, which should be an RGBA tuple.
| Method: | renpy.Render.get_size | (): |
Returns the width and height of this render as a pair.
| Method: | renpy.Render.kill | (): |
Deallocates the memory used by this Render. This must be called on a Render returned by renpy.render or renpy.Render.subsurface if the render is not blitted to another Render. Once this is called, the render should not be blitted to a surface or have any other method called. It is safe to call this on a Render that has been blitted somewhere, as these calls are ignored.
| Method: | renpy.Render.subsurface | (pos): |
Returns a render that is a subsurface of this render. Pos should be an (x,y,w,h) tuple, where x and y are the coordinates of the upper-left corner of the subsurface, w is the width, and h is the height of the subsurface.
| Method: | renpy.Render.add_focus | (displayable, arg, x, y, w, h, mx=None, my=None, mask=None): |
This is used to indicate that a sub-region of this Render is eligible for being focused.
displayable - The displayable that will be focused. arg - Ignored, should be None. x, y, w, h - If not None, a rectangular subregion of this Render that will be focused. If all are None, this displayable has full-screen focus. mx, my - If not None, offsets of the focus mask from the upper-left hand corner of this Render. mask - A Render that is used as a focus mask when mouse focus is needed. The mouse will only focus the displayable when it is over a non-transparent pixel in the mask.
| Method: | renpy.Render.canvas | (): |
This function returns a canvas object that has methods corresponding to the pygame.draw functions, except that the first argument (the surface) is omitted. For example, instead of calling pygame.draw.line(surface, (255, 255, 255, 255), (100, 100), (200, 200)), one would call c.line((255, 255, 255, 255), (100, 100), (200, 200)).
Code that uses a canvas may not be portable to non-pygame platforms, should we choose to support them in the future.
The renpy.Container class implements a displayable that positions its children using style properties, in a manner similar to Fixed and ui.fixed. Unlike the displayable returned by those functions, renpy.Container supports adding and removing children, and it may be subclassed to change its behavior (including the behavior of the render and event methods).
A renpy.Container implements all of the methods of a renpy.Displayable. These methods may be overridden in a subclass, and this is often done with for the render and event methods. A container has three additional fields:
| Field: | children | = [] |
A list of the children of this container.
| Field: | children | = None |
The last child added to this container and not removed, or None if there are no children in this container.
| Field: | offsets | = [] |
A list of (x, y) tuples giving the coordinates of the upper-left corners of the children of this displayable.
It also has three methods. (We give these without the self parameter, as we expect them to be called, and only rarely overridden.)
| Method: | renpy.Container.add | (d): |
Add a d to this container.
| Method: | renpy.Container.remove | (d): |
Remove the first instance of d from this container.
| Method: | renpy.Container.update | (): |
This should be called after add or remove, to indicate that the container has changed and should be redrawn.
| Function: | renpy.render | (displayable, width, height, st, at): |
Call this function to get a Render from a displayable. It takes care of calling the render method on that displayable, and then caching the results when nothing has changed.
| Function: | renpy.redraw | (displayable, time): |
Causes the supplied displayable to be redrawn after time seconds have elapsed. Time may be zero to ensure an immediate redraw.
| Function: | renpy.timeout | (time): |
Causes an event to occur in time seconds. The type of the event is undefined.
| Function: | renpy.easy_displayable | (d, none=False): |
This takes an "easy displayable", and returns a Displayable. Easy displayables may be Displayables, or may be strings. If a string, then:
If none is True and d is None, then None is returned. Otherwise, if d is None, an exception is thrown.
Once a user-defined displayable class has been defined, objects of that class can be created. Such an object can be shown with a show statement, or added to the transient layer with ui.add.
An At-function is a function that is suitable for use in an at-list, as part of a show statement. These are functions that take a displayable as an argument, and return a second displayable. (User-defined or not.)
Transitions take two keyword arguments, new_widget and old_widget, representing the new and old scenes, respectively. They return a displayable that performs the transition, which should have its delay fields set to the duration of the transition.
Although we will do our best to avoid breaking code unnecessarily, we reserve the right to change the displayable API as necessary to support the future development of Ren'Py. As a result, code using the displayable API may not be forward-compatible with future versions of Ren'Py.