diff --git a/src/editor/toolkit/brush.cpp b/src/editor/toolkit/brush.cpp index 3ae2588eae0c..447d55e58a24 100644 --- a/src/editor/toolkit/brush.cpp +++ b/src/editor/toolkit/brush.cpp @@ -20,42 +20,6 @@ namespace editor { -/*WIKI - * @page = EditorWML - * @order = 1_header - * - * {{AutogeneratedWML}} - * - * = Brush = - * - * Each brush tag defines one brush. (0,0) is the hotspot, that is, the brush - * is always moved so the mouse is over the brush's (0,0) coordinate. The - * following keys and tags are recognized: - * - * (Note the 1.5 version and the mandatory image are for testing only.) - * - * @begin{description}{wml_reference} - * name & string & "" & & - * Name for the brush (will possibly show up in the tooltip for the - * brush). $ - * image & filename & "" & & - * Icon for the brush to de displayed on the toolbar. $ - * radius & integer & 0 & & - * Include in the brushall hexes that are this or closer to the center - * of the brush, excluding the (0,0) point. $ - * [relative] & node & 1 & & Include in the brush a single hex with - * coordinates relative from the center of the brush. $ - * - * @begin{description}{wml_reference} - * x & int & 0 & & The relative x coordinate. $ - * y & int & 0 & & The relative y coordinate. $ - * @end{description} - * - * @end{description} - * A brush that has neither a radius nor any [relative] hexes will be empty - * which is not desired and a warning or error is to be expected. - */ - brush::brush() : relative_tiles_() , name_() diff --git a/src/gui/core/canvas.cpp b/src/gui/core/canvas.cpp index 041221327598..f6528e6d6409 100644 --- a/src/gui/core/canvas.cpp +++ b/src/gui/core/canvas.cpp @@ -40,46 +40,6 @@ namespace gui2 namespace { -/*WIKI - * @page = GUICanvasWML - * - * {{Autogenerated}} - * - * = 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. - */ - -/*WIKI - * @page = GUICanvasWML - * @begin{parent}{name="generic/state/draw/"} - * - * == Pre commit == - * @begin{tag}{name="pre_commit"}{min="0"}{max="1"} - * - * 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 === - * @begin{tag}{name="blur"}{min="0"}{max="1"} - * - * Blurs the background before applying the canvas. This doesn't make sense - * if the widget isn't semi-transparent. - * - * Keys: - * @begin{table}{config} - * depth & unsigned & 0 & The depth to blur. $ - * @end{table} - * @end{tag}{name="blur"} - * @end{tag}{name="pre_commit"} - */ - /***** ***** ***** ***** ***** DRAWING PRIMITIVES ***** ***** ***** ***** *****/ static void set_renderer_color(SDL_Renderer* renderer, color_t color) @@ -261,314 +221,9 @@ static void fill_circle(surface& canvas, } // namespace -/*WIKI - unclassified - * This code can be used by a parser to generate the wiki page - * structure - * [tag name] - * param type_info description - * - * param Name of the parameter. - * - * type_info = ( type = default_value) The info about a optional parameter. - * type_info = ( type ) The info about a mandatory parameter - * type_info = [ type_info ] The info about a conditional parameter - * description should explain the reason. - * - * description Description of the parameter. - * - * - * - * - * Formulas are a function between brackets, that way the engine can see whether - * there is standing a plain number or a formula eg: - * 0 A value of zero - * (0) A formula returning zero - * - * When formulas are available the text should state the available variables - * which are available in that function. - */ - -/*WIKI - * @page = GUIVariable - * - * {{Autogenerated}} - * - * == Variables == - * - * In various parts of the GUI there are several variables types in use. This - * page describes them. - * - * === Simple types === - * - * The simple types are types which have one value or a short list of options. - * - * @begin{table}{variable_types} - * unsigned & Unsigned number (positive whole numbers - * and zero). $ - * f_unsigned & Unsigned number or formula returning an - * unsigned number. $ - * int & Signed number (whole numbers). $ - * f_int & Signed number or formula returning an - * signed number. $ - * bool & A boolean value accepts the normal - * values as the rest of the game. $ - * f_bool & Boolean value or a formula returning a - * boolean value. $ - * string & A text. $ - * tstring & A translatable string. $ - * f_tstring & Formula returning a translatable string. - * $ - * function & A string containing a set of function - * definition for the formula language. $ - * - * color & A string which contains the color, this - * a group of 4 numbers between 0 and 255 - * separated by a comma. The numbers are red - * component, green component, blue - * component and alpha. A color of 0 is not - * available. An alpha of 255 is fully - * transparent. Omitted values are set to - * 0. $ - * f_color & A string which contains a color, or a formula - * which evaluates to a list containing the color's - * components. $ - * - * font_style & A string which contains the style of the - * font: - * @* normal normal font - * @* bold bold font - * @* italic italic font - * @* underline underlined font - * @-Since SDL has problems combining these - * styles only one can be picked. Once SDL - * will allow multiple options, this type - * will be transformed to a comma separated - * list. If empty we default to the normal - * style. Since the render engine is - * replaced by Pango markup this field will - * change later on. Note widgets that allow - * marked up text can use markup to change - * the font style. $ - * - * v_align & Vertical alignment; how an item is - * aligned vertically in the available - * space. Possible values: - * @* top aligned at the top - * @* bottom aligned at the bottom - * @* center centered - * @-When nothing is set or an another - * value as in the list the item is - * centered. $ - * - * h_align & Horizontal alignment; how an item is - * aligned horizontal in the available - * space. Possible values: - * @* left aligned at the left side - * @* right aligned at the right side - * @* center centered $ - * - * f_h_align & A horizontal alignment or a formula - * returning a horizontal alignment. $ - * - * border & Comma separated list of borders to use. - * Possible values: - * @* left border at the left side - * @* right border at the right side - * @* top border at the top - * @* bottom border at the bottom - * @* all alias for "left, right, top, - * bottom" $ - * - * scrollbar_mode & How to show the scrollbar of a widget. - * Possible values: - * @* always The scrollbar is always - * shown, regardless whether it's required - * or not. - * @* never The scrollbar is never - * shown, even not when needed. (Note when - * setting this mode dialogs might - * not properly fit anymore). - * @* auto Shows the scrollbar when - * needed. The widget will reserve space for - * the scrollbar, but only show when needed. - * @* initial_auto Like auto, but when the - * scrollbar is not needed the space is not - * reserved. - * @-Use auto when the list can be changed - * dynamically eg the game list in the - * lobby. For optimization you can also - * use auto when you really expect a - * scrollbar, but don't want it to be shown - * when not needed eg the language list - * will need a scrollbar on most screens. $ - * - * resize_mode & Determines how an image is resized. - * Possible values: - * @* scale The image is scaled. - * @* stretch The first row or column - * of pixels is copied over the entire - * image. (Can only be used to scale resize - * in one direction, else falls - * back to scale.) - * @* tile The image is placed - * several times until the entire surface - * is filled. The last images are - * truncated. - * @* tile_center Like tile, but the - * image is first centered on the screen. $ - * - * grow_direction & Determines whether the image may grow in - * the horizontal or vertical direction. $ - * @end{table} - * @allow{type}{name="unsigned"}{value="^\d+$"} - * @allow{type}{name="f_unsigned"}{value="^.+$"} - * @allow{type}{name="int"}{value="^-?\d+$"} - * @allow{type}{name="f_int"}{value="^.*$"} - * @allow{type}{name="bool"}{value="^true|false|yes|no$"} - * @allow{type}{name="f_bool"}{value="^.*$"} - * @allow{type}{name="string"}{value="^.*$"} - * @allow{type}{name="t_string"}{value="^_?.*$"} - * @allow{type}{name="f_string"}{value="^.*$"} - * @allow{type}{name="f_tstring"}{value="^_?.*$"} - * @allow{type}{name="function"}{value="^_?.*$"} - * - * @allow{type}{name="color"}{value="^(?:2[0-5][0-5]|[01]?\d?\d)[.,]\s*(?:2[0-5][0-5]|[01]?\d?\d)[.,]\s*(?:2[0-5][0-5]|[01]?\d?\d)[.,]\s*(?:2[0-5][0-5]|[01]?\d?\d)$"} - * - * @allow{type}{name="font_style"}{value="^(normal|bold|italic|underline)?$"} - * @allow{type}{name="v_align"}{value="^top|bottom|center$"} - * @allow{type}{name="h_align"}{value="^left|right|center$"} - * @allow{type}{name="f_h_align"}{value="^.*$"} - * @allow{type}{name="border"}{value="^(top|bottom|left|right|all)?(,\s*(top|bottom|left|right|all))*$"} - * @allow{type}{name="scrollbar_mode"}{value="^always|never|auto|initial_auto$"} - * @allow{type}{name="resize_mode"}{value="^scale|stretch|tile$"} - * @allow{type}{name="grow_direction"}{value="^horizontal|vertical$"} - * - * @remove{type}{name="section"} - * @remove{type}{name="config"} - * @remove{type}{name="grid"} - * == Section types == - * - * For more complex parts, there are sections. Sections contain of several - * lines of WML and can have sub sections. For example a grid has sub sections - * which contain various widgets. Here's the list of sections. - * - * @begin{table}{variable_types} - * section & A generic section. The documentation - * about the section should describe the - * section in further detail. $ - * - * grid & A grid contains several widgets. (TODO - * add link to generic grid page.) $ - * @end{table} - */ /***** ***** ***** ***** ***** LINE ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Line == - * @begin{tag}{name="line"}{min="0"}{max="-1"} - * Definition of a line. - * - * Keys: - * @begin{table}{config} - * 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. $ - * @end{table} - * @end{tag}{name="line"} - * - * Variables:. - * @begin{table}{formula} - * 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. $ - *@end{table} - * - * 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: - * @begin{table}{formula} - * 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)"'. - * $ - * - * size_request_mode & string & A field foo: - * - maximum - * - size - * - * @end{table} - * - * 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.) - */ - line_shape::line_shape(const config& cfg) : shape(cfg) , x1_(cfg["x1"]) @@ -619,39 +274,6 @@ void line_shape::draw(surface& canvas, /***** ***** ***** ***** ***** Rectangle ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Rectangle == - * @begin{tag}{name="rectangle"}{min="0"}{max="-1"} - * - * 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: - * @begin{table}{config} - * 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. $ - * @end{table} - * @end{tag}{name="rectangle"} - * Variables: - * See [[#general_variables|Line]]. - * - */ rectangle_shape::rectangle_shape(const config& cfg) : shape(cfg) , x_(cfg["x"]) @@ -731,40 +353,6 @@ void rectangle_shape::draw(surface& canvas, /***** ***** ***** ***** ***** Rounded Rectangle ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Rounded Rectangle == - * @begin{tag}{name="round_rectangle"}{min="0"}{max="-1"} - * - * Definition of a rounded rectangle. 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. - * - * Keys: - * @begin{table}{config} - * 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 rounded rectangle. $ - * h & f_unsigned & 0 & The height of the rounded rectangle. $ - * 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. $ - * @end{table} - * @end{tag}{name="round_rectangle"} - * Variables: - * See [[#general_variables|Line]]. - * - */ round_rectangle_shape::round_rectangle_shape(const config& cfg) : shape(cfg) , x_(cfg["x"]) @@ -854,36 +442,6 @@ void round_rectangle_shape::draw(surface& canvas, /***** ***** ***** ***** ***** CIRCLE ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Circle == - * @begin{tag}{name="circle"}{min="0"}{max="-1"} - * - * 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: - * @begin{table}{config} - * 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 & "" & - * The border thickness of the circle. $ - * border_color & f_color & "" & The color of the circle. $ - * fill_color & f_color & "" & The color of the circle. $ - * debug & string & "" & Debug message to show upon creation; this - * message is not stored. $ - * @end{table} - * @end{tag}{name="circle"} - * Variables: - * See [[#general_variables|Line]]. - * - * Drawing outside the area will result in unpredictable results including - * crashing. (That should be fixed, when encountered.) - */ circle_shape::circle_shape(const config& cfg) : shape(cfg) , x_(cfg["x"]) @@ -954,63 +512,6 @@ void circle_shape::draw(surface& canvas, /***** ***** ***** ***** ***** IMAGE ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Image == - * @begin{tag}{name="image"}{min="0"}{max="-1"} - * Definition of an image. - * - * Keys: - * @begin{table}{config} - * 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. $ - * - * @end{table} - * @end{tag}{name="image"} - * Variables: - * @begin{table}{formula} - * 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). $ - * @end{table} - * Also the general variables are available, see [[#general_variables|Line]]. - */ - image_shape::image_shape(const config& cfg, wfl::action_function_symbol_table& functions) : shape(cfg) , x_(cfg["x"]) @@ -1181,58 +682,6 @@ image_shape::resize_mode image_shape::get_resize_mode(const std::string& resize_ /***** ***** ***** ***** ***** TEXT ***** ***** ***** ***** *****/ -/*WIKI - * @page = GUICanvasWML - * - * == Text == - * @begin{tag}{name="text"}{min="0"}{max="-1"} - * Definition of text. - * - * Keys: - * @begin{table}{config} - * 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 & & 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_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. $ - * @end{table} - * @end{tag}{name="text"} - * 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: - * @begin{table}{formula} - * text_width & unsigned & The width of the rendered text. $ - * text_height & unsigned & The height of the rendered text. $ - * @end{table} - * Also the general variables are available, see [[#general_variables|Line]]. - * @end{parent}{name="generic/state/draw/"} - */ - text_shape::text_shape(const config& cfg) : shape(cfg) , x_(cfg["x"]) @@ -1527,20 +976,3 @@ void canvas::invalidate_cache() /***** ***** ***** ***** ***** SHAPE ***** ***** ***** ***** *****/ } // namespace gui2 - -/*WIKI - * @page = GUICanvasWML - * @order = ZZZZZZ_footer - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - * - */ - -/*WIKI - * @page = GUIVariable - * @order = ZZZZZZ_footer - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - */ diff --git a/src/gui/core/canvas.hpp b/src/gui/core/canvas.hpp index ab4b579c780c..f85aef7befbd 100644 --- a/src/gui/core/canvas.hpp +++ b/src/gui/core/canvas.hpp @@ -223,8 +223,7 @@ class canvas * the config object is no longer required and thus not stored in the * object. * - * @param cfg The config object with the data to draw, see - * https://www.wesnoth.org/wiki/GUICanvasWML + * @param cfg The config object with the data to draw, see @ref GUICanvasWML */ void parse_cfg(const config& cfg); diff --git a/src/gui/core/canvas_private.hpp b/src/gui/core/canvas_private.hpp index 68167b03780a..90a79feed5e2 100644 --- a/src/gui/core/canvas_private.hpp +++ b/src/gui/core/canvas_private.hpp @@ -17,15 +17,62 @@ See the COPYING file for more details. namespace gui2 { -/** Definition of a line shape. */ +/** + * @ingroup GUICanvasWML + * + * 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 | @ref guivartype_f_unsigned "f_unsigned"|0 |The x coordinate of the startpoint. + * y1 | @ref guivartype_f_unsigned "f_unsigned"|0 |The y coordinate of the startpoint. + * x2 | @ref guivartype_f_unsigned "f_unsigned"|0 |The x coordinate of the endpoint. + * y2 | @ref guivartype_f_unsigned "f_unsigned"|0 |The y coordinate of the endpoint. + * color | @ref guivartype_color "color" |"" |The color of the line. + * thickness | @ref guivartype_unsigned "unsigned" |0 |The thickness of the line; if 0 nothing is drawn. + * debug | @ref guivartype_string "string" |"" |Debug message to show upon creation this message is not stored. + * + * Variables: + * Key |Type |Description + * -------------------|----------------------------------------|----------- + * width | @ref guivartype_unsigned "unsigned" |The width of the canvas. + * height | @ref guivartype_unsigned "unsigned" |The height of the canvas. + * text | @ref guivartype_t_string "t_string" |The text to render on the widget. + * text_maximum_width | @ref guivartype_unsigned "unsigned" |The maximum width available for the text on the widget. + * text_maximum_height| @ref guivartype_unsigned "unsigned" |The maximum height available for the text on the widget. + * text_wrap_mode | @ref guivartype_int "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 | @ref guivartype_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: + * Key |Type |Description + * ---------------|------------------------------------|----------- + * screen_width | @ref guivartype_unsigned "unsigned"|The usable width of the Wesnoth main window. + * screen_height | @ref guivartype_unsigned "unsigned"|The usable height of the Wesnoth main window. + * gamemapx_offset| @ref guivartype_unsigned "unsigned"|The distance between left edge of the screen and the game map. + * gamemap_width | @ref guivartype_unsigned "unsigned"|The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width. + * gamemap_height | @ref guivartype_unsigned "unsigned"|The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height. + * mouse_x | @ref guivartype_unsigned "unsigned"|The x coordinate of the mouse pointer. + * mouse_y | @ref guivartype_unsigned "unsigned"|The y coordinate of the mouse pointer. + * window_width | @ref guivartype_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 | @ref guivartype_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: + * * 0 -> width - 1 + * * 0 -> height -1 + * + * Drawing outside this area will result in unpredictable results including crashing. (That should be fixed, when encountered.) + */ class line_shape : public canvas::shape { public: /** * Constructor. * - * @param cfg The config object to define the line see - * https://www.wesnoth.org/wiki/GUICanvasWML#Line - * for more information. + * @param cfg The config object to define the line. */ explicit line_shape(const config& cfg); @@ -53,15 +100,33 @@ class line_shape : public canvas::shape { unsigned thickness_; }; -/** Definition of a rectangle shape. */ +/** + * @ingroup GUICanvasWML + * + * 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 | @ref guivartype_f_unsigned "f_unsigned"|0 |The x coordinate of the top left corner. + * y | @ref guivartype_f_unsigned "f_unsigned"|0 |The y coordinate of the top left corner. + * w | @ref guivartype_f_unsigned "f_unsigned"|0 |The width of the rectangle. + * h | @ref guivartype_f_unsigned "f_unsigned"|0 |The height of the rectangle. + * border_thickness | @ref guivartype_unsigned "unsigned" |0 |The thickness of the border if the thickness is zero it's not drawn. + * border_color | @ref guivartype_color "color" |"" |The color of the border if empty it's not drawn. + * fill_color | @ref guivartype_color "color" |"" |The color of the interior if omitted it's not drawn. + * debug | @ref guivartype_string "string" |"" |Debug message to show upon creation this message is not stored. + * + * Variables: see line_shape + */ class rectangle_shape : public canvas::shape { public: /** * Constructor. * - * @param cfg The config object to define the rectangle see - * https://www.wesnoth.org/wiki/GUICanvasWML#Rectangle - * for more information. + * @param cfg The config object to define the rectangle. */ explicit rectangle_shape(const config& cfg); @@ -98,15 +163,30 @@ class rectangle_shape : public canvas::shape { typed_formula fill_color_; }; -/** Definition of a rounded rectangle shape. */ +/** + * @ingroup GUICanvasWML + * + * 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 + * ----------------|----------------------------------------|---------|----------- + * x | @ref guivartype_f_unsigned "f_unsigned"|0 |The x coordinate of the top left corner. + * y | @ref guivartype_f_unsigned "f_unsigned"|0 |The y coordinate of the top left corner. + * w | @ref guivartype_f_unsigned "f_unsigned"|0 |The width of the rounded rectangle. + * h | @ref guivartype_f_unsigned "f_unsigned"|0 |The height of the rounded rectangle. + * corner_radius | @ref guivartype_f_unsigned "f_unsigned"|0 |The radius of the rectangle's corners. + * border_thickness| @ref guivartype_unsigned "unsigned" |0 |The thickness of the border; if the thickness is zero it's not drawn. + * border_color | @ref guivartype_color "color" |"" |The color of the border; if empty it's not drawn. + * fill_color | @ref guivartype_color "color" |"" |The color of the interior; if omitted it's not drawn. + * debug | @ref guivartype_string "string" |"" |Debug message to show upon creation; this message is not stored. + */ class round_rectangle_shape : public canvas::shape { public: /** * Constructor. * - * @param cfg The config object to define the round rectangle see - * https://www.wesnoth.org/wiki/GUICanvasWML#Rounded_Rectangle - * for more information. + * @param cfg The config object to define the round rectangle. */ explicit round_rectangle_shape(const config& cfg); @@ -144,15 +224,32 @@ class round_rectangle_shape : public canvas::shape { typed_formula fill_color_; }; -/** Definition of a circle shape. */ +/** + * @ingroup GUICanvasWML + * + * 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 | @ref guivartype_f_unsigned "f_unsigned"|0 |The x coordinate of the center. + * y | @ref guivartype_f_unsigned "f_unsigned"|0 |The y coordinate of the center. + * radius | @ref guivartype_f_unsigned "f_unsigned"|0 |The radius of the circle; if 0 nothing is drawn. + * color | @ref guivartype_color "color" |"" |The color of the circle. + * debug | @ref guivartype_string "string" |"" |Debug message to show upon creation this message is not stored. + * + * Variables: see line_shape + * + * Drawing outside the area will result in unpredictable results including crashing. (That should be fixed, when encountered.) + */ class circle_shape : public canvas::shape { public: /** * Constructor. * - * @param cfg The config object to define the circle see - * https://www.wesnoth.org/wiki/GUICanvasWML#Circle - * for more information. + * @param cfg The config object to define the circle. */ explicit circle_shape(const config& cfg); @@ -173,7 +270,31 @@ class circle_shape : public canvas::shape { unsigned int border_thickness_; }; -/** Definition of an image shape. */ +/** + * @ingroup GUICanvasWML + * + * Keys: + * Key |Type |Default|Description + * -------------------|------------------------------------------|-------|----------- + * x | @ref guivartype_f_unsigned "f_unsigned" |0 |The x coordinate of the top left corner. + * y | @ref guivartype_f_unsigned "f_unsigned" |0 |The y coordinate of the top left corner. + * w | @ref guivartype_f_unsigned "f_unsigned" |0 |The width of the image, if not zero the image will be scaled to the desired width. + * h | @ref guivartype_f_unsigned "f_unsigned" |0 |The height of the image, if not zero the image will be scaled to the desired height. + * resize_mode | @ref guivartype_resize_mode "resize_mode"|scale |Determines how an image is scaled to fit the wanted size. + * vertical_mirror | @ref guivartype_f_bool "f_bool" |false |Mirror the image over the vertical axis. + * name | @ref guivartype_string "string" |"" |The name of the image. + * debug | @ref guivartype_string "string" |"" |Debug message to show upon creation this message is not stored. + * + * Variables: + * Key |Type |Description + * ---------------------|--------------------------------------|----------- + * image_width | @ref guivartype_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.) + * image_height | @ref guivartype_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.) + * image_original_width | @ref guivartype_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). + * image_original_height| @ref guivartype_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). + * + * Also the general variables are available, see line_shape + */ class image_shape : public canvas::shape { public: /** @@ -238,15 +359,44 @@ class image_shape : public canvas::shape { static void dimension_validation(unsigned value, const std::string& name, const std::string& key); }; -/** Definition of a text shape. */ +/** + * @ingroup GUICanvasWML + * + * Key |Type |Default |Description + * -------------------|------------------------------------------|---------|----------- + * x | @ref guivartype_f_unsigned "f_unsigned" |0 |The x coordinate of the top left corner. + * y | @ref guivartype_f_unsigned "f_unsigned" |0 |The y coordinate of the top left corner. + * w | @ref guivartype_f_unsigned "f_unsigned" |0 |The width of the text's bounding rectangle. + * h | @ref guivartype_f_unsigned "f_unsigned" |0 |The height of the text's bounding rectangle. + * font_family | @ref guivartype_font_style "font_style" |"sans" |The font family used for the text. + * font_size | @ref guivartype_f_unsigned "f_unsigned" |mandatory|The size of the text font. + * font_style | @ref guivartype_f_unsigned "f_unsigned" |"" |The style of the text. + * text_alignment | @ref guivartype_f_unsigned "f_unsigned" |"left" |The alignment of the text. + * color | @ref guivartype_color "color" |"" |The color of the text. + * text | @ref guivartype_f_tstring "f_tstring" |"" |The text to draw (translatable). + * text_markup | @ref guivartype_f_bool "f_bool" |false |Can the text have mark-up? + * text_link_aware | @ref guivartype_f_bool "f_bool" |false |Is the text link aware? + * text_link_color | @ref guivartype_string "string" |"#ffff00"|The color of links in the text. + * maximum_width | @ref guivartype_f_int "f_int" |-1 |The maximum width the text is allowed to be. + * maximum_height | @ref guivartype_f_int "f_int" |-1 |The maximum height the text is allowed to be. + * debug | @ref guivartype_string "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: + * Key |Type |Description + * -------------------|------------------------------------------|----------- + * text_width | @ref guivartype_unsigned "unsigned" |The width of the rendered text. + * text_height | @ref guivartype_unsigned "unsigned" |The height of the rendered text. + * Also the general variables are available, see line_shape + */ class text_shape : public canvas::shape { public: /** * Constructor. * - * @param cfg The config object to define the text see - * https://www.wesnoth.org/wiki/GUICanvasWML#Text - * for more information. + * @param cfg The config object to define the text. */ explicit text_shape(const config& cfg); diff --git a/src/gui/core/widget_definition.cpp b/src/gui/core/widget_definition.cpp index 1ca6563b1c82..596a1295dace 100644 --- a/src/gui/core/widget_definition.cpp +++ b/src/gui/core/widget_definition.cpp @@ -24,99 +24,12 @@ namespace gui2 { -/*WIKI - * @page = GUIToolkitWML - * @order = 1_widget - * - * == State == - * - * @begin{parent}{name="generic/"} - * @begin{tag}{name="state"}{min=0}{max=1} - * Definition of a state. A state contains the info what to do in a state. - * Atm this is rather focused on the drawing part, might change later. - * Keys: - * @begin{table}{config} - * draw & section & & Section with drawing directions for a - *canvas. $ - * @end{table} - * @end{tag}{name="state"} - * @end{parent}{name="generic/"} - * - */ state_definition::state_definition(const config& cfg) : canvas_cfg_(cfg ? cfg.child("draw") : cfg) { VALIDATE(canvas_cfg_, _("No state or draw section defined.")); } -/*WIKI - * @page = GUIToolkitWML - * @order = 1_widget - * @begin{parent}{name=generic/widget_definition/} - * == Resolution == - * @begin{tag}{name="resolution"}{min="0"}{max="-1"} - * - * Depending on the resolution a widget can look different. Resolutions are - * evaluated in order of appearance. The ''window_width'' and ''window_height'' - * are the upper limit this resolution is valid for. When one of the sizes - * gets above the limit, the next resolution is selected. There's one special - * case where both values are ''0''. This resolution always matches. (Resolution - * definitions behind that one will never be picked.) This resolution can be - * used as upper limit or if there's only one resolution. - * - * The default (and also minimum) size of a button is determined by two items, - * the wanted default size and the size needed for the text. The size of the - * text differs per used widget so needs to be determined per button. - * - * Container widgets like panels and windows have other rules for their sizes. - * Their sizes are based on the size of their children (and the border they need - * themselves). It's wise to set all sizes to 0 for these kind of widgets. - * - * @begin{table}{config} - * window_width & unsigned & 0 & Width of the application window. $ - * window_height & unsigned & 0 & Height of the application window. $ - * - * - * min_width & unsigned & 0 & The minimum width of the widget. $ - * min_height & unsigned & 0 & The minimum height of the widget. $ - * - * - * default_width & unsigned & 0 & The default width of the widget. $ - * default_height & unsigned & 0 & The default height of the widget. $ - * - * - * max_width & unsigned & 0 & The maximum width of the widget. $ - * max_height & unsigned & 0 & The maximum height of the widget. $ - * - * text_extra_width & unsigned & 0 & - * The extra width needed to determine the minimal size for the text. $ - * - * text_extra_height & unsigned & 0 & - * The extra height needed to determine the minimal size for the text. $ - * - * text_font_family & font_family & "" & - * The font family, needed to determine the minimal size for the text. $ - * - * text_font_size & formula for unsigned & 0 & - * The font size, which needs to be used to determine the minimal size for - * the text. Currently, the only variables supported in this formula are - * those available from the global GUI2 settings object, namely screen_width, - * screen_height, screen_pitch_microns, gamemap_width, gamemap_height, and - * gamemap_x_offset. $ - * - * text_font_style & font_style & "" & - * The font style, which needs to be used to determine the minimal size for - * the text. $ - * - * - * state & section & & - * Every widget has one or more state sections. Note they aren't called - * state but state_xxx the exact names are listed per widget. $ - * @end{table} - * @end{tag}{name="resolution"} - * @end{parent}{name=generic/widget_definition/} - */ - resolution_definition::resolution_definition(const config& cfg) : window_width(cfg["window_width"]) , window_height(cfg["window_height"]) @@ -140,29 +53,6 @@ resolution_definition::resolution_definition(const config& cfg) linked_groups = parse_linked_group_definitions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1 - * - * {{Autogenerated}} - * - * = Widget definition = - * - * This page describes the definition of all widgets in the toolkit. Every - * widget has some parts in common, first of all; every definition has the - * following fields. - * @begin{parent}{name="generic/"} - * @begin{tag}{name=widget_definition}{min=0}{max=1} - * @begin{table}{config} - * id & string & & Unique id for this gui (theme). $ - * description & t_string & & Unique translatable name for this gui. $ - * - * resolution & section & & The definitions of the widget in various - * resolutions. $ - * @end{table} - * @end{tag}{name=widget_definition} - * @end{parent}{name="generic/"} - */ styled_widget_definition::styled_widget_definition(const config& cfg) : id(cfg["id"]), description(cfg["description"].t_str()), resolutions() { diff --git a/src/gui/core/widget_definition.hpp b/src/gui/core/widget_definition.hpp index 3f56113d7429..886421f3781a 100644 --- a/src/gui/core/widget_definition.hpp +++ b/src/gui/core/widget_definition.hpp @@ -39,7 +39,40 @@ struct state_definition config canvas_cfg_; }; -/** Base class of a resolution, contains the common keys for a resolution. */ +/** + * Base class of a resolution, contains the common keys for a resolution. + * + * Depending on the resolution a widget can look different. Resolutions are evaluated in order of appearance. + * The window_width and window_height are the upper limit this resolution is valid for. + * When one of the sizes gets above the limit, the next resolution is selected. + * There's one special case where both values are 0. This resolution always matches. + * (Resolution definitions behind that one will never be picked.) + * This resolution can be used as upper limit or if there's only one resolution. + * + * The default (and also minimum) size of a button is determined by two items, the wanted default size and the size needed for the text. + * The size of the text differs per used widget so needs to be determined per button. + * + * Container widgets like panels and windows have other rules for their sizes. + * Their sizes are based on the size of their children (and the border they need themselves). + * It's wise to set all sizes to 0 for these kind of widgets. + * + * Key |Type |Default |Description + * -----------------|------------------------------------|---------|------------- + * window_width | @ref guivartype_unsigned "unsigned"|0 |Width of the application window. + * window_height | @ref guivartype_unsigned "unsigned"|0 |Height of the application window. + * min_width | @ref guivartype_unsigned "unsigned"|0 |The minimum width of the widget. + * min_height | @ref guivartype_unsigned "unsigned"|0 |The minimum height of the widget. + * default_width | @ref guivartype_unsigned "unsigned"|0 |The default width of the widget. + * default_height | @ref guivartype_unsigned "unsigned"|0 |The default height of the widget. + * max_width | @ref guivartype_unsigned "unsigned"|0 |TThe maximum width of the widget. + * max_height | @ref guivartype_unsigned "unsigned"|0 |The maximum height of the widget. + * text_extra_width | @ref guivartype_unsigned "unsigned"|0 |The extra width needed to determine the minimal size for the text. + * text_extra_height| @ref guivartype_unsigned "unsigned"|0 |The extra height needed to determine the minimal size for the text. + * text_font_family | font_family |"" |The font family, needed to determine the minimal size for the text. + * text_font_size | @ref guivartype_unsigned "unsigned"|0 |The font size, which needs to be used to determine the minimal size for the text. + * text_font_style | font_style |"" |The font style, which needs to be used to determine the minimal size for the text. + * state | @ref guivartype_section "section" |mandatory|Every widget has one or more state sections. Note they aren't called state but state_xxx the exact names are listed per widget. + */ struct resolution_definition { explicit resolution_definition(const config& cfg); diff --git a/src/gui/core/window_builder.cpp b/src/gui/core/window_builder.cpp index 24af0813d03e..818e92c85cc9 100644 --- a/src/gui/core/window_builder.cpp +++ b/src/gui/core/window_builder.cpp @@ -33,19 +33,7 @@ namespace gui2 { -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 1 - * - * {{Autogenerated}} - * - * = Widget instance = - * - * Inside a grid (which is inside all container widgets) a widget is - * instantiated. With this instantiation some more variables of a widget can - * be tuned. This page will describe what can be tuned. - * - */ + std::unique_ptr build(const builder_window::window_resolution& definition) { // We set the values from the definition since we can only determine the @@ -143,28 +131,6 @@ widget* build_single_widget_instance_helper(const std::string& type, const confi return builder(cfg)->build(); } -/*WIKI - * @page = GUIToolkitWML - * @order = 1_window - * @begin{parent}{name="gui/"} - * = Window definition = - * @begin{tag}{name="window"}{min="0"}{max="-1"} - * - * A window defines how a window looks in the game. - * - * @begin{table}{config} - * id & string & & Unique id for this window. $ - * description & t_string & & Unique translatable name for this - * window. $ - * - * resolution & section & & The definitions of the window in various - * resolutions. $ - * @end{table} - * @end{tag}{name="window"} - * @end{parent}{name="gui/"} - * - * - */ void builder_window::read(const config& cfg) { VALIDATE(!id_.empty(), missing_mandatory_wml_key("window", "id")); @@ -180,113 +146,6 @@ void builder_window::read(const config& cfg) } } -/*WIKI - * @page = GUIToolkitWML - * @order = 1_window - * @begin{parent}{name=gui/window/} - * == Resolution == - * @begin{tag}{name="resolution"}{min="0"}{max="-1"} - * @begin{table}{config} - * window_width & unsigned & 0 & Width of the application window. $ - * window_height & unsigned & 0 & Height of the application window. $ - * - * - * automatic_placement & bool & true & - * Automatically calculate the best size for the window and place it. If - * automatically placed ''vertical_placement'' and ''horizontal_placement'' - * can be used to modify the final placement. If not automatically placed - * the ''width'' and ''height'' are mandatory. $ - * - * - * x & f_unsigned & 0 & X coordinate of the window to show. $ - * y & f_unsigned & 0 & Y coordinate of the window to show. $ - * width & f_unsigned & 0 & Width of the window to show. $ - * height & f_unsigned & 0 & Height of the window to show. $ - * - * reevaluate_best_size & f_bool & false & - * The foo $ - * - * functions & function & "" & - * The function definitions s available for the formula fields in window. $ - * - * vertical_placement & v_align & "" & - * The vertical placement of the window. $ - * - * horizontal_placement & h_align & "" & - * The horizontal placement of the window. $ - * - * - * maximum_width & unsigned & 0 & - * The maximum width of the window (only used for automatic placement). $ - * - * maximum_height & unsigned & 0 & - * The maximum height of the window (only used for automatic placement). $ - * - * - * click_dismiss & bool & false & - * Does the window need click dismiss behavior? Click dismiss behavior - * means that any mouse click will close the dialog. Note certain widgets - * will automatically disable this behavior since they need to process the - * clicks as well, for example buttons do need a click and a misclick on - * button shouldn't close the dialog. NOTE with some widgets this behavior - * depends on their contents (like scrolling labels) so the behavior might - * get changed depending on the data in the dialog. NOTE the default - * behavior might be changed since it will be disabled when can't be used - * due to widgets which use the mouse, including buttons, so it might be - * wise to set the behavior explicitly when not wanted and no mouse using - * widgets are available. This means enter, escape or an external source - * needs to be used to close the dialog (which is valid). $ - * - * - * definition & string & "default" & - * Definition of the window which we want to show. $ - * - * - * linked_group & sections & [] & A group of linked widget sections. $ - * - * - * tooltip & section & & - * Information regarding the tooltip for this window. $ - * - * helptip & section & & - * Information regarding the helptip for this window. $ - * - * - * grid & grid & & The grid with the widgets to show. $ - * @end{table} - * @begin{tag}{name="linked_group"}{min=0}{max=-1} - * A linked_group section has the following fields: - * @begin{table}{config} - * id & string & & The unique id of the group (unique in this - * window). $ - * fixed_width & bool & false & Should widget in this group have the same - * width. $ - * fixed_height & bool & false & Should widget in this group have the same - * height. $ - * @end{table} - * @end{tag}{name="linked_group"} - * A linked group needs to have at least one size fixed. - * All widgets that are defined with linked_group=foo, where foo is the id of - * the linked_group, will have the same width (if fixed_width) and the same - * height (if fixed_height). - * @begin{tag}{name="tooltip"}{min=0}{max=1} - * A tooltip and helptip section have the following field: - * @begin{table}{config} - * id & string & & The id of the tip to show. - * Note more fields will probably be added later on. - * @end{table}{config} - * @end{tag}{name=tooltip} - * @begin{tag}{name="foreground"}{min=0}{max=1} - * @end{tag}{name="foreground"} - * @begin{tag}{name="background"}{min=0}{max=1} - * @end{tag}{name="background"} - * @end{tag}{name="resolution"} - * @end{parent}{name=gui/window/} - * @begin{parent}{name=gui/window/resolution/} - * @begin{tag}{name="helptip"}{min=0}{max=1}{super="gui/window/resolution/tooltip"} - * @end{tag}{name="helptip"} - * @end{parent}{name=gui/window/resolution/} - */ builder_window::window_resolution::window_resolution(const config& cfg) : window_width(cfg["window_width"]) , window_height(cfg["window_height"]) @@ -338,68 +197,6 @@ builder_window::window_resolution::tooltip_info::tooltip_info(const config& cfg, VALIDATE(!id.empty(), missing_mandatory_wml_key("[window][resolution][" + tagname + "]", "id")); } -/*WIKI - * @page = GUIToolkitWML - * @order = 2_cell - * @begin{parent}{name="gui/window/resolution/"} - * = Cell = - * @begin{tag}{name="grid"}{min="1"}{max="1"} - * @begin{table}{config} - * id & string & "" & A grid is a widget and can have an id. This isn't - * used that often, but is allowed. $ - * linked_group & string & 0 & $ - * @end{table} - * - * Every grid cell has some cell configuration values and one widget in the grid - * cell. Here we describe the what is available more information about the usage - * can be found here [[GUILayout]]. - * - * == Row values == - * @begin{tag}{name="row"}{min="0"}{max="-1"} - * For every row the following variables are available: - * - * @begin{table}{config} - * grow_factor & unsigned & 0 & The grow factor for a row. $ - * @end{table} - * - * == Cell values == - * @begin{tag}{name="column"}{min="0"}{max="-1"} - * @allow{link}{name="gui/window/resolution/grid"} - * For every column the following variables are available: - * @begin{table}{config} - * grow_factor & unsigned & 0 & The grow factor for a column, this - * value is only read for the first row. $ - * - * border_size & unsigned & 0 & The border size for this grid cell. $ - * border & border & "" & Where to place the border in this grid - * cell. $ - * - * vertical_alignment & v_align & "" & - * The vertical alignment of the widget in - * the grid cell. (This value is ignored if - * vertical_grow is true.) $ - * horizontal_alignment & h_align & "" & - * The horizontal alignment of the widget in - * the grid cell.(This value is ignored if - * horizontal_grow is true.) $ - * - * vertical_grow & bool & false & Does the widget grow in vertical - * direction when the grid cell grows in the - * vertical direction. This is used if the - * grid cell is wider as the best width for - * the widget. $ - * horizontal_grow & bool & false & Does the widget grow in horizontal - * direction when the grid cell grows in the - * horizontal direction. This is used if the - * grid cell is higher as the best width for - * the widget. $ - * @end{table} - * @end{tag}{name="column"} - * @end{tag}{name="row"} - * @end{tag}{name="grid"} - * @end{parent}{name="gui/window/resolution/"} - * - */ builder_grid::builder_grid(const config& cfg) : builder_widget(cfg) , rows(0) @@ -522,20 +319,3 @@ void builder_grid::build(grid& grid, const replacements_map& replacements) const } } // namespace gui2 - -/*WIKI - * @page = GUIToolkitWML - * @order = ZZZZZZ_footer - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = ZZZZZZ_footer - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - * - */ diff --git a/src/gui/core/window_builder.hpp b/src/gui/core/window_builder.hpp index 16664c22e3d9..f8c7a134c44a 100644 --- a/src/gui/core/window_builder.hpp +++ b/src/gui/core/window_builder.hpp @@ -141,6 +141,41 @@ class builder_window read(cfg); } + /** + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * window_width | @ref guivartype_unsigned "unsigned" |0 |Width of the application window. + * window_height | @ref guivartype_unsigned "unsigned" |0 |Height of the application window. + * automatic_placement | @ref guivartype_bool "bool" |true |Automatically calculate the best size for the window and place it. If automatically placed vertical_placement and horizontal_placement can be used to modify the final placement. If not automatically placed the width and height are mandatory. + * x | @ref guivartype_f_unsigned "f_unsigned"|0 |X coordinate of the window to show. + * y | @ref guivartype_f_unsigned "f_unsigned"|0 |Y coordinate of the window to show. + * width | @ref guivartype_f_unsigned "f_unsigned"|0 |Width of the window to show. + * height | @ref guivartype_f_unsigned "f_unsigned"|0 |Height of the window to show. + * reevaluate_best_size| @ref guivartype_f_bool "f_bool" |false |The foo + * functions | @ref guivartype_function "function" |"" |The function definitions s available for the formula fields in window. + * vertical_placement | @ref guivartype_v_align "v_align" |"" |The vertical placement of the window. + * horizontal_placement| @ref guivartype_h_align "h_align" |"" |The horizontal placement of the window. + * maximum_width | @ref guivartype_unsigned "unsigned" |0 |The maximum width of the window (only used for automatic placement). + * maximum_height | @ref guivartype_unsigned "unsigned" |0 |The maximum height of the window (only used for automatic placement). + * click_dismiss | @ref guivartype_bool "bool" |false |Does the window need click dismiss behavior? Click dismiss behavior means that any mouse click will close the dialog. Note certain widgets will automatically disable this behavior since they need to process the clicks as well, for example buttons do need a click and a misclick on button shouldn't close the dialog. NOTE with some widgets this behavior depends on their contents (like scrolling labels) so the behavior might get changed depending on the data in the dialog. NOTE the default behavior might be changed since it will be disabled when can't be used due to widgets which use the mouse, including buttons, so it might be wise to set the behavior explicitly when not wanted and no mouse using widgets are available. This means enter, escape or an external source needs to be used to close the dialog (which is valid). + * definition | @ref guivartype_string "string" |"default"|Definition of the window which we want to show. + * linked_group | sections |[] |A group of linked widget sections. + * tooltip | @ref guivartype_section "section" |mandatory|Information regarding the tooltip for this window. + * helptip | @ref guivartype_section "section" |mandatory|Information regarding the helptip for this window. + * grid | @ref guivartype_grid "grid" |mandatory|The grid with the widgets to show. + * + * A linked_group section has the following fields and needs to have at least one size fixed: + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * id | @ref guivartype_string "string" |mandatory|The unique id of the group (unique in this window). + * fixed_width | @ref guivartype_bool "bool" |false |Should widget in this group have the same width. + * fixed_height | @ref guivartype_bool "bool" |false |Should widget in this group have the same height. + * + * A tooltip and helptip section have the following field; more fields will probably be added later on: + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * id | @ref guivartype_string "string" |mandatory|The id of the tip to show. + */ struct window_resolution { public: diff --git a/src/gui/core/window_builder/instance.cpp b/src/gui/core/window_builder/instance.cpp index c6e8281e8105..d1c83d22135d 100644 --- a/src/gui/core/window_builder/instance.cpp +++ b/src/gui/core/window_builder/instance.cpp @@ -48,12 +48,3 @@ widget* builder_instance::build(const replacements_map& replacements) const } // namespace implementation } // namespace gui2 - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_instance - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="instance"}{min=0}{max=-1}{super="generic/widget_instance"} - * @end{tag}{name="instance"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ diff --git a/src/gui/dialogs/addon/connect.cpp b/src/gui/dialogs/addon/connect.cpp index 538425ec0d28..8d6ca736c0da 100644 --- a/src/gui/dialogs/addon/connect.cpp +++ b/src/gui/dialogs/addon/connect.cpp @@ -30,29 +30,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_addon_connect - * - * == Addon connect == - * - * This shows the dialog for managing addons and connecting to the addon server. - * - * @begin{table}{dialog_widgets} - * hostname & & text_box & m & - * This text contains the name of the server to connect to. $ - * - * show_help & & button & m & - * Thus button shows the in-game help about add-ons management when - * triggered. $ - * - * & 2 & button & o & - * This button closes the dialog to display a dialog for removing - * installed add-ons. $ - * - * @end{table} - */ - REGISTER_DIALOG(addon_connect) addon_connect::addon_connect(std::string& host_name, diff --git a/src/gui/dialogs/addon/connect.hpp b/src/gui/dialogs/addon/connect.hpp index 84f422295cd1..0b494efc6f5c 100644 --- a/src/gui/dialogs/addon/connect.hpp +++ b/src/gui/dialogs/addon/connect.hpp @@ -21,7 +21,16 @@ namespace gui2 namespace dialogs { -/** Addon connect dialog. */ +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog for managing addons and connecting to the addon server. + * Key |Type |Mandatory|Description + * ------------------|----------|---------|----------- + * hostname | text_box |yes |This text contains the name of the server to connect to. + * show_help | @ref gui::button |yes |Thus button shows the in-game help about add-ons management when triggered. + * free to choose (2)| button |no |This button closes the dialog to display a dialog for removing installed add-ons. + */ class addon_connect : public modal_dialog { public: diff --git a/src/gui/dialogs/addon/manager.cpp b/src/gui/dialogs/addon/manager.cpp index 057100088733..037f7347b561 100644 --- a/src/gui/dialogs/addon/manager.cpp +++ b/src/gui/dialogs/addon/manager.cpp @@ -63,38 +63,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_addon_list - * - * == Addon list == - * - * This shows the dialog with the addons to install. This dialog is under - * construction and only used with --new-widgets. - * - * @begin{table}{dialog_widgets} - * - * addons & & listbox & m & - * A listbox that will contain the info about all addons on the server. $ - * - * -name & & styled_widget & o & - * The name of the addon. $ - * - * -version & & styled_widget & o & - * The version number of the addon. $ - * - * -author & & styled_widget & o & - * The author of the addon. $ - * - * -downloads & & styled_widget & o & - * The number of times the addon has been downloaded. $ - * - * -size & & styled_widget & o & - * The size of the addon. $ - * - * @end{table} - */ - namespace { struct filter_transform { diff --git a/src/gui/dialogs/addon/manager.hpp b/src/gui/dialogs/addon/manager.hpp index 39050f4e6f9a..3a21a6b51568 100644 --- a/src/gui/dialogs/addon/manager.hpp +++ b/src/gui/dialogs/addon/manager.hpp @@ -35,7 +35,20 @@ class stacked_widget; namespace dialogs { -/** Shows the list of addons on the server. */ +/** + * @ingroup GUIWindowDefinitionWML + * + * Shows the list of addons on the server available for installation. + * This dialog is under construction and only used with --new-widgets. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * addons | @ref listbox |yes |A listbox that will contain the info about all addons on the server. + * name | control |no |The name of the addon. + * version | control |no |The version number of the addon. + * author | control |no |The author of the addon. + * downloads | control |no |The number of times the addon has been downloaded. + * size | control |no |The size of the addon. + */ class addon_manager : public modal_dialog { public: diff --git a/src/gui/dialogs/addon/uninstall_list.cpp b/src/gui/dialogs/addon/uninstall_list.cpp index 893a89087808..a326f21bc7f5 100644 --- a/src/gui/dialogs/addon/uninstall_list.cpp +++ b/src/gui/dialogs/addon/uninstall_list.cpp @@ -28,28 +28,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_addon_uninstall_list - * - * == Add-on uninstall list == - * - * Dialog with a checkbox list for choosing installed add-ons to remove. - * - * @begin{table}{dialog_widgets} - * - * addons_list & & listbox & m & - * A listbox containing add-on selection entries. $ - * - * -checkbox & & toggle_button & m & - * A toggle button allowing the user to mark/unmark the add-on. $ - * - * -name & & styled_widget & o & - * The name of the add-on. $ - * - * @end{table} - */ - REGISTER_DIALOG(addon_uninstall_list) void addon_uninstall_list::pre_show(window& window) diff --git a/src/gui/dialogs/addon/uninstall_list.hpp b/src/gui/dialogs/addon/uninstall_list.hpp index 899d4b7cc846..0b4ee72304a1 100644 --- a/src/gui/dialogs/addon/uninstall_list.hpp +++ b/src/gui/dialogs/addon/uninstall_list.hpp @@ -23,6 +23,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog with a checkbox list for choosing installed add-ons to remove. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * addons_list | @ref listbox |yes |A listbox containing add-on selection entries. + * checkbox | toggle_button |yes |A toggle button allowing the user to mark/unmark the add-on. + * name | control |no |The name of the add-on. + */ class addon_uninstall_list : public modal_dialog { public: diff --git a/src/gui/dialogs/campaign_difficulty.cpp b/src/gui/dialogs/campaign_difficulty.cpp index e87b1c0250bf..4bfe1d07c220 100644 --- a/src/gui/dialogs/campaign_difficulty.cpp +++ b/src/gui/dialogs/campaign_difficulty.cpp @@ -35,38 +35,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_campaign_difficulty - * - * == Campaign difficulty == - * - * The campaign mode difficulty menu. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * message & & scroll_label & o & - * Text label displaying a description or instructions. $ - * - * listbox & & listbox & m & - * Listbox displaying user choices, defined by WML for each campaign. $ - * - * -icon & & styled_widget & m & - * Widget which shows a listbox item icon, first item markup column. $ - * - * -label & & styled_widget & m & - * Widget which shows a listbox item label, second item markup column. $ - * - * -description & & styled_widget & m & - * Widget which shows a listbox item description, third item markup - * column. $ - * - * @end{table} - */ - REGISTER_DIALOG(campaign_difficulty) config generate_difficulty_config(const config& source) diff --git a/src/gui/dialogs/campaign_difficulty.hpp b/src/gui/dialogs/campaign_difficulty.hpp index d4c66f2aafe6..a55a76bd0601 100644 --- a/src/gui/dialogs/campaign_difficulty.hpp +++ b/src/gui/dialogs/campaign_difficulty.hpp @@ -30,6 +30,19 @@ namespace dialogs */ config generate_difficulty_config(const config& source); +/** + * @ingroup GUIWindowDefinitionWML + * + * The campaign mode difficulty menu. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * message | scroll_label |no |Text label displaying a description or instructions. + * listbox | @ref listbox |yes |Listbox displaying user choices, defined by WML for each campaign. + * icon | control |yes |Widget which shows a listbox item icon, first item markup column. + * label | control |yes |Widget which shows a listbox item label, second item markup column. + * description | control |yes |Widget which shows a listbox item description, third item markup column. + */ class campaign_difficulty : public modal_dialog { public: diff --git a/src/gui/dialogs/campaign_selection.cpp b/src/gui/dialogs/campaign_selection.cpp index 7a0d489037c2..24b32d508bbd 100644 --- a/src/gui/dialogs/campaign_selection.cpp +++ b/src/gui/dialogs/campaign_selection.cpp @@ -43,44 +43,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_campaign_selection - * - * == Campaign selection == - * - * This shows the dialog which allows the user to choose which campaign to - * play. - * - * @begin{table}{dialog_widgets} - * - * campaign_tree & & tree_view & m & - * A tree_view that contains all available campaigns. $ - * - * -icon & & image & o & - * The icon for the campaign. $ - * - * -name & & styled_widget & o & - * The name of the campaign. $ - * - * -victory & & image & o & - * The icon to show when the user finished the campaign. The engine - * determines whether or not the user has finished the campaign and - * sets the visible flag for the widget accordingly. $ - * - * campaign_details & & multi_page & m & - * A multi page widget that shows more details for the selected - * campaign. $ - * - * -image & & image & o & - * The image for the campaign. $ - * - * -description & & styled_widget & o & - * The description of the campaign. $ - * - * @end{table} - */ - REGISTER_DIALOG(campaign_selection) void campaign_selection::campaign_selected() diff --git a/src/gui/dialogs/campaign_selection.hpp b/src/gui/dialogs/campaign_selection.hpp index b0c3bd367cef..ccdda8228fdc 100644 --- a/src/gui/dialogs/campaign_selection.hpp +++ b/src/gui/dialogs/campaign_selection.hpp @@ -26,6 +26,20 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog which allows the user to choose which campaign to play. + * Key |Type |Mandatory|Description + * ------------------|-----------------|---------|----------- + * campaign_list | @ref listbox |yes |A listbox that contains all available campaigns. + * icon | @ref image |no |The icon for the campaign. + * name | control |no |The name of the campaign. + * victory | @ref image |no |The icon to show when the user finished the campaign. The engine determines whether or not the user has finished the campaign and sets the visible flag for the widget accordingly. + * campaign_details | @ref multi_page |yes |A multi page widget that shows more details for the selected campaign. + * image | @ref image |no |The image for the campaign. + * description | control |no |The description of the campaign. + */ class campaign_selection : public modal_dialog { enum CAMPAIGN_ORDER {RANK, DATE, NAME}; diff --git a/src/gui/dialogs/chat_log.cpp b/src/gui/dialogs/chat_log.cpp index fb35fd17c633..501d339e733a 100644 --- a/src/gui/dialogs/chat_log.cpp +++ b/src/gui/dialogs/chat_log.cpp @@ -49,17 +49,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 3_chat_log - * - * == Settings manager == - * - * This shows the settings manager - * - */ - - REGISTER_DIALOG(chat_log) // The model is an interface defining the data to be displayed or otherwise diff --git a/src/gui/dialogs/core_selection.cpp b/src/gui/dialogs/core_selection.cpp index ae80ba5c6bb5..d6988da5b537 100644 --- a/src/gui/dialogs/core_selection.cpp +++ b/src/gui/dialogs/core_selection.cpp @@ -31,39 +31,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_core_selection - * - * == Core selection == - * - * This shows the dialog which allows the user to choose which core to - * play. - * - * @begin{table}{dialog_widgets} - * - * core_list & & listbox & m & - * A listbox that contains all available cores. $ - * - * -icon & & image & o & - * The icon for the core. $ - * - * -name & & styled_widget & o & - * The name of the core. $ - * - * core_details & & multi_page & m & - * A multi page widget that shows more details for the selected - * core. $ - * - * -image & & image & o & - * The image for the core. $ - * - * -description & & styled_widget & o & - * The description of the core. $ - * - * @end{table} - */ - REGISTER_DIALOG(core_selection) void core_selection::core_selected() const diff --git a/src/gui/dialogs/core_selection.hpp b/src/gui/dialogs/core_selection.hpp index f65630d30a5e..851c29eab5b1 100644 --- a/src/gui/dialogs/core_selection.hpp +++ b/src/gui/dialogs/core_selection.hpp @@ -23,6 +23,19 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog which allows the user to choose which core to play. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * core_list | @ref listbox |yes |A listbox that contains all available cores. + * icon | @ref image |no |The icon for the core. + * name | control |no |The name of the core. + * core_details | multi_page |yes |A multi page widget that shows more details for the selected core. + * image | @ref image |no |The image for the core. + * description | control |no |The description of the core. + */ class core_selection : public modal_dialog { public: diff --git a/src/gui/dialogs/debug_clock.cpp b/src/gui/dialogs/debug_clock.cpp index 1a99a61d7b2e..09b038489594 100644 --- a/src/gui/dialogs/debug_clock.cpp +++ b/src/gui/dialogs/debug_clock.cpp @@ -33,48 +33,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_clock - * - * == Clock == - * - * This shows the dialog for keeping track of the drawing events related to the - * current time. (This window is used for debug purposes only.) - * - * @begin{table}{dialog_widgets} - * hour_percentage & & progress_bar & o & - * This shows the hours as a percentage, where 24 hours is 100%. $ - * minute_percentage & & progress_bar & o & - * This shows the minutes as a percentage, where 60 minutes is 100%. $ - * second_percentage & & progress_bar & o & - * This shows the seconds as a percentage, where 60 seconds is 100%. $ - * - * hour & & integer_selector & o & - * This shows the seconds since the beginning of the day. The styled_widget - * should have a ''minimum_value'' of 0 and a ''maximum_value'' of 86399 - * (24 * 60 * 60 - 1). $ - * - * minute & & integer_selector & o & - * This shows the seconds since the beginning of the current hour. The - * styled_widget should have a ''minimum_value'' of 0 and a ''maximum_value'' - * of 3599 (60 * 60 - 1). $ - * - * minute & & integer_selector & o & - * This shows the seconds since the beginning of the current minute. The - * styled_widget should have a ''minimum_value'' of 0 and a ''maximum_value'' - * of 59. $ - * - * clock & & styled_widget & o & - * A styled_widget which will have set three variables in its canvas: - * @* hour, the same value as the hour integer_selector. - * @* minute, the same value as the minute integer_selector. - * @* second, the same value as the second integer_selector. - * @- the styled_widget can then should the time in its own preferred - * format(s). $ - * @end{table} - */ - REGISTER_DIALOG(debug_clock) void debug_clock::pre_show(window& window) diff --git a/src/gui/dialogs/debug_clock.hpp b/src/gui/dialogs/debug_clock.hpp index 018adc59978e..f4bfa78c6738 100644 --- a/src/gui/dialogs/debug_clock.hpp +++ b/src/gui/dialogs/debug_clock.hpp @@ -29,7 +29,22 @@ class integer_selector; namespace dialogs { -/** Clock to test the draw events. */ +/** + * @ingroup GUIWindowDefinitionWML + * + * Clock to test the draw events. + * + * This shows the dialog for keeping track of the drawing events related to the current time. (This window is used for debug purposes only.) + * Key |Type |Mandatory|Description + * ------------------|------------------|---------|----------- + * hour_percentage | progress_bar |no |This shows the hours as a percentage, where 24 hours is 100%. + * minute_percentage | progress_bar |no |This shows the minutes as a percentage, where 60 minutes is 100%. + * second_percentage | progress_bar |no |This shows the seconds as a percentage, where 60 seconds is 100%. + * hour | integer_selector |no |This shows the seconds since the beginning of the day. The control should have a minimum_value of 0 and a maximum_value of 86399 (246060 - 1). + * minute | integer_selector |no |This shows the seconds since the beginning of the current hour. The control should have a minimum_value of 0 and a maximum_value of 3599 (6060 - 1). + * second | integer_selector |no |This shows the seconds since the beginning of the current minute. The control should have a minimum_value of 0 and a maximum_value of 59. + * clock | control |no |A control which will have set three variables in its canvas:
  • hour - the same value as the hour integer_selector.
  • minute - the same value as the minute integer_selector.
  • second - the same value as the second integer_selector.
The control can then show the time in its own preferred format(s). + */ class debug_clock : public modeless_dialog { public: diff --git a/src/gui/dialogs/depcheck_confirm_change.cpp b/src/gui/dialogs/depcheck_confirm_change.cpp index 1d1916e7e185..820e81a9c682 100644 --- a/src/gui/dialogs/depcheck_confirm_change.cpp +++ b/src/gui/dialogs/depcheck_confirm_change.cpp @@ -26,32 +26,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_depcheck_confirm_change - * - * == SP/MP Dependency Check: Confirm Change == - * - * Asks the user to confirm a change required to proceed. Currently used - * for enabling/disabling modifications - * - * @begin{table}{dialog_widgets} - * - * message & & label & m & - * displays the details of the required changes $ - * - * itemlist & & scroll_label & m & - * displays the list of affected items $ - * - * cancel & & button & m & - * refuse to apply changes $ - * - * ok & & button & m & - * agree to apply changes $ - * - * @end{table} - */ - REGISTER_DIALOG(depcheck_confirm_change) depcheck_confirm_change::depcheck_confirm_change( diff --git a/src/gui/dialogs/depcheck_confirm_change.hpp b/src/gui/dialogs/depcheck_confirm_change.hpp index b87790ad5139..936b251dce36 100644 --- a/src/gui/dialogs/depcheck_confirm_change.hpp +++ b/src/gui/dialogs/depcheck_confirm_change.hpp @@ -23,6 +23,17 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Asks the user to confirm a change required to proceed. Currently used for enabling/disabling modifications. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * message | @ref label |yes |displays the details of the required changes + * itemlist | scroll_label |yes |displays the list of affected items + * cancel | @ref button |yes |refuse to apply changes + * ok | @ref button |yes |agree to apply changes + */ class depcheck_confirm_change : public modal_dialog { public: diff --git a/src/gui/dialogs/depcheck_select_new.cpp b/src/gui/dialogs/depcheck_select_new.cpp index c3988dd48a0f..c3c0e0ddfa39 100644 --- a/src/gui/dialogs/depcheck_select_new.cpp +++ b/src/gui/dialogs/depcheck_select_new.cpp @@ -27,33 +27,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_depcheck_select_new - * - * == SP/MP Dependency Check: Select New == - * - * Offers a list of compatible items if a currently selected one is - * incompatible. Currently used for switching era or map. - * - * @begin{table}{dialog_widgets} - * - * message & & label & m & - * displays the details of the required changes $ - * - * itemlist & & listbox & m & - * displays the available items to choose from $ - * - * cancel & & button & m & - * refuse to apply any changes $ - * - * ok & & button & m & - * select the chosen item $ - * - * @end{table} - * - */ - REGISTER_DIALOG(depcheck_select_new) depcheck_select_new::depcheck_select_new( diff --git a/src/gui/dialogs/depcheck_select_new.hpp b/src/gui/dialogs/depcheck_select_new.hpp index dc33308d7bec..7ca84189e24b 100644 --- a/src/gui/dialogs/depcheck_select_new.hpp +++ b/src/gui/dialogs/depcheck_select_new.hpp @@ -24,6 +24,17 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Offers a list of compatible items if a currently selected one is incompatible. Currently used for switching era or map. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * message | @ref label |yes |displays the details of the required changes + * itemlist | @ref listbox |yes |displays the available items to choose from + * cancel | @ref button |yes |refuse to apply any changes + * ok | @ref button |yes |select the chosen item + */ class depcheck_select_new : public modal_dialog { public: diff --git a/src/gui/dialogs/edit_label.cpp b/src/gui/dialogs/edit_label.cpp index 75981c6f5d50..b83ff684bf82 100644 --- a/src/gui/dialogs/edit_label.cpp +++ b/src/gui/dialogs/edit_label.cpp @@ -23,29 +23,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_edit_label - * - * == Edit label == - * - * Dialog for editing gamemap labels. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * label & & text_box & m & - * Input field for the map label. $ - * - * team_only_toggle & & toggle_button & m & - * Checkbox for whether to make the label visible to the player's team - * only or not. $ - * - * @end{table} - */ - REGISTER_DIALOG(edit_label) edit_label::edit_label(std::string& label, bool& team_only) diff --git a/src/gui/dialogs/edit_label.hpp b/src/gui/dialogs/edit_label.hpp index e035d4b5c342..31ba802822c3 100644 --- a/src/gui/dialogs/edit_label.hpp +++ b/src/gui/dialogs/edit_label.hpp @@ -21,6 +21,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for editing gamemap labels. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * label | @ref text_box |yes |Input field for the map label. + * team_only_toggle | toggle_button |yes |Checkbox for whether to make the label visible to the player's team only or not. + */ class edit_label : public modal_dialog { public: diff --git a/src/gui/dialogs/edit_text.cpp b/src/gui/dialogs/edit_text.cpp index 1fabceca652f..ef96eeb56cf7 100644 --- a/src/gui/dialogs/edit_text.cpp +++ b/src/gui/dialogs/edit_text.cpp @@ -28,22 +28,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_rename_unit - * - * == Rename unit == - * - * Dialog for renaming units in-game. - * - * @begin{table}{dialog_widgets} - * - * name & & text_box & m & - * Input field for the unit name. $ - * - * @end{table} - */ - REGISTER_DIALOG(edit_text) edit_text::edit_text(const std::string& title, diff --git a/src/gui/dialogs/edit_text.hpp b/src/gui/dialogs/edit_text.hpp index e92c40c64a5f..5d976c069892 100644 --- a/src/gui/dialogs/edit_text.hpp +++ b/src/gui/dialogs/edit_text.hpp @@ -21,6 +21,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for renaming units in-game. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * name | text_box |yes |Input field for the unit name. + */ class edit_text : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/custom_tod.cpp b/src/gui/dialogs/editor/custom_tod.cpp index f8fb39799ce3..0e10496b10dd 100644 --- a/src/gui/dialogs/editor/custom_tod.cpp +++ b/src/gui/dialogs/editor/custom_tod.cpp @@ -37,52 +37,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_custom_tod - * - * == Custom Schedules == - * - * This shows the dialog to modify tod schedules. - * - * @begin{table}{dialog_widgets} - * - * current_tod_name & & text_box & m & - * The name of the time of day(ToD). $ - * - * current_tod_id & & text_box & m & - * The id of the time of day(ToD). $ - * - * current_tod_image & & image & m & - * The image for the time of day(ToD). $ - * - * current_tod_mask & & image & m & - * The image mask for the time of day(ToD). $ - * - * current_tod_sonund & & label & m & - * The sound for the time of day(ToD). $ - * - * next_tod & & button & m & - * Selects the next ToD. $ - * - * prev_tod & & button & m & - * Selects the previous ToD. $ - * - * lawful_bonus & & slider & m & - * Sets the Lawful Bonus for the current ToD. $ - * - * tod_red & & slider & m & - * Sets the red component of the current ToD. $ - * - * tod_green & & slider & m & - * Sets the green component of the current ToD. $ - * - * tod_blue & & slider & m & - * Sets the blue component of the current ToD. $ - * - * @end{table} - */ - static custom_tod::string_pair tod_getter_image(const time_of_day& tod) { static std::string type = "image"; diff --git a/src/gui/dialogs/editor/custom_tod.hpp b/src/gui/dialogs/editor/custom_tod.hpp index 04b8987b977e..f3044711d569 100644 --- a/src/gui/dialogs/editor/custom_tod.hpp +++ b/src/gui/dialogs/editor/custom_tod.hpp @@ -26,6 +26,24 @@ class slider; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to modify tod schedules. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * current_tod_name | text_box |yes |The name of the time of day(ToD). + * current_tod_id | text_box |yes |The id of the time of day(ToD). + * current_tod_image | @ref image |yes |The image for the time of day(ToD). + * current_tod_mask | @ref image |yes |The image mask for the time of day(ToD). + * current_tod_sound | @ref label |yes |The sound for the time of day(ToD). + * next_tod | @ref button |yes |Selects the next ToD. + * prev_tod | @ref button |yes |Selects the previous ToD. + * lawful_bonus | @ref slider |yes |Sets the Lawful Bonus for the current ToD. + * tod_red | @ref slider |yes |Sets the red component of the current ToD. + * tod_green | @ref slider |yes |Sets the green component of the current ToD. + * tod_blue | @ref slider |yes |Sets the blue component of the current ToD. + */ class custom_tod : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/edit_label.cpp b/src/gui/dialogs/editor/edit_label.cpp index 9881196fb7f7..19551c98bfb6 100644 --- a/src/gui/dialogs/editor/edit_label.cpp +++ b/src/gui/dialogs/editor/edit_label.cpp @@ -28,29 +28,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_edit_label - * - * == Edit label == - * - * Dialog for editing gamemap labels. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * label & & text_box & m & - * Input field for the map label. $ - * - * team_only_toggle & & toggle_button & m & - * Checkbox for whether to make the label visible to the player's team - * only or not. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_edit_label) editor_edit_label::editor_edit_label(std::string& text, diff --git a/src/gui/dialogs/editor/edit_label.hpp b/src/gui/dialogs/editor/edit_label.hpp index f1a0022f3ebf..1748b3a55736 100644 --- a/src/gui/dialogs/editor/edit_label.hpp +++ b/src/gui/dialogs/editor/edit_label.hpp @@ -22,6 +22,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for editing gamemap labels. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * label | @ref text_box |yes |Input field for the map label. + * team_only_toggle | toggle_button |yes |Checkbox for whether to make the label visible to the player's team only or not. + */ class editor_edit_label : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/edit_scenario.cpp b/src/gui/dialogs/editor/edit_scenario.cpp index d9e3c9e1ad02..29f2fa155004 100644 --- a/src/gui/dialogs/editor/edit_scenario.cpp +++ b/src/gui/dialogs/editor/edit_scenario.cpp @@ -26,29 +26,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_edit_scenario - * - * == Edit scenario == - * - * Dialog for editing gamemap scenarios. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * label & & text_box & m & - * Input field for the map label. $ - * - * team_only_toggle & & toggle_button & m & - * Checkbox for whether to make the label visible to the player's team - * only or not. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_edit_scenario) editor_edit_scenario::editor_edit_scenario( diff --git a/src/gui/dialogs/editor/edit_scenario.hpp b/src/gui/dialogs/editor/edit_scenario.hpp index 52598ebc7128..8b8b15f9705a 100644 --- a/src/gui/dialogs/editor/edit_scenario.hpp +++ b/src/gui/dialogs/editor/edit_scenario.hpp @@ -21,6 +21,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for editing gamemap scenarios. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * label | @ref text_box |yes |Input field for the map label. + * team_only_toggle | toggle_button |yes |Checkbox for whether to make the label visible to the player's team only or not. + */ class editor_edit_scenario : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/edit_side.cpp b/src/gui/dialogs/editor/edit_side.cpp index 2156e0f08e0a..cdb203f94782 100644 --- a/src/gui/dialogs/editor/edit_side.cpp +++ b/src/gui/dialogs/editor/edit_side.cpp @@ -27,29 +27,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_edit_side - * - * == Edit side == - * - * Dialog for editing gamemap sides. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * id & & text_box & m & - * Input field for the id. $ - * - * team_only_toggle & & toggle_button & m & - * Checkbox for whether to make the label visible to the player's team - * only or not. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_edit_side) editor_edit_side::editor_edit_side(editor::editor_team_info& info) diff --git a/src/gui/dialogs/editor/edit_side.hpp b/src/gui/dialogs/editor/edit_side.hpp index 9bef4ef3d372..60243249802d 100644 --- a/src/gui/dialogs/editor/edit_side.hpp +++ b/src/gui/dialogs/editor/edit_side.hpp @@ -25,6 +25,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for editing gamemap sides. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * label | @ref text_box |yes |Input field for the id. + * team_only_toggle | toggle_button |yes |Checkbox for whether to make the label visible to the player's team only or not. + */ class editor_edit_side : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/generate_map.cpp b/src/gui/dialogs/editor/generate_map.cpp index bcfe28a74b54..5fc914880681 100644 --- a/src/gui/dialogs/editor/generate_map.cpp +++ b/src/gui/dialogs/editor/generate_map.cpp @@ -35,29 +35,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_editor_generate_map - * - * == Editor generate map == - * - * This shows the dialog in the editor to select which random generator - * should be used to generate a map. - * - * @begin{table}{dialog_widgets} - * - * generators_list & & listbox & m & - * Listbox displaying known map generators. $ - * - * settings & & button & m & - * When clicked this button opens the generator settings dialog. $ - * - * seed_textbox & & text_box & m & - * Allows entering a seed for the map generator. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_generate_map) editor_generate_map::editor_generate_map(std::vector>& mg) diff --git a/src/gui/dialogs/editor/generate_map.hpp b/src/gui/dialogs/editor/generate_map.hpp index ff44d2ef1c27..02694ec3cef9 100644 --- a/src/gui/dialogs/editor/generate_map.hpp +++ b/src/gui/dialogs/editor/generate_map.hpp @@ -28,7 +28,16 @@ namespace gui2 namespace dialogs { -/** The dialog for selecting which random generator to use in the editor. */ +/** + * @ingroup GUIWindowDefinitionWML + * + * The dialog for selecting which random generator to use in the editor. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * generators_list | @ref listbox |yes |Listbox displaying known map generators. + * settings | @ref button |yes |When clicked this button opens the generator settings dialog. + * seed_textbox | text_box |yes |Allows entering a seed for the map generator. + */ class editor_generate_map : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/new_map.cpp b/src/gui/dialogs/editor/new_map.cpp index 688aaf7426af..7564df4330d0 100644 --- a/src/gui/dialogs/editor/new_map.cpp +++ b/src/gui/dialogs/editor/new_map.cpp @@ -22,25 +22,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_editor_new_map - * - * == Editor new map == - * - * This shows the dialog to generate a new map in the editor. - * - * @begin{table}{dialog_widgets} - * - * width & & integer_selector & m & - * An integer selector to determine the width of the map to create. $ - * - * height & & integer_selector & m & - * An integer selector to determine the height of the map to create. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_new_map) editor_new_map::editor_new_map(const t_string& title, int& width, int& height) diff --git a/src/gui/dialogs/editor/new_map.hpp b/src/gui/dialogs/editor/new_map.hpp index b258ae8f70f5..acc0d3b12306 100644 --- a/src/gui/dialogs/editor/new_map.hpp +++ b/src/gui/dialogs/editor/new_map.hpp @@ -23,6 +23,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Key |Type |Mandatory|Description + * ------------------|------------------|---------|----------- + * width | integer_selector |yes |An integer selector to determine the width of the map to create. + * height | integer_selector |yes |An integer selector to determine the height of the map to create. + */ class editor_new_map : public modal_dialog { public: diff --git a/src/gui/dialogs/editor/resize_map.cpp b/src/gui/dialogs/editor/resize_map.cpp index 02e6dc491df3..c6a44c8a419b 100644 --- a/src/gui/dialogs/editor/resize_map.cpp +++ b/src/gui/dialogs/editor/resize_map.cpp @@ -27,66 +27,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_editor_resize_map - * - * == Editor resize map == - * - * This shows the dialog to resize the current map. - * - * @begin{table}{dialog_widgets} - * - * old_width & & label & o & - * Shows the old width of the map. $ - * - * old_height & & label & o & - * Shows the old height of the map. $ - * - * width & & slider & m & - * Determines the new width of the map. $ - * - * height & & slider & m & - * Determines the new height of the map. $ - * - * copy_edge_terrain & & boolean_selector & m & - * Determines whether the border terrains should be used to expand or - * not. $ - * - * expand0 & & toggle_button & m & - * Determines in which direction to expand, shows the north east - * marker. $ - * - * expand1 & & toggle_button & m & - * Determines in which direction to expand, shows the north marker. $ - * - * expand2 & & toggle_button & m & - * Determines in which direction to expand, shows the north west - * marker. $ - * - * expand3 & & toggle_button & m & - * Determines in which direction to expand, shows the east marker. $ - * - * expand4 & & toggle_button & m & - * Determines in which direction to expand, shows the center marker. $ - * - * expand5 & & toggle_button & m & - * Determines in which direction to expand, shows the west marker. $ - * - * expand6 & & toggle_button & m & - * Determines in which direction to expand, shows the south east - * marker. $ - * - * expand7 & & toggle_button & m & - * Determines in which direction to expand, shows the south marker. $ - * - * expand8 & & toggle_button & m & - * Determines in which direction to expand, shows the south west - * marker. $ - * - * @end{table} - */ - REGISTER_DIALOG(editor_resize_map) editor_resize_map::editor_resize_map(int& width, diff --git a/src/gui/dialogs/editor/resize_map.hpp b/src/gui/dialogs/editor/resize_map.hpp index bf428c9a829b..13ae77d844d5 100644 --- a/src/gui/dialogs/editor/resize_map.hpp +++ b/src/gui/dialogs/editor/resize_map.hpp @@ -24,6 +24,27 @@ class toggle_button; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to resize the current map. + * Key |Type |Mandatory|Description + * ------------------|------------------|---------|----------- + * old_width | @ref label |no |Shows the old width of the map. + * old_height | @ref label |no |Shows the old height of the map. + * width | @ref slider |yes |Determines the new width of the map. + * height | @ref slider |yes |Determines the new height of the map. + * copy_edge_terrain | boolean_selector |yes |Determines whether the border terrains should be used to expand or not. + * expand0 | toggle_button |yes |Determines in which direction to expand, shows the north east marker. + * expand1 | toggle_button |yes |Determines in which direction to expand, shows the north marker. + * expand2 | toggle_button |yes |Determines in which direction to expand, shows the north west marker. + * expand3 | toggle_button |yes |Determines in which direction to expand, shows the east marker. + * expand4 | toggle_button |yes |Determines in which direction to expand, shows the center marker. + * expand5 | toggle_button |yes |Determines in which direction to expand, shows the west marker. + * expand6 | toggle_button |yes |Determines in which direction to expand, shows the south east marker. + * expand7 | toggle_button |yes |Determines in which direction to expand, shows the south marker. + * expand8 | toggle_button |yes |Determines in which direction to expand, shows the south west marker. + */ class editor_resize_map : public modal_dialog { public: diff --git a/src/gui/dialogs/folder_create.cpp b/src/gui/dialogs/folder_create.cpp index dfaf8b0cb8e4..606445d3cbe7 100644 --- a/src/gui/dialogs/folder_create.cpp +++ b/src/gui/dialogs/folder_create.cpp @@ -27,25 +27,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_folder_create - * - * == Folder Create == - * - * Dialog for providing the name of a new folder or bookmark to create. - * Used by the file dialog. - * - * @begin{table}{dialog_widgets} - * - * title & & styled_widget & m & - * Label with the dialog caption. Changed in bookmark mode. $ - * name & & text_box & m & - * Input field for the new folder/bookmark name. $ - * - * @end{table} - */ - REGISTER_DIALOG(folder_create) folder_create::folder_create(std::string& folder_name) diff --git a/src/gui/dialogs/folder_create.hpp b/src/gui/dialogs/folder_create.hpp index a486b8305066..4b7e7bc964e5 100644 --- a/src/gui/dialogs/folder_create.hpp +++ b/src/gui/dialogs/folder_create.hpp @@ -21,6 +21,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for providing the name of a new folder to create. Used by the file dialog. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * name | text_box |yes |Input field for the new folder name. + */ class folder_create : public modal_dialog { public: diff --git a/src/gui/dialogs/formula_debugger.cpp b/src/gui/dialogs/formula_debugger.cpp index d9b4a06a2073..2ebd5afd29e8 100644 --- a/src/gui/dialogs/formula_debugger.cpp +++ b/src/gui/dialogs/formula_debugger.cpp @@ -31,40 +31,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_formula_debugger - * - * == Formula debugger == - * - * This shows the debugger for the formulas. - * - * @begin{table}{dialog_widgets} - * - * stack & & styled_widget & m & - * A stack. $ - * - * execution & & styled_widget & m & - * Execution trace label. $ - * - * state & & styled_widget & m & - * The state. $ - * - * step & & button & m & - * Button to step into the execution. $ - * - * stepout & & button & m & - * Button to step out of the execution. $ - * - * next & & button & m & - * Button to execute the next statement. $ - * - * continue & & button & m & - * Button to continue the execution. $ - * - * @end{table} - */ - REGISTER_DIALOG(formula_debugger) void formula_debugger::pre_show(window& window) diff --git a/src/gui/dialogs/formula_debugger.hpp b/src/gui/dialogs/formula_debugger.hpp index 4aa35f04096b..3af04fa5ce85 100644 --- a/src/gui/dialogs/formula_debugger.hpp +++ b/src/gui/dialogs/formula_debugger.hpp @@ -26,6 +26,20 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the debugger for the formulas. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * stack | control |yes |A stack. + * execution | control |yes |Execution trace label. + * state | control |yes |The state. + * step | @ref button |yes |Button to step into the execution. + * stepout | @ref button |yes |Button to step out of the execution. + * next | @ref button |yes |Button to execute the next statement. + * continue | @ref button |yes |Button to continue the execution. + */ class formula_debugger : public modal_dialog { public: diff --git a/src/gui/dialogs/game_cache_options.cpp b/src/gui/dialogs/game_cache_options.cpp index ba603d068647..918a88ffa885 100644 --- a/src/gui/dialogs/game_cache_options.cpp +++ b/src/gui/dialogs/game_cache_options.cpp @@ -38,42 +38,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_game_cache_options - * - * == Game cache options == - * - * A Preferences subdialog including a report on the location and size of the - * game's WML cache, buttons to copy its path to clipboard or browse to it, - * and the possibility of clearing stale files from the cache or purging it - * entirely. - * - * @begin{table}{dialog_widgets} - * - * path & & text_box & m & - * Cache dir path. $ - * - * copy & & button & m & - * Copies the cache path to clipboard. $ - * - * browse & & button & m & - * Browses to the cache path using the platform's file management - * application. $ - * - * size & & label & m & - * Current total size of the cache dir's contents. $ - * - * clean & & button & m & - * Cleans the cache, erasing stale files not used by the Wesnoth - * version presently running the dialog. $ - * - * purge & & button & m & - * Purges the cache in its entirety. $ - * - * @end{table} - */ - REGISTER_DIALOG(game_cache_options) game_cache_options::game_cache_options() diff --git a/src/gui/dialogs/game_cache_options.hpp b/src/gui/dialogs/game_cache_options.hpp index 4275992bcb79..0f3618b7230f 100644 --- a/src/gui/dialogs/game_cache_options.hpp +++ b/src/gui/dialogs/game_cache_options.hpp @@ -23,6 +23,20 @@ class button; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * A Preferences subdialog including a report on the location and size of the game's WML cache, + * buttons to copy its path to clipboard or browse to it, and the possibility of clearing stale files from the cache or purging it entirely. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * path | text_box |yes |Cache dir path. + * copy | @ref button |yes |Copies the cache path to clipboard. + * browse | @ref button |yes |Browses to the cache path using the platform's file management application. + * size | @ref label |yes |Current total size of the cache dir's contents. + * clean | @ref button |yes |Cleans the cache, erasing stale files not used by the Wesnoth version presently running the dialog. + * purge | @ref button |yes |Purges the cache in its entirety. + */ class game_cache_options : public modal_dialog { public: diff --git a/src/gui/dialogs/game_delete.cpp b/src/gui/dialogs/game_delete.cpp index a5da9ca81397..82b028d45e21 100644 --- a/src/gui/dialogs/game_delete.cpp +++ b/src/gui/dialogs/game_delete.cpp @@ -22,22 +22,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_game_delete - * - * == Delete a savegame == - * - * This shows the dialog to confirm deleting a savegame file. - * - * @begin{table}{dialog_widgets} - * - * dont_ask_again & & boolean_selector & m & - * A checkbox to not show this dialog again. $ - * - * @end{table} - */ - REGISTER_DIALOG(game_delete) /** diff --git a/src/gui/dialogs/game_delete.hpp b/src/gui/dialogs/game_delete.hpp index d78786d17db3..8cd40e905904 100644 --- a/src/gui/dialogs/game_delete.hpp +++ b/src/gui/dialogs/game_delete.hpp @@ -21,6 +21,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to confirm deleting a savegame file. + * Key |Type |Mandatory|Description + * ------------------|------------------|---------|----------- + * dont_ask_again | boolean_selector |yes |A checkbox to not show this dialog again. + */ class game_delete : public modal_dialog { public: diff --git a/src/gui/dialogs/game_load.cpp b/src/gui/dialogs/game_load.cpp index 47de31e36d78..df992049d925 100644 --- a/src/gui/dialogs/game_load.cpp +++ b/src/gui/dialogs/game_load.cpp @@ -58,49 +58,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_game_load - * - * == Load a game == - * - * This shows the dialog to select and load a savegame file. - * - * @begin{table}{dialog_widgets} - * - * txtFilter & & text & m & - * The filter for the listbox items. $ - * - * dirList & & menu_button & m & - * Allows changing directory to the directories for old versions of Wesnoth. $ - * - * savegame_list & & listbox & m & - * List of savegames. $ - * - * -filename & & styled_widget & m & - * Name of the savegame. $ - * - * -date & & styled_widget & o & - * Date the savegame was created. $ - * - * -minimap & & minimap & m & - * Minimap of the selected savegame. $ - * - * -imgLeader & & image & m & - * The image of the leader in the selected savegame. $ - * - * -lblScenario & & label & m & - * The name of the scenario of the selected savegame. $ - * - * -lblSummary & & label & m & - * Summary of the selected savegame. $ - * - * delete & & button & m & - * Delete the selected savegame. $ - * - * @end{table} - */ - REGISTER_DIALOG(game_load) game_load::game_load(const game_config_view& cache_config, savegame::load_game_metadata& data) diff --git a/src/gui/dialogs/game_load.hpp b/src/gui/dialogs/game_load.hpp index 749a9cf1df48..ddb93421dc00 100644 --- a/src/gui/dialogs/game_load.hpp +++ b/src/gui/dialogs/game_load.hpp @@ -29,6 +29,22 @@ class text_box_base; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to select and load a savegame file. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * txtFilter | text |yes |The filter for the listbox items. + * savegame_list | @ref listbox |yes |List of savegames. + * filename | control |yes |Name of the savegame. + * date | control |no |Date the savegame was created. + * preview_pane | widget |yes |Container widget or grid that contains the items for a preview. The visible status of this container depends on whether or not something is selected. + * minimap | @ref minimap |yes |Minimap of the selected savegame. + * imgLeader | @ref image |yes |The image of the leader in the selected savegame. + * lblScenario | @ref label |yes |The name of the scenario of the selected savegame. + * lblSummary | @ref label |yes |Summary of the selected savegame. + */ class game_load : public modal_dialog { public: diff --git a/src/gui/dialogs/game_save.cpp b/src/gui/dialogs/game_save.cpp index 7e698c75a263..6d2eef041dfe 100644 --- a/src/gui/dialogs/game_save.cpp +++ b/src/gui/dialogs/game_save.cpp @@ -27,25 +27,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_game_save - * - * == Save a game == - * - * This shows the dialog to create a savegame file. - * - * @begin{table}{dialog_widgets} - * - * lblTitle & & label & m & - * The title of the window. $ - * - * txtFilename & & text_box & m & - * The name of the savefile. $ - * - * @end{table} - */ - REGISTER_DIALOG(game_save) game_save::game_save(std::string& filename, const std::string& title) diff --git a/src/gui/dialogs/game_save.hpp b/src/gui/dialogs/game_save.hpp index ddb521bd3d16..e41fa2a9cf7f 100644 --- a/src/gui/dialogs/game_save.hpp +++ b/src/gui/dialogs/game_save.hpp @@ -21,6 +21,15 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to create a savegame file. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * lblTitle | @ref label |yes |The title of the window. + * txtFilename | text_box |yes |The name of the savefile. + */ class game_save : public modal_dialog { public: diff --git a/src/gui/dialogs/game_version_dialog.cpp b/src/gui/dialogs/game_version_dialog.cpp index 5fdbabe24ad9..2b66c4182303 100644 --- a/src/gui/dialogs/game_version_dialog.cpp +++ b/src/gui/dialogs/game_version_dialog.cpp @@ -54,33 +54,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_game_version - * - * == Game paths == - * - * Dialog displaying the various paths used by the game to locate - * resource and configuration files. - * - * There are several item types used to build widget ids in this dialog. - * All references to TYPE below refer to the following suffixes: - * datadir, config, userdata, saves, addons, cache. - * - * @begin{table}{dialog_widgets} - * - * path_TYPE & & text_box & m & - * Textbox containing the filesystem path for the given item. $ - * - * copy_TYPE & & button & m & - * Copies the given item's path to clipboard. $ - * - * browse_TYPE & & button & m & - * Launches the default file browser on the given item's path. $ - * - * @end{table} - */ - REGISTER_DIALOG(game_version) game_version::game_version() diff --git a/src/gui/dialogs/game_version_dialog.hpp b/src/gui/dialogs/game_version_dialog.hpp index e5d96bb7e468..7647d77af262 100644 --- a/src/gui/dialogs/game_version_dialog.hpp +++ b/src/gui/dialogs/game_version_dialog.hpp @@ -29,6 +29,19 @@ class listbox; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog displaying the various paths used by the game to locate resource and configuration files. + * + * There are several item types used to build widget ids in this dialog. + * All references to TYPE below refer to the following suffixes: datadir, config, userdata, saves, addons, cache. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * path_TYPE | text_box |yes |Textbox containing the filesystem path for the given item. + * copy_TYPE | @ref button |yes |Copies the given item's path to clipboard. + * browse_TYPE | @ref button |yes |Launches the default file browser on the given item's path. + */ class game_version : public modal_dialog { public: diff --git a/src/gui/dialogs/gamestate_inspector.cpp b/src/gui/dialogs/gamestate_inspector.cpp index b4697d1498c7..4fc466a0bc92 100644 --- a/src/gui/dialogs/gamestate_inspector.cpp +++ b/src/gui/dialogs/gamestate_inspector.cpp @@ -71,31 +71,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_gamestate_inspector - * - * == Gamestate inspector == - * - * This shows the gamestate inspector - * - * @begin{table}{dialog_widgets} - * - * inspector_name & & styled_widget & m & - * Name of the inspector. $ - * - * stuff_list & & styled_widget & m & - * List of various stuff that can be viewed. $ - * - * inspect & & styled_widget & m & - * The state of the variable or event. $ - * - * copy & & button & m & - * A button to copy the state to clipboard. $ - * - * @end{table} - */ - class gamestate_inspector::model { public: diff --git a/src/gui/dialogs/gamestate_inspector.hpp b/src/gui/dialogs/gamestate_inspector.hpp index 5d6b8d10ba64..df3265a85c0c 100644 --- a/src/gui/dialogs/gamestate_inspector.hpp +++ b/src/gui/dialogs/gamestate_inspector.hpp @@ -25,6 +25,17 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the gamestate inspector. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * inspector_name | control |yes |Name of the inspector. + * stuff_list | control |yes |List of various stuff that can be viewed. + * inspect | control |yes |The state of the variable or event. + * copy | @ref button |yes |A button to copy the state to clipboard. + */ class gamestate_inspector : public modal_dialog { public: diff --git a/src/gui/dialogs/language_selection.cpp b/src/gui/dialogs/language_selection.cpp index fa6338fe08b6..e6a4cdc35a39 100644 --- a/src/gui/dialogs/language_selection.cpp +++ b/src/gui/dialogs/language_selection.cpp @@ -28,27 +28,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_language_selection - * - * == Language selection == - * - * This shows the dialog to select the language to use. When the dialog is - * closed with the OK button it also updates the selected language in the - * preferences. - * - * @begin{table}{dialog_widgets} - * - * language_list & & listbox & m & - * This listbox contains the list with available languages. $ - * - * - & & styled_widget & o & - * Show the name of the language in the current row. $ - * - * @end{table} - */ - /** * @todo show we also reset the translations and is the tips of day call * really needed? diff --git a/src/gui/dialogs/language_selection.hpp b/src/gui/dialogs/language_selection.hpp index b30226c9d649..66ad739dec78 100644 --- a/src/gui/dialogs/language_selection.hpp +++ b/src/gui/dialogs/language_selection.hpp @@ -21,6 +21,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to select the language to use. + * When the dialog is closed with the OK button it also updates the selected language in the preferences. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * language_list | @ref listbox |yes |This listbox contains the list with available languages. + * free to choose | control |no |Show the name of the language in the current row. + */ class language_selection : public modal_dialog { public: diff --git a/src/gui/dialogs/lua_interpreter.cpp b/src/gui/dialogs/lua_interpreter.cpp index 5de412b0295d..93dbbfbf055f 100644 --- a/src/gui/dialogs/lua_interpreter.cpp +++ b/src/gui/dialogs/lua_interpreter.cpp @@ -62,17 +62,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 3_lua_interpretter - * - * == Settings manager == - * - * This shows the settings manager - * - */ - - REGISTER_DIALOG(lua_interpreter) // Model, View, Controller definitions diff --git a/src/gui/dialogs/modal_dialog.cpp b/src/gui/dialogs/modal_dialog.cpp index 8a8456fc0538..41b5bd394249 100644 --- a/src/gui/dialogs/modal_dialog.cpp +++ b/src/gui/dialogs/modal_dialog.cpp @@ -273,23 +273,3 @@ void modal_dialog::finalize_fields(window& window, const bool save_fields) } // namespace dialogs } // namespace gui2 - - -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 1 - * - * {{Autogenerated}} - * - * = Window definition = - * - * The window definition define how the windows shown in the dialog look. - */ - -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = ZZZZZZ_footer - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - */ diff --git a/src/gui/dialogs/multiplayer/mp_alerts_options.cpp b/src/gui/dialogs/multiplayer/mp_alerts_options.cpp index 2631da75bbcd..92690c72d529 100644 --- a/src/gui/dialogs/multiplayer/mp_alerts_options.cpp +++ b/src/gui/dialogs/multiplayer/mp_alerts_options.cpp @@ -36,31 +36,6 @@ namespace gui2 { namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_alerts_options - * - * == Lobby sounds options == - * - * A Preferences subdialog permitting to configure the sounds and notifications - * generated in response to various mp lobby / game events. - * - * @begin{table}{dialog_widgets} - * - * _label & & label & m & - * Item name. $ - * - * _sound & & toggle_button & m & - * Toggles whether to play the item sound. $ - * - * _notif & & toggle_button & m & - * Toggles whether to give a notification. $ - * - * _lobby & & toggle_button & m & - * Toggles whether to take actions for this item when in the lobby. $ - * - * @end{table} - */ static toggle_button * setup_pref_toggle_button(const std::string & id, bool def, window & window) { diff --git a/src/gui/dialogs/multiplayer/mp_alerts_options.hpp b/src/gui/dialogs/multiplayer/mp_alerts_options.hpp index e4a2d5319ac4..33ceb6aba096 100644 --- a/src/gui/dialogs/multiplayer/mp_alerts_options.hpp +++ b/src/gui/dialogs/multiplayer/mp_alerts_options.hpp @@ -21,6 +21,17 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * A Preferences subdialog permitting to configure the sounds and notifications generated in response to various mp lobby / game events. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * _label | @ref label |yes |Item name. + * _sound | toggle_button |yes |Toggles whether to play the item sound. + * _notif | toggle_button |yes |Toggles whether to give a notification. + * _lobby | toggle_button |yes |Toggles whether to take actions for this item when in the lobby. + */ class mp_alerts_options : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/mp_change_control.cpp b/src/gui/dialogs/multiplayer/mp_change_control.cpp index 7e52d16ec85d..439259a92514 100644 --- a/src/gui/dialogs/multiplayer/mp_change_control.cpp +++ b/src/gui/dialogs/multiplayer/mp_change_control.cpp @@ -45,25 +45,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_change_control - * - * == Change control dialog == - * - * This shows the multiplayer change control dialog. - * - * @begin{table}{dialog_widgets} - * sides_list & & listbox & m & - * List of sides participating in the MP game. $ - * - * nicks_list & & listbox & m & - * List of nicks of all clients playing or observing the MP game. $ - * - * @end{table} - * - */ - REGISTER_DIALOG(mp_change_control) mp_change_control::mp_change_control(events::menu_handler& mh) diff --git a/src/gui/dialogs/multiplayer/mp_change_control.hpp b/src/gui/dialogs/multiplayer/mp_change_control.hpp index ebf654193981..8007f04b3248 100644 --- a/src/gui/dialogs/multiplayer/mp_change_control.hpp +++ b/src/gui/dialogs/multiplayer/mp_change_control.hpp @@ -29,6 +29,15 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the multiplayer change control dialog. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * sides_list | @ref listbox |yes |List of sides participating in the MP game. + * nicks_list | @ref listbox |yes |List of nicks of all clients playing or observing the MP game. + */ class mp_change_control : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/mp_connect.cpp b/src/gui/dialogs/multiplayer/mp_connect.cpp index c0edabfcb22f..f42e0ebae2ac 100644 --- a/src/gui/dialogs/multiplayer/mp_connect.cpp +++ b/src/gui/dialogs/multiplayer/mp_connect.cpp @@ -59,25 +59,6 @@ void clear_listbox_selection(listbox& listbox) namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_connect - * - * == Multiplayer connect == - * - * This shows the dialog to the MP server to connect to. - * - * @begin{table}{dialog_widgets} - * - * start_table & & text_box & m & - * The name of the server to connect to. $ - * - * list & & button & o & - * Shows a dialog with a list of predefined servers to connect to. $ - * - * @end{table} - */ - REGISTER_DIALOG(mp_connect) mp_connect::mp_connect() diff --git a/src/gui/dialogs/multiplayer/mp_connect.hpp b/src/gui/dialogs/multiplayer/mp_connect.hpp index ee946b8955c3..6ac72ada3698 100644 --- a/src/gui/dialogs/multiplayer/mp_connect.hpp +++ b/src/gui/dialogs/multiplayer/mp_connect.hpp @@ -29,6 +29,15 @@ class listbox; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to the MP server to connect to. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * start_table | text_box |yes |The name of the server to connect to. + * list | @ref button |no |Shows a dialog with a list of predefined servers to connect to. + */ class mp_connect : public modal_dialog { /** The unit test needs to be able to test the mp_connect dialog. */ diff --git a/src/gui/dialogs/multiplayer/mp_host_game_prompt.cpp b/src/gui/dialogs/multiplayer/mp_host_game_prompt.cpp index 3e7dc7ce6c55..9ee8338dce04 100644 --- a/src/gui/dialogs/multiplayer/mp_host_game_prompt.cpp +++ b/src/gui/dialogs/multiplayer/mp_host_game_prompt.cpp @@ -23,22 +23,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_host_game_prompt - * - * == Host Networked Game prompt == - * - * This shows the dialog to confirm deleting a savegame file. - * - * @begin{table}{dialog_widgets} - * - * do_not_show_again & & boolean_selector & m & - * A checkbox to not show this dialog again. $ - * - * @end{table} - */ - REGISTER_DIALOG(mp_host_game_prompt) /** diff --git a/src/gui/dialogs/multiplayer/mp_host_game_prompt.hpp b/src/gui/dialogs/multiplayer/mp_host_game_prompt.hpp index affb2e8b6966..b4291b0e3db7 100644 --- a/src/gui/dialogs/multiplayer/mp_host_game_prompt.hpp +++ b/src/gui/dialogs/multiplayer/mp_host_game_prompt.hpp @@ -22,6 +22,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to confirm deleting a savegame file. + * Key |Type |Mandatory|Description + * ------------------|------------------|---------|----------- + * do_not_show_again | boolean_selector |yes |A checkbox to not show this dialog again. + */ class mp_host_game_prompt : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.cpp b/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.cpp index 58d9dcc8ed1a..c5c1d50e9524 100644 --- a/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.cpp +++ b/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.cpp @@ -21,22 +21,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_join_game_password_prompt - * - * == Join Game: Password Prompt == - * - * Dialog for entering a password for joining a password-protected MP game. - * - * @begin{table}{dialog_widgets} - * - * password & & text_box & m & - * Input field for the game password. $ - * - * @end{table} - */ - REGISTER_DIALOG(mp_join_game_password_prompt) mp_join_game_password_prompt::mp_join_game_password_prompt( diff --git a/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.hpp b/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.hpp index 4c0f9bc47abd..cece6fdf6d91 100644 --- a/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.hpp +++ b/src/gui/dialogs/multiplayer/mp_join_game_password_prompt.hpp @@ -21,6 +21,14 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for entering a password for joining a password-protected MP game. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * password | text_box |yes |Input field for the game password. + */ class mp_join_game_password_prompt : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/mp_login.cpp b/src/gui/dialogs/multiplayer/mp_login.cpp index afda0b7c713f..f01f810b1ceb 100644 --- a/src/gui/dialogs/multiplayer/mp_login.cpp +++ b/src/gui/dialogs/multiplayer/mp_login.cpp @@ -31,35 +31,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_login - * - * == Multiplayer connect == - * - * This shows the dialog to log in to the MP server - * - * @begin{table}{dialog_widgets} - * - * user_name & & text_box & m & - * The login user name. $ - * - * password & & text_box & m & - * The password. $ - * - * remember_password & & toggle_button & o & - * A toggle button to offer to remember the password in the - * preferences. $ - * - * change_username & & button & o & - * Use a different username. $ - * - * login_label & & button & o & - * Displays the information received from the server. $ - * - * @end{table} - */ - REGISTER_DIALOG(mp_login) mp_login::mp_login(const std::string& host, const std::string& label, const bool focus_password) diff --git a/src/gui/dialogs/multiplayer/mp_login.hpp b/src/gui/dialogs/multiplayer/mp_login.hpp index 758454e55fde..8e899c2bdf9a 100644 --- a/src/gui/dialogs/multiplayer/mp_login.hpp +++ b/src/gui/dialogs/multiplayer/mp_login.hpp @@ -23,6 +23,19 @@ class field_text; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to log in to the MP server. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * user_name | text_box |yes |The login user name. + * password | text_box |yes |The password. + * remember_password | toggle_button |no |A toggle button to offer to remember the password in the preferences. + * password_reminder | @ref button |no |Request a password reminder. + * change_username | @ref button |no |Use a different username. + * login_label | @ref button |no |Displays the information received from the server. + */ class mp_login : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/mp_method_selection.cpp b/src/gui/dialogs/multiplayer/mp_method_selection.cpp index 92e2ea5906be..6ab551b25a88 100644 --- a/src/gui/dialogs/multiplayer/mp_method_selection.cpp +++ b/src/gui/dialogs/multiplayer/mp_method_selection.cpp @@ -30,25 +30,6 @@ namespace gui2 { namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_mp_method_selection - * - * == MP method selection == - * - * This shows the dialog to select the kind of MP game the user wants to play. - * - * @begin{table}{dialog_widgets} - * - * user_name & & text_box & m & - * This text contains the name the user on the MP server. This widget - * will get a fixed maximum length by the engine. $ - * - * method_list & & listbox & m & - * The list with possible game methods. $ - * - * @end{table} - */ REGISTER_DIALOG(mp_method_selection) diff --git a/src/gui/dialogs/multiplayer/mp_method_selection.hpp b/src/gui/dialogs/multiplayer/mp_method_selection.hpp index 1c2512ac8ae2..022e63b004a4 100644 --- a/src/gui/dialogs/multiplayer/mp_method_selection.hpp +++ b/src/gui/dialogs/multiplayer/mp_method_selection.hpp @@ -21,6 +21,15 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to select the kind of MP game the user wants to play. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * user_name | text_box |yes |This text contains the name the user on the MP server. This widget will get a fixed maximum length by the engine. + * method_list | @ref listbox |yes |The list with possible game methods. + */ class mp_method_selection : public modal_dialog { public: diff --git a/src/gui/dialogs/multiplayer/synced_choice_wait.cpp b/src/gui/dialogs/multiplayer/synced_choice_wait.cpp index 8251c58a72ea..cfa8c8197cb9 100644 --- a/src/gui/dialogs/multiplayer/synced_choice_wait.cpp +++ b/src/gui/dialogs/multiplayer/synced_choice_wait.cpp @@ -33,28 +33,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_theme_list - * - * == Theme list == - * - * Dialog for selecting a GUI theme. - * - * @begin{table}{dialog_widgets} - * - * themes & & listbox & m & - * Listbox displaying user choices. $ - * - * -name & & styled_widget & m & - * Widget which shows a theme item name. $ - * - * -description & & styled_widget & m & - * Widget which shows a theme item description. $ - * - * @end{table} - */ - REGISTER_DIALOG(synched_choice_wait) synched_choice_wait::synched_choice_wait(user_choice_manager& mgr) diff --git a/src/gui/dialogs/screenshot_notification.cpp b/src/gui/dialogs/screenshot_notification.cpp index c99cd73b8c25..d198c6b76a1e 100644 --- a/src/gui/dialogs/screenshot_notification.cpp +++ b/src/gui/dialogs/screenshot_notification.cpp @@ -39,35 +39,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_screenshot_notification - * - * == Screenshot notification == - * - * Notification dialog used after saving a game or map screenshot to display - * information about it for the user. - * - * @begin{table}{dialog_widgets} - * - * path & & text_box & m & - * Read-only textbox containing the screenshot path. $ - * - * filesize & & label & o & - * Optional label to display the file size. $ - * - * copy & & button & m & - * Button to copy the path to clipboard. $ - * - * open & & button & m & - * Button to open the screnshot using the default application. $ - * - * browse_dir & & button & m & - * Button to browse the screenshots directory in the file manager. $ - * - * @end{table} - */ - REGISTER_DIALOG(screenshot_notification) screenshot_notification::screenshot_notification(const std::string& path, surface screenshot) diff --git a/src/gui/dialogs/screenshot_notification.hpp b/src/gui/dialogs/screenshot_notification.hpp index c865666c1268..ab70feaa74c2 100644 --- a/src/gui/dialogs/screenshot_notification.hpp +++ b/src/gui/dialogs/screenshot_notification.hpp @@ -22,6 +22,18 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Notification dialog used after saving a game or map screenshot to display information about it for the user. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * path | text_box |yes |Read-only textbox containing the screenshot path. + * filesize | @ref label |no |Optional label to display the file size. + * copy | @ref button |yes |Button to copy the path to clipboard. + * open | @ref button |yes |Button to open the screnshot using the default application. + * browse_dir | @ref button |yes |Button to browse the screenshots directory in the file manager. + */ class screenshot_notification : public modal_dialog { public: diff --git a/src/gui/dialogs/simple_item_selector.cpp b/src/gui/dialogs/simple_item_selector.cpp index 0dd9aed4171c..67f9c574e68f 100644 --- a/src/gui/dialogs/simple_item_selector.cpp +++ b/src/gui/dialogs/simple_item_selector.cpp @@ -28,37 +28,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_simple_item_selector - * - * == Simple item selector == - * - * A simple one-column listbox with OK and Cancel buttons. - * - * @begin{table}{dialog_widgets} - * - * title & & label & m & - * Dialog title label. $ - * - * message & & styled_widget & m & - * Text label displaying a description or instructions. $ - * - * listbox & & listbox & m & - * Listbox displaying user choices. $ - * - * -item & & styled_widget & m & - * Widget which shows a listbox item label. $ - * - * ok & & button & m & - * OK button. $ - * - * cancel & & button & m & - * Cancel button. $ - * - * @end{table} - */ - REGISTER_DIALOG(simple_item_selector) simple_item_selector::simple_item_selector(const std::string& title, diff --git a/src/gui/dialogs/simple_item_selector.hpp b/src/gui/dialogs/simple_item_selector.hpp index 10f2e33c1b60..6781f999216b 100644 --- a/src/gui/dialogs/simple_item_selector.hpp +++ b/src/gui/dialogs/simple_item_selector.hpp @@ -23,6 +23,19 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * A simple one-column listbox with OK and Cancel buttons. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * title | @ref label |yes |Dialog title label. + * message | control |yes |Text label displaying a description or instructions. + * listbox | @ref listbox |yes |Listbox displaying user choices. + * item | control |yes |Widget which shows a listbox item label. + * ok | @ref button |yes |OK button. + * cancel | @ref button |yes |Cancel button. + */ class simple_item_selector : public modal_dialog { public: diff --git a/src/gui/dialogs/surrender_quit.cpp b/src/gui/dialogs/surrender_quit.cpp index 5e6acc639fd0..5ebe23d60efb 100644 --- a/src/gui/dialogs/surrender_quit.cpp +++ b/src/gui/dialogs/surrender_quit.cpp @@ -21,16 +21,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_surrender_quit - * - * == Surrender and/or quit a game == - * - * This shows the dialog to confirm surrender and/or quitting the game - * - */ - REGISTER_DIALOG(surrender_quit) diff --git a/src/gui/dialogs/surrender_quit.hpp b/src/gui/dialogs/surrender_quit.hpp index 96401d3666ed..2d3825320bc9 100644 --- a/src/gui/dialogs/surrender_quit.hpp +++ b/src/gui/dialogs/surrender_quit.hpp @@ -21,6 +21,11 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog to confirm surrender and/or quitting the game. + */ class surrender_quit : public modal_dialog { public: diff --git a/src/gui/dialogs/theme_list.cpp b/src/gui/dialogs/theme_list.cpp index 3452d016117b..60eb9e953ece 100644 --- a/src/gui/dialogs/theme_list.cpp +++ b/src/gui/dialogs/theme_list.cpp @@ -25,28 +25,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_theme_list - * - * == Theme list == - * - * Dialog for selecting a GUI theme. - * - * @begin{table}{dialog_widgets} - * - * themes & & listbox & m & - * Listbox displaying user choices. $ - * - * -name & & styled_widget & m & - * Widget which shows a theme item name. $ - * - * -description & & styled_widget & m & - * Widget which shows a theme item description. $ - * - * @end{table} - */ - REGISTER_DIALOG(theme_list) theme_list::theme_list(const std::vector& themes, int selection) diff --git a/src/gui/dialogs/theme_list.hpp b/src/gui/dialogs/theme_list.hpp index bfc8ff6de118..619a9bd13f5f 100644 --- a/src/gui/dialogs/theme_list.hpp +++ b/src/gui/dialogs/theme_list.hpp @@ -23,6 +23,16 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * Dialog for selecting a GUI theme. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * themes | @ref listbox |yes |Listbox displaying user choices. + * name | control |yes |Widget which shows a theme item name. + * description | control |yes |Widget which shows a theme item description. + */ class theme_list : public modal_dialog { public: diff --git a/src/gui/dialogs/title_screen.cpp b/src/gui/dialogs/title_screen.cpp index 4ac692529990..1b4ed06898b6 100644 --- a/src/gui/dialogs/title_screen.cpp +++ b/src/gui/dialogs/title_screen.cpp @@ -67,70 +67,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_title_screen - * - * == Title screen == - * - * This shows the title screen. - * - * @begin{table}{dialog_widgets} - * tutorial & & button & o & - * The button to start the tutorial. $ - * - * campaign & & button & o & - * The button to start a campaign. $ - * - * multiplayer & & button & o & - * The button to start multiplayer mode. $ - * - * load & & button & o & - * The button to load a saved game. $ - * - * editor & & button & o & - * The button to start the editor. $ - * - * addons & & button & o & - * The button to start managing the addons. $ - * - * language & & button & o & - * The button to select the game language. $ - * - * credits & & button & o & - * The button to show Wesnoth's contributors. $ - * - * quit & & button & m & - * The button to quit Wesnoth. $ - * - * tips & & multi_page & o & - * A multi_page to hold all tips, when this widget is used the area of - * the tips doesn't need to be resized when the next or previous button - * is pressed. $ - * - * -tip & & label & o & - * Shows the text of the current tip. $ - * - * -source & & label & o & - * The source (the one who's quoted or the book referenced) of the - * current tip. $ - * - * next_tip & & button & o & - * The button show the next tip of the day. $ - * - * previous_tip & & button & o & - * The button show the previous tip of the day. $ - * - * logo & & image & o & - * The Wesnoth logo. $ - * - * revision_number & & styled_widget & o & - * A widget to show the version number when the version number is - * known. $ - * - * @end{table} - */ - REGISTER_DIALOG(title_screen) bool show_debug_clock_button = false; diff --git a/src/gui/dialogs/title_screen.hpp b/src/gui/dialogs/title_screen.hpp index 6592e974ce09..9f3d30bf700f 100644 --- a/src/gui/dialogs/title_screen.hpp +++ b/src/gui/dialogs/title_screen.hpp @@ -29,10 +29,32 @@ class modeless_dialog; extern bool show_debug_clock_button; /** + * @ingroup GUIWindowDefinitionWML + * * This class implements the title screen. * * The menu buttons return a result back to the caller with the button pressed. * So at the moment it only handles the tips itself. + * + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * tutorial | @ref button |yes |The button to start the tutorial. + * campaign | @ref button |yes |The button to start a campaign. + * multiplayer | @ref button |yes |The button to start multiplayer mode. + * load | @ref button |yes |The button to load a saved game. + * editor | @ref button |yes |The button to start the editor. + * addons | @ref button |yes |The button to start managing the addons. + * cores | @ref button |yes |The button to start managing the cores. + * language | @ref button |yes |The button to select the game language. + * credits | @ref button |yes |The button to show Wesnoth's contributors. + * quit | @ref button |yes |The button to quit Wesnoth. + * tips | multi_page |yes |A multi_page to hold all tips, when this widget is used the area of the tips doesn't need to be resized when the next or previous button is pressed. + * tip | @ref label |no |Shows the text of the current tip. + * source | @ref label |no |The source (the one who's quoted or the book referenced) of the current tip. + * next_tip | @ref button |yes |The button show the next tip of the day. + * previous_tip | @ref button |yes |The button show the previous tip of the day. + * logo | progress_bar |no |A progress bar to "animate" the Wesnoth logo. + * revision_number | control |no |A widget to show the version number when the version number is known. */ class title_screen : public modal_dialog { diff --git a/src/gui/dialogs/tooltip.cpp b/src/gui/dialogs/tooltip.cpp index 4797126629fd..16a145b24006 100644 --- a/src/gui/dialogs/tooltip.cpp +++ b/src/gui/dialogs/tooltip.cpp @@ -31,42 +31,29 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_tip - * - * == Tip float == - * - * Generic window to show a floating tip window. The class has several - * subclasses using the same format. For example there will be tooltips and - * helptips, both using this class. - * - * @begin{table}{dialog_widgets} - * - * label & & styled_widget & m & - * This text contains the message to show in the tip. $ - * - * @end{table} - * - * In the canvas of the windows used in this dialog the following variables are - * defined: - * - * @begin{table}{formula} - * mouse_x & unsigned & The x coordinate of the mouse pointer when - * the window was created. $ - * mouse_y & unsigned & The y coordinate of the mouse pointer when - * the window was created. $ - * @end{table} - */ - REGISTER_WINDOW(tooltip_large) /** + * @ingroup GUIWindowDefinitionWML + * * Class to show the tips. * * At the moment two kinds of tips are known: * * tooltip * * helptip + * + * Generic window to show a floating tip window. + * The class has several subclasses using the same format. + * For example there will be tooltips and helptips, both using this class. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * label | control |yes |This text contains the message to show in the tip. + * + * In the canvas of the windows used in this dialog the following variables are defined: + * Variable |Type |Description + * ------------------|-----------------------------------|----------- + * mouse_x | @ref guivartype_string "unsigned" |The x coordinate of the mouse pointer when the window was created. + * mouse_y | @ref guivartype_string "unsigned" |The y coordinate of the mouse pointer when the window was created. */ class tooltip : public modeless_dialog { diff --git a/src/gui/dialogs/unit_attack.cpp b/src/gui/dialogs/unit_attack.cpp index 603aba159663..6de059dd5e0b 100644 --- a/src/gui/dialogs/unit_attack.cpp +++ b/src/gui/dialogs/unit_attack.cpp @@ -41,32 +41,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_unit_attack - * - * == Unit attack == - * - * This shows the dialog for attacking units. - * - * @begin{table}{dialog_widgets} - * $ - * attacker_icon & & image & o & Shows the icon of the attacking unit. $ - * attacker_name & & styled_widget & o & Shows the name of the attacking unit. $ - * - * defender_portrait & & image & o & Shows the portrait of the defending unit. - * $ - * defender_icon & & image & o & Shows the icon of the defending unit. $ - * defender_name & & styled_widget & o & Shows the name of the defending unit. $ - * - * - * weapon_list & & listbox & m & The list with weapons to choose from. $ - * -attacker_weapon & & styled_widget & o & The weapon for the attacker to use. $ - * -defender_weapon & & styled_widget & o & The weapon for the defender to use. $ - * - * @end{table} - */ - REGISTER_DIALOG(unit_attack) unit_attack::unit_attack(const unit_map::iterator& attacker_itor, diff --git a/src/gui/dialogs/unit_attack.hpp b/src/gui/dialogs/unit_attack.hpp index 9366e6cb90f7..e9941c6cab6f 100644 --- a/src/gui/dialogs/unit_attack.hpp +++ b/src/gui/dialogs/unit_attack.hpp @@ -23,6 +23,22 @@ namespace gui2 namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the dialog for attacking units. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * attacker_portrait | @ref image |no |Shows the portrait of the attacking unit. + * attacker_icon | @ref image |no |Shows the icon of the attacking unit. + * attacker_name | control |no |Shows the name of the attacking unit. + * defender_portrait | @ref image |no |Shows the portrait of the defending unit. + * defender_icon | @ref image |no |Shows the icon of the defending unit. + * defender_name | control |no |Shows the name of the defending unit. + * weapon_list | @ref listbox |yes |The list with weapons to choose from. + * attacker_weapon | control |no |The weapon for the attacker to use. + * defender_weapon | control |no |The weapon for the defender to use. + */ class unit_attack : public modal_dialog { public: diff --git a/src/gui/dialogs/unit_create.cpp b/src/gui/dialogs/unit_create.cpp index 118f2a2084e6..d54fb0db9f8f 100644 --- a/src/gui/dialogs/unit_create.cpp +++ b/src/gui/dialogs/unit_create.cpp @@ -46,34 +46,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_unit_create - * - * == Unit create == - * - * This shows the debug-mode dialog to create new units on the map. - * - * @begin{table}{dialog_widgets} - * - * male_toggle & & toggle_button & m & - * Option button to select the "male" gender for created units. $ - * - * female_toggle & & toggle_button & m & - * Option button to select the "female" gender for created units. $ - * - * unit_type_list & & listbox & m & - * Listbox displaying existing unit types sorted by name and race. $ - * - * -unit_type & & styled_widget & m & - * Widget which shows the unit type name label. $ - * - * -race & & styled_widget & m & - * Widget which shows the unit race name label. $ - * - * @end{table} - */ - REGISTER_DIALOG(unit_create) unit_create::unit_create() diff --git a/src/gui/dialogs/unit_create.hpp b/src/gui/dialogs/unit_create.hpp index d5bb4e9e9c5c..d82704544979 100644 --- a/src/gui/dialogs/unit_create.hpp +++ b/src/gui/dialogs/unit_create.hpp @@ -33,6 +33,18 @@ class text_box_base; namespace dialogs { +/** + * @ingroup GUIWindowDefinitionWML + * + * This shows the debug-mode dialog to create new units on the map. + * Key |Type |Mandatory|Description + * ------------------|---------------|---------|----------- + * male_toggle | toggle_button |yes |Option button to select the "male" gender for created units. + * female_toggle | toggle_button |yes |Option button to select the "female" gender for created units. + * unit_type_list | @ref listbox |yes |Listbox displaying existing unit types sorted by name and race. + * unit_type | control |yes |Widget which shows the unit type name label. + * race | control |yes |Widget which shows the unit race name label. + */ class unit_create : public modal_dialog { public: diff --git a/src/gui/dialogs/wml_error.cpp b/src/gui/dialogs/wml_error.cpp index b7ad469348ac..f4ce8ee772f9 100644 --- a/src/gui/dialogs/wml_error.cpp +++ b/src/gui/dialogs/wml_error.cpp @@ -134,39 +134,6 @@ namespace gui2 namespace dialogs { -/*WIKI - * @page = GUIWindowDefinitionWML - * @order = 2_wml_error - * - * == WML error == - * - * Dialog used to report WML parser or preprocessor errors. - * - * @begin{table}{dialog_widgets} - * - * summary & & styled_widget & m & - * Label used for displaying a brief summary of the error(s). $ - * - * files & & styled_widget & m & - * Label used to display the list of affected add-ons or files, if - * applicable. It is hidden otherwise. It is recommended to place it - * after the summary label. $ - * - * post_summary & & styled_widget & m & - * Label used for displaying instructions for reporting the error. - * It is recommended to place it after the file list label. It may be - * hidden if empty. $ - * - * details & & styled_widget & m & - * Full report of the parser or preprocessor error(s) found. $ - * - * copy & & button & m & - * Button that the user can click on to copy the error report to the - * system clipboard. $ - * - * @end{table} - */ - REGISTER_DIALOG(wml_error) wml_error::wml_error(const std::string& summary, diff --git a/src/gui/dialogs/wml_error.hpp b/src/gui/dialogs/wml_error.hpp index aa682ae961ea..c0278a6e102d 100644 --- a/src/gui/dialogs/wml_error.hpp +++ b/src/gui/dialogs/wml_error.hpp @@ -21,7 +21,18 @@ namespace gui2 namespace dialogs { -/** WML preprocessor/parser error report dialog. */ +/** + * @ingroup GUIWindowDefinitionWML + * + * WML preprocessor/parser error report dialog. + * Key |Type |Mandatory|Description + * ------------------|--------------|---------|----------- + * summary | control |yes |Label used for displaying a brief summary of the error(s). + * files | control |yes |Label used to display the list of affected add-ons or files, if applicable. It is hidden otherwise. It is recommended to place it after the summary label. + * post_summary | control |yes |Label used for displaying instructions for reporting the error. It is recommended to place it after the file list label. It may be hidden if empty. + * details | control |yes |Full report of the parser or preprocessor error(s) found. + * copy | @ref button |yes |Button that the user can click on to copy the error report to the system clipboard. + */ class wml_error : public modal_dialog { public: diff --git a/src/gui/widgets/button.cpp b/src/gui/widgets/button.cpp index 94295cb92a61..96e4fb6af035 100644 --- a/src/gui/widgets/button.cpp +++ b/src/gui/widgets/button.cpp @@ -154,34 +154,6 @@ button_definition::button_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_button - * - * == Button == - * - * @macro = button_description - * - * The following states exist: - * * state_enabled, the button is enabled. - * * state_disabled, the button is disabled. - * * state_pressed, the left mouse button is down. - * * state_focused, the mouse is over the button. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="button_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="button_definition"} - * @end{parent}{name="gui/"} - */ button_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -194,44 +166,6 @@ button_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{button_description} - * - * A button is a styled_widget that can be pushed to start an action or close - * a dialog. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_button - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="button"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Button == - * - * @macro = button_description - * - * Instance of a button. When a button has a return value it sets the - * return value for the window. Normally this closes the window and returns - * this value to the caller. The return value can either be defined by the - * user or determined from the id of the button. The return value has a - * higher precedence as the one defined by the id. (Of course it's weird to - * give a button an id and then override its return value.) - * - * When the button doesn't have a standard id, but you still want to use the - * return value of that id, use return_value_id instead. This has a higher - * precedence as return_value. - * - * List with the button specific variables: - * @begin{table}{config} - * return_value_id & string & "" & The return value id. $ - * return_value & int & 0 & The return value. $ - * - * @end{table} - * @end{tag}{name="button"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/drawing.cpp b/src/gui/widgets/drawing.cpp index 36702c7ebe84..e85fe5921c3c 100644 --- a/src/gui/widgets/drawing.cpp +++ b/src/gui/widgets/drawing.cpp @@ -91,30 +91,6 @@ drawing_definition::drawing_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_drawing - * - * == Drawing == - * - * @macro = drawing_description - * - * The definition of a drawing. The widget normally has no event interaction - * so only one state is defined. - * - * The following states exist: - * * state_enabled - * the drawing is enabled. The state is a dummy since the - * things really drawn are placed in the window instance. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="drawing_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="drawing_definition"} - * @end{parent}{name="gui/"} - */ drawing_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -129,40 +105,6 @@ drawing_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{drawing_description} - * - * A drawing is widget with a fixed size and gives access to the - * canvas of the widget in the window instance. This allows special - * display only widgets. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_drawing - * - * == Spacer == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="drawing"}{min=0}{max=-1}{super="generic/widget_instance"} - * @macro = drawing_description - * - * If either the width or the height is not zero the drawing functions as a - * fixed size drawing. - * - * @begin{table}{config} - * width & f_unsigned & 0 & The width of the drawing. $ - * height & f_unsigned & 0 & The height of the drawing. $ - * draw & config & & The config containing the drawing. $ - * @end{table} - * @allow{link}{name="generic/state/draw"} - * @end{tag}{name="drawing"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - * The variable available are the same as for the window resolution see - * https://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of - * items. - */ - namespace implementation { diff --git a/src/gui/widgets/drawing.hpp b/src/gui/widgets/drawing.hpp index 5e728c09df0b..1903417dfe56 100644 --- a/src/gui/widgets/drawing.hpp +++ b/src/gui/widgets/drawing.hpp @@ -30,10 +30,23 @@ namespace implementation // ------------ WIDGET -----------{ /** - * A widget to draw upon. - * - * This widget has a fixed size like the spacer, but allows the user to - * manual draw items. The widget is display only. + * @ingroup GUIWidgetWML + * + * A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. + * It has a fixed size like the spacer, but allows the user to manually draw items. + * This widget is display only. + * + * The widget normally has no event interaction so only one state is defined: + * * state_enabled - the drawing is enabled. The state is a dummy since the things really drawn are placed in the window instance. + * + * If either the width or the height is not zero the drawing functions as a fixed size drawing. + * Key |Type |Default |Description + * -------------|----------------------------------------|---------|----------- + * width | @ref guivartype_f_unsigned "f_unsigned"|0 |The width of the drawing. + * height | @ref guivartype_f_unsigned "f_unsigned"|0 |The height of the drawing. + * draw | @ref guivartype_config "config" |mandatory|The config containing the drawing. + * + * The variables available are the same as for the window resolution see @ref builder_window::window_resolution for the list of items. */ class drawing : public styled_widget { diff --git a/src/gui/widgets/grid.cpp b/src/gui/widgets/grid.cpp index bee05a96464b..1971be840f3e 100644 --- a/src/gui/widgets/grid.cpp +++ b/src/gui/widgets/grid.cpp @@ -1115,210 +1115,3 @@ void set_single_child(grid& grid, widget* widget) } } // namespace gui2 - - -/*WIKI - * @page = GUILayout - * - * {{Autogenerated}} - * - * = Abstract = - * - * In the widget library the placement and sizes of elements is determined by - * a grid. Therefore most widgets have no fixed size. - * - * - * = Theory = - * - * We have two examples for the addon dialog, the first example the lower - * buttons are in one grid, that means if the remove button gets wider - * (due to translations) the connect button (4.1 - 2.2) will be aligned - * to the left of the remove button. In the second example the connect - * button will be partial underneath the remove button. - * - * A grid exists of x rows and y columns for all rows the number of columns - * needs to be the same, there is no column (nor row) span. If spanning is - * required place a nested grid to do so. In the examples every row has 1 column - * but rows 3, 4 (and in the second 5) have a nested grid to add more elements - * per row. - * - * In the grid every cell needs to have a widget, if no widget is wanted place - * the special widget ''spacer''. This is a non-visible item which normally - * shouldn't have a size. It is possible to give a spacer a size as well but - * that is discussed elsewhere. - * - * Every row and column has a ''grow_factor'', since all columns in a grid are - * aligned only the columns in the first row need to define their grow factor. - * The grow factor is used to determine with the extra size available in a - * dialog. The algorithm determines the extra size work like this: - * - * * determine the extra size - * * determine the sum of the grow factors - * * if this sum is 0 set the grow factor for every item to 1 and sum to sum of items. - * * divide the extra size with the sum of grow factors - * * for every item multiply the grow factor with the division value - * - * eg - * extra size 100 - * grow factors 1, 1, 2, 1 - * sum 5 - * division 100 / 5 = 20 - * extra sizes 20, 20, 40, 20 - * - * Since we force the factors to 1 if all zero it's not possible to have non - * growing cells. This can be solved by adding an extra cell with a spacer and a - * grow factor of 1. This is used for the buttons in the examples. - * - * Every cell has a ''border_size'' and ''border'' the ''border_size'' is the - * number of pixels in the cell which aren't available for the widget. This is - * used to make sure the items in different cells aren't put side to side. With - * ''border'' it can be determined which sides get the border. So a border is - * either 0 or ''border_size''. - * - * If the widget doesn't grow when there's more space available the alignment - * determines where in the cell the widget is placed. - * - * == Examples == - * - * |---------------------------------------| - * | 1.1 | - * |---------------------------------------| - * | 2.1 | - * |---------------------------------------| - * | |-----------------------------------| | - * | | 3.1 - 1.1 | 3.1 - 1.2 | | - * | |-----------------------------------| | - * |---------------------------------------| - * | |-----------------------------------| | - * | | 4.1 - 1.1 | 4.1 - 1.2 | 4.1 - 1.3 | | - * | |-----------------------------------| | - * | | 4.1 - 2.1 | 4.1 - 2.2 | 4.1 - 2.3 | | - * | |-----------------------------------| | - * |---------------------------------------| - * - * - * 1.1 label : title - * 2.1 label : description - * 3.1 - 1.1 label : server - * 3.1 - 1.2 text box : server to connect to - * 4.1 - 1.1 spacer - * 4.1 - 1.2 spacer - * 4.1 - 1.3 button : remove addon - * 4.1 - 2.1 spacer - * 4.1 - 2.2 button : connect - * 4.1 - 2.3 button : cancel - * - * - * |---------------------------------------| - * | 1.1 | - * |---------------------------------------| - * | 2.1 | - * |---------------------------------------| - * | |-----------------------------------| | - * | | 3.1 - 1.1 | 3.1 - 1.2 | | - * | |-----------------------------------| | - * |---------------------------------------| - * | |-----------------------------------| | - * | | 4.1 - 1.1 | 4.1 - 1.2 | | - * | |-----------------------------------| | - * |---------------------------------------| - * | |-----------------------------------| | - * | | 5.1 - 1.1 | 5.1 - 1.2 | 5.1 - 2.3 | | - * | |-----------------------------------| | - * |---------------------------------------| - * - * - * 1.1 label : title - * 2.1 label : description - * 3.1 - 1.1 label : server - * 3.1 - 1.2 text box : server to connect to - * 4.1 - 1.1 spacer - * 4.1 - 1.2 button : remove addon - * 5.1 - 1.1 spacer - * 5.1 - 1.2 button : connect - * 5.1 - 1.3 button : cancel - * - * = Praxis = - * - * This is the code needed to create the skeleton for the structure the extra - * flags are omitted. - * - * [grid] - * [row] - * [column] - * [label] - * # 1.1 - * [/label] - * [/column] - * [/row] - * [row] - * [column] - * [label] - * # 2.1 - * [/label] - * [/column] - * [/row] - * [row] - * [column] - * [grid] - * [row] - * [column] - * [label] - * # 3.1 - 1.1 - * [/label] - * [/column] - * [column] - * [text_box] - * # 3.1 - 1.2 - * [/text_box] - * [/column] - * [/row] - * [/grid] - * [/column] - * [/row] - * [row] - * [column] - * [grid] - * [row] - * [column] - * [spacer] - * # 4.1 - 1.1 - * [/spacer] - * [/column] - * [column] - * [spacer] - * # 4.1 - 1.2 - * [/spacer] - * [/column] - * [column] - * [button] - * # 4.1 - 1.3 - * [/button] - * [/column] - * [/row] - * [row] - * [column] - * [spacer] - * # 4.1 - 2.1 - * [/spacer] - * [/column] - * [column] - * [button] - * # 4.1 - 2.2 - * [/button] - * [/column] - * [column] - * [button] - * # 4.1 - 2.3 - * [/button] - * [/column] - * [/row] - * [/grid] - * [/column] - * [/row] - * [/grid] - * - * - * [[Category: WML Reference]] - * [[Category: GUI WML Reference]] - */ diff --git a/src/gui/widgets/helper.hpp b/src/gui/widgets/helper.hpp index 5ce1d3fa0b48..f78444d24908 100644 --- a/src/gui/widgets/helper.hpp +++ b/src/gui/widgets/helper.hpp @@ -46,9 +46,7 @@ SDL_Rect create_rect(const point& origin, const point& size); /** * Converts a color string to a color. * - * @param color A color string see - * https://www.wesnoth.org/wiki/GUIVariable for - * more info. + * @param color A color string see @ref GUIWidgetWML for more info. * * @returns The color. */ @@ -57,9 +55,7 @@ color_t decode_color(const std::string& color); /** * Converts a text alignment string to a text alignment. * - * @param alignment An alignment string see - * https://www.wesnoth.org/wiki/GUIVariable for - * more info. + * @param alignment An alignment string see @ref GUIWidgetWML for more info. * * @returns The text alignment. */ @@ -70,18 +66,14 @@ PangoAlignment decode_text_alignment(const std::string& alignment); * * @param alignment An alignment. * - * @returns An alignment string see - * https://www.wesnoth.org/wiki/GUIVariable for - * more info. + * @returns An alignment string see @ref GUIWidgetWML for more info. */ std::string encode_text_alignment(const PangoAlignment alignment); /** * Converts a font style string to a font style. * - * @param style A font style string see - * https://www.wesnoth.org/wiki/GUIVariable for - * more info. + * @param style A font style string see @ref GUIWidgetWML for more info. * * @returns The font style. */ diff --git a/src/gui/widgets/horizontal_scrollbar.cpp b/src/gui/widgets/horizontal_scrollbar.cpp index bc7700ca7144..d9cad248495b 100644 --- a/src/gui/widgets/horizontal_scrollbar.cpp +++ b/src/gui/widgets/horizontal_scrollbar.cpp @@ -115,54 +115,6 @@ horizontal_scrollbar_definition::horizontal_scrollbar_definition( load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_vertical_scrollbar - * - * == Horizontal scrollbar == - * - * @macro = horizontal_scrollbar_description - * @begin{parent}{name="gui/"} - * @begin{tag}{name="horizontal_scrollbar_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * The resolution for a horizontal scrollbar also contains the following keys: - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{table}{config} - * minimum_positioner_length & unsigned & & - * The minimum size the positioner is - * allowed to be. The engine needs to know - * this in order to calculate the best size - * for the positioner. $ - * maximum_positioner_length & unsigned & 0 & - * The maximum size the positioner is - * allowed to be. If minimum and maximum are - * the same value the positioner is fixed - * size. If the maximum is 0 (and the - * minimum not) there's no maximum. $ - * left_offset & unsigned & 0 & The number of pixels at the left which - * can't be used by the positioner. $ - * right_offset & unsigned & 0 & The number of pixels at the right which - * can't be used by the positioner. $ - * @end{table} - * - * The following states exist: - * * state_enabled, the horizontal scrollbar is enabled. - * * state_disabled, the horizontal scrollbar is disabled. - * * state_pressed, the left mouse button is down on the positioner of the - * horizontal scrollbar. - * * state_focused, the mouse is over the positioner of the horizontal - * scrollbar. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="horizontal_scrollbar_definition"} - * @end{parent}{name="gui/"} - */ horizontal_scrollbar_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , minimum_positioner_length(cfg["minimum_positioner_length"]) @@ -183,29 +135,6 @@ horizontal_scrollbar_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{horizontal_scrollbar_description} - * - * A horizontal scrollbar is a widget that shows a horizontal scrollbar. - * This widget is most of the time used in a container to control the - * scrolling of its contents. - * @end{macro} - */ - -/*WIKI - * @page = GUIToolkitWML - * @order = 2_horizontal_scrollbar - * - * == Horizontal scrollbar == - * - * @macro = horizontal_scrollbar_description - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="horizontal_scrollbar"}{min=0}{max=-1}{super="generic/widget_instance"} - * @end{tag}{name="horizontal_scrollbar"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - * A horizontal scrollbar has no special fields. - */ - namespace implementation { diff --git a/src/gui/widgets/horizontal_scrollbar.hpp b/src/gui/widgets/horizontal_scrollbar.hpp index 3723faa1d3c3..bde93f6daca3 100644 --- a/src/gui/widgets/horizontal_scrollbar.hpp +++ b/src/gui/widgets/horizontal_scrollbar.hpp @@ -28,7 +28,25 @@ struct builder_horizontal_scrollbar; // ------------ WIDGET -----------{ -/** A horizontal scrollbar. */ +/** + * @ingroup GUIWidgetWML + * + * A horizontal scrollbar is a widget that shows a horizontal scrollbar. + * This widget is most of the time used in a container to control the scrolling of its contents. + * + * The resolution for a horizontal scrollbar also contains the following keys: + * Key |Type |Default |Description + * -------------------------|------------------------------------|---------|------------- + * minimum_positioner_length| @ref guivartype_unsigned "unsigned"|mandatory|The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner. + * maximum_positioner_length| @ref guivartype_unsigned "unsigned"|0 |The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum. + * left_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the left which can't be used by the positioner. + * right_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the right which can't be used by the positioner. + * The following states exist: + * * state_enabled - the horizontal scrollbar is enabled. + * * state_disabled - the horizontal scrollbar is disabled. + * * state_pressed - the left mouse button is down on the positioner of the horizontal scrollbar. + * * state_focussed - the mouse is over the positioner of the horizontal scrollbar. + */ class horizontal_scrollbar : public scrollbar_base { friend struct implementation::builder_horizontal_scrollbar; diff --git a/src/gui/widgets/image.cpp b/src/gui/widgets/image.cpp index 6b552d186e94..88bfc85cba1d 100644 --- a/src/gui/widgets/image.cpp +++ b/src/gui/widgets/image.cpp @@ -105,29 +105,6 @@ image_definition::image_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_image - * - * == Image == - * - * @macro = image_description - * - * The definition of an image. The label field of the widget is used as the - * name of file to show. The widget normally has no event interaction so only - * one state is defined. - * - * The following states exist: - * * state_enabled, the image is enabled. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="image_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="image_definition"} - * @end{parent}{name="gui/"} - */ image_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -137,27 +114,6 @@ image_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{image_description} - * An image shows a static image. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_image - * - * == Image == - * - * @macro = image_description - * - * An image has no extra fields. - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="image"}{min=0}{max=-1}{super="generic/widget_instance"} - * @end{tag}{name="image"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/image.hpp b/src/gui/widgets/image.hpp index 5a9a4c776ad2..e653a8ec7038 100644 --- a/src/gui/widgets/image.hpp +++ b/src/gui/widgets/image.hpp @@ -28,7 +28,14 @@ namespace implementation // ------------ WIDGET -----------{ -/** An image. */ +/** + * @ingroup GUIWidgetWML + * + * An image shows a static image. + * + * The label field of the widget is used as the name of file to show. The widget normally has no event interaction so only one state is defined: + * * state_enabled - the image is enabled. + */ class image : public styled_widget { public: diff --git a/src/gui/widgets/label.cpp b/src/gui/widgets/label.cpp index 98f6698884f8..7f196b2c7e66 100644 --- a/src/gui/widgets/label.cpp +++ b/src/gui/widgets/label.cpp @@ -231,44 +231,6 @@ label_definition::label_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_label - * - * == Label == - * - * @macro = label_description - * - * Although the label itself has no event interaction it still has two states. - * The reason is that labels are often used as visual indication of the state - * of the widget it labels. - * - * Note: The above is outdated, if "link_aware" is enabled then there is interaction. - * - * - * The following states exist: - * * state_enabled, the label is enabled. - * * state_disabled, the label is disabled. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="label_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{table}{config} - * link_aware & f_bool & false & Whether the label is link aware. This means - * it is rendered with links highlighted, - * and responds to click events on those - * links. $ - * link_color & string & #ffff00 & The color to render links with. This - * string will be used verbatim in pango - * markup for each link. $ - * @end{table} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="label_definition"} - * @end{parent}{name="gui/"} - */ label_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , link_color(cfg["link_color"].empty() ? color_t::from_hex_string("ffff00") : color_t::from_rgba_string(cfg["link_color"].str())) @@ -280,43 +242,6 @@ label_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{label_description} - * - * A label displays a text, the text can be wrapped but no scrollbars - * are provided. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_label - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="label"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Label == - * - * @macro = label_description - * - * List with the label specific variables: - * @begin{table}{config} - * wrap & bool & false & Is wrapping enabled for the label. $ - * characters_per_line & unsigned & 0 & - * Sets the maximum number of characters per - * line. The amount is an approximate since the - * width of a character differs. E.g. iii is - * smaller than MMM. When the value is non-zero - * it also implies can_wrap is true. - * When having long strings wrapping them can - * increase readability, often 66 characters per - * line is considered the optimum for a one - * column text. - * text_alignment & h_align & "left" & - * How is the text aligned in the label. $ - * @end{table} - * @end{tag}{name="label"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/label.hpp b/src/gui/widgets/label.hpp index df2ab93194f3..a59b1dc005bd 100644 --- a/src/gui/widgets/label.hpp +++ b/src/gui/widgets/label.hpp @@ -28,7 +28,31 @@ namespace implementation // ------------ WIDGET -----------{ -/** Label showing a text. */ +/** + * @ingroup GUIWidgetWML + * + * A label displays a text, the text can be wrapped but no scrollbars are provided. + * + * Although the label itself has no event interaction it still has two states. + * The reason is that labels are often used as visual indication of the state of the widget it labels. + * + * Note: The above is outdated, if "link_aware" is enabled then there is interaction. + * + * The following states exist: + * * state_enabled - the label is enabled. + * * state_disabled - the label is disabled. + * + * Key |Type |Default |Description + * -------------------|------------------------------------|--------|------------- + * link_aware | @ref guivartype_f_bool "f_bool" |false |Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links. + * link_color | @ref guivartype_string "string" |\#ffff00|The color to render links with. This string will be used verbatim in pango markup for each link. + * + * The label specific variables: + * Key |Type |Default|Description + * -------------------|------------------------------------|-------|------------- + * wrap | @ref guivartype_bool "bool" |false |Is wrapping enabled for the label. + * characters_per_line| @ref guivartype_unsigned "unsigned"|0 |Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. + */ class label : public styled_widget { friend struct implementation::builder_label; diff --git a/src/gui/widgets/listbox.cpp b/src/gui/widgets/listbox.cpp index 9594657098bb..7900b2f81c4d 100644 --- a/src/gui/widgets/listbox.cpp +++ b/src/gui/widgets/listbox.cpp @@ -719,85 +719,6 @@ listbox_definition::listbox_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_listbox - * @begin{parent}{name="gui/"} - * @begin{tag}{name="listbox_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * == Listbox == - * - * @macro = listbox_description - * - * The definition of a listbox contains the definition of its scrollbar. - * - * The resolution for a listbox also contains the following keys: - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super=generic/widget_definition/resolution} - * @begin{table}{config} - * scrollbar & section & & A grid containing the widgets for the - * scrollbar. The scrollbar has some special - * widgets so it can make default behavior - * for certain widgets. $ - * @end{table} - * @begin{table}{dialog_widgets} - * _begin & & clickable & o & Moves the position to the beginning - * of the list. $ - * _line_up & & clickable & o & Move the position one item up. (NOTE - * if too many items to move per item it - * might be more items.) $ - * _half_page_up & & clickable & o & - * Move the position half the number of the - * visible items up. (See note at - * _line_up.) $ - * _page_up & & clickable & o & Move the position the number of - * visible items up. (See note at - * _line_up.) $ - * - * _end & & clickable & o & Moves the position to the end of the - * list. $ - * _line_down & & clickable & o & Move the position one item down.(See - * note at _line_up.) $ - * _half_page_down & & clickable & o & - * Move the position half the number of the - * visible items down. (See note at - * _line_up.) $ - * _page_down & & clickable & o & Move the position the number of - * visible items down. (See note at - * _line_up.) $ - * - * _scrollbar & & vertical_scrollbar & m & - * This is the scrollbar so the user can - * scroll through the list. $ - * @end{table} - * A clickable is one of: - * * button - * * repeating_button - * @{allow}{link}{name="gui/window/resolution/grid/row/column/button"} - * @{allow}{link}{name="gui/window/resolution/grid/row/column/repeating_button"} - * The following states exist: - * * state_enabled, the listbox is enabled. - * * state_disabled, the listbox is disabled. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @allow{link}{name="gui/window/resolution/grid"} - * @end{tag}{name="resolution"} - * @end{tag}{name="listbox_definition"} - * @end{parent}{name="gui/"} - */ - -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_horizonal_listbox - * - * == Horizontal listbox == - * @begin{parent}{name="gui/"} - * @begin{tag}{name="horizontal_listbox_definition"}{min=0}{max=-1}{super="gui/listbox_definition"} - * @end{tag}{name="horizontal_listbox_definition"} - * @end{parent}{name="gui/"} - * @macro = horizontal_listbox_description - * The definition of a horizontal listbox is the same as for a normal listbox. - */ listbox_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , grid(nullptr) @@ -812,101 +733,6 @@ listbox_definition::resolution::resolution(const config& cfg) grid = std::make_shared(child); } -// }---------- BUILDER -----------{ - -/*WIKI_MACRO - * @begin{macro}{listbox_description} - * - * A listbox is a styled_widget that holds several items of the same type. - * Normally the items in a listbox are ordered in rows, this version - * might allow more options for ordering the items in the future. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_listbox - * - * == Listbox == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="listbox"}{min=0}{max=-1}{super="generic/widget_instance"} - * @macro = listbox_description - * - * List with the listbox specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * - * header & grid & [] & Defines the grid for the optional - * header. (This grid will automatically - * get the id _header_grid.) $ - * footer & grid & [] & Defines the grid for the optional - * footer. (This grid will automatically - * get the id _footer_grid.) $ - * - * list_definition & section & & This defines how a listbox item - * looks. It must contain the grid - * definition for 1 row of the list. $ - * - * list_data & section & [] & A grid alike section which stores the - * initial data for the listbox. Every row - * must have the same number of columns as - * the 'list_definition'. $ - * - * has_minimum & bool & true & If false, less than one row can be selected. $ - * - * has_maximum & bool & true & If false, more than one row can be selected. $ - * - * @end{table} - * @begin{tag}{name="header"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="header"} - * @begin{tag}{name="footer"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="footer"} - * @begin{tag}{name="list_definition"}{min=0}{max=1} - * @begin{tag}{name="row"}{min=1}{max=1}{super="generic/listbox_grid/row"} - * @end{tag}{name="row"} - * @end{tag}{name="list_definition"}x - * @begin{tag}{name="list_data"}{min=0}{max=1}{super="generic/listbox_grid"} - * @end{tag}{name="list_data"} - * - * In order to force widgets to be the same size inside a listbox, the widgets - * need to be inside a linked_group. - * - * Inside the list section there are only the following widgets allowed - * * grid (to nest) - * * selectable widgets which are - * ** toggle_button - * ** toggle_panel - * @end{tag}{name="listbox"} - * - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - -/*WIKI - * @begin{parent}{name="generic/"} - * @begin{tag}{name="listbox_grid"}{min="0"}{max="-1"} - * @begin{tag}{name="row"}{min="0"}{max="-1"} - * @begin{table}{config} - * grow_factor & unsigned & 0 & The grow factor for a row. $ - * @end{table} - * @begin{tag}{name="column"}{min="0"}{max="-1"}{super="gui/window/resolution/grid/row/column"} - * @begin{table}{config} - * label & t_string & "" & $ - * tooltip & t_string & "" & $ - * icon & t_string & "" & $ - * @end{table} - * @allow{link}{name="gui/window/resolution/grid/row/column/toggle_button"} - * @allow{link}{name="gui/window/resolution/grid/row/column/toggle_panel"} - * @end{tag}{name="column"} - * @end{tag}{name="row"} - * @end{tag}{name="listbox_grid"} - * @end{parent}{name="generic/"} - */ - namespace implementation { static std::vector> parse_list_data(const config& data, const unsigned int req_cols) @@ -992,69 +818,6 @@ widget* builder_listbox::build() const return widget; } -/*WIKI_MACRO - * @begin{macro}{horizontal_listbox_description} - * - * A horizontal listbox is a styled_widget that holds several items of the - * same type. Normally the items in a listbox are ordered in rows, - * this version orders them in columns instead. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_horizontal_listbox - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="horizontal_listbox"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * == Horizontal listbox == - * - * @macro = horizontal_listbox_description - * - * List with the horizontal listbox specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * - * list_definition & section & & This defines how a listbox item - * looks. It must contain the grid - * definition for 1 column of the list. $ - * - * list_data & section & [] & A grid alike section which stores the - * initial data for the listbox. Every row - * must have the same number of columns as - * the 'list_definition'. $ - * - * has_minimum & bool & true & If false, less than one row can be selected. $ - * - * has_maximum & bool & true & If false, more than one row can be selected. $ - * - * @end{table} - * @begin{tag}{name="header"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="header"} - * @begin{tag}{name="footer"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="footer"} - * @begin{tag}{name="list_definition"}{min=0}{max=1} - * @begin{tag}{name="row"}{min=1}{max=1}{super="generic/listbox_grid/row"} - * @end{tag}{name="row"} - * @end{tag}{name="list_definition"} - * @begin{tag}{name="list_data"}{min=0}{max=1}{super="generic/listbox_grid"} - * @end{tag}{name="list_data"} - * In order to force widgets to be the same size inside a horizontal listbox, - * the widgets need to be inside a linked_group. - * - * Inside the list section there are only the following widgets allowed - * * grid (to nest) - * * selectable widgets which are - * ** toggle_button - * ** toggle_panel - * @end{tag}{name="horizontal_listbox"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - builder_horizontal_listbox::builder_horizontal_listbox(const config& cfg) : builder_styled_widget(cfg) , vertical_scrollbar_mode(get_scrollbar_mode(cfg["vertical_scrollbar_mode"])) @@ -1097,69 +860,6 @@ widget* builder_horizontal_listbox::build() const return widget; } -/*WIKI_MACRO - * @begin{macro}{grid_listbox_description} - * - * A grid listbox is a styled_widget that holds several items of the - * same type. Normally the items in a listbox are ordered in rows, - * this version orders them in a grid instead. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_grid_listbox - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="grid_listbox"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * == Horizontal listbox == - * - * @macro = grid_listbox_description - * - * List with the grid listbox specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * - * list_definition & section & & This defines how a listbox item - * looks. It must contain the grid - * definition for 1 column of the list. $ - * - * list_data & section & [] & A grid alike section which stores the - * initial data for the listbox. Every row - * must have the same number of columns as - * the 'list_definition'. $ - * - * has_minimum & bool & true & If false, less than one cell can be selected. $ - * - * has_maximum & bool & true & If false, more than one cell can be selected. $ - * - * @end{table} - * @begin{tag}{name="header"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="header"} - * @begin{tag}{name="footer"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="footer"} - * @begin{tag}{name="list_definition"}{min=0}{max=1} - * @begin{tag}{name="row"}{min=1}{max=1}{super="generic/listbox_grid/row"} - * @end{tag}{name="row"} - * @end{tag}{name="list_definition"} - * @begin{tag}{name="list_data"}{min=0}{max=1}{super="generic/listbox_grid"} - * @end{tag}{name="list_data"} - * In order to force widgets to be the same size inside a grid listbox, - * the widgets need to be inside a linked_group. - * - * Inside the list section there are only the following widgets allowed - * * grid (to nest) - * * selectable widgets which are - * ** toggle_button - * ** toggle_panel - * @end{tag}{name="grid_listbox"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - builder_grid_listbox::builder_grid_listbox(const config& cfg) : builder_styled_widget(cfg) , vertical_scrollbar_mode(get_scrollbar_mode(cfg["vertical_scrollbar_mode"])) diff --git a/src/gui/widgets/listbox.hpp b/src/gui/widgets/listbox.hpp index 0a9ec84c5c27..5eea170fe0ed 100644 --- a/src/gui/widgets/listbox.hpp +++ b/src/gui/widgets/listbox.hpp @@ -442,6 +442,49 @@ struct listbox_definition : public styled_widget_definition namespace implementation { +/** + * @ingroup GUIWidgetWML + * + * A listbox is a control that holds several items of the same type. + * Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future. + * The definition of a listbox contains the definition of its scrollbar: + * Key |Type |Default |Description + * -------------------------|------------------------------------|------------|------------- + * scrollbar | @ref guivartype_section "section" |mandatory |A grid containing the widgets for the scrollbar. The scrollbar has some special widgets so it can make default behavior for certain widgets. + * The resolution for a listbox also contains the following keys: + * ID (return value) |Type |Mandatory |Description + * -------------------------|--------------------|------------|------------- + * _begin | clickable |no |Moves the position to the beginning of the list. + * _line_up | clickable |no |Move the position one item up. (NOTE: if too many items to move per item it might be more items.) + * _half_page_up | clickable |no |Move the position half the number of the visible items up. (See note at _line_up.) + * _page_up | clickable |no |Move the position the number of visible items up. (See note at _line_up.) + * _end | clickable |no |Moves the position to the end of the list. + * _line_down | clickable |no |Move the position one item down.(See note at _line_up.) + * _half_page_down | clickable |no |Move the position half the number of the visible items down. (See note at _line_up.) + * _page_down | clickable |no |Move the position the number of visible items down. (See note at _line_up.) + * _scrollbar | vertical_scrollbar |yes |This is the scrollbar so the user can scroll through the list. + * A clickable is one of: + * * button + * * repeating_button + * The following states exist: + * * state_enabled - the listbox is enabled. + * * state_disabled - the listbox is disabled. + * List with the listbox specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|------------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * header | @ref guivartype_grid "grid" |[] |Defines the grid for the optional header. (This grid will automatically get the id _header_grid.) + * footer | @ref guivartype_grid "grid" |[] |Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.) + * list_definition | @ref guivartype_section "section" |mandatory |This defines how a listbox item looks. It must contain the grid definition for 1 row of the list. + * list_data | @ref guivartype_section "section" |[] |A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'. + * has_minimum | @ref guivartype_bool "bool" |true |If false, less than one row can be selected. + * has_maximum | @ref guivartype_bool "bool" |true |If false, more than one row can be selected. + * In order to force widgets to be the same size inside a listbox, the widgets need to be inside a linked_group. Inside the list section there are only the following widgets allowed: + * * grid (to nest) + * * toggle_button + * * toggle_panel + */ struct builder_listbox : public builder_styled_widget { explicit builder_listbox(const config& cfg); @@ -469,6 +512,27 @@ struct builder_listbox : public builder_styled_widget bool has_minimum_, has_maximum_; }; +/** + * @ingroup GUIWidgetWML + * + * A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead. The definition of a horizontal listbox is the same as for a normal listbox. + * + * List with the horizontal listbox specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|------------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * list_definition | @ref guivartype_section "section" |mandatory |This defines how a listbox item looks. It must contain the grid definition for 1 column of the list. + * list_data | @ref guivartype_section "section" |[] |A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'. + * has_minimum | @ref guivartype_bool "bool" |true |If false, less than one row can be selected. + * has_maximum | @ref guivartype_bool "bool" |true |If false, more than one row can be selected. + * + * In order to force widgets to be the same size inside a horizontal listbox, the widgets need to be inside a linked_group. + * Inside the list section there are only the following widgets allowed: + * * grid (to nest) + * * toggle_button + * * toggle_panel + */ struct builder_horizontal_listbox : public builder_styled_widget { explicit builder_horizontal_listbox(const config& cfg); @@ -493,6 +557,28 @@ struct builder_horizontal_listbox : public builder_styled_widget bool has_minimum_, has_maximum_; }; +/** + * @ingroup GUIWidgetWML + * + * A grid listbox is a styled_widget that holds several items of the same type. + * Normally the items in a listbox are ordered in rows, this version orders them in a grid instead. + * + * List with the grid listbox specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|------------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * list_definition | @ref guivartype_section "section" |mandatory |This defines how a listbox item looks. It must contain the grid definition for 1 column of the list. + * list_data | @ref guivartype_section "section" |[] |A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'. + * has_minimum | @ref guivartype_bool "bool" |true |If false, less than one row can be selected. + * has_maximum | @ref guivartype_bool "bool" |true |If false, more than one row can be selected. + * + * In order to force widgets to be the same size inside a horizontal listbox, the widgets need to be inside a linked_group. + * Inside the list section there are only the following widgets allowed: + * * grid (to nest) + * * toggle_button + * * toggle_panel + */ struct builder_grid_listbox : public builder_styled_widget { explicit builder_grid_listbox(const config& cfg); diff --git a/src/gui/widgets/matrix.cpp b/src/gui/widgets/matrix.cpp index cff9bd08eb8f..c744e000b826 100644 --- a/src/gui/widgets/matrix.cpp +++ b/src/gui/widgets/matrix.cpp @@ -175,37 +175,16 @@ bool matrix::disable_click_dismiss() const return false; } +/** + * @todo Implement properly. + */ iteration::walker_base* matrix::create_walker() { - /** - * @todo Implement properly. - */ return nullptr; } // }---------- DEFINITION ---------{ -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_matrix - * @begin{parent}{name="gui/"} - * @begin{tag}{name="matrix_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * == Listbox == - * - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super=generic/widget_definition/resolution} - * - * - * @begin{tag}{name="state_enabled"}{min=1}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=1}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="content"}{min=1}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="content"} - * @end{tag}{name="resolution"} - * @end{tag}{name="matrix_definition"} - * @end{parent}{name="gui/"} - */ - matrix_definition::matrix_definition(const config& cfg) : styled_widget_definition(cfg) { @@ -225,43 +204,6 @@ matrix_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_matrix - * - * == Listbox == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="matrix"}{min=0}{max=-1}{super="generic/widget_instance"} - * - * - * List with the matrix specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * @end{table} - * - * - * @begin{tag}{name="top"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="top"} - * @begin{tag}{name="bottom"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="bottom"} - * - * @begin{tag}{name="left"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="left"} - * @begin{tag}{name="right"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="right"} - * - * @begin{tag}{name="main"}{min="1"}{max="1"}{super="gui/window/resolution/grid/row/column"} - * @end{tag}{name="main"} - * @end{tag}{name="matrix"} - * - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/matrix.hpp b/src/gui/widgets/matrix.hpp index 67e937554ae4..2954efa215ff 100644 --- a/src/gui/widgets/matrix.hpp +++ b/src/gui/widgets/matrix.hpp @@ -95,7 +95,15 @@ class control_NEW : public styled_widget, public STATE typedef control_NEW tbase; -/** The matrix class. */ +/** + * @ingroup GUIWidgetWML + * + * List with the matrix specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|----------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + */ class matrix : public tbase { friend class debug_layout_graph; diff --git a/src/gui/widgets/menu_button.cpp b/src/gui/widgets/menu_button.cpp index df47b55e9df5..4af5146bd5d8 100644 --- a/src/gui/widgets/menu_button.cpp +++ b/src/gui/widgets/menu_button.cpp @@ -224,34 +224,6 @@ menu_button_definition::menu_button_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_menu_button - * - * == menu_button == - * - * @macro = menu_button_description - * - * The following states exist: - * * state_enabled, the menu_button is enabled. - * * state_disabled, the menu_button is disabled. - * * state_pressed, the left mouse menu_button is down. - * * state_focused, the mouse is over the menu_button. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="menu_button_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="menu_button_definition"} - * @end{parent}{name="gui/"} - */ menu_button_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -264,43 +236,6 @@ menu_button_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{menu_button_description} - * - * A menu_button is a styled_widget to choose an element from a list of elements. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_menu_button - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="menu_button"}{min=0}{max=-1}{super="generic/widget_instance"} - * == menu_button == - * - * @macro = menu_button_description - * - * Instance of a menu_button. When a menu_button has a return value it sets the - * return value for the window. Normally this closes the window and returns - * this value to the caller. The return value can either be defined by the - * user or determined from the id of the menu_button. The return value has a - * higher precedence as the one defined by the id. (Of course it's weird to - * give a menu_button an id and then override its return value.) - * - * When the menu_button doesn't have a standard id, but you still want to use the - * return value of that id, use return_value_id instead. This has a higher - * precedence as return_value. - * - * List with the menu_button specific variables: - * @begin{table}{config} - * return_value_id & string & "" & The return value id. $ - * return_value & int & 0 & The return value. $ - * - * @end{table} - * @end{tag}{name="menu_button"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/menu_button.hpp b/src/gui/widgets/menu_button.hpp index 88c0f5435235..2affb1dbb3dc 100644 --- a/src/gui/widgets/menu_button.hpp +++ b/src/gui/widgets/menu_button.hpp @@ -36,7 +36,30 @@ namespace implementation // ------------ WIDGET -----------{ /** - * Simple push button. + * @ingroup GUIWidgetWML + * + * A menu_button is a styled_widget to choose an element from a list of elements. + * + * When a menu_button has a return value it sets the return value for the window. + * Normally this closes the window and returns this value to the caller. + * The return value can either be defined by the user or determined from the id of the menu_button. + * The return value has a higher precedence as the one defined by the id. + * (Of course it's weird to give a menu_button an id and then override its return value.) + * + * When the menu_button doesn't have a standard id, but you still want to use the return value of that id, use return_value_id instead. + * This has a higher precedence as return_value. + * + * List with the menu_button specific variables: + * Key |Type |Default |Description + * ---------------|------------------------------------|---------|----------- + * return_value_id| @ref guivartype_string "string" |"" |The return value id. + * return_value | @ref guivartype_int "int" |0 |The return value. + * + * The following states exist: + * * state_enabled - the menu_button is enabled. + * * state_disabled - the menu_button is disabled. + * * state_pressed - the left mouse menu_button is down. + * * state_focused - the mouse is over the menu_button. */ class menu_button : public styled_widget, public selectable_item { diff --git a/src/gui/widgets/minimap.cpp b/src/gui/widgets/minimap.cpp index 52652871a43e..072e92b65bd9 100644 --- a/src/gui/widgets/minimap.cpp +++ b/src/gui/widgets/minimap.cpp @@ -233,25 +233,6 @@ minimap_definition::minimap_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_minimap - * - * == Minimap == - * - * @macro = minimap_description - * - * The following states exist: - * * state_enabled, the minimap is enabled. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="minimap_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="minimap_definition"} - * @end{parent}{name="gui/"} - */ minimap_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -261,30 +242,6 @@ minimap_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{minimap_description} - * - * A minimap to show the gamemap, this only shows the map and has no - * interaction options. This version is used for map previews, there - * will be a another version which allows interaction. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_minimap - * - * == Minimap == - * - * @macro = minimap_description - * - * A minimap has no extra fields. - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="minimap"}{min=0}{max=-1}{super="generic/widget_instance"} - * @end{tag}{name="minimap"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/minimap.hpp b/src/gui/widgets/minimap.hpp index 078ce11ddc4c..12e9504a4149 100644 --- a/src/gui/widgets/minimap.hpp +++ b/src/gui/widgets/minimap.hpp @@ -30,10 +30,14 @@ struct builder_minimap; // ------------ WIDGET -----------{ /** + * @ingroup GUIWidgetWML + * * The basic minimap class. - * - * This minimap can only show a minimap, but it can't be interacted with. For - * that the tminimap_interactive class will be created. + * This minimap can only show a minimap, but it can't be interacted with. + * + * The following states exist: + * * state_enabled - the minimap is enabled. + * A minimap has no extra fields. */ class minimap : public styled_widget { diff --git a/src/gui/widgets/multi_page.cpp b/src/gui/widgets/multi_page.cpp index 8391de92b17d..0020d9b9faf9 100644 --- a/src/gui/widgets/multi_page.cpp +++ b/src/gui/widgets/multi_page.cpp @@ -171,27 +171,6 @@ multi_page_definition::multi_page_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_multi_page - * - * == Multi page == - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="multi_page_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @macro = multi_page_description - * - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{table}{config} - * grid & grid & & A grid containing the widgets for main - * widget. $ - * @end{table} - * @allow{link}{name="gui/window/resolution/grid"} - * @end{tag}{name="resolution"} - * @end{tag}{name="multi_page_definition"} - * @end{parent}{name="gui/"} - * A multipage has no states. - */ multi_page_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg), grid(nullptr) { @@ -203,49 +182,6 @@ multi_page_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{multi_page_description} - * - * A multi page is a styled_widget that contains several 'pages' of which - * only one is visible. The pages can contain the same widgets containing - * the same 'kind' of data or look completely different. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_multi_page - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="multi_page"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Multi page == - * - * @macro = multi_page_description - * - * List with the multi page specific variables: - * @begin{table}{config} - * page_definition & section & & This defines how a multi page item - * looks. It must contain the grid - * definition for at least one page. $ - * - * page_data & section & [] & A grid alike section which stores the - * initial data for the multi page. Every - * row must have the same number of columns - * as the 'page_definition'. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. - * @end{table} - * @begin{tag}{name="page_definition"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="page_definition"} - * @begin{tag}{name="page_data"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="page_data"} - * @end{tag}{name="multi_page"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/multi_page.hpp b/src/gui/widgets/multi_page.hpp index d0350dc86b54..465f4b400618 100644 --- a/src/gui/widgets/multi_page.hpp +++ b/src/gui/widgets/multi_page.hpp @@ -31,7 +31,20 @@ struct builder_multi_page; class generator_base; -/** The multi page class. */ +/** + * @ingroup GUIWidgetWML + * + * A multi page is a control that contains several 'pages' of which only one is visible. + * The pages can contain the same widgets containing the same 'kind' of data or look completely different. + * Key |Type |Default |Description + * -------------|----------------------------|---------|----------- + * grid | @ref guivartype_grid "grid"|mandatory|Defines the grid with the widgets to place on the page. + * A multipage has no states. List with the multi page specific variables: + * Key |Type |Default |Description + * ---------------|----------------------------------|---------|----------- + * page_definition| @ref guivartype_section "section"|mandatory|This defines how a multi page item looks. It must contain the grid definition for at least one page. + * page_data | @ref guivartype_section "section"|[] |A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'. + */ class multi_page : public container_base { friend struct implementation::builder_multi_page; diff --git a/src/gui/widgets/multimenu_button.cpp b/src/gui/widgets/multimenu_button.cpp index 32878fc55e4b..0ebe9065900b 100644 --- a/src/gui/widgets/multimenu_button.cpp +++ b/src/gui/widgets/multimenu_button.cpp @@ -244,34 +244,6 @@ multimenu_button_definition::multimenu_button_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_multimenu_button - * - * == multimenu_button == - * - * @macro = multimenu_button_description - * - * The following states exist: - * * state_enabled, the multimenu_button is enabled. - * * state_disabled, the multimenu_button is disabled. - * * state_pressed, the left mouse multimenu_button is down. - * * state_focused, the mouse is over the multimenu_button. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="multimenu_button_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="multimenu_button_definition"} - * @end{parent}{name="gui/"} - */ multimenu_button_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -284,44 +256,6 @@ multimenu_button_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{multimenu_button_description} - * - * A multimenu_button is a styled_widget to choose an element from a list of elements. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_multimenu_button - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="multimenu_button"}{min=0}{max=-1}{super="generic/widget_instance"} - * == multimenu_button == - * - * @macro = multimenu_button_description - * - * Instance of a multimenu_button. When a multimenu_button has a return value it sets the - * return value for the window. Normally this closes the window and returns - * this value to the caller. The return value can either be defined by the - * user or determined from the id of the multimenu_button. The return value has a - * higher precedence as the one defined by the id. (Of course it's weird to - * give a multimenu_button an id and then override its return value.) - * - * When the multimenu_button doesn't have a standard id, but you still want to use the - * return value of that id, use return_value_id instead. This has a higher - * precedence as return_value. - * - * List with the multimenu_button specific variables: - * @begin{table}{config} - * return_value_id & string & "" & The return value id. $ - * return_value & int & 0 & The return value. $ - * maximum_shown & int & -1 & The maximum number of currently selected values to list on the button. $ - * - * @end{table} - * @end{tag}{name="multimenu_button"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/multimenu_button.hpp b/src/gui/widgets/multimenu_button.hpp index da82b7fc2a51..126c9bd66c4b 100644 --- a/src/gui/widgets/multimenu_button.hpp +++ b/src/gui/widgets/multimenu_button.hpp @@ -36,7 +36,31 @@ struct builder_multimenu_button; // ------------ WIDGET -----------{ /** - * Simple push button. + * @ingroup GUIWidgetWML + * + * A multimenu_button is a styled_widget to choose an element from a list of elements. + * + * When a multimenu_button has a return value it sets the return value for the window. + * Normally this closes the window and returns this value to the caller. + * The return value can either be defined by the user or determined from the id of the multimenu_button. + * The return value has a higher precedence as the one defined by the id. + * (Of course it's weird to give a multimenu_button an id and then override its return value.) + * + * When the multimenu_button doesn't have a standard id, but you still want to use the return value of that id, use return_value_id instead. + * This has a higher precedence as return_value. + * + * List with the multimenu_button specific variables: + * Key |Type |Default |Description + * ---------------|------------------------------------|---------|----------- + * return_value_id| @ref guivartype_string "string" |"" |The return value id. + * return_value | @ref guivartype_int "int" |0 |The return value. + * maximum_shown | @ref guivartype_int "int" |-1 |The maximum number of currently selected values to list on the button. + * + * The following states exist: + * * state_enabled - the multimenu_button is enabled. + * * state_disabled - the multimenu_button is disabled. + * * state_pressed - the left mouse multimenu_button is down. + * * state_focused - the mouse is over the multimenu_button. */ class multimenu_button : public styled_widget { diff --git a/src/gui/widgets/pane.cpp b/src/gui/widgets/pane.cpp index 80de1d5ecc8a..2f3de445b732 100644 --- a/src/gui/widgets/pane.cpp +++ b/src/gui/widgets/pane.cpp @@ -369,40 +369,6 @@ void pane::signal_handler_request_placement(dispatcher& dispatcher, // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{pane_description} - * - * A pane is a container where new members can be added and removed - * during run-time. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_viewport - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="pane"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Label == - * - * @macro = viewport_description - * - * List with the label specific variables: - * @begin{table}{config} - * grow_direction & grow_direction & & - * The direction in which new items grow. $ - * parallel_items & unsigned & & - * The number of items that are growing in - * parallel. $ - * item_definition & section & & - * The definition of a new item. $ - * @end{table} - * - * @begin{tag}{name="item_definition"}{min=1}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="item_definition"} - * @end{tag}{name="pane"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/pane.hpp b/src/gui/widgets/pane.hpp index 1f635cfd402e..a62539f85c19 100644 --- a/src/gui/widgets/pane.hpp +++ b/src/gui/widgets/pane.hpp @@ -34,6 +34,11 @@ struct builder_pane; class grid; +/** + * @ingroup GUIWidgetWML + * + * A pane is a container where new members can be added and removed during run-time. + */ class pane : public widget { friend struct pane_implementation; diff --git a/src/gui/widgets/panel.cpp b/src/gui/widgets/panel.cpp index 9bfac6805dce..6232f533e996 100644 --- a/src/gui/widgets/panel.cpp +++ b/src/gui/widgets/panel.cpp @@ -103,44 +103,6 @@ panel_definition::panel_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_panel - * - * == Panel == - * - * @macro = panel_description - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="panel_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * A panel is always enabled and can't be disabled. Instead it uses the - * states as layers to draw on. - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * The resolution for a panel also contains the following keys: - * @begin{table}{config} - * top_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * bottom_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * left_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * right_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * @end{table} - * - * The following layers exist: - * * background, the background of the panel. - * * foreground, the foreground of the panel. - * @begin{tag}{name="foreground"}{min=0}{max=1} - * @allow{link}{name="generic/state/draw"} - * @end{tag}{name="foreground"} - * @begin{tag}{name="background"}{min=0}{max=1} - * @allow{link}{name="generic/state/draw"} - * @end{tag}{name="background"} - * @end{tag}{name="resolution"} - * @end{tag}{name="panel_definition"} - * @end{parent}{name="gui/"} - */ panel_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , top_border(cfg["top_border"]) @@ -155,34 +117,6 @@ panel_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{panel_description} - * - * A panel is an item which can hold other items. The difference - * between a grid and a panel is that it's possible to define how a - * panel looks. A grid in an invisible container to just hold the - * items. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_panel - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="panel"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * == Panel == - * - * @macro = panel_description - * - * @begin{table}{config} - * grid & grid & & Defines the grid with the widgets to - * place on the panel. $ - * @end{table} - * @allow{link}{name="gui/window/resolution/grid"} - * @end{tag}{name="panel"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/panel.hpp b/src/gui/widgets/panel.hpp index 37185ef578ce..42a0442b9843 100644 --- a/src/gui/widgets/panel.hpp +++ b/src/gui/widgets/panel.hpp @@ -29,10 +29,30 @@ struct builder_panel; // ------------ WIDGET -----------{ /** - * Visible container to hold multiple widgets. - * - * This widget can draw items beyond the widgets it holds and in front of them. - * A panel is always active so these functions return dummy values. + * @ingroup GUIWidgetWML + * + * A panel is a visible container to hold multiple widgets. + * The difference between a grid and a panel is that it's possible to define how a panel looks. + * A grid in an invisible container to just hold the items. + * A panel is always enabled and can't be disabled. + * Instead it uses the states as layers to draw on and can draw items beyond the widgets it holds and in front of them. + * A panel is always active so some functions return dummy values. + * + * The widget instance has the following: + * Key |Type |Default |Description + * -------------|----------------------------|---------|----------- + * grid | @ref guivartype_grid "grid"|mandatory|Defines the grid with the widgets to place on the panel. + * + * The resolution for a panel also contains the following keys: + * Key |Type |Default|Description + * -------------|------------------------------------|-------|------------- + * top_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * bottom_border| @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * left_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * right_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * The following layers exist: + * * background - the background of the panel. + * * foreground - the foreground of the panel. */ class panel : public container_base { diff --git a/src/gui/widgets/password_box.cpp b/src/gui/widgets/password_box.cpp index 4138a227cbef..e3d386fb8fcb 100644 --- a/src/gui/widgets/password_box.cpp +++ b/src/gui/widgets/password_box.cpp @@ -101,7 +101,7 @@ void password_box::paste_selection(const bool mouse) insert_char(text); } -const std::string& password_box::type() \ +const std::string& password_box::type() { static const std::string type = "password_box"; return type; @@ -117,21 +117,6 @@ const std::string& password_box::get_control_type() const namespace implementation { -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_password_box - * - * == Password box == - * - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="password_box"}{min=0}{max=-1}{super="generic/widget_instance"} - * @begin{table}{config} - * label & t_string & "" & The initial text of the password box. $ - * @end{table} - * @end{tag}{name="password_box"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - builder_password_box::builder_password_box(const config& cfg) : builder_styled_widget(cfg), history_(cfg["history"]) { diff --git a/src/gui/widgets/password_box.hpp b/src/gui/widgets/password_box.hpp index 7c30d84d3b86..1adf4a90e00a 100644 --- a/src/gui/widgets/password_box.hpp +++ b/src/gui/widgets/password_box.hpp @@ -35,6 +35,13 @@ namespace implementation // ------------ WIDGET -----------{ +/** + * @ingroup GUIWidgetWML + * + * Key |Type |Default |Description + * -------------|------------------------------------|---------|----------- + * label | @ref guivartype_t_string "t_string"|"" |The initial text of the password box. + */ class password_box : public text_box { public: diff --git a/src/gui/widgets/progress_bar.cpp b/src/gui/widgets/progress_bar.cpp index 592d2c592bee..9e9d28a54337 100644 --- a/src/gui/widgets/progress_bar.cpp +++ b/src/gui/widgets/progress_bar.cpp @@ -86,28 +86,6 @@ progress_bar_definition::progress_bar_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_progress_bar - * - * == Progress bar == - * - * @macro = progress_bar_description - * - * The definition of a progress bar. This object shows the progress of a certain - * action, or the value state of a certain item. - * - * The following states exist: - * * state_enabled, the progress bar is enabled. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="progress_bar_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="progress_bar_definition"} - * @end{parent}{name="gui/"} - */ progress_bar_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -117,27 +95,6 @@ progress_bar_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{progress_bar_description} - * A progress bar shows the progress of a certain object. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_progress_bar - * - * == Image == - * - * @macro = progress_bar_description - * - * A progress bar has no extra fields. - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="progress_bar"}{min=0}{max=-1}{super="generic/widget_instance"} - * @end{tag}{name="progress_bar"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/progress_bar.hpp b/src/gui/widgets/progress_bar.hpp index 96aa91c09f97..c54d3d35e9d9 100644 --- a/src/gui/widgets/progress_bar.hpp +++ b/src/gui/widgets/progress_bar.hpp @@ -28,6 +28,14 @@ struct builder_progress_bar; // ------------ WIDGET -----------{ +/** + * @ingroup GUIWidgetWML + * + * This object shows the progress of a certain action, or the value state of a certain item. + * + * The following states exist: + * * state_enabled - the progress bar is enabled. + */ class progress_bar : public styled_widget { public: diff --git a/src/gui/widgets/repeating_button.cpp b/src/gui/widgets/repeating_button.cpp index f514ffff3b7a..d3e54651394c 100644 --- a/src/gui/widgets/repeating_button.cpp +++ b/src/gui/widgets/repeating_button.cpp @@ -173,34 +173,6 @@ repeating_button_definition::repeating_button_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_repeating_button - * - * == Repeating button == - * - * @macro = repeating_button_description - * - * The following states exist: - * * state_enabled, the repeating_button is enabled. - * * state_disabled, the repeating_button is disabled. - * * state_pressed, the left mouse repeating_button is down. - * * state_focused, the mouse is over the repeating_button. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="repeating_button_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="repeating_button_definition"} - * @end{parent}{name="gui/"} - */ repeating_button_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -214,28 +186,6 @@ repeating_button_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{repeating_button_description} - * - * A repeating_button is a styled_widget that can be pushed down and repeat a - * certain action. Once the button is down every x milliseconds it is - * down a new down event is triggered. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_repeating_button - * - * == Repeating button == - * - * @macro = repeating_button_description - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="repeating_button"}{min=0}{max=-1}{super="gui/window/resolution/grid/row/column/button"} - * @end{tag}{name="repeating_button"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/repeating_button.hpp b/src/gui/widgets/repeating_button.hpp index 8855240506bb..cd73873cd67a 100644 --- a/src/gui/widgets/repeating_button.hpp +++ b/src/gui/widgets/repeating_button.hpp @@ -29,6 +29,18 @@ struct builder_repeating_button; // ------------ WIDGET -----------{ +/** + * @ingroup GUIWidgetWML + * + * A repeating_button is a control that can be pushed down and repeat a certain action. + * Once the button is down every x milliseconds it is down a new down event is triggered. + * + * The following states exist: + * * state_enabled - the repeating_button is enabled. + * * state_disabled - the repeating_button is disabled. + * * state_pressed - the left mouse repeating_button is down. + * * state_focussed - the mouse is over the repeating_button. + */ class repeating_button : public styled_widget, public clickable_item { public: diff --git a/src/gui/widgets/scroll_label.cpp b/src/gui/widgets/scroll_label.cpp index 0188735b8cee..6fa85d115347 100644 --- a/src/gui/widgets/scroll_label.cpp +++ b/src/gui/widgets/scroll_label.cpp @@ -171,48 +171,6 @@ scroll_label_definition::scroll_label_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_scroll_label - * - * == Scroll label == - * - * @macro = scroll_label_description - * - * @begin{parent}{name="gui/"} - * This widget is slower as a normal label widget so only use this widget - * when the scrollbar is required (or expected to become required). - * @begin{tag}{name="scroll_label_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{table}{config} - * grid & grid & & A grid containing the widgets for main - * widget. $ - * @end{table} - * @allow{link}{name="gui/window/resolution/grid"} - * TODO we need one definition for a vertical scrollbar since this is the second - * time we use it. - * - * @begin{table}{dialog_widgets} - * _content_grid & & grid & m & A grid which should only contain one - * label widget. $ - * _scrollbar_grid & & grid & m & A grid for the scrollbar - * (Merge with listbox info.) $ - * @end{table} - * @begin{tag}{name="content_grid"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="content_grid"} - * @begin{tag}{name="scrollbar_grid"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="scrollbar_grid"} - * The following states exist: - * * state_enabled, the scroll label is enabled. - * * state_disabled, the scroll label is disabled. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="scroll_label_definition"} - * @end{parent}{name="gui/"} - */ scroll_label_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg), grid(nullptr) { @@ -228,39 +186,6 @@ scroll_label_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{scroll_label_description} - * - * A scroll label is a label that wraps its text and also has a - * vertical scrollbar. This way a text can't be too long to be shown - * for this widget. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_scroll_label - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="scroll_label"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * == Scroll label == - * - * @macro = scroll_label_description - * - * List with the scroll label specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * wrap & boolean & true & Determines whether the text of the - * label is allowed to wrap. $ - * @end{table} - * @end{tag}{name="scroll_label"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/scroll_label.hpp b/src/gui/widgets/scroll_label.hpp index 936ce516a8df..228a936beec3 100644 --- a/src/gui/widgets/scroll_label.hpp +++ b/src/gui/widgets/scroll_label.hpp @@ -33,11 +33,31 @@ struct builder_scroll_label; } /** + * @ingroup GUIWidgetWML + * * Label showing a text. * - * This version shows a scrollbar if the text gets too long and has some - * scrolling features. In general this widget is slower as the normal label so - * the normal label should be preferred. + * This version shows a scrollbar if the text gets too long and has some scrolling features. + * In general this widget is slower as the normal label so the normal label should be preferred. + * + * Key |Type |Default |Description + * -------------|----------------------------|---------|----------- + * grid | @ref guivartype_grid "grid"|mandatory|A grid containing the widgets for main widget. + * + * TODO: we need one definition for a vertical scrollbar since this is the second time we use it. + * + * ID (return value)|Type |Default |Description + * -----------------|----------------------------|---------|----------- + * _content_grid | @ref guivartype_grid "grid"|mandatory|A grid which should only contain one label widget. + * _scrollbar_grid | @ref guivartype_grid "grid"|mandatory|A grid for the scrollbar (Merge with listbox info.) + * The following states exist: + * * state_enabled - the scroll label is enabled. + * * state_disabled - the scroll label is disabled. + * List with the scroll label specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|----------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. */ class scroll_label : public scrollbar_container { diff --git a/src/gui/widgets/scrollbar_panel.cpp b/src/gui/widgets/scrollbar_panel.cpp index f5f7f79c0c51..0b228c165d39 100644 --- a/src/gui/widgets/scrollbar_panel.cpp +++ b/src/gui/widgets/scrollbar_panel.cpp @@ -62,31 +62,6 @@ scrollbar_panel_definition::scrollbar_panel_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_scrollbar_panel - * - * == Scrollbar panel == - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="scrollbar_panel_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="gui/window_definition/resolution"} - * The definition of a panel with scrollbars. A panel is a container holding - * other elements in its grid. A panel is always enabled and can't be - * disabled. Instead it uses the states as layers to draw on. - * - * @begin{table}{config} - * grid & grid & & A grid containing the widgets for main - * widget. $ - * @end{table} - * The following layers exist: - * * background, the background of the panel. - * * foreground, the foreground of the panel. - * - * @end{tag}{name="resolution"} - * @end{tag}{name="scrollbar_panel_definition"} - * @end{parent}{name="gui/"} - */ scrollbar_panel_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg), grid() { @@ -102,35 +77,6 @@ scrollbar_panel_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_scrollbar_panel - * - * == Scrollbar panel == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="scrollbar_panel"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * Instance of a scrollbar_panel. - * - * List with the scrollbar_panel specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * - * definition & section & & This defines how a scrollbar_panel item - * looks. It must contain the grid - * definition for 1 row of the list. $ - * - * @end{table} - * @begin{tag}{name="definition"}{min=0}{max=1}{super="gui/window/resolution/grid"} - * @end{tag}{name="definition"} - * @end{tag}{name="scrollbar_panel"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/scrollbar_panel.hpp b/src/gui/widgets/scrollbar_panel.hpp index 2885d8346eaf..36ec236f7a97 100644 --- a/src/gui/widgets/scrollbar_panel.hpp +++ b/src/gui/widgets/scrollbar_panel.hpp @@ -30,10 +30,28 @@ struct builder_scrollbar_panel; } /** + * @ingroup GUIWidgetWML + * * Visible container to hold multiple widgets. * - * This widget can draw items beyond the widgets it holds and in front of - * them. A panel is always active so these functions return dummy values. + * This widget can draw items beyond the widgets it holds and in front of them. + * A panel is always active so these functions return dummy values. + * + * A panel is a container holding other elements in its grid. + * It uses the states as layers to draw on. + * + * Key |Type |Default |Description + * -------------|----------------------------|---------|----------- + * grid | @ref guivartype_grid "grid"|mandatory|A grid containing the widgets for main widget. + * The following layers exist: + * * background - the background of the panel. + * * foreground - the foreground of the panel. + * List with the scrollbar_panel specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|----------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * definition | @ref guivartype_section "section" |mandatory |This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list. */ class scrollbar_panel : public scrollbar_container { diff --git a/src/gui/widgets/size_lock.cpp b/src/gui/widgets/size_lock.cpp index a43a63d8be00..48ea5be545ff 100644 --- a/src/gui/widgets/size_lock.cpp +++ b/src/gui/widgets/size_lock.cpp @@ -96,23 +96,6 @@ size_lock_definition::size_lock_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_size_lock - * - * == Size lock == - * - * A size lock contains one child widget and forces it to have the specified size. - * This can be used, for example, when there are two list boxes in different rows of - * the same grid and it's desired that only one list box changes size when its - * contents change. - * - * A size lock has no states. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="size_lock_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @end{tag}{name="size_lock_definition"} - * @end{tag}{name="gui/"} - */ size_lock_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , grid(nullptr) @@ -127,30 +110,6 @@ size_lock_definition::resolution::resolution(const config& cfg) grid = std::make_shared(child); } -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_size_lock - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="size_lock"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Size lock == - * - * A size lock contains one child widget and forces it to have the specified size. - * This can be used, for example, when there are two list boxes in different rows of - * the same grid and it's desired that only one list box changes size when its - * contents change. - * - * @begin{table}{config} - * widget & section & mandatory & The widget. $ - * width & f_unsigned & mandatory & The width of the widget. $ - * height & f_unsigned & mandatory & The height of the widget. $ - * @end{table} - * - * The variables available are the same as for window resolution, see - * [[GuiToolkitWML#Resolution_2]] for the list of items. - * @end{tag}{name="size_lock"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { builder_size_lock::builder_size_lock(const config& cfg) diff --git a/src/gui/widgets/size_lock.hpp b/src/gui/widgets/size_lock.hpp index 77b7ae355f5b..8883ca1a5d26 100644 --- a/src/gui/widgets/size_lock.hpp +++ b/src/gui/widgets/size_lock.hpp @@ -29,8 +29,22 @@ namespace implementation struct builder_size_lock; } -/* A fixed-size widget that wraps an arbitrary widget and forces it to the given size. */ - +/** + * @ingroup GUIWidgetWML + * + * A fixed-size widget that wraps an arbitrary widget and forces it to the given size. + * + * A size lock contains one child widget and forces it to have the specified size. + * This can be used, for example, when there are two list boxes in different rows of the same grid + * and it's desired that only one list box changes size when its contents change. + * + * A size lock has no states. + * Key |Type |Default |Description + * -------------|----------------------------------------|---------|----------- + * widget | @ref guivartype_section "section" |mandatory|The widget. + * width | @ref guivartype_f_unsigned "f_unsigned"|mandatory|The width of the widget. + * height | @ref guivartype_f_unsigned "f_unsigned"|mandatory|The height of the widget. + */ class size_lock : public container_base { friend struct implementation::builder_size_lock; diff --git a/src/gui/widgets/slider.cpp b/src/gui/widgets/slider.cpp index 7dd8a4734f07..756104e0335f 100644 --- a/src/gui/widgets/slider.cpp +++ b/src/gui/widgets/slider.cpp @@ -312,53 +312,6 @@ slider_definition::slider_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_slider - * - * == Slider == - * - * @macro = slider_description - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="slider_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{table}{config} - * minimum_positioner_length & unsigned & & - * The minimum size the positioner is - * allowed to be. The engine needs to know - * this in order to calculate the best size - * for the positioner. $ - * maximum_positioner_length & unsigned & 0 & - * The maximum size the positioner is - * allowed to be. If minimum and maximum are - * the same value the positioner is fixed - * size. If the maximum is 0 (and the - * minimum not) there's no maximum. $ - * left_offset & unsigned & 0 & The number of pixels at the left side - * which can't be used by the positioner. $ - * right_offset & unsigned & 0 & The number of pixels at the right side - * which can't be used by the positioner. $ - * @end{table} - * - * The following states exist: - * * state_enabled, the slider is enabled. - * * state_disabled, the slider is disabled. - * * state_pressed, the left mouse button is down on the positioner of the - * slider. - * * state_focused, the mouse is over the positioner of the slider. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="slider_definition"} - * @end{parent}{name="gui/"} - */ slider_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , positioner_length(cfg["minimum_positioner_length"]) @@ -376,57 +329,6 @@ slider_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{slider_description} - * A slider is a styled_widget that can select a value by moving a grip on a groove. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 3_slider - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="slider"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * == Slider == - * - * @macro = slider_description - * - * @begin{table}{config} - * best_slider_length & unsigned & 0 & - * The best length for the sliding part. $ - * minimum_value & int & 0 & The minimum value the slider can have. $ - * maximum_value & int & 0 & The maximum value the slider can have. $ - * - * step_size & unsigned & 0 & The number of items the slider's value - * increases with one step. $ - * value & int & 0 & The value of the slider. $ - * - * minimum_value_label & t_string & "" & - * If the minimum value is chosen there - * might be the need for a special value - * (eg off). When this key has a value - * that value will be shown if the minimum - * is selected. $ - * maximum_value_label & t_string & "" & - * If the maximum value is chosen there - * might be the need for a special value - * (eg unlimited)). When this key has a - * value that value will be shown if the - * maximum is selected. $ - * value_labels & [] & It might be the labels need to be shown - * are not a linear number sequence eg - * (0.5, 1, 2, 4) in that case for all - * items this section can be filled with - * the values, which should be the same - * number of items as the items in the - * slider. NOTE if this option is used, - * 'minimum_value_label' and - * 'maximum_value_label' are ignored. $ - * @end{table} - * @end{tag}{name="slider"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { builder_slider::builder_slider(const config& cfg) diff --git a/src/gui/widgets/slider.hpp b/src/gui/widgets/slider.hpp index 3730c822d6a2..a2bbf5ef196a 100644 --- a/src/gui/widgets/slider.hpp +++ b/src/gui/widgets/slider.hpp @@ -29,7 +29,32 @@ struct builder_slider; // ------------ WIDGET -----------{ -/** A slider. */ +/** + * @ingroup GUIWidgetWML + * + * A slider is a control that can select a value by moving a grip on a groove. + * Key |Type |Default |Description + * -------------------------|------------------------------------|---------|----------- + * minimum_positioner_length| @ref guivartype_unsigned "unsigned"|mandatory|The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner. + * maximum_positioner_length| @ref guivartype_unsigned "unsigned"|0 |The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum. + * left_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the left side which can't be used by the positioner. + * right_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the right side which can't be used by the positioner. + * Variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------|---------|----------- + * best_slider_length | @ref guivartype_unsigned "unsigned"|0 |The best length for the sliding part. + * minimum_value | @ref guivartype_int "int" |0 |The minimum value the slider can have. + * maximum_value | @ref guivartype_int "int" |0 |The maximum value the slider can have. + * step_size | @ref guivartype_unsigned "unsigned"|0 |The number of items the slider's value increases with one step. + * value | @ref guivartype_int "int" |0 |The value of the slider. + * minimum_value_label | @ref guivartype_t_string "t_string"|"" |If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected. + * maximum_value_label | @ref guivartype_t_string "t_string"|"" |If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected. + * The following states exist: + * * state_enabled - the slider is enabled. + * * state_disabled - the slider is disabled. + * * state_pressed - the left mouse button is down on the positioner of the slider. + * * state_focussed - the mouse is over the positioner of the slider. + */ class slider : public slider_base, public integer_selector { friend struct implementation::builder_slider; diff --git a/src/gui/widgets/spacer.cpp b/src/gui/widgets/spacer.cpp index d849bb50cb5b..cea97773900a 100644 --- a/src/gui/widgets/spacer.cpp +++ b/src/gui/widgets/spacer.cpp @@ -115,20 +115,6 @@ spacer_definition::spacer_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_spacer - * - * == Spacer == - * - * @macro = spacer_description - * - * A spacer has no states so nothing to load. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="spacer_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @end{tag}{name="spacer_definition"} - * @end{parent}{name="gui/"} - */ spacer_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -136,39 +122,6 @@ spacer_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{spacer_description} - * - * A spacer is a dummy item to either fill in a widget since no empty - * items are allowed or to reserve a fixed space. - * @end{macro} - */ - - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_spacer - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="spacer"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Spacer == - * - * @macro = spacer_description - * - * If either the width or the height is non-zero the spacer functions as a - * fixed size spacer. - * - * @begin{table}{config} - * width & f_unsigned & 0 & The width of the spacer. $ - * height & f_unsigned & 0 & The height of the spacer. $ - * @end{table} - * - * The variable available are the same as for the window resolution see - * https://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of - * items. - * @end{tag}{name="spacer"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/spacer.hpp b/src/gui/widgets/spacer.hpp index 31f4b2b628bf..25f496f8d4c9 100644 --- a/src/gui/widgets/spacer.hpp +++ b/src/gui/widgets/spacer.hpp @@ -30,13 +30,20 @@ struct builder_spacer; // ------------ WIDGET -----------{ /** - * An empty widget. - * - * Since every grid cell needs a widget this is a blank widget. This widget can - * also be used to 'force' sizes. - * - * Since we're a kind of dummy class we're always active, our drawing does - * nothing. + * @ingroup GUIWidgetWML + * + * An empty widget to either fill in a widget since no empty items are allowed or to reserve a fixed space. + * + * Since every grid cell needs a widget this is a blank widget. + * This widget can also be used to 'force' sizes - if either the width or the height is non-zero the spacer functions as a fixed size spacer. + * + * Since we're a kind of dummy class we're always active, our drawing does nothing. + * + * Key |Type |Default |Description + * -------------|----------------------------------------|---------|----------- + * width | @ref guivartype_f_unsigned "f_unsigned"|0 |The width of the spacer. + * height | @ref guivartype_f_unsigned "f_unsigned"|0 |The height of the spacer. + * The variable available are the same as for the window resolution see @ref builder_window::window_resolution for the list of items. */ class spacer : public styled_widget { diff --git a/src/gui/widgets/stacked_widget.cpp b/src/gui/widgets/stacked_widget.cpp index 9964ad182249..7661ddbca800 100644 --- a/src/gui/widgets/stacked_widget.cpp +++ b/src/gui/widgets/stacked_widget.cpp @@ -209,26 +209,6 @@ stacked_widget_definition::stacked_widget_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_stacked_widget - * - * == Stacked widget == - * - * A stacked widget holds several widgets on top of each other. This can be used - * for various effects; add an optional overlay to an image, stack it with a - * spacer to force a minimum size of a widget. The latter is handy to avoid - * making a separate definition for a single instance with a fixed size. - * - * A stacked widget has no states. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="stacked_widget_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @allow{link}{name="gui/window/resolution/grid"} - * @end{tag}{name="resolution"} - * @end{tag}{name="stacked_widget_definition"} - * @end{parent}{name="gui/"} - */ stacked_widget_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg), grid(nullptr) { @@ -244,26 +224,6 @@ stacked_widget_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIToolkitWML - * @order = 2_stacked_widget - * - * == Stacked widget == - * - * A stacked widget is a set of widget stacked on top of each other. The - * widgets are drawn in the layers, in the order defined in the the instance - * config. By default the last drawn item is also the 'active' layer for the - * event handling. - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="stacked_widget"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * @begin{table}{config} - * @end{table} - * @begin{tag}{name="layer"}{min=0}{max=-1}{super="gui/window/resolution/grid"} - * @end{tag}{name="layer"} - * @end{tag}{name="stacked_widget"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/stacked_widget.hpp b/src/gui/widgets/stacked_widget.hpp index 35f2385da6ba..46a694e2110e 100644 --- a/src/gui/widgets/stacked_widget.hpp +++ b/src/gui/widgets/stacked_widget.hpp @@ -33,6 +33,15 @@ struct builder_stacked_widget; class generator_base; +/** + * @ingroup GUIWidgetWML + * + * A stacked widget holds several widgets on top of each other. + * This can be used for various effects; add an optional overlay to an image, stack it with a spacer to force a minimum size of a widget. + * The latter is handy to avoid making a separate definition for a single instance with a fixed size. + * + * A stacked widget has no states. + */ class stacked_widget : public container_base { friend struct stacked_widget_implementation; diff --git a/src/gui/widgets/styled_widget.cpp b/src/gui/widgets/styled_widget.cpp index 3147bd4a44a3..435005c5712c 100644 --- a/src/gui/widgets/styled_widget.cpp +++ b/src/gui/widgets/styled_widget.cpp @@ -586,84 +586,6 @@ std::string styled_widget::get_label_link(const point & position) const // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 1_widget - * - * = Widget = - * @begin{parent}{name="generic/"} - * @begin{tag}{name="widget_instance"}{min="0"}{max="-1"} - * All widgets placed in the cell have some values in common: - * @begin{table}{config} - * id & string & "" & This value is used for the engine to - * identify 'special' items. This means that - * for example a text_box can get the proper - * initial value. This value should be - * unique or empty. Those special values are - * documented at the window definition that - * uses them. NOTE items starting with an - * underscore are used for composed widgets - * and these should be unique per composed - * widget. $ - * - * definition & string & "default" & - * The id of the widget definition to use. - * This way it's possible to select a - * specific version of the widget e.g. a - * title label when the label is used as - * title. $ - * - * linked_group & string & "" & The linked group the styled_widget belongs - * to. $ - * - * label & t_string & "" & Most widgets have some text associated - * with them, this field contain the value - * of that text. Some widgets use this value - * for other purposes, this is documented - * at the widget. E.g. an image uses the - * filename in this field. $ - * - * tooltip & t_string & "" & If you hover over a widget a while (the - * time it takes can differ per widget) a - * short help can show up.This defines the - * text of that message. This field may not - * be empty when 'help' is set. $ - * - * help & t_string & "" & If you hover over a widget and press F10 - * (or the key the user defined for the help - * tip) a help message can show up. This - * help message might be the same as the - * tooltip but in general (if used) this - * message should show more help. This - * defines the text of that message. $ - * - * use_markup & bool & false & Whether to format the text using Pango - * markup. Applies to Labels and - * other Widgets with text. $ - * - * use_tooltip_on_label_overflow & bool & true & - * If the text on the label is truncated and - * the tooltip is empty the label can be - * used for the tooltip. If this variable is - * set to true this will happen. $ - * - * debug_border_mode & unsigned & 0 & - * The mode for showing the debug border. - * This border shows the area reserved for - * a widget. This function is only meant - * for debugging and might not be - * available in all Wesnoth binaries. - * Available modes: - * @* 0 no border. - * @* 1 1 pixel border. - * @* 2 floodfill the widget area. $ - * - * debug_border_color & color & "" & The color of the debug border. $ - * @end{table} - * @end{tag}{name="widget_instance"} - * @end{parent}{name="generic/"} - */ - namespace implementation { diff --git a/src/gui/widgets/styled_widget.hpp b/src/gui/widgets/styled_widget.hpp index 93e1f246cff0..901a74f0f790 100644 --- a/src/gui/widgets/styled_widget.hpp +++ b/src/gui/widgets/styled_widget.hpp @@ -30,7 +30,25 @@ namespace implementation struct builder_styled_widget; } // namespace implementation -/** Base class for all visible items. */ +/** + * @ingroup GUIWidgetWML + * + * Base class for all visible items. + * + * All widgets placed in a cell of a grid have some values in common: + * Key |Type |Default |Description + * -----------------------------|------------------------------------|---------|----------- + * id | @ref guivartype_string "string" |"" |This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE: items starting with an underscore are used for composed widgets and these should be unique per composed widget. + * definition | @ref guivartype_string "string" |"default"|The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title. + * linked_group | @ref guivartype_string "string" |"" |The linked group the control belongs to. + * label | @ref guivartype_t_string "t_string"|"" |Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field. + * tooltip | @ref guivartype_t_string "t_string"|"" |If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set. + * help | @ref guivartype_t_string "t_string"|"" |If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message. + * use_tooltip_on_label_overflow| @ref guivartype_bool "bool" |true |If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen. + * debug_border_mode | @ref guivartype_unsigned "unsigned"|0 |The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
  • 0 - no border
  • 1 - 1 pixel border
  • 2 - floodfill the widget area
+ * debug_border_color | @ref guivartype_color "color" |"" |The color of the debug border. + * size_text | @ref guivartype_t_string "t_string"|"" |Sets the minimum width of the widget depending on the text in it. (Note: not implemented yet.) + */ class styled_widget : public widget { friend class debug_layout_graph; @@ -39,8 +57,7 @@ class styled_widget : public widget /** * Constructor. * - * @param builder The builder object with the settings for the - * object. + * @param builder The builder object with the settings for the object. * @param control_type The type of control to be built. */ styled_widget(const implementation::builder_styled_widget& builder, diff --git a/src/gui/widgets/text_box.cpp b/src/gui/widgets/text_box.cpp index 12c4613414bd..eff643fd6153 100644 --- a/src/gui/widgets/text_box.cpp +++ b/src/gui/widgets/text_box.cpp @@ -403,44 +403,6 @@ text_box_definition::text_box_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_text_box - * - * == Text box == - * - * The definition of a text box. - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="ext_box_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * The resolution for a text box also contains the following keys: - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super=generic/widget_definition/resolution} - * @begin{table}{config} - * text_x_offset & f_unsigned & "" & The x offset of the text in the text - * box. This is needed for the code to - * determine where in the text the mouse - * clicks, so it can set the cursor - * properly. $ - * text_y_offset & f_unsigned & "" & The y offset of the text in the text - * box. $ - * @end{table} - * - * The following states exist: - * * state_enabled, the text box is enabled. - * * state_disabled, the text box is disabled. - * * state_focused, the text box has the focus of the keyboard. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @begin{tag}{name="state_hovered"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_hovered"} - * @end{tag}{name="resolution"} - * @end{tag}{name="ext_box_definition"} - * @end{parent}{name="gui/"} - */ text_box_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , text_x_offset(cfg["text_x_offset"]) @@ -455,28 +417,6 @@ text_box_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_text_box - * - * == Text box == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="text_box"}{min="0"}{max="-1"}{super="generic/widget_instance"} - * @begin{table}{config} - * label & t_string & "" & The initial text of the text box. $ - * history & string & "" & The name of the history for the text - * box. - * A history saves the data entered in a - * text box between the games. With the up - * and down arrow it can be accessed. To - * create a new history item just add a - * new unique name for this field and the - * engine will handle the rest. $ - * @end{table} - * @end{tag}{name="text_box"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/text_box.hpp b/src/gui/widgets/text_box.hpp index 3251c59a457d..c984ff3162dc 100644 --- a/src/gui/widgets/text_box.hpp +++ b/src/gui/widgets/text_box.hpp @@ -117,7 +117,26 @@ class text_history bool enabled_; }; -/** Class for a single line text area. */ +/** + * @ingroup GUIWidgetWML + * + * Class for a single line text area. + * + * The resolution for a text box also contains the following keys: + * Key |Type |Default |Description + * -------------|----------------------------------------|---------|----------- + * text_x_offset| @ref guivartype_f_unsigned "f_unsigned"|"" |The x offset of the text in the text box. This is needed for the code to determine where in the text the mouse clicks, so it can set the cursor properly. + * text_y_offset| @ref guivartype_f_unsigned "f_unsigned"|"" |The y offset of the text in the text box. + * The following states exist: + * * state_enabled - the text box is enabled. + * * state_disabled - the text box is disabled. + * * state_focussed - the text box has the focus of the keyboard. + * The following variables exist: + * Key |Type |Default |Description + * -------------|------------------------------------|---------|----------- + * label | @ref guivartype_t_string "t_string"|"" |The initial text of the text box. + * history | @ref guivartype_string "string" |"" |The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest. + */ class text_box : public text_box_base { friend struct implementation::builder_text_box; diff --git a/src/gui/widgets/toggle_button.cpp b/src/gui/widgets/toggle_button.cpp index 2d3a44e529e6..307a2f05c8b8 100644 --- a/src/gui/widgets/toggle_button.cpp +++ b/src/gui/widgets/toggle_button.cpp @@ -201,41 +201,6 @@ toggle_button_definition::toggle_button_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_toggle_button - * - * == Toggle button == - * - * The definition of a toggle button. - * - * The following states exist: - * * state_enabled, the button is enabled and not selected. - * * state_disabled, the button is disabled and not selected. - * * state_focused, the mouse is over the button and not selected. - * - * * state_enabled_selected, the button is enabled and selected. - * * state_disabled_selected, the button is disabled and selected. - * * state_focused_selected, the mouse is over the button and selected. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="oggle_button_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @begin{tag}{name="state_enabled_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled_selected"} - * @begin{tag}{name="state_disabled_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled_selected"} - * @begin{tag}{name="state_focused_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused_selected"} - * @end{tag}{name="resolution"} - * @end{tag}{name="oggle_button_definition"} - * @end{parent}{name="gui/"} - */ toggle_button_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) { @@ -251,26 +216,6 @@ toggle_button_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIToolkitWML - * @order = 2_toggle_button - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="toggle_button"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Toggle button == - * - * @begin{table}{config} - * icon & f_string & "" & The name of the icon file to show. $ - * return_value_id & string & "" & The return value id, see - * [[GUIToolkitWML#Button]] for more - * information. $ - * return_value & int & 0 & The return value, see - * [[GUIToolkitWML#Button]] for more - * information. $ - * @end{table} - * @end{tag}{name="toggle_button"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/toggle_button.hpp b/src/gui/widgets/toggle_button.hpp index 679738129524..4d9871578670 100644 --- a/src/gui/widgets/toggle_button.hpp +++ b/src/gui/widgets/toggle_button.hpp @@ -27,10 +27,27 @@ namespace implementation // ------------ WIDGET -----------{ /** + * @ingroup GUIWidgetWML + * * Class for a toggle button. - * - * A toggle button is a button with two states 'up' and 'down' or 'selected' and - * 'deselected'. When the mouse is pressed on it the state changes. + * + * A toggle button is a button with two states 'up' and 'down' or 'selected' and 'deselected'. + * When the mouse is pressed on it the state changes. + * + * The following states exist: + * * state_enabled - the button is enabled and not selected. + * * state_disabled - the button is disabled and not selected. + * * state_focussed - the mouse is over the button and not selected. + * * state_enabled_selected - the button is enabled and selected. + * * state_disabled_selected - the button is disabled and selected. + * * state_focussed_selected - the mouse is over the button and selected. + * + * Variables: + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * icon | @ref guivartype_string "string" |"" |The name of the icon file to show. + * return_value_id | @ref guivartype_string "string" |"" |The return value id. + * return_value | @ref guivartype_int "int" |0 |The return value. */ class toggle_button : public styled_widget, public selectable_item { diff --git a/src/gui/widgets/toggle_panel.cpp b/src/gui/widgets/toggle_panel.cpp index e9e4cf27e15d..c9de9105df71 100644 --- a/src/gui/widgets/toggle_panel.cpp +++ b/src/gui/widgets/toggle_panel.cpp @@ -293,55 +293,6 @@ toggle_panel_definition::toggle_panel_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_toggle_panel - * - * == Toggle panel == - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="oggle_panel_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * The definition of a toggle panel. A toggle panel is like a toggle button, but - * instead of being a button it's a panel. This means it can hold multiple child - * items. - * - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super=generic/widget_definition/resolution} - * The resolution for a toggle panel also contains the following keys: - * @begin{table}{config} - * top_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * bottom_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * left_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * right_border & unsigned & 0 & The size which isn't used for the client - * area. $ - * @end{table} - * - * The following states exist: - * * state_enabled, the panel is enabled and not selected. - * * state_disabled, the panel is disabled and not selected. - * * state_focused, the mouse is over the panel and not selected. - * - * * state_enabled_selected, the panel is enabled and selected. - * * state_disabled_selected, the panel is disabled and selected. - * * state_focused_selected, the mouse is over the panel and selected. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @begin{tag}{name="state_enabled_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled_selected"} - * @begin{tag}{name="state_disabled_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled_selected"} - * @begin{tag}{name="state_focused_selected"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused_selected"} - * @end{tag}{name="resolution"} - * @end{tag}{name="oggle_panel_definition"} - * @end{parent}{name="gui/"} - */ toggle_panel_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , top_border(cfg["top_border"]) @@ -360,34 +311,6 @@ toggle_panel_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_toggle_panel - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="toggle_panel"}{min=0}{max=-1}{super="generic/widget_instance"} - * == Toggle panel == - * - * A toggle panel is an item which can hold other items. The difference between - * a grid and a panel is that it's possible to define how a panel looks. A grid - * in an invisible container to just hold the items. The toggle panel is a - * combination of the panel and a toggle button, it allows a toggle button with - * its own grid. - * - * @begin{table}{config} - * grid & grid & & Defines the grid with the widgets to - * place on the panel. $ - * return_value_id & string & "" & The return value id, see - * [[GUIToolkitWML#Button]] for more - * information. $ - * return_value & int & 0 & The return value, see - * [[GUIToolkitWML#Button]] for more - * information. $ - * @end{table} - * @allow{link}{name="gui/window/resolution/grid"} - * @end{tag}{name="toggle_panel"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/toggle_panel.hpp b/src/gui/widgets/toggle_panel.hpp index 5f479b97ed85..8b73f63ffd43 100644 --- a/src/gui/widgets/toggle_panel.hpp +++ b/src/gui/widgets/toggle_panel.hpp @@ -28,12 +28,39 @@ struct builder_toggle_panel; // ------------ WIDGET -----------{ /** + * @ingroup GUIWidgetWML + * * Class for a toggle button. - * - * Quite some code looks like toggle_button maybe we should inherit from that - * but let's test first. the problem is that the toggle_button has an icon we - * don't want, but maybe look at refactoring later. but maybe we should also - * ditch the icon, not sure however since it's handy for checkboxes... + * + * Quite some code looks like toggle_button maybe we should inherit from that but let's test first. + * the problem is that the toggle_button has an icon we don't want, but maybe look at refactoring later. + * but maybe we should also ditch the icon, not sure however since it's handy for checkboxes... + * + * A toggle panel is an item which can hold multiple other items. + * The difference between a grid and a panel is that it's possible to define how a panel looks. + * A grid in an invisible container to just hold the items. + * The toggle panel is a combination of the panel and a toggle button, it allows a toggle button with its own grid. + * + * The resolution for a toggle panel also contains the following keys: + * Key |Type |Default|Description + * -------------|------------------------------------|-------|------------- + * top_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * bottom_border| @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * left_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * right_border | @ref guivartype_unsigned "unsigned"|0 |The size which isn't used for the client area. + * The following states exist: + * * state_enabled - the button is enabled and not selected. + * * state_disabled - the button is disabled and not selected. + * * state_focussed - the mouse is over the button and not selected. + * * state_enabled_selected - the button is enabled and selected. + * * state_disabled_selected - the button is disabled and selected. + * * state_focussed_selected - the mouse is over the button and selected. + * Variables: + * Key |Type |Default |Description + * ---------------|--------------------------------|---------|----------- + * grid | @ref guivartype_grid "grid" |mandatory|Defines the grid with the widgets to place on the panel. + * return_value_id| @ref guivartype_string "string"|"" |The return value id. + * return_value | @ref guivartype_int "int" |0 |The return value. */ class toggle_panel : public panel, public selectable_item { diff --git a/src/gui/widgets/tree_view.cpp b/src/gui/widgets/tree_view.cpp index fd23aec0e1e4..fac040e7506e 100644 --- a/src/gui/widgets/tree_view.cpp +++ b/src/gui/widgets/tree_view.cpp @@ -267,31 +267,6 @@ tree_view_definition::tree_view_definition(const config& cfg) load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_tree_view - * - * == Tree view == - * - * @macro = tree_view_description - * - * The documentation is not written yet. - * - * The following states exist: - * * state_enabled, the listbox is enabled. - * * state_disabled, the listbox is disabled. - * @begin{parent}{name="gui/"} - * @begin{tag}{name="ree_view_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="generic/widget_definition/resolution"} - * @allow{link}{name="gui/window/resolution/grid"} - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @end{tag}{name="resolution"} - * @end{tag}{name="ree_view_definition"} - * @end{parent}{name="gui/"} - */ tree_view_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , grid(nullptr) @@ -308,59 +283,6 @@ tree_view_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{tree_view_description} - * - * A tree view is a styled_widget that holds several items of the same or - * different types. The items shown are called tree view nodes and when - * a node has children, these can be shown or hidden. Nodes that contain - * children need to provide a clickable button in order to fold or - * unfold the children. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_tree_view - * - * == Tree view == - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="tree_view"}{min=0}{max=-1}{super="generic/widget_instance"} - * @macro = tree_view_description - * - * List with the tree view specific variables: - * @begin{table}{config} - * vertical_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * horizontal_scrollbar_mode & scrollbar_mode & initial_auto & - * Determines whether or not to show the - * scrollbar. $ - * - * indentation_step_size & unsigned & 0 & - * The number of pixels every level of - * nodes is indented from the previous - * level. $ - * - * node & section & & The tree view can contain multiple node - * sections. This part needs more - * documentation. $ - * @end{table} - * @begin{tag}{name="node"}{min=0}{max=-1} - * @begin{table}{config} - * id & string & "" & $ - * @end{table} - * @begin{tag}{name="node_definition"}{min=0}{max=-1}{super="gui/window/resolution/grid"} - * @begin{table}{config} - * return_value_id & string & "" & $ - * @end{table} - * @end{tag}{name="node_definition"} - * @end{tag}{name="node"} - * @end{tag}{name="tree_view"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - * NOTE more documentation and examples are needed. - */ // TODO annotate node - namespace implementation { builder_tree_view::builder_tree_view(const config& cfg) diff --git a/src/gui/widgets/tree_view.hpp b/src/gui/widgets/tree_view.hpp index fee8f36629c2..a16cbead2d76 100644 --- a/src/gui/widgets/tree_view.hpp +++ b/src/gui/widgets/tree_view.hpp @@ -36,6 +36,26 @@ namespace implementation { class tree_view_node; +/** + * @ingroup GUIWidgetWML + * + * A tree view is a control that holds several items of the same or different types. + * The items shown are called tree view nodes and when a node has children, these can be shown or hidden. + * Nodes that contain children need to provide a clickable button in order to fold or unfold the children. + * + * The following states exist: + * * state_enabled - the listbox is enabled. + * * state_disabled - the listbox is disabled. + * List with the tree view specific variables: + * Key |Type |Default |Description + * -------------------------|------------------------------------------------|------------|------------- + * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar. + * indention_step_size | @ref guivartype_unsigned "unsigned" |0 |The number of pixels every level of nodes is indented from the previous level. + * node | @ref guivartype_unsigned "unsigned" |mandatory |The tree view can contain multiple node sections. This part needs more documentation. + * id | @ref guivartype_unsigned "unsigned" |"" |. + * return_value_id | @ref guivartype_unsigned "unsigned" |"" |. + */ class tree_view : public scrollbar_container { friend struct implementation::builder_tree_view; diff --git a/src/gui/widgets/vertical_scrollbar.cpp b/src/gui/widgets/vertical_scrollbar.cpp index a09ec294d5b0..921e9d1078f8 100644 --- a/src/gui/widgets/vertical_scrollbar.cpp +++ b/src/gui/widgets/vertical_scrollbar.cpp @@ -105,54 +105,6 @@ vertical_scrollbar_definition::vertical_scrollbar_definition( load_resolutions(cfg); } -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_vertical_scrollbar - * - * == Vertical scrollbar == - * - * The definition of a vertical scrollbar. This class is most of the time not - * used directly. Instead it's used to build other items with scrollbars. - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="vertical_scrollbar_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * The resolution for a vertical scrollbar also contains the following keys: - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super=generic/widget_definition/resolution} - * @begin{table}{config} - * minimum_positioner_length & unsigned & & - * The minimum size the positioner is - * allowed to be. The engine needs to know - * this in order to calculate the best size - * for the positioner. $ - * maximum_positioner_length & unsigned & 0 & - * The maximum size the positioner is - * allowed to be. If minimum and maximum are - * the same value the positioner is fixed - * size. If the maximum is 0 (and the - * minimum not) there's no maximum. $ - * top_offset & unsigned & 0 & The number of pixels at the top which - * can't be used by the positioner. $ - * bottom_offset & unsigned & 0 & The number of pixels at the bottom which - * can't be used by the positioner. $ - * @end{table} - * The following states exist: - * * state_enabled, the vertical scrollbar is enabled. - * * state_disabled, the vertical scrollbar is disabled. - * * state_pressed, the left mouse button is down on the positioner of the - * vertical scrollbar. - * * state_focused, the mouse is over the positioner of the vertical scrollbar. - * @begin{tag}{name="state_enabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_enabled"} - * @begin{tag}{name="state_disabled"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_disabled"} - * @begin{tag}{name="state_pressed"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_pressed"} - * @begin{tag}{name="state_focused"}{min=0}{max=1}{super="generic/state"} - * @end{tag}{name="state_focused"} - * @end{tag}{name="resolution"} - * @end{tag}{name="vertical_scrollbar_definition"} - * @end{parent}{name="gui/"} - */ vertical_scrollbar_definition::resolution::resolution(const config& cfg) : resolution_definition(cfg) , minimum_positioner_length(cfg["minimum_positioner_length"]) @@ -173,19 +125,6 @@ vertical_scrollbar_definition::resolution::resolution(const config& cfg) // }---------- BUILDER -----------{ -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_vertical_scrollbar - * - * == Vertical scrollbar == - * - * - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="vertical_scrollbar"}{min=0}{max=1}{super="generic/widget_instance"} - * @end{tag}{name="vertical_scrollbar"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/vertical_scrollbar.hpp b/src/gui/widgets/vertical_scrollbar.hpp index 698d7479e270..79fb67da5d8c 100644 --- a/src/gui/widgets/vertical_scrollbar.hpp +++ b/src/gui/widgets/vertical_scrollbar.hpp @@ -25,7 +25,26 @@ struct builder_vertical_scrollbar; // ------------ WIDGET -----------{ -/** A vertical scrollbar. */ +/** + * @ingroup GUIWidgetWML + * + * The definition of a vertical scrollbar. + * This class is most of the time not used directly. + * Instead it's used to build other items with scrollbars. + * + * The resolution for a vertical scrollbar also contains the following keys: + * Key |Type |Default |Description + * -------------------------|------------------------------------|---------|------------- + * minimum_positioner_length| @ref guivartype_unsigned "unsigned"|mandatory|The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner. + * maximum_positioner_length| @ref guivartype_unsigned "unsigned"|0 |The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum. + * top_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the top which can't be used by the positioner. + * bottom_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the bottom which can't be used by the positioner. + * The following states exist: + * * state_enabled - the vertical scrollbar is enabled. + * * state_disabled - the vertical scrollbar is disabled. + * * state_pressed - the left mouse button is down on the positioner of the vertical scrollbar. + * * state_focussed - the mouse is over the positioner of the vertical scrollbar. + */ class vertical_scrollbar : public scrollbar_base { friend struct implementation::builder_vertical_scrollbar; diff --git a/src/gui/widgets/viewport.cpp b/src/gui/widgets/viewport.cpp index 44ebfb50108a..2ddc1124b7a6 100644 --- a/src/gui/widgets/viewport.cpp +++ b/src/gui/widgets/viewport.cpp @@ -183,33 +183,6 @@ iteration::walker_base* viewport::create_walker() // }---------- BUILDER -----------{ -/*WIKI_MACRO - * @begin{macro}{viewport_description} - * - * A viewport is an special widget used to view only a part of the - * widget it `holds'. - * @end{macro} - */ - -/*WIKI - * @page = GUIWidgetInstanceWML - * @order = 2_viewport - * @begin{parent}{name="gui/window/resolution/grid/row/column/"} - * @begin{tag}{name="viewport"}{min=0}{max=-1}{super="generic/widget_instance"} - * @begin{tag}{name="widget"}{min="1"}{max="1"}{super="gui/window/resolution/grid/row/column"} - * == Label == - * - * @macro = viewport_description - * - * List with the label specific variables: - * @begin{table}{config} - * widget & section & & Holds a single widget like a grid cell.$ - * @end{table} - * @end{tag}{name="widget"} - * @end{tag}{name="viewport"} - * @end{parent}{name="gui/window/resolution/grid/row/column/"} - */ - namespace implementation { diff --git a/src/gui/widgets/viewport.hpp b/src/gui/widgets/viewport.hpp index 72dba291e0de..31fa5c2693cb 100644 --- a/src/gui/widgets/viewport.hpp +++ b/src/gui/widgets/viewport.hpp @@ -29,6 +29,18 @@ struct builder_viewport; class grid; +/** + * @ingroup GUIWidgetWML + * + * A viewport is an special widget used to view only a part of the widget it 'holds'. + * + * List with the viewport specific variables: + * Key |Type |Default |Description + * ---------------|------------------------------------------------|---------|----------- + * grow_direction | @ref guivartype_grow_direction "grow_direction"|mandatory|The direction in which new items grow. + * parallel_items | @ref guivartype_unsigned "unsigned" |mandatory|The number of items that are growing in parallel. + * item_definition| @ref guivartype_section "section" |mandatory|The definition of a new item. + */ class viewport : public widget { friend struct viewport_implementation; diff --git a/src/gui/widgets/window.cpp b/src/gui/widgets/window.cpp index a556d79fc5b7..dff766283654 100644 --- a/src/gui/widgets/window.cpp +++ b/src/gui/widgets/window.cpp @@ -428,15 +428,6 @@ window* window::window_instance(const unsigned handle) return manager::instance().get_window(handle); } -/*WIKI - * @page = GUIToolkitWML - * @order = 3_widget_window_2 - * - * List if the id's that have generate a return value: - * * ok confirms the dialog. - * * cancel cancels the dialog. - * - */ retval window::get_retval_by_id(const std::string& id) { // Note it might change to a map later depending on the number @@ -1449,25 +1440,6 @@ void window::signal_handler_close_window() // }---------- DEFINITION ---------{ -/*WIKI - * @page = GUIWidgetDefinitionWML - * @order = 1_window - * - * == Window == - * - * The definition of a window. A window is a kind of panel see the panel for - * which fields exist - * - * @begin{parent}{name="gui/"} - * @begin{tag}{name="window_definition"}{min=0}{max=-1}{super="generic/widget_definition"} - * @begin{tag}{name="resolution"}{min=0}{max=-1}{super="gui/panel_definition/resolution"} - * @allow{link}{name="gui/window/resolution/grid"} - * @allow{link}{name="gui/panel_definition/resolution/background"} - * @allow{link}{name="gui/panel_definition/resolution/foreground"} - * @end{tag}{name="resolution"} - * @end{tag}{name="window_definition"} - * @end{parent}{name="gui/"} - */ window_definition::window_definition(const config& cfg) : styled_widget_definition(cfg) { diff --git a/src/gui/widgets/window.hpp b/src/gui/widgets/window.hpp index 1e795520fb0f..e0a30374e73f 100644 --- a/src/gui/widgets/window.hpp +++ b/src/gui/widgets/window.hpp @@ -56,8 +56,10 @@ class distributor; } // namespace event /** - * base class of top level items, the only item - * which needs to store the final canvases to draw on + * @ingroup GUIWidgetWML + * + * base class of top level items, the only item which needs to store the final canvases to draw on. + * A window is a kind of panel see the panel for which fields exist. */ class window : public panel { diff --git a/src/serialization/schema/tag.cpp b/src/serialization/schema/tag.cpp index cf727a4df0a8..de8fc1f53d56 100644 --- a/src/serialization/schema/tag.cpp +++ b/src/serialization/schema/tag.cpp @@ -267,31 +267,6 @@ void wml_tag::remove_keys_by_type(const std::string& type) } } -/*WIKI - * @begin{parent}{name="wml_schema/"} - * @begin{tag}{name="tag"}{min=0}{max=1} - * @begin{table}{config} - * name & string & & The name of tag. $ - * min & int & & The min number of occurrences. $ - * max & int & & The max number of occurrences. $ - * super & string & "" & The super-tag of this tag $ - * @end{table} - * @begin{tag}{name="link"}{min=0}{max=-1} - * @begin{table}{config} - * name & string & & The name of link. $ - * @end{table} - * @end{tag}{name="link"} - * @begin{tag}{name="tag"}{min=0}{max=-1}{super="wml_schema/tag"} - * @end{tag}{name="tag"} - * @end{tag}{name="tag"} - * @begin{tag}{name="type"}{min=0}{max=-1} - * @begin{table}{config} - * name & string & & The name of type. $ - * value & string & & The value of the type, regex. $ - * @end{table} - * @end{tag}{name="type"} - * @end{parent}{name="wml_schema/"} - */ void wml_tag::printl(std::ostream& os, int level, int step) { std::string s; diff --git a/src/serialization/schema/type.cpp b/src/serialization/schema/type.cpp index bd170c748de9..6db29db76806 100644 --- a/src/serialization/schema/type.cpp +++ b/src/serialization/schema/type.cpp @@ -25,18 +25,6 @@ namespace schema_validation { -/*WIKI - * @begin{parent}{name="wml_schema/tag/"} - * @begin{tag}{name="key"}{min=0}{max=-1} - * @begin{table}{config} - * name & string & & The name of key. $ - * type & string & & The type of key value. $ - * default & string & & The default value of the key. $ - * mandatory & string & & Shows if key is mandatory $ - * @end{table} - * @end{tag}{name="key"} - * @end{parent}{name="wml_schema/tag/"} - */ std::shared_ptr wml_type::from_config(const config& cfg) { utils::optional composite_range; diff --git a/src/wesnoth.cpp b/src/wesnoth.cpp index fdc15d76585a..2c3c3bc2f752 100644 --- a/src/wesnoth.cpp +++ b/src/wesnoth.cpp @@ -1120,3 +1120,326 @@ int main(int argc, char** argv) return 0; } // end main + +/** + * @page GUIToolkitWML GUIToolkitWML + * @tableofcontents + * + * @section State State + * + * A state contains the info what to do in a state. At the moment this is rather focussed on the drawing part, might change later. Keys: + * Key |Type |Default |Description + * -----------------|------------------------------------|---------|------------- + * draw | @ref guivartype_section "section" |mandatory|Section with drawing directions for a canvas. + * + * @section WindowDefinition Window Definition + * + * A window defines how a window looks in the game. + * Key |Type |Default |Description + * -----------------|------------------------------------|---------|------------- + * id | @ref guivartype_string "string" |mandatory|Unique id for this window. + * description | @ref guivartype_t_string "t_string"|mandatory|Unique translatable name for this window. + * resolution | @ref guivartype_section "section" |mandatory|The definitions of the window in various resolutions. + * + * @section Cell Cell + * + * Every grid cell has some cell configuration values and one widget in the grid cell. + * Here we describe the what is available more information about the usage can be found at @ref GUILayout. + * + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * id | @ref guivartype_string "string" |"" |A grid is a widget and can have an id. This isn't used that often, but is allowed. + * linked_group | @ref guivartype_string "string" |0 |. + * + * @section RowValues Row Values + * + * For every row the following variables are available: + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * grow_factor | @ref guivartype_unsigned "unsigned" |0 |The grow factor for a row. + * + * @section CellValues Cell Values + * + * For every column the following variables are available: + * Key |Type |Default |Description + * --------------------|----------------------------------------|---------|------------- + * grow_factor | @ref guivartype_unsigned "unsigned" |0 |The grow factor for a column, this value is only read for the first row. + * border_size | @ref guivartype_unsigned "unsigned" |0 |The border size for this grid cell. + * border | @ref guivartype_border "border" |"" |Where to place the border in this grid cell. + * vertical_alignment | @ref guivartype_v_align "v_align" |"" |The vertical alignment of the widget in the grid cell. (This value is ignored if vertical_grow is true.) + * horizontal_alignment| @ref guivartype_h_align "h_align" |"" |The horizontal alignment of the widget in the grid cell.(This value is ignored if horizontal_grow is true.) + * vertical_grow | @ref guivartype_bool "bool" |false |Does the widget grow in vertical direction when the grid cell grows in the vertical direction. This is used if the grid cell is wider as the best width for the widget. + * horizontal_grow | @ref guivartype_bool "bool" |false |Does the widget grow in horizontal direction when the grid cell grows in the horizontal direction. This is used if the grid cell is higher as the best width for the widget. + */ + +/** + * @page GUILayout GUILayout + * @tableofcontents + * + * @section Abstract Abstract + * + * In the widget library the placement and sizes of elements is determined by + * a grid. Therefore most widgets have no fixed size. + * + * @section Theory Theory + * + * We have two examples for the addon dialog, the first example the lower + * buttons are in one grid, that means if the remove button gets wider + * (due to translations) the connect button (4.1 - 2.2) will be aligned + * to the left of the remove button. In the second example the connect + * button will be partial underneath the remove button. + * + * A grid exists of x rows and y columns for all rows the number of columns + * needs to be the same, there is no column (nor row) span. If spanning is + * required place a nested grid to do so. In the examples every row has 1 column + * but rows 3, 4 (and in the second 5) have a nested grid to add more elements + * per row. + * + * In the grid every cell needs to have a widget, if no widget is wanted place + * the special widget @a spacer. This is a non-visible item which normally + * shouldn't have a size. It is possible to give a spacer a size as well but + * that is discussed elsewhere. + * + * Every row and column has a @a grow_factor, since all columns in a grid are + * aligned only the columns in the first row need to define their grow factor. + * The grow factor is used to determine with the extra size available in a + * dialog. The algorithm determines the extra size work like this: + * + * * determine the extra size + * * determine the sum of the grow factors + * * if this sum is 0 set the grow factor for every item to 1 and sum to sum of items. + * * divide the extra size with the sum of grow factors + * * for every item multiply the grow factor with the division value + * + * eg: + * * extra size 100 + * * grow factors 1, 1, 2, 1 + * * sum 5 + * * division 100 / 5 = 20 + * * extra sizes 20, 20, 40, 20 + * + * Since we force the factors to 1 if all zero it's not possible to have non + * growing cells. This can be solved by adding an extra cell with a spacer and a + * grow factor of 1. This is used for the buttons in the examples. + * + * Every cell has a @a border_size and @a border the @a border_size is the + * number of pixels in the cell which aren't available for the widget. This is + * used to make sure the items in different cells aren't put side to side. With + * @a border it can be determined which sides get the border. So a border is + * either 0 or @a border_size. + * + * If the widget doesn't grow when there's more space available the alignment + * determines where in the cell the widget is placed. + * + * @subsection AbstractExample Abstract Example + * + * |---------------------------------------| + * | 1.1 | + * |---------------------------------------| + * | 2.1 | + * |---------------------------------------| + * | |-----------------------------------| | + * | | 3.1 - 1.1 | 3.1 - 1.2 | | + * | |-----------------------------------| | + * |---------------------------------------| + * | |-----------------------------------| | + * | | 4.1 - 1.1 | 4.1 - 1.2 | 4.1 - 1.3 | | + * | |-----------------------------------| | + * | | 4.1 - 2.1 | 4.1 - 2.2 | 4.1 - 2.3 | | + * | |-----------------------------------| | + * |---------------------------------------| + * + * + * 1.1 label : title + * 2.1 label : description + * 3.1 - 1.1 label : server + * 3.1 - 1.2 text box : server to connect to + * 4.1 - 1.1 spacer + * 4.1 - 1.2 spacer + * 4.1 - 1.3 button : remove addon + * 4.1 - 2.1 spacer + * 4.1 - 2.2 button : connect + * 4.1 - 2.3 button : cancel + * + * + * |---------------------------------------| + * | 1.1 | + * |---------------------------------------| + * | 2.1 | + * |---------------------------------------| + * | |-----------------------------------| | + * | | 3.1 - 1.1 | 3.1 - 1.2 | | + * | |-----------------------------------| | + * |---------------------------------------| + * | |-----------------------------------| | + * | | 4.1 - 1.1 | 4.1 - 1.2 | | + * | |-----------------------------------| | + * |---------------------------------------| + * | |-----------------------------------| | + * | | 5.1 - 1.1 | 5.1 - 1.2 | 5.1 - 2.3 | | + * | |-----------------------------------| | + * |---------------------------------------| + * + * + * 1.1 label : title + * 2.1 label : description + * 3.1 - 1.1 label : server + * 3.1 - 1.2 text box : server to connect to + * 4.1 - 1.1 spacer + * 4.1 - 1.2 button : remove addon + * 5.1 - 1.1 spacer + * 5.1 - 1.2 button : connect + * 5.1 - 1.3 button : cancel + * + * @subsection ConcreteExample Concrete Example + * + * This is the code needed to create the skeleton for the structure the extra + * flags are omitted. + * + * [grid] + * [row] + * [column] + * [label] + * # 1.1 + * [/label] + * [/column] + * [/row] + * [row] + * [column] + * [label] + * # 2.1 + * [/label] + * [/column] + * [/row] + * [row] + * [column] + * [grid] + * [row] + * [column] + * [label] + * # 3.1 - 1.1 + * [/label] + * [/column] + * [column] + * [text_box] + * # 3.1 - 1.2 + * [/text_box] + * [/column] + * [/row] + * [/grid] + * [/column] + * [/row] + * [row] + * [column] + * [grid] + * [row] + * [column] + * [spacer] + * # 4.1 - 1.1 + * [/spacer] + * [/column] + * [column] + * [spacer] + * # 4.1 - 1.2 + * [/spacer] + * [/column] + * [column] + * [button] + * # 4.1 - 1.3 + * [/button] + * [/column] + * [/row] + * [row] + * [column] + * [spacer] + * # 4.1 - 2.1 + * [/spacer] + * [/column] + * [column] + * [button] + * # 4.1 - 2.2 + * [/button] + * [/column] + * [column] + * [button] + * # 4.1 - 2.3 + * [/button] + * [/column] + * [/row] + * [/grid] + * [/column] + * [/row] + * [/grid] + */ + +/** + * @defgroup GUIWidgetWML GUIWidgetWML + * In various parts of the GUI there are several variables types in use. This section describes them. + * + * Below are the simple types which have one value or a short list of options: + * Variable |description + * ------------------------------------------------|----------- + * @anchor guivartype_unsigned unsigned |Unsigned number (positive whole numbers and zero). + * @anchor guivartype_f_unsigned f_unsigned |Unsigned number or formula returning an unsigned number. + * @anchor guivartype_int int |Signed number (whole numbers). + * @anchor guivartype_f_int f_int |Signed number or formula returning an signed number. + * @anchor guivartype_bool bool |A boolean value accepts the normal values as the rest of the game. + * @anchor guivartype_f_bool f_bool |Boolean value or a formula returning a boolean value. + * @anchor guivartype_string string |A text. + * @anchor guivartype_t_string t_string |A translatable string. + * @anchor guivartype_f_tstring f_tstring |Formula returning a translatable string. + * @anchor guivartype_function function |A string containing a set of function definition for the formula language. + * @anchor guivartype_color color |A string which contains the color, this a group of 4 numbers between 0 and 255 separated by a comma. The numbers are red component, green component, blue component and alpha. A color of 0 is not available. An alpha of 255 is fully transparent. Omitted values are set to 0. + * @anchor guivartype_font_style font_style |A string which contains the style of the font:
  • normal
  • bold
  • italic
  • underlined
Since SDL has problems combining these styles only one can be picked. Once SDL will allow multiple options, this type will be transformed to a comma separated list. If empty we default to the normal style. Since the render engine is replaced by Pango markup this field will change later on. Note widgets that allow marked up text can use markup to change the font style. + * @anchor guivartype_v_align v_align |Vertical alignment; how an item is aligned vertically in the available space. Possible values:
  • top
  • bottom
  • center
When nothing is set or an another value as in the list the item is centered. + * @anchor guivartype_h_align h_align |Horizontal alignment; how an item is aligned horizontal in the available space. Possible values:
  • left
  • right
  • center
+ * @anchor guivartype_f_h_align f_h_align |A horizontal alignment or a formula returning a horizontal alignment. + * @anchor guivartype_border border |Comma separated list of borders to use. Possible values:
  • left
  • right
  • top
  • bottom
  • all alias for "left, right, top, bottom"
+ * @anchor guivartype_scrollbar_mode scrollbar_mode|How to show the scrollbar of a widget. Possible values:
  • always - The scrollbar is always shown, regardless whether it's required or not.
  • never - The scrollbar is never shown, even not when needed. (Note when setting this mode dialogs might not properly fit anymore).
  • auto - Shows the scrollbar when needed. The widget will reserve space for the scrollbar, but only show when needed.
  • initial_auto - Like auto, but when the scrollbar is not needed the space is not reserved.
Use auto when the list can be changed dynamically eg the game list in the lobby. For optimization you can also use auto when you really expect a scrollbar, but don't want it to be shown when not needed eg the language list will need a scrollbar on most screens. + * @anchor guivartype_resize_mode resize_mode |Determines how an image is resized. Possible values:
  • scale - The image is scaled.
  • stretch - The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
  • tile - The image is placed several times until the entire surface is filled. The last images are truncated.
+ * @anchor guivartype_grow_direction grow_direction|Determines how an image is resized. Possible values:
  • scale - The image is scaled.
  • stretch - The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
  • tile - The image is placed several times until the entire surface is filled. The last images are truncated.
+ * + * For more complex parts, there are sections. Sections contain of several lines of WML and can have sub sections. For example a grid has sub sections which contain various widgets. Here's the list of sections: + * Variable |description + * ------------------------------------------------|----------- + * @anchor guivartype_section section |A generic section. The documentation about the section should describe the section in further detail. + * @anchor guivartype_grid grid |A grid contains several widgets. + * @anchor guivartype_config config |. + * + * Every widget has some parts in common. First of all, every definition has the following fields: + * Key |Type |Default |Description + * -------------|------------------------------------|---------|----------- + * id | @ref guivartype_string "string" |mandatory|Unique id for this gui (theme). + * description | @ref guivartype_t_string "t_string"|mandatory|Unique translatable name for this gui. + * resolution | @ref guivartype_section "section" |mandatory|The definitions of the widget in various resolutions. + * Inside a grid (which is inside all container widgets) a widget is instantiated. With this instantiation some more variables of a widget can be tuned. + */ + +/** + * @defgroup GUICanvasWML GUICanvasWML + * + * 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. + * + * @section PreCommit 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. + * + * @subsection Blur 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 | @ref guivartype_unsigned "unsigned"|0 |The depth to blur. + */ + +/** + * @defgroup GUIWindowDefinitionWML GUIWindowDefinitionWML + * + * The window definition define how the windows shown in the dialog look. + */ \ No newline at end of file diff --git a/src/widgets/button.hpp b/src/widgets/button.hpp index 5684dd315de0..e1c9b103955a 100644 --- a/src/widgets/button.hpp +++ b/src/widgets/button.hpp @@ -21,6 +21,31 @@ namespace gui { +/** + * @ingroup GUIWidgetWML + * + * A button is a control that can be pushed to start an action or close a dialog. + * + * When a button has a return value it sets the return value for the window. + * Normally this closes the window and returns this value to the caller. + * The return value can either be defined by the user or determined from the id of the button. + * The return value has a higher precedence as the one defined by the id. + * (Of course it's weird to give a button an id and then override its return value.) + * + * When the button doesn't have a standard id, but you still want to use the return value of that id, use return_value_id instead. + * This has a higher precedence as return_value. + * + * List with the button specific variables: + * Key |Type |Default|Description + * ---------------|--------------------------------|-------|----------- + * return_value_id| @ref guivartype_string "string"|"" |The return value id. + * return_value | @ref guivartype_int "int" |0 |The return value. + * The following states exist: + * * state_enabled - the button is enabled. + * * state_disabled - the button is disabled. + * * state_pressed - the left mouse button is down. + * * state_focussed - the mouse is over the button. + */ class button : public widget { public: diff --git a/utils/wiki_grabber.py b/utils/wiki_grabber.py deleted file mode 100755 index ee633b1bc360..000000000000 --- a/utils/wiki_grabber.py +++ /dev/null @@ -1,644 +0,0 @@ -#!/usr/bin/env python3 -# vim: tabstop=4: shiftwidth=4: expandtab: softtabstop=4: autoindent: - -""" - Copyright (C) 2007 - 2009 by Mark de Wever - Part of the Battle for Wesnoth Project https://www.wesnoth.org/ - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License. - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY. - - See the COPYING file for more details. - - -The wiki grabber is a tool to convert wiki comment formatting[1] into a text -page which can be used in the wiki. - -[1] https://wesnoth.org/wiki/Wiki_grabber -""" - -import operator -import os -import sys -import re -import argparse - -if __name__ == "__main__": - # setup and parse command line arguments - # The defaults are set to the values of the older hardcoded implementation. - parser = argparse.ArgumentParser(description='The wiki grabber is a tool' - + ' to convert wiki comment formatting into a text page which can' - + ' be used in the wiki. For more details, see' - + ' https://wesnoth.org/wiki/Wiki_grabber') - parser.add_argument('-s', '--src-dir', default='../src/gui', dest='src_dir', - help="the location of wesnoth's source code") - parser.add_argument('-o', '--output', default='/tmp/', dest='output_dir', - help='the output directory') - args = parser.parse_args() - - # contains all output generated: - # - key filename - # - value node list - # - # every node is a list with 2 items - # - first the sorting order - # - second the actual data - file_map = {} - - # contains all macros: - # - key macro name - # - value macro contents - macro_map = {} - - output_directory = args.output_dir - src_directory = args.src_dir - - if not os.path.isdir(output_directory): - raise IOError("'%s' isn't a directory." % output_directory) - if not os.path.isdir(src_directory): - raise IOError("'%s' isn't a directory." % src_directory) - - # current file being processed - current_file = "" - - # current block being processed - current_block = "" - - re_record_start = '^\s*' - # There must be whitespace between the field separator (&). - # However if there is an empty field eg '...foo & & bar...' - # The first field separator eats the whitespace before the second - # which would \s+ cause to fail. - # The solution is to make the whitespace optional and assert the - # character before the ampersand is whitespace. - re_field_separator = '\s*(?:(?<=\s))&\s+' - # Same issue as with the re_field_separator but then with '...foo & $' - re_record_end = '\s*(?:(?<=\s))\$$' - - re_variable = '([a-zA-Z]\w*)' - re_string = '(.+?)' - - def is_empty(res, data): - """ - This checks whether or not a table is empty and writes to stderr if it is. - It returns True if the table is empty, False otherwise. - """ - if not res: - sys.stderr.write("Empty container:\n%s\n" % data) - return True - return False - - def reindent(data): - """Converts the raw input to an easier to use format. - - Lines starting with 8 spaces are concatenated with the previous line. - The start of line ' *' are removed and if another space exists it's also - removed.""" - - # concatenate - data = re.sub(r'\n \*(?: ){8,}', " ", data) - - # strip - data = re.sub(" \*(?: |)", "", data) - - #annotation - data = re.sub(r'@(?:begin|end|allow|remove)\{(?:parent|tag|link|global|type|key)\}(?:\{.*\})', "", data) - return data - - def get_value(data, key): - """ - Extracts data from a key value pair, a key must start at the start of - a line. - """ - - res = re.compile("^" + key + " *= *(.*)$", re.M).search(data) - - if res is not None: - res = res.group(1) - - return res - - def process_header(data): - """Processes the header.""" - - page = get_value(data, "@page") - order = get_value(data, "@order") - if order is None: - # in Python 2, this was an int with value 10000 - # when compared to strings, ints were always lower - # in Python 3 such comparison raises an error - # for this reason, order is now an empty strings - # when compared with other strings, empty ones are always lower - order = "" - - return [page, order] - - def debug_dump(data, res): - """Show the data the regex retrieved from a match. - - data is the raw data the regex tried to match. - res is the result of the regex.findall. - """ - sys.stderr.write("data : %s" % data) - for i, val in res: - for j, sub_val in val: - sys.stderr.write("Line %s match %s: %s\n" % (i, j, sub_val)) - - def format(data): - """Formats the data for the wiki. - - Replaces the following: - - An end of line and its surrounding whitespace to a single space. - - @$ -> $ - - @& -> & - - @* -> \n* needed in a list. - - @- -> \n needed to add text after a list. - """ - data = re.sub(r'\s*\n\s*', ' ', data) - data = re.sub(r'@\$', '$', data) - data = re.sub(r'@&', '&', data) - data = re.sub(r'@\*', "\n*", data) - data = re.sub(r'@\-', "\n", data) - return data - - def create_config_table(data): - """Creates a table for data in a config table. - - A config table is a table with info about WML configuration key value pairs. - """ - - # matches a line like - # x1 & f_unsigned & 0 & The x coordinate of the - # startpoint. $ - # x1 & f_unsigned & & The x coordinate of the - # startpoint. $ - regex = re.compile("([A-Za-z]\w*) +& +([A-Za-z]\w*) +& +([^&]*?) *& +(.*) +\$") - res = regex.findall(data) - - regex = re_record_start - regex += re_variable # 0 variable id - regex += re_field_separator - regex += re_variable # 1 variable type - regex += re_field_separator - regex += '(.*?)' # 2 optional default value, if omitted mandatory field - regex += re_field_separator - regex += re_string # 3 description - regex += re_record_end - - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!key\n!type\n!default\n!description\n" - for i in res: - result += "|-\n" - result += "| %s\n" % i[0] - result += "| [[GUIVariable#%s|%s]]\n" % (i[1], i[1]) - if not i[2]: - result += "| mandatory\n" - else: - result += "| %s\n" % i[2] - result += "| %s\n" % format(i[3]) - result += "|}" - - return result - - def create_formula_table(data): - """Creates a table for data in a formula table. - - A formula table is a table with info about which function parameters - are available for processing in WML formulas. - """ - regex = re_record_start - regex += re_variable # 0 variable id - regex += re_field_separator - regex += re_variable # 1 variable type - regex += re_field_separator - regex += re_string # 2 description - regex += re_record_end - - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!Variable\n!type\n!description\n" - for i in res: - result += "|-\n" - result += "| %s\n" % i[0] - result += "| %s\n" % i[1] - result += "| %s\n" % format(i[2]) - result += "|}" - - return result - - def create_variable_types_table(data): - """Creates a table for the variable types.""" - - regex = re_record_start - regex += re_variable # 0 variable type - regex += re_field_separator - regex += re_string # 1 description - regex += re_record_end - - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!Variable\n!description\n" - for i in res: - result += "|-\n" - result += '| %s\n' % (i[0], i[0]) - result += "| %s\n" % format(i[1]) - result += "|}" - - return result - - def create_widget_overview_table(data): - """Creates a table for all available widgets.""" - - regex = re_record_start - regex += re_variable # widget type - regex += re_field_separator - regex += re_string # description - regex += re_record_end - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!Section\n!Description\n" - for i in res: - result += "|-\n" - result += '| ' % i[0].lower() - result += re.sub(r'_', ' ', i[0]) - result += "" - result += " ([[GUIWidgetDefinitionWML#%s|definition]]" % i[0] - result += ", [[GUIWidgetInstanceWML#%s|instantiation]])\n" % i[0] - result += "| %s\n" % format(i[1]) - result += "|}" - - return result - - def create_window_overview_table(data): - """Creates a table for all available windows.""" - - regex = re_record_start - regex += re_variable # 0 window id - regex += re_field_separator - regex += re_string # 1 description - regex += re_record_end - - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!Section\n!Description\n" - for i in res: - result += "|-\n" - result += "| " + re.sub(r'_', ' ', i[0]) - result += " ([[GUIWindowDefinitionWML#%s|definition]])\n" % i[0] - result += "| %s\n" % format(i[1]) - result += "|}" - - return result - - def create_dialog_widgets_table(data): - """Creates a table for the widgets in a dialog.""" - - regex = re_record_start - regex += '(-*)' # 0 indention markers - regex += '((?:[a-zA-Z_]?)\w*)' # 1 optional id may start with an underscore - regex += re_field_separator - regex += '(.*?)' # 2 optional retval - regex += re_field_separator - regex += re_variable # 3 type - regex += re_field_separator - regex += '([om])' # 4 mandatory flag - regex += re_field_separator - regex += re_string # 5 description - regex += re_record_end - - regex = re.compile(regex, re.DOTALL | re.MULTILINE) - res = regex.findall(data) - - if is_empty(res, data): - return "Empty table." - - result = '{| class="wikitable"' - result += "\n!ID (return value)\n!Type\n!Mandatory\n!Description\n" - for i in res: - result += "|-\n| " + " " * len(i[0]) * 8 - - if not i[1]: - result += "''free to choose''" - else: - result += i[1] - - if not i[2]: - result += "\n" - else: - result += " (%s)\n" % i[2] - - result += "| [[GUIToolkitWML#%s|%s]]\n" % (i[3], i[3]) - - if i[4] == 'm': - result += "| yes\n" - else: - result += "| no\n" - - result += "| %s\n" % format(i[5]) - - result += "|}" - - return result - - def validate_table(table): - """Validates a table. - - At the moments tests for whitespace around separators.""" - - regex = '((?