UI Functions
While the say and menu statements are often enough for many games, there are times when more complex user interfaces are desired. For example, dating sim games can require more complex scheduling screens. These screens can be built using the UI functions.
Most of the UI functions create widgets and add them to the screen. The UI functions manage the complexity of nesting widgets. The screen can then be shown to the user with ui.interact , and a value returned and used by the game script.
To start, let's give a script snippet that uses the UI functions. The following displays a window containing three buttons, arraigned horizontally. The string assigned to choice varies depending on which of the three is picked.
$ ui.window() $ ui.hbox() $ ui.textbutton("A", clicked=ui.returns("A")) $ ui.textbutton("B", clicked=ui.returns("B")) $ ui.textbutton("C", clicked=ui.returns("C")) $ ui.close() $ choice = ui.interact(suppress_overlay=True)
There are three kinds of widgets that can be created by the UI functions.
-
The first kind of widget (of which ui.window is one), takes a single child widget. When this kind of widget is open, the next widget to be created is added to it, and it then closes automatically.
-
The second kind of widget can take an arbitrary number of child widgets. This kind of widget is exemplified by the layout widgets: vbox, hbox, and fixed. New widgets are added to this kind of widget until a matching call to ui.close occurs, unless they are instead added to an open child of this widget.
-
The third kind of widget cannot take any children. This kind of widget is exemplified by ui.textbutton .
There is also a set of functions that are used to manage the interaction, and a set of functions that can be used to perform various actions when buttons are clicked.
Single-Child Widgets
Function: ui.frame( | **properties) |
A frame contains a single widget. This is similar to a window, but may be styled differently.
Function: ui.sizer( | maxwidth=None, maxheight=None, **properties) |
This is a widget that can shrink the size allocated to the next widget added. If maxwidth or maxheight is not None, then the space allocated to the child in the appropriate direction is limited to the given amount.
Please note that this only works with child widgets that can have a limited area allocated to them (like text), and not with ones that use a fixed area (like images).
maxwidth - The maximum width of the child widget, or None to not affect width.
maxheight - The maximum height of the child widget, or None ot not affect height.
Function: ui.window( | **properties) |
A window contains a single widget. It draws that window atop a background and with appropriate amounts of margin and padding, taken from the window properties supplied to this call. The next widget created is added to this window.
Multiple-Child Widgets
Function: ui.grid( | cols, rows, padding=0, transpose=False, **properties) |
This creates a layout that places widgets in an evenly spaced grid. New widgets are added to this grid until ui.close is called. Widgets are added by going from left to right within a single row, and down to the start of the next row when a row is full. All cells must be filled (that is, exactly col * rows widgets must be added to the grid.)
The children of this widget should have a fixed size that does not vary based on the space allocated to them. Failure to observe this restriction could lead to really odd layouts, or things being rendered off screen. This condition is relaxed in the appropriate dimension if xfill or yfill is set.
Each cell of the grid is exactly the same size. By default, the grid is the smallest size that can accommodate all of its children, but it can be expanded to consume all available space in a given dimension by setting xfill or yfill to True, as appropriate. (Otherwise, xfill and yfill are inherited from the style.)
cols - The number of columns in this grid.
rows - The number of rows in this grid.
padding - The amount of space to leave between rows and columns.
xfill - True if the grid should consume all available width.
yfill - True if the grid should consume all available height.
transpose - If True, grid will fill down columns before filling across rows.
Function: ui.hbox( | spacing=None, style='hbox', **properties) |
This creates a layout that places widgets next to each other, from left to right. New widgets are added to this hbox until ui.close is called.
spacing - The number of pixels to leave between widgets. If None, take the amount of spacing from the style.
Function: ui.vbox( | spacing=None, style='vbox', **properties) |
This creates a layout that places widgets next to each other, from top to bottom. New widgets are added to this vbox until ui.close is called.
spacing - The number of pixels to leave between widgets. If None, take the amount of spacing from the style.
No-Child Widgets
Function: ui.bar( | range, value, clicked=None, **properties) |
This creates a bar widget. The bar widget can be used to display data in a bar graph format, and optionally to report when the user clicks on a location in that bar.
range - The range of values this bar can undertake. The bar is completely full when its value is this number.
value - The value of this bar. It must be between 0 and range, inclusive.
clicked - This is a callback function called when the mouse is clicked in this widget. It is called with a single argument, which is the value corresponding to the location at which the mouse button was clicked. If this function returns a value, that value is returned from ui.interact .
The width and height should be set with the xmaximum and ymaximum properties. For best results, if clicked is set then width should be at least twice as big as range.
Function: ui.image( | im, **properties) |
This loads an image, and displays it as a widget. The image may be the name of a file containing the image, or an arbitrary displayable.
Function: ui.imagemap( | ground, selected, hotspots, unselected=None, style='imagemap', button_style='imagemap_button', **properties) |
This is called to create imagemaps. Parameters are roughly the same as renpy.imagemap . The value of the hotspot is returned when ui.interact returns.
Function: ui.null( | **properties) |
This widget displays nothing on the screen. Why would one want to do this? If a widget requires contents, but you don't have any contents to provide it.
Function: ui.saybehavior( | afm=None, dismiss=[ 'dismiss' ], allow_dismiss=None) |
This is a pseudo-widget that adds the say behavior to the screen. The say behavior is to return True if the left mouse is clicked or enter is pressed. It also returns True in various other cases, such as if the current statement has already been seen. This widget should not be added to any other widget, but should instead be only added to the screen itself.
If afm is present, it is a block of text, that's given to the auto forwarding mode algorithm to determine the auto-forwarding timeout.
If dismiss is present, it is a list of names of keybindings that are used to dismiss this saybehavior.
If allow_dismiss is present, it should be a function. This function is called without any arguments each time the user initiates a dismiss request. If the function returns True, the dismiss request is allowed, otherwise it is ignored. Added in 5.6.6.
There should only be one saybehavior shown at a time, otherwise they will fight for focus.
Function: ui.pausebehavior( | delay, result=False) |
This is a pseudo-widget that adds the pause behavior to the screen. The pause behavior is to return the supplied result when the given number of seconds elapses. This widget should not be added to any other widget, but should instead be only added to the screen itself.
Please note that this widget will always pause for the given amount of time. If you want a pause that can be interrupted by the user, add in a saybehavior.
delay - The amount of time to pause, in seconds.
result - The result that will be retuned after the delay time elapses.
Function: ui.keymap( | **keymap) |
This is a psuedo-widget that adds a keymap to the screen. This function takes as keyword arguments the names of bindings or keysyms. These keywords should be given as their arguments a function, which is called with zero arguments when an appropriate keysym is pressed.
Management Functions
Function: ui.add( | w, make_current=False, once=False) |
This is used to add a displayable to the current widget. If make_current is True, then the widget is made the current widget. If once is True, then the displayable will be made the current widget, but only for the next widget to be added.
Function: ui.at( | position) |
The ui.at function takes a position or motion, and applies it to the next widget created using a ui function.
Function: ui.clear( | ) |
Clears the current layer of widgets. Allows the ui functions to be used on non-transient layers, although not all widgets may be used in this way.
Function: ui.close( | ) |
This closes the currently open widget or layer. If a widget is closed, then we start adding to its parent, or the layer if no parent is open. If a layer is closed, we return to the previously open layer. An error is thrown if we close the last open layer.
Function: ui.interact( | **kwargs) |
Displays the current scene to the user, waits for a widget to indicate a return value, and returns that value to the user. As a side-effect, disables fast skip mode when executed.
Some useful keyword arguments are:
show_mouse - Should the mouse be shown during this interaction? Only advisory, as this doesn't work reliably.
suppress_overlay - This suppresses the display of the overlay during this interaction.
suppress_underlay - This suppresses the underlay during this interaction. The underlay contains the key and mouse bindings that let the user access the game menu. (As well as a number of other useful in-game functions.)
roll_forward - The value returned if the user tries to roll forward. This is normally used in conjunction with renpy.roll_forward_info and renpy.checkpoint .
Clicked Action Functions
The result of these functions is suitable for use as the clicked argument used by ui.button , ui.imagebutton , and ui.textbutton .
Function: ui.jumps( | label) |
This function returns a function that, when called, jumps the game to the given label, ending the current interaction in the process. It's best used to supply the clicked argument to the various button widgets.
Function: ui.jumpsoutofcontext( | label) |
This function returns a function that, when called, exits the current context, and in the parent context jumps to the named label. It's intended to be used as the clicked argument to a button.
Function: ui.returns( | value) |
This function returns a function that, when called, returns the supplied value. It's best used to supply the clicked argument to the various button widgets.