GUICanvasWML

Canvas

A canvas is a blank drawing area on which the user can draw several shapes. The drawing is done by adding WML structures to the canvas.

Pre commit

This section contains the pre commit functions. These functions will be executed before the drawn canvas is applied on top of the normal background. There should only be one pre commit section and its order regarding the other shapes doesn't matter. The function has effect on the entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

Blur

Blurs the background before applying the canvas. This doesn't make sense if the widget isn't semi-transparent.

Keys:

key	type	default	description
depth	unsigned	0	The depth to blur.

Line

Definition of a line. When drawing a line it doesn't get blended on the surface but replaces the pixels instead.

Keys:

key	type	default	description
x1	f_unsigned	0	The x coordinate of the startpoint.
y1	f_unsigned	0	The y coordinate of the startpoint.
x2	f_unsigned	0	The x coordinate of the endpoint.
y2	f_unsigned	0	The y coordinate of the endpoint.
color	color	""	The color of the line.
thickness	unsigned	0	The thickness of the line if 0 nothing is drawn.
debug	string	""	Debug message to show upon creation this message is not stored.

Bounded Shape

Common attributes of rectangles, round rectangles and text:

key	type	default	description
x	f_unsigned	0	The x coordinate of the top left corner.
y	f_unsigned	0	The y coordinate of the top left corner.
w	f_unsigned	0	The width of the rectangle.
h	f_unsigned	0	The height of the rectangle.

Rectangle

Definition of a rectangle. When drawing a rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

Keys:

key	type	default	description
x	f_unsigned	0	The x coordinate of the top left corner.
y	f_unsigned	0	The y coordinate of the top left corner.
w	f_unsigned	0	The width of the rectangle.
h	f_unsigned	0	The height of the rectangle.
border_thickness	unsigned	0	The thickness of the border if the thickness is zero it's not drawn.
border_color	color	""	The color of the border if empty it's not drawn.
fill_color	color	""	The color of the interior if omitted it's not drawn.
debug	string	""	Debug message to show upon creation this message is not stored.

Variables: See Line.

Rounded Rectangle

Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

key	type	default	description
corner_radius	f_unsigned	0	The radius of the rectangle's corners.
border_thickness	unsigned	0	The thickness of the border; if the thickness is zero it's not drawn.
border_color	color	""	The color of the border; if empty it's not drawn.
fill_color	color	""	The color of the interior; if omitted it's not drawn.
debug	string	""	Debug message to show upon creation; this message is not stored.

Circle

Definition of a circle. When drawing a circle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

Keys:

key	type	default	description
x	f_unsigned	0	The x coordinate of the center.
y	f_unsigned	0	The y coordinate of the center.
radius	f_unsigned	0	The radius of the circle if 0 nothing is drawn.
color	color	""	The color of the circle.
debug	string	""	Debug message to show upon creation this message is not stored.

Variables: See Line.

Drawing outside the area will result in unpredictable results including crashing. (That should be fixed, when encountered.)

Image

Definition of an image.

Keys:

key	type	default	description
x	f_unsigned	0	The x coordinate of the top left corner.
y	f_unsigned	0	The y coordinate of the top left corner.
w	f_unsigned	0	The width of the image, if not zero the image will be scaled to the desired width.
h	f_unsigned	0	The height of the image, if not zero the image will be scaled to the desired height.
resize_mode	resize_mode	scale	Determines how an image is scaled to fit the wanted size.
vertical_mirror	f_bool	false	Mirror the image over the vertical axis.
name	f_string	""	The name of the image.
debug	string	""	Debug message to show upon creation this message is not stored.

Local Variables:

Variable	type	description
image_width	unsigned	The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
image_height	unsigned	The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
image_original_width	unsigned	The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
image_original_height	unsigned	The height of the image as stored on disk, can be used to set y or h (also x and y can be set).

Also the general global variables are available, see Line.

Text

Definition of text.

Keys:

key	type	default	description
x	f_unsigned	0	The x coordinate of the top left corner.
y	f_unsigned	0	The y coordinate of the top left corner.
w	f_unsigned	0	The width of the text's bounding rectangle.
h	f_unsigned	0	The height of the text's bounding rectangle.
font_family	font_family	"sans"	The font family used for the text.
font_size	unsigned	mandatory	The size of the text font.
font_style	font_style	""	The style of the text.
text_alignment	f_h_align	"left"	The alignment of the text.
color	color	""	The color of the text.
text	f_tstring	""	The text to draw (translatable).
text_markup	f_bool	false	Can the text have mark-up?
text_link_aware	f_bool	false	Is the text link aware?
text_link_color	f_string	"#ffff00"	The color of links in the text
maximum_width	f_int	-1	The maximum width the text is allowed to be.
maximum_height	f_int	-1	The maximum height the text is allowed to be.
actions	string	""	WFL code that will be executed when this shape is drawn. In particular, set_var can be used here to store any variables mentioned in the variables section for global use inside the canvas.
debug	string	""	Debug message to show upon creation this message is not stored.

NOTE alignment could only be done with the formulas, but now with the text_alignment flag as well, older widgets might still use the formulas and not all widgets may expose the text alignment yet and when exposed not use it yet.

Local Variables:

Variable	type	description
text_width	unsigned	The width of the rendered text.
text_height	unsigned	The height of the rendered text.

Also the general global variables are available, see Line.