UI Actions

UI Actions

Introduction

The UI actions are a way to trigger specific emulators actions from menu items, hotkeys or controller buttons without code duplication and letting VICE deal with issues like threading and avoiding showing multiple dialogs or retriggering actions that haven’t finished yet.

UI actions are managed through an API living in src/arch/shared/uiactions.h. Actions are triggered by specifying action ID in menu items, or by using an action name in hotkey and joy map files (which VICE translates to IDs).

The file src/arch/shared/uiactions.h contains the UI action IDs available, while the file src/arch/shared/uiactions.c contains a table mapping these IDs to action names.

New actions can be created by adding a unqiue ID in the header file and an entry (with a unique name) in the aformentioned table in the source file. An action handler is required to implement the action’s logic, this handler is a callback function that gets passed some information about itself (the entry in the table, an ui_action_map_t*). The action will need to be registered with the UI actions system via ui_actions_register(). (See below)

Basic API usage

The basic functions and types used by the UI actions are relatively simple. A selection of the most used functions and types is listed here.

General functions dealing with the UI actions system itself:

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

VICE will call ui_actions_init() and ui_actions_shutdown(), and calling ui_actions_set_dispatch() is optional (more on this later).

Functions dealing with individual actions:

void        ui_action_trigger         (int action);
void        ui_action_finish          (int action);
int         ui_action_get_id          (const char *name);
const char *ui_action_get_name        (int action);
const char *ui_action_get_desc        (int action);
char *      ui_action_get_hotkey_label(int action);