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 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.
Format of the 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-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
SEE ALSO