UI Actions

This page explains the UI actions system used in the Gtk3 port and which is supposed to be used in the SDL port and future ports.

Rationale

In the Gtk3 UI the concept of "UI actions" was introduced to allow for a unified interface to trigger certain actions in the emulator and its user interface . UI actions decouple hotkeys from menu items so hotkeys can be defined that do not have a corresponding menu item. This interface will also allow calling actions from customizable joystick mappings, reusing the code triggered by menu items and/or hotkeys.

Since most user interactions are independent of what UI toolkit is used it makes sense to generalize these interactions and make all current and future UIs use this UI actions system. For example "soft reset" or "attach disk to unit #8" may use different dialogs, menu items or hotkeys, the underlying logic (and code) will be the same. So providing a predefined -- and extendable -- set of UI actions will aid in development of future UIs.

Mechanism

The UI actions API code resides in src/arch/uiactions.h and src/arch/uiactions.c. The code is documented using Doxygen docblocks, so the documentation can be generated with doc/mkdoxy.sh or just read in the files themselves.

UI actions are triggered using a unique ID and calling a function: ui_action_trigger(action-ID). The IDs are available in the src/arch/uiactions.h header, these are all prefixed with ACTION_.

At emulator boot the UI code calls ui_actions_init() to initialize the UI actions system, sets a UI-specific dispatch function with ui_actions_set_dispatch(dispatch-func) and registers UI action handlers with ui_actions_register(list-of-actions).

Example

Example code helps a lot, the following is taken from the Gtk3 UI code and cobbled together.

