VgaGames4

VgaGames4 - canvas man-pages

[.. upper level ..]

# Canvas functions

A canvas is a composition of user-input-elements in a graphical surface. So the user will be able to select an item from a list or to input text. The canvas consists of a textfile, which describes the user-input-element (named canvas-items), their positions and configurations (see vg4->canvas->load()). Additionally variables can be used, which are passed via vg4->canvas->load(). There are functions to set and get values of canvas-items. When executing the canvas via vg4->canvas->exec() returns, the values of all canvas-items can be queried, not only of the user-selected one, and used for the decision to re-execute the canvas or not. For predefined canvasses, see dialog. See also the command: vg4 canvas -h

- General functions
- vg4->canvas->load()
  Load canvas from file.
- vg4->canvas->reload()
  Reload canvas with actual variable-values.
- vg4->canvas->destroy()
  Destroy canvas.
- vg4->canvas->destroyall()
  Destroy all canvasses.
- vg4->canvas->getname()
  Get filename of a canvas.
- vg4->canvas->exec()
  Execute canvas.
- vg4->canvas->subcanvas()
  Prepare for drawing a new sub-canvas upon a parent-canvas.
- vg4->canvas->set_mouse()
  Set default mouse-images for all canvasses.
- vg4->canvas->set_activated()
  Set canvas-item to be activated.
- vg4->canvas->disable()
  Disable or enable canvas-item.
- vg4->canvas->is_disabled()
  Return whether canvas-item is disabled.
- Canvas-item switch
- vg4->canvas->switch_set()
  Set switch to ON or OFF.
- vg4->canvas->switch_get()
  Get whether switch is ON or OFF.
- Canvas-item selection-list
- vg4->canvas->list_clear()
  Clear selection-list.
- vg4->canvas->list_add()
  Add list-item to selection-list.
- vg4->canvas->list_set_activated()
  Activate list-item of a selection-list.
- vg4->canvas->list_get_activated()
  Get activated list-item of a selection-list.
- Canvas-item selection-chain
- vg4->canvas->chain_clear()
  Clear selection-chain.
- vg4->canvas->chain_add()
  Add chain-item to selection-chain.
- vg4->canvas->chain_disable()
  Disable or enable chain-item of a selection-chain.
- vg4->canvas->chain_set_activated()
  Activate chain-item of a selection-chain.
- vg4->canvas->chain_get_activated()
  Get activated chain-item of a selection-chain.
- Canvas-item textline-input
- vg4->canvas->input_set_text()
  Set text of a textline-input.
- vg4->canvas->input_get_text()
  Get text of a textline-input.
- Canvas-item percent-bar
- vg4->canvas->bar_set_percent()
  Set percent value of a percent-bar.
- vg4->canvas->bar_get_percent()
  Get percent value of a percent-bar.
- Canvas-item map with selectable areas
- vg4->canvas->map_area_get_selected()
  Get selected area of a map.
- vg4->canvas->map_area_disable()
  Disable or enable an area of a map.
- Canvas-item text box for showing text
- vg4->canvas->text_set()
  Set text of a text-box.
- Canvas-item unique-key-pressing
- vg4->canvas->uniqkey_set()
  Set key-code of a unique-key-pressing for keyboard or a gamecontroller.
- vg4->canvas->uniqkey_get()
  Get key-code of a unique-key-pressing.
- Canvas-item non-selectable image or sprite
- vg4->canvas->image_setimage()
  (Re)Set image to show
- vg4->canvas->image_setsprite()
  (Re)Set sprite to show

## Example

