The Battle for Wesnoth  1.15.9+dev
tree_view.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2010 - 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 
20 namespace gui2
21 {
22 
23 namespace implementation {
24  struct builder_tree_view;
25  struct tree_node
26  {
27  explicit tree_node(const config& cfg);
28 
29  std::string id;
30  bool unfolded;
32  };
33 }
34 
35 // ------------ WIDGET -----------{
36 
37 class tree_view_node;
38 
39 /**
40  * @ingroup GUIWidgetWML
41  *
42  * A tree view is a control that holds several items of the same or different types.
43  * The items shown are called tree view nodes and when a node has children, these can be shown or hidden.
44  * Nodes that contain children need to provide a clickable button in order to fold or unfold the children.
45  *
46  * The following states exist:
47  * * state_enabled - the listbox is enabled.
48  * * state_disabled - the listbox is disabled.
49  * List with the tree view specific variables:
50  * Key |Type |Default |Description
51  * -------------------------|------------------------------------------------|------------|-------------
52  * vertical_scrollbar_mode | @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar.
53  * horizontal_scrollbar_mode| @ref guivartype_scrollbar_mode "scrollbar_mode"|initial_auto|Determines whether or not to show the scrollbar.
54  * indention_step_size | @ref guivartype_unsigned "unsigned" |0 |The number of pixels every level of nodes is indented from the previous level.
55  * node | @ref guivartype_unsigned "unsigned" |mandatory |The tree view can contain multiple node sections. This part needs more documentation.
56  * id | @ref guivartype_unsigned "unsigned" |"" |.
57  * return_value_id | @ref guivartype_unsigned "unsigned" |"" |.
58  */
60 {
62  friend class tree_view_node;
63 
64 public:
66 
68 
69  ~tree_view();
70 
72 
74  {
75  return *root_node_;
76  }
77 
79  add_node(const std::string& id,
80  const std::map<std::string /* widget id */, string_map>& data,
81  const int index = -1);
82 
83  /**
84  * Removes the given node as a child of its parent node.
85  *
86  * @param node A pointer to the node to remove.
87  *
88  * @returns A pair consisting of a smart pointer managing the removed
89  * node, and its position before removal.
90  */
91  std::pair<tree_view_node::ptr_t, int> remove_node(tree_view_node* node);
92 
93  void clear();
94 
95  /** See @ref widget::child_populate_dirty_list. */
96  virtual void
97  child_populate_dirty_list(window& caller,
98  const std::vector<widget*>& call_stack) override;
99 
100  /** See @ref container_base::set_self_active. */
101  virtual void set_self_active(const bool active) override;
102 
103  bool empty() const;
104 
105  /** See @ref widget::layout_children. */
106  virtual void layout_children() override;
107 
108  /***** ***** ***** setters / getters for members ***** ****** *****/
109 
110  void set_indentation_step_size(const unsigned indentation_step_size)
111  {
112  indentation_step_size_ = indentation_step_size;
113  }
114 
116  {
117  return selected_item_;
118  }
119 
121  {
122  return selected_item_;
123  }
124 
125  const std::vector<node_definition>& get_node_definitions() const
126  {
127  return node_definitions_;
128  }
129 
130 protected:
131  /***** ***** ***** ***** keyboard functions ***** ***** ***** *****/
132 
133  /** Inherited from scrollbar_container. */
134  void handle_key_up_arrow(SDL_Keymod modifier, bool& handled) override;
135 
136  /** Inherited from scrollbar_container. */
137  void handle_key_down_arrow(SDL_Keymod modifier, bool& handled) override;
138 
139  /** Inherited from scrollbar_container. */
140  void handle_key_left_arrow(SDL_Keymod modifier, bool& handled) override;
141 
142  /** Inherited from scrollbar_container. */
143  void handle_key_right_arrow(SDL_Keymod modifier, bool& handled) override;
144 private:
145  /**
146  * @todo evaluate which way the dependency should go.
147  *
148  * We no depend on the implementation, maybe the implementation should
149  * depend on us instead.
150  */
151  const std::vector<node_definition> node_definitions_;
152 
154 
156 
158 
160 
161  /**
162  * Resizes the content.
163  *
164  * The resize either happens due to resizing the content or invalidate the
165  * layout of the window.
166  *
167  * @param width_modification The wanted modification to the width:
168  * * negative values reduce width.
169  * * zero leave width as is.
170  * * positive values increase width.
171  * @param height_modification The wanted modification to the height:
172  * * negative values reduce height.
173  * * zero leave height as is.
174  * * positive values increase height.
175  * @param width_modification_pos
176  * @param height_modification_pos
177  */
178  void resize_content(const int width_modification,
179  const int height_modification,
180  const int width_modification_pos = -1,
181  const int height_modification_pos = -1);
182 
183  /** Layouts the children if needed. */
184  void layout_children(const bool force);
185 
186  /** Inherited from container_base. */
187  virtual void finalize_setup();
188 
189 public:
190  /** Static type getter that does not rely on the widget being constructed. */
191  static const std::string& type();
192 
193 private:
194  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
195  virtual const std::string& get_control_type() const override;
196 
197  /***** ***** ***** signal handlers ***** ****** *****/
198 
199  void signal_handler_left_button_down(const event::ui_event event);
200 
201  template<tree_view_node* (tree_view_node::*func) ()>
202  tree_view_node* get_next_node();
203 
204  template<tree_view_node* (tree_view_node::*func) ()>
205  bool handle_up_down_arrow();
206 };
207 
208 // }---------- DEFINITION ---------{
209 
211 {
212 
213  explicit tree_view_definition(const config& cfg);
214 
216  {
217  explicit resolution(const config& cfg);
218 
220  };
221 };
222 
223 // }---------- BUILDER -----------{
224 
225 namespace implementation
226 {
227 
229 {
230  explicit builder_tree_view(const config& cfg);
231 
233 
234  virtual widget* build() const override;
235 
238 
240 
241  /**
242  * The types of nodes in the tree view.
243  *
244  * Since we expect the amount of nodes to remain low it's stored in a
245  * vector and not in a map.
246  */
247  std::vector<tree_node> nodes;
248 
249  /*
250  * NOTE this class doesn't have a data section, so it can only be filled
251  * with data by the engine. I think this poses no limit on the usage since
252  * I don't foresee that somebody wants to pre-fill a tree view. If the need
253  * arises the data part can be added.
254  */
255 };
256 
257 } // namespace implementation
258 
259 // }------------ END --------------
260 
261 } // namespace gui2
Base class of a resolution, contains the common keys for a resolution.
virtual widget * build() const =0
void finalize_setup()
The builder needs to call us so we do our setup.
unsigned indentation_step_size_
Definition: tree_view.hpp:153
tree_view_node & get_root_node()
Definition: tree_view.hpp:73
Base class for all widgets.
Definition: widget.hpp:49
void clear(const std::string &key)
Definition: general.cpp:203
tree_view_node * selected_item()
Definition: tree_view.hpp:115
scrollbar_container::scrollbar_mode vertical_scrollbar_mode
Definition: tree_view.hpp:236
const tree_view_node * selected_item() const
Definition: tree_view.hpp:120
Generic file dialog.
Definition: field-fwd.hpp:22
tree_view_node * selected_item_
Definition: tree_view.hpp:159
tree_view_node * root_node_
Definition: tree_view.hpp:157
std::vector< tree_node > nodes
The types of nodes in the tree view.
Definition: tree_view.hpp:247
A tree view is a control that holds several items of the same or different types. ...
Definition: tree_view.hpp:59
void set_indentation_step_size(const unsigned indentation_step_size)
Definition: tree_view.hpp:110
Base class for creating containers with one or two scrollbar(s).
implementation::tree_node node_definition
Definition: tree_view.hpp:65
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
scrollbar_mode
The way to handle the showing or hiding of the scrollbar.
scrollbar_container::scrollbar_mode horizontal_scrollbar_mode
Definition: tree_view.hpp:237
point resolution()
Definition: general.cpp:371
std::unique_ptr< window > build(const builder_window::window_resolution &definition)
Builds a window.
const std::vector< node_definition > node_definitions_
Definition: tree_view.hpp:151
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:58
base class of top level items, the only item which needs to store the final canvases to draw on...
Definition: window.hpp:64
std::shared_ptr< builder_grid > builder_grid_ptr
const std::vector< node_definition > & get_node_definitions() const
Definition: tree_view.hpp:125
static std::deque< std::string > call_stack
Definition: function.cpp:40
Contains the implementation details for lexical_cast and shouldn&#39;t be used directly.
ui_event
The event send to the dispatcher.
Definition: handler.hpp:47
tree_node(const config &cfg)
Definition: tree_view.cpp:326