Screens and Python

Ren'Py supports defining screens in Python, as well as in the Ren'Py screen language. A Python screen is created by supplying a screen function to the renpy.define_screen() function. It can then be used like it was any other screen.

The screen function should have parameters corresponding to the scope variables it expects, and it should ignore extra keyword arguments. (That is, it should have **kwargs at the end of its parameter list.) It is then expected to call the UI functions to add displayables to the screen.The screen function is called whenever an interaction starts or restarts.

To ensure that this restarting is seamless to the user (and not causing things to reset), it's important that every call to a UI function supply the id argument. As a screen is re-created, Ren'Py will update each displayable with the contents of the old displayable with the same id. Ids are generated automatically by the screen language, but when doing things by hand, they must be manually specified.

Here's an example python screen:

init python:
    def say_screen(who, what, **kwargs):
        ui.window(id="window")
        ui.vbox(id="say_vbox")

        ui.text(who, id="who")
        ui.text(what, id="what")

        ui.close()

    renpy.define_screen("say", say_screen)

Screen Functions

The following functions support the definition, display, and hiding of screens.

renpy.call_screen(_screen_name, *args, **kwargs)

The programmatic equivalent of the show screen statement.

This shows _screen_name as a screen, then causes an interaction to occur. The screen is hidden at the end of the interaction, and the result of the interaction is returned.

Keyword arguments not beginning with _ are passed to the scope of the screen.

If the keyword argument _with_none is false, "with None" is not run at the end of end of the interaction.

renpy.define_screen(name, function, modal="False", zorder="0", tag=None, variant=None)

Defines a screen with name, which should be a string.

function

The function that is called to display the screen. The function is called with the screen scope as keyword arguments. It should ignore additional keyword arguments.

The function should call the ui functions to add things to the screen.

modal
A string that, when evaluated, determines of the created screen should be modal. A modal screen prevents screens underneath it from receiving input events.
zorder
A string that, when evaluated, should be an integer. The integer controls the order in which screens are displayed. A screen with a greater zorder number is displayed above screens with a lesser zorder number.
tag
The tag associated with this screen. When the screen is shown, it replaces any other screen with the same tag. The tag defaults to the name of the screen.
predict
If true, this screen can be loaded for image prediction. If false, it can't. Defaults to true.
variant
String. Gives the variant of the screen to use.
renpy.get_screen(name, layer='screens')

Returns the ScreenDisplayable with the given tag, on layer. If no displayable with the tag is not found, it is interpreted as screen name. If it's still not found, None is returned.

renpy.get_widget(screen, id, layer='screens')

From the screen on layer, returns the widget with id. Returns None if the screen doesn't exist, or there is no widget with that id on the screen.

renpy.hide_screen(tag, layer='screens')

The programmatic equivalent of the hide screen statement.

Hides the screen with tag on layer.

renpy.show_screen(_screen_name, *_args, **kwargs)

The programmatic equivalent of the show screen statement.

Shows the named screen. This takes the following keyword arguments:

_screen_name
The name of the screen to show.
_layer
The layer to show the screen on.
_tag
The tag to show the screen with. If not specified, defaults to the tag associated with the screen. It that's not specified, defaults to the name of the screen.,
_widget_properties
A map from the id of a widget to a property name -> property value map. When a widget with that id is shown by the screen, the specified properties are added to it.
_transient
If true, the screen will be automatically hidden at the end of the current interaction.

Keyword arguments not beginning with underscore (_) are used to initialize the screen's scope.

renpy.variant(name)

Returns true if a name is a screen variant that can be chosen by Ren'Py. See Screen Variants for more details. This function can be used as the condition in a python if statement to set up the appropriate styles for the selected screen variant.

name can also be a list of variants, in which case this function returns True if any of the variants is selected.

UI Functions

The UI functions are python equivalents of the screen language statements. For each screen language statement, there is a ui function with the same name. For example, ui.text corresponds to the text statement, and ui.add corresponds to the add statement.

There is a simple mapping between screen language parameters and arguments and python arguments. Screen language parameters become positional arguments, while properties become keyword arguments. For example, the screen language statement:

text "Hello, World" size 40 xalign 0.5

becomes:

ui.text("Hello, World", size=40, xalign=0.5)

(It really should have an id parameter added.)

There are three groups of UI functions, corresponding to the number of children they take.

The following UI functions do not take any children.

  • ui.add
  • ui.bar
  • ui.imagebutton
  • ui.input
  • ui.key
  • ui.label
  • ui.null
  • ui.text
  • ui.textbutton
  • ui.timer
  • ui.vbar
  • ui.hotspot
  • ui.hotbar
  • ui.spritemanager