Top-canvas
Select yellow sunnyboy from selection-list
Select red sunnyboy from selection-chain
Sub-canvas

    example.c

    /* select a sunnyboy from a list or a chain */

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

    /* show sub-canvas containing information of selected sunnyboy */
    static void
    show_subcanvas(struct VG_Canvas *cvas_top, const char *selected_sb)
    {
      struct VG_Canvas *cvas_sub;
      struct VG_Hash *hvar;
      struct VG_Position possub;
      struct VG_ImagecopyAttrPixel iattr_pixel;
      const char *selname;

      /* set variables */
      hvar = vg4->hash->create();
      vg4->hash->setstr(hvar, "sb_color", selected_sb);

      /* load canvas with variables */
      cvas_sub = vg4->canvas->load("example-sub.cvas", hvar);
      vg4->hash->destroy(hvar);
      if (cvas_sub == NULL) { return; }

      /* get position of sub-canvas and set background with reduced brightness */
      VG_IMAGECOPY_ATTRPIXEL_DEFAULT(&iattr_pixel);
      iattr_pixel.brightness = 60;
      possub = vg4->canvas->subcanvas(cvas_top, &iattr_pixel);

      /* execute sub-canvas */
      if (!vg4->canvas->exec(cvas_sub, &possub, &selname)) { return; }

      /* as there is just an OK-button, the selection is ignored */
    }

    int main(int argc, char **argv) {
      struct VG_Canvas *cvas_top;
      const char *selname;
      const char *selected_sb;

      (void)argc; (void)argv;

      /* initialize and open window */
      if (!VG_init("test")) { exit(1); }
      if (!vg4->window->open(VG_WINDOW_SIZE_LOW, VG_WINDOW_SCALE_BEST)) { VG_dest(); exit(1); }

      /* load canvas */
      cvas_top = vg4->canvas->load("example-top.cvas", NULL);
      if (cvas_top == NULL) { VG_dest(); exit(1); }

      /* fill selection-list */
      vg4->canvas->list_add(cvas_top, "sb_list", "Red sunnyboy", "sb_red");
      vg4->canvas->list_add(cvas_top, "sb_list", "Yellow sunnyboy", "sb_yellow");
      vg4->canvas->list_add(cvas_top, "sb_list", "Blue sunnyboy", "sb_blue");

      /* set switch to ON and disable selection-chain */
      vg4->canvas->switch_set(cvas_top, "list_or_chain", VG_TRUE);
      vg4->canvas->disable(cvas_top, "sb_chain", VG_TRUE);

      /* contains the color of the selected sunnyboy */
      selected_sb = NULL;

      for (;;) {
        /* execute canvas */
        if (!vg4->canvas->exec(cvas_top, NULL, &selname)) { VG_dest(); exit(1); }
        if (selname == NULL) { break; }  /* cancelled via escape-key or cancel-button */

        /* act according to selection */

        if (*selname == '\0') {  /* no selection, but return-key pressed */
          /* no action, re-execute canvas */
          ;

        } else if (strcmp(selname, "list_or_chain") == 0) {  /* switch selected */
          /* enable or disable list and chain according to switch */
          VG_BOOL is_on = vg4->canvas->switch_get(cvas_top, selname);
          if (is_on) {
            vg4->canvas->disable(cvas_top, "sb_list", VG_FALSE);
            vg4->canvas->disable(cvas_top, "sb_chain", VG_TRUE);
          } else {
            vg4->canvas->disable(cvas_top, "sb_list", VG_TRUE);
            vg4->canvas->disable(cvas_top, "sb_chain", VG_FALSE);
          }

        } else if (strcmp(selname, "sb_list") == 0) {  /* item selected from list */
          /* set selected_sb to color of selected list-item */
          const char *listkey = vg4->canvas->list_get_activated(cvas_top, selname);
          if (listkey != NULL) {
            if (strcmp(listkey, "sb_red") == 0) { selected_sb = "red"; }
            else if (strcmp(listkey, "sb_yellow") == 0) { selected_sb = "yellow"; }
            else if (strcmp(listkey, "sb_blue") == 0) { selected_sb = "blue"; }
          }

        } else if (strcmp(selname, "sb_chain") == 0) {  /* item selected from chain */
          /* set selected_sb to color of selected chain-item */
          const char *chainkey = vg4->canvas->chain_get_activated(cvas_top, selname);
          if (chainkey != NULL) {
            if (strcmp(chainkey, "sb_red") == 0) { selected_sb = "red"; }
            else if (strcmp(chainkey, "sb_yellow") == 0) { selected_sb = "yellow"; }
            else if (strcmp(chainkey, "sb_blue") == 0) { selected_sb = "blue"; }
          }
        }

        /* if sunnyboy was selected, show sub-canvas and exit */
        if (selected_sb != NULL) {
          show_subcanvas(cvas_top, selected_sb);
          break;
        }
      }

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

    example-top.cvas

    # Top-canvas for selecting a sunnyboy

    [MAIN]
    %{imgfile[
      utag-title=10+230,8+12
      utag-sw_list=20+80,37+16
      utag-swt=109+32,37+16
      utag-sw_chain=155+80,37+16
      utag-sb_list=20+130,64+75
      utag-sb_chain=166+64,69+64
      utag-cancel=100+50,150+20
     ]: images/example.top.bmp%}

    [MOUSE]
    disable: 0

    [FONT]
    sys:low

    # title
    [CV-TEXT]
    name: title
    position-itag: title
    default-text: Select sunnyboy
    text.orientation: center+left
    text.v-orientation: center
    text.fgcolor: 0xffff00
    text.nowrap: 1

    # text left of switch showing "List"
    [CV-TEXT]
    name: sw_list
    position-itag: sw_list
    default-text: List
    text.fgcolor: 0x888888
    text.orientation: right
    text.v-orientation: center

    # switch to select between list and chain
    [CV-SWITCH]
    name: list_or_chain
    position-itag: swt
    img-on-dfl: img:images/swt_on-dfl.bmp
    img-on-act: img:images/swt_on-act.bmp
    img-off-dfl: img:images/swt_off-dfl.bmp
    img-off-act: img:images/swt_off-act.bmp

    # text right of switch showing "Chain"
    [CV-TEXT]
    name: sw_chain
    position-itag: sw_chain
    default-text: Chain
    text.fgcolor: 0x888888
    text.orientation: left
    text.v-orientation: center

    # selection-list
    [CV-LIST]
    name: sb_list
    position-itag: sb_list
    spacing=1+
    bgcolor-dfl=0x0000cc
    bgcolor-act=0xcccc00
    fgcolor-dfl = 0xcccc00
    fgcolor-act = 0x0000cc

    # selection-chain
    [CV-CHAIN]
    name: sb_chain
    position-itag: sb_chain
    element.sb_red: img:images/sb_red.bmp
    element.sb_yellow: img:images/sb_yellow.bmp
    element.sb_blue: img:images/sb_blue.bmp

    # cancel-button
    [CV-BUTTON]
    name: cancel
    position-itag: cancel
    is-cancel: 1
    img-dfl: img:images/button-cancel-up.bmp
    img-sel: img:images/button-cancel-down.bmp

    example-sub.cvas

    # Sub-canvas for showing a text which sunnyboy has been selected

    [MAIN]
    %{box[boxwidth=150 boxheight=60 bgcolor=0x417dbd
     utag-text=10+130,10+30
     utag-done=50+50,45+10
     ]:
    %}

    [MOUSE]
    disable: 0

    [FONT]
    sys:low

    [VAR-DEFAULT]
    var.sb_color:

    # text
    [CV-TEXT]
    name: text
    position-itag: text
    default-text: You have selected the %{var: sb_color%} sunnyboy
    text.fgcolor: 0xbbbb00
    velo: 2

    # Done-button
    [CV-BUTTON]
    name: done
    position-itag: done
    img-dfl: img:images/button-done-up.bmp
    img-sel: img:images/button-done-down.bmp