GUICanvasWML
Contents
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. A blitting flag might be added later if needed.
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. |
Variables:.
Variable | type | description |
---|---|---|
width | unsigned | The width of the canvas. |
height | unsigned | The height of the canvas. |
text | tstring | The text to render on the widget. |
text_maximum_width | unsigned | The maximum width available for the text on the widget. |
text_maximum_height | unsigned | The maximum height available for the text on the widget. |
text_wrap_mode | int | When the text doesn't fit in the available width there are several ways to fix that. This variable holds the best method. (NOTE this is a 'hidden' variable meant to copy state from a widget to its canvas so there's no reason to use this variable and thus its values are not listed and might change without further notice.) |
text_alignment | h_align | The way the text is aligned inside the canvas. |
The size variables are copied to the window and will be determined at runtime. This is needed since the main window can be resized and the dialog needs to resize accordingly. The following variables are available:
Variable | type | description |
---|---|---|
screen_width | unsigned | The usable width of the Wesnoth main window. |
screen_height | unsigned | The usable height of the Wesnoth main window. |
gamemapx_offset | unsigned | The distance between left edge of the screen and the game map. |
gamemap_width | unsigned | The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width. |
gamemap_height | unsigned | The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height. |
mouse_x | unsigned | The x coordinate of the mouse pointer. |
mouse_y | unsigned | The y coordinate of the mouse pointer. |
window_width | unsigned | The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'. |
window_height | unsigned | The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'. |
Note when drawing the valid coordinates are:
0 -> width - 1
0 -> height -1
Drawing outside this area will result in unpredictable results including crashing. (That should be fixed, when encountered.)
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. |
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 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. |
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.
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 variables are available, see Line.