VgaGames 3 - System-menu man-pages

[.. upper level ..]

VG3_sysmenu_insert_dataentry()

Insert a data-entry into the system-menu.
SYNTAX
void VG3_sysmenu_insert_dataentry(struct vg3_sysmenu *sysm, void *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)

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

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.

EXAMPLE

Using cursor keys UP and DOWN to increment and decrement a percent value:
  struct my_menu {
    int percent;
  };

  main() {
    void *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);
    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 very soon */

    /* 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);
  }

SEE ALSO
VG3_sysmenu_insert_menuentry() VG3_sysmenu_insert_textentry()