User:Compyx

Personal notes, observations and rants

SDL UI code

Since I'm tasked with updating the SDL code to use the generic UI actions and hotkeys code and use those UI actions from the menu items, hotkeys and custom joystick mappings, and the code is poorly documented, I'll be writing down some observations on how the SDL UI code works here, and some notes on how to move the code to using the shared UI actions and hotkeys code.

Menu items

Current API

Menu items are defined with the type ui_menu_entry_t (in uimenu.h):

typedef struct ui_menu_entry_s {
    char *string;
    ui_menu_entry_type_t type;
    ui_callback_t callback;
    ui_callback_data_t data;
    ui_menu_status_type_t status;
} ui_menu_entry_t;

String

The string is used to display the item text in the menus. It is used by sdl_ui_display_item() to render a menu item.

Type

The type determines what to do when the user activates the item, types include radio buttons, toggle buttons, submenus, and dialogs. The various menu item types are defined as:

typedef enum {
    /* Text item (no operation): if data == 1 text colors are inverted */
    MENU_ENTRY_TEXT = 0,

    /* Resource toggle: no UI needed, callback is used */
    MENU_ENTRY_RESOURCE_TOGGLE,

    /* Resource radio: no UI needed, callback is used, data is the resource value */
    MENU_ENTRY_RESOURCE_RADIO,

    /* Resource int: needs UI, callback is used */
    MENU_ENTRY_RESOURCE_INT,

    /* Resource string: needs UI, callback is used */
    MENU_ENTRY_RESOURCE_STRING,

    /* Submenu: needs UI, data points to the submenu */
    MENU_ENTRY_SUBMENU,

    /* Dynamic submenu: needs UI, data points to the submenu, hotkeys disabled */
    MENU_ENTRY_DYNAMIC_SUBMENU,

    /* Custom dialog: needs UI */
    MENU_ENTRY_DIALOG,

    /* Other: no UI needed */
    MENU_ENTRY_OTHER,

    /* Other: no UI needed */
    MENU_ENTRY_OTHER_TOGGLE
} ui_menu_entry_type_t;

Callback and Data

When an item is activated the callback is called with data as its argument. The return value of the callback (a const char*) is used to update the item's state or to exit the UI (more on that later).

Callbacks are prototyped in uimenu.h:

typedef const char *(*ui_callback_t)(int activated, ui_callback_data_t param);

These callbacks are triggered both by displaying an item (activated == 0) and by activating an item (activated == 1). The return value is used to either display something in front of the item, like sdl_menu_text_tick (a tick mark), nothing (NULL) or the special sdl_menu_text_exit_ui ("\1") which means the activation succeeded and the UI must be exited (for example when triggering soft/hard reset). The param argument is the data field of the menu item definition.

Some helper macros and functions exit for the callbacks in menu_common.{c,h}.

#define UI_MENU_CALLBACK(name) \
    const char *name(int activated, ui_callback_data_t param)

