This page is out of date

You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.

Some places to look are:

• The Ren'Py Home Page
• Download the Latest Version
• Ren'Py Documentation
• Quickstart Tutorial
• Ren'Py Cookbook

Please do not create new links to this page.

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. 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()

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 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.

For compatibility purposes, styles may also be created using the style.create function.

Style Methods. Style objects have methods that may be useful when customizing styles.

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()

Property Prefixes

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 *.

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.

Indexed Styles and Inheritance

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:

1. style.mm_button["Start Game"]
2. style.mm_button
3. style.button["Start Game"]
4. style.button
5. style.default["Start Game"]
6. style.default

with the property taken from the lowest numbered style with that property defined.

List of Styles

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 must be set to True to enable access to the developer console.)