documentation index ◦ reference manual ◦ function index

# Layouts

Layouts control the feel of the out-of-game menus. There are five main kinds of layouts:

- main_menu layouts control the feel of the main menu.
- navigation layouts control the feel of the game menu navigation.
- load_save layouts control the feel of the load and save screens.
- yesno_prompt layouts control the feel of asking the user a yes or no question.
- preferences layouts control the feel of the preference screens.
- joystick_preferences layouts control the feel of the joystick preference screens.

There are also standalone layouts which do not fall into any of these categories. While a game needs exactly one of each of the five main kinds of layouts to function properly, it can have as many standalone layouts as it needs.

Each kind of layout provides certain functionality to the interface. The functionality provided by each kind of layout is described below. The selection of layouts is expected to occur before the selection of a theme. If no layout of a given kind is selected, then the classic variant is used. For example, if no yesno_prompt layout has been selected, then layout.classic_yesno_prompt is used.

Note that there are combinations of layouts and themes that will not look reasonable together. This is not a bug... it's impossible to have every layout work with every other layout and every theme, and still have an unlimited range of layouts and themes. Caveat factor.

## main_menu layouts

The main_menu layouts are responsible for defining the look of the main menu. This includes the background of the main menu, and the buttons that are used to go to the game menu or start a game.

Function: | layout.classic_main_menu | ():

This displays the classic main menu, which stacks the main menu buttons vertically.

Function: | layout.grouped_main_menu | ():

This defines a main menu layout that groups buttons into rows horizontally, and then stacks those rows vertically.

Variable: | config.main_menu_per_group | = 2

The number of buttons placed in to each horizontal row.

Function: | layout.imagemap_main_menu | (ground, selected, hotspots):

ground - The ground image. This is used for hotspots that are not selected.

selected - The selected image. This used for hotspots that are selected.

hotspots - A list of tuples defining the hotspot. Each tuple consists of:

1. The x-coordinate of the left side.
2. The y-coordinate of the top side.
3. The x-coordinate of the right side.
4. The y-coordinate of the bottom side.
5. Either the (untranslated) name of the main menu button this hotspot is equivalent to, or, a label in the program to jump to when this hotspot is clicked.

Despite the name, this function can take arbitrary displayables (like Animations) as well as images.

## navigation layouts

The navigation layouts are responsible for defining the navigation through the game menu. This includes the background of the game menus and the buttons that are used to go between game menu screens.

Function: | layout.classic_navigation | ():

This displays the navigation buttons in a vertical box.

Function: | layout.grouped_navigation | ():

This displays the navigation buttons in horizontal groups, which are then stacked vertically.

Variable: | config.navigation_per_group | = 2

The number of navigation buttons per horizontal group.

Function: | layout.imagemap_navigation | (ground, idle, hover, selected_idle, selected_hover, hotspots):

This layout uses an imagemap to handle game menu navigation.

ground - The displayable used for disabled buttons, and areas that are not in a hotspot.

idle - The displayable used for unfocused unselected hotspots.

hover - The displayable used for focused unselected hotspots.

selected_idle - The displayable used for unfocused selected hotspots.

selected_hover - The displayable used for focused selected hotspots.

hotspots - A list of tuples defining the hotspots. Each tuple consists of

1. The x-coordinate of the left side.
2. The y-coordinate of the top side.
3. The x-coordinate of the right side.
4. The y-coordinate of the bottom side.
5. The (untranslated) name of the game menu button this hotspot is equivalent to.

Despite the name, this function can take arbitrary displayables as well as images.

## load_save layouts

The load_save layouts are responsible for defining the load and save screens.

Function: | layout.classic_load_save | ():

This layout displays the the load and save screens as having a certain number of rows and columns of slots, with a row of navigation buttons on top.

Variable: | config.file_page_rows | = 5

The number of rows of file slots to display.

Variable: | config.file_page_cols | = 2

The number of columns of file slots to display.

Variable: | config.file_quick_access_pages | = 8

The number of pages of files to provide quick access buttons for.

Variable: | config.disable_file_pager | = False

If True, the pager is disabled. This prevents access to pages other than the first page of files.

Variable: | config.disable_thumbnails | = False

If True, thumbnails are not shown.

Variable: | config.load_save_empty_thumbnail | = None

