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

1914 lines
116 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>Screen Actions, Values, and Functions &#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="Special Screen Names" href="screen_special.html" />
<link rel="prev" title="Screens and Screen Language" href="screens.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 class="current">
<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 current"><a class="current reference internal" href="#">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>
<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"><a class="reference internal" href="screen_python.html">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="#">Screen Actions, Values, and Functions</a><ul>
<li><a class="reference internal" href="#actions">Actions</a><ul>
<li><a class="reference internal" href="#control-actions">Control Actions</a></li>
<li><a class="reference internal" href="#data-actions">Data Actions</a></li>
<li><a class="reference internal" href="#menu-actions">Menu Actions</a></li>
<li><a class="reference internal" href="#file-actions">File Actions</a></li>
<li><a class="reference internal" href="#audio-actions">Audio Actions</a></li>
<li><a class="reference internal" href="#focus-actions">Focus Actions</a></li>
<li><a class="reference internal" href="#other-actions">Other Actions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bar-values">Bar Values</a></li>
<li><a class="reference internal" href="#input-values">Input Values</a></li>
<li><a class="reference internal" href="#functions-and-classes">Functions and Classes</a><ul>
<li><a class="reference internal" href="#preferences">Preferences</a></li>
<li><a class="reference internal" href="#gamepad">Gamepad</a></li>
<li><a class="reference internal" href="#file-functions">File Functions</a></li>
<li><a class="reference internal" href="#side-image-functions">Side Image Functions</a></li>
<li><a class="reference internal" href="#tooltips">Tooltips</a><ul>
<li><a class="reference internal" href="#legacy">Legacy</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="col-md-9 content">
<div class="section" id="screen-actions-values-and-functions">
<h1>Screen Actions, Values, and Functions<a class="headerlink" href="#screen-actions-values-and-functions" title="Permalink to this headline"> link</a></h1>
<p>Ren'Py ships with a number of actions, values, and functions intended
for use with screens and the screen language.</p>
<div class="section" id="actions">
<h2>Actions<a class="headerlink" href="#actions" title="Permalink to this headline"> link</a></h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<div class="section" id="control-actions">
<h3>Control Actions<a class="headerlink" href="#control-actions" title="Permalink to this headline"> link</a></h3>
<p>These are actions that manage screens, interaction results, and control flow.</p>
<dl class="function">
<dt id="Call">
<code class="descname">Call</code><span class="sig-paren">(</span><em>label</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Call" title="Permalink to this definition"> link</a></dt>
<dd><p>Ends the current statement, and calls <cite>label</cite>, given as a string.
Arguments and keyword arguments are passed to <a class="reference internal" href="statement_equivalents.html#renpy.call" title="renpy.call"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.call()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="Hide">
<code class="descname">Hide</code><span class="sig-paren">(</span><em>screen=None</em>, <em>transition=None</em>, <em>_layer=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Hide" title="Permalink to this definition"> link</a></dt>
<dd><p>This causes a screen to be hidden if it is shown.</p>
<dl class="docutils">
<dt><cite>screen</cite></dt>
<dd>Either a string giving the name of the screen to be hidden, or
None to hide the current screen.</dd>
<dt><cite>transition</cite></dt>
<dd>If not None, a transition that occurs when hiding the screen.</dd>
<dt><cite>_layer</cite></dt>
<dd>This is passed as the layer argument to <a class="reference internal" href="screen_python.html#renpy.hide_screen" title="renpy.hide_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.hide_screen()</span></code></a>.
Ignored if <cite>screen</cite> is None.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="Jump">
<code class="descname">Jump</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span><a class="headerlink" href="#Jump" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes control to transfer to <cite>label</cite>, given as a string.</p>
</dd></dl>
<dl class="function">
<dt id="NullAction">
<code class="descname">NullAction</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#NullAction" title="Permalink to this definition"> link</a></dt>
<dd><p>Does nothing.</p>
<p>This can be used to make a button responsive to hover/unhover events,
without actually doing anything.</p>
</dd></dl>
<dl class="function">
<dt id="Return">
<code class="descname">Return</code><span class="sig-paren">(</span><em>value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Return" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the current interaction to return the supplied value, which
must not be None. This is often used with menus and imagemaps, to
select what the return value of the interaction is. If the screen
was called using the <code class="docutils literal notranslate"><span class="pre">call</span> <span class="pre">screen</span></code> statement, the return value
is placed in the <cite>_return</cite> variable.</p>
<p>When in a menu, this returns from the menu. (The value should be
None in this case.)</p>
</dd></dl>
<dl class="function">
<dt id="Show">
<code class="descname">Show</code><span class="sig-paren">(</span><em>screen</em>, <em>transition=None</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Show" title="Permalink to this definition"> link</a></dt>
<dd><p>This causes another screen to be shown. <cite>screen</cite> is a string
giving the name of the screen. The arguments are
passed to the screen being shown.</p>
<p>If not None, <cite>transition</cite> is used to show the new screen.</p>
<p>This action takes the <cite>_layer</cite>, <cite>_zorder</cite> and <cite>_tag</cite> keyword
arguments, which have the same meaning as in the
<a class="reference internal" href="screen_python.html#renpy.show_screen" title="renpy.show_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.show_screen()</span></code></a> function.</p>
</dd></dl>
<dl class="function">
<dt id="ShowTransient">
<code class="descname">ShowTransient</code><span class="sig-paren">(</span><em>screen</em>, <em>transition=None</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#ShowTransient" title="Permalink to this definition"> link</a></dt>
<dd><p>Shows a transient screen. A transient screen will be hidden when
the current interaction completes. The arguments are
passed to the screen being shown.</p>
<p>If not None, <cite>transition</cite> is use to show the new screen.</p>
<p>This action takes the <cite>_layer</cite>, <cite>_zorder</cite> and <cite>_tag</cite> keyword
arguments, which have the same meaning as in the
<a class="reference internal" href="screen_python.html#renpy.show_screen" title="renpy.show_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.show_screen()</span></code></a> function.</p>
</dd></dl>
<dl class="function">
<dt id="ToggleScreen">
<code class="descname">ToggleScreen</code><span class="sig-paren">(</span><em>screen</em>, <em>transition=None</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleScreen" title="Permalink to this definition"> link</a></dt>
<dd><p>This toggles the visibility of <cite>screen</cite>. If it is not currently
shown, the screen is shown with the provided arguments. Otherwise,
the screen is hidden.</p>
<p>If not None, <cite>transition</cite> is use to show and hide the screen.</p>
<p>This action takes the <cite>_layer</cite>, <cite>_zorder</cite> and <cite>_tag</cite> keyword
arguments, which have the same meaning as in the
<a class="reference internal" href="screen_python.html#renpy.show_screen" title="renpy.show_screen"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.show_screen()</span></code></a> function.</p>
</dd></dl>
</div>
<div class="section" id="data-actions">
<h3>Data Actions<a class="headerlink" href="#data-actions" title="Permalink to this headline"> link</a></h3>
<p>These set or toggle data.</p>
<dl class="function">
<dt id="AddToSet">
<code class="descname">AddToSet</code><span class="sig-paren">(</span><em>set</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#AddToSet" title="Permalink to this definition"> link</a></dt>
<dd><p>Adds <cite>value</cite> to <cite>set</cite>.</p>
<dl class="docutils">
<dt><cite>set</cite></dt>
<dd>The set to add to. This may be a Python set or list, in which
case the value is appended to the list.</dd>
<dt><cite>value</cite></dt>
<dd>The value to add or append.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="RemoveFromSet">
<code class="descname">RemoveFromSet</code><span class="sig-paren">(</span><em>set</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#RemoveFromSet" title="Permalink to this definition"> link</a></dt>
<dd><p>Removes <cite>value</cite> from <cite>set</cite>.</p>
<dl class="docutils">
<dt><cite>set</cite></dt>
<dd>The set to remove from. This may be a set or list.</dd>
<dt><cite>value</cite></dt>
<dd>The value to remove.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="SetDict">
<code class="descname">SetDict</code><span class="sig-paren">(</span><em>dict</em>, <em>key</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#SetDict" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the value of <cite>key</cite> in <cite>dict</cite> to be set to <cite>value</cite>.
This also works with lists, where <cite>key</cite> is the index at which
the value will be set.</p>
</dd></dl>
<dl class="function">
<dt id="SetField">
<code class="descname">SetField</code><span class="sig-paren">(</span><em>object</em>, <em>field</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#SetField" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the a field on an object to be set to a given value.
<cite>object</cite> is the object, <cite>field</cite> is a string giving the name of the
field to set, and <cite>value</cite> is the value to set it to.</p>
</dd></dl>
<dl class="function">
<dt id="SetLocalVariable">
<code class="descname">SetLocalVariable</code><span class="sig-paren">(</span><em>name</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#SetLocalVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the variable called <cite>name</cite> to be set to <cite>value</cite> in the current
local context.</p>
<p>This function is only useful in a screen that has been <code class="docutils literal notranslate"><span class="pre">use</span></code>d by
another screen, as it provides a way of setting the value of a
variable inside the used screen. In all other cases,
<a class="reference internal" href="#SetScreenVariable" title="SetScreenVariable"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetScreenVariable()</span></code></a> should be preferred, as it allows more
of the screen to be cached.</p>
<p>For more information, see <a class="reference internal" href="screens.html#sl-use"><span class="std std-ref">Use</span></a>.</p>
<p>This must be created in the context that the variable is set
in - it can't be passed in from somewhere else.</p>
</dd></dl>
<dl class="function">
<dt id="SetScreenVariable">
<code class="descname">SetScreenVariable</code><span class="sig-paren">(</span><em>name</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#SetScreenVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the variable called <cite>name</cite> associated with the current screen
to be set to <cite>value</cite>.
In a <code class="docutils literal notranslate"><span class="pre">use</span></code>d screen, this action sets the variable in the context
of the screen containing the <code class="docutils literal notranslate"><span class="pre">use</span></code>d one(s).
To set variables within a <code class="docutils literal notranslate"><span class="pre">use</span></code>d screen, and only in that
case, use <a class="reference internal" href="#SetLocalVariable" title="SetLocalVariable"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetLocalVariable()</span></code></a> instead.</p>
</dd></dl>
<dl class="function">
<dt id="SetVariable">
<code class="descname">SetVariable</code><span class="sig-paren">(</span><em>name</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#SetVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the variable called <cite>name</cite> to be set to <cite>value</cite>.</p>
<p>The <cite>name</cite> argument must be a string, and can be a simple name like &quot;strength&quot;, or
one with dots separating the variable from fields, like &quot;hero.strength&quot;
or &quot;persistent.show_cutscenes&quot;.</p>
</dd></dl>
<dl class="function">
<dt id="ToggleDict">
<code class="descname">ToggleDict</code><span class="sig-paren">(</span><em>dict</em>, <em>key</em>, <em>true_value=None</em>, <em>false_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleDict" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the value of <cite>key</cite> in <cite>dict</cite>. It also works on
lists, in which case <cite>key</cite> is the index of the value to toggle.
Toggling means to invert the value when the action is performed.</p>
<dl class="docutils">
<dt><cite>true_value</cite></dt>
<dd>If not None, then this is the true value used.</dd>
<dt><cite>false_value</cite></dt>
<dd>If not None, then this is the false value used.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleField">
<code class="descname">ToggleField</code><span class="sig-paren">(</span><em>object</em>, <em>field</em>, <em>true_value=None</em>, <em>false_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleField" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles <cite>field</cite> on <cite>object</cite>. Toggling means to invert the boolean
value of that field when the action is performed.</p>
<dl class="docutils">
<dt><cite>true_value</cite></dt>
<dd>If not None, then this is the true value we use.</dd>
<dt><cite>false_value</cite></dt>
<dd>If not None, then this is the false value we use.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleLocalVariable">
<code class="descname">ToggleLocalVariable</code><span class="sig-paren">(</span><em>name</em>, <em>true_value=None</em>, <em>false_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleLocalVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the value of the variable called <cite>name</cite> in the current local context.</p>
<p>This function is only useful in a screen that has been <code class="docutils literal notranslate"><span class="pre">use</span></code>d by
another screen, as it provides a way of setting the value of a
variable inside the used screen. In all other cases,
<a class="reference internal" href="#ToggleScreenVariable" title="ToggleScreenVariable"><code class="xref py py-func docutils literal notranslate"><span class="pre">ToggleScreenVariable()</span></code></a> should be preferred, as it allows more
of the screen to be cached.</p>
<p>For more information, see <a class="reference internal" href="screens.html#sl-use"><span class="std std-ref">Use</span></a>.</p>
<p>This must be created in the context that the variable is set
in - it can't be passed in from somewhere else.</p>
<dl class="docutils">
<dt><cite>true_value</cite></dt>
<dd>If not None, then this is the true value used.</dd>
<dt><cite>false_value</cite></dt>
<dd>If not None, then this is the false value used.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleScreenVariable">
<code class="descname">ToggleScreenVariable</code><span class="sig-paren">(</span><em>name</em>, <em>true_value=None</em>, <em>false_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleScreenVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the value of the variable called <cite>name</cite> in the current screen.
In a <code class="docutils literal notranslate"><span class="pre">use</span></code>d screen, this action accesses and sets the given variable
in the context of the screen containing the <code class="docutils literal notranslate"><span class="pre">use</span></code>d one(s).
To access and set variables within a <code class="docutils literal notranslate"><span class="pre">use</span></code>d screen, and only in that
case, use <a class="reference internal" href="#ToggleLocalVariable" title="ToggleLocalVariable"><code class="xref py py-func docutils literal notranslate"><span class="pre">ToggleLocalVariable()</span></code></a> instead.</p>
<dl class="docutils">
<dt><cite>true_value</cite></dt>
<dd>If not None, then this is the true value used.</dd>
<dt><cite>false_value</cite></dt>
<dd>If not None, then this is the false value used.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleSetMembership">
<code class="descname">ToggleSetMembership</code><span class="sig-paren">(</span><em>set</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleSetMembership" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the membership of <cite>value</cite> in <cite>set</cite>. If the value is not
in the set, it's added. Otherwise, it is removed.</p>
<p>Buttons with this action are marked as selected if and only if the
value is in the set.</p>
<dl class="docutils">
<dt><cite>set</cite></dt>
<dd>The set to add to or remove from. This may be a set or list. In the
case of a list, new items are appended.</dd>
<dt><cite>value</cite></dt>
<dd>The value to add or append.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleVariable">
<code class="descname">ToggleVariable</code><span class="sig-paren">(</span><em>variable</em>, <em>true_value=None</em>, <em>false_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleVariable" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the variable whose name is given in <cite>variable</cite>.</p>
<p>The <cite>variable</cite> argument must be a string, and can be a simple name like &quot;strength&quot;, or
one with dots separating the variable from fields, like &quot;hero.strength&quot;
or &quot;persistent.show_cutscenes&quot;.</p>
<dl class="docutils">
<dt><cite>true_value</cite></dt>
<dd>If not None, then this is the true value used.</dd>
<dt><cite>false_value</cite></dt>
<dd>If not None, then this is the false value used.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="menu-actions">
<h3>Menu Actions<a class="headerlink" href="#menu-actions" title="Permalink to this headline"> link</a></h3>
<p>These actions invoke menus, or are primarily useful while in the main
or game menus.</p>
<dl class="function">
<dt id="MainMenu">
<code class="descname">MainMenu</code><span class="sig-paren">(</span><em>confirm=True</em>, <em>save=True</em><span class="sig-paren">)</span><a class="headerlink" href="#MainMenu" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes Ren'Py to return to the main menu.</p>
<dl class="docutils">
<dt><cite>confirm</cite></dt>
<dd>If true, causes Ren'Py to ask the user if he wishes to
return to the main menu, rather than returning
directly.</dd>
<dt><cite>save</cite></dt>
<dd>If true, the game is saved in <a class="reference internal" href="store_variables.html#var-_quit_slot"><code class="xref std std-var docutils literal notranslate"><span class="pre">_quit_slot</span></code></a> before Ren'Py
restarts and returns the user to the main menu. The game is not
saved if <a class="reference internal" href="store_variables.html#var-_quit_slot"><code class="xref std std-var docutils literal notranslate"><span class="pre">_quit_slot</span></code></a> is None.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="Quit">
<code class="descname">Quit</code><span class="sig-paren">(</span><em>confirm=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Quit" title="Permalink to this definition"> link</a></dt>
<dd><p>Quits the game.</p>
<dl class="docutils">
<dt><cite>confirm</cite></dt>
<dd>If true, prompts the user if he wants to quit, rather
than quitting directly. If None, asks if and only if
the user is not at the main menu.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ShowMenu">
<code class="descname">ShowMenu</code><span class="sig-paren">(</span><em>screen=None</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#ShowMenu" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes us to enter the game menu, if we're not there already. If we
are in the game menu, then this shows a screen or jumps to a label.</p>
<p><cite>screen</cite> is usually the name of a screen, which is shown using
the screen mechanism. If the screen doesn't exist, then &quot;_screen&quot;
is appended to it, and that label is jumped to.</p>
<p>If the optional keyword argument <cite>_transition</cite> is given, the
menu will change screens using the provided transition.
If not manually specified, the default transition is
<cite>config.intra_transition</cite>.</p>
<ul class="simple">
<li>ShowMenu(&quot;load&quot;)</li>
<li>ShowMenu(&quot;save&quot;)</li>
<li>ShowMenu(&quot;preferences&quot;)</li>
</ul>
<p>This can also be used to show user-defined menu screens. For
example, if one has a &quot;stats&quot; screen defined, one can
show it as part of the game menu using:</p>
<ul class="simple">
<li>ShowMenu(&quot;stats&quot;)</li>
</ul>
<p>ShowMenu without an argument will enter the game menu at the
default screen, taken from _game_menu_screen.</p>
<p>Extra arguments and keyword arguments are passed on to the screen</p>
</dd></dl>
<dl class="function">
<dt id="Start">
<code class="descname">Start</code><span class="sig-paren">(</span><em>label=u'start'</em><span class="sig-paren">)</span><a class="headerlink" href="#Start" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes Ren'Py to jump out of the menu context to the named
label. The main use of this is to start a new game from the
main menu. Common uses are:</p>
<ul class="simple">
<li>Start() - Start at the start label.</li>
<li>Start(&quot;foo&quot;) - Start at the &quot;foo&quot; label.</li>
</ul>
</dd></dl>
</div>
<div class="section" id="file-actions">
<h3>File Actions<a class="headerlink" href="#file-actions" title="Permalink to this headline"> link</a></h3>
<p>These actions handle saving, loading, and deleting of files. Many of these
take the <cite>name</cite> and <cite>page</cite> arguments.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>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.</dd>
<dt><cite>page</cite></dt>
<dd>The page that this action acts on. This is one of &quot;auto&quot;,
&quot;quick&quot;, or a positive integer. If None, the page is determined
automatically, based on a persistent page number.</dd>
</dl>
<dl class="function">
<dt id="FileAction">
<code class="descname">FileAction</code><span class="sig-paren">(</span><em>name</em>, <em>page=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#FileAction" title="Permalink to this definition"> link</a></dt>
<dd><p>&quot;Does the right thing&quot; with the file. This means loading it if the
load screen is showing (current screen is named &quot;load&quot;), and saving
otherwise.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the slot to save to or load from. If None, an unused slot
(a large number based on the current time) will be used.</dd>
<dt><cite>page</cite></dt>
<dd>The page that the file will be saved to or loaded from. If None, the
current page is used.</dd>
</dl>
<p>Other keyword arguments are passed to FileLoad or FileSave.</p>
</dd></dl>
<dl class="function">
<dt id="FileDelete">
<code class="descname">FileDelete</code><span class="sig-paren">(</span><em>name</em>, <em>confirm=True</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileDelete" title="Permalink to this definition"> link</a></dt>
<dd><p>Deletes the file.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the slot to delete.</dd>
<dt><cite>confirm</cite></dt>
<dd>If true and not at the main menu, prompt for confirmation before loading the file.</dd>
<dt><cite>page</cite></dt>
<dd>The page that the file will be loaded from. If None, the
current page is used.</dd>
<dt><cite>slot</cite></dt>
<dd>If True, <cite>name</cite> is taken to be a slot name, and <cite>page</cite> is ignored.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FileLoad">
<code class="descname">FileLoad</code><span class="sig-paren">(</span><em>name</em>, <em>confirm=True</em>, <em>page=None</em>, <em>newest=True</em>, <em>cycle=False</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileLoad" title="Permalink to this definition"> link</a></dt>
<dd><p>Loads the file.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the slot to load from. If None, an unused slot will be
used, and hence the file will not be loadable.</dd>
<dt><cite>confirm</cite></dt>
<dd>If true and not at the main menu, prompt for confirmation before loading the file.</dd>
<dt><cite>page</cite></dt>
<dd>The page that the file will be loaded from. If None, the
current page is used.</dd>
<dt><cite>newest</cite></dt>
<dd>If true, the button is selected if this is the newest file.</dd>
<dt><cite>cycle</cite></dt>
<dd>Ignored.</dd>
<dt><cite>slot</cite></dt>
<dd>If True, <cite>name</cite> is taken to be a slot name, and <cite>page</cite> is ignored.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FilePage">
<code class="descname">FilePage</code><span class="sig-paren">(</span><em>page</em><span class="sig-paren">)</span><a class="headerlink" href="#FilePage" title="Permalink to this definition"> link</a></dt>
<dd><p>Sets the file page to <cite>page</cite>, which should be one of &quot;auto&quot;, &quot;quick&quot;,
or an integer.</p>
</dd></dl>
<dl class="function">
<dt id="FilePageNext">
<code class="descname">FilePageNext</code><span class="sig-paren">(</span><em>max=None</em>, <em>wrap=False</em>, <em>auto=True</em>, <em>quick=True</em><span class="sig-paren">)</span><a class="headerlink" href="#FilePageNext" title="Permalink to this definition"> link</a></dt>
<dd><p>Goes to the next file page.</p>
<dl class="docutils">
<dt><cite>max</cite></dt>
<dd>If set, this should be an integer that gives the number of
the maximum file page we can go to.</dd>
<dt><cite>wrap</cite></dt>
<dd>If true, we can go to the first page when on the
last file page if <cite>max</cite> is set.</dd>
<dt><cite>auto</cite></dt>
<dd>If true and wrap is set, this can bring the player to
the page of automatic saves.</dd>
<dt><cite>quick</cite></dt>
<dd>If true and wrap is set, this can bring the player to
the page of automatic saves.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FilePagePrevious">
<code class="descname">FilePagePrevious</code><span class="sig-paren">(</span><em>max=None</em>, <em>wrap=False</em>, <em>auto=True</em>, <em>quick=True</em><span class="sig-paren">)</span><a class="headerlink" href="#FilePagePrevious" title="Permalink to this definition"> link</a></dt>
<dd><p>Goes to the previous file page, if possible.</p>
<dl class="docutils">
<dt><cite>max</cite></dt>
<dd>If set, this should be an integer that gives the number of
the maximum file page we can go to. This is required to enable
wrap.</dd>
<dt><cite>wrap</cite></dt>
<dd>If true, we can go to the last page when on the first file page if max is set.</dd>
<dt><cite>auto</cite></dt>
<dd>If true, this can bring the player to
the page of automatic saves.</dd>
<dt><cite>quick</cite></dt>
<dd>If true, this can bring the player to
the page of automatic saves.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FileSave">
<code class="descname">FileSave</code><span class="sig-paren">(</span><em>name</em>, <em>confirm=True</em>, <em>newest=True</em>, <em>page=None</em>, <em>cycle=False</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileSave" title="Permalink to this definition"> link</a></dt>
<dd><p>Saves the file.</p>
<p>The button with this slot is selected if it's marked as the
newest save file.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the slot to save to. If None, an unused slot
(a large number based on the current time) will be used.</dd>
<dt><cite>confirm</cite></dt>
<dd>If true, then we will prompt before overwriting a file.</dd>
<dt><cite>newest</cite></dt>
<dd>Ignored.</dd>
<dt><cite>page</cite></dt>
<dd>The name of the page that the slot is on. If None, the current
page is used.</dd>
<dt><cite>cycle</cite></dt>
<dd>If true, then saves on the supplied page will be cycled before
being shown to the user. <a class="reference internal" href="config.html#var-config.quicksave_slots"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.quicksave_slots</span></code></a> slots are
used in the cycle.</dd>
<dt><cite>slot</cite></dt>
<dd>If True, <cite>name</cite> is taken to be a slot name, and <cite>page</cite> is ignored.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FileTakeScreenshot">
<code class="descname">FileTakeScreenshot</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#FileTakeScreenshot" title="Permalink to this definition"> link</a></dt>
<dd><p>Take a screenshot to be used when the game is saved. This can
be used to ensure that the screenshot is accurate, by taking
a picture of the screen before a file save screen is shown.</p>
</dd></dl>
<dl class="function">
<dt id="QuickLoad">
<code class="descname">QuickLoad</code><span class="sig-paren">(</span><em>confirm=True</em><span class="sig-paren">)</span><a class="headerlink" href="#QuickLoad" title="Permalink to this definition"> link</a></dt>
<dd><p>Performs a quick load.</p>
<dl class="docutils">
<dt><cite>confirm</cite></dt>
<dd>If true and not at the main menu, prompt for confirmation before loading the file.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="QuickSave">
<code class="descname">QuickSave</code><span class="sig-paren">(</span><em>message=u'Quick save complete.'</em>, <em>newest=False</em><span class="sig-paren">)</span><a class="headerlink" href="#QuickSave" title="Permalink to this definition"> link</a></dt>
<dd><p>Performs a quick save.</p>
<dl class="docutils">
<dt><cite>message</cite></dt>
<dd>A message to display to the user when the quick save finishes.</dd>
<dt><cite>newest</cite></dt>
<dd>Set to true to mark the quicksave as the newest save.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="audio-actions">
<span id="id1"></span><h3>Audio Actions<a class="headerlink" href="#audio-actions" title="Permalink to this headline"> link</a></h3>
<p>The concept of channels and how they work, as well as most information
about audio in Ren'Py, is explained at <a class="reference internal" href="audio.html"><span class="doc">Audio</span></a>.</p>
<dl class="function">
<dt id="PauseAudio">
<code class="descname">PauseAudio</code><span class="sig-paren">(</span><em>channel</em>, <em>value=True</em><span class="sig-paren">)</span><a class="headerlink" href="#PauseAudio" title="Permalink to this definition"> link</a></dt>
<dd><p>Sets the pause flag for <cite>channel</cite>.</p>
<p>If <cite>value</cite> is True, the channel is paused. If False, the channel is
unpaused. If &quot;toggle&quot;, the pause flag will be toggled.</p>
</dd></dl>
<dl class="function">
<dt id="Play">
<code class="descname">Play</code><span class="sig-paren">(</span><em>channel</em>, <em>file</em>, <em>selected=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Play" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes an audio file to be played on a given channel.</p>
<dl class="docutils">
<dt><cite>channel</cite></dt>
<dd>The channel to play the sound on.</dd>
<dt><cite>file</cite></dt>
<dd>The file to play.</dd>
<dt><cite>selected</cite></dt>
<dd>If True, buttons using this action will be marked as selected
if the file is playing on the channel. If False, this action
will not cause the button to start playing. If None, the button
is marked selected if the channel is a music channel, and not
otherwise.</dd>
</dl>
<p>Any other keyword arguments are passed to <a class="reference internal" href="audio.html#renpy.music.play" title="renpy.music.play"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.play()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="Queue">
<code class="descname">Queue</code><span class="sig-paren">(</span><em>channel</em>, <em>file</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Queue" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes an audio file to be queued on a given channel.</p>
<dl class="docutils">
<dt><cite>channel</cite></dt>
<dd>The channel to play the sound on.</dd>
<dt><cite>file</cite></dt>
<dd>The file to play.</dd>
</dl>
<p>Any keyword arguments are passed to <a class="reference internal" href="audio.html#renpy.music.queue" title="renpy.music.queue"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.queue()</span></code></a></p>
</dd></dl>
<dl class="function">
<dt id="SetMixer">
<code class="descname">SetMixer</code><span class="sig-paren">(</span><em>mixer</em>, <em>volume</em><span class="sig-paren">)</span><a class="headerlink" href="#SetMixer" title="Permalink to this definition"> link</a></dt>
<dd><p>Sets the volume of <cite>mixer</cite> to <cite>value</cite>.</p>
<dl class="docutils">
<dt><cite>mixer</cite></dt>
<dd>The mixer to set the volume of. A string, usually one of
&quot;main&quot;, &quot;music&quot;, &quot;sfx&quot;, or &quot;voice&quot;. See <a class="reference internal" href="audio.html#volume"><span class="std std-ref">Volume</span></a> for
more information about mixers.</dd>
<dt><cite>value</cite></dt>
<dd>The value to set the volume to. A number between 0.0 and 1.0,
inclusive.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="SetMute">
<code class="descname">SetMute</code><span class="sig-paren">(</span><em>mixer</em>, <em>mute</em><span class="sig-paren">)</span><a class="headerlink" href="#SetMute" title="Permalink to this definition"> link</a></dt>
<dd><p>Sets the mute status of one or more mixers. When a mixer is muted,
audio channels associated with that mixer will stop playing audio.</p>
<dl class="docutils">
<dt><cite>mixer</cite></dt>
<dd>Either a single string giving a mixer name, or a list of strings
giving a list of mixers. The strings should be mixer names.</dd>
<dt><cite>mute</cite></dt>
<dd>True to mute the mixer, False to ummute it.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="Stop">
<code class="descname">Stop</code><span class="sig-paren">(</span><em>channel</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Stop" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes an audio channel to be stopped.</p>
<dl class="docutils">
<dt><cite>channel</cite></dt>
<dd>The channel to stop the sound on.</dd>
</dl>
<p>Any keyword arguments are passed to <a class="reference internal" href="audio.html#renpy.music.stop" title="renpy.music.stop"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.stop()</span></code></a></p>
</dd></dl>
<dl class="function">
<dt id="ToggleMute">
<code class="descname">ToggleMute</code><span class="sig-paren">(</span><em>mixer</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleMute" title="Permalink to this definition"> link</a></dt>
<dd><p>Toggles the mute status of one or more mixers.</p>
<dl class="docutils">
<dt><cite>mixer</cite></dt>
<dd>Either a single string giving a mixer name, or a list of strings
giving a list of mixers. The strings should be mixer names.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="focus-actions">
<h3>Focus Actions<a class="headerlink" href="#focus-actions" title="Permalink to this headline"> link</a></h3>
<dl class="function">
<dt id="CaptureFocus">
<code class="descname">CaptureFocus</code><span class="sig-paren">(</span><em>name=u'default'</em><span class="sig-paren">)</span><a class="headerlink" href="#CaptureFocus" title="Permalink to this definition"> link</a></dt>
<dd><p>If a displayable is focused when this action is run, the rectangle
containing that displayable is stored with the name <cite>name</cite>. This
rectangle can then be retrieved with the <a class="reference internal" href="#GetFocusRect" title="GetFocusRect"><code class="xref py py-func docutils literal notranslate"><span class="pre">GetFocusRect()</span></code></a> action,
or the <cite>focus</cite> property of the <a class="reference internal" href="screens.html#sl-nearrect"><span class="std std-ref">Nearrect</span></a> displayable.</p>
<p>If no displayable is focused, the previous capture with that name
is removed.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the focus rectangle to store. This should be a string.
The name &quot;tooltip&quot; is special, as it is automatically captured
when the tooltip is changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ClearFocus">
<code class="descname">ClearFocus</code><span class="sig-paren">(</span><em>name=u'default'</em><span class="sig-paren">)</span><a class="headerlink" href="#ClearFocus" title="Permalink to this definition"> link</a></dt>
<dd><p>Clears a stored focus rectangle captured with <a class="reference internal" href="#CaptureFocus" title="CaptureFocus"><code class="xref py py-func docutils literal notranslate"><span class="pre">CaptureFocus()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="GetFocusRect">
<code class="descname">GetFocusRect</code><span class="sig-paren">(</span><em>name=u'default'</em><span class="sig-paren">)</span><a class="headerlink" href="#GetFocusRect" title="Permalink to this definition"> link</a></dt>
<dd><p>If a focus rectangle with the given name has been stored (either with
<a class="reference internal" href="#CaptureFocus" title="CaptureFocus"><code class="xref py py-func docutils literal notranslate"><span class="pre">CaptureFocus()</span></code></a>, or automatically by a tooltip, returns the
a (x, y, h, w) rectangle. Otherwise, returns None.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the focus rectangle to retrieve. The name &quot;tooltip&quot;
is special, as it is automatically captured when the tooltip is
changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ToggleFocus">
<code class="descname">ToggleFocus</code><span class="sig-paren">(</span><em>name=u'default'</em><span class="sig-paren">)</span><a class="headerlink" href="#ToggleFocus" title="Permalink to this definition"> link</a></dt>
<dd><p>If the focus rectangle exists, clears it, otherwise captures it.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>The name of the focus rectangle to store. This should be a string.
The name &quot;tooltip&quot; is special, as it is automatically captured
when the tooltip is changed.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="other-actions">
<h3>Other Actions<a class="headerlink" href="#other-actions" title="Permalink to this headline"> link</a></h3>
<p>These are other actions, not found anywhere else.</p>
<dl class="function">
<dt id="Confirm">
<code class="descname">Confirm</code><span class="sig-paren">(</span><em>prompt</em>, <em>yes</em>, <em>no=None</em>, <em>confirm_selected=False</em><span class="sig-paren">)</span><a class="headerlink" href="#Confirm" title="Permalink to this definition"> link</a></dt>
<dd><p>Prompts the user for confirmation of an action. If the user
clicks yes, the yes action is performed. Otherwise, the <cite>no</cite>
action is performed.</p>
<dl class="docutils">
<dt><cite>prompt</cite></dt>
<dd>The prompt to display to the user.</dd>
<dt><cite>confirm_selected</cite></dt>
<dd>If true, the prompt will be displayed even if the <cite>yes</cite> action
is already selected. If false (the default), the prompt
will not be displayed if the <cite>yes</cite> action is selected.</dd>
</dl>
<p>The sensitivity and selectedness of this action match those
of the <cite>yes</cite> action.</p>
</dd></dl>
<dl class="function">
<dt id="DisableAllInputValues">
<code class="descname">DisableAllInputValues</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#DisableAllInputValues" title="Permalink to this definition"> link</a></dt>
<dd><p>Disables all active InputValue. This will re-focus the default
InputValue, if there is one. Otherwise, no InputValue will be
focused.</p>
</dd></dl>
<dl class="function">
<dt id="Function">
<code class="descname">Function</code><span class="sig-paren">(</span><em>callable</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Function" title="Permalink to this definition"> link</a></dt>
<dd><p>This Action calls <cite>callable</cite> with <cite>args</cite> and <cite>kwargs</cite>.</p>
<dl class="docutils">
<dt><cite>callable</cite></dt>
<dd>Callable object. This assumes that if two callables compare
equal, calling either one will be equivalent.</dd>
<dt><cite>args</cite></dt>
<dd>position arguments to be passed to <cite>callable</cite>.</dd>
<dt><cite>kwargs</cite></dt>
<dd>keyword arguments to be passed to <cite>callable</cite>.</dd>
</dl>
<p>This Action takes an optional _update_screens keyword argument, which
defaults to true. When it is true, the interaction restarts and
the screens are updated after the function returns.</p>
<p>If the function returns a non-None value, the interaction stops and
returns that value. (When called using the call screen statement, the
result is placed in the <cite>_return</cite> variable.)</p>
<p>Instead of using a Function action, you can define your own subclass
of the <a class="reference internal" href="screen_python.html#Action" title="Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a> class. This lets you name the action, and
determine when it should be selected and sensitive.</p>
</dd></dl>
<dl class="function">
<dt id="Help">
<code class="descname">Help</code><span class="sig-paren">(</span><em>help=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Help" title="Permalink to this definition"> link</a></dt>
<dd><p>Displays help.</p>
<p>If a screen named <code class="docutils literal notranslate"><span class="pre">help</span></code> is defined, that screen is displayed
using <a class="reference internal" href="#ShowMenu" title="ShowMenu"><code class="xref py py-func docutils literal notranslate"><span class="pre">ShowMenu()</span></code></a> and <cite>help</cite> is ignored.</p>
<dl class="docutils">
<dt><cite>help</cite></dt>
<dd><p class="first">A string that is used to find help. This is used in the
following way:</p>
<ul class="simple">
<li>If a label with this name exists, the label is called in
a new context.</li>
<li>Otherwise, this is interpreted as giving the name of a file
that should be opened in a web browser.</li>
</ul>
<p class="last">If <cite>help</cite> is None, <code class="xref std std-var docutils literal notranslate"><span class="pre">config.help</span></code> is used as the default
value.</p>
</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="HideInterface">
<code class="descname">HideInterface</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#HideInterface" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the interface to be hidden until the user clicks.
This is typically what happens when hitting the H key in a Ren'Py game.</p>
</dd></dl>
<dl class="function">
<dt id="If">
<code class="descname">If</code><span class="sig-paren">(</span><em>expression</em>, <em>true=None</em>, <em>false=None</em><span class="sig-paren">)</span><a class="headerlink" href="#If" title="Permalink to this definition"> link</a></dt>
<dd><p>This returns <cite>true</cite> if <cite>expression</cite> is true, and <cite>false</cite>
otherwise. Use this to select an action based on an expression.
Note that the default, None, can be used as an action that causes
a button to be disabled.</p>
</dd></dl>
<dl class="function">
<dt id="InvertSelected">
<code class="descname">InvertSelected</code><span class="sig-paren">(</span><em>action</em><span class="sig-paren">)</span><a class="headerlink" href="#InvertSelected" title="Permalink to this definition"> link</a></dt>
<dd><p>This inverts the selection state of the provided action, while
proxying over all of the other methods.</p>
</dd></dl>
<dl class="function">
<dt id="MouseMove">
<code class="descname">MouseMove</code><span class="sig-paren">(</span><em>x</em>, <em>y</em>, <em>duration=0</em><span class="sig-paren">)</span><a class="headerlink" href="#MouseMove" title="Permalink to this definition"> link</a></dt>
<dd><p>Move the mouse pointer to <cite>x</cite>, <cite>y</cite>. If the device does not have a mouse
pointer or _preferences.mouse_move is False, this does nothing.</p>
<dl class="docutils">
<dt><cite>duration</cite></dt>
<dd>The time it will take to perform the move, in seconds. During
this time, the mouse may be unresponsive.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="Notify">
<code class="descname">Notify</code><span class="sig-paren">(</span><em>message</em><span class="sig-paren">)</span><a class="headerlink" href="#Notify" title="Permalink to this definition"> link</a></dt>
<dd><p>Displays <cite>message</cite> using <a class="reference internal" href="other.html#renpy.notify" title="renpy.notify"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.notify()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="OpenDirectory">
<code class="descname">OpenDirectory</code><span class="sig-paren">(</span><em>directory</em><span class="sig-paren">)</span><a class="headerlink" href="#OpenDirectory" title="Permalink to this definition"> link</a></dt>
<dd><p>Opens <cite>directory</cite> in a file browser. <cite>directory</cite> is relative to
the config.basedir.</p>
</dd></dl>
<dl class="function">
<dt id="OpenURL">
<code class="descname">OpenURL</code><span class="sig-paren">(</span><em>url</em><span class="sig-paren">)</span><a class="headerlink" href="#OpenURL" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes <cite>url</cite> to be opened in a web browser.</p>
</dd></dl>
<dl class="function">
<dt id="QueueEvent">
<code class="descname">QueueEvent</code><span class="sig-paren">(</span><em>event</em>, <em>up=False</em><span class="sig-paren">)</span><a class="headerlink" href="#QueueEvent" title="Permalink to this definition"> link</a></dt>
<dd><p>Queues the given event using <a class="reference internal" href="other.html#renpy.queue_event" title="renpy.queue_event"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.queue_event()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="RestartStatement">
<code class="descname">RestartStatement</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#RestartStatement" title="Permalink to this definition"> link</a></dt>
<dd><p>This action causes Ren'Py to rollback to before the current
statement, and then re-run the current statement. This may be used
when changing a persistent variable that affects how the statement
is displayed.</p>
<p>If run in a menu context, this waits until the player exits to a
top-level context before performing the rollback.</p>
</dd></dl>
<dl class="function">
<dt id="RollForward">
<code class="descname">RollForward</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#RollForward" title="Permalink to this definition"> link</a></dt>
<dd><p>This action causes a rollforward to occur, if a roll forward is
possible. Otherwise, it is insensitive.</p>
</dd></dl>
<dl class="function">
<dt id="Rollback">
<code class="descname">Rollback</code><span class="sig-paren">(</span><em>*args</em>, <em>force=&quot;menu&quot;</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Rollback" title="Permalink to this definition"> link</a></dt>
<dd><p>This action causes a rollback to occur, when a rollback is possible.
Otherwise, nothing happens.</p>
<p>The arguments are given to <a class="reference internal" href="save_load_rollback.html#renpy.rollback" title="renpy.rollback"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.rollback()</span></code></a>. This includes the
<cite>force</cite> argument which here defaults to &quot;menu&quot;.</p>
</dd></dl>
<dl class="function">
<dt id="RollbackToIdentifier">
<code class="descname">RollbackToIdentifier</code><span class="sig-paren">(</span><em>identifier</em><span class="sig-paren">)</span><a class="headerlink" href="#RollbackToIdentifier" title="Permalink to this definition"> link</a></dt>
<dd><p>This causes a rollback to an identifier to occur. Rollback
identifiers are returned as part of HistoryEntry objects.</p>
</dd></dl>
<dl class="function">
<dt id="Screenshot">
<code class="descname">Screenshot</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Screenshot" title="Permalink to this definition"> link</a></dt>
<dd><p>Takes a screenshot.</p>
</dd></dl>
<dl class="function">
<dt id="Scroll">
<code class="descname">Scroll</code><span class="sig-paren">(</span><em>id</em>, <em>direction</em>, <em>amount=u'step'</em><span class="sig-paren">)</span><a class="headerlink" href="#Scroll" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes a Bar, Viewport, or Vpgrid to scroll.</p>
<dl class="docutils">
<dt><cite>id</cite></dt>
<dd>The id of a bar, viewport, or vpgrid in the current screen.</dd>
<dt><cite>direction</cite></dt>
<dd>For a vbar, one of &quot;increase&quot; or &quot;decrease&quot;. For a viewport
or vpgrid, one of &quot;horizontal increase&quot;, &quot;vertical increase&quot;,
&quot;horizontal decrease&quot;, or &quot;vertical decrease&quot;.</dd>
<dt><cite>amount</cite></dt>
<dd>The amount to scroll by. This can be a number of pixels, or
else &quot;step&quot; or &quot;page&quot;.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="SelectedIf">
<code class="descname">SelectedIf</code><span class="sig-paren">(</span><em>expression</em><span class="sig-paren">)</span><a class="headerlink" href="#SelectedIf" title="Permalink to this definition"> link</a></dt>
<dd><p>This indicates that one action in a list of actions should be used
to determine if a button is selected. This only makes sense
when the button has a list of actions. For example:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="c1"># The button is selected only if mars_flag is True</span>
<span class="k">textbutton</span> <span class="s2">&quot;Marsopolis&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="p">[</span> <span class="n">SelectedIf</span><span class="p">(</span><span class="n">SetVariable</span><span class="p">(</span><span class="s2">&quot;mars_flag&quot;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)),</span> <span class="n">SetVariable</span><span class="p">(</span><span class="s2">&quot;on_mars&quot;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span> <span class="p">]</span>
</pre></div>
</div>
<p>The action inside SelectedIf is run normally when the button is clicked.</p>
</dd></dl>
<dl class="function">
<dt id="SensitiveIf">
<code class="descname">SensitiveIf</code><span class="sig-paren">(</span><em>expression</em><span class="sig-paren">)</span><a class="headerlink" href="#SensitiveIf" title="Permalink to this definition"> link</a></dt>
<dd><p>This indicates that one action in a list of actions should be used
to determine if a button is sensitive. This only makes sense
when the button has a list of actions. For example:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="c1"># The button is sensitive only if mars_flag is True</span>
<span class="k">textbutton</span> <span class="s2">&quot;Marsopolis&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="p">[</span> <span class="n">SensitiveIf</span><span class="p">(</span><span class="n">SetVariable</span><span class="p">(</span><span class="s2">&quot;mars_flag&quot;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)),</span> <span class="n">SetVariable</span><span class="p">(</span><span class="s2">&quot;on_mars&quot;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span> <span class="p">]</span>
</pre></div>
</div>
<p>The action inside SensitiveIf is run normally when the button is clicked.</p>
</dd></dl>
<dl class="function">
<dt id="Skip">
<code class="descname">Skip</code><span class="sig-paren">(</span><em>fast=False</em>, <em>confirm=False</em><span class="sig-paren">)</span><a class="headerlink" href="#Skip" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes the game to begin skipping. If the game is in a menu
context, then this returns to the game. Otherwise, it just
enables skipping.</p>
<dl class="docutils">
<dt><cite>fast</cite></dt>
<dd>If true, skips directly to the next menu choice.</dd>
<dt><cite>confirm</cite></dt>
<dd>If true, asks for confirmation before beginning skipping.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="With">
<code class="descname">With</code><span class="sig-paren">(</span><em>transition</em><span class="sig-paren">)</span><a class="headerlink" href="#With" title="Permalink to this definition"> link</a></dt>
<dd><p>Causes <cite>transition</cite> to occur.</p>
</dd></dl>
<p>Additional actions are available in other pages of this documentation, such
as <a class="reference internal" href="translation.html#Language" title="Language"><code class="xref py py-class docutils literal notranslate"><span class="pre">Language</span></code></a>, <a class="reference internal" href="rooms.html#Replay" title="Replay"><code class="xref py py-class docutils literal notranslate"><span class="pre">Replay</span></code></a> and <a class="reference internal" href="rooms.html#EndReplay" title="EndReplay"><code class="xref py py-class docutils literal notranslate"><span class="pre">EndReplay</span></code></a>,
<a class="reference internal" href="gui_advanced.html#gui.SetPreference" title="gui.SetPreference"><code class="xref py py-class docutils literal notranslate"><span class="pre">gui.SetPreference</span></code></a> and <a class="reference internal" href="gui_advanced.html#gui.TogglePreference" title="gui.TogglePreference"><code class="xref py py-class docutils literal notranslate"><span class="pre">gui.TogglePreference</span></code></a>,
<a class="reference internal" href="style.html#StylePreference" title="StylePreference"><code class="xref py py-class docutils literal notranslate"><span class="pre">StylePreference</span></code></a>, and the <span class="xref std std-ref">voice actions</span>.</p>
<p>Other actions can be created using the <a class="reference internal" href="screen_python.html#Action" title="Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a> class.</p>
</div>
</div>
<div class="section" id="bar-values">
<span id="id2"></span><h2>Bar Values<a class="headerlink" href="#bar-values" title="Permalink to this headline"> link</a></h2>
<p>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 <a class="reference internal" href="screen_python.html#BarValue" title="BarValue"><code class="xref py py-class docutils literal notranslate"><span class="pre">BarValue</span></code></a> class. All classes that have the <cite>step</cite> keyword also accept
the <cite>force_step</cite> keyword whose behavior is described in <a class="reference internal" href="screen_python.html#ui.adjustment" title="ui.adjustment"><code class="xref py py-func docutils literal notranslate"><span class="pre">ui.adjustment()</span></code></a>.</p>
<dl class="function">
<dt id="AnimatedValue">
<code class="descname">AnimatedValue</code><span class="sig-paren">(</span><em>value=0.0</em>, <em>range=1.0</em>, <em>delay=1.0</em>, <em>old_value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#AnimatedValue" title="Permalink to this definition"> link</a></dt>
<dd><p>This animates a value, taking <cite>delay</cite> seconds to vary the value from
<cite>old_value</cite> to <cite>value</cite>.</p>
<dl class="docutils">
<dt><cite>value</cite></dt>
<dd>The value itself, a number.</dd>
<dt><cite>range</cite></dt>
<dd>The range of the value, a number.</dd>
<dt><cite>delay</cite></dt>
<dd>The time it takes to animate the value, in seconds. Defaults
to 1.0.</dd>
<dt><cite>old_value</cite></dt>
<dd>The old value. If this is None, then the value is taken from the
AnimatedValue we replaced, if any. Otherwise, it is initialized
to <cite>value</cite>.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="AudioPositionValue">
<code class="descname">AudioPositionValue</code><span class="sig-paren">(</span><em>channel=u'music'</em>, <em>update_interval=0.1</em><span class="sig-paren">)</span><a class="headerlink" href="#AudioPositionValue" title="Permalink to this definition"> link</a></dt>
<dd><p>A value that shows the playback position of the audio file playing
in <cite>channel</cite>.</p>
<dl class="docutils">
<dt><cite>update_interval</cite></dt>
<dd>How often the value updates, in seconds.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="DictValue">
<code class="descname">DictValue</code><span class="sig-paren">(</span><em>dict</em>, <em>key</em>, <em>range</em>, <em>max_is_zero=False</em>, <em>style=u'bar'</em>, <em>offset=0</em>, <em>step=None</em>, <em>action=None</em>, <em>force_step=False</em><span class="sig-paren">)</span><a class="headerlink" href="#DictValue" title="Permalink to this definition"> link</a></dt>
<dd><p>A value that allows the user to adjust the value of a key
in a dict.</p>
<dl class="docutils">
<dt><cite>dict</cite></dt>
<dd>The dict.</dd>
<dt><cite>key</cite></dt>
<dd>The key.</dd>
<dt><cite>range</cite></dt>
<dd>The range to adjust over.</dd>
<dt><cite>max_is_zero</cite></dt>
<dd>If True, then when the value of a key is zero, the value of the
bar will be range, and all other values will be shifted down by 1.
This works both ways - when the bar is set to the maximum, the
value of a key is set to 0.</dd>
<dt><cite>style</cite></dt>
<dd>The styles of the bar created.</dd>
<dt><cite>offset</cite></dt>
<dd>An offset to add to the value.</dd>
<dt><cite>step</cite></dt>
<dd>The amount to change the bar by. If None, defaults to 1/10th of
the bar.</dd>
<dt><cite>action</cite></dt>
<dd>If not None, an action to call when the field has changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FieldValue">
<code class="descname">FieldValue</code><span class="sig-paren">(</span><em>object</em>, <em>field</em>, <em>range</em>, <em>max_is_zero=False</em>, <em>style=u'bar'</em>, <em>offset=0</em>, <em>step=None</em>, <em>action=None</em>, <em>force_step=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FieldValue" title="Permalink to this definition"> link</a></dt>
<dd><p>A bar value that allows the user to adjust the value of a field
on an object.</p>
<dl class="docutils">
<dt><cite>object</cite></dt>
<dd>The object.</dd>
<dt><cite>field</cite></dt>
<dd>The field, a string.</dd>
<dt><cite>range</cite></dt>
<dd>The range to adjust over.</dd>
<dt><cite>max_is_zero</cite></dt>
<dd><p class="first">If True, then when the field is zero, the value of the
bar will be range, and all other values will be shifted
down by 1. This works both ways - when the bar is set to
the maximum, the field is set to 0.</p>
<p class="last">This is used internally, for some preferences.</p>
</dd>
<dt><cite>style</cite></dt>
<dd>The styles of the bar created.</dd>
<dt><cite>offset</cite></dt>
<dd>An offset to add to the value.</dd>
<dt><cite>step</cite></dt>
<dd>The amount to change the bar by. If None, defaults to 1/10th of
the bar.</dd>
<dt><cite>action</cite></dt>
<dd>If not None, an action to call when the field has changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="MixerValue">
<code class="descname">MixerValue</code><span class="sig-paren">(</span><em>mixer</em><span class="sig-paren">)</span><a class="headerlink" href="#MixerValue" title="Permalink to this definition"> link</a></dt>
<dd><p>The value of an audio mixer.</p>
<dl class="docutils">
<dt><cite>mixer</cite></dt>
<dd>The name of the mixer to adjust. This is usually one of
&quot;main&quot;, &quot;music&quot;, &quot;sfx&quot;, or &quot;voice&quot;. See <a class="reference internal" href="audio.html#volume"><span class="std std-ref">Volume</span></a>
for more information.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ScreenVariableValue">
<code class="descname">ScreenVariableValue</code><span class="sig-paren">(</span><em>variable</em>, <em>range</em>, <em>max_is_zero=False</em>, <em>style=u'bar'</em>, <em>offset=0</em>, <em>step=None</em>, <em>action=None</em>, <em>force_step=False</em><span class="sig-paren">)</span><a class="headerlink" href="#ScreenVariableValue" title="Permalink to this definition"> link</a></dt>
<dd><p>A bar value that adjusts the value of a variable in a screen.</p>
<dl class="docutils">
<dt><cite>variable</cite></dt>
<dd>A string giving the name of the variable to adjust.</dd>
<dt><cite>range</cite></dt>
<dd>The range to adjust over.</dd>
<dt><cite>max_is_zero</cite></dt>
<dd><p class="first">If True, then when the field is zero, the value of the
bar will be range, and all other values will be shifted
down by 1. This works both ways - when the bar is set to
the maximum, the field is set to 0.</p>
<p class="last">This is used internally, for some preferences.</p>
</dd>
<dt><cite>style</cite></dt>
<dd>The styles of the bar created.</dd>
<dt><cite>offset</cite></dt>
<dd>An offset to add to the value.</dd>
<dt><cite>step</cite></dt>
<dd>The amount to change the bar by. If None, defaults to 1/10th of
the bar.</dd>
<dt><cite>action</cite></dt>
<dd>If not None, an action to call when the field has changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="StaticValue">
<code class="descname">StaticValue</code><span class="sig-paren">(</span><em>value=0.0</em>, <em>range=1.0</em><span class="sig-paren">)</span><a class="headerlink" href="#StaticValue" title="Permalink to this definition"> link</a></dt>
<dd><p>This allows a value to be specified statically.</p>
<dl class="docutils">
<dt><cite>value</cite></dt>
<dd>The value itself, a number.</dd>
<dt><cite>range</cite></dt>
<dd>The range of the value.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="VariableValue">
<code class="descname">VariableValue</code><span class="sig-paren">(</span><em>variable</em>, <em>range</em>, <em>max_is_zero=False</em>, <em>style=u'bar'</em>, <em>offset=0</em>, <em>step=None</em>, <em>action=None</em>, <em>force_step=False</em><span class="sig-paren">)</span><a class="headerlink" href="#VariableValue" title="Permalink to this definition"> link</a></dt>
<dd><p>A bar value that allows the user to adjust the value of a variable
in the default store.</p>
<dl class="docutils">
<dt><cite>variable</cite></dt>
<dd>A string giving the name of the variable to adjust.</dd>
<dt><cite>range</cite></dt>
<dd>The range to adjust over.</dd>
<dt><cite>max_is_zero</cite></dt>
<dd><p class="first">If True, then when the field is zero, the value of the
bar will be range, and all other values will be shifted
down by 1. This works both ways - when the bar is set to
the maximum, the field is set to 0.</p>
<p class="last">This is used internally, for some preferences.</p>
</dd>
<dt><cite>style</cite></dt>
<dd>The styles of the bar created.</dd>
<dt><cite>offset</cite></dt>
<dd>An offset to add to the value.</dd>
<dt><cite>step</cite></dt>
<dd>The amount to change the bar by. If None, defaults to 1/10th of
the bar.</dd>
<dt><cite>action</cite></dt>
<dd>If not None, an action to call when the field has changed.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="XScrollValue">
<code class="descname">XScrollValue</code><span class="sig-paren">(</span><em>viewport</em><span class="sig-paren">)</span><a class="headerlink" href="#XScrollValue" title="Permalink to this definition"> link</a></dt>
<dd><p>The value of an adjustment that horizontally scrolls the viewport with the
given id, on the current screen. The viewport must be defined before a bar
with this value is.</p>
</dd></dl>
<dl class="function">
<dt id="YScrollValue">
<code class="descname">YScrollValue</code><span class="sig-paren">(</span><em>viewport</em><span class="sig-paren">)</span><a class="headerlink" href="#YScrollValue" title="Permalink to this definition"> link</a></dt>
<dd><p>The value of an adjustment that vertically scrolls the viewport with the
given id, on the current screen. The viewport must be defined before a bar
with this value is.</p>
</dd></dl>
</div>
<div class="section" id="input-values">
<span id="id3"></span><h2>Input Values<a class="headerlink" href="#input-values" title="Permalink to this headline"> link</a></h2>
<p>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 <a class="reference internal" href="screen_python.html#InputValue" title="InputValue"><code class="xref py py-class docutils literal notranslate"><span class="pre">InputValue</span></code></a>
class.</p>
<p>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 <a class="reference internal" href="#DisableAllInputValues" title="DisableAllInputValues"><code class="xref py py-func docutils literal notranslate"><span class="pre">DisableAllInputValues()</span></code></a> action.</p>
<dl class="function">
<dt id="DictInputValue">
<code class="descname">DictInputValue</code><span class="sig-paren">(</span><em>dict</em>, <em>key</em>, <em>default=True</em>, <em>returnable=False</em><span class="sig-paren">)</span><a class="headerlink" href="#DictInputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>An input value that updates <cite>key</cite> in <cite>dict</cite>.</p>
<dl class="docutils">
<dt><cite>default</cite></dt>
<dd>If true, this input can be editable by default.</dd>
<dt><cite>returnable</cite></dt>
<dd>If true, the value of this input will be returned when the
user presses enter.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FieldInputValue">
<code class="descname">FieldInputValue</code><span class="sig-paren">(</span><em>object</em>, <em>field</em>, <em>default=True</em>, <em>returnable=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FieldInputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>An input value that updates <cite>field</cite> on <cite>object</cite>.</p>
<dl class="docutils">
<dt><cite>field</cite></dt>
<dd>A string giving the name of the field.</dd>
<dt><cite>default</cite></dt>
<dd>If true, this input can be editable by default.</dd>
<dt><cite>returnable</cite></dt>
<dd>If true, the value of this input will be returned when the
user presses enter.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FilePageNameInputValue">
<code class="descname">FilePageNameInputValue</code><span class="sig-paren">(</span><em>pattern=u'Page {}'</em>, <em>auto=u'Automatic saves'</em>, <em>quick=u'Quick saves'</em>, <em>page=None</em>, <em>default=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FilePageNameInputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>An input value that updates the name of a file page.</p>
<dl class="docutils">
<dt><cite>pattern</cite></dt>
<dd>This is used for the default name of a page. Python-style substition
is performed, such that {} is replaced with the number of the page.</dd>
<dt><cite>auto</cite></dt>
<dd>The name of the autosave page.</dd>
<dt><cite>quick</cite></dt>
<dd>The name of the quicksave page.</dd>
<dt><cite>page</cite></dt>
<dd>If given, the number of the page to display. This should usually
be left as None, to give the current page.</dd>
<dt><cite>default</cite></dt>
<dd>If true, this input can be editable by default.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="ScreenVariableInputValue">
<code class="descname">ScreenVariableInputValue</code><span class="sig-paren">(</span><em>variable</em>, <em>default=True</em>, <em>returnable=False</em><span class="sig-paren">)</span><a class="headerlink" href="#ScreenVariableInputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>An input value that updates variable.</p>
<dl class="docutils">
<dt><cite>variable</cite></dt>
<dd>A string giving the name of the variable to update.</dd>
<dt><cite>default</cite></dt>
<dd>If true, this input can be editable by default.</dd>
<dt><cite>returnable</cite></dt>
<dd>If true, the value of this input will be returned when the
user presses enter.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="VariableInputValue">
<code class="descname">VariableInputValue</code><span class="sig-paren">(</span><em>variable</em>, <em>default=True</em>, <em>returnable=False</em><span class="sig-paren">)</span><a class="headerlink" href="#VariableInputValue" title="Permalink to this definition"> link</a></dt>
<dd><p>An input value that updates <cite>variable</cite>.</p>
<dl class="docutils">
<dt><cite>variable</cite></dt>
<dd>A string giving the name of the variable to update.</dd>
<dt><cite>default</cite></dt>
<dd>If true, this input can be editable by default.</dd>
<dt><cite>returnable</cite></dt>
<dd>If true, the value of this input will be returned when the
user presses enter.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="functions-and-classes">
<h2>Functions and Classes<a class="headerlink" href="#functions-and-classes" title="Permalink to this headline"> link</a></h2>
<p>These functions and classes are useful in association with screens.</p>
<div class="section" id="preferences">
<h3>Preferences<a class="headerlink" href="#preferences" title="Permalink to this headline"> link</a></h3>
<p>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.</p>
<dl class="function">
<dt id="Preference">
<code class="descname">Preference</code><span class="sig-paren">(</span><em>name</em>, <em>value=None</em>, <em>range=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Preference" title="Permalink to this definition"> link</a></dt>
<dd><p>This constructs the appropriate action or value from a preference.
The preference name should be the name given in the standard
menus, while the value should be either the name of a choice,
&quot;toggle&quot; to cycle through choices, a specific value, or left off
in the case of buttons.</p>
<p>Actions that can be used with buttons and hotspots are:</p>
<ul class="simple">
<li>Preference(&quot;display&quot;, &quot;fullscreen&quot;) - displays in fullscreen mode.</li>
<li>Preference(&quot;display&quot;, &quot;window&quot;) - displays in windowed mode at 1x normal size.</li>
<li>Preference(&quot;display&quot;, 2.0) - displays in windowed mode at 2.0x normal size.</li>
<li>Preference(&quot;display&quot;, &quot;any window&quot;) - displays in windowed mode at the previous size.</li>
<li>Preference(&quot;display&quot;, &quot;toggle&quot;) - toggle display mode.</li>
<li>Preference(&quot;transitions&quot;, &quot;all&quot;) - show all transitions.</li>
<li>Preference(&quot;transitions&quot;, &quot;none&quot;) - do not show transitions.</li>
<li>Preference(&quot;transitions&quot;, &quot;toggle&quot;) - toggle transitions.</li>
<li>Preference(&quot;video sprites&quot;, &quot;show&quot;) - show all video sprites.</li>
<li>Preference(&quot;video sprites&quot;, &quot;hide&quot;) - fall back to images where possible.</li>
<li>Preference(&quot;video sprites&quot;, &quot;toggle&quot;) - toggle image fallback behavior.</li>
<li>Preference(&quot;show empty window&quot;, &quot;show&quot;) - Allow the &quot;window show&quot; and &quot;window auto&quot; statement to show an empty window outside of the say statement.</li>
<li>Preference(&quot;show empty window&quot;, &quot;hide&quot;) - Prevent the above.</li>
<li>Preference(&quot;show empty window&quot;, &quot;toggle&quot;) - Toggle the above.</li>
<li>Preference(&quot;text speed&quot;, 0) - make text appear instantaneously.</li>
<li>Preference(&quot;text speed&quot;, 142) - set text speed to 142 characters per second.</li>
<li>Preference(&quot;joystick&quot;) - Show the joystick preferences.</li>
<li>Preference(&quot;skip&quot;, &quot;seen&quot;) - Only skip seen messages.</li>
<li>Preference(&quot;skip&quot;, &quot;all&quot;) - Skip unseen messages.</li>
<li>Preference(&quot;skip&quot;, &quot;toggle&quot;) - Toggle between skip seen and skip all.</li>
<li>Preference(&quot;begin skipping&quot;) - Starts skipping.</li>
<li>Preference(&quot;after choices&quot;, &quot;skip&quot;) - Skip after choices.</li>
<li>Preference(&quot;after choices&quot;, &quot;stop&quot;) - Stop skipping after choices.</li>
<li>Preference(&quot;after choices&quot;, &quot;toggle&quot;) - Toggle skipping after choices.</li>
<li>Preference(&quot;auto-forward time&quot;, 0) - Set the auto-forward time to infinite.</li>
<li>Preference(&quot;auto-forward time&quot;, 10) - Set the auto-forward time (unit is seconds per 250 characters).</li>
<li>Preference(&quot;auto-forward&quot;, &quot;enable&quot;) - Enable auto-forward mode.</li>
<li>Preference(&quot;auto-forward&quot;, &quot;disable&quot;) - Disable auto-forward mode.</li>
<li>Preference(&quot;auto-forward&quot;, &quot;toggle&quot;) - Toggle auto-forward mode.</li>
<li>Preference(&quot;auto-forward after click&quot;, &quot;enable&quot;) - Remain in auto-forward mode after a click.</li>
<li>Preference(&quot;auto-forward after click&quot;, &quot;disable&quot;) - Disable auto-forward mode after a click.</li>
<li>Preference(&quot;auto-forward after click&quot;, &quot;toggle&quot;) - Toggle auto-forward after click.</li>
<li>Preference(&quot;automatic move&quot;, &quot;enable&quot;) - Enable automatic mouse mode.</li>
<li>Preference(&quot;automatic move&quot;, &quot;disable&quot;) - Disable automatic mouse mode.</li>
<li>Preference(&quot;automatic move&quot;, &quot;toggle&quot;) - Toggle automatic mouse mode.</li>
<li>Preference(&quot;wait for voice&quot;, &quot;enable&quot;) - Wait for the currently playing voice to complete before auto-forwarding.</li>
<li>Preference(&quot;wait for voice&quot;, &quot;disable&quot;) - Do not wait for the currently playing voice to complete before auto-forwarding.</li>
<li>Preference(&quot;wait for voice&quot;, &quot;toggle&quot;) - Toggle wait voice.</li>
<li>Preference(&quot;voice sustain&quot;, &quot;enable&quot;) - Sustain voice past the current interaction.</li>
<li>Preference(&quot;voice sustain&quot;, &quot;disable&quot;) - Don't sustain voice past the current interaction.</li>
<li>Preference(&quot;voice sustain&quot;, &quot;toggle&quot;) - Toggle voice sustain.</li>
<li>Preference(&quot;music mute&quot;, &quot;enable&quot;) - Mute the music mixer.</li>
<li>Preference(&quot;music mute&quot;, &quot;disable&quot;) - Un-mute the music mixer.</li>
<li>Preference(&quot;music mute&quot;, &quot;toggle&quot;) - Toggle music mute.</li>
<li>Preference(&quot;sound mute&quot;, &quot;enable&quot;) - Mute the sound mixer.</li>
<li>Preference(&quot;sound mute&quot;, &quot;disable&quot;) - Un-mute the sound mixer.</li>
<li>Preference(&quot;sound mute&quot;, &quot;toggle&quot;) - Toggle sound mute.</li>
<li>Preference(&quot;voice mute&quot;, &quot;enable&quot;) - Mute the voice mixer.</li>
<li>Preference(&quot;voice mute&quot;, &quot;disable&quot;) - Un-mute the voice mixer.</li>
<li>Preference(&quot;voice mute&quot;, &quot;toggle&quot;) - Toggle voice mute.</li>
<li>Preference(&quot;mixer &lt;mixer&gt; mute&quot;, &quot;enable&quot;) - Mute the specified mixer.</li>
<li>Preference(&quot;mixer &lt;mixer&gt; mute&quot;, &quot;disable&quot;) - Unmute the specified mixer.</li>
<li>Preference(&quot;mixer &lt;mixer&gt; mute&quot;, &quot;toggle&quot;) - Toggle mute of the specified mixer.</li>
<li>Preference(&quot;all mute&quot;, &quot;enable&quot;) - Mute each individual mixer.</li>
<li>Preference(&quot;all mute&quot;, &quot;disable&quot;) - Unmute each individual mixer.</li>
<li>Preference(&quot;all mute&quot;, &quot;toggle&quot;) - Toggle mute of each individual mixer.</li>
<li>Preference(&quot;main volume&quot;, 0.5) - Set the adjustment applied to all channels.</li>
<li>Preference(&quot;music volume&quot;, 0.5) - Set the music volume.</li>
<li>Preference(&quot;sound volume&quot;, 0.5) - Set the sound volume.</li>
<li>Preference(&quot;voice volume&quot;, 0.5) - Set the voice volume.</li>
<li>Preference(&quot;mixer &lt;mixer&gt; volume&quot;, 0.5) - Set the specified mixer volume.</li>
<li>Preference(&quot;emphasize audio&quot;, &quot;enable&quot;) - Emphasize the audio channels found in <a class="reference internal" href="config.html#var-config.emphasize_audio_channels"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.emphasize_audio_channels</span></code></a>.</li>
<li>Preference(&quot;emphasize audio&quot;, &quot;disable&quot;) - Do not emphasize audio channels.</li>
<li>Preference(&quot;emphasize audio&quot;, &quot;toggle&quot;) - Toggle emphasize audio.</li>
<li>Preference(&quot;self voicing&quot;, &quot;enable&quot;) - Enables self-voicing.</li>
<li>Preference(&quot;self voicing&quot;, &quot;disable&quot;) - Disable self-voicing.</li>
<li>Preference(&quot;self voicing&quot;, &quot;toggle&quot;) - Toggles self-voicing.</li>
<li>Preference(&quot;self voicing volume drop&quot;, 0.5) - Drops the volume of non-voice mixers when self voicing is active.</li>
<li>Preference(&quot;clipboard voicing&quot;, &quot;enable&quot;) - Enables clipboard-voicing.</li>
<li>Preference(&quot;clipboard voicing&quot;, &quot;disable&quot;) - Disable clipboard-voicing.</li>
<li>Preference(&quot;clipboard voicing&quot;, &quot;toggle&quot;) - Toggles clipboard-voicing.</li>
<li>Preference(&quot;debug voicing&quot;, &quot;enable&quot;) - Enables self-voicing debug</li>
<li>Preference(&quot;debug voicing&quot;, &quot;disable&quot;) - Disable self-voicing debug.</li>
<li>Preference(&quot;debug voicing&quot;, &quot;toggle&quot;) - Toggles self-voicing debug.</li>
<li>Preference(&quot;rollback side&quot;, &quot;left&quot;) - Touching the left side of the screen causes rollback.</li>
<li>Preference(&quot;rollback side&quot;, &quot;right&quot;) - Touching the right side of the screen causes rollback.</li>
<li>Preference(&quot;rollback side&quot;, &quot;disable&quot;) - Touching the screen will not cause rollback.</li>
<li>Preference(&quot;gl powersave&quot;, True) - Drop framerate to allow for power savings.</li>
<li>Preference(&quot;gl powersave&quot;, False) - Do not drop framerate to allow for power savings.</li>
<li>Preference(&quot;gl powersave&quot;, &quot;auto&quot;) - Enable powersave when running on battery.</li>
<li>Preference(&quot;gl framerate&quot;, None) - Runs at the display framerate.</li>
<li>Preference(&quot;gl framerate&quot;, 60) - Runs at the given framerate.</li>
<li>Preference(&quot;gl tearing&quot;, True) - Tears rather than skipping frames.</li>
<li>Preference(&quot;gl tearing&quot;, False) - Skips frames rather than tearing.</li>
<li>Preference(&quot;font transform&quot;, &quot;opendyslexic&quot;) - Sets the accessibility font transform to opendyslexic.</li>
<li>Preference(&quot;font transform&quot;, &quot;dejavusans&quot;) - Sets the accessibility font transform to deja vu sans.</li>
<li>Preference(&quot;font transform&quot;, None) - Disables the accessibility font transform.</li>
<li>Preference(&quot;font size&quot;, 1.0) - Sets the accessibility font size scaling factor.</li>
<li>Preference(&quot;font line spacing&quot;, 1.0) - Sets the accessibility font vertical spacing scaling factor.</li>
<li>Preference(&quot;system cursor&quot;, &quot;enable&quot;) - Use system cursor ignoring config.mouse.</li>
<li>Preference(&quot;system cursor&quot;, &quot;disable&quot;) - Use cursor defined in config.mouse.</li>
<li>Preference(&quot;system cursor&quot;, &quot;toggle&quot;) - Toggle system cursor.</li>
<li>Preference(&quot;high contrast text&quot;, &quot;enable&quot;) - Enables white text on a black background.</li>
<li>Preference(&quot;high contrast text&quot;, &quot;disable&quot;) - Disables high contrast text.</li>
<li>Preference(&quot;high contrast text&quot;, &quot;toggle&quot;) - Toggles high contrast text.</li>
<li>Preference(&quot;audio when minimized&quot;, &quot;enable&quot;) - Enable sounds playing when the window is not in focus.</li>
<li>Preference(&quot;audio when minimized&quot;, &quot;disable&quot;) - Disable sounds playing when the window is not in focus.</li>
<li>Preference(&quot;audio when minimized&quot;, &quot;toggle&quot;) - Toggle sounds playing when the window is not in focus.</li>
</ul>
<p>Values that can be used with bars are:</p>
<ul class="simple">
<li>Preference(&quot;text speed&quot;)</li>
<li>Preference(&quot;auto-forward time&quot;)</li>
<li>Preference(&quot;main volume&quot;)</li>
<li>Preference(&quot;music volume&quot;)</li>
<li>Preference(&quot;sound volume&quot;)</li>
<li>Preference(&quot;voice volume&quot;)</li>
<li>Preference(&quot;mixer &lt;mixer&gt; volume&quot;)</li>
<li>Preference(&quot;self voicing volume drop&quot;)</li>
<li>Preference(&quot;font size&quot;)</li>
<li>Preference(&quot;font line spacing&quot;)</li>
</ul>
<p>The <cite>range</cite> parameter can be given to give the range of certain bars.
For &quot;text speed&quot;, it defaults to 200 cps. For &quot;auto-forward time&quot;, it
defaults to 30.0 seconds per chunk of text. (These are maximums, not
defaults.)</p>
<p>Actions that can be used with buttons are:</p>
<ul class="simple">
<li>Preference(&quot;renderer menu&quot;) - Show the renderer menu.</li>
<li>Preference(&quot;accessibility menu&quot;) - Show the accessibility menu.</li>
</ul>
<p>These screens are intended for internal use, and are not customizable.</p>
</dd></dl>
<dl class="function">
<dt id="GetCharacterVolume">
<code class="descname">GetCharacterVolume</code><span class="sig-paren">(</span><em>voice_tag</em><span class="sig-paren">)</span><a class="headerlink" href="#GetCharacterVolume" title="Permalink to this definition"> link</a></dt>
<dd><p>This returns the volume associated with voice tag, a number
between 0.0 and 1.0, which is interpreted as a fraction of the
mixer volume for the <cite>voice</cite> channel.</p>
</dd></dl>
</div>
<div class="section" id="gamepad">
<h3>Gamepad<a class="headerlink" href="#gamepad" title="Permalink to this headline"> link</a></h3>
<p>These functions and actions work with the gamepad.</p>
<dl class="function">
<dt id="GamepadCalibrate">
<code class="descname">GamepadCalibrate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#GamepadCalibrate" title="Permalink to this definition"> link</a></dt>
<dd><p>An action that invokes the gamepad calibration routine.</p>
</dd></dl>
<dl class="function">
<dt id="GamepadExists">
<code class="descname">GamepadExists</code><span class="sig-paren">(</span><em>developer=True</em><span class="sig-paren">)</span><a class="headerlink" href="#GamepadExists" title="Permalink to this definition"> link</a></dt>
<dd><p>A function that returns true if a gamepad is present, and false otherwise.</p>
<dl class="docutils">
<dt><cite>developer</cite></dt>
<dd>Forces this function to always return true while <a class="reference internal" href="config.html#var-config.developer"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.developer</span></code></a>
is true.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="file-functions">
<h3>File Functions<a class="headerlink" href="#file-functions" title="Permalink to this headline"> link</a></h3>
<p>These functions return useful information about files. They use the
same default page as the file actions.</p>
<dl class="function">
<dt id="FileCurrentPage">
<code class="descname">FileCurrentPage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#FileCurrentPage" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the current file page as a string.</p>
</dd></dl>
<dl class="function">
<dt id="FileCurrentScreenshot">
<code class="descname">FileCurrentScreenshot</code><span class="sig-paren">(</span><em>empty=None</em>, <em>**properties</em><span class="sig-paren">)</span><a class="headerlink" href="#FileCurrentScreenshot" title="Permalink to this definition"> link</a></dt>
<dd><p>A displayable that shows the screenshot that will be saved with the current
file, if a screenshot has been taken when entering a menu or with
<a class="reference internal" href="#FileTakeScreenshot" title="FileTakeScreenshot"><code class="xref py py-func docutils literal notranslate"><span class="pre">FileTakeScreenshot()</span></code></a>.</p>
<p>If there is no current screenshot, <cite>empty</cite> is shown in its place. (If <cite>empty</cite> is
None, it defaults to <a class="reference internal" href="displayables.html#Null" title="Null"><code class="xref py py-func docutils literal notranslate"><span class="pre">Null()</span></code></a>.)</p>
</dd></dl>
<dl class="function">
<dt id="FileJson">
<code class="descname">FileJson</code><span class="sig-paren">(</span><em>name</em>, <em>key=None</em>, <em>empty=None</em>, <em>missing=None</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileJson" title="Permalink to this definition"> link</a></dt>
<dd><p>Accesses the Json information associated with <cite>name</cite>.</p>
<p>This always returns <cite>empty</cite> if the slot is empty.</p>
<p>If not, and if <cite>key</cite> is None, returns the entire dictionary containing the Json data.</p>
<p>Otherwise, this returns json[key] if <cite>key</cite> is defined on the json object of the save,
and <cite>missing</cite> if there is a save with the given name, but it does not contain <cite>key</cite>.</p>
<p>Such Json data is added to a save slot by callbacks registered using
<a class="reference internal" href="config.html#var-config.save_json_callbacks"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.save_json_callbacks</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="FileLoadable">
<code class="descname">FileLoadable</code><span class="sig-paren">(</span><em>name</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileLoadable" title="Permalink to this definition"> link</a></dt>
<dd><p>This is a function that returns true
if the file is loadable, and false otherwise.</p>
</dd></dl>
<dl class="function">
<dt id="FileNewest">
<code class="descname">FileNewest</code><span class="sig-paren">(</span><em>name</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileNewest" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns True if this is the newest file slot, or False otherwise.</p>
</dd></dl>
<dl class="function">
<dt id="FilePageName">
<code class="descname">FilePageName</code><span class="sig-paren">(</span><em>auto=u'a'</em>, <em>quick=u'q'</em><span class="sig-paren">)</span><a class="headerlink" href="#FilePageName" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the name of the current file page, as a string. If a normal
page, this returns the page number. Otherwise, it returns
<cite>auto</cite> or <cite>quick</cite>.</p>
</dd></dl>
<dl class="function">
<dt id="FileSaveName">
<code class="descname">FileSaveName</code><span class="sig-paren">(</span><em>name</em>, <em>empty=u''</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileSaveName" title="Permalink to this definition"> link</a></dt>
<dd><p>Return the save_name that was in effect when the file was saved,
or <cite>empty</cite> if the file does not exist.</p>
</dd></dl>
<dl class="function">
<dt id="FileScreenshot">
<code class="descname">FileScreenshot</code><span class="sig-paren">(</span><em>name</em>, <em>empty=None</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileScreenshot" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the screenshot associated with the given file. If the
file is not loadable, then <cite>empty</cite> is returned, unless it's None,
in which case, a Null displayable is created.</p>
<p>The return value is a displayable.</p>
</dd></dl>
<dl class="function">
<dt id="FileSlotName">
<code class="descname">FileSlotName</code><span class="sig-paren">(</span><em>slot</em>, <em>slots_per_page</em>, <em>auto=u'a'</em>, <em>quick=u'q'</em>, <em>format=u'%s%d'</em><span class="sig-paren">)</span><a class="headerlink" href="#FileSlotName" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the name of the numbered slot. This assumes that slots on
normal pages are numbered in a linear order starting with 1, and
that page numbers start with 1. When slot is 2, and slots_per_page
is 10, and the other variables are the defaults:</p>
<ul class="simple">
<li>When the first page is showing, this returns &quot;2&quot;.</li>
<li>When the second page is showing, this returns &quot;12&quot;.</li>
<li>When the auto page is showing, this returns &quot;a2&quot;.</li>
<li>When the quicksave page is showing, this returns &quot;q2&quot;.</li>
</ul>
<dl class="docutils">
<dt><cite>slot</cite></dt>
<dd>The number of the slot to access.</dd>
<dt><cite>slots_per_page</cite></dt>
<dd>The number of slots per page.</dd>
<dt><cite>auto</cite></dt>
<dd>A prefix to use for the auto page.</dd>
<dt><cite>quick</cite></dt>
<dd>A prefix to use for the quick page.</dd>
<dt><cite>format</cite></dt>
<dd>The formatting code to use. This is given two arguments: A string
giving the page prefix, and an integer giving the slot number.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="FileTime">
<code class="descname">FileTime</code><span class="sig-paren">(</span><em>name</em>, <em>format=u'%b %d</em>, <em>%H:%M'</em>, <em>empty=u''</em>, <em>page=None</em>, <em>slot=False</em><span class="sig-paren">)</span><a class="headerlink" href="#FileTime" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the time the file was saved, formatted according
to the supplied <cite>format</cite>. If the file is not found, <cite>empty</cite> is
returned.</p>
<p>The return value is a string.</p>
</dd></dl>
<dl class="function">
<dt id="FileUsedSlots">
<code class="descname">FileUsedSlots</code><span class="sig-paren">(</span><em>page=None</em>, <em>highest_first=True</em><span class="sig-paren">)</span><a class="headerlink" href="#FileUsedSlots" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns a list of used numeric file slots on the page.</p>
<dl class="docutils">
<dt><cite>page</cite></dt>
<dd>The name of the page that will be scanned. If None, the current page
is used.</dd>
<dt><cite>highest_first</cite></dt>
<dd>If true, the highest-numbered file slot is listed first.
Otherwise, the lowest-numbered slot is listed first.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="side-image-functions">
<h3>Side Image Functions<a class="headerlink" href="#side-image-functions" title="Permalink to this headline"> link</a></h3>
<p>This function returns the side image to use.</p>
<dl class="function">
<dt id="SideImage">
<code class="descname">SideImage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#SideImage" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the side image associated with the currently speaking character,
or a Null displayable if no such side image exists.</p>
</dd></dl>
</div>
<div class="section" id="tooltips">
<span id="id4"></span><h3>Tooltips<a class="headerlink" href="#tooltips" title="Permalink to this headline"> link</a></h3>
<p>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.</p>
<p>Here's an example:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">screen</span> <span class="n">tooltip_example</span><span class="p">():</span>
<span class="k">vbox</span><span class="p">:</span>
<span class="k">textbutton</span> <span class="s2">&quot;North&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;n&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;To meet a polar bear.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;South&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;s&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;All the way to the tropics.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;East&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;e&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;So we can embrace the dawn.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;West&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;Where to go to see the best sunsets.&quot;</span>
<span class="k">$</span> <span class="na">tooltip</span> <span class="o">=</span> <span class="n">GetTooltip</span><span class="p">()</span>
<span class="k">if</span> <span class="na">tooltip</span><span class="p">:</span>
<span class="k">text</span> <span class="s2">&quot;[tooltip]&quot;</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="screens.html#sl-nearrect"><span class="std std-ref">Nearrect</span></a> displayable can be used to display &quot;popup-style&quot; tooltips,
and has support for a special &quot;tooltip&quot; focus name, that is set to the location
of the last focus that set a tooltip:</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">screen</span> <span class="n">tooltip_example2</span><span class="p">():</span>
<span class="k">frame</span><span class="p">:</span>
<span class="na">padding</span> <span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="na">align</span> <span class="p">(</span><span class="o">.</span><span class="mi">5</span><span class="p">,</span> <span class="o">.</span><span class="mi">3</span><span class="p">)</span>
<span class="k">has</span> <span class="k">vbox</span>
<span class="k">textbutton</span> <span class="s2">&quot;North&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;n&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;To meet a polar bear.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;South&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;s&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;All the way to the tropics.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;East&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;e&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;So we can embrace the dawn.&quot;</span>
<span class="k">textbutton</span> <span class="s2">&quot;West&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
<span class="na">tooltip</span> <span class="s2">&quot;Where to go to see the best sunsets.&quot;</span>
<span class="c1"># This has to be the last thing shown in the screen.</span>
<span class="k">$</span> <span class="na">tooltip</span> <span class="o">=</span> <span class="n">GetTooltip</span><span class="p">()</span>
<span class="k">if</span> <span class="na">tooltip</span><span class="p">:</span>
<span class="k">nearrect</span><span class="p">:</span>
<span class="na">focus</span> <span class="s2">&quot;tooltip&quot;</span>
<span class="na">prefer_top</span> <span class="kc">True</span>
<span class="k">frame</span><span class="p">:</span>
<span class="na">xalign</span> <span class="mf">0.5</span>
<span class="k">text</span> <span class="na">tooltip</span>
</pre></div>
</div>
<dl class="function">
<dt id="GetTooltip">
<code class="descname">GetTooltip</code><span class="sig-paren">(</span><em>screen=None</em>, <em>last=False</em><span class="sig-paren">)</span><a class="headerlink" href="#GetTooltip" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns the tooltip of the currently focused displayable, or None
if no displayable is focused.</p>
<dl class="docutils">
<dt><cite>screen</cite></dt>
<dd>If not None, this should be the name or tag of a screen. If
given, this function only returns the tooltip if the focused
displayable is part of the screen.</dd>
<dt><cite>last</cite></dt>
<dd>If true, returns the last non-None value this function would
have returned.</dd>
</dl>
</dd></dl>
<div class="section" id="legacy">
<h4>Legacy<a class="headerlink" href="#legacy" title="Permalink to this headline"> link</a></h4>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This has been obsoleted by the above, but you might see it in older projects.</p>
</div>
<p>The tooltip class changes the screen when a button is hovered.</p>
<dl class="class">
<dt id="Tooltip">
<em class="property">class </em><code class="descname">Tooltip</code><span class="sig-paren">(</span><em>default</em><span class="sig-paren">)</span><a class="headerlink" href="#Tooltip" title="Permalink to this definition"> link</a></dt>
<dd><p>A tooltip object can be used to define a portion of a screen that is
updated when the mouse hovers an area.</p>
<p>A tooltip object has a <code class="docutils literal notranslate"><span class="pre">value</span></code> field, which is set to the <cite>default</cite>
value passed to the constructor when the tooltip is created. When
a button using an action created by the tooltip is hovered, the
value field changes to the value associated with the action.</p>
<dl class="method">
<dt id="Tooltip.Action">
<code class="descname">Action</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#Tooltip.Action" title="Permalink to this definition"> link</a></dt>
<dd><p>Returns an action that is generally used as the hovered property
of a button. When the button is hovered, the value field of this
tooltip is set to <cite>value</cite>. When the button loses focus, the
value field of this tooltip reverts to the default.</p>
</dd></dl>
</dd></dl>
<p>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.</p>
<p>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.</p>
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">screen</span> <span class="n">tooltip_test</span><span class="p">:</span>
<span class="k">default</span> <span class="n">tt</span> <span class="o">=</span> <span class="n">Tooltip</span><span class="p">(</span><span class="s2">&quot;No button selected.&quot;</span><span class="p">)</span>
<span class="k">frame</span><span class="p">:</span>
<span class="na">xfill</span> <span class="kc">True</span>
<span class="k">has</span> <span class="k">vbox</span>
<span class="k">textbutton</span> <span class="s2">&quot;One.&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="na">hovered</span> <span class="n">tt</span><span class="o">.</span><span class="n">Action</span><span class="p">(</span><span class="s2">&quot;The loneliest number.&quot;</span><span class="p">)</span>
<span class="k">textbutton</span> <span class="s2">&quot;Two.&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="na">hovered</span> <span class="n">tt</span><span class="o">.</span><span class="n">Action</span><span class="p">(</span><span class="s2">&quot;Is what it takes.&quot;</span><span class="p">)</span>
<span class="k">textbutton</span> <span class="s2">&quot;Three.&quot;</span><span class="p">:</span>
<span class="na">action</span> <span class="n">Return</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="na">hovered</span> <span class="n">tt</span><span class="o">.</span><span class="n">Action</span><span class="p">(</span><span class="s2">&quot;A crowd.&quot;</span><span class="p">)</span>
<span class="k">text</span> <span class="n">tt</span><span class="o">.</span><span class="na">value</span>
</pre></div>
</div>
</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