VG3_sysmenu_insert_dataentry()

[modified in version 1.3]

Insert a data-entry into the system-menu.

SYNTAX

void VG3_sysmenu_insert_dataentry(struct vg3_sysmenu *sysm, struct vg3_sysmenu_submenu *submenu, int inr, int jid, int (*setf)(struct vg3_sysmenu *sysm, int inr, int key_pressed, int jid, int gc_pressed), int (*getf)(struct vg3_sysmenu *sysm, int inr, int jid, struct vg3_text *rkey, struct vg3_text *rval), const char *info, int cursorflag)

FUNCTION PARAMETERS

sysm	System-menu-struct
submenu	Where to put it: sub-menu or NULL = main menu
inr	Arbitrary number for the callback-functions getf and setf, if they were called from different menu-entries, e.g. serial number
jid	Joystick-ID or 0 = irrelevant This parameter is only useful, if the entry is based on a certain input-device
setf	Callback-function for setting data into this data-entry. Parameters: - *sysm: as parameter sysm* - *inr: as parameter inr* - *key_pressed: pressed key of keyboard (VGAG3_KEYS) - jid: as parameter jid* - *gc_pressed: pressed button/axis of gamecontroller/joystick (VGAG3_GCS or joystick-input-keynumber) Return value:* - 0: OK - 1: return to parent menu - 2: exit game
getf	Callback-function for retrieving data from this data-entry. Parameters: - *sysm: as parameter sysm* - *inr: as parameter inr* - *jid: as parameter jid* - *rkey: for returning key of data-entry (pointer elements must not be allocated) - rval*: for returning value of data-entry (pointer elements must not be allocated)
info	Short description text for menu-window for this entry or NULL = no text
cursorflag	Whether showing arrows when setting data, meaning to use cursor keys to elect items: - 0: don't show - VGAG3_SYSMENU_CURS_LEFT_RIGHT: show arrows left and right - VGAG3_SYSMENU_CURS_UP_DOWN: show arrows up and down - (VGAG3_SYSMENU_CURS_LEFT_RIGHT \| VGAG3_SYSMENU_CURS_UP_DOWN): show all arrows

DESCRIPTION

Insert a data-entry into the system-menu. The entry is inserted into the sub-menu submenu. If the menu-window for this data-entry is entered, the callback-function setf is called initially with key_pressed=VGAG3_KEY_NOKEY and gc_pressed=VGAG3_GC_NOKEY. So it is possible to return 2 (for exit game) without waiting for input. When a key of the keyboard or a button/axis of the gamecontroller/joystick belonging to jid is pressed, the callback-function setf is called again passing the pressed key/button/axis. This can be evaluated and an element of the struct of individual menu-entries, which has been passed by VG3_sysmenu_new() with parameter vdata can be set. The escape-key must not be evaluated, pressing it returns back to the parent menu. The callback-function setf should return - 0 to stay in the menu-window for this entry - 1 to return to the parent menu - 2 to exit the game The callback-function getf is called automatically to retrieve the data set by setf using the same element of the struct of individual menu-entries. The cursorflags just specify whether and which arrows are to be shown to indicate using cursor-keys for selecting values.

EXAMPLE

Using cursor keys UP and DOWN to increment and decrement a percent value:

  struct my_menu {
    int percent;
  };

  main() {
    struct vg3_window *wstruct;
    struct vg3_sysmenu *sysm;
    struct my_menu mymenu;

    [... open window etc. ...]

    sysm = VG3_sysmenu_new(wstruct, &mymenu, int VGAG3_COLOR_YELLOW, VGAG3_COLOR_BLUE);
    VG3_sysmenu_insert_dataentry(sysm, NULL, 0, 0, setf_mymenu, getf_mymenu, NULL, VGAG3_SYSMENU_CURS_UP_DOWN);
    mymenu.percent = 0;

    [...]
  }

  /* callback-function for setting data */
  static int
  setf_mymenu(struct vg3_sysmenu *sysm, int inr, int key_pressed, int jid, int gc_pressed)
  {
    struct my_menu *mymenu = (struct my_menu *)sysm->vdata;

    if (key_pressed == VGAG3_KEY_NOKEY && gc_pressed == VGAG3_GC_NOKEY) { return 0; }  /* entering call */

    if (key_pressed == VGAG3_KEY_UCURS) { mymenu->percent++; }  /* cursor up: increment value */
    if (key_pressed == VGAG3_KEY_DCURS) { mymenu->percent--; }  /* cursor down: decrement value */

    if (key_pressed == VGAG3_KEY_ENTER) { return 1; }  /* back to parent menu (additional to escape-key) */

    return 0;
  }

  /* callback-function for retrieving data
   * (automatically called to show values in the menu-window of this data-entry)
   */
  static void
  getf_mymenu(struct vg3_sysmenu *sysm, int inr, int jid, struct vg3_text *rkey, struct vg3_text *rval)
  {
    struct my_menu *mymenu = (struct my_menu *)sysm->vdata;
    static char keybuf[64], valbuf[64];  /* using static is ok, as it will be copied immediately */

    /* key of data-entry: fixed string */
    snprintf(keybuf, sizeof(keybuf), "Percent number");
    VGAG3_TEXT_ATTRIBUTES_SET(rkey, NULL, '\n', 0, keybuf);

    /* value of data-entry: percent value */
    snprintf(valbuf, sizeof(valbuf), "%d%%", mymenu->percent);
    VGAG3_TEXT_ATTRIBUTES_SET(rval, NULL, 0, 0, valbuf);
  }