documentation index ◦ reference manual ◦ function index

# ui.button

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. See also ui.imagebutton, which creates a button in the form of an image.

clicked - 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. If clicked itself is None, the button is displayed in the "insensitive" (disabled) style.

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. It's also called at least once per interaction, when a button is not focused at the start of the interaction. The return value is currently ignored, but should be None.

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

Note that code in the clicked, hovered, and unhovered methods is run inside the current interaction. This means that the screen is not cleared while this code is run. Displayables may be added or removed from the current interaction, provided renpy.restart_interaction is called to let Ren'Py know that the interaction has been changed. You should not run code that causes a new interaction from inside these functions, except inside a new context using renpy.call_in_new_context, renpy.invoke_in_new_context, or ui.callsinnewcontext.

## Example

    python:
        def button(text, selected, returns, **properties):
            style='selected_button'
            style_text='selected_button_text'

            if selected:
                role='selected_'
            else:
                 role=''

            ui.button(clicked=ui.returns(returns),
                      style='button', role=role, **properties)
            ui.text(text, style='button_text')

documentation index ◦ reference manual ◦ function index