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_".

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.

Function: ui.viewport( | child_size=(None, None), offsets=(0.0, 0.0), style='viewport', **properties)

Displays a viewport on the screen. A viewport restricts the size of its child, and allows the child to be displayed at an offset. Viewports have two methods, set_xoffset and set_yoffset, that allow the offsets to be changed, and hence the viewport to be scrolled.

child_size - The x and y size of the area the child is asked to render. If either is None, defaults to the size of this viewport.

offsets - The x and y offsets. If an integer, this is taken as a number of pixels. If a float, a fraction of the amount by which the child is larger then the viewport.

In general, viewports are only useful when the xmaximum and ymaximum properties are specified. You'll also want to set clipping=True on the style, although this is part of the default viewport style.

The set_xoffset and set_yoffset methods take a single argument, the new value of the offset.

## Multiple-Child Widgets

Function: ui.fixed( | **properties)

This creates a layout that places widgets at fixed locations relative to the origin of the enclosing widget. The layout takes up the entire area allocated to it. New widgets are added to this widget until the next call to ui.close .

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, changed=None, style='bar', **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.

changed - 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. This argument is an integer if range is an integer, and a float if range is a float. If this function returns a value, that value is returned from ui.interact .

style - The style of this bar. As of 6.2.0, there are four styles that you can use:

- bar - A horizontal bar, with the largest value to the right.

- scrollbar - A horizontal scrollbar, with the largest value to the right.

- vbar - A vertical bar, with the largest value to the top.

- vscrollbar - A vertical scrollbar, with the largest value to the bottom.

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.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.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.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.

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:

type - The type of this interaction. See renpy.last_interact_type for more details.

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 .

Function: ui.layer( | name)

This causes widgets to be added to the named layer, until a matching call to ui.close .

## 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.

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