Here we have a few action handler implementations (from src/arch/gtk3/actions-machine.c. Some of this is Gtk3-specific, other handlers can be moved into generic code:

static void confirm_exit_callback(GtkDialog *dialog, gboolean result)
{
    if (result) {
        mainlock_release();
        archdep_vice_exit(0);
        mainlock_obtain();
    }
    /* mark action finished in case the user selected "No" */
    ui_action_finish(ACTION_QUIT);
}

/** \brief  Quit emulator, possibly popping up a confirmation dialog */
static void quit_action(void)
{
    int confirm = FALSE;

    resources_get_int("ConfirmOnExit", &confirm);
    if (!confirm) {
        ui_action_finish(ACTION_QUIT);
        archdep_vice_exit(0);
        return;
    }

    vice_gtk3_message_confirm(
            confirm_exit_callback,
            "Exit VICE",
            "Do you really wish to exit VICE?");
}

/** \brief  Open the monitor */
static void monitor_open_action(void)
{
    int server = 0;

    /* don't spawn the monitor if the monitor server is running */
    resources_get_int("MonitorServer", &server);
    if (server == 0) {
        vsync_suspend_speed_eval();
        if (ui_pause_active()) {
            ui_pause_enter_monitor();
        } else {
            monitor_startup_trap();
        }
    }
}

/** \brief  Trigger soft reset of the machine */
static void reset_soft_action(void)
{
    machine_trigger_reset(MACHINE_RESET_MODE_SOFT);
    ui_pause_disable();
}

/** \brief  Trigger hard reset of the machine */
static void reset_hard_action(void)
{
    machine_trigger_reset(MACHINE_RESET_MODE_HARD);
    ui_pause_disable();
}

/** \brief  Toggle PET userport diagnostic pin */
static void diagnostic_pin_toggle_action(void)
{
    int active = 0;

    resources_get_int("DiagPin", &active);
    resources_set_int("DiagPin", active ? 0 : 1);
}

This is the list of action handlers defined above we'll be passing to ui_actions_register():

/** \brief  List of machine-related actions */
static const ui_action_map_t machine_actions[] = {
    {
        .action = ACTION_QUIT,
        .handler = quit_action,
        .blocks = true,
        .dialog = true
    },
    {
        .action = ACTION_MONITOR_OPEN,
        .handler = monitor_open_action,
        .uithread = true
    },
    {
        .action = ACTION_RESET_SOFT,
        .handler = reset_soft_action
    },
    {
        .action = ACTION_RESET_HARD,
        .handler = reset_hard_action
    },
    {
        .action = ACTION_DIAGNOSTIC_PIN_TOGGLE,
        .handler = diagnostic_pin_toggle_action,
        /* no need for UI thread, the status bar code will update the LED when
         * it runs */
        .uithread = false
    },

    UI_ACTION_MAP_TERMINATOR
};

Here we initialize the UI actions system, set a dispatch handler and register the action handlers listed above:

/*
 * Helper that pushes the handler on the UI thread (details will follow)
 */
static gboolean ui_action_dispatch_impl(gpointer data)
{
    void (*handler)(void) = data;
    handler();
    return FALSE;
}

/*
 * This is the action dispatch function, whenever ui_action_trigger() is called this
 * function is called in response.
 */
static void ui_action_dispatch(const ui_action_map_t *map)
{
    if (mainlock_is_vice_thread()) {
        /* we're on the main thread, push to UI thread */
        gdk_threads_add_timeout(0, ui_action_dispatch_impl, (gpointer)(map->handler));
    } else {
        /* we're already on the UI thread */
        map->handler();
    }
}

/* Initialize UI actions */
ui_actions_init();

/* Set dispatch function */
ui_actions_set_dispatch(ui_action_dispatch);

/* Register some actions */
ui_actions_register(machine_actions);

On emulator shutdown call the UI actions shutdown function:

ui_actions_shutdown();

Some details of the API are already shown here, such as actions having certain properties: does an action pop up a dialog? does an action need to run on the UI thread? does an action need to block before it can be triggered again? This will be explained in the next section.

Hotkey files (.vhk) used in the Gtk3 UI refer to these actions with strings as IDs, for better readability, manual editing and to allow changing the internal integer IDs without breaking these files. A table of mappings of action integer IDs to strings can be found in src/arch/shared/uiactions.c, in the action_info_list[] array, at the time of writing at line 67. The table also provides descriptions of each action for use in the UI (e.g. the Gtk3 hotkeys editor widget) and a bitmask of which emulators support the action; all this is accessible through the API.

API

Main functions

The API is exposed in the src/arch/uiactions.h header. The main functions used are, as seen in the example code:

void ui_actions_init        (void);
void ui_actions_set_dispatch(void (*dispatch)(const ui_action_map_t *));
void ui_actions_register    (const ui_action_map_t *mappings);
void ui_actions_shutdown    (void);

The ui_action_map_t struct

The ui_action_map_t typedef can be found in the header as well:

/** \brief  Mapping of an action ID to a handler
 */
typedef struct ui_action_map_s {
    int    action;          /**< action ID */
    void (*handler)(void);  /**< function handling the action */

    /* modes */
    bool   blocks;          /**< action blocks (the same action cannot be
                                 triggered again until it finishes) */
    bool   dialog;          /**< action pops up a dialog (only one dialog action
                                 is allowed at a time), this implies using the
                                 UI thread */
    bool   uithread;        /**< must run on the UI thread */

    /* state */
    bool   is_busy;         /**< action is busy */
} ui_action_map_t;

Members

action

Pretty self-explanatory, an integer containing the unique ID as found in the header as ACTION_ defines.

handler

The function to be called when ui_action_trigger() is invoked. It takes no arguments and returns nothing.

blocks

A boolean indicating the same action cannot be triggered again until it is marked finished with ui_action_finish(). Actions that require user interaction or take time to complete can set this to true.

dialog

A boolean indicating the action shows a dialog. Since we don't want a user pressing a controller button mapped to "smart-attach" twenty times and the UI showing twenty dialogs, the UI action system allows only a single dialog active at a time for actions having set this to true. This flag also implies the action must be run on the UI thread.

uithread

A boolean indicating the action must be run on the UI thread. Due to the multi-threaded nature of current VICE any non-UI thread cannot directly call UI code, so any action that shows dialogs or updates UI elements must run on the UI thread. The dispatch function set by ui_actions_set_dispatch() is responsible for handling thread-safety.

is_busy

Internal flag used for blocking actions. It is set by the UI action system when ui_action_trigger() function is called with a blocking action and cleared when the ui_action_finish() function is called for that same action (inside the action handler). On registration of actions this is always set to false so just leave it out when using C99 designated initializers.