Reference Manual: (offline | online) Quickstart: (offline | online)

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.button( clicked=None, **properties)

This creates a button that can be clicked by the user. When this button is clicked or otherwise selected, the function supplied as the clicked argument is called. If it returns a value, that value is returned from ui.interact .

Buttons created with this function contain another widget, specifically the next widget to be added. As a convenience, one can use ui.textbutton to create a button with a text label.

clicked - A function that is called with no arguments when this button is clicked.

hovered - A function that is called with no arguments when this button is focused. If it returns a non-None value, then that value is returned from ui.interact .

unhovered - A function that is called with no arguments when the button loses focus.

role - The role this button undertakes. This can be the empty string, or "selected_".

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.

No-Child Widgets

Function: ui.imagebutton( idle_image, hover_image, clicked=None, image_style='image_button_image', **properties)

This creates a button that contains two images. The first is the idle image, which is used when the mouse is not over the image, while the second is the hover image, which is used when the mouse is over the image. If the button is clicked or otherwise selected, then the clicked argument is called. If it returns a value, that value is returned from ui.interact .

idle_image - The file name of the image used when this button is idle.

hover_image - The file name of the image used when this button is hovered.

clicked - The function that is called when this button is clicked.

hovered - A function that is called with no arguments when this button is clicked. If it returns a non-None value, then that value is returned from ui.interact .

image_style - The style that is applied to the images that are used as part of the imagebutton.

role - The role this button undertakes. This can be the empty string, or "selected_".

Function: ui.menu( menuitems, style='menu', caption_style='menu_caption', choice_style='menu_choice', choice_chosen_style='menu_choice_chosen', choice_button_style='menu_choice_button', choice_chosen_button_style='menu_choice_chosen_button', location=None, focus=None, default=False, **properties)

This creates a new menu widget. Unlike the menu statement or renpy.menu function, this menu widget is not enclosed in any sort of window. You'd have to do that yourself, if it is desired.

menuitems - A list of tuples that are the items to be added to this menu. The first element of a tuple is a string that is used for this menuitem. The second element is the value to be returned from ui.interact if this item is selected, or None if this item is a non-selectable caption.

location - Some serializable and hashable object that represents the location of this menu in the game. (Normally, this is the name of the statement executing the menu.) If provided, then this logs which menuitems have been chosen, and changes the style of those menuitems to the choice_seen_style.

Management Functions

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 .

Reference Manual: (offline | online) Quickstart: (offline | online)