The Battle for Wesnoth  1.17.0-dev
placer.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2012 - 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 /**
17  * @file
18  * Base class for the placement helper.
19  *
20  * Some items can create new child items and these items are placed in some way
21  * this code contains helpers for the placement by calculating the positions
22  * for the items and the best size for the children.
23  */
24 
25 #pragma once
26 
27 #include "utils/make_enum.hpp"
28 
29 struct point;
30 
31 namespace gui2
32 {
33 
34 /**
35  * Base class for the placement helper.
36  *
37  * The normal operation for the usage of the class is:
38  * * Call @ref initialize().
39  * * For every visible child item call @ref add_item() with the wanted size of
40  * the widget.
41  * Once this is done the required size for all children can be retrieved with
42  * @ref get_size(). It is also possible to place all children now. In order to
43  * do so loop again over all children in the same order as @ref add_item() and
44  * call @ref get_origin(). The @p index parameter is an increasing counter.
45  *
46  * @note The origins can only be retrieved after all items are added since the
47  * adding of a later item may influence a previous item. E.g. in a vertical
48  * list with two columns the position of the second column depends on the width
49  * of the first and a later row may have a wider column 1 as an earlier row.
50  */
52 {
53 public:
54  /***** ***** Types. ***** *****/
55 
56  /** The direction the placer should grow towards. */
57  MAKE_ENUM(grow_direction,
58  (horizontal, "horizontal")
59  (vertical, "vertical")
60  );
61 
62 
63  /***** ***** Constructor, destructor, assignment. ***** *****/
64 
65 public:
66  /**
67  * Builder function.
68  *
69  * @pre @p parallel_items > 0
70  *
71  * @param grow_direction The direction in which the items will be
72  * added.
73  * @param parallel_items The direction perpendicular towards the grow
74  * direction has a fixed number of items. This
75  * value sets that limit. For a list containing
76  * only horizontally or vertically placed items
77  * the value should be 1.
78  */
79  static placer_base* build(const grow_direction grow_direction,
80  const unsigned parallel_items);
81 
82  virtual ~placer_base();
83 
84 
85  /***** ***** Operations. ***** *****/
86 
87  /**
88  * Initialises the placer.
89  *
90  * When the placement needs to be calculated the state often needs to be
91  * reset, items are placed, removed or changed visibility causing the old
92  * placement to be invalid.
93  */
94  virtual void initialize() = 0;
95 
96  /**
97  * Adds a item to be placed.
98  *
99  * @param size The required size for the item.
100  */
101  virtual void add_item(const point& size) = 0;
102 
103  /**
104  * Gets the required size of all items.
105  *
106  * @returns The required size.
107  */
108  virtual point get_size() const = 0;
109 
110  /**
111  * Gets the origin for an item.
112  *
113  * @param index The index of the item whose origin to return.
114  * The index is the index of the call to
115  * @ref add_item().
116  *
117  * @returns The origin where to place the widget.
118  */
119  virtual point get_origin(const unsigned index) const = 0;
120 };
121 
122 } // namespace gui2
Base class for the placement helper.
Definition: placer.hpp:51
MAKE_ENUM(grow_direction,(horizontal, "horizontal")(vertical, "vertical"))
The direction the placer should grow towards.
virtual point get_size() const =0
Gets the required size of all items.
Generic file dialog.
Definition: field-fwd.hpp:23
virtual ~placer_base()
Definition: placer.cpp:41
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:87
Holds a 2D point.
Definition: point.hpp:24
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:72
virtual void initialize()=0
Initialises the placer.
virtual void add_item(const point &size)=0
Adds a item to be placed.
virtual point get_origin(const unsigned index) const =0
Gets the origin for an item.
Defines the MAKE_ENUM macro.
static placer_base * build(const grow_direction grow_direction, const unsigned parallel_items)
Builder function.
Definition: placer.cpp:28