vg4->font->totext()

struct VG_Image * vg4->font->totext(const char *text, const char *dparam, const char *dirname, struct VG_Hash *hvar, struct VG_Hash **htags)

Returns the text as image or NULL = Error

Create text image. Additional to normal text, the contents of text may contain control-commands: %{ <command> [<header>] : <data> %} Examples: - %{txt: My text%} - %{txt[border=4]: My other text with two lines %} Control-commands may be nested. When they are executed, they return an image, called a box. A missing start-control-command assumes command txt. The filename of images, text files or sprites to be loaded in the text are searched relatively to dirname. If a filename of a file to be loaded begins with a '/', it is searched from the current directory. Variables are taken from the parameter hvar. Their values are represented by the format $(<variable name>). Control-commands: ----------------- - txtfile: load another text file data = path to text file to load (data may contain variables, - a specific automatic variable LANG contains the locale, e.g.: %{txtfile: myfile_$(LANG).txt%} ) Example: %{txtfile: another_text.txt%} - txt: text data data = embedded text Example: %{txt: Hello World%} - imgfile: load an image from file data = path to image file to load (data may contain variables, - a specific automatic variable LANG contains the locale, e.g.: %{imgfile: myfile_$(LANG).bmp%} ) Example: %{imgfile: images/myimg.bmp%} - img: load image from embedded data data = embedded base64-coded image Example: %{img: R0lGODlhQAHIA...BZIAAA7%} - mlang: multilanguage scope:key, will be replaced by appropriate text data = <scope> : <key> (data may contain variables) Example: %{mlang: myscope:mykey%} - var: variable: will be replaced by the variable value (from parameter hvar) data = variable name Example: %{var: myvar%} - box: a box just containing control-commands data = control-commands Example: %{box: %{imgfile: me.bmp%} %{txt[fgcolor=0xff0000]: That's me%} %} - table: a table the header needs cells data = cell control-commands Example: %{table[cells=50,50 fullraster=0x888888]: %{cell: line1 row1%} %{cell: line1 row2%} %{cell: line2 row1%} %{cell: line2 row2%} %} - cell: a cell of a table (only as sub-command to table) data = embedded text Example: see table - nl: a newline (only in txt and box, without header and data) Example: %{nl%} - sp: a space (only in txt and box, without header and data) Example: %{sp%} Header: ------- Nearly each control-command may have a header, which comes after the control-command and before the colon in square brackets: %{txt[headerkey1=headervalue1 headerkey2=headervalue2]: data %} Header values may contain variables. Most missing header pairs inherit from the parent control-command. Following header pairs are defined: - background image - key: bgimg - value: path to image file to load - default: empty - inherited: no Example: %{txt[bgimg=images/background.bmp]: some text%} - greatest width of box - key: maxwidth - value: width in pixels or percent (e.g. "50" or "50%"), or 0 = no limit - default: width of parent, or window if no parent - inherited: yes, and can be overwritten only by lesser values Example: %{txt[maxwidth=80%]: some text%} - width of box - key: boxwidth - value: width in pixels or percent (e.g. "50" or "50%"), or 0 = no limit - default: 0 (no limit) - inherited: yes, but as header "maxwidth" Example: %{txt[boxwidth=80%]: some text%} - height of box (if no background image) - key: boxheight - value: height in pixels, or 0 = no limit - default: 0 (no limit) - inherited: no Example: %{txt[boxheight=150]: some text%} - border in pixels in background color around (outside) box - key: border - value: border in pixels - default: 0 (no border) - inherited: no Example: %{txt[border=5]: some text%} - rectangle around box - key: rectcolor - value: color as hex number (0xRRGGBB), or "no" - default: "no" - inherited: yes Example: %{txt[rectcolor=0xff0000]: some text%} - font - key: font - value: font name - default: sys:low for VG_WINDOW_SIZE_LOW, sys:high for VG_WINDOW_SIZE_HIGH - inherited: yes Example: %{txt[font=sys:low]: some text%} - text color - key: fgcolor - value: color as hex number (0xRRGGBB) - default: 0xffffff - inherited: yes Example: %{txt[fgcolor=0xffff00]: some text%} - background color - key: bgcolor - value: color as hex number (0xRRGGBB), or "transparent" - default: "transparent" - inherited: yes Example: %{txt[bgcolor=transparent]: some text%} - whether font-characters are bold - key: bold - value: "no", "off", "0" or "yes", "on", "1" - default: "no" - inherited: yes Example: %{txt[bold=yes]: some text%} - line pitch to add (in percent of default pitch) - key: linepitch - value: line pitch to add, e.g. "100" will be twice of default pitch - default: 0 - inherited: yes Example: %{txt[linepitch=150]: some text%} - orientation of embedded text - key: orientation - value: "left", "center", "right" or "block" The value may have an additional orientation appended with '+', which will be used, if a textline exceeds the width of boxwidth or maxwidth, e.g.: "center+right" => text is centered, but if greater than box it is right-orientated - default: "left" - inherited: yes Example: %{txt[orientation=center]: some text%} - vertical orientation, only if bgimg or boxheight is set, or in table-cell - key: v-orientation - value: "top", "center" or "bottom" The value may have an additional vertical orientation appended with '+', which will be used, if the text exceeds the boundaries of bgimg or boxheight, e.g.: "top+bottom" => text is on top, but if greater than boxheight it is on bottom - default: "center" - inherited: no Example: %{txt[boxheight=100 v-orientation=top]: some text%} - not wrapping lines on separation character - key: nowrap - value: "no", "off", "0" or "yes", "on", "1" - default: "no" - inherited: yes Example: %{txt[nowrap=on]: some text%} - box-tag, will tag the box and return it in parameter htags - key: tag - value: arbitrary string, which serves as key for htags - default: empty - inherited: no Example: %{txt[tag=yellowbox]: some text%} => sets to htags: yellowbox = <rectangle of text-box> - box-sub-tag, will tag a part of the box and return it in parameter htags, can be repeated - key: utag-*, where "*" is an arbitrary string and serves as key for htags - value: rectangle in the format: "<x>+<w>,<y>+<h>" - default: none - inherited: no Example: %{imgfile[utag-yellowbox=5+10,20+70 utag-redbox=55+10,20+70]: myimg.bmp%} => sets to htags: yellowbox = <rectangle 5+10,20+70 within rectangle of image-box> redbox = <rectangle 55+10,20+70 within rectangle of image-box> - only for command table - cells of a table - key: cells - value: comma-separated percent-size of each cell, e.g. "20,20,50" has three cells in a line, the first's size is 20% of the table, the seconds's size is 20% of the table, the third's size is 50% of the table, the missing 10% will be used for cell-distances in background color - there is no default, it must exist for a table - inherited: no - raster of a table (will correct cell-sizes to 100% and clear linepitch) - key: for a line raster: lineraster for a full raster: fullraster - value: raster-color: hex number (0xRRGGBB) - default: no raster - inherited: no Example: %{table[cells=20,20,50 fullraster=0x888888]: ... %} Aliases: -------- Aliases are appended to the control-command after a & e.g. %{txt&center: Text is centered%} Following aliases are defined, internally setting header values - left orientation - alias: left - sets header to: [orientation=left boxwidth=100%] - right orientation - alias: right - sets header to: [orientation=right boxwidth=100%] - centered orientation - alias: center - sets header to: [orientation=center boxwidth=100%] - block orientation - alias: block - sets header to: [orientation=block boxwidth=100%] Example: %{txt&right[fgcolor=0x008844 bold=yes]: Hello world%} is identical to %{txt[orientation=right boxwidth=100% fgcolor=0x008844 bold=yes]: Hello world%}

/* Simple example for a text with control-commands */

Hello World.
This is my first text.

Here you see my dog: %{imgfile: mydog.bmp%}.
And that is my cat: %{imgfile: mycat.bmp%}.

Table of differences:

%{table[cells=50,50 fullraster=0x888888]:
%{cell[bold=on]: My dog%}
%{cell[bold=on]: My cat%}

%{cell: Sleeps at night%}
%{cell: Active at night%}

%{cell: Barks%}
%{cell: Does not bark%}

%{cell: Obeys%}
%{cell: Does not obey%}

%}

vg4->font->loadtext() vg4 text show -h