VgaGames4

VgaGames4 - actionstack man-pages

[.. upper level ..]

# Actionstack functions

A stack. Functions to activate just one object(-instance) of many. Their main purpose are dice games. Example: -------- There are three objects: - dice - selecting a character - moving the character As vg4->object->call_run() calls the f_run() functions of all objects, there must be a distinction which object-instance shall be actually active: - either the dice picks a number - or the player selects a character - or the character moves So each f_run() function must check whether it is actually active by calling vg4->actionstack->get() and checking the returned name_id. At first the dice-object is activated by a vg4->actionstack->push(). If the dice has picked a number it calls vg4->actionstack->push() to activate the object moving the character. But this object does not know which character to move, so it calls vg4->actionstack->push() to activate the object selecting a character. This object selects a character and calls vg4->actionstack->parent() to set the selected character into the parent's data, then it calls vg4->actionstack->pop(). Now the object moving the character is activated again which moves the character and calls a vg4->actionstack->pop() to activate the dice-object again. In short: - push(dice): the dice picks a number - push(move): a character shall be moved, but which? - push(select): select the character and set the selection into the parent data (move) - pop(select): which activates move, which moves the selected character - pop(move): which activates dice, which rolls again

- Functions
- vg4->actionstack->freefunction()
  Set function for freeing data of actionstack-elements.
- vg4->actionstack->push()
  Push element onto actionstack.
- vg4->actionstack->get()
  Get upmost element from actionstack.
- vg4->actionstack->parent()
  Get parent of upmost element from actionstack.
- vg4->actionstack->pop()
  Remove upmost element from actionstack.
- vg4->actionstack->clear()
  Clear actionstack.

## Example

    /* just a demonstration how to use actionstack */

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <sys/types.h>
    #include <unistd.h>
    #include <errno.h>
    #include <vgagames4.h>

    static void do_free(unsigned int, void *);

    /* keys */
    struct {
      int k_quit;
      int k_push;
      int k_get;
      int k_pop;
      int k_clear;
    } kref;

    /* free function for element-data */
    static void
    do_free(unsigned int name_id, void *vdata)
    {
      if (vdata != NULL) {
        printf("REMOVE: %u:%s\n", name_id, (char *)vdata);
        free(vdata);
      }
    }

    int main(int argc, char **argv) {

      (void)argc; (void)argv;

      if (!VG_init("test")) { exit(1); }
      if (!vg4->window->open(VG_WINDOW_SIZE_LOW, VG_WINDOW_SCALE_NONE)) { VG_dest(); exit(1); }
      vg4->window->flush();

      /* set keys */
      if ((kref.k_quit = vg4->input->key_insert("Quit", VG_FALSE, VG_FALSE)) == 0) { VG_dest(); exit(1); }
      vg4->input->key_setkbd(kref.k_quit, VG_INPUT_KBDCODE_Q);
      if ((kref.k_push = vg4->input->key_insert("PUSH", VG_FALSE, VG_FALSE)) == 0) { VG_dest(); exit(1); }
      vg4->input->key_setkbd(kref.k_push, VG_INPUT_KBDCODE_UCURS);
      if ((kref.k_get = vg4->input->key_insert("GET+PARENT", VG_FALSE, VG_FALSE)) == 0) { VG_dest(); exit(1); }
      vg4->input->key_setkbd(kref.k_get, VG_INPUT_KBDCODE_SPACE);
      if ((kref.k_pop = vg4->input->key_insert("POP", VG_FALSE, VG_FALSE)) == 0) { VG_dest(); exit(1); }
      vg4->input->key_setkbd(kref.k_pop, VG_INPUT_KBDCODE_DCURS);
      if ((kref.k_clear = vg4->input->key_insert("CLEAR", VG_FALSE, VG_FALSE)) == 0) { VG_dest(); exit(1); }
      vg4->input->key_setkbd(kref.k_clear, VG_INPUT_KBDCODE_TAB);

      /* set free function */
      vg4->actionstack->freefunction(do_free);

      /* info */
      printf("\n");
      printf("Keys:\n");
      printf(" - quit:  Q\n");
      printf(" - push:  cursor up\n");
      printf(" - get:   space-key\n");
      printf(" - pop:   cursor down\n");
      printf(" - clear: tabulator\n");
      printf("\n");

      /* Gameloop */
      for (;;) {
        if (!vg4->input->update(VG_TRUE)) { break; }
        if (vg4->input->key_newpressed(kref.k_quit)) { break; }

        /* push element */
        if (vg4->input->key_newpressed(kref.k_push)) {
          /* element-data shall be just one of the following words */
          static char dbuf[][16] = { "the", "dog", "is", "running", "fast" };
          /* get a random name_id which shall correspond to the element-data */
          unsigned int name_id = vg4->random->get(NULL, 1, 5);
          /* push element */
          printf("ADD: %u:%s\n", name_id, dbuf[name_id - 1]);
          vg4->actionstack->push(name_id, strdup(dbuf[name_id - 1]));
        }

        /* get upmost and parent element */
        if (vg4->input->key_newpressed(kref.k_get)) {
          void *vdata;
          unsigned int name_id;
          printf("\n");
          vdata = vg4->actionstack->get(&name_id);
          if (name_id != 0) { printf("Upmost: %u:%s\n", name_id, (char *)vdata); }
          vdata = vg4->actionstack->parent(&name_id);
          if (name_id != 0) { printf("Parent: %u:%s\n", name_id, (char *)vdata); }
          printf("\n");
        }

        /* pop upmost element */
        if (vg4->input->key_newpressed(kref.k_pop)) {
          vg4->actionstack->pop();
        }

        /* clear actionstack */
        if (vg4->input->key_newpressed(kref.k_clear)) {
          vg4->actionstack->clear();
        }

        /* wait */
        vg4->misc->wait_time(50);
      }

      /* destroy and exit */
      VG_dest();
      exit(0);
    }