#define UI_MENU_DEFINE_TOGGLE(resource)                              \
    static UI_MENU_CALLBACK(toggle_##resource##_callback)            \
    {                                                                \
        return sdl_ui_menu_toggle_helper(activated, #resource);      \
    }

#define UI_MENU_DEFINE_RADIO(resource)                                \
    static UI_MENU_CALLBACK(radio_##resource##_callback)              \
    {                                                                 \
        return sdl_ui_menu_radio_helper(activated, param, #resource); \
    }

#define UI_MENU_DEFINE_STRING(resource)                                \
    static UI_MENU_CALLBACK(string_##resource##_callback)              \
    {                                                                  \
        return sdl_ui_menu_string_helper(activated, param, #resource); \
    }

#define UI_MENU_DEFINE_INT(resource)                                \
    static UI_MENU_CALLBACK(int_##resource##_callback)              \
    {                                                               \
        return sdl_ui_menu_int_helper(activated, param, #resource); \
    }

#define UI_MENU_DEFINE_FILE_STRING(resource)                                \
    static UI_MENU_CALLBACK(file_string_##resource##_callback)              \
    {                                                                       \
        return sdl_ui_menu_file_string_helper(activated, param, #resource); \
    }

#define UI_MENU_DEFINE_SLIDER(resource, min, max)                                  \
    static UI_MENU_CALLBACK(slider_##resource##_callback)                          \
    {                                                                              \
        return sdl_ui_menu_slider_helper(activated, param, #resource, min, max);   \
    }

These are used with a resource name as their first argument and expand to the beginning of a function definition of a callback. For example:

UI_MENU_DEFINE_RADIO(VICIIBorderMode)

static const ui_menu_entry_t vicii_border_menu[] = {
    { "Normal",
      MENU_ENTRY_RESOURCE_RADIO,
      radio_VICIIBorderMode_callback,
      (ui_callback_data_t)VICII_NORMAL_BORDERS },
    { "Full",
      MENU_ENTRY_RESOURCE_RADIO,
      radio_VICIIBorderMode_callback,
      (ui_callback_data_t)VICII_FULL_BORDERS },
    /* Debug and None snipped */
    SDL_MENU_LIST_END
};

The macro at the top expands to:

static const char *radio_VICIIBorderMode_callback(int activated, ui_callback_data_t param)
{
    return sdl_ui_menu_radio_helper(activated, param, "VICIIBorderMode");  
}

The helper function is defined (in menu_common.cas:

const char *sdl_ui_menu_radio_helper(int activated, ui_callback_data_t param, const char *resource_name)
{
    if (activated) {
        if (resources_query_type(resource_name) == RES_INTEGER) {
            resources_set_int(resource_name, vice_ptr_to_int(param));
        } else {
            resources_set_string(resource_name, (char *)param);
        }
    } else {
        int v;
        const char *w;
        if (resources_query_type(resource_name) == RES_INTEGER) {
            if (resources_get_int(resource_name, &v) == 0) {
                if (v == vice_ptr_to_int(param)) {
                    return sdl_menu_text_tick;
                }
            }
        } else {
            if (resources_get_string(resource_name, &w) == 0) {
                if (!strcmp(w, (char *)param)) {
                    return sdl_menu_text_tick;
                }
            }
        }
    }
    return NULL;
}

So if activated the resource is set to param and NULL is returned: The callback and its data are used in sdl_ui_menu_item_activate() as follows:

const char *p;

p = item->callback(1, item->data);
if (p == sdl_menu_text_exit_ui) {
    return MENU_RETVAL_EXIT_UI;
}

If not activated (when rendering the item's text), sdl_menu_text_tick is returned if the param matches the current resource value, otherwise NULL is returned. The callback and its data are used in sdl_ui_display_item() as follows:

int istoggle = 0, status = 0;
char string[3] = {0x20, 0x20, 0};

istoggle = (item->type == MENU_ENTRY_RESOURCE_TOGGLE) ||
           (item->type == MENU_ENTRY_RESOURCE_RADIO) ||
           (item->type == MENU_ENTRY_OTHER_TOGGLE);

itemdata = item->callback(0, item->data);

if ((itemdata != NULL) && !strcmp(itemdata, MENU_NOT_AVAILABLE_STRING)) {
    /* menu is not available */
    status = 2;
} else {
    /* print tick-mark for toggles and radio buttons at the start of the line */
    if (istoggle) {
        status = (itemdata == NULL) ? 0 : 1;
        string[0] = (itemdata == NULL) ? MENU_CHECKMARK_UNCHECKED_CHAR : itemdata[0];
    }
}

In the above example when clicking on "Full" the integer resource "VICIIBorderMode" is set to the data field's value VICII_FULL_BORDERS ((void*)1). When rendering the menu the callback for "Full" will return sdl_menu_text_tick and a tick mark (green filled circle) is rendered in front of the item and the other menu items' callbacks return NULL since their data doesn't match the value of "VICIIBorderMode"; which the UI code then renders as an empty red circle (MENU_CHECKMARK_UNCHECKED_CHAR).

Status

The status field is used for radio buttons to display the selection's state.

typedef enum {
    MENU_STATUS_ACTIVE = 0,
    MENU_STATUS_INACTIVE = 1,
    MENU_STATUS_NA = 2
} ui_menu_status_type_t;

Moving to UI Actions

Work is done on moving to using UI actions in the compyx/sdl-uiactions branch. Currently UI actions for menu items work and are being added.

Initialization of UI actions

1. ui_actions_init(), ui_hotkeys_resource_init() and ui_hotkeys_cmdline_init() are called in main_program() (in src/main.c), setting up the UI actions and registering hotkeys resources and command line options
2. ui_hotkeys_init() is called in kbd_arch_init() (in src/arch/sdl/kbd.c), initializing the new hotkeys system, but not used further currently
3. hotkeys_iterate_menu() is called in ui_init_finalize() to store pointers to menu items that have UI action IDs so the action handlers can use the callbacks (see below).
4. The UI action handlers are registered in ui_init_finalize()

Extending the menu code

Fields are added to the ui_menu_entry_t struct:

/* extra members for the UI actions */
int         action;       /**< UI action ID */
const char *activated;    /**< text to return when the item is activated */

The sdl_ui_menu_item_activate() function has been updated to check the action field, and if > 0, call ui_action_trigger() and return the activated field to the UI code so the UI can respond accordingly (keep going, show toggle/radio indicator, or exit UI).

The current menu callbacks are left in place for the current hotkeys/joymapping implementation. Some of these callbacks can be removed once the UI actions are also supported for the hotkeys/joymappings, others need to remain (perhaps in a slightly altered form) since they contain the implementation of dialogs such as file choosers.

In order to be able to show such a dialog and pass the correct data back to the UI code the function sdl_ui_menu_item_activate_by_action(int action) has been added. It checks whether the UI is currently active, and if so, calls sdl_ui_menu_item_activate(), otherwise it sets a CPU trap to activate the UI and trigger the menu item's callback.

Current (2023-06-22) implementation with a lot of debugging noise:

void sdl_ui_menu_item_activate_by_action(int action)
{
    ui_action_map_t *map = ui_action_map_get(action);
    printf("%s(): map = %p\n", __func__, (const void *)map);
    if (map != NULL) {
        ui_menu_entry_t *item = map->menu_item[0];
        printf("%s(): item = %p\n", __func__, (const void *)item);
        if (item != NULL) {
            if (sdl_menu_state) {
                /* menu is already active */
                printf("%s(): menu is already active, activating item\n", __func__);
                /* we can call sdl_ui_menu_item_activate() because that would trigger
                 * the action again */
                if (item->callback != NULL) {
                    item->callback(1 /*activated*/, item->data);
                } else {
                    fprintf(stderr, "%s(): error: no callback to trigger!\n", __func__);
                }
            } else {
                printf("%s(): menu is not active, calling interrupt_maincpu_trigger_trap()\n", __func__);
                interrupt_maincpu_trigger_trap(sdl_ui_trap, item);
            }
        }
    }
}

TODO

• Handling of MENU_ENTRY_RESOURCE_RADIO items with string resources, currently only integer resources are handled in the actions code for radio items.
• Handling of MENU_ENTRY_RESOURCE_INT items.
• Handling of MENU_ENTRY_RESOURCE_STRING items.

Hotkeys

Joystick mappings