If not None, this should be a displayable that will be shown with empty load/save slots.

Variable: | config.time_format | = "%b %d, %H:%M"

The format used for file times in the file entry slots.

Variable: | config.file_entry_format | = "%(time)s\n%(save_name)s"

The format of file entries in the file entry slots.

Function: | layout.scrolling_load_save | ():

This uses a scrolling area that contains file picker entries. The user picks one of these entries to load or save a file. There is one big thumbnail to the right of the screen, which corresponds to the currently hovered entry. (config.thumbnail_width and config.thumbnail_height control the size of this thumbnail.)

Variable: | config.load_save_slots | = 50

The number of normal slots to show.

Variable: | config.load_save_auto_slots | = 5

The number of autosave slots to show.

Variable: | config.load_save_quick_slots | = 5

The number of quicksave slots to show.

Variable: | config.load_save_empty_thumbnail | = None

When not None, this should be a displayable that will be shown in the thumbnail frame when no save slot has been hovered.

Variable: | config.time_format | = "%b %d, %H:%M"

The format used for file times in the file entry slots.

Variable: | config.file_entry_format | = "%(time)s\n%(save_name)s"

The format of file entries in the file entry slots.

Function: | layout.imagemap_load_save | (ground, idle, hover, selected_idle, selected_hover, hotspots):

This layout uses an imagemap to handle loading and saving.

ground - The displayable used for disabled buttons, and areas that are not in a hotspot.

idle - The displayable used for unfocused unselected hotspots.

hover - The displayable used for focused unselected hotspots.

selected_idle - The displayable used for unfocused selected hotspots.

selected_hover - The displayable used for focused selected hotspots.

hotspots - A list of tuples defining the hotspots. Each tuple consists of

1. The x-coordinate of the left side.
2. The y-coordinate of the top side.
3. The x-coordinate of the right side.
4. The y-coordinate of the bottom side.
5. The function of this hotspot.

The function of the hotspot should be one of:

- "previous" - go to the previous page.
- "next" - go to the next page.
- "page_auto" - go to the auto-save page.
- "page_quick" - go to the quick-save page.
- "page_1", "page_2", "page_3", ... - go to the specified page. The page numbers must start with 1, and be dense (not skip any numbers).
- "slot_0", "slot_1", "slot_2", ... - a save/load slot. The slot numbers must start with 0, and be dense.

Screenshots and slot text are placed inside windows that are laid out relative to the slot. Adjusting style.file_picker_ss_window controls the screenshot placement, and adjusting style.file_picker_text_window controls the placement of per-slot test. It will usually be necessary to adjust these styles, as the default places both in the upper left.

Despite the name, this function can take arbitrary displayables as well as images. The images or displayables used should be transparent to allow the navigation to show through.

Variable: | config.disable_thumbnails | = False

If True, thumbnails are not shown.

Variable: | config.load_save_empty_thumbnail | = None

If not None, this should be a displayable that will be shown with empty load/save slots.

Variable: | config.time_format | = "%b %d, %H:%M"

The format used for file times in the file entry slots.

Variable: | config.file_entry_format | = "%(time)s\n%(save_name)s"

The format of file entries in the file entry slots.

## yesno_prompt layouts

The yesno_prompt layouts are responsible for defining yes/no prompt screens.

Function: | layout.classic_yesno_prompt | ():

This displays the classic yes/no prompt, which is just a prompt above two buttons.

Function: | layout.imagemap_yesno_prompt | (ground, idle, hover, hotspots):

This layout uses an imagemap to handle prompting the user with yes/no questions.

ground - The displayable used for disabled buttons, and areas that are not in a hotspot.

idle - The displayable used for unfocused hotspots.

hover - The displayable used for focused hotspots.

hotspots - A list of tuples defining the hotspots. Each tuple consists of

1. The x-coordinate of the left side.
2. The y-coordinate of the top side.
3. The x-coordinate of the right side.
4. The y-coordinate of the bottom side.
5. The button replaced by this hotspot (one of "Yes" or "No").

Placement of the prompt text can be controlled using style.yesno_prompt, with the style of the text proper being controlled by style.yesno_prompt_text.

Despite the name, this function can take arbitrary displayables as well as images. The images or displayables used should be transparent to allow the navigation to show through.

