Screen Actions, Values, and Functions link

Ren'Py ships with a number of actions, values, and functions intended for use with screens and the screen language.

Actions link

Actions are invoked when a button (including imagebuttons, textbuttons, and hotspots) is activated, hovered, or unhovered. Actions may determine when a button is selected or insensitive.

Along with these actions, an action may be a function that does not take any arguments. The function is called when the action is invoked. If the action returns a value, then the value is returned from an interaction.

A list of actions can usually be provided in lieu of a single action, in which case the actions in the list are run in order. A list of actions is sensitive if all of the actions are sensitive, and selected if any of them are ; that unless SensitiveIf() or SelectedIf(), respectively, is part of the list.

Control Actions link

These are actions that manage screens, interaction results, and control flow.

Data Actions link

These set or toggle data.

File Actions link

These actions handle saving, loading, and deleting of files. Many of these take the name and page arguments.

name

The name of the file to save to. This can be a string or an integer. It's combined with the page to create the filename.

page

The page that this action acts on. This is one of "auto", "quick", or a positive integer. If None, the page is determined automatically, based on a persistent page number.

These are converted to a slot name using config.file_slotname_callback, if it's set.

Sync Actions link

Audio Actions link

The concept of channels and how they work, as well as most information about audio in Ren'Py, is explained at Audio.

Focus Actions link

Other Actions link

These are other actions, not found anywhere else.

Additional actions are available in other pages of this documentation, such as Language, Replay and EndReplay, gui.SetPreference and gui.TogglePreference, StylePreference, and the voice actions.

Other actions can be created using the Action class.

Bar Values link

Bar values are used with bars, to set the bar value, and to allow the bar to adjust an underlying property. To create a new bar value, subclass the BarValue class. All classes that have the step keyword also accept the force_step keyword whose behavior is described in ui.adjustment().

Input Values link

Input values are used with text inputs, to set the default text, to accept changed text, to respond to the enter key, and to determine if the text is editable by default. To create a new input value, subclass the InputValue class.

Ren'Py-defined input values inherit from InputValue, which means that all values also include Enable(), Disable(), and Toggle() methods that return actions that enable, disable, and toggle editing, respectively. See also the DisableAllInputValues() action.

Functions and Classes link

These functions and classes are useful in association with screens.

Preferences link

While all preferences can be defined based on the Actions and Values given above, it requires some knowledge of Ren'Py to figure out the correct one to use. The preferences constructor makes this easy, by creation an action or value, as appropriate, based on the names used in the default preferences screen.

Gamepad link

These functions and actions work with the gamepad.

File Functions link

These functions return useful information about files. They use the same default page as the file actions.

Side Image Functions link

This function returns the side image to use.

Other Functions link

Tooltips link

Tooltips can now be accessed by the tooltip property available on all displayables, and the GetTooltip function. The GetTooltip function returns the value of the tooltip property when the displayable gains focus.

As a reminder, values passed to the tooltip property must support equality.

Here's an example:

screen tooltip_example():
    vbox:
        textbutton "North":
            action Return("n")
            tooltip "To meet a polar bear."

        textbutton "South":
            action Return("s")
            tooltip "All the way to the tropics."

        textbutton "East":
            action Return("e")
            tooltip "So we can embrace the dawn."

        textbutton "West":
            action Return("w")
            tooltip "Where to go to see the best sunsets."

        $ tooltip = GetTooltip()

        if tooltip:
            text "[tooltip]"

The Nearrect displayable can be used to display "popup-style" tooltips, and has support for a special "tooltip" focus name, that is set to the location of the last focus that set a tooltip:

screen tooltip_example2():
    frame:

        padding (20, 20)
        align (.5, .3)

        has vbox

        textbutton "North":
            action Return("n")
            tooltip "To meet a polar bear."

        textbutton "South":
            action Return("s")
            tooltip "All the way to the tropics."

        textbutton "East":
            action Return("e")
            tooltip "So we can embrace the dawn."

        textbutton "West":
            action Return("w")
            tooltip "Where to go to see the best sunsets."

    # This has to be the last thing shown in the screen.

    $ tooltip = GetTooltip()

    if tooltip:

        nearrect:
            focus "tooltip"
            prefer_top True

            frame:
                xalign 0.5
                text tooltip

Legacy link

Warning

This has been obsoleted by the above, but you might see it in older projects.

The tooltip class changes the screen when a button is hovered.

When using a tooltip with a screen, the usual behavior is to create a tooltip object in a default statement. The value of the tooltip and the action method can then be used within the screen. The order of use within a screen doesn't matter – it's possible to use the value before an action is used.

Tooltips can take on any value. While in the example below we use the text statement to display a string on the screen, it's also possible to use the add statement to add a displayable. More complex behavior is also possible.

screen tooltip_test:

    default tt = Tooltip("No button selected.")

    frame:
        xfill True

        has vbox

        textbutton "One.":
            action Return(1)
            hovered tt.Action("The loneliest number.")

        textbutton "Two.":
            action Return(2)
            hovered tt.Action("Is what it takes.")

        textbutton "Three.":
            action Return(3)
            hovered tt.Action("A crowd.")

        text tt.value