[.. 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.

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