## preferences layouts

The preferences layouts are used to define the preferences screen.

Function: | layout.classic_preferences | ():

This uses a three-column preferences layout.

Variable: | config.sample_sound | = None

A sound file used to test the sound volume.

Variable: | config.sample_voice=None | = None

A sound file used to test the voice volume.

Variable: | config.has_transitions | = True

If True, the option to enable or disable transitions is shown.

Variable: | config.has_cps | = True

If True, the option to control text speed is shown.

Variable: | config.has_afm | = True

If True, the option to control auto-forward mode is shown.

Variable: | config.has_skipping | = True

If True, the option to control skipping read messages or not is shown

Variable: | config.has_skip_after_choice | = True

If True, the option to control skipping after choices is shown

Variable: | config.always_has_joystick | = False

If True, the link to the joystick page is always active.

Variable: | config.has_joystick | = True

If True, the link to the joystick page is shown.

Function: | layout.two_column_preferences | ():

This uses a two-column preferences layout. Configuration variables are the same as for layout.classic_preferences.

Function: | layout.one_column_preferences | ():

This uses a one-column preferences layout. Configuration variables are the same as for layout.classic_preferences.

Function: | layout.imagemap_preferences | (ground, idle, hover, selected_idle, selected_hover, hotspots):

This layout uses an imagemap to handle preferences.

ground - The displayable used for disabled buttons, and areas that are not in a hotspot.

idle - The displayable used for unfocused unselected hotspots.

hover - The displayable used for focused unselected hotspots.

selected_idle - The displayable used for unfocused selected hotspots.

selected_hover - The displayable used for focused selected hotspots.

hotspots - A list of tuples defining the hotspots. Each tuple consists of

1. The x-coordinate of the left side.
2. The y-coordinate of the top side.
3. The x-coordinate of the right side.
4. The y-coordinate of the bottom side.
5. The function of this hotspot.

There are two kinds of hotspots, buttons and bars. The buttons are:

- "Window", "Fullscreen" - The display preference.
- "All", "Some", None" - The transition preferences.
- "Joystick" - The button used to jump to the joystick preferences.
- "Seen Messages", "All Messages" - Control which messages are skipped.
- "Begin Skipping" - Forces skipping to begin.
- "Stop Skipping", "Keep Skipping" - Control skipping at menus.
- "Sound Test", "Voice Test" - Test the corresponding audio channels.

The other type of hotspot is a horizontal bar. The selected images are used for the full portion of the bar, while the unselected images are used for the empty part of the bar. The known bars are:

- "Music Volume"
- "Sound Volume"
- "Voice Volume"
- "Auto-Forward Time"
- "Text Speed"

Despite the name, this function can take arbitrary displayables as well as images. The images or displayables used should be transparent to allow the navigation to show through.

## joystick_preferences layouts

The joystick_preferences layout are used to define the joystick preferences screen.

Function: | layout.classic_joystick_preferences | ():

The standard joystick preferences layout.

## standalone layouts

These provide interesting functionality to Ren'Py games, and they stand alone, so it's possible to call as many of them as you want.

Function: | layout.button_menu | ():

This changes the in-game menus to use buttons defined in the current theme.

# Defining New Layouts

This section contains some notes on how to define your own layouts. If you're not interested in defining your own labels, then you can safely ignore this section.

When it comes to defining layouts, there are two important principles you should follow:

1. layout.provides must be called with the type of layout being defined, and it must be called before any theme function is called. For example, if a navigation layout is being defined, then `layout.provides("navigation")` should be called.
2. The layout needs to implement the contract of it's layout kind. These contracts are described below.

While the default layouts are enable through the use of functions on the `layout` object, this is by no means the only way to supply a layout. For a user-defined layout, it should be enough to place the call to layout.provides in an `init -2 python` block, with the rest of the code residing in init blocks or labels as appropriate.

If your layout defines new configuration variables, you should set config.locked to False before creating them, and then back to True when you're done creating them. We suggest that configuration variables should be prefixed with the type of layout they're used by. Load/save variables should be prefixed by `config.load_save_`, navigation variables with `config.navigation_` and so on. (For compatibility reasons, the default layouts do not conform to this standard.)

## main_menu layouts

Main_menu layouts need to call:

        layout.provides('main_menu')

