Properties and Styles
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, which should be a string giving the name of the style which unspecified properties are inherited from.
$ ui.text("Hello, World", xalign=0.5, yalign=0.5, size=42, style='default') $ ui.saybehavior() $ ui.interact()
Styles. 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 filed 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
A new style can be created by calling 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.
Style Methods. Style objects have methods that may be useful when customizing styles.
Method: Style.take( | other) |
This expects other to be a style object. It takes style customizations from other, and applies them to this style.
Prefixed Properties. 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 widget may be selected or unselected, and it may be focused, unfocused, or unfocusable. 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 |
||||
focused |
unfocused |
unfocusable |
focused |
unfocused |
unfocusable |
|
(no prefix) |
* |
* |
* |
* |
* |
* |
hover_ |
* |
* |
||||
idle_ |
* |
* |
||||
insensitive_ |
* |
* |
||||
selected_ |
* |
* |
* |
|||
selected_hover_ |
* |
|||||
selected_idle_ |
* |
|||||
selected_insensitive_ |
* |
Resolving Conflicts. 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.
Text Properties
The following properties can be applied to displayables that draw text.
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.
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.
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.
italic --- If True, then this text will be rendered in italics.
underline --- If true, then this text will be rendered with an underline.
antialias --- If True, the text will be antialiased. Otherwise, it will be left jagged.
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"
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.
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.
text_y_fudge --- This fudges the y position of a block of text by adding whitespace above the first line.
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.)
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.)
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.
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.
Window Properties
Window properties control the look of windows. Note that buttons and frames are also windows, and so can also take these properties.
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.)
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.
Position Properties
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.
Sound Properties
These properties may be supplied to buttons and button-like displayables, to cause sounds to play when buttons are hovered or activated.
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.
Bar Properties
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.
left_gutter --- The size of the left gutter of a horizontal bar, in pixels.
right_gutter --- The size of the right gutter of a horizontal bar, in pixels.
top_gutter --- The size of the top gutter of a vertical bar, in pixels.
bottom_gutter --- The size of the bottom gutter of a vertical bar, in pixels.
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.
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.
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.
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.
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 offset between the division in the bar and the side of the thumb, in pixels. This will often be negative, so that the thumb overlaps the division to some extent.
Box Properties
Horizontal and Vertical boxes have a number of properties that can be used to control how they are laid out. By changing these properties, one can control the spacing between elements in a box, and even turn a box from horizontal to vertical (or vice versa).
box_spacing --- The spacing between elements in the box.
box_first_spacing --- If not None, the spacing between the first two elements in the box.
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 None, the layout of the box is controlled by the function that created the box, with ui.hbox and ui.vbox making horizontal and vertical boxes, respectively.
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.
Focus Properties
These are only used on buttons.
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). New in 5.6.5.
List of Styles
Style: animation (inherits from default) |
This is the default style of animations. Don't change this, change image_placement instead.
Style: button (inherits from default) |
(window) The default style used for buttons in the main and game menus.
Style: centered_text (inherits from default) |
(text) The style used for text spoken by the "centered" character.
Style: centered_window (inherits from default) |
(window) The style that is used for a "window" containing centered text.
Style: default (inherits from None) |
The default style that all styles inherit from. (This style does not inherit from another style.)
Style: error_body (inherits from default) |
(text) The style of the body of error messages generated by Ren'Py.
Style: error_root (inherits from default) |
(window) The style of the window containing error messages generated by Ren'Py.
Style: error_title (inherits from default) |
(text) The style of the text containing the title of error messages generated by Ren'Py.
Style: file_picker_empty_slot (inherits from file_picker_text) |
(text) The style that is used for the empty slot indicator in the file picker.
Style: file_picker_entry (inherits from menu_button) |
(window) The style that is used for each of the slots in the file picker.
Style: file_picker_entry_box (inherits from thin_hbox) |
(box) The style that is used for the hbox inside of a file picker entry.
Style: file_picker_extra_info (inherits from file_picker_text) |
(text) The style that is applied to extra info in the file picker. The extra info is the save time, and the save_name if one exists.
Style: file_picker_frame (inherits from default) |
(window) A window containing the file picker that is used to choose slots for loading and saving.
Style: file_picker_frame_vbox (inherits from thin_vbox) |
(box) The vbox containing both the nav and the grid in the file picker.
Style: file_picker_grid (inherits from default) |
The style of the grid containing the file picker entries.
Style: file_picker_nav_button (inherits from menu_button) |
(window) The style that is used for file picker navigation buttons. (The buttons that let the user select the file picker page.)
Style: file_picker_nav_button_text (inherits from menu_button_text) |
(text) The style that is used for the label of file picker navigation buttons.
Style: file_picker_navbox (inherits from thick_hbox) |
(box) The box containing the naviation (next/previous) buttons in the file picker.
Style: file_picker_new (inherits from file_picker_text) |
(text) The style that is applied to the number of the new slot in the file picker.
Style: file_picker_old (inherits from file_picker_text) |
(text) The style that is applied to the number of the old slots in the file picker.
Style: file_picker_text (inherits from default) |
(text) A base style for all text that is displayed in the file picker.
Style: gm_nav_button (inherits from menu_button) |
(window) The style of a game menu navigation button.
Style: gm_nav_button_text (inherits from menu_button_text) |
(text, hover) The style of the text of a game menu navigation button.
Style: gm_nav_frame (inherits from default) |
(window) The style used by a window containing buttons that allow the user to navigate through the different screens of the game menu.
Style: gm_nav_vbox (inherits from thin_vbox) |
(box) The style that is used by the box inside the gm_nav_frame.
Style: gm_root (inherits from default) |
(window) The style used for the root window of the game menu. This is primarily used to change the background of the game menu.
Style: hyperlink (inherits from default) |
(window) The style of a hyperlink button, created with the {a} text tag.
Style: hyperlink_text (inherits from default) |
(window) The stylee of hyperlink button text, created with the {a} text tag.
Style: image (inherits from default) |
This is the style of images themselves. Don't change this, change image_placement instead.
Style: image_button_image (inherits from default) |
The default style used for images inside image buttons.
Style: image_placement (inherits from default) |
This style is used to control the default placement of images on the screen.
Style: imagemap_button (inherits from default) |
(window) The style that is used for buttons inside imagemaps.
Style: js_frame (inherits from prefs_frame) |
(window) The window containing the joystick mapping message.
Style: js_frame_vbox (inherits from thick_vbox) |
(window) The vbox containing the joistick mapping message.
Style: js_function_label (inherits from prefs_label) |
(text, position) The style of the joystick mapping function name.
Style: js_prompt_label (inherits from prefs_label) |
(text) The style of the joystick mapping prompt message.
Style: menu (inherits from default) |
(position) The style that is used for the vbox containing a menu.
Style: menu_button (inherits from button) |
(window) The base style for buttons that are part of the main or game menus.
Style: menu_button_text (inherits from button_text) |
(text) The base style for the label of buttons that are part of the main or game menus.
Style: menu_caption (inherits from default) |
(text) The style that is used to render a menu caption. (This isn't used in button_menu mode.)
Style: menu_choice (inherits from default) |
(text) The style that is used to render the text of a menu choice.
Style: menu_choice_button (inherits from default) |
(window) The style that is used to render the button containing a menu choice.
Style: menu_choice_chosen (inherits from menu_choice) |
(text) The style that is used to render the text of a menu choice that has been chosen by the user sometime in the past.
Style: menu_choice_chosen_button (inherits from menu_choice_button) |
(window) The style that is used to render the button containing a menu choice that has been chosen by the user sometime in the past.
Style: menu_window (inherits from window) |
(window) The default style for windows containing a choice menu.
Style: mm_button (inherits from menu_button) |
(window) The style that is used for buttons that are part of the main menu.
Style: mm_button_text (inherits from menu_button_text) |
(text) The style that is used for the labels of buttons that are part of the main menu.
Style: mm_menu_frame (inherits from default) |
(window) A window that contains the choices in the main menu. Change this to change the placement of these choices on the main menu screen.
Style: mm_menu_frame_vbox (inherits from thin_vbox) |
(box) The vbox containing the main menu choices.
Style: mm_root (inherits from default) |
(window) The style used for the root window of the main menu. This is primarily used to set a background for the main menu.
Style: prefs_button_text (inherits from menu_button_text) |
(text, hover) The style of the text of a preference button.
Style: prefs_hbox (inherits from default) |
If config.hbox_pref_choices is True, the style of the hbox containing the choices.
Style: prefs_joystick (inherits from prefs_center) |
The position of the column of joystick preferences.
Style: prefs_js_button (inherits from prefs_button) |
(window, hover) The style of buttons giving a joystick mapping.
Style: prefs_js_button_text (inherits from prefs_button_text) |
(text) The style of the text in buttons giving a joystick mapping.
Style: prefs_js_frame (inherits from prefs_pref_frame) |
(window) The window containing a joystick mapping preference.
Style: prefs_js_vbox (inherits from prefs_pref_vbox) |
(box) A vbox containing a joystick mapping preference.
Style: prefs_jump (inherits from prefs_pref_frame) |
(window) The style of a window containing a jump preference.
Style: prefs_jump_button (inherits from prefs_button) |
(window) The style of a jump preference button.
Style: prefs_jump_button_text (inherits from prefs_button_text) |
(text) The style of jump preference button text.
Style: prefs_label (inherits from default) |
(text) The style that is applied to the label of a block of preferences.
Style: prefs_pref_vbox (inherits from thin_vbox) |
(box) The style of the vbox containing a preference.
Style: prefs_spinner (inherits from default) |
The position of the prefs spinner. (Note that preference spinners are not used in modern versions of Ren'Py.)
Style: prefs_spinner_button (inherits from prefs_button) |
(window, hover) The style of the + or - buttons in a preference spinner.
Style: prefs_spinner_button_text (inherits from prefs_button_text) |
(text, hover) The style of the text of the + and - buttons in a preference spinner.
Style: prefs_spinner_label (inherits from prefs_label) |
(text) This is the style that displays the value of a preference spinner.
Style: prefs_volume_slider (inherits from prefs_slider) |
(bar) The style that is applied to volume sliders.
Style: say_dialogue (inherits from default) |
(text) The style that is used by default for the text of dialogue.
Style: say_label (inherits from default) |
(text) The style that is used by default for the label of dialogue. The label is used to indicate who is saying something.
Style: say_thought (inherits from default) |
(text) The label that is used by default for the text of thoughts or narration, when no speaker is given.
Style: say_two_window_vbox (inherits from vbox) |
(window) The style used for the containing vbox in dialogue for a character with two_window set.
Style: say_vbox (inherits from vbox) |
(box) The vbox containing the label (if present) and the body of dialogue and thoughts.
Style: say_who_window (inherits from window) |
(window) The style used for the window containing the label, of a character with show_two_window set.
Style: say_window (inherits from window) |
(window) The default style for windows containing dialogue and thoughts.
Style: soundtest_button_text (inherits from prefs_button_text) |
(text) The style of the text of a sound test button.
Style: window (inherits from default) |
(window) The base style for the windows that contain dialogue, thoughts, and menus.
Style: yesno_frame (inherits from default) |
(window) The style of a window containing a yes/no prompt.
Style: yesno_frame_vbox (inherits from thick_vbox) |
(box) The style of a box containing the widgets in a yes/no prompt.