The Battle for Wesnoth  1.17.0-dev
multi_page.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2021
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 
19 
22 
23 namespace gui2
24 {
25 
26 // ------------ WIDGET -----------{
27 
28 namespace implementation
29 {
30 struct builder_multi_page;
31 }
32 
33 class generator_base;
34 
35 /**
36  * @ingroup GUIWidgetWML
37  *
38  * A multi page is a control that contains several 'pages' of which only one is visible.
39  * The pages can contain the same widgets containing the same 'kind' of data or look completely different.
40  * Key |Type |Default |Description
41  * -------------|----------------------------|---------|-----------
42  * grid | @ref guivartype_grid "grid"|mandatory|Defines the grid with the widgets to place on the page.
43  * A multipage has no states. List with the multi page specific variables:
44  * Key |Type |Default |Description
45  * ---------------|----------------------------------|---------|-----------
46  * 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.
47  * 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'.
48  */
49 class multi_page : public container_base
50 {
52  friend class debug_layout_graph;
53 
54 public:
55  explicit multi_page(const implementation::builder_multi_page& builder);
56 
57  /***** ***** ***** ***** Page handling. ***** ***** ****** *****/
58 
59  /**
60  * Adds single page to the grid.
61  *
62  * This function expect a page to one multiple widget.
63  *
64  * @param item The data to send to the set_members of the
65  * widget.
66  *
67  * @returns The grid of the newly added page.
68  */
69  grid& add_page(const string_map& item);
70 
71  /**
72  * Adds single page to the grid.
73  *
74  * This function expect a page to one multiple widget.
75  *
76  * @param item The data to send to the set_members of the
77  * widget.
78  *
79  * @param type the id of the [page_definition] that shoduol be used
80  *
81  * @param insert_pos the position where th new page is inserted, usually
82  * -1 for 'at end'
83  *
84  * @returns The grid of the newly added page.
85  */
86  grid& add_page(const std::string& type, int insert_pos, const string_map& item);
87 
88  /**
89  * Adds single page to the grid.
90  *
91  * This function expect a page to have multiple widgets (either multiple
92  * columns or one column with multiple widgets).
93  *
94  *
95  * @param data The data to send to the set_members of the
96  * widgets. If the member id is not an empty
97  * string it is only send to the widget that
98  * has the wanted id (if any). If the member
99  * id is an empty string, it is send to all
100  * members. Having both empty and non-empty
101  * id's gives undefined behavior.
102  *
103  * @returns The grid of the newly added page.
104  */
105  grid& add_page(const std::map<std::string /* widget id */, string_map>& data);
106 
107  /**
108  * Adds single page to the grid.
109  *
110  * This function expect a page to have multiple widgets (either multiple
111  * columns or one column with multiple widgets).
112  *
113  *
114  * @param data The data to send to the set_members of the
115  * widgets. If the member id is not an empty
116  * string it is only send to the widget that
117  * has the wanted id (if any). If the member
118  * id is an empty string, it is send to all
119  * members. Having both empty and non-empty
120  * id's gives undefined behavior.
121  *
122  * @param type the id of the [page_definition] that should be used
123  *
124  * @param insert_pos the position where th new page is inserted, usually
125  * -1 for 'at end'
126  *
127  * @returns The grid of the newly added page.
128  */
129  grid& add_page(const std::string& type, int insert_pos, const std::map<std::string /* widget id */, string_map>& data);
130 
131  /**
132  * Removes a page in the multi page.
133  *
134  * @param page The page to remove, when not in
135  * range the function is ignored.
136  * @param count The number of pages to remove, 0 means all
137  * pages (starting from page).
138  */
139  void remove_page(const unsigned page, unsigned count = 1);
140 
141  /** Removes all pages in the multi page, clearing it. */
142  void clear();
143 
144  /** Returns the number of pages. */
145  unsigned get_page_count() const;
146 
147  /**
148  * Selects a page.
149  *
150  * @param page The page to select.
151  * @param select Select or deselect the page.
152  */
153  void select_page(const unsigned page, const bool select = true);
154 
155  /**
156  * Returns the selected page.
157  *
158  * @returns The selected page.
159  * @retval -1 No page selected.
160  */
161  int get_selected_page() const;
162 
163  /**
164  * Returns the grid for the page.
165  *
166  * @param page The page to get the grid from, the caller
167  * has to make sure the page is a valid page.
168  *
169  * @returns The grid of the wanted page.
170  */
171  const grid& page_grid(const unsigned page) const;
172 
173  /**
174  * Returns the grid for the page.
175  *
176  * @param page The page to get the grid from, the caller
177  * has to make sure the page is a valid page.
178  *
179  * @returns The grid of the wanted page.
180  */
181  grid& page_grid(const unsigned page);
182 
183  /***** ***** ***** inherited ***** ****** *****/
184 
185  /** See @ref styled_widget::get_active. */
186  virtual bool get_active() const override;
187 
188  /** See @ref styled_widget::get_state. */
189  virtual unsigned get_state() const override;
190 
191 private:
192  /***** ***** ***** setters / getters for members ***** ****** *****/
193 
194  void set_page_builders(const std::map<std::string, builder_grid_const_ptr>& page_builders)
195  {
196  assert(!page_builders.empty());
197  page_builders_ = page_builders;
198  }
199 
200  /**
201  * Finishes the building initialization of the widget.
202  *
203  * @param page_data The initial data to fill the widget with.
204  */
205  void finalize(const std::vector<string_map>& page_data);
206 
207  /**
208  * Contains a pointer to the generator.
209  *
210  * The pointer is not owned by this class, it's stored in the content_grid_
211  * of the scrollbar_container super class and freed when it's grid is
212  * freed.
213  */
215 
216  /** Contains the builder for the new items. */
217  std::map<std::string, builder_grid_const_ptr> page_builders_;
218 
219  /** See @ref widget::impl_draw_background. */
220  virtual void impl_draw_background(surface& frame_buffer,
221  int x_offset,
222  int y_offset) override;
223 
224 public:
225  /** Static type getter that does not rely on the widget being constructed. */
226  static const std::string& type();
227 
228 private:
229  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
230  virtual const std::string& get_control_type() const override;
231 
232  /** See @ref container_base::set_self_active. */
233  virtual void set_self_active(const bool active) override;
234 };
235 
236 // }---------- DEFINITION ---------{
237 
239 {
240  explicit multi_page_definition(const config& cfg);
241 
243  {
244  explicit resolution(const config& cfg);
245 
247  };
248 };
249 
250 // }---------- BUILDER -----------{
251 
252 namespace implementation
253 {
254 
256 {
257  explicit builder_multi_page(const config& cfg);
258 
260 
261  virtual widget* build() const override;
262 
263  std::map<std::string, builder_grid_const_ptr> builders;
264 
265  /**
266  * Multi page data.
267  *
268  * Contains a vector with the data to set in every cell, it's used to
269  * serialize the data in the config, so the config is no longer required.
270  */
271  std::vector<std::map<std::string, t_string>> data;
272 };
273 
274 } // namespace implementation
275 
276 // }------------ END --------------
277 
278 } // namespace gui2
Base class of a resolution, contains the common keys for a resolution.
virtual widget * build() const =0
void set_page_builders(const std::map< std::string, builder_grid_const_ptr > &page_builders)
Definition: multi_page.hpp:194
Base class for all widgets.
Definition: widget.hpp:49
std::map< std::string, builder_grid_const_ptr > builders
Definition: multi_page.hpp:263
void clear(const std::string &key)
Definition: general.cpp:186
std::vector< std::map< std::string, t_string > > data
Multi page data.
Definition: multi_page.hpp:271
Generic file dialog.
Definition: field-fwd.hpp:23
Base container class.
Definition: grid.hpp:31
Abstract base class for the generator.
Definition: generator.hpp:38
generator_base * generator_
Contains a pointer to the generator.
Definition: multi_page.hpp:214
std::map< std::string, t_string > string_map
Definition: widget.hpp:26
A generic container base class.
A multi page is a control that contains several &#39;pages&#39; of which only one is visible.
Definition: multi_page.hpp:49
std::map< std::string, builder_grid_const_ptr > page_builders_
Contains the builder for the new items.
Definition: multi_page.hpp:217
point resolution()
Definition: general.cpp:393
std::unique_ptr< window > build(const builder_window::window_resolution &definition)
Builds a window.
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:61
std::shared_ptr< builder_grid > builder_grid_ptr
Contains the implementation details for lexical_cast and shouldn&#39;t be used directly.
std::pair< std::string, unsigned > item
Definition: help_impl.hpp:410