VgaGames4

VgaGames4 - canvas man-pages

[.. upper level ..]

# vg4->canvas->load()

Load canvas from file.

SYNTAX
struct VG_Canvas * vg4->canvas->load(const char *filename, struct VG_Hash *hvar)
FUNCTION PARAMETERS

filename | File to load
hvar | Hash with variable-values for text control-commands "var" and for "$(<varname>)", or NULL hash-format: - key: variable name - value: variable value (string-value) Hash will be copied, therefore may be freed after function call

RETURN VALUE
Returns loaded canvas or NULL = Error
DESCRIPTION
Load canvas from file. A canvas file is a text file, which describes the canvas. It consists of several sections containing general configuration or canvas-items. There may be following additional files: - hover.wav which is played when selecting a canvas-item Format of the canvas file: -------------------------- Comments begin with #. The filename of images, text files or sprites to be loaded in the canvas-file are searched relatively to the canvas-file. If a filename of a file to be loaded begins with a '/', it is searched from the current directory. The filename of a file to be loaded may contain variables in the format: $(<varname>). A specific automatic variable LANG contains the (fallback) locale, e.g.: img:mypath_$(LANG)/myimage.bmp The other section-parameters except TEXT (according to vg4->font->totext()) may also contain $(<varname>). The variable values are taken from the parameter hvar. Sections -------- - General configuration There are the sections: [MAIN], [MOUSE], [ARROWS], [SPRITE], [FONT], [ACTIVATED], [VAR-DEFAULT]
- [MAIN] - the main text (according to vg4->font->totext()) as background - no section-parameters but text lines Example: [MAIN] %{imgfile[ utag-title=10+120,10+24 utag-textbox=30+80,60+16 utag-button=115+50,100+20 ]: images/background.bmp%}
- [MOUSE] - (optional:) mouse image - section-parameters - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - img-dfl: default image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-act: activated image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - point-centered: which pixel of mouse-image points values: - 1 or yes or on = center of mouse-image - 0 or no or off = upper left pixel of mouse-image, (default) Example: [MOUSE] disable: 0 img-dfl: img:images/mouse-dfl.bmp img-act: img:images/mouse-act.bmp
- [ARROWS] - (optional:) arrow images - section-parameters - for each direction up, down, left, right - <direction>-dfl: image-file for default arrow value: <filename> - <direction>-act: image-file for activated arrow value: <filename> - <direction>-sel: image-file for selected arrow value: <filename> - <direction>-end: image-file for ended arrow value: <filename> Example: [ARROWS] up-dfl: images/arrow_up-dfl.bmp up-act: images/arrow_up-act.bmp up-sel: images/arrow_up-sel.bmp up-end: images/arrow_up-end.bmp down-dfl: images/arrow_down-dfl.bmp left-dfl: images/arrow_left-dfl.bmp right-dfl: images/arrow_right-dfl.bmp
- [SPRITE] - (optional, repeated:) sprite on top of the main text or a text-box - section-parameters - sprite: sprite file value: <filename> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - textbox: text-box the sprite belongs to, (missing: belongs to main text) value: <name of text-box> Example: [SPRITE] sprite: sprites/sunnyboy-yellow.sprite position-rect: 20+30,0+30
- [FONT] - (recommended:) default font - no section-parameters but fontname Example: [FONT] sys:low
- [ACTIVATED] - (optional:) activated canvas-item - no section-parameters but name of canvas-item Example: [ACTIVATED] inputtext
- [VAR-DEFAULT] - (optional:) default values of variables - section-parameters - var.<name>: (repeated for each variable:) default value for name value: <default value> Example: [VAR-DEFAULT] var.title: Input something var.button: OK
- Canvas-items There are the sections: - [CV-BUTTON] - [CV-SWITCH] - [CV-LIST] - [CV-CHAIN] - [CV-INPUT] - [CV-BAR] - [CV-MAP] - [CV-TEXT] - [CV-UNIQKEY] - [CV-IMAGE]
- [CV-BUTTON] - button - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - orientation: orientation within position-rectangle, (missing = center) values: - left = left orientated - center = centered - right = right orientated - v-orientation: vertical orientation within position-rectangle, (missing = center) values: - top = on top - center = centered - bottom = on the bottom - is-cancel: whether button is a cancel-button, (missing = no) values: - 1 or yes or on = yes - 0 or no or off = no - img-dfl: default image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-act: activated image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-sel: selected image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file Example: [CV-BUTTON] name: apply position-itag: apply img-dfl: img:images/button-apply-up.bmp img-sel: img:images/button-apply-down.bmp
- [CV-SWITCH] - switch - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - orientation: orientation within position-rectangle, (missing = center) values: - left = left orientated - center = centered - right = right orientated - v-orientation: vertical orientation within position-rectangle, (missing = center) values: - top = on top - center = centered - bottom = on the bottom - is-on: whether switch is ON, (missing = OFF) values: - 1 or yes or on = ON - 0 or no or off = OFF - img-on-dfl: default image/text/sprite file for ON values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-on-act: activated image/text/sprite file for ON values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-off-dfl: default image/text/sprite file for OFF values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file - img-off-act: activated image/text/sprite file for OFF values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file Example: [CV-SWITCH] name: mute position-itag: mute img-on-dfl: img:images/vol-mute-dfl.bmp img-on-act: img:images/vol-mute-act.bmp img-off-dfl: img:images/vol-unmute-dfl.bmp img-off-act: img:images/vol-unmute-act.bmp
- [CV-LIST] - selection-list - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - spacing: space in pixels between list-items, (default: 0), may have appended a '+' to arrange few list-items in the box value: <space in pixels>[+] - font: font name, (missing: default font) value: <font name> - orientation: orientation of list-items values: - left = left orientation (default) - center = centered orientation - right = right orientation - block = block orientation - bgcolor: background color for background value: <0xRRGGBB> or transparent (default) - bgcolor-dfl: background color for default list-items value: <0xRRGGBB> or transparent (default) - bgcolor-act: background color for activated list-item value: <0xRRGGBB> or transparent (default) - fgcolor-dfl: text color for default list-items value: <0xRRGGBB>, (default = white) - fgcolor-act: text color for activated list-item value: <0xRRGGBB>, (default = white) - item1.bgcolor-dfl: background color for default odd list-items value: <0xRRGGBB> or transparent (default) - item1.bgcolor-act: background color for activated odd list-item value: <0xRRGGBB> or transparent (default) - item1.fgcolor-dfl: text color for default odd list-items value: <0xRRGGBB>, (default = white) - item1.fgcolor-act: text color for activated odd list-item value: <0xRRGGBB>, (default = white) - item2.bgcolor-dfl: background color for default even list-items value: <0xRRGGBB> or transparent (default) - item2.bgcolor-act: background color for activated even list-item value: <0xRRGGBB> or transparent (default) - item2.fgcolor-dfl: text color for default even list-items value: <0xRRGGBB>, (default = white) - item2.fgcolor-act: text color for activated even list-item value: <0xRRGGBB>, (default = white) Example: [CV-LIST] name: filelist position-itag: list spacing=1 item1.bgcolor-dfl=0xffffff item1.bgcolor-act=0xffffff item2.bgcolor-dfl=0xeeeeee item2.bgcolor-act=0xeeeeee fgcolor-dfl = 0x111111 fgcolor-act = 0xcc0000
- [CV-CHAIN] - selection-chain - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - orientation: orientation within position-rectangle, (missing = center) values: - left = left orientated - center = centered - right = right orientated - v-orientation: vertical orientation within position-rectangle, (missing = center) values: - top = on top - center = centered - bottom = on the bottom - element.<name>: (repeated for each image to insert:) image/text/sprite file values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file Example: [CV-CHAIN] name: characterselect position-itag: csel element.fred: img:images/fred.bmp element.jeff: img:images/jeff.bmp element.susan: img:images/susan.bmp
- [CV-INPUT] - textline-input - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - font: font name, (missing: default font) value: <font name> - maxchar: maximum number of input-characters value: <number>, (default: 128) - fgcolor: text color for text value: <0xRRGGBB>, (default = white) - bgcolor: background color for text value: <0xRRGGBB> or transparent (default) - ch-acc: allowed characters and -groups value: characters or %d,%a,%b,%p, see vg4->input->textbuffer(), (default: empty = all) - ch-rej: not allowed characters and -groups value: characters or %d,%a,%b,%p, see vg4->input->textbuffer(), (default: empty = none) - text-dfl: default text value: <text>, (default = empty) Example: [CV-INPUT] name: input position-itag: input disable: 0 ch-acc: %d%a%p ch-rej: /
- [CV-BAR] - percent-bar - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - percent-dfl: default percent value, (missing = 0) value: <number> - img-bar: image file for bar, where its width corresponds to 100%, (missing: internal image) value: <filename> - img-bar-overdrive: image file for bar, when percent value overdrives value: <overdrive-percent-value>:[<filename>] Example: [VAR-DEFAULT] var.overdrive: 60 [CV-BAR] name: brightness position-itag: brightness img-bar: images/bar.bmp img-bar-overdrive: $(overdrive):images/bar-overdrive.bmp
- [CV-MAP] - map with selectable areas - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - img: image file for map value: <filename> - homeposition: home position when showing map value: <x>,<y> - velo: moving velocitas in pixels, (missing = 1) value: <number> - area.<name>: (repeated for each area:) position of a selectable area value: <x>+<w>,<y>+<h> Example: [CV-MAP] name: map position-itag: map img: images/map.bmp homeposition: 100,50 velo: 2 area.area1: 37+26,26+39 area.area2: 88+32,145+38 area.area3: 130+35,111+25
- [CV-TEXT] - text box for showing text - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - velo: scrolling velocitas in pixels, (missing = no scrolling) value: <number> - bgcolor: background color of text box value: <0xRRGGBB> or transparent (default) - default-text: default text (according to vg4->font->totext()), (missing = empty) value: <text> - text.border: text header parameter border value: see vg4->font->totext() - text.font: text header parameter font value: see vg4->font->totext() - text.fgcolor: text header parameter fgcolor value: see vg4->font->totext() - text.bgcolor: text header parameter bgcolor value: see vg4->font->totext() - text.bold: text header parameter bold value: see vg4->font->totext() - text.linepitch: text header parameter linepitch value: see vg4->font->totext() - text.orientation: text header parameter orientation value: see vg4->font->totext() - text.v-orientation: text header parameter v-orientation value: see vg4->font->totext() - text.nowrap: text header parameter nowrap value: see vg4->font->totext() Example: [VAR-DEFAULT] var.title: Title [CV-TEXT] name: title position-itag: title default-text: %{var: title%} text.orientation: center+left text.v-orientation: center text.fgcolor: 0xffff00 text.nowrap: 1
- [CV-UNIQKEY] - unique-key-pressing: for selecting an input-key or -button - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - font: font name, (missing: default font) value: <font name> - fgcolor: text color for key-name value: <0xRRGGBB>, (default = white) - bgcolor: background color value: <0xRRGGBB> or transparent (default) - to get this to work, vg4->canvas->uniqkey_set() must have been called before Example: [CV-UNIQKEY] name: keypress position-itag: keypress fgcolor: 0x111111
- [CV-IMAGE] - non-selectable Image or Sprite - section-parameters - name: name value: <arbitrary string> - position-itag: position according to a box-tag or box-sub-tag value: <box-(sub-)tag name> - position-rect: position according to a rectangle value: <x>+<w>,<y>+<h> - disable: whether is disabled, (missing = enabled) values: - 1 or yes or on = yes - 0 or no or off = no - orientation: orientation within position-rectangle, (missing = center) values: - left = left orientated - center = centered - right = right orientated - v-orientation: vertical orientation within position-rectangle, (missing = center) values: - top = on top - center = centered - bottom = on the bottom - zoom-in: whether zoom in too great image fitting into position, (missing = no) values: - 1 or yes or on = yes - 0 or no or off = no - zoom-out: whether zoom out too small image fitting into position, (missing = no) values: - 1 or yes or on = yes - 0 or no or off = no - img: image/text/sprite file, or missing values: - img:<filename> = image file - txt:<filename> = text file - sprt:<filename> = sprite file Example: [CV-IMAGE] name: avatar position-itag: avatar img: img:images/myavatar.bmp zoom-in: yes
SEE ALSO
vg4->canvas->reload()