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