The following functions support various operations related to screens.
renpy.
call_screen
(_screen_name, *args, _with_none=True, _mode="screen", **kwargs) linkThe programmatic equivalent of the call 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.
Positional arguments, and keyword arguments that do not begin with _ are passed to the screen.
If _with_none is false, "with None" is not run at the end of end of the interaction.
If _mode is passed, it will be the mode of this interaction, otherwise the mode will be "screen".
renpy.
current_screen
() linkReturns the ScreenDisplayable corresponding to the screen currently being updated, rendered, or processed.
See get_screen()
for documented fields on ScreenDisplayable.
renpy.
get_displayable
(screen, id, layer=None, base=False) linkFrom the screen on layer, returns the displayable with id. Returns None if the screen doesn't exist, or there is no widget with that id on the screen.
renpy.
get_displayable_properties
(id, screen=None, layer=None) linkReturns the properties for the displayable with id in the screen on layer. If screen is None, returns the properties for the current screen. This can be used from Python or property code inside a screen.
Note that this returns a dictionary containing the widget properties, and so to get an individual property, the dictionary must be accessed.
renpy.
get_screen
(name, layer=None) linkReturns the ScreenDisplayable with the given name on layer. name is first interpreted as a tag name, and then as a screen name. If the screen is not showing, returns None.
This can also take a list of names, in which case the first screen that is showing is returned.
This function can be used to check if a screen is showing:
if renpy.get_screen("say"):
text "The say screen is showing."
else:
text "The say screen is hidden."
The ScreenDisplayable objects returned by this function have the following documented fields:
ScreenDisplayable.
layer
linkThe layer the screen is being displayed on.
ScreenDisplayable.
name
linkThe name of the screen.
ScreenDisplayable.
zorder
linkThe zorder the screen is being displayed at.
renpy.
hide_screen
(tag, layer=None) linkThe programmatic equivalent of the hide screen statement.
Hides the screen with tag on layer.
renpy.
set_focus
(screen, id, layer=u'screens') linkThis attempts to focus the displayable with id in the screen screen. Focusing will fail if the displayable isn't found, the window isn't focused, or something else is grabbing focus.
The focus may change if the mouse moves, even slightly, after this call is processed.
renpy.
show_screen
(_screen_name, *_args, **kwargs) linkThe programmatic equivalent of the show screen statement.
Shows the named screen. This takes the following keyword arguments:
Non-keyword arguments, and keyword arguments that do not begin with an underscore, are passed to the screen.
renpy.
start_predict_screen
(_screen_name, *args, **kwargs) linkCauses Ren'Py to start predicting the screen named _screen_name
with the given arguments. This replaces any previous prediction
of _screen_name. To stop predicting a screen, call renpy.stop_predict_screen()
.
Prediction will occur during normal gameplay. To wait for prediction
to complete, use the predict argument to renpy.pause()
.
renpy.
stop_predict_screen
(name) linkCauses Ren'Py to stop predicting the screen named name.
renpy.
variant
(name) linkReturns true if name is a screen variant that corresponds to the context in which Ren'Py is currently executing. See Screen Variants for more details. This function can be used as the condition in an if statement to switch behavior based on the selected screen variant.
name can also be a list of variants, in which case this function returns True if any of the variants would.
ui.
adjustment
(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False) linkAdjustment 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:
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.
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.
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.
This function is called with the adjustment object when the range of the adjustment is set by a viewport.
This function may be called multiple times, as part of the layout process.
change
(value) linkChanges the value of the adjustment to value, updating any bars and viewports that use the adjustment.
ui.
interact
(roll_forward=None, mouse='default') linkCauses an interaction with the user, and returns the result of that interaction. This causes Ren'Py to redraw the screen and begin processing input events. When a displayable returns a value in response to an event, that value is returned from ui.interact, and the interaction ends.
This function is rarely called directly. It is usually called by other
parts of Ren'Py, including the say statement, menu statement, with statement,
pause statement, call screen, renpy.input()
, among many other
functions. However, it can be called directly if necessary.
When an interaction ends, the transient layer and all screens shown with transient=True are cleared from the scene lists.
The following arguments are documented. As other, undocumented arguments exist for Ren'Py's internal use, please pass all arguments as keyword arguments.
renpy.roll_forward_info()
function.Many of the displayables created in the screen language take actions as arguments. An action is one of three things:
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.
Action
linkTo define a new action, inherit from this class. Override the methods in this class to change the behavior of the action.
__call__
(self) linkThis 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 overridden, as the default method will raise a NotImplemented exception (and hence cause Ren'Py to report an error).
get_sensitive
(self) linkThis 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) linkThis should return true if the button should be rendered as a selected button, and false otherwise.
The default implemention returns False.
get_tooltip
(self) linkThis gets a default tooltip for this button, if a specific tooltip is not assigned. It should return the tooltip value, or None if a tooltip is not known.
This defaults to returning None.
periodic
(self, st) linkThis 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:
unhovered
(self) linkWhen the action is used as the hovered parameter to a button (or similar object), this method is called when the object loses focus.
To run an action from Python, use renpy.run()
.
renpy.
is_selected
(action) linkReturns a true value if the provided action or list of actions indicates it is selected, and false otherwise.
renpy.
is_sensitive
(action) linkReturns a true value if the provided action or list of actions indicates it is sensitive, and false otherwise.
renpy.
run
(action) linkRun an action or list of actions. A single action is called with no arguments, a list of actions is run in order using this function, and None is ignored.
Returns the result of the last action to return a value.
When creating a bar, vbar, or hotbar, a BarValue object can be supplied as the value property. Methods on the BarValue object are called to get the adjustment and styles.
BarValue
linkTo define a new BarValue, inherit from this class and override some of the methods.
get_adjustment
(self) linkThis 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 overridden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).
get_style
(self) linkThis 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").
get_tooltip
(self) linkThis gets a default tooltip for this button, if a specific tooltip is not assigned. It should return the tooltip value, or None if a tooltip is not known.
This defaults to returning None.
replaces
(self, other) linkThis 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) linkThis 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 call the
adjustment's changed method.
When creating an input, an InputValue object can be supplied as the value property. Methods on the InputValue object are called to get and set the text, determine if the input is editable, and handle the enter key being pressed.
InputValue
linkTo define a new InputValue, inherit from this class, override some or all of the methods, and set the value of the default field.
default
linkIf true, the input is eligible to be editable by default. (That is, it may be given the caret when the screen is shown.)
get_text
(self) linkReturns the default text of the input. This must be implemented.
set_text
(self, s) linkCalled when the text of the input is changed, with the new text. This must be implemented.
enter
(self) linkCalled when the user presses enter. If this returns a non-None value, that value is returned from the interacton. This may also raise renpy.IgnoreEvent() to ignore the press. Otherwise, the enter-press is propagated to other displayables.
The following actions are available as methods on InputValue:
Enable
() linkReturns an action that enables text editing on the input.
Disable
() linkReturns an action that disables text editing on the input.
Toggle
() linkReturns an action that toggles text editing on the input.
Ren'Py supports defining custom screen language statements. Creator-defined screen language statements are wrappers for the screen language use statement. Positional arguments remain positional arguments, properties become keyword arguments, and if the statement takes a block, so does the use statement. For example, the custom screen language statement:
titledwindow "Test Window":
icon "icon.png"
text "This is a test."
becomes:
use titledwindow("Test Window", icon="icon.png"):
text "This is a test."
Creator-defined screen language statements must be registered in a python early
block.
What's more, the filename containing the creator-defined statement must be be loaded earlier
than any file that uses it. Since Ren'Py loads files in the Unicode sort order of their paths,
it generally makes sense to prefix the name of any file registering a user-defined
statement with 01, or some other small number.
Creator-defined screen language statements are registered with the renpy.register_sl_statement function:
renpy.
register_sl_displayable
(name, displayable, style, nchildren=0, scope=False, replaces=False, default_keywords={}, default_properties=True, unique=False) linkRegisters a screen language statement that creates a displayable.
This is a function that, when called, returns a displayable object. All position arguments, properties, and style properties are passed as arguments to this function. Other keyword arguments are also given to this function, a described below.
This must return a Displayable. If it returns multiple displayables, the _main attribute of the outermost displayable should be set to the "main" displayable - the one that children should be added to.
style
keyword argument.The number of children of this displayable. One of:
The following arguments should be passed in using keyword arguments:
Returns an object that can have positional arguments and properties added to it by calling the following methods. Each of these methods returns the object it is called on, allowing methods to be chained together.
add_positional
(name) linkAdds a positional argument with name
add_property
(name) linkAdds a property with name. Properties are passed as keyword arguments.
add_style_property
(name) linkAdds a family of properties, ending with name and prefixed with the various style property prefixes. For example, if called with ("size"), this will define size, idle_size, hover_size, etc.
add_prefix_style_property
(prefix, name) linkAdds a family of properties with names consisting of prefix, a style property prefix, and name. For example, if called with a prefix of text_ and a name of size, this will create text_size, text_idle_size, text_hover_size, etc.
add_property_group
(group, prefix='') linkAdds a group of properties, prefixed with prefix. Group may be one of the strings:
These correspond to groups of style-properties. Group can also be "ui", in which case it adds the common ui properties.
renpy.
register_sl_statement
(name, children=u'many', screen=None) linkRegisters a custom screen language statement with Ren'Py.
Returns an object that can have positional arguments and properties
added to it. This object has the same .add_ methods as the objects
returned by renpy.register_sl_displayable
.
As an example of a creator-defined screen language statement, here's an
implementation of the titledwindow
statement given above. First, the
statement must be registered in a python early
block in a file that is loaded
early – a name like 01custom.rpy will often load soon enough. The registration
call looks like:
python early:
renpy.register_sl_statement("titledwindow", children=1).add_positional("title").add_property("icon").add_property("pos")
Then, we define a screen that implements the custom statement. This screen can be defined in any file. One such screen is:
screen titledwindow(title, icon=None, pos=(0, 0)):
drag:
pos pos
frame:
background "#00000080"
has vbox
hbox:
if icon is not None:
add icon
text title
null height 15
transclude
When are used large property groups like a add_property_group, it makes sense to use the **properties syntax with a properties keyword in some place. For example:
screen titledwindow(title, icon=None, **properties):
frame:
# When background not in properties it will use it as default value.
background "#00000080"
properties properties
has vbox
hbox:
if icon is not None:
add icon
text title
null height 15
transclude