1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<html><head><title>Style Customization - Ren'Py Visual Novel Engine</title><link href="../shared.css" rel="stylesheet"><link href="../monobook.css" rel="stylesheet"><link href="../common.css" rel="stylesheet"><link href="../monobook2.css" rel="stylesheet"><link href="../docs.css" rel="stylesheet" /></link></link></link></link></head><body><div id="bodyContent">
<p class="docnav"><a href="../index.html">documentation index</a></p><table class="toc" id="toc" summary="Contents">
<tr>
<td>
<div id="toctitle">
<h2>Contents</h2>
</div>
<ul>
<li class="toclevel-1"><a href="#Style_Customization_Tutorial"><span class="tocnumber">1</span> <span class="toctext">Style Customization Tutorial</span></a>
<ul>
<li class="toclevel-2"><a href="#Common_Style_Customizations"><span class="tocnumber">1.1</span> <span class="toctext">Common Style Customizations</span></a></li>
<li class="toclevel-2"><a href="#Customize_Any_Style"><span class="tocnumber">1.2</span> <span class="toctext">Customize Any Style</span></a>
<ul>
<li class="toclevel-3"><a href="#Style_Inspector"><span class="tocnumber">1.2.1</span> <span class="toctext">Style Inspector</span></a></li>
<li class="toclevel-3"><a href="#Style_Hierarchy"><span class="tocnumber">1.2.2</span> <span class="toctext">Style Hierarchy</span></a>
<ul>
<li class="toclevel-4"><a href="#layout.button_menu"><span class="tocnumber">1.2.2.1</span> <span class="toctext">layout.button_menu</span></a></li>
</ul>
</li>
<li class="toclevel-3"><a href="#Style_Indexing_and_Inheritance"><span class="tocnumber">1.2.3</span> <span class="toctext">Style Indexing and Inheritance</span></a></li>
<li class="toclevel-3"><a href="#Setting_Style_Properties"><span class="tocnumber">1.2.4</span> <span class="toctext">Setting Style Properties</span></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</td>
</tr>
</table>
<script type="text/javascript">
//
if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); }
//
</script>
<p><a id="Style_Customization_Tutorial" name="Style_Customization_Tutorial"></a></p>
<h1><span class="mw-headline">Style Customization Tutorial</span></h1>
<p>By default, Ren'Py games are made with a usable but relatively generic style. The purpose of this tutorial is to teach you how to customize the Ren'Py style system to make your game more attractive.</p>
<p>Before we start, we should note that the style system is only one way to customize your game, and may not be able to accomplish all customizations.</p>
<ul>
<li><a href="../reference/Layouts.html" title="renpy/doc/reference/Layouts">Layouts</a> define the basic look of the various main and game menu screens, such as what buttons and other displayables are present. There are several built-in layouts, including imagemap-based layouts, and it's possible to write your own.</li>
<li><a href="../reference/Themes.html" title="renpy/doc/reference/Themes">Themes</a> handle the largest changes to the style system, defining consistent looks along many styles.</li>
<li>Once you have chosen your layout and theme, you can further tweak the look of your game using the style system.</li>
</ul>
<p>This tutorial is divided into two parts. The first part gives canned recipes for the most common style customizations. The second part explains how to customize any style and style property in the system, using the style inspector and style tree tools.</p>
<p><a id="Common_Style_Customizations" name="Common_Style_Customizations"></a></p>
<h2><span class="mw-headline">Common Style Customizations</span></h2>
<p><a id="Customize_Any_Style" name="Customize_Any_Style"></a></p>
<h2><span class="mw-headline">Customize Any Style</span></h2>
<p>The first thing one needs to do to when customizing styles is to determine which style it is you really want to customize. The easiest way to do this is to use the style inspector. It's also possible to use the style heirarchy tool to determine styles.</p>
<p><a id="Style_Inspector" name="Style_Inspector"></a></p>
<h3><span class="mw-headline">Style Inspector</span></h3>
<p>To use the style inspector, place the mouse over any element in the game, and press <tt>shift+I</tt>. If nothing happens, then set <a href="../reference/Configuration_Variables#config.developer" title="renpy/doc/reference/Configuration Variables">config.developer</a> to True, and restart your game. Otherwise, a screen similar to the following will pop up, showing the styles and Displayables underneath the mouse.</p>
<p><a class="image" href="/wiki/File:Style_Inspector.png.html" title="Style Inspector.png"><img alt="" border="0" height="480" src="../images/640px-Style_Inspector.png" width="640" /></a></p>
<p>This screenshot was created by hovering over the "Start Game" button on the demo game main menu, and pressing <tt>shift+I</tt>.</p>
<p>Each line contains the following three fields:</p>
<ol>
<li>The kind of displayable that is being shown.</li>
<li>The name of the style that is being used by that displayable.</li>
<li>The size of the displayable.</li>
</ol>
<p>The lines are arrange in the order that things are drawn on the screen, so that the first line is the farthest from the user, and the last line is closest to the user. Indentation is used to represent nesting of displayables. Such nesting may affect the positioning of the various displayables.</p>
<p><a id="Style_Hierarchy" name="Style_Hierarchy"></a></p>
<h3><span class="mw-headline">Style Hierarchy</span></h3>
<p>Styles may inherit from each other. The precise nature of style inheritance varies based on the layouts and themes that are being used. For a full accounting of styles the system knows about, hit <tt>shift+D</tt> and choose "Style Hierarchy". This will display a list of styles that the system knows about.</p>
<p>The styles that can be expected by all games to exist are:</p>
<ul>
<li><span id="default"><b>style.default</b> (Everything)</span> — The root of the style hierarchy. It must have a value for all style properties, and all properties take their default value from here.
<ul>
<li><span id="bar"><b>style.bar</b> (Bar)</span> — Horizontal bars intended to convey information without allowing the user to adjust their value.</li>
<li><span id="button"><b>style.button</b> (Button)</span> — Normal sized buttons.
<ul>
<li><span id="small_button"><b>style.small_button</b> (Button)</span> — Smaller than normal buttons.</li>
</ul>
</li>
<li><span id="button_text"><b>style.button_text</b> (Text)</span> — Text inside buttons.
<ul>
<li><span id="small_button_text"><b>style.small_button_text</b> (Text)</span> — Text inside smaller than normal buttons.</li>
</ul>
</li>
<li><span id="centered_text"><b>style.centered_text</b> (Text)</span> — Text displayed by the pre-defined centered character.</li>
<li><span id="centered_window"><b>style.centered_window</b> (Window)</span> — Window containing text displayed by the pre-defined centered character.</li>
<li><span id="frame"><b>style.frame</b> (Window)</span> — Frames are windows intended to contain buttons, labels, and other ui components. Used by default by <a href="../reference/functions/ui.frame.html" title="renpy/doc/reference/functions/ui.frame">ui.frame</a>.
<ul>
<li><span id="menu_frame"><b>style.menu_frame</b> (Window)</span> — Frames that are part of the main or game menus.</li>
</ul>
</li>
<li><span id="gm_root"><b>style.gm_root</b> (Window)</span> — An empty Window placed at the root of the game menu.</li>
<li><span id="hbox"><b>style.hbox</b> (Box)</span> — A box that lays out its children from left to right.</li>
<li><span id="hyperlink_text"><b>style.hyperlink_text</b> (Text)</span> — Hyperlinked text, using the {a} text tag.</li>
<li><span id="image_button"><b>style.image_button</b> (Button)</span> — <a href="../reference/functions/ui.imagebutton.html" title="renpy/doc/reference/functions/ui.imagebutton">ui.imagebuttons</a>.</li>
<li><span id="input_prompt"><b>style.input_prompt</b> (Text)</span> — Prompt text used by <a href="../reference/functions/renpy.input.html" title="renpy/doc/reference/functions/renpy.input">renpy.input</a>.</li>
<li><span id="input_text"><b>style.input_text</b> (Input)</span> — Input fields produced by <a href="../reference/functions/renpy.input.html" title="renpy/doc/reference/functions/renpy.input">renpy.input</a> and <a href="../reference/functions/ui.input.html" title="renpy/doc/reference/functions/ui.input">ui.input</a>.</li>
<li><span id="label"><b>style.label</b> (Window)</span> — Window surrounding the text of a label. Labels are small amounts of text used in the game menu.</li>
<li><span id="label_text"><b>style.label_text</b> (Text)</span> — The text of a label.</li>
<li><span id="large_button"><b>style.large_button</b> (Button)</span> — A large button, like those used for slots in the file picker.</li>
<li><span id="large_button_text"><b>style.large_button_text</b> (Text)</span> — Text used by large buttons.</li>
<li><span id="menu"><b>style.menu</b> (Box)</span> — Box containing an in-game menu, like those shown using the menu statement.</li>
<li><span id="menu_caption"><b>style.menu_caption</b> (Text)</span> — Text of a caption used in an in-game menu.</li>
<li><span id="menu_choice"><b>style.menu_choice</b> (Text)</span> — Text of a menu choice.
<ul>
<li><span id="menu_choice_chosen"><b>style.menu_choice_chosen</b> (Text)</span> — Text of a menu choice that has been chosen in some earlier game.</li>
</ul>
</li>
<li><span id="menu_choice_button"><b>style.menu_choice_button</b> (Button)</span> — Button containing a menu choice.
<ul>
<li><span id="menu_choice_chosen_button"><b>style.menu_choice_chosen_button</b> (Button)</span> — Button containing a menu choice that has been chosen in some earlier game.</li>
</ul>
</li>
<li><span id="menu_window"><b>style.menu_window</b> (Window)</span> — Window containing an in-game menu.</li>
<li><span id="mm_root"><b>style.mm_root</b> (Window)</span> — Empty window shown at the root of the main menu.</li>
<li><span id="prompt"><b>style.prompt</b> (Window)</span> — A window containing prompt text. Prompt text is used in the game menu, and is generally longer than label text.</li>
<li><span id="prompt_text"><b>style.prompt_text</b> (Text)</span> — Prompt text.</li>
<li><span id="say_dialogue"><b>style.say_dialogue</b> (Text)</span> — Dialogue in the say statement.</li>
<li><span id="say_label"><b>style.say_label</b> (Text)</span> — The name of the character speaking in the say statement.</li>
<li><span id="say_thought"><b>style.say_thought</b> (Text)</span> — Dialogue spoken by the default <tt>narrator</tt>.</li>
<li><span id="scrollbar"><b>style.scrollbar</b> (Bar)</span> — Horizontal scrollbars thay may or may not be intended to be adjusted by the user.</li>
<li><span id="slider"><b>style.slider</b> (Bar)</span> — Horizontal bars that are intended to be adjusted by the user.</li>
<li><span id="vbar"><b>style.vbar</b> (Bar)</span> — Vertical bars intended to convey information without allowing the user to adjust their value.</li>
<li><span id="vbox"><b>style.vbox</b> (Box)</span> — A box that lays out its children from top to bottom.</li>
<li><span id="vscrollbar"><b>style.vscrollbar</b> (Bar)</span> — Vertical scrollbars thay may or may not be intended to be adjusted by the user.</li>
<li><span id="vslider"><b>style.vslider</b> (Bar)</span> — Vertical bars that are intended to be adjusted by the user.</li>
<li><span id="window"><b>style.window</b> (Window)</span> — Window that's used to show dialogue and other in-game text.</li>
</ul>
</li>
</ul>
<p><a id="layout.button_menu" name="layout.button_menu"></a></p>
<h4><span class="mw-headline">layout.button_menu</span></h4>
<p>Invoking <a href="../reference/functions/layout.button_menu.html" title="renpy/doc/reference/functions/layout.button menu">layout.button_menu</a>, as the default game template does, makes a couple of changes to the default style hierarchy.</p>
<ul>
<li><b>menu_choice</b> is reparented to <b>button_text</b>.</li>
<li><b>menu_choice_button</b> is reparented to <b>button</b>.</li>
</ul>
<p>This makes menu choices look like buttons.</p>
<p><a id="Style_Indexing_and_Inheritance" name="Style_Indexing_and_Inheritance"></a></p>
<h3><span class="mw-headline">Style Indexing and Inheritance</span></h3>
<p>Some styles used by the game may be index. For example, the style mm_button[u"Start Game"] is the style mm_button indexed with the string u"Start Game". Indexing is used to specifically customize a single button or label.</p>
<p>According to the style hierarchy tool, the default inheritance hierarchy for the mm_button style is:</p>
<ol>
<li>mm_button</li>
<li>button</li>
<li>default</li>
</ol>
<p>When indexed with u"Start Game", it becomes.</p>
<ol>
<li>mm_button[u"Start Game"]</li>
<li>mm_button</li>
<li>button[u"Start Game"]</li>
<li>button</li>
<li>default[u"Start Game"]</li>
<li>default</li>
</ol>
<p>Ren'Py will look at styles in this order until it finds the first style in which a value for the property is defined.</p>
<p><a id="Setting_Style_Properties" name="Setting_Style_Properties"></a></p>
<h3><span class="mw-headline">Setting Style Properties</span></h3>
<p>Each displayable is in one of two roles, <b>selected</b> or <b>unselected</b>. The selected role is used, for example, to indicate the page that is being shown, or the current value of a preference. The unselected role is used for all other displayables.</p>
<p>Each displayable is in one of four states:</p>
<ul>
<li><b>insensitive</b>, unable to respond to user input.</li>
<li><b>idle</b>, able to respond to user input, but not focused.</li>
<li><b>hover</b>, able to respond to user input, and focused.</li>
<li><b>activate</b>, chosen by the user (for example, a clicked button).</li>
</ul>
<p>The roles and states correspond to prefixes that are applied to style properties. The role prefixes are:</p>
<ul>
<li>"" (no prefix) - set for both selected and unselected roles.</li>
<li>"selected_" - set for only the selected role.</li>
</ul>
<p>The state prefixes are:</p>
<ul>
<li>"" (no prefix) - set for all states.</li>
<li>"insensitive_" - set for the insensitive state.</li>
<li>"idle_" - set for the idle state.</li>
<li>"hover_" - set for the hover and activate states.</li>
<li>"activate_" - set for the activate state.</li>
</ul>
<p>To set a property, one assigns a value to the python expression:</p>
<dl>
<dd>style.<i><style name></i>.<i><role prefix><state prefix><property></i></dd>
</dl>
<p>For example:</p>
<pre>
<span class="kwa">init python</span><span class="sym">:</span>
style<span class="sym">.</span>mm_button<span class="sym">.</span>background <span class="sym">=</span> <span class="str">"#f00"</span>
style<span class="sym">.</span>mm_button<span class="sym">.</span>hover_background <span class="sym">=</span> <span class="str">"#ff0"</span>
style<span class="sym">.</span>mm_button<span class="sym">.</span>selected_hover_background <span class="sym">=</span> <span class="str">"#00f"</span>
style<span class="sym">.</span>mm_button<span class="sym">[</span>u<span class="str">"Start Game"</span><span class="sym">].</span>background <span class="sym">=</span> <span class="str">"#0f0"</span>
</pre>
<p>The first line sets the background of all main menu buttons to be red. The second changes the background of hovered main menu buttons to be yellow. The third changes selected and hovered main menu buttons to be blue - this doesn't actually do anything, since main menu buttons are never selected. Finally, the last one changes the index style to have a green background. Since the indexed style is hire in the inheritance order, it will take precedence over all other styles.</p>
<p>Note that the order of statements matters. The code:</p>
<pre>
<span class="kwa">init python</span><span class="sym">:</span>
style<span class="sym">.</span>mm_button<span class="sym">.</span>hover_background <span class="sym">=</span> <span class="str">"#ff0"</span>
style<span class="sym">.</span>mm_button<span class="sym">.</span>background <span class="sym">=</span> <span class="str">"#f00"</span>
</pre>
<p>Will cause hovered main menu buttons to have a red background. This is because the second statement, which sets all roles and states, takes precedence over the first statement. Generally, it makes sense to set the unprefixed properties first, and the prefixed properties second.</p>
<div class="visualClear" />
<hr /><p class="docnav"><a href="../index.html">documentation index</a></p></div>
</body></html>
|
