Queerscriptors/renpy
2
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
renpy/doc/screen_python.html

921 lines
56 KiB
HTML
Raw Normal View History

renpy 7.5.3
2023-01-18 22:13:55 +00:00
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Screens and Python &#8212; Ren&#39;Py Documentation</title>
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Modes" href="modes.html" />
<link rel="prev" title="Advanced GUI" href="gui_advanced.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
</head><body>
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
Ren&#39;Py Documentation</a>
<span class="navbar-text navbar-version pull-left"><b>7.5.3</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li><a href="https://www.renpy.org">Home Page</a></li>
<li><a href="https://www.renpy.org/doc/html/">Online Documentation</a></li>
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Site <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="gui.html">GUI Customization Guide</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="language_basics.html">Language Basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="label.html">Labels &amp; Control Flow</a></li>
<li class="toctree-l1"><a class="reference internal" href="dialogue.html">Dialogue and Narration</a></li>
<li class="toctree-l1"><a class="reference internal" href="displaying_images.html">Displaying Images</a></li>
<li class="toctree-l1"><a class="reference internal" href="menus.html">In-Game Menus</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Statements</a></li>
<li class="toctree-l1"><a class="reference internal" href="conditional.html">Conditional Statements</a></li>
<li class="toctree-l1"><a class="reference internal" href="audio.html">Audio</a></li>
<li class="toctree-l1"><a class="reference internal" href="movie.html">Movie</a></li>
<li class="toctree-l1"><a class="reference internal" href="voice.html">Voice</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="text.html">Text</a></li>
<li class="toctree-l1"><a class="reference internal" href="translation.html">Translation</a></li>
<li class="toctree-l1"><a class="reference internal" href="displayables.html">Displayables</a></li>
<li class="toctree-l1"><a class="reference internal" href="transforms.html">Transforms</a></li>
<li class="toctree-l1"><a class="reference internal" href="transitions.html">Transitions</a></li>
<li class="toctree-l1"><a class="reference internal" href="atl.html">Animation and Transformation Language</a></li>
<li class="toctree-l1"><a class="reference internal" href="matrixcolor.html">Matrixcolor</a></li>
<li class="toctree-l1"><a class="reference internal" href="layeredimage.html">Layered Images</a></li>
<li class="toctree-l1"><a class="reference internal" href="3dstage.html">3D Stage</a></li>
<li class="toctree-l1"><a class="reference internal" href="live2d.html">Live2D Cubism</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="style.html">Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="style_properties.html">Style Properties</a></li>
<li class="toctree-l1"><a class="reference internal" href="screens.html">Screens and Screen Language</a></li>
<li class="toctree-l1"><a class="reference internal" href="screen_actions.html">Screen Actions, Values, and Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="screen_special.html">Special Screen Names</a></li>
<li class="toctree-l1"><a class="reference internal" href="screen_optimization.html">Screen Language Optimization</a></li>
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration Variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="preferences.html">Preference Variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="store_variables.html">Store Variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="mouse.html">Custom Mouse Cursors</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="launcher.html">Launcher</a></li>
<li class="toctree-l1"><a class="reference internal" href="developer_tools.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="director.html">Interactive Director</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="nvl_mode.html">NVL-Mode Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="input.html">Text Input</a></li>
<li class="toctree-l1"><a class="reference internal" href="side_image.html">Side Images</a></li>
<li class="toctree-l1"><a class="reference internal" href="rooms.html">Image Gallery, Music Room, and Replay Actions</a></li>
<li class="toctree-l1"><a class="reference internal" href="drag_drop.html">Drag and Drop</a></li>
<li class="toctree-l1"><a class="reference internal" href="sprites.html">Sprites</a></li>
<li class="toctree-l1"><a class="reference internal" href="keymap.html">Customizing the Keymap</a></li>
<li class="toctree-l1"><a class="reference internal" href="achievement.html">Achievements</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">Dialogue History</a></li>
<li class="toctree-l1"><a class="reference internal" href="multiple.html">Multiple Character Dialogue</a></li>
<li class="toctree-l1"><a class="reference internal" href="splashscreen_presplash.html">Splashscreen and Presplash</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="statement_equivalents.html">Statement Equivalents</a></li>
<li class="toctree-l1"><a class="reference internal" href="save_load_rollback.html">Saving, Loading, and Rollback</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistent.html">Persistent Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="trans_trans_python.html">Transforms and Transitions in Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="gui_advanced.html">Advanced GUI</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Screens and Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="modes.html">Modes</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdd.html">Creator-Defined Displayables</a></li>
<li class="toctree-l1"><a class="reference internal" href="cds.html">Creator-Defined Statements</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom_text_tags.html">Custom Text Tags</a></li>
<li class="toctree-l1"><a class="reference internal" href="character_callbacks.html">Character Callbacks</a></li>
<li class="toctree-l1"><a class="reference internal" href="file_python.html">File Access</a></li>
<li class="toctree-l1"><a class="reference internal" href="color_class.html">Color Class</a></li>
<li class="toctree-l1"><a class="reference internal" href="matrix.html">Matrix</a></li>
<li class="toctree-l1"><a class="reference internal" href="model.html">Model-Based Rendering</a></li>
<li class="toctree-l1"><a class="reference internal" href="other.html">Other Functions and Variables</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="build.html">Building Distributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="updater.html">Web Updater</a></li>
<li class="toctree-l1"><a class="reference internal" href="android.html">Android</a></li>
<li class="toctree-l1"><a class="reference internal" href="chromeos.html">Chrome OS/Chromebook</a></li>
<li class="toctree-l1"><a class="reference internal" href="ios.html">iOS</a></li>
<li class="toctree-l1"><a class="reference internal" href="iap.html">In-App Purchasing</a></li>
<li class="toctree-l1"><a class="reference internal" href="gesture.html">Gestures</a></li>
<li class="toctree-l1"><a class="reference internal" href="raspi.html">Raspberry Pi</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="problems.html">Dealing with Problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="environment_variables.html">Environment Variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="self_voicing.html">Self-Voicing</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="editor.html">Text Editor Integration</a></li>
<li class="toctree-l1"><a class="reference internal" href="skins.html">Skins</a></li>
<li class="toctree-l1"><a class="reference internal" href="translating_renpy.html">Translating Ren'Py</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog (Ren'Py 7.x-)</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog6.html">Changelog (Ren'Py 6.11 - 6.99)</a></li>
<li class="toctree-l1"><a class="reference internal" href="incompatible.html">Incompatible Changes</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributor.html">Distributor Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Credits</a></li>
<li class="toctree-l1"><a class="reference internal" href="sponsors.html">Ren'Py Development Sponsors</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="thequestion.html">Script of The Question</a></li>
<li class="toctree-l1"><a class="reference internal" href="thequestion_nvl.html">NVL-mode script for The Question</a></li>
</ul>
</ul>
</li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3">
<div id="sidebar" class="bs-sidenav" role="complementary"><ul>
<li><a class="reference internal" href="#">Screens and Python</a><ul>
<li><a class="reference internal" href="#screen-functions">Screen Functions</a></li>
<li><a class="reference internal" href="#actions">Actions</a></li>
<li><a class="reference internal" href="#barvalues">BarValues</a></li>
<li><a class="reference internal" href="#inputvalue">InputValue</a></li>
<li><a class="reference internal" href="#creator-defined-screen-language-statements">Creator-Defined Screen Language Statements</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="col-md-9 content">
<div class="section" id="screens-and-python">
<h1>Screens and Python<a class="headerlink" href="#screens-and-python" title="Permalink to this headline"> link</a></h1>
<div class="section" id="screen-functions">
<h2>Screen Functions<a class="headerlink" href="#screen-functions" title="Permalink to this headline"> link</a></h2>
<p>The following functions support various operations related to screens.</p>
<dl class="function">
<dt id="renpy.call_screen">
<code class="descclassname">renpy.</code><code class="descname">call_screen</code><span class="sig-paren">(</span><em>_screen_name</em>, <em>*args</em>, <em>_with_none=True</em>, <em>_mode=&quot;screen&quot;</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.call_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>The programmatic equivalent of the call screen statement.</p>
<p>This shows <cite>_screen_name</cite> 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.</p>
<p>Positional arguments, and keyword arguments that do not begin with
_ are passed to the screen.</p>
<p>If <cite>_with_none</cite> is false, &quot;with None&quot; is not run at the end of end
of the interaction.</p>
<p>If <cite>_mode</cite> is passed, it will be the mode of this interaction,
otherwise the mode will be &quot;screen&quot;.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.current_screen">
<code class="descclassname">renpy.</code><code class="descname">current_screen</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#renpy.current_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the ScreenDisplayable corresponding to the screen currently being
updated, rendered, or processed.</p>
<p>See <a class="reference internal" href="#renpy.get_screen" title="renpy.get_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_screen()</span></code></a> for documented fields on ScreenDisplayable.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.get_displayable">
<code class="descclassname">renpy.</code><code class="descname">get_displayable</code><span class="sig-paren">(</span><em>screen</em>, <em>id</em>, <em>layer=None</em>, <em>base=False</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.get_displayable" title="Permalink to this definition"> link</a></dt>
<dd><p>From the <cite>screen</cite> on <cite>layer</cite>, returns the displayable with
<cite>id</cite>. Returns None if the screen doesn't exist, or there is no
widget with that id on the screen.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.get_displayable_properties">
<code class="descclassname">renpy.</code><code class="descname">get_displayable_properties</code><span class="sig-paren">(</span><em>id</em>, <em>screen=None</em>, <em>layer=None</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.get_displayable_properties" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the properties for the displayable with <cite>id</cite> in the <cite>screen</cite>
on <cite>layer</cite>. If <cite>screen</cite> is None, returns the properties for the
current screen. This can be used from Python or property code inside
a screen.</p>
<p>Note that this returns a dictionary containing the widget properties,
and so to get an individual property, the dictionary must be accessed.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.get_screen">
<code class="descclassname">renpy.</code><code class="descname">get_screen</code><span class="sig-paren">(</span><em>name</em>, <em>layer=None</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.get_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the ScreenDisplayable with the given <cite>name</cite> on <cite>layer</cite>. <cite>name</cite>
is first interpreted as a tag name, and then as a screen name. If the
screen is not showing, returns None.</p>
<p>This can also take a list of names, in which case the first screen
that is showing is returned.</p>
<p>This function can be used to check if a screen is showing:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">renpy</span><span class="o">.</span><span class="n">get_screen</span><span class="p">(</span><span class="s2">&quot;say&quot;</span><span class="p">):</span>
<span class="k">text</span> <span class="s2">&quot;The say screen is showing.&quot;</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">text</span> <span class="s2">&quot;The say screen is hidden.&quot;</span>
</pre></div>
</div>
<p>The ScreenDisplayable objects returned by this function have the
following documented fields:</p>
<dl class="attribute">
<dt id="renpy.ScreenDisplayable.layer">
<code class="descclassname">ScreenDisplayable.</code><code class="descname">layer</code><a class="headerlink" href="#renpy.ScreenDisplayable.layer" title="Permalink to this definition"> link</a></dt>
<dd><p>The layer the screen is being displayed on.</p>
</dd></dl>
<dl class="attribute">
<dt id="ScreenDisplayable.name">
<code class="descclassname">ScreenDisplayable.</code><code class="descname">name</code><a class="headerlink" href="#ScreenDisplayable.name" title="Permalink to this definition"> link</a></dt>
<dd><p>The name of the screen.</p>
</dd></dl>
<dl class="attribute">
<dt id="ScreenDisplayable.zorder">
<code class="descclassname">ScreenDisplayable.</code><code class="descname">zorder</code><a class="headerlink" href="#ScreenDisplayable.zorder" title="Permalink to this definition"> link</a></dt>
<dd><p>The zorder the screen is being displayed at.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="renpy.hide_screen">
<code class="descclassname">renpy.</code><code class="descname">hide_screen</code><span class="sig-paren">(</span><em>tag</em>, <em>layer=None</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.hide_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>The programmatic equivalent of the hide screen statement.</p>
<p>Hides the screen with <cite>tag</cite> on <cite>layer</cite>.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.set_focus">
<code class="descclassname">renpy.</code><code class="descname">set_focus</code><span class="sig-paren">(</span><em>screen</em>, <em>id</em>, <em>layer=u'screens'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.set_focus" title="Permalink to this definition"> link</a></dt>
<dd><p>This attempts to focus the displayable with <cite>id</cite> in the screen <cite>screen</cite>.
Focusing will fail if the displayable isn't found, the window isn't
focused, or something else is grabbing focus.</p>
<p>The focus may change if the mouse moves, even slightly, after this call
is processed.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.show_screen">
<code class="descclassname">renpy.</code><code class="descname">show_screen</code><span class="sig-paren">(</span><em>_screen_name</em>, <em>*_args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.show_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>The programmatic equivalent of the show screen statement.</p>
<p>Shows the named screen. This takes the following keyword arguments:</p>
<dl class="docutils">
<dt><cite>_screen_name</cite></dt>
<dd>The name of the screen to show.</dd>
<dt><cite>_layer</cite></dt>
<dd>The layer to show the screen on.</dd>
<dt><cite>_zorder</cite></dt>
<dd>The zorder to show the screen on. If not specified, defaults to
the zorder associated with the screen. It that's not specified,
it is 0 by default.</dd>
<dt><cite>_tag</cite></dt>
<dd>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.</dd>
<dt><cite>_widget_properties</cite></dt>
<dd>A map from the id of a widget to a property name -&gt; property
value map. When a widget with that id is shown by the screen,
the specified properties are added to it.</dd>
<dt><cite>_transient</cite></dt>
<dd>If true, the screen will be automatically hidden at the end of
the current interaction.</dd>
</dl>
<p>Non-keyword arguments, and keyword arguments that do not begin with
an underscore, are passed to the screen.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.start_predict_screen">
<code class="descclassname">renpy.</code><code class="descname">start_predict_screen</code><span class="sig-paren">(</span><em>_screen_name</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.start_predict_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes Ren'Py to start predicting the screen named <cite>_screen_name</cite>
with the given arguments. This replaces any previous prediction
of <cite>_screen_name</cite>. To stop predicting a screen, call <a class="reference internal" href="#renpy.stop_predict_screen" title="renpy.stop_predict_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.stop_predict_screen()</span></code></a>.</p>
<p>Prediction will occur during normal gameplay. To wait for prediction
to complete, use the <cite>predict</cite> argument to <a class="reference internal" href="statement_equivalents.html#renpy.pause" title="renpy.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.pause()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.stop_predict_screen">
<code class="descclassname">renpy.</code><code class="descname">stop_predict_screen</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.stop_predict_screen" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes Ren'Py to stop predicting the screen named <cite>name</cite>.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.variant">
<code class="descclassname">renpy.</code><code class="descname">variant</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.variant" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns true if <cite>name</cite> is a screen variant that corresponds to the
context in which Ren'Py is currently executing. See <a class="reference internal" href="screens.html#screen-variants"><span class="std std-ref">Screen Variants</span></a>
for more details. This function can be used as the condition in an
if statement to switch behavior based on the selected screen variant.</p>
<p><cite>name</cite> can also be a list of variants, in which case this function
returns True if any of the variants would.</p>
</dd></dl>
<dl class="function">
<dt id="ui.adjustment">
<code class="descclassname">ui.</code><code class="descname">adjustment</code><span class="sig-paren">(</span><em>range=1</em>, <em>value=0</em>, <em>step=None</em>, <em>page=None</em>, <em>changed=None</em>, <em>adjustable=None</em>, <em>ranged=None</em>, <em>force_step=False</em><span class="sig-paren">)</span><a class="headerlink" href="#ui.adjustment" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>The following parameters correspond to fields or properties on
the adjustment object:</p>
<dl class="docutils">
<dt><cite>range</cite></dt>
<dd>The range of the adjustment, a number.</dd>
<dt><cite>value</cite></dt>
<dd>The value of the adjustment, a number.</dd>
<dt><cite>step</cite></dt>
<dd><p class="first">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.</p>
<p class="last">This is used when scrolling a viewport with the mouse wheel.</p>
</dd>
<dt><cite>page</cite></dt>
<dd><p class="first">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.</p>
<p class="last">It's can be used when clicking on a scrollbar.</p>
</dd>
</dl>
<p>The following parameters control the behavior of the adjustment.</p>
<dl class="docutils">
<dt><cite>adjustable</cite></dt>
<dd><p class="first">If True, this adjustment can be changed by a bar. If False,
it can't.</p>
<p class="last">It defaults to being adjustable if a <cite>changed</cite> function
is given or if the adjustment is associated with a viewport,
and not adjustable otherwise.</p>
</dd>
<dt><cite>changed</cite></dt>
<dd>This function is called with the new value when the value of
the adjustment changes.</dd>
<dt><cite>ranged</cite></dt>
<dd><p class="first">This function is called with the adjustment object when
the range of the adjustment is set by a viewport.</p>
<p class="last">This function may be called multiple times, as part of the layout
process.</p>
</dd>
<dt><cite>force_step</cite></dt>
<dd>If True and this adjustment changes by dragging associated
viewport or a bar, value will be changed only if the drag
reached next step.
If &quot;release&quot; and this adjustment changes by dragging associated
viewport or a bar, after the release, value will be
rounded to the nearest step.
If False, this adjustment will changes by dragging, ignoring
the step value.</dd>
</dl>
<dl class="method">
<dt id="ui.change">
<code class="descname">change</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#ui.change" title="Permalink to this definition"> link</a></dt>
<dd><p>Changes the value of the adjustment to <cite>value</cite>, updating
any bars and viewports that use the adjustment.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="ui.interact">
<code class="descclassname">ui.</code><code class="descname">interact</code><span class="sig-paren">(</span><em>roll_forward=None</em>, <em>mouse='default'</em><span class="sig-paren">)</span><a class="headerlink" href="#ui.interact" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes 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.</p>
<p>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, <a class="reference internal" href="input.html#renpy.input" title="renpy.input"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.input()</span></code></a>, among many other
functions. However, it can be called directly if necessary.</p>
<p>When an interaction ends, the transient layer and all screens shown with
transient=True are cleared from the scene lists.</p>
<p>The following arguments are documented. As other, undocumented arguments
exist for Ren'Py's internal use, please pass all arguments as keyword
arguments.</p>
<dl class="docutils">
<dt><cite>roll_forward</cite></dt>
<dd>The information that will be returned by this function when a
roll forward occurs. (If None, the roll forward is ignored.) This
should usually be passed the result of the <a class="reference internal" href="save_load_rollback.html#renpy.roll_forward_info" title="renpy.roll_forward_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.roll_forward_info()</span></code></a>
function.</dd>
<dt><cite>mouse</cite></dt>
<dd>The style of mouse cursor to use during this function.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="actions">
<h2>Actions<a class="headerlink" href="#actions" title="Permalink to this headline"> link</a></h2>
<p>Many of the displayables created in the screen language take actions
as arguments. An action is one of three things:</p>
<ul class="simple">
<li>A callable Python object (like a function or bound method) that
takes no arguments.</li>
<li>An object of a class that inherits from the Action class.</li>
<li>A list of other Actions.</li>
</ul>
<p>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.</p>
<dl class="class">
<dt id="Action">
<em class="property">class </em><code class="descname">Action</code><a class="headerlink" href="#Action" title="Permalink to this definition"> link</a></dt>
<dd><p>To define a new action, inherit from this class. Override the
methods in this class to change the behavior of the action.</p>
<dl class="method">
<dt id="Action.__call__">
<code class="descname">__call__</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.__call__" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>This method must be overridden, as the default method will
raise a NotImplemented exception (and hence cause Ren'Py to
report an error).</p>
</dd></dl>
<dl class="method">
<dt id="Action.get_sensitive">
<code class="descname">get_sensitive</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.get_sensitive" title="Permalink to this definition"> link</a></dt>
<dd><p>This is called to determine if the button with this action
should be sensitive. It should return true if the button is
sensitive.</p>
<p>Note that __call__ can be called, even if this returns False.</p>
<p>The default implementation returns True.</p>
</dd></dl>
<dl class="method">
<dt id="Action.get_selected">
<code class="descname">get_selected</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.get_selected" title="Permalink to this definition"> link</a></dt>
<dd><p>This should return true if the button should be rendered as a
selected button, and false otherwise.</p>
<p>The default implemention returns False.</p>
</dd></dl>
<dl class="method">
<dt id="Action.get_tooltip">
<code class="descname">get_tooltip</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.get_tooltip" title="Permalink to this definition"> link</a></dt>
<dd><p>This 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.</p>
<p>This defaults to returning None.</p>
</dd></dl>
<dl class="method">
<dt id="Action.periodic">
<code class="descname">periodic</code><span class="sig-paren">(</span><em>self</em>, <em>st</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.periodic" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>The main use of this is to call
<a class="reference internal" href="other.html#renpy.restart_interaction" title="renpy.restart_interaction"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.restart_interaction()</span></code></a> if the value of
get_selected or get_sensitive should change.</p>
<p>It takes one argument:</p>
<dl class="docutils">
<dt><cite>st</cite></dt>
<dd>The number of seconds since the screen or displayable this
action is associated with was first shown.</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="Action.unhovered">
<code class="descname">unhovered</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#Action.unhovered" title="Permalink to this definition"> link</a></dt>
<dd><p>When the action is used as the <cite>hovered</cite> parameter to a button (or
similar object), this method is called when the object loses focus.</p>
</dd></dl>
</dd></dl>
<p>To run an action from Python, use <a class="reference internal" href="#renpy.run" title="renpy.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.run()</span></code></a>.</p>
<dl class="function">
<dt id="renpy.is_selected">
<code class="descclassname">renpy.</code><code class="descname">is_selected</code><span class="sig-paren">(</span><em>action</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.is_selected" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns a true value if the provided action or list of actions
indicates it is selected, and false otherwise.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.is_sensitive">
<code class="descclassname">renpy.</code><code class="descname">is_sensitive</code><span class="sig-paren">(</span><em>action</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.is_sensitive" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns a true value if the provided action or list of actions
indicates it is sensitive, and false otherwise.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.run">
<code class="descclassname">renpy.</code><code class="descname">run</code><span class="sig-paren">(</span><em>action</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.run" title="Permalink to this definition"> link</a></dt>
<dd><p>Run 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.</p>
<p>Returns the result of the last action to return a value.</p>
</dd></dl>
</div>
<div class="section" id="barvalues">
<h2>BarValues<a class="headerlink" href="#barvalues" title="Permalink to this headline"> link</a></h2>
<p>When creating a bar, vbar, or hotbar, a BarValue object can be supplied as
the <cite>value</cite> property. Methods on the BarValue object are called to get
the adjustment and styles.</p>
<dl class="class">
<dt id="BarValue">
<em class="property">class </em><code class="descname">BarValue</code><a class="headerlink" href="#BarValue" title="Permalink to this definition"> link</a></dt>
<dd><p>To define a new BarValue, inherit from this class and override
some of the methods.</p>
<dl class="method">
<dt id="BarValue.get_adjustment">
<code class="descname">get_adjustment</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#BarValue.get_adjustment" title="Permalink to this definition"> link</a></dt>
<dd><p>This method is called to get an adjustment object for the
bar. It should create the adjustment with
<a class="reference internal" href="#ui.adjustment" title="ui.adjustment"><code class="xref py py-func docutils literal notranslate"><span class="pre">ui.adjustment()</span></code></a>, and then return the object created this
way.</p>
<p>This method must be overridden, as the default method will
raise NotImplemented (and hence cause Ren'Py to report an
error).</p>
</dd></dl>
<dl class="method">
<dt id="BarValue.get_style">
<code class="descname">get_style</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#BarValue.get_style" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>This defaults to (&quot;bar&quot;, &quot;vbar&quot;).</p>
</dd></dl>
<dl class="method">
<dt id="BarValue.get_tooltip">
<code class="descname">get_tooltip</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#BarValue.get_tooltip" title="Permalink to this definition"> link</a></dt>
<dd><p>This 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.</p>
<p>This defaults to returning None.</p>
</dd></dl>
<dl class="method">
<dt id="BarValue.replaces">
<code class="descname">replaces</code><span class="sig-paren">(</span><em>self</em>, <em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#BarValue.replaces" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>Note that <cite>other</cite> is not necessarily the same type as <cite>self</cite>.</p>
</dd></dl>
<dl class="method">
<dt id="BarValue.periodic">
<code class="descname">periodic</code><span class="sig-paren">(</span><em>self</em>, <em>st</em><span class="sig-paren">)</span><a class="headerlink" href="#BarValue.periodic" title="Permalink to this definition"> link</a></dt>
<dd><p>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.</p>
<p>It can be used to update the value of the bar over time, like
<a class="reference internal" href="screen_actions.html#AnimatedValue" title="AnimatedValue"><code class="xref py py-func docutils literal notranslate"><span class="pre">AnimatedValue()</span></code></a> does. To do this, get_adjustment should
store the adjustment, and periodic should call the
adjustment's changed method.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="inputvalue">
<h2>InputValue<a class="headerlink" href="#inputvalue" title="Permalink to this headline"> link</a></h2>
<p>When creating an input, an InputValue object can be supplied as the
<cite>value</cite> 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.</p>
<dl class="class">
<dt id="InputValue">
<em class="property">class </em><code class="descname">InputValue</code><a class="headerlink" href="#InputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>To define a new InputValue, inherit from this class, override
some or all of the methods, and set the value of the default
field.</p>
<dl class="attribute">
<dt id="InputValue.default">
<code class="descname">default</code><a class="headerlink" href="#InputValue.default" title="Permalink to this definition"> link</a></dt>
<dd><p>If true, the input is eligible to be editable by default. (That
is, it may be given the caret when the screen is shown.)</p>
</dd></dl>
<dl class="method">
<dt id="InputValue.get_text">
<code class="descname">get_text</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.get_text" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the default text of the input. This must be implemented.</p>
</dd></dl>
<dl class="method">
<dt id="InputValue.set_text">
<code class="descname">set_text</code><span class="sig-paren">(</span><em>self</em>, <em>s</em><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.set_text" title="Permalink to this definition"> link</a></dt>
<dd><p>Called when the text of the input is changed, with the new text.
This must be implemented.</p>
</dd></dl>
<dl class="method">
<dt id="InputValue.enter">
<code class="descname">enter</code><span class="sig-paren">(</span><em>self</em><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.enter" title="Permalink to this definition"> link</a></dt>
<dd><p>Called 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.</p>
</dd></dl>
<p>The following actions are available as methods on InputValue:</p>
<dl class="method">
<dt id="InputValue.Enable">
<code class="descname">Enable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.Enable" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns an action that enables text editing on the input.</p>
</dd></dl>
<dl class="method">
<dt id="InputValue.Disable">
<code class="descname">Disable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.Disable" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns an action that disables text editing on the input.</p>
</dd></dl>
<dl class="method">
<dt id="InputValue.Toggle">
<code class="descname">Toggle</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#InputValue.Toggle" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns an action that toggles text editing on the input.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="creator-defined-screen-language-statements">
<span id="creator-defined-sl"></span><h2>Creator-Defined Screen Language Statements<a class="headerlink" href="#creator-defined-screen-language-statements" title="Permalink to this headline"> link</a></h2>
<p>Ren'Py supports defining custom screen language statements. Creator-defined screen
language statements are wrappers for the screen language <a class="reference internal" href="screens.html#sl-use"><span class="std std-ref">use statement</span></a>.
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:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="n">titledwindow</span> <span class="s2">&quot;Test Window&quot;</span><span class="p">:</span>
<span class="n">icon</span> <span class="s2">&quot;icon.png&quot;</span>
<span class="k">text</span> <span class="s2">&quot;This is a test.&quot;</span>
</pre></div>
</div>
<p>becomes:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">use</span> <span class="n">titledwindow</span><span class="p">(</span><span class="s2">&quot;Test Window&quot;</span><span class="p">,</span> <span class="n">icon</span><span class="o">=</span><span class="s2">&quot;icon.png&quot;</span><span class="p">):</span>
<span class="k">text</span> <span class="s2">&quot;This is a test.&quot;</span>
</pre></div>
</div>
<p>Creator-defined screen language statements must be registered in a <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">early</span></code> 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.</p>
<p>Creator-defined screen language statements are registered with the renpy.register_sl_statement
function:</p>
<dl class="class">
<dt id="renpy.register_sl_displayable">
<em class="property">class </em><code class="descclassname">renpy.</code><code class="descname">register_sl_displayable</code><span class="sig-paren">(</span><em>name</em>, <em>displayable</em>, <em>style</em>, <em>nchildren=0</em>, <em>scope=False</em>, <em>replaces=False</em>, <em>default_keywords={}</em>, <em>default_properties=True</em>, <em>unique=False</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable" title="Permalink to this definition"> link</a></dt>
<dd><p>Registers a screen language statement that creates a displayable.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the screen language statement, a string containing a Ren'Py
keyword. This keyword is used to introduce the new statement.</dd>
<dt><cite>displayable</cite></dt>
<dd><p class="first">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.</p>
<p class="last">This must return a Displayable. If it returns multiple displayables,
the _main attribute of the outermost displayable should be set to
the &quot;main&quot; displayable - the one that children should be added
to.</p>
</dd>
<dt><cite>style</cite></dt>
<dd>The base name of the style of this displayable. If the style property
is not given, this will have the style prefix added to it. The
computed style is passed to the <cite>displayable</cite> function as the
<code class="docutils literal notranslate"><span class="pre">style</span></code> keyword argument.</dd>
<dt><cite>nchildren</cite></dt>
<dd><p class="first">The number of children of this displayable. One of:</p>
<dl class="last docutils">
<dt>0</dt>
<dd>The displayable takes no children.</dd>
<dt>1</dt>
<dd>The displayable takes 1 child. If more than one child is given,
the children are placed in a Fixed.</dd>
<dt>&quot;many&quot;</dt>
<dd>The displayable takes more than one child.</dd>
</dl>
</dd>
<dt><cite>unique</cite></dt>
<dd>This should be set to true if the function returns a displayable with
no other references to it.</dd>
</dl>
<p>The following arguments should be passed in using keyword arguments:</p>
<dl class="docutils">
<dt><cite>replaces</cite></dt>
<dd>If true, and the displayable replaces a prior displayable, that displayable
is passed as a parameter to the new displayable.</dd>
<dt><cite>default_keywords</cite></dt>
<dd>The default set of keyword arguments to supply to the displayable.</dd>
<dt><cite>default_properties</cite></dt>
<dd>If true, the ui and position properties are added by default.</dd>
</dl>
<p>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.</p>
<dl class="method">
<dt id="renpy.register_sl_displayable.add_positional">
<code class="descname">add_positional</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable.add_positional" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds a positional argument with <cite>name</cite></p>
</dd></dl>
<dl class="method">
<dt id="renpy.register_sl_displayable.add_property">
<code class="descname">add_property</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable.add_property" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds a property with <cite>name</cite>. Properties are passed as keyword
arguments.</p>
</dd></dl>
<dl class="method">
<dt id="renpy.register_sl_displayable.add_style_property">
<code class="descname">add_style_property</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable.add_style_property" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds a family of properties, ending with <cite>name</cite> and prefixed with
the various style property prefixes. For example, if called with
(&quot;size&quot;), this will define size, idle_size, hover_size, etc.</p>
</dd></dl>
<dl class="method">
<dt id="renpy.register_sl_displayable.add_prefix_style_property">
<code class="descname">add_prefix_style_property</code><span class="sig-paren">(</span><em>prefix</em>, <em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable.add_prefix_style_property" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds a family of properties with names consisting of <cite>prefix</cite>,
a style property prefix, and <cite>name</cite>. For example, if called
with a prefix of <cite>text_</cite> and a name of <cite>size</cite>, this will
create text_size, text_idle_size, text_hover_size, etc.</p>
</dd></dl>
<dl class="method">
<dt id="renpy.register_sl_displayable.add_property_group">
<code class="descname">add_property_group</code><span class="sig-paren">(</span><em>group</em>, <em>prefix=''</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_displayable.add_property_group" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds a group of properties, prefixed with <cite>prefix</cite>. <cite>Group</cite> may
be one of the strings:</p>
<ul class="simple">
<li>&quot;bar&quot;</li>
<li>&quot;box&quot;</li>
<li>&quot;button&quot;</li>
<li>&quot;position&quot;</li>
<li>&quot;text&quot;</li>
<li>&quot;window&quot;</li>
</ul>
<p>These correspond to groups of <span class="xref std std-ref">style-properties</span>. Group can
also be &quot;ui&quot;, in which case it adds the <a class="reference internal" href="screens.html#common-properties"><span class="std std-ref">common ui properties</span></a>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="renpy.register_sl_statement">
<em class="property">class </em><code class="descclassname">renpy.</code><code class="descname">register_sl_statement</code><span class="sig-paren">(</span><em>name</em>, <em>children=u'many'</em>, <em>screen=None</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.register_sl_statement" title="Permalink to this definition"> link</a></dt>
<dd><p>Registers a custom screen language statement with Ren'Py.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>This must be a word. It's the name of the custom screen language
statement.</dd>
<dt><cite>children</cite></dt>
<dd>The number of children this custom statement takes. This should
be 0, 1, or &quot;many&quot;, which means zero or more.</dd>
<dt><cite>screen</cite></dt>
<dd>The screen to use. If not given, defaults to <cite>name</cite>.</dd>
</dl>
<p>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 <a class="reference internal" href="#renpy.register_sl_displayable" title="renpy.register_sl_displayable"><code class="xref py py-class docutils literal notranslate"><span class="pre">renpy.register_sl_displayable</span></code></a>.</p>
</dd></dl>
<p>As an example of a creator-defined screen language statement, here's an
implementation of the <code class="docutils literal notranslate"><span class="pre">titledwindow</span></code> statement given above. First, the
statement must be registered in a <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">early</span></code> block in a file that is loaded
early – a name like 01custom.rpy will often load soon enough. The registration
call looks like:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">python</span> <span class="n">early</span><span class="p">:</span>
<span class="n">renpy</span><span class="o">.</span><span class="n">register_sl_statement</span><span class="p">(</span><span class="s2">&quot;titledwindow&quot;</span><span class="p">,</span> <span class="n">children</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">add_positional</span><span class="p">(</span><span class="s2">&quot;title&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">add_property</span><span class="p">(</span><span class="s2">&quot;icon&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">add_property</span><span class="p">(</span><span class="s2">&quot;pos&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Then, we define a screen that implements the custom statement. This screen can be defined in
any file. One such screen is:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">screen</span> <span class="n">titledwindow</span><span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">icon</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="na">pos</span><span class="o">=</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)):</span>
<span class="k">drag</span><span class="p">:</span>
<span class="na">pos</span> <span class="na">pos</span>
<span class="k">frame</span><span class="p">:</span>
<span class="na">background</span> <span class="s2">&quot;#00000080&quot;</span>
<span class="k">has</span> <span class="k">vbox</span>
<span class="k">hbox</span><span class="p">:</span>
<span class="k">if</span> <span class="n">icon</span> <span class="k">is</span> <span class="k">not</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">add</span> <span class="n">icon</span>
<span class="k">text</span> <span class="n">title</span>
<span class="k">null</span> <span class="na">height</span> <span class="mi">15</span>
<span class="k">transclude</span>
</pre></div>
</div>
<p>When are used large property groups like a <cite>add_property_group</cite>, it makes sense to use
the **properties syntax with a properties keyword in some place. For example:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">screen</span> <span class="n">titledwindow</span><span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">icon</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="na">properties</span><span class="p">):</span>
<span class="k">frame</span><span class="p">:</span>
<span class="c1"># When background not in properties it will use it as default value.</span>
<span class="na">background</span> <span class="s2">&quot;#00000080&quot;</span>
<span class="na">properties</span> <span class="na">properties</span>
<span class="k">has</span> <span class="k">vbox</span>
<span class="k">hbox</span><span class="p">:</span>
<span class="k">if</span> <span class="n">icon</span> <span class="k">is</span> <span class="k">not</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">add</span> <span class="n">icon</span>
<span class="k">text</span> <span class="n">title</span>
<span class="k">null</span> <span class="na">height</span> <span class="mi">15</span>
<span class="k">transclude</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2012-2022, Tom Rothamel.<br/>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.6.<br/>
</p>
</div>
</footer>
</body>
</html>
Reference in a new issue Copy permalink