documentation index ◦ reference manual ◦ function index
Ren'Py contains a style system, which is used to determine the look of displayables. This system allows the look of Ren'Py games to be customized to a great extent.
Any function that takes a **properties parameter can be given the properties described below, including prefixed properties, but not all properties are understood by all functions. These functions may also be given a style parameter. A style may be specified by supplying the style object directly, or by supplying a string giving the style name.
$ ui.text("Hello, World", xalign=0.5, yalign=0.5, size=42, style='default')
$ ui.text('How are you doing?', style=style.centered_text)
$ ui.saybehavior()
$ ui.interact()
Each Displayable has a default style that is used when no style is explicitly given. Displayables used by Ren'Py are often given unique styles, which allow their look to be customized using the style system.
A style can be accessed as a field on the style object. Prefixed properties are fields on styles, which allow values to be assigned to them. Styles should only be created and changed inside init blocks.
init: $ style.button_text.size = 22 $ style.button_text.hover_size = 28
New styles can be created by using the Style function. These styles should be assigned to one or more fields on the style object at the time of creation.
| Function: | Style | (parent): |
Constructs a new style, with the given style as its parent. It's expected that the result of this call will be assigned to a field of the style object.
For compatibility purposes, styles may also be created using the style.create function.
| Function: | style.create | (name, parent): |
Creates a new style.
name - The name of the new style, as a string.
parent - The parent of the new style, as a string. This is either 'default' or something more specific.
| Function: | style.rebuild | (): |
This causes all styles to be rebuilt, making it possible to change styles outside of init code. There are several caveats:
Style Methods. Style objects have methods that may be useful when customizing styles.
| Method: | Style.clear | (): |
This removes all property customizations from the style it is called on.
| Method: | Style.take | (other): |
This expects other to be a style object. It takes style customizations from other, and applies them to this style.
| Method: | Style.set_parent | (parent): |
Changes the parent of this style to be parent.
Indexed Styles. Indexed styles are accessed by indexing a style with a value. If an indexed style does not exist, indexing creates it. Indexed styles are lightweight, allowing there to be a large number of them. The parent of an indexed style is the style it was indexed off of.
init python: # Creates the new indexed style button['Foo'] style.button['Foo'].background = "#f00" style.button['Foo'].xalign = 1.0 label example: python: # Accesses style button['Foo'] ui.textbutton('Foo', style=style.button['Foo'], clicked=ui.returns('Foo')) # Accesses style button['Bar'], creating it if necessary. ui.textbutton('Bar', style=style.button['Bar'], clicked=ui.returns('Bar')) ui.interact()
The style system lets us specify new values for properties of a displayable depending on the situation that displayable is in. There are two components of the situation. The displayable may be selected or unselected, and it may be activated, focused, unfocused, or unfocusable. A displayable is activated when the button containing it is clicked, and returns to a previous state if the clicked function returns None. Prefixed properties let one set the value of properties for some subset of these situations.
In the following table, we give a list of prefixes and situations. We indicate which situations a prefix applies in with a *.
| prefix | unselected | selected | ||||||
| activated | focused | unfocused | unfocusable | activated | focused | unfocused | unfocusable | |
| (no prefix) | * | * | * | * | * | * | * | * |
| activate_ | * | * | ||||||
| hover_ | * | * | * | * | ||||
| idle_ | * | * | ||||||
| insensitive_ | * | * | ||||||
| selected_ | * | * | * | * | ||||
| selected_activate_ | * | |||||||
| selected_hover_ | * | * | ||||||
| selected_idle_ | * | |||||||
| selected_insensitive_ | * | |||||||
There are two kinds of conflicts that can occur.
If we have multiple prefixes that would assign to the same property in the same situation at the same time, then we take the more specific one, where a more specific is defined as being lower in the above chart. This is the case when more then one prefix is given for a property in the call to a function that takes properties as arguments.
When assignment occurs at distinct points in time, then the value of the property for a given situation is determined the last assignment performed. This is the case when we have assignment to style properties.
To avoid conflicts, assign values to prefixed properties in order from most to least specific.
Styles can be indexed with a string or number. This allows one to easily have styles that are specific to one button, without having to define all styles in advance. Indexed styles do not show up in the style hierarchy, but do show up when using the style inspector.
When styles inherit properties, inheritance is first through the indexed form of a style, then the unindexed form of that style, then the indexed form of that style's parent, then the unindexed form of the parent, and so on. Specifically, if style.mm_button inherits from style.button inherits from style.default, then the components of style.mm_button["Start Game"] are taken from:
with the property taken from the lowest numbered style with that property defined.
The styles that are available to be customized vary depending on the layouts and themes being used. To get a complete tree of styles, including a brief explantion of what each is used for, hit shift+D inside your game to get to the developer menu, then pick "Style Hierarchy". (Note that config.developer must be set to True to enable access to the developer console.)
This is a list of properties, loosely grouped by the use of the property.
Contents |
The following properties are used by Text displayables.
antialias --- If True, the text will be antialiased. Otherwise, it will be left jagged.
black_color --- This should be an RGBA triple. When an SFont is used, this is the color the black will be mapped to. This property is ignored when a truetype font is used. The alpha channel in this color is ignored.
bold --- If True, then this text will be rendered in bold.
color --- The color in which the text will be displayed on the screen, as an RGBA tuple. When an SFont is used, this is the color that white in that Sfont will be displayed as.
drop_shadow --- This is used to control the generation of a drop shadow on text. It's either a 2-element tuple, a list of tuples, or None. If it's a tuple, then the 2 elements control the drop shadow offsets in X and Y, respectively. If it's a list, then it's expected to be a list of 2-element tuples, each of which is the drop shadow. Using a list like [ (-1, -1), (1, -1), (-1, 1), (1, 1) ] creates outlined text instead of a drop-shadow. If None, then no drop shadow is created for the text.
drop_shadow_color --- The color of the drop-shadow. Example: "#000"
first_indent --- This is used to give, in pixels, the indentation of the first line of text in the text widget. It can be used to indent the first line of a paragraph of text. (Not that that's a good idea on a computer monitor, better to leave a blank line between paragraphs.)
font --- The font that will be used to render text. This is either the name of a file containing a truetype font, or the name of a font. In the former case, the font is loaded from the file. In the latter case, the filename is used to search SFonts registered with register_sfont, and truetype fonts found on the system font directory.
size --- The size of the font that is used to display the text on the screen. Please note that the meaning of this can vary from font to font, and bears only a weak relationship with the number of pixels high that the font will be on the screen.
italic --- If True, then this text will be rendered in italics.
justify --- If True, additional whitespace is inserted between words so that the left and right margins of each line are even. This is not performed on the last line of a paragraph.
language --- The language (really, language family) that's used to display the text. Right now, this is one of two choices: "western" for western-style text which is broken at spaces, "eastasian" for Chinese/Japanese text, which can be broken between characters.
layout --- Controls how line-breaking occurs. This defaults to "greedy", which attempts to put as much as possible on each line. It may also be "subtitle", which tries to make the lines even in length.
line_spacing --- This is used to increase or decrease the spacing between lines of text by a constant number of pixels. A positive value increases, while a negative value decreases the spacing.
minwidth --- The minimum width in pixels of this text. If the rendered text is smaller than this, it is right-padded with whitespace until it is at least this many pixels long.
outlines --- A list of 2 or 4-component tuples, giving the size, color, and optionally the x and y offsets of outlines around the text. An outline is a block of text that has been expanded in size by a given number of pixels. The x and y offsets can be omitted. The first tuple in the list is furthest from the screen, while the last is closest. (new in 6.8.0)
rest_indent --- This is used to give, in pixels, the indentation of the second and later lines of a text widget. It can be used to give a hanging indent to quoted dialogue.
slow_cps --- If a number, causes text to be shown at a rate of that many characters per second. If True, takes that number from the "Text Speed" preference.
slow_cps_multiplier --- A multiplier that will be applied to the number of characters shown per second. For example, 2.0 causes characters to be shown twice as fast.
slow_abortable --- If True, slow text can be aborted by clicking the mouse.
text_align --- This is used to control the horizontal alignment of the lines of text in the area allocated to the Text widget containing that text. It only really has any effect if the text is more than one line long. It's a number between 0 and 1, which gives the fraction of empty space that should be to the left of each line of text. (To center text, it should be 0.5.)
text_y_fudge --- This fudges the y position of a block of text by adding whitespace above the first line.
underline --- If true, then this text will be rendered with an underline.
The properties control the look of Windows and Buttons.
background --- A Displayable that is used as the background for the window. This needs to be a Displayable that always draws exactly the size requested of it, which usually means either a Solid or a Frame. This can also be None, which means that there is no background on this window. (All the other window properties that refer to a background still work. Just think of them as if their background was transparent.)
foreground --- This is drawn in the same way as the background, except it is drawn above the contents of the window.
left_margin --- The amount of transparent space left to the left of this window. If a floating point number, it is scaled to the available width.
right_margin --- The amount of transparent space left to the right of this window. If a floating point number, it is scaled to the available width.
top_margin --- The amount of transparent space left to the top of this window. If a floating point number, it is scaled to the available height.
bottom_margin --- The amount of transparent space left to the bottom of this window. If a floating point number, it is scaled to the available height.
xmargin --- This is a convenient (and backwards compatible) way of setting left_margin and right_margin to the same value.
ymargin --- This is a convenient (and backwards compatible) way of setting top_margin and bottom_margin to the same value.
left_padding --- The amount of space left between the edge of the border and the left side of the contents of the window. If a float, it is scaled to the width of the window.
right_padding --- The amount of space left between the edge of the border and the right side of the contents of the window. If a float, it is scaled to the width of the window.
top_padding --- The amount of space left between the edge of the border and the top side of the contents of the window. If a float, it is scaled to the height of the window.
bottom_padding --- The amount of space left between the edge of the border and the bottom side of the contents of the window. If a float, it is scaled to the height of the window.
xpadding --- A convenient (and backwards compatible) way of setting left_padding and right_padding to the same value.
ypadding --- A convenient (and backwards compatible) way of setting top_padding and bottom_padding to the same value.
xfill --- If True, the window will expand to fill all available space in the x direction. If False, it will shrink to fit its contents.
yfill --- If True, the window will expand to fill all available space in the y direction. If False, it will shrink to fit its contents.
xminimum --- The minimum size of this window in the x direction, including margins and padding. If the window would be smaller than this, it is grown to be at least this size. If a floating point number, it is scaled to the available width.
yminimum --- The minimum size of this window in the y direction, including margins and padding. If the window would be smaller than this, it is grown to be at least this size. If a floating point number, it is scaled to the available height.
size_group --- If not None, this should be set to a string. All windows or buttons with a given string as their size_group are rendered at the same width. (new in 6.6.0)
clipping - If true and the child is bigger than the maximum size set for this window, it will be clipped to the size of the window.
These are only applicable to Buttons.
hover_sound --- The sound to play when this widget becomes hovered.
activate_sound --- The sound to play when the widget is activated, by clicking on or otherwise selecting it.
focus_mask --- This is used as a mask that determines if a button should be focused or not. If False, a default rectangle is used as the mask. Otherwise, if the special value True, the rendered displayable is used as the mask, or else the value is interpreted as a displayable, rendered to the size of the button, and used. In either case, the alpha value of the mask is what's used, with any non-zero amount of alpha indicating that a pixel is part of the mask. New in 5.6.5.
focus_rect --- If not None, this gives as a (x, y, width, height) tuple the focus rectangle of a button, as an offset from the upper-left corner of the button. For proper keyboard navigation, the focus rectangles of images are not allowed to overlap. By setting this and focus_mask on an imagebutton, one can have imagebuttons that overlap, but yet still support keyboard focus. This should almost certainly never be set on an individual image, but rather for each individual button (and it's rare to do even that).
time_policy --- A function that is responsible for modifying the displayable timebase of displayables used by buttons. This function expects to be given a time, a state object, and a style object, and is expected to return a new time and a new state. (The state object defaults to None the first time time_policy is called.) This function may want to determine the style prefix by inspecting its .prefix field. The default time_policy does not change the time.
child --- If not None, this displayable is displayed in the place of the child of this button.
mouse --- If not None, a string giving the name of the mouse cursor that is used when this button is focused. The name must be listed in config.mouse. This also works with other focusable displayables.
The ui.bar has a few properties that are specific to it, that control the look of the bars. The bar has gutters on the left and the right. The remaining space is the space in which the bar can change, with the division of the bar being the fraction of this space representing the bar's value as a fraction of the range.
When the bar is drawn, the thumb's shadow is drawn first, followed by the left and right sides of the bar, followed by the thumb.
bar_vertical --- If true, the bar is drawn vertically, if false, horizontally.
bar_invert --- If true, the value of the bar is represented on the right/top side of the bar, rather then the left/bottom side of the bar.
bar_resizing --- If true, we resize the sub-bars, rather than rendering them full size and then cropping.
left_gutter --- The size of the left gutter of a horizontal bar, in pixels. (Named fore_gutter internally.)
right_gutter --- The size of the right gutter of a horizontal bar, in pixels. (Named aft_gutter internally.)
top_gutter --- The size of the top gutter of a vertical bar, in pixels. (Named fore_gutter internally.)
bottom_gutter --- The size of the bottom gutter of a vertical bar, in pixels. (Named aft_gutter internally)
left_bar --- A Displayable that is used to draw the left side of a horizontal bar. This displayable is first rendered at the full size of the bar, and then cropped so only the left side is visible. (Named fore_bar internally.)
right_bar --- A Displayable that is used to draw the right side of a horizontal bar. This displayable is first rendered at the full size of the bar, and then cropped so only the right side is visible. (Named aft_bar internally.)
top_bar --- A Displayable that is used to draw the top of a vertical bar. This displayable is first rendered at the full size of the bar, and then cropped so only the top is visible. (Named fore_bar internally.)
bottom_bar --- A Displayable that is used to draw the bottom of a vertical bar. This displayable is first rendered at the full size of the bar, and then cropped so only the bottom is visible. (Named aft_bar internally.)
thumb --- If not None, this is a thumb image that is drawn over the break between the sides of the bar.
thumb_shadow --- If not None, a shadow of the thumb that is drawn underneath the break between the sides of the bar.
thumb_offset --- The amount by which the thumb overlaps the bars, in pixels. To have the left and right bars continue unbroken, set this to half the width of the thumb. For compatibility's sake, we take the absolute value of this property.
unscrollable --- Controls what happens if the bar is unscrollable (if the range is set to 0, as is the case with a ui.viewport containing a displayable smaller than itself. There are three possible values:
(new in 6.8.0)
The HBox, VBox, and Fixed displayables are instances of a common MultiBox displayable. These properties control how these displayables are laid out.
box_layout --- If "horizontal", the box is laid out in a horizontal manner. If "vertical", the box is laid out in a vertical fashion. If "fixed", the layout of the box is controlled by the position properties of the children of the box, and the rest of these properties are ignored. If None, the layout of the box is controlled by the function that created the box.
spacing --- The spacing between elements in the box, in pixels. This is also used for ui.grid and ui.side. This was formerly known as box_spacing, an alias which still works.
first_spacing --- If not None, the spacing between the first two elements in the box, in pixels. This is only used for boxes. This was formerly known as box_first_spacing, an alias that still works.
xfill --- If True, the box will expand to fill all available space in the x direction. If False, it will shrink to fit its contents.
yfill --- If True, the box will expand to fill all available space in the y direction. If False, it will shrink to fit its contents.
Position properties are applied to displayables that are smaller than the space allocated to them. They apply to all displayables, and control the placement of the widget in the space. For example, position properties can be used to control the placement of a dialogue window on the screen.
Position properties work best when a small displayables is placed into empty space. This is the case for say windows, and the menus that are displayed as part of the main menu. Position properties work on other displayables, but the vagaries of how space is allocated can make some of the results counterintuitive.
Positioning works by placing the displayable such that an anchor (specified relative to the displayable) is at the same location as the position (specified relative to the available space).
xanchor --- The x-axis location of the anchor, relative to the upper-left corner of the displayable. This may be an absolute number of pixels, or a floating point number which is interpreted as a fraction of the size of the displayable.
xpos --- The x-axis location of the position, relative to the upper-left corner of the available space. This may be an absolute number of pixels, or a floating point number which is interpreted as a fraction of the size of the available space.
xalign --- A shortcut for specifying xanchor and xpos at the same time. This should almost always be assigned a floating point number. As an example, xanchor=0.5 will center a displayable in the available space.
yanchor --- The y-axis location of the anchor, relative to the upper-left corner of the displayable. This may be an absolute number of pixels, or a floating point number which is interpreted as a fraction of the size of the displayable.
ypos --- The y-axis location of the position, relative to the upper-left corner of the available space. This may be an absolute number of pixels, or a floating point number which is interpreted as a fraction of the size of the available space.
yalign --- A shortcut for specifying yanchor and ypos at the same time. This should almost always be assigned a floating point number.
xoffset --- An offset, in pixels, that is added to the position computed using xpos and xanchor.
yoffset --- An offset, in pixels, that is added to the position computed using ypos and yanchor.
Assuming xpos, ypos, xanchor, and yanchor have all been converted to pixels if necessary, the position of the upper-left corner of a displayable relative to the upper-left corner of the area it is laid out in can be expressed as: