Difference between revisions of "GUICanvasWML"

From The Battle for Wesnoth Wiki
(→‎Text: document set_var usage)
m (→‎Text)
 
(17 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
A canvas is a blank drawing area on which the user can draw several shapes.
 
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.
 
The drawing is done by adding WML structures to the canvas.
 +
 +
== Global Variables ==
 +
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
 +
{| border="1"
 +
!Variable
 +
!type
 +
!description
 +
|-
 +
| width
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The width of the canvas.
 +
|-
 +
| height
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The height of the canvas.
 +
|-
 +
| text
 +
| [[GUIVariable#tstring|tstring]]
 +
| The text to render on the widget.
 +
|-
 +
| text_maximum_width
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The maximum width available for the text on the widget.
 +
|-
 +
| text_maximum_height
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The maximum height available for the text on the widget.
 +
|-
 +
| text_wrap_mode
 +
| [[GUIVariable#int|int]]
 +
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
 +
|-
 +
| text_alignment
 +
| [[GUIVariable#h_align|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:
 +
{| border="1"
 +
!Variable
 +
!type
 +
!description
 +
|-
 +
| screen_width
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The usable width of the Wesnoth main window.
 +
|-
 +
| screen_height
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The usable height of the Wesnoth main window.
 +
|-
 +
| gamemapx_offset
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The distance between left edge of the screen and the game map.
 +
|-
 +
| gamemap_width
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
 +
|-
 +
| gamemap_height
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
 +
|-
 +
| mouse_x
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The x coordinate of the mouse pointer.
 +
|-
 +
| mouse_y
 +
| [[GUIVariable#unsigned|unsigned]]
 +
| The y coordinate of the mouse pointer.
 +
|-
 +
| window_width
 +
| [[GUIVariable#unsigned|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
 +
| [[GUIVariable#unsigned|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:<br>
 +
0 -> width - 1 <br>
 +
0 -> height -1
 +
 +
Drawing outside this area will result in unpredictable results including
 +
crashing. (That should be fixed, when encountered.)
  
 
== Pre commit ==
 
== Pre commit ==
Line 32: Line 120:
 
== Line ==
 
== Line ==
 
Definition of a line. When drawing a line it doesn't get blended on the
 
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
+
surface but replaces the pixels instead.
−
if needed.
 
  
 
Keys:
 
Keys:
Line 63: Line 150:
 
|-
 
|-
 
| color
 
| color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the line.
 
| The color of the line.
Line 77: Line 164:
 
| Debug message to show upon creation this message is not stored.
 
| Debug message to show upon creation this message is not stored.
 
|}
 
|}
−
 
−
<span id="general_variables">Variables:</span>.
 
−
{| border="1"
 
−
!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:
 
−
{| border="1"
 
−
!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:<br>
 
−
0 -> width - 1 <br>
 
−
0 -> height -1
 
−
 
−
Drawing outside this area will result in unpredictable results including
 
−
crashing. (That should be fixed, when encountered.)
 
  
 
== Bounded Shape ==
 
== Bounded Shape ==
Line 232: Line 232:
 
|-
 
|-
 
| border_color
 
| border_color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the border if empty it's not drawn.
 
| The color of the border if empty it's not drawn.
 
|-
 
|-
 
| fill_color
 
| fill_color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the interior if omitted it's not drawn.
 
| The color of the interior if omitted it's not drawn.
Line 246: Line 246:
 
| Debug message to show upon creation this message is not stored.
 
| Debug message to show upon creation this message is not stored.
 
|}
 
|}
−
 
−
Variables:
 
−
See [[#general_variables|Line]].
 
  
 
== Rounded Rectangle ==
 
== Rounded Rectangle ==
Line 272: Line 269:
 
|-
 
|-
 
| border_color
 
| border_color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the border; if empty it's not drawn.
 
| The color of the border; if empty it's not drawn.
 
|-
 
|-
 
| fill_color
 
| fill_color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the interior; if omitted it's not drawn.
 
| The color of the interior; if omitted it's not drawn.
Line 314: Line 311:
 
| The radius of the circle if 0 nothing is drawn.
 
| The radius of the circle if 0 nothing is drawn.
 
|-
 
|-
−
| color
+
| border_thickness
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#unsigned|unsigned]]
 +
| 1
 +
| The thickness of the border; if the thickness is zero it's not drawn.
 +
|-
 +
| border_color
 +
| [[GUIVariable#f_color|f_color]]
 +
| ""
 +
| The color of the border; if empty it's white.
 +
|-
 +
| fill_color
 +
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
−
| The color of the circle.
+
| The color of the interior; if omitted it's not drawn.|-
 
|-
 
|-
 
| debug
 
| debug
Line 324: Line 331:
 
| Debug message to show upon creation this message is not stored.
 
| Debug message to show upon creation this message is not stored.
 
|}
 
|}
−
 
−
Variables:
 
−
See [[#general_variables|Line]].
 
  
 
Drawing outside the area will result in unpredictable results including
 
Drawing outside the area will result in unpredictable results including
Line 367: Line 371:
 
|-
 
|-
 
| vertical_mirror
 
| vertical_mirror
 +
| [[GUIVariable#f_bool|f_bool]]
 +
| false
 +
| Mirror the image over the vertical axis.  Deprecated, replaced by mirror.
 +
|-
 +
| mirror
 
| [[GUIVariable#f_bool|f_bool]]
 
| [[GUIVariable#f_bool|f_bool]]
 
| false
 
| false
Line 382: Line 391:
 
|}
 
|}
  
−
Variables:
+
Local Variables:
 
{| border="1"
 
{| border="1"
 
!Variable
 
!Variable
Line 389: Line 398:
 
|-
 
|-
 
| image_width
 
| image_width
−
| unsigned
+
| [[GUIVariable#unsigned|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.)
 
| 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
 
| image_height
−
| unsigned
+
| [[GUIVariable#unsigned|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.)
 
| 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
 
| image_original_width
−
| unsigned
+
| [[GUIVariable#unsigned|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).
 
| 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
 
| image_original_height
−
| unsigned
+
| [[GUIVariable#unsigned|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).
 
| 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 [[#general_variables|Line]].
 
  
 
== Text ==
 
== Text ==
Line 442: Line 450:
 
|-
 
|-
 
| font_size
 
| font_size
−
| [[GUIVariable#unsigned|unsigned]]
+
| [[GUIVariable#f_unsigned|f_unsigned]]
 
| mandatory
 
| mandatory
 
| The size of the text font.
 
| The size of the text font.
Line 457: Line 465:
 
|-
 
|-
 
| color
 
| color
−
| [[GUIVariable#color|color]]
+
| [[GUIVariable#f_color|f_color]]
 
| ""
 
| ""
 
| The color of the text.
 
| The color of the text.
Line 477: Line 485:
 
|-
 
|-
 
| text_link_color
 
| text_link_color
−
| [[GUIVariable#f_string|f_string]]
+
| [[GUIVariable#f_color|f_color]]
 
| "#ffff00"
 
| "#ffff00"
 
| The color of links in the text
 
| The color of links in the text
Line 507: Line 515:
 
it yet.
 
it yet.
  
−
Variables:
+
Local Variables:
 
{| border="1"
 
{| border="1"
 
!Variable
 
!Variable
Line 514: Line 522:
 
|-
 
|-
 
| text_width
 
| text_width
−
| unsigned
+
| [[GUIVariable#unsigned|unsigned]]
 
| The width of the rendered text.
 
| The width of the rendered text.
 
|-
 
|-
 
| text_height
 
| text_height
−
| unsigned
+
| [[GUIVariable#unsigned|unsigned]]
 
| The height of the rendered text.
 
| The height of the rendered text.
 
|}
 
|}
−
Also the general variables are available, see [[#general_variables|Line]].
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]
 
[[Category: GUI WML Reference]]
 
[[Category: GUI WML Reference]]

Latest revision as of 06:04, 5 November 2024

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.

Global Variables

These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.

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 sets which method is used and possible values are the same as here, that is, 0 (No elllipsization, wrap text instead), 1 (ellipsize start of text), 2 (ellipsize end of text), 3 (ellipsize at the middle). More details (slightly technical) are found at the Pango docs here.
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.)

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 f_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 f_color "" The color of the border if empty it's not drawn.
fill_color f_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.

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 f_color "" The color of the border; if empty it's not drawn.
fill_color f_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.
border_thickness unsigned 1 The thickness of the border; if the thickness is zero it's not drawn.
border_color f_color "" The color of the border; if empty it's white.
fill_color f_color "" -
debug string "" Debug message to show upon creation this message is not stored.

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. Deprecated, replaced by mirror.
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).

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 f_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 f_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_color "#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.
Retrieved from "https://wiki.wesnoth.org/index.php?title=GUICanvasWML&oldid=73949"
This page was last edited on 5 November 2024, at 06:04.