The following UI functions take a single child. They must be given that child - use ui.null() if the child is missing.

  • ui.button
  • ui.frame
  • ui.transform
  • ui.window
  • ui.drag

The following UI functions take multiple children. They continue taking children until ui.close() is called.

  • ui.fixed
  • ui.grid
  • ui.hbox
  • ui.side
  • ui.vbox
  • ui.imagemap
  • ui.draggroup

There are a few UI functions that do not correspond to screen language statments, as they correspond to concepts that are not present in the screen language.

ui.adjustment(range=1, value=0, step=None, page=0, changed=None, adjustable=None, ranged=None)

Adjustment objects represent a value that can be adjusted by a bar or viewport. They contain information about the value, the range of the value, and how to adjust the value in small steps and large pages.

The following parameters correspond to fields or properties on the adjustment object:

range
The range of the adjustment, a number.
value
The value of the adjustment, a number.
step

The step size of the adjustment, a number. If None, then defaults to 1/10th of a page, if set. Otherwise, defaults to the 1/20th of the range.

This is used when scrolling a viewport with the mouse wheel.

page

The page size of the adjustment. If None, this is set automatically by a viewport. If never set, defaults to 1/10th of the range.

It's can be used when clicking on a scrollbar.

The following parameters control the behavior of the adjustment.

adjustable

If True, this adjustment can be changed by a bar. If False, it can't.

It defaults to being adjustable if a changed function is given or if the adjustment is associated with a viewport, and not adjustable otherwise.

changed
This function is called with the new value when the value of the adjustment changes.
ranged
This function is called with the adjustment object when the range of the adjustment is set by a viewport.
change(value)

Changes the value of the adjustment to value, updating any bars and viewports that use the adjustment.

ui.at(transform)

Specifieds a transform that is applied to the next displayable to be created. This is largely obsolete, as all UI functions now take an at argument.

ui.close()

Closes a displayable created with by a UI function. When a displayable is closed, we add new displayables to its parent, or to the layer if no displayable is open.

ui.detached()

Do not add the next displayable to any later or container. Use this if you want to assign the result of a ui function to a variable.

ui.layer(name)

Adds displayables to the layer named name. The later must be closed with ui.close().

Actions

Many of the displayables created in the screen language take actions as arguments. An action is one of three things:

  • A callable python object (like a function or bound method) that takes no arguments.
  • An object of a class that inherits from the Action class.
  • A list of other Actions.

The advantage to inheriting from the Action class is that it allows you to override the methods that determine when a button should be sensitive, and when it is selected.

class Action

To define a new action, inherit from this class. Override the methods in this class to change the behavior of the action.

__call__(self)

This is the method that is called when the action is activated. In many cases, returning a non-None value from the action will cause the current interaction to end.

This method must be overriden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

get_sensitive(self)

This is called to determine if the button with this action should be sensitive. It should return true if the button is sensitive.

Note that __call__ can be called, even if this returns False.

The default implementation returns True.

get_selected(self)

This should return true if the button should be rendered as a selected button, and false otherwise.

The default implemention returns False.

periodic(self, st)

This method is called once at the start of each interaction, and then is called periodically thereafter. If it returns a number, it will be called before that many seconds elapse, but it might be called sooner.

The main use of this is to call renpy.restart_interaction() if the value of get_selected or get_sensitive should change.

It takes one argument:

st
The number of seconds since the screen or displayable this action is associated with was first shown.
unhovered(self):

When the action is used as the hovered parameter to a button (or similar object), this method is called when the object loses focus.

BarValues

When creating a bar, vbar, or hotbar, a BarValue object can be supplied as the value argument. Methods on the BarValue object are called to get the adjustment and styles.

class BarValue

To define a new BarValue, inherit from this class and override some of the methods.

get_adjustment(self)

This method is called to get an adjustment object for the bar. It should create the adjustment with ui.adjustment(), and then return the object created this way.

This method must be overriden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

get_style(self)

This is used to determine the style of bars that use this value. It should return a tuple of two style names or style objects. The first is used for a bar, and the second for vbar.

This defaults to ("bar", "vbar").

replaces(self, other)

This is called when a BarValue replaces another BarValue, such as when a screen is updated. It can be used to update this BarValue from the other. It is called before get_adjustment.

Note that other is not necessarily the same type as self.

periodic(self, st)

This method is called once at the start of each interaction. If it returns a number of seconds, it will be called before that many seconds elapse, but it might be called sooner. It is called after get_adjustment.

It can be used to update the value of the bar over time, like AnimatedValue() does. To do this, get_adjustment should store the adjustment, and periodic should calle the adjustment's changed method.