The style properties associated with styles control how Displayables are shown. Style properties can be either given without a prefix, in which case they apply to all states of the displayable, or with a prefix that limits the property to a limited number of states.
Applying a prefix to a style property indicates allows a displayable to change it's look in response to its focus or selection status. For example, a button can change its color when the mouse hovers above it, or to indicate when the choice represented by the button is the currently selected one.
There are five states a displayable can be it.
Button and Bar displayables (and their variants) update their state, and the state of their children, in response to events. For example, when the user puts his mouse over an unselected button, it and all its children will be put into the hover state.
Style property prefixes allow one to set style properties for the different states. There is a system of implications set up, so that a prefix can imply setting the property for more than one state.
The implications are:
prefix | states implied by prefix |
---|---|
(no prefix) | insensitive, idle, hover, selected_idle, selected_hover |
idle_ |
idle, selected_idle |
hover_ |
hover, selected_hover |
selected_ |
selected_idle, selected_hover |
insensitive_ |
insensitive |
selected_idle_ |
selected_idle |
selected_hover_ |
selected_hover |
selected_insensitive_ |
selected_insensitive |
Using a text button, we can show this in action. Text buttons use two styles
by default: button
for the button itself, and button_text
for the
text inside the button. The background
style property sets the
background of a button, while the color
property sets the color of
text.:
# The button background is gray when insensitive, light
# blue when hovered, and dark blue otherwise.
style button:
background "#006"
insensitive_background "#444"
hover_background "#00a"
# The button text is yellow when selected, and white
# otherwise.
style button_text:
color "#fff"
selected_color "#ff0"
Each style property expects a specific kind of data. Many of these are standard Python types, but a few are novel. Here are descriptions of the novel kinds of value a style property can expect.
Positions are used to specify locations relative to the upper-left corner of the containing area. (For positions, the containing area is given by the layout the displayable is in, if one is given, or the screen otherwise. For anchors, the containing area is the size of the displayable itself.)
The way a position value is interpreted depends on the type of the value:
absolute
number is interpreted as the number of pixels from the
left or top side of the screen, when using subpixel-precise rendering.Colors in Ren'Py can be expressed as strings beginning with the hash mark (#), followed by a hex triple or hex quadruple, with each of the three or four elements consisting of a one or two hexadecimal character color code.
In a triple, the components represent red, green, and blue. In a quadruple, the components represent red, green, blue, and alpha. For example:
"#f00"
and "#ff0000"
represent an opaque red color."#0f08"
and #00ff0080"
represent a semi-transparent green
color.The color triples are the same as used in HTML.
Colors can also be represented as a 4-component tuple, with the 4 components being integers between 0 and 255. The components correspond to red, green, blue, and alpha, in that order.
(0, 0, 255, 255)
represents an opaque blue color.Finally, colors can be an instance of Color
.
When a style property contains the "[prefix_]" substitution, a prefix search is performed. The prefix search is performed separately for each state, including states that are implied by the original property assigned.
For example, if we have:
style button:
hover_background "[prefix_]background.png"
separate searches are performed for the hover and selected_hover states. The prefixes searched vary based on the state.
state | search order |
---|---|
idle | "idle_", "" |
hover | "hover_", "", |
insensitive | "insensitive_", "", "idle_" |
selected_idle | "selected_idle_", "idle_", "selected_", "" |
selected_hover | "selected_hover_", "hover_", "selected_", "" |
selected_insensitive | "selected_insensitive_", "hover_", "selected_", "", "selected_idle_", "idle_" |
When a search is performed, each prefix is tried in the order given. The string has "[prefix_]" replaced with the prefix, and then Ren'Py checks to see if a loadable file or image with that name exists. If the file or image exists, the search stops and the displayable found is used. Otherwise, it proceeds to the next prefix.
The style prefix is passed through displayables that do not take user input, including containers, transforms, and frames.
As an example of how this can be used, if the files "idle_button.png" and "hover_button.png" exist (and no other files ending in "button.png" do):
style button:
background "[prefix_]button.png"
is equivalent to:
style button:
idle_background "idle_button.png"
hover_background "hover_button.png"
insensitive_background "idle_button.png"
selected_idle_background "idle_button.png"
selected_hover_background "hover_button.png"
selected_insensitive_background "idle_button.png"
The style properties control the look of the various displayables. Not all style properties apply to all displayables, so we've divided them up into groups.
These properties apply to all displayables, and mostly control the position of a displayable inside the area allocated to it by a layout, or on the screen when not inside a layout.
alt
- string or None linkAlternative text used for the displayable when self-voicing is enabled. See the self voicing section for more information.
xpos
- position linkThe position of the displayable relative to the left side of the containing area.
ypos
- position linkThe position of the displayable relative to the top side of the containing area.
pos
- tuple of (position, position) linkEquivalent to setting xpos to the first component of the tuple, and ypos to the second component of the tuple.
xanchor
- position linkThe position of the anchor relative to the left side of the displayable.
yanchor
- position linkThe position of the anchor relative to the top side of the displayable.
If the displayable is a Text()
, then there is one special value
of this property. If the property is set to renpy.BASELINE, the anchor
is set to the baseline of the first line of text.
anchor
- tuple of (position, position) linkEquivalent to setting xanchor to the first component of the tuple, and yanchor to the second component of the tuple.
xalign
- float linkEquivalent to setting xpos and xanchor to the same value. This has the effect of placing the displayable at a relative location on the screen, with 0.0 being the left side, 0.5 the center, and 1.0 being the right side.
yalign
- float linkEquivalent to setting ypos and yanchor to the same value. This has the effect of placing the displayable at a relative location on the screen, with 0.0 being the top, 0.5 the center, and 1.0 the bottom.
align
- tuple of (float, float) linkEquivalent to setting xalign to the first component of the tuple, and yalign to the second.
xcenter
- position linkEquivalent to setting xpos to the value of this property, and xanchor to 0.5.
ycenter
- position linkEquivalent to setting ypos to the value of this property, and yanchor to 0.5.
xoffset
- int linkGives a number of pixels that are added to the horizontal position computed using xpos and xalign.
yoffset
- int linkGives a number of pixels that are added to the vertical position computed using ypos and yalign.
offset
- tuple of (int, int) linkEquivalent to setting xoffset to the first component of the tuple, and yoffset to the second component of the tuple.
xmaximum
- int linkSpecifies the maximum horizontal size of the displayable, in pixels.
ymaximum
- int linkSpecifies the maximum vertical size of the displayable in pixels.
maximum
- tuple of (int, int) linkEquivalent to setting xmaximum to the first component of the tuple, and ymaximum to the second.
xminimum
- int linkSets the minimum width of the displayable, in pixels. Only works with displayables that can vary their size.
yminimum
- int linkSets the minimum height of the displayables, in pixels. Only works with displayables that can vary their size.
minimum
- tuple of (int, int) linkEquivalent to setting xminimum to the first component of the tuple, and yminimum to the second.
xsize
- int linkEquivalent to setting xminimum and xmaximum to the same value. This has the effect of setting the width of the displayable.
ysize
- int linkEquivalent to setting yminimum and ymaximum to the same value. This has the effect of setting the height of the displayable.
xysize
- tuple of (int, int) linkEquivalent to setting xminimum and xmaximum to the first component of the tuple, and yminimum and ymaximum to the second component. This has the effect of setting the size of the displayable.
xfill
- boolean linkIf true, the displayable will expand to fill all available horizontal space. If not true, it will only be large enough to contain its children.
This only works for displayables that can change size.
yfill
- boolean linkIf true, the displayable will expand to fill all available vertical space. If not true, it will only be large enough to contain its children.
This only works for displayables that can change size.
area
- tuple of (int, int, int, int) linkThe tuple is interpreted as (xpos, ypos, width, height). Attempts to position the displayable such that it's upper-left corner is at xpos and ypos, and its size is width and height.
It does this by setting the xpos, ypos, xanchor, yanchor, xmaximum, ymaximum, xminimum, yminimum, xfill, and yfill properties to appropriate values.
This will not work with all displayables and all layouts.
mipmap
- boolean or None linkThis controls if textures created by this displayable are mipmapped.
This applies only to certain displayables, including Text()
,
Movie()
, and dissolves.
If None, the default for this is taken from config variables such
as config.mipmap_text
, config.mipmap_movies
, and
config.mipmap_dissolves
.
antialias
- boolean linkIf True, the default, TrueType font text will be rendered anti-aliased.
adjust_spacing
- boolean or str linkIf True, Ren'Py will adjust the spacing of drawable-resolution text to match the spacing of the text rendered at virtual resolution, to ensure the size of frames and other containers holding text does not change.
When set to False, text will not change in size, but it is the creator's responsibility to ensure there is enough space to layout text at any window size.
When set to the string "horizontal", text will adjust in the horizontal direction only. When set to the string "vertical", text will adjust in the vertical direction only.
Defaults to True for most text, but False for text in an input
.
altruby_style
- style or None linkIf not None, this should be a style object. The style that's used for alternate ruby text.
black_color
- color linkWhen rendering an image-based font, black will be mapped to this color. This has no effect for TrueType fonts.
bold
- boolean linkIf True, render the font in a bold style. For a TrueType font,
this usually involves synthetically increasing the font weight. It
can also cause the font to be remapped, using
config.font_replacement_map
.
caret
- displayable or None linkIf not None, this should be a displayable. The input widget will use this as the caret at the end of the text. If None, a 1 pixel wide blinking line is used as the caret.
color
- color linkThe color the text is rendered in. When using a TrueType font, the font is rendered in this color. When using an image-based font, white is mapped to this color.
first_indent
- int linkThe amount that the first line of text in a paragraph is indented by, in pixels.
font
- string linkA string giving the name of the font used to render text.
For a TrueType font file, this is usually the name of the file
containing the font (like "DejaVuSans.ttf"
). To select a second
font in a collection, this can be prefixed with a number and
at sign (like "0@font.ttc"
or "1@font.ttc"
). For an
image-based font, this should be the name used to register the
font.
size
- int linkThe size of the font on the screen. While this is nominally in pixels, font files may have creative interpretations of this value.
italic
- boolean linkIf true, the text will be rendered in italics. For a TrueType font,
this usually involves synthetically increasing the font slant. It
can also cause the font to be remapped, using
config.font_replacement_map
.
justify
- boolean linkIf True, additional whitespace is inserted between words so that the left and right margins of each line are even. This is not performed on the last line of a paragraph.
kerning
- float linkA kerning adjustment, the number of pixels of space that's added between each pair of characters. (This can be negative to remove space between characters.)
language
- string linkControls the language family used to break text into lines. Legal values are:
"unicode"
(default)"japanese-strict"
"japanese-normal"
"japanese-loose"
"korean-with-spaces"
"western"
"anywhere"
The three Japanese breaking modes are taken from the CSS3 text module.
layout
- string linkControls how words are allocated to lines. Legal values are:
"tex"
(default)"subtitle"
"greedy"
"nobreak"
line_leading
- int linkThe number of pixels of spacing to include above each line.
line_overlap_split
- int linkWhen in slow text mode, and two lines overlap, this many pixels of the overlap are allocated to the top line. Increase this if the bottoms of characters on the top line are clipped.
line_spacing
- int linkThe number of pixels of spacing to include below each line.
min_width
- int linkSets the minimum width of each line of that. If a line is shorter
than this, it is padded to this length, with text_align
used to
specify where such padding is placed.
newline_indent
- boolean linkIf true, the first_indent
indentation is used after
each newline in a string. Otherwise, the rest_indent
indentation is used.
outlines
- list of tuple of (int, color, int, int) linkThis is a list of outlines that are drawn behind the text. Each tuple specifies an outline, and outlines are drawn from back to front.
The list contains (size, color, xoffset, yoffset) tuples. size is the amount the font is expanded by, in pixels. color is the color of the outline. xoffset and yoffset are the amount the outline is shifted by, in pixels.
The outline functionality can also be used to give drop-shadows to fonts, by specifying a size of 0 and non-zero offsets.
By default, size, xoffset and yoffset are scaled with the text. When given as the absolute type, they are not scaled. For example:
style default:
outlines [ (absolute(1), "#000", absolute(0), absolute(0)) ]
will always produce a 1 pixel-wide border.
Outlines only work with TrueType fonts. Outlines only work when applied to an entire Text displayable. They do not work when applied to a hyperlink, text tag, or other method that applies to only a portion of the text.
outline_scaling
- string linkThis determines how outline sizes and offsets are scaled when the window is scaled.
"linear"
The default, best for text with thick outlines. The window scaling factor is applied to the outline size, and then rounded to an integer. This looks better for thick outlines, but concentric outlines of similar thickness may become indistinguishable.
The resulting width is always at least 1 pixel.
"step"
Best for text that uses thin outlines and text that uses multiple outlines. The window scaling factor is rounded down to an integer and applied to the outline size and offsets. This ensures that multiple outlines all scale together, without risk of eclipsing one another, but this yields different visual results depending on the size of the game window.
The window scaling factor is always above 1.
rest_indent
- int linkSpecifies the number of pixels the second and later lines in a paragraph are indented by.
ruby_style
- style or None linkIf not None, this should be a style object. The style that's used for ruby text.
slow_abortable
- boolean linkIf True, a click that reaches the Text object will cause the slow text to abort, which means that the rest of the slow text will be displayed instantly.
slow_cps
- int or True linkIf a number, shows text at the rate of that many characters per second. If True, shows text at the speed taken from the "Text Speed" preference.
slow_cps_multiplier
- float linkThe speed of the text is multiplied by this number. This can be used to have a character that speaks at a faster-than-normal rate of speed.
strikethrough
- boolean linkIf True, a line is drawn through the text.
text_align
- float linkThis is used when a line is shorter than the width of the text displayable. It determines how much of the extra space is placed on the left side of the text. (And hence, the text alignment.)
0.0 will yield left-aligned text, 0.5 centered text, and 1.0 right-aligned text.
underline
- boolean linkIf True, an underline will be added to the text.
hyperlink_functions
- tuple of (function, function, function) linkThis is a tuple of three functions relating to hyperlinks in text.
The first item is the hyperlink style function. When called with a single
argument, the argument of the hyperlink, it must return a style object to
use for the hyperlink, such as style.hyperlink_text
. Note that a
style object is not a string.
The second item is the hyperlink clicked function. This function is called when a hyperlink is chosen by the user. If it returns a value other than None, the interaction returns that value.
The third item is the hyperlink focus function. This function is called with the argument of the hyperlink when the hyperlink gains focus, and with None when it loses focus. If it returns a value other than None, the interaction returns that value.
vertical
- boolean linkIf True, the text will be rendered vertically.
hinting
- str linkControls how the font will be hinted. This should be one of the following strings:
Window properties are used to specify the look of windows, frames, and buttons. Margin Style Properties also form part of this group.
background
- displayable or None linkA displayable that is used as the background of the window. This
is often a Frame()
, allowing the size of the background to
scale with the size of the window.
If None, no background is drawn, but other properties function as if the background was present.
foreground
- displayable or None linkIf not None, this displayable is drawn above the contents of the window.
left_padding
- int linkThe amount of space between the background and the left side of the window content, in pixels.
right_padding
- int linkThe amount of space between the background and the right side of the window content, in pixels.
xpadding
- int linkEquivalent to setting left_padding and right_padding to the same value.
top_padding
- int linkThe amount of space between the background and the top side of the window content, in pixels.
bottom_padding
- int linkThe amount of space between the background and the bottom side of the window content, in pixels.
ypadding
- int linkEquivalent to setting top_padding and bottom_padding to the same value.
padding
- tuple linkWhen given a two-item tuple, equivalent to setting xpadding and ypadding to the two items. When given a four-item tuple, equivalent to setting left_padding, top_padding, right_padding, and bottom_padding to the four items.
size_group
- string or None linkIf not None, this should be a string. Ren'Py will render all windows with the same size_group value at the same size.
modal
- boolean or callable linkIf True, the window is treated as modal. Events will stop propagating through layers while the mouse is within the window or button. If False, the window is not modal.
This may also be a callable function. If it is, the function is called with (ev, x, y, w, h), where ev is either a pygame event, or None to represent a generic mouse event; x and y are coordinates relative to the window, and w and h are the height and width of the window. If the callable returns true, the windows is treated as modal. If it returns false, it is not.
child
- displayable or None linkIf not None, this gives a displayable that replaces the child of the button. For example, this (as insensitive_child) can be used to replace the contents of an insensitive button with an image that indicates the button is locked.
hover_sound
- string linkA sound that is played when the button gains focus.
activate_sound
- string linkA sound that is played when the button is activated (clicked). This is also played when a bar or drag is activated.
mouse
- string linkThe mouse style that is used when the button is focused. This
should be one of the styles in config.mouse
.
focus_mask
- multiple linkA mask that's used to control what portions of the button can be focused, and hence clicked on. The type of this property determines how it is interpreted.
If a non-displayable callable (like a function, method, or object
with a __call__
method) is given, the function is called with two
arguments, the x and y offset from the top-left corner of the
displayable.
If the function returns a callable when called with two arguments, that callable is called with four arguments - the x and y offsets, and the width and height of the displayable.
If the function returns true, the displayable is focused.
keyboard_focus
- boolean linkIf True, the default, this button can be focused using the keyboard focus mechanism, if it can be focused at all. If False, the keyboard focus mechanism will skip this button. (The keyboard focus mechanism is used by keyboards and keyboard-like devices, such as joypads.)
key_events
- boolean linkIf True, keyboard-generated events are passed to the children of this button. If False, those events are not propagated. In this default style, this is set to True while the button is hovered, and False otherwise.
Setting this to True can be used to propagate keyboard events to an input inside a button, even when the button isn't focused.
Bars are drawn with gutters on the left and right, that when clicked can cause the bar to move by a small amount. The remaining space is the portion of the bar that can change, with the amount on each side proportional to the bar's value as a fraction of the range.
The thumb is an area in the center of the bar that can be dragged by the user.
When a bar is drawn, the thumb's shadow is drawn first. Then the left/bottom and right/top sides of the bar, followed by the thumb itself.
Note that the valid sides of a bar depend on the value of the bar_vertical property. If it's True, the top and bottom sides are relevant. Otherwise, the left and right sides are used.
bar_vertical
- boolean linkIf True, the bar has a vertical orientation. If False, it has a horizontal orientation.
bar_invert
- boolean linkIf True, the value of the bar is represented on the right/top side of the bar, rather than the left/bottom side.
bar_resizing
- boolean linkIf True, we resize the sides of the bar. If False, we render the sides of the bar at full size, and then crop them.
left_gutter
- int linkThe size of the gutter on the left side of the bar, in pixels.
right_gutter
- int linkThe size of the gutter on the right side of the bar, in pixels.
top_gutter
- int linkThe size of the gutter on the top side of the bar, in pixels.
bottom_gutter
- int linkThe size of the gutter on the bottom side of the bar, in pixels.
left_bar
- displayable linkThe displayable used for the left side of the bar.
right_bar
- displayable linkThe displayable used for the right side of the bar.
top_bar
- displayable linkThe displayable used for the top side of the bar.
bottom_bar
- displayable linkThe displayable uses for the bottom side of the bar.
base_bar
- displayable linkA single displayable that is used for left_bar/right_bar or top_bar/bottom_bar, as appropriate. (This can be used with thumb to make a slider or scrollbar.)
thumb
- displayable or None linkIf not None, this is a displayable that is drawn over the break between the sides of the bar.
thumb_shadow
- displayable or None linkIf not None, this is a displayable that is drawn over the break between the sides of the bar.
thumb_offset
- int linkThe amount that by which the thumb overlaps the bars, in pixels. To have the left and right bars continue unbroken, set this to half the width of the thumb in pixels.
mouse
- string linkThe mouse style that is used when the button is focused. This
should be one of the styles in config.mouse
.
unscrollable
- string or None linkControls what happens if the bar is unscrollable (if the range is set to 0, as is the case with a viewport containing a displayable smaller than itself). There are three possible values:
None
"insensitive"
"hide"
keyboard_focus
- boolean linkIf True, the default, this button can be focused using the keyboard focus mechanism, if it can be focused at all. If False, the keyboard focus mechanism will skip this button. (The keyboard focus mechanism is used by keyboards and keyboard-like devices, such as joypads.)
These are used for the horizontal and vertical box layouts.
spacing
- int linkThe spacing between members of this box, in pixels.
first_spacing
- int linkIf not None, the spacing between the first and second members of this box, in pixels. This overrides the spacing property.
box_reverse
- boolean linkIf True, the placement of the items in the box will be reversed. When this is True, a hbox will be filled right-to-left, and a vbox will be filled bottom-to-top. This defaults to False.
box_wrap
- boolean linkIf True, then boxes will wrap when they reach the end of a line or column. If False (the default), they will extend past the end of the line.
box_wrap_spacing
- int linkWhen box_wrap is True, this is the spacing between wrapped lines or columns. (So it is the vertical spacing between lines in a wrapped hbox, and the horizontal spacing between columns in a wrapped vbox.)
order_reverse
- boolean linkIf False, the default, the items in the box will be drawn first-to-last, with the first item in the box being below the second, and so on. If True, this order will be reversed, and the first item in the box will be above all other items in the box.
These are the properties used by the grid and vpgrid displayables. Margin Style Properties also form part of this group.
spacing
- int linkThe spacing between cells of the grid, in pixels.
xspacing
- int or None linkThe spacing between cells of the grid in the horizontal direction, in pixels. This takes precedence over the spacing property when it is not None.
yspacing
- int or None linkThe spacing between cells of the grid in the vertical direction, in pixels. This takes precedence over the spacing property when it is not None.
These are used with the fixed layout.
fit_first
- boolean or "width" or "height" linkIf True, then the size of the fixed layout is shrunk to be equal with the size of the first item in the layout. If "width", only the width is changed (the fixed will fill the screen vertically). Similarly, "height" only changes the height.
The position of the child is ignored for the purpose of fit_first.
xfit
- boolean linkIf True, the size of the fixed layout is shrunk horizontally to match the right side of the rightmost child of the fixed.
yfit
- boolean linkIf True, the size of the fixed layout is shrunk vertically to match the bottom side of the bottommost child of the fixed.
When these properties are supplied, the children of the fixed are first offered the full area given to the fixed by its parent. Once the size and placement of the children are known, these properties are then used to select the size of the fixed.
Margin properties are used to add transparent space around some displayables. Most notably: windows, frames, buttons and outside a grid or vpgrid.
left_margin
- int linkThe amount of transparent space to the left of the displayable, in pixels.
right_margin
- int linkThe amount of transparent space to the right of the displayable, in pixels.
xmargin
- int linkEquivalent to setting left_margin and right_margin to the same value.
top_margin
- int linkThe amount of transparent space above the displayable, in pixels.
bottom_margin
- int linkThe amount of transparent space below the displayable, in pixels.
ymargin
- int linkEquivalent to setting top_margin and bottom_margin to the same value.
margin
- tuple linkWhen given a two-item tuple, equivalent to setting xmargin and ymargin to the two items. When given a four-item tuple, equivalent to setting left_margin, top_margin, right_margin, and bottom_margin to the four items.