The Battle for Wesnoth  1.15.1+dev
generator.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 
17 #include "widget.hpp"
18 
19 #include <boost/dynamic_bitset.hpp>
20 
21 #include <array>
22 
23 namespace gui2
24 {
25 
26 struct builder_grid;
27 typedef std::shared_ptr<const builder_grid> builder_grid_const_ptr;
28 
29 class grid;
30 
31 /**
32  * Abstract base class for the generator.
33  *
34  * A generator is a class which holds multiple grids and controls their
35  * placement on the screen. The final class is policy based, more info about
36  * the possible policies is documented in the build() function. This function
37  * is the factory to generate the classes as well.
38  */
39 class generator_base : public widget
40 {
41  friend class debug_layout_graph;
42 
43 public:
44  virtual ~generator_base()
45  {
46  }
47 
48  /** Determines how the items are placed. */
49  enum placement {
54  };
55 
56  /**
57  * Create a new generator.
58  *
59  * @param has_minimum Does one item need to be selected.
60  * @param has_maximum Is one the maximum number of items that can
61  * be selected?
62  * @param placement The placement of the grids, see tplacement
63  * for more info.
64  * @param select If a grid is selected, what should happen?
65  * If true the grid is selected, if false the
66  * grid is shown.
67  *
68  * @returns A pointer to a new object. The caller gets
69  * ownership of the new object.
70  */
71  static generator_base* build(const bool has_minimum,
72  const bool has_maximum,
73  const placement placement,
74  const bool select);
75 
76  /**
77  * Deletes an item.
78  */
79  virtual void delete_item(const unsigned index) = 0;
80 
81  /** Deletes all items. */
82  virtual void clear() = 0;
83 
84  /**
85  * (De)selects an item.
86  *
87  * @param index The item to (de)select.
88  * @param select If true selects, if false deselects.
89  */
90  virtual void select_item(const unsigned index, const bool select) = 0;
91 
92  /**
93  * Toggles the selection state of an item.
94  *
95  * @param index The item to toggle.
96  */
97  void toggle_item(const unsigned index)
98  {
99  select_item(index, !is_selected(index));
100  }
101 
102  /** Returns whether the item is selected. */
103  virtual bool is_selected(const unsigned index) const = 0;
104 
105  /**
106  * Shows or hides an item.
107  *
108  * The caller is responsible for reformatting the grid.
109  *
110  * @param index The item to show or hide.
111  * @param show If true shows the item, else hides it.
112  */
113  virtual void set_item_shown(const unsigned index, const bool show) = 0;
114 
115  /** Returns whether the item is shown. */
116  virtual bool get_item_shown(const unsigned index) const = 0;
117 
118  /** Returns the visibility of all the items as a bit set. */
119  boost::dynamic_bitset<> get_items_shown() const
120  {
121  boost::dynamic_bitset<> items_shown(get_item_count());
122  for (unsigned int i = 0u; i < get_item_count(); ++i)
123  {
124  items_shown[i] = get_item_shown(i);
125  }
126  return items_shown;
127  }
128 
129  /** Returns the number of items. */
130  virtual unsigned get_item_count() const = 0;
131 
132  /** Returns the number of selected items. */
133  virtual unsigned get_selected_item_count() const = 0;
134 
135  /**
136  * Returns the selected item.
137  *
138  * If a list has multiple selected items it looks whether it knows the last
139  * item actually selected, if that item is selected that one is chosen.
140  * Else is goes through all selected items and returns the first one
141  * selected.
142  *
143  * @note stacked_widget depends on that behavior it always has all items
144  * selected and thus shown and by default the last selected item (the top
145  * one) is active.
146  *
147  * @returns The selected item, -1 if none selected.
148  */
149  virtual int get_selected_item() const = 0;
150 
151  /** Gets the grid of an item. */
152  virtual grid& item(const unsigned index) = 0;
153 
154  /** Gets the grid of an item. */
155  virtual const grid& item(const unsigned index) const = 0;
156 
157  /***** ***** ***** ***** Create items ***** ***** ***** *****/
158 
159  /**
160  * Creates a new item.
161  *
162  * The item_data is used for the first widget found, this normally should
163  * be used when there's one widget in an item.
164  *
165  * @param index The item before which to add the new item,
166  * 0 == begin, -1 == end.
167  * @param list_builder A grid builder that's will build the
168  * contents of the new item.
169  * @param item_data The data to initialize the parameters of
170  * the new item.
171  * @param callback The callback function to call when an item
172  * in the grid is (de)selected.
173  *
174  * @returns A reference to the newly created grid.
175  */
176  virtual grid& create_item(const int index,
177  builder_grid_const_ptr list_builder,
178  const string_map& item_data,
179  const std::function<void(widget&)>& callback)
180  = 0;
181 
182  /**
183  * Creates a new item.
184  *
185  * The item_data is used by id, and is meant to set multiple widgets in
186  * an item.
187  *
188  * @param index The item before which to add the new item,
189  * 0 == begin, -1 == end.
190  * @param list_builder A grid builder that's will build the
191  * contents of the new item.
192  * @param data The data to initialize the parameters of
193  * the new item.
194  * @param callback The callback function to call when an item
195  * in the grid is (de)selected.
196  *
197  * @returns A reference to the newly created grid.
198  */
199  virtual grid&
200  create_item(const int index,
201  builder_grid_const_ptr list_builder,
202  const std::map<std::string /* widget id */, string_map>& data,
203  const std::function<void(widget&)>& callback) = 0;
204 
205  /**
206  * Creates one or more new item(s).
207  *
208  * For every item in item_data a new item is generated. This version
209  * expects one widget per item.
210  *
211  * @param index The item before which to add the new item,
212  * 0 == begin, -1 == end.
213  * @param list_builder A grid builder that's will build the
214  * contents of the new item.
215  * @param data The data to initialize the parameters of
216  * the new item.
217  * @param callback The callback function to call when an item
218  * in the grid is (de)selected.
219  */
220  virtual void create_items(const int index,
221  builder_grid_const_ptr list_builder,
222  const std::vector<string_map>& data,
223  const std::function<void(widget&)>& callback)
224  = 0;
225 
226  /**
227  * Creates one or more new item(s).
228  *
229  * For every item in item_data a new item is generated. This version
230  * expects multiple widgets per item.
231  *
232  * @param index The item before which to add the new item,
233  * 0 == begin, -1 == end.
234  * @param list_builder A grid builder that's will build the
235  * contents of the new item.
236  * @param data The data to initialize the parameters of
237  * the new item.
238  * @param callback The callback function to call when an item
239  * in the grid is (de)selected.
240  */
241  virtual void create_items(
242  const int index,
243  builder_grid_const_ptr list_builder,
244  const std::vector<std::map<std::string /*widget id*/, string_map>>&
245  data,
246  const std::function<void(widget&)>& callback) = 0;
247 
248  typedef std::function<bool (unsigned, unsigned)> order_func;
249  virtual void set_order(const order_func& order) = 0;
250 
251  /***** ***** ***** ***** Inherited ***** ***** ***** *****/
252 
253  /*
254  * These functions must be defined in our child classes so make sure they
255  * become pure virtuals.
256  */
257 
258  /** See @ref widget::layout_initialize. */
259  virtual void layout_initialize(const bool full_initialization) override = 0;
260 
261  /** See @ref widget::request_reduce_width. */
262  virtual void request_reduce_width(const unsigned maximum_width) override
263  = 0;
264 
265  /** See @ref widget::request_reduce_height. */
266  virtual void request_reduce_height(const unsigned maximum_height) override
267  = 0;
268 
269  /** See @ref widget::calculate_best_size. */
270  virtual point calculate_best_size() const override = 0;
271 
272  /** See @ref widget::place. */
273  virtual void place(const point& origin, const point& size) override = 0;
274 
275  /** See @ref widget::set_origin. */
276  virtual void set_origin(const point& origin) override = 0;
277 
278  /** See @ref widget::set_visible_rectangle. */
279  virtual void set_visible_rectangle(const SDL_Rect& rectangle) override = 0;
280 
281  /** See @ref widget::impl_draw_children. */
282  virtual void impl_draw_children(surface& frame_buffer,
283  int x_offset,
284  int y_offset) override = 0;
285 
286 protected:
287  /** See @ref widget::child_populate_dirty_list. */
288  virtual void
290  const std::vector<widget*>& call_stack) override
291  = 0;
292 
293 public:
294  /** See @ref widget::find_at. */
295  virtual widget* find_at(const point& coordinate,
296  const bool must_be_active) override = 0;
297 
298  /** See @ref widget::find_at. */
299  virtual const widget* find_at(const point& coordinate,
300  const bool must_be_active) const override
301  = 0;
302 
303  /***** ***** ***** ***** keyboard functions ***** ***** ***** *****/
304 
305  /**
306  * Up arrow key pressed.
307  *
308  * @param modifier The SDL keyboard modifier when the key was
309  * pressed.
310  * @param handled If the function handles the key it should
311  * set handled to true else do not modify it.
312  * This is used in the keyboard event
313  * changing.
314  */
315  virtual void handle_key_up_arrow(SDL_Keymod modifier, bool& handled) = 0;
316 
317  /**
318  * Down arrow key pressed.
319  *
320  * @param modifier The SDL keyboard modifier when the key was
321  * pressed.
322  * @param handled If the function handles the key it should
323  * set handled to true else do not modify it.
324  * This is used in the keyboard event
325  * changing.
326  */
327  virtual void handle_key_down_arrow(SDL_Keymod modifier, bool& handled) = 0;
328 
329  /**
330  * Left arrow key pressed.
331  *
332  * @param modifier The SDL keyboard modifier when the key was
333  * pressed.
334  * @param handled If the function handles the key it should
335  * set handled to true else do not modify it.
336  * This is used in the keyboard event
337  * changing.
338  */
339  virtual void handle_key_left_arrow(SDL_Keymod modifier, bool& handled) = 0;
340 
341  /**
342  * Right arrow key pressed.
343  *
344  * @param modifier The SDL keyboard modifier when the key was
345  * pressed.
346  * @param handled If the function handles the key it should
347  * set handled to true else do not modify it.
348  * This is used in the keyboard event
349  * changing.
350  */
351  virtual void handle_key_right_arrow(SDL_Keymod modifier, bool& handled) = 0;
352 
353 protected:
354  /**
355  * Selects a not selected item.
356  *
357  * @param index The index of a not selected item.
358  */
359  virtual void do_select_item(const unsigned index) = 0;
360 
361  /**
362  * Deselects a selected item.
363  *
364  * @param index The index of a selected item.
365  */
366  virtual void do_deselect_item(const unsigned index) = 0;
367 
368  /** Gets the grid of an item. */
369  virtual grid& item_ordered(const unsigned index) = 0;
370 
371  /** Gets the grid of an item. */
372  virtual const grid& item_ordered(const unsigned index) const = 0;
373 
374 public:
375  virtual unsigned get_ordered_index(unsigned index) const = 0;
376 
377  virtual unsigned get_item_at_ordered(unsigned index_ordered) const = 0;
378 
379 };
380 
381 using generator_sort_array = std::array<generator_base::order_func, 2>;
382 
383 } // namespace gui2
virtual void handle_key_left_arrow(SDL_Keymod modifier, bool &handled)=0
Left arrow key pressed.
friend class debug_layout_graph
Definition: generator.hpp:41
virtual grid & item_ordered(const unsigned index)=0
Gets the grid of an item.
virtual void handle_key_up_arrow(SDL_Keymod modifier, bool &handled)=0
Up arrow key pressed.
virtual unsigned get_item_at_ordered(unsigned index_ordered) const =0
virtual void request_reduce_width(const unsigned maximum_width) override=0
See widget::request_reduce_width.
virtual widget * find_at(const point &coordinate, const bool must_be_active) override=0
See widget::find_at.
virtual unsigned get_item_count() const =0
Returns the number of items.
virtual void handle_key_right_arrow(SDL_Keymod modifier, bool &handled)=0
Right arrow key pressed.
virtual grid & create_item(const int index, builder_grid_const_ptr list_builder, const string_map &item_data, const std::function< void(widget &)> &callback)=0
Creates a new item.
virtual void set_item_shown(const unsigned index, const bool show)=0
Shows or hides an item.
std::shared_ptr< const builder_grid > builder_grid_const_ptr
virtual ~generator_base()
Definition: generator.hpp:44
virtual void place(const point &origin, const point &size) override=0
See widget::place.
virtual void set_order(const order_func &order)=0
virtual bool is_selected(const unsigned index) const =0
Returns whether the item is selected.
virtual void do_select_item(const unsigned index)=0
Selects a not selected item.
Base class for all widgets.
Definition: widget.hpp:47
std::function< bool(unsigned, unsigned)> order_func
Definition: generator.hpp:248
virtual grid & item(const unsigned index)=0
Gets the grid of an item.
virtual void child_populate_dirty_list(window &caller, const std::vector< widget *> &call_stack) override=0
See widget::child_populate_dirty_list.
virtual unsigned get_selected_item_count() const =0
Returns the number of selected items.
Generic file dialog.
Definition: field-fwd.hpp:22
virtual point calculate_best_size() const override=0
See widget::calculate_best_size.
Base container class.
Definition: grid.hpp:30
virtual void request_reduce_height(const unsigned maximum_height) override=0
See widget::request_reduce_height.
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:86
Abstract base class for the generator.
Definition: generator.hpp:39
void toggle_item(const unsigned index)
Toggles the selection state of an item.
Definition: generator.hpp:97
placement
Determines how the items are placed.
Definition: generator.hpp:49
virtual void layout_initialize(const bool full_initialization) override=0
See widget::layout_initialize.
virtual void create_items(const int index, builder_grid_const_ptr list_builder, const std::vector< string_map > &data, const std::function< void(widget &)> &callback)=0
Creates one or more new item(s).
virtual bool get_item_shown(const unsigned index) const =0
Returns whether the item is shown.
virtual int get_selected_item() const =0
Returns the selected item.
std::size_t i
Definition: function.cpp:933
virtual void set_visible_rectangle(const SDL_Rect &rectangle) override=0
See widget::set_visible_rectangle.
virtual void clear()=0
Deletes all items.
std::map< std::string, t_string > string_map
Definition: widget.hpp:24
std::array< generator_base::order_func, 2 > generator_sort_array
Definition: generator.hpp:381
Holds a 2D point.
Definition: point.hpp:23
std::size_t index(const std::string &str, const std::size_t index)
Codepoint index corresponding to the nth character in a UTF-8 string.
Definition: unicode.cpp:71
static generator_base * build(const bool has_minimum, const bool has_maximum, const placement placement, const bool select)
Create a new generator.
Definition: generator.cpp:1166
bool grid()
Definition: general.cpp:505
virtual void delete_item(const unsigned index)=0
Deletes an item.
virtual void handle_key_down_arrow(SDL_Keymod modifier, bool &handled)=0
Down arrow key pressed.
virtual void select_item(const unsigned index, const bool select)=0
(De)selects an item.
virtual unsigned get_ordered_index(unsigned index) const =0
map_location coordinate
Contains an x and y coordinate used for starting positions in maps.
virtual void set_origin(const point &origin) override=0
See widget::set_origin.
virtual void do_deselect_item(const unsigned index)=0
Deselects a selected item.
virtual void impl_draw_children(surface &frame_buffer, int x_offset, int y_offset) override=0
See widget::impl_draw_children.
base class of top level items, the only item which needs to store the final canvases to draw on ...
Definition: window.hpp:63
static std::deque< std::string > call_stack
Definition: function.cpp:39
boost::dynamic_bitset get_items_shown() const
Returns the visibility of all the items as a bit set.
Definition: generator.hpp:119
void show(const std::string &window_id, const t_string &message, const point &mouse, const SDL_Rect &source_rect)
Shows a tip.
Definition: tooltip.cpp:154