Main menu layouts are expected to define a `main_menu_screen` label. This label is expected to:

- Show a fullscreen window of type mm_root. The code to do this is:

        python:
            ui.window(style='mm_root')
            ui.null()

- Create a keymap that disables the game_menu binding. (This is optional, but it can prevent transitions from the main menu to itself.)

        python:
            ui.keymap(game_menu=ui.returns(None))

- Displays the main menu on the screen. How this is done is generally up to the layout itself, but we strongly recommend you use config.main_menu to control the generation of the menu. Note that the documentation for config.main_menu says that bare strings cause a jump out of context to occur; use ui.jumpsoutofcontext to implement this properly. Using config.main_menu ensures that your layout will work even with extensions (like image galleries) that add options to the main menu.

## navigation layouts

Navigation layouts need to call:

        layout.provides('navigation')

Navigation layouts are expected to redefine the layout.navigation function. The way to do this is to first define a function in an `init python` block, and then assign that function to layout.navigation.

Function: | layout.navigation | (screen):

This function is intended to be set by a navigation layout. It's legitimate to replace this function with one of your choosing, provided the signature remains the same.

This function displays the navigation on the game menu. It's expected to set the background of the game menu. If screen is not None, it's also expected to display the navigation buttons defined in config.game_menu, highlighting the one named in screen.

It's suggested that your navigation function use config.game_menu to determine the game menu buttons to show to the user. (But note that the game menu is less often extended then the main menu, so this is correspondingly less important.)

## load_save layouts

Load/save layouts need to call:

        layout.provides('load_save')

Load/save layouts are expected to provide two labels: `load_screen` and `save_screen`, which are used to load and save, respectively. These screens should call layout.navigation with "load" or "save" as an argument, and are otherwise unconstrained in how they provide loading and saving functionality.

Please see the section on load/save functions for the functions that would be used to actually implement these screens.

## yesno_prompt layouts

Yes/no prompt layouts need to call:

        layout.provides('yesno_prompt')

Navigation layouts are expected to redefine the layout.yesno_prompt function. The way to do this is to first define a function in an `init python` block, and then assign that function to layout.yesno_prompt.

Function: | layout.yesno_prompt | (screen, message):

This function is intended to be customized by yesno_prompt layouts. It can be replaced by another function, provided the signature remains the same.

screen - The screen button that should be highlighted when this prompt is shown. If None, then no game menu navigation is shown.

message - The message that is shown to the user to prompt them to answer yes or no.

This function returns True if the user clicks Yes, or False if the user clicks No.

## preferences layouts

Preferences layouts need to call:

        layout.provides('preferences')

The preferences layout should define a `preferences_screen` label, which contains code to set the preferences. This screen should call layout.navigation("preferences"). It then needs to allow the user to alter the preferences, using the variables and functions defined in the preferences section. Finally, it should:

- Allow the user to begin skipping, by jumping to the `_begin_skipping` label.
- Allow the user to go to the joystick preferences, by jumping to the `joystick_preferences_screen` label.

## joystick_preferences layouts

Joystick preferences layouts need to call:

        layout.provides('joystick_preferences')

The preferences layout should define a `joystick_preferences_screen` label, which contains code to set the joystick preferences. This screen should call layout.navigation("joystick_preferences"). Unfortunately, the joystick preferences are undocumented at this time.

## Example

An example of a new main_menu layout:

    init -2 python:
        layout.provides('main_menu')

        style.mm_button = Style(style.button, help="main menu button")
        style.mm_button_text = Style(style.button_text, help="main menu button (text)")
        style.mm_button.size_group = "mm"

    label main_menu_screen:
        python:
            layout.button(u"Start Game", "mm", clicked=ui.jumpsoutofcontext('start'), xpos=400, ypos=400)
            layout.button(u"Continue Game", "mm", clicked=_intra_jumps("load_screen", "main_game_transition"), xpos=450, ypos=430)
            layout.button(u"Preferences", "mm", clicked=_intra_jumps("preferences_screen", "main_game_transition"), xpos=500, ypos=460),
            layout.button(u"Quit", "mm", clicked=ui.jumps("_quit"), xpos=550, ypos=490)

            ui.interact()

documentation index ◦ reference manual ◦ function index