The Battle for Wesnoth  1.17.17+dev
window_builder.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2023
3  by Mark de Wever <koraq@xs4all.nl>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
20 #include "gui/widgets/grid.hpp"
21 #include "color.hpp"
23 
24 #include <functional>
25 
26 class config;
27 
28 namespace gui2
29 {
30 
31 class window;
32 
33 /** Contains the info needed to instantiate a widget. */
35 {
36  /**
37  * The replacements type is used to define replacement types.
38  *
39  * Certain widgets need to build a part of themselves upon instantiation
40  * but at the time of the definition it's not yet known what exactly. By
41  * using and `[instance]' widget this decision can be postponed until
42  * instantiation.
43  */
44  using replacements_map = std::map<std::string, std::shared_ptr<builder_widget>>;
45 
46  /**
47  * @todo: evaluate whether to combine the two @ref build() functions with this
48  * as the sole parameter.
49  */
51 
52  explicit builder_widget(const config& cfg);
53 
54  virtual ~builder_widget()
55  {
56  }
57 
58  virtual std::unique_ptr<widget> build() const = 0;
59 
60  virtual std::unique_ptr<widget> build(const replacements_map& replacements) const = 0;
61 
62  /** Parameters for the widget. */
63  std::string id;
64  std::string linked_group;
65 
68 };
69 
70 using builder_widget_ptr = std::shared_ptr<builder_widget>;
71 using builder_widget_const_ptr = std::shared_ptr<const builder_widget>;
72 
73 /**
74  * Create a widget builder.
75  *
76  * This object holds the instance builder for a single widget.
77  *
78  * @param cfg The config object holding the information
79  * regarding the widget instance.
80  *
81  * @returns The builder for the widget instance.
82  */
84 
85 /**
86  * Implementation detail for @ref build_single_widget_instance. Do not use directly!
87  *
88  * @param type String ID of the widget type.
89  * @param cfg Data config to pass to the widget's builder.
90  *
91  * @returns A shared_ptr of the base widget type containing
92  * the newly built widget.
93  */
94 std::unique_ptr<widget> build_single_widget_instance_helper(const std::string& type, const config& cfg);
95 
96 /**
97  * Builds a single widget instance of the given type with the specified attributes.
98  *
99  * This should be used in place of creating a widget object directly, as it
100  * allows the widget-specific builder code to be executed.
101  *
102  * This is equivalent to calling @c build() on the result of @ref create_widget_builder.
103  *
104  * @tparam T The final widget type. The widget pointer will be
105  * cast to this.
106  *
107  * @param cfg Data config to pass to the widget's builder.
108  *
109  * @returns A shared_ptr of the given type containing the
110  * newly build widget.
111  */
112 template<typename T>
113 std::unique_ptr<T> build_single_widget_instance(const config& cfg = {})
114 {
115  static_assert(std::is_base_of_v<widget, T>, "Type is not a widget type");
116  return std::unique_ptr<T>{ static_cast<T*>(build_single_widget_instance_helper(T::type(), cfg).release()) };
117 }
118 
120 {
121  explicit builder_grid(const config& cfg);
122 
123  unsigned rows;
124  unsigned cols;
125 
126  /** The grow factor for the rows / columns. */
127  std::vector<unsigned> row_grow_factor;
128  std::vector<unsigned> col_grow_factor;
129 
130  /** The flags per grid cell. */
131  std::vector<unsigned> flags;
132 
133  /** The border size per grid cell. */
134  std::vector<unsigned> border_size;
135 
136  /** The widgets per grid cell. */
137  std::vector<builder_widget_ptr> widgets;
138 
139  /** Inherited from @ref builder_widget. */
140  virtual std::unique_ptr<widget> build() const override;
141 
142  /** Inherited from @ref builder_widget. */
143  virtual std::unique_ptr<widget> build(const replacements_map& replacements) const override;
144 
145  void build(grid& grid, optional_replacements replacements = std::nullopt) const;
146 };
147 
148 using builder_grid_ptr = std::shared_ptr<builder_grid>;
149 using builder_grid_const_ptr = std::shared_ptr<const builder_grid>;
150 using builder_grid_map = std::map<std::string, builder_grid_const_ptr>;
151 
153 {
154 public:
155  explicit builder_window(const config& cfg)
156  : resolutions()
157  , id_(cfg["id"])
158  , description_(cfg["description"])
159  {
160  read(cfg);
161  }
162 
163  /**
164  * Key |Type |Default |Description
165  * --------------------|----------------------------------------|---------|-------------
166  * window_width | @ref guivartype_unsigned "unsigned" |0 |Width of the application window.
167  * window_height | @ref guivartype_unsigned "unsigned" |0 |Height of the application window.
168  * 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.
169  * x | @ref guivartype_f_unsigned "f_unsigned"|0 |X coordinate of the window to show.
170  * y | @ref guivartype_f_unsigned "f_unsigned"|0 |Y coordinate of the window to show.
171  * width | @ref guivartype_f_unsigned "f_unsigned"|0 |Width of the window to show.
172  * height | @ref guivartype_f_unsigned "f_unsigned"|0 |Height of the window to show.
173  * reevaluate_best_size| @ref guivartype_f_bool "f_bool" |false |The foo
174  * functions | @ref guivartype_function "function" |"" |The function definitions s available for the formula fields in window.
175  * vertical_placement | @ref guivartype_v_align "v_align" |"" |The vertical placement of the window.
176  * horizontal_placement| @ref guivartype_h_align "h_align" |"" |The horizontal placement of the window.
177  * maximum_width | @ref guivartype_unsigned "unsigned" |0 |The maximum width of the window (only used for automatic placement).
178  * maximum_height | @ref guivartype_unsigned "unsigned" |0 |The maximum height of the window (only used for automatic placement).
179  * 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).
180  * definition | @ref guivartype_string "string" |"default"|Definition of the window which we want to show.
181  * linked_group | sections |[] |A group of linked widget sections.
182  * tooltip | @ref guivartype_section "section" |mandatory|Information regarding the tooltip for this window.
183  * helptip | @ref guivartype_section "section" |mandatory|Information regarding the helptip for this window.
184  * grid | @ref guivartype_grid "grid" |mandatory|The grid with the widgets to show.
185  *
186  * A linked_group section has the following fields and needs to have at least one size fixed:
187  * Key |Type |Default |Description
188  * --------------------|----------------------------------------|---------|-------------
189  * id | @ref guivartype_string "string" |mandatory|The unique id of the group (unique in this window).
190  * fixed_width | @ref guivartype_bool "bool" |false |Should widget in this group have the same width.
191  * fixed_height | @ref guivartype_bool "bool" |false |Should widget in this group have the same height.
192  *
193  * A tooltip and helptip section have the following field; more fields will probably be added later on:
194  * Key |Type |Default |Description
195  * --------------------|----------------------------------------|---------|-------------
196  * id | @ref guivartype_string "string" |mandatory|The id of the tip to show.
197  */
199  {
200  explicit window_resolution(const config& cfg);
201 
202  unsigned window_width;
203  unsigned window_height;
204 
206 
212 
214 
217 
220 
222 
223  std::string definition;
224 
225  std::vector<linked_group_definition> linked_groups;
226 
227  /** Helper struct to store information about the tips. */
229  {
230  tooltip_info(const config& cfg, const std::string& tagname);
231 
232  std::string id;
233  };
234 
237 
239  };
240 
241  /**
242  * Resolution options for this window instance.
243  *
244  * The window widget handles resolution options differently from other widgets.
245  * Most specify their resolution options in their definitions. However, windows
246  * define different resolution options for each window *instance*. That enables
247  * each dialog to have its own set of options.
248  */
249  std::vector<window_resolution> resolutions;
250 
251 private:
252  void read(const config& cfg);
253 
254  std::string id_;
255  std::string description_;
256 };
257 
258 /**
259  * Builds a window.
260  *
261  * @param type The type id string of the window, this window
262  * must be registered at startup.
263  */
264 std::unique_ptr<window> build(const std::string& type);
265 
266 /**
267  * Builds a window.
268  */
269 std::unique_ptr<window> build(const builder_window::window_resolution& res);
270 
271 } // namespace gui2
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
builder_window(const config &cfg)
std::vector< window_resolution > resolutions
Resolution options for this window instance.
void read(const config &cfg)
Base container class.
Definition: grid.hpp:32
A simple wrapper class for optional reference types.
Generic file dialog.
std::shared_ptr< builder_grid > builder_grid_ptr
std::shared_ptr< builder_widget > builder_widget_ptr
std::unique_ptr< T > build_single_widget_instance(const config &cfg={})
Builds a single widget instance of the given type with the specified attributes.
std::unique_ptr< widget > build_single_widget_instance_helper(const std::string &type, const config &cfg)
Implementation detail for build_single_widget_instance.
builder_widget_ptr create_widget_builder(const config &cfg)
Create a widget builder.
std::unique_ptr< window > build(const builder_window::window_resolution &definition)
Builds a window.
std::map< std::string, builder_grid_const_ptr > builder_grid_map
std::shared_ptr< const builder_widget > builder_widget_const_ptr
std::shared_ptr< const builder_grid > builder_grid_const_ptr
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
std::vector< unsigned > col_grow_factor
std::vector< unsigned > flags
The flags per grid cell.
std::vector< builder_widget_ptr > widgets
The widgets per grid cell.
builder_grid(const config &cfg)
std::vector< unsigned > row_grow_factor
The grow factor for the rows / columns.
virtual std::unique_ptr< widget > build() const override
Inherited from builder_widget.
std::vector< unsigned > border_size
The border size per grid cell.
Contains the info needed to instantiate a widget.
virtual std::unique_ptr< widget > build(const replacements_map &replacements) const =0
widget::debug_border debug_border_mode
virtual std::unique_ptr< widget > build() const =0
builder_widget(const config &cfg)
std::string id
Parameters for the widget.
std::map< std::string, std::shared_ptr< builder_widget > > replacements_map
The replacements type is used to define replacement types.
Helper struct to store information about the tips.
tooltip_info(const config &cfg, const std::string &tagname)
std::vector< linked_group_definition > linked_groups
wfl::function_symbol_table functions
typed_formula< unsigned > maximum_height
typed_formula< unsigned > maximum_width