The Battle for Wesnoth  1.17.0-dev
text_box.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 
18 
19 namespace gui2
20 {
21 namespace implementation
22 {
23 struct builder_text_box;
24 }
25 
26 // ------------ WIDGET -----------{
27 
28 /**
29  * Class for text input history.
30  *
31  * The history of text items can be stored in the preferences. This class
32  * handles that. Every item needs an id by which the history is loaded and
33  * saved.
34  */
36 {
37 public:
38  /**
39  * Gets history that matches id.
40  *
41  * @param id The id of the history to look for.
42  * @param enabled The enabled state of the history.
43  *
44  * @returns The history object.
45  */
46  static text_history get_history(const std::string& id, const bool enabled);
47 
48  text_history() : history_(0), pos_(0), enabled_(false)
49  {
50  }
51 
52  /**
53  * Push string into the history.
54  *
55  * If the string is empty or the same as the last item in the history this
56  * function is a nop.
57  *
58  * @param text The text to push in the history.
59  */
60  void push(const std::string& text);
61 
62  /**
63  * One step up in the history.
64  *
65  * Pushes text to the history if at the end.
66  *
67  * @param text The text to push in the history.
68  *
69  * @returns The current value of the history.
70  */
71  std::string up(const std::string& text = "");
72 
73  /**
74  * One step down in the history.
75  *
76  * Pushes text to the history if at the end.
77  *
78  * @param text The text to push in the history.
79  *
80  * @returns The current value of the history.
81  */
82  std::string down(const std::string& text = "");
83 
84  /**
85  * Gets the current history value.
86  *
87  * @returns If enabled return the current history
88  * position, otherwise an empty string is
89  * returned.
90  */
91  std::string get_value() const;
92 
93  /***** ***** ***** setters / getters for members ***** ****** *****/
94 
95  void set_enabled(bool enabled = true)
96  {
97  enabled_ = enabled;
98  }
99  bool get_enabled() const
100  {
101  return enabled_;
102  }
103 
104 private:
105  text_history(std::vector<std::string>* history, const bool enabled)
106  : history_(history), pos_(history->size()), enabled_(enabled)
107  {
108  }
109 
110  /** The items in the history. */
111  std::vector<std::string>* history_;
112 
113  /** The current position in the history. */
114  unsigned pos_;
115 
116  /** Is the history enabled. */
117  bool enabled_;
118 };
119 
120 /**
121  * @ingroup GUIWidgetWML
122  *
123  * Class for a single line text area.
124  *
125  * The resolution for a text box also contains the following keys:
126  * Key |Type |Default |Description
127  * -------------|----------------------------------------|---------|-----------
128  * text_x_offset| @ref guivartype_f_unsigned "f_unsigned"|"" |The x offset of the text in the text box. This is needed for the code to determine where in the text the mouse clicks, so it can set the cursor properly.
129  * text_y_offset| @ref guivartype_f_unsigned "f_unsigned"|"" |The y offset of the text in the text box.
130  * The following states exist:
131  * * state_enabled - the text box is enabled.
132  * * state_disabled - the text box is disabled.
133  * * state_focussed - the text box has the focus of the keyboard.
134  * The following variables exist:
135  * Key |Type |Default |Description
136  * -------------|------------------------------------|---------|-----------
137  * label | @ref guivartype_t_string "t_string"|"" |The initial text of the text box.
138  * history | @ref guivartype_string "string" |"" |The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
139  */
140 class text_box : public text_box_base
141 {
143 
144 public:
145  explicit text_box(const implementation::builder_styled_widget& builder);
146 
147  /** Saves the text in the widget to the history. */
149  {
150  history_.push(get_value());
151  }
152 
153  /***** ***** ***** setters / getters for members ***** ****** *****/
154 
155  void set_history(const std::string& id)
156  {
157  history_ = text_history::get_history(id, true);
158  }
159 
160  void set_max_input_length(const std::size_t length)
161  {
162  max_input_length_ = length;
163  }
164 
165  void set_hint_data(const std::string& text, const std::string& image)
166  {
167  hint_text_ = text;
168  hint_image_ = image;
169 
170  update_canvas();
171  }
172 
173  void clear()
174  {
175  set_value("");
176  }
177 
178 protected:
179  /***** ***** ***** ***** layout functions ***** ***** ***** *****/
180 
181  /** See @ref widget::place. */
182  virtual void place(const point& origin, const point& size) override;
183 
184  /***** ***** ***** ***** Inherited ***** ***** ***** *****/
185 
186  /** See @ref styled_widget::update_canvas. */
187  virtual void update_canvas() override;
188 
189  /** Inherited from text_box_base. */
190  void goto_end_of_line(const bool select = false) override
191  {
192  goto_end_of_data(select);
193  }
194 
195  /** Inherited from text_box_base. */
196  void goto_start_of_line(const bool select = false) override
197  {
198  goto_start_of_data(select);
199  }
200 
201  /** Inherited from text_box_base. */
202  void delete_char(const bool before_cursor) override;
203 
204  /** Inherited from text_box_base. */
205  void delete_selection() override;
206 
207  void handle_mouse_selection(point mouse, const bool start_selection);
208 
209 private:
210  /** The history text for this widget. */
212 
213  /** The maximum length of the text input. */
214  std::size_t max_input_length_;
215 
216  /**
217  * The x offset in the widget where the text starts.
218  *
219  * This value is needed to translate a location in the widget to a location
220  * in the text.
221  */
222  unsigned text_x_offset_;
223 
224  /**
225  * The y offset in the widget where the text starts.
226  *
227  * Needed to determine whether a click is on the text.
228  */
229  unsigned text_y_offset_;
230 
231  /**
232  * The height of the text itself.
233  *
234  * Needed to determine whether a click is on the text.
235  */
236  unsigned text_height_;
237 
238  /** Updates text_x_offset_ and text_y_offset_. */
239  void update_offsets();
240 
241  /** Is the mouse in dragging mode, this affects selection in mouse move */
242  bool dragging_;
243 
244  /** Helper text to display (such as "Search") if the text box is empty. */
245  std::string hint_text_;
246 
247  /** Image (such as a magnifying glass) that accompanies the help text. */
248  std::string hint_image_;
249 
250  /**
251  * Inherited from text_box_base.
252  *
253  * Unmodified Unhandled.
254  * Control Ignored.
255  * Shift Ignored.
256  * Alt Ignored.
257  */
258  void handle_key_up_arrow(SDL_Keymod /*modifier*/, bool& /*handled*/) override
259  {
260  }
261 
262  /**
263  * Inherited from text_box_base.
264  *
265  * Unmodified Unhandled.
266  * Control Ignored.
267  * Shift Ignored.
268  * Alt Ignored.
269  */
270  void handle_key_down_arrow(SDL_Keymod /*modifier*/, bool& /*handled*/) override
271  {
272  }
273 
274  /**
275  * Goes one item up in the history.
276  *
277  * @returns True if there's a history, false otherwise.
278  */
279  bool history_up();
280 
281  /**
282  * Goes one item down in the history.
283  *
284  * @returns True if there's a history, false otherwise.
285  */
286  bool history_down();
287 
288  /** Inherited from text_box_base. */
289  void handle_key_tab(SDL_Keymod modifier, bool& handled) override;
290 
291  /** Inherited from text_box_base. */
292  void handle_key_clear_line(SDL_Keymod modifier, bool& handled) override;
293 
294 public:
295  /** Static type getter that does not rely on the widget being constructed. */
296  static const std::string& type();
297 
298 private:
299  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
300  virtual const std::string& get_control_type() const override;
301 
302  /***** ***** ***** signal handlers ***** ****** *****/
303 
304  void signal_handler_mouse_motion(const event::ui_event event,
305  bool& handled,
306  const point& coordinate);
307 
308  void signal_handler_left_button_down(const event::ui_event event,
309  bool& handled);
310 
311  void signal_handler_left_button_up(const event::ui_event event,
312  bool& handled);
313 
314  void signal_handler_left_button_double_click(const event::ui_event event,
315  bool& handled);
316 };
317 
318 // }---------- DEFINITION ---------{
319 
321 {
322  explicit text_box_definition(const config& cfg);
323 
325  {
326  explicit resolution(const config& cfg);
327 
330  };
331 };
332 
333 // }---------- BUILDER -----------{
334 
335 namespace implementation
336 {
337 
339 {
340 public:
341  explicit builder_text_box(const config& cfg);
342 
344 
345  virtual widget* build() const override;
346 
347  std::string history;
348 
349  std::size_t max_input_length;
350 
352  std::string hint_image;
353 };
354 
355 } // namespace implementation
356 
357 // }------------ END --------------
358 
359 } // namespace gui2
Base class of a resolution, contains the common keys for a resolution.
virtual widget * build() const =0
void set_history(const std::string &id)
Definition: text_box.hpp:155
Abstract base class for text items.
unsigned pos_
The current position in the history.
Definition: text_box.hpp:114
void set_hint_data(const std::string &text, const std::string &image)
Definition: text_box.hpp:165
Base class for all widgets.
Definition: widget.hpp:49
std::size_t max_input_length_
The maximum length of the text input.
Definition: text_box.hpp:214
void save_to_history()
Saves the text in the widget to the history.
Definition: text_box.hpp:148
void handle_key_down_arrow(SDL_Keymod, bool &) override
Inherited from text_box_base.
Definition: text_box.hpp:270
void set_max_input_length(const std::size_t length)
Definition: text_box.hpp:160
bool dragging_
Is the mouse in dragging mode, this affects selection in mouse move.
Definition: text_box.hpp:242
static text_history get_history(const std::string &id, const bool enabled)
Gets history that matches id.
Definition: text_box.cpp:37
Class for a single line text area.
Definition: text_box.hpp:140
Generic file dialog.
Definition: field-fwd.hpp:22
void goto_start_of_line(const bool select=false) override
Inherited from text_box_base.
Definition: text_box.hpp:196
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:86
text_history(std::vector< std::string > *history, const bool enabled)
Definition: text_box.hpp:105
void set_enabled(bool enabled=true)
Definition: text_box.hpp:95
typed_formula< unsigned > text_x_offset
Definition: text_box.hpp:328
unsigned text_height_
The height of the text itself.
Definition: text_box.hpp:236
bool enabled_
Is the history enabled.
Definition: text_box.hpp:117
Class for text input history.
Definition: text_box.hpp:35
void goto_end_of_line(const bool select=false) override
Inherited from text_box_base.
Definition: text_box.hpp:190
std::vector< std::string > * get_history(const std::string &id)
Returns a pointer to the history vector associated with given id making a new one if it doesn&#39;t exist...
Definition: game.cpp:950
std::vector< std::string > * history_
The items in the history.
Definition: text_box.hpp:111
unsigned text_y_offset_
The y offset in the widget where the text starts.
Definition: text_box.hpp:229
Holds a 2D point.
Definition: point.hpp:23
bool get_enabled() const
Definition: text_box.hpp:99
unsigned text_x_offset_
The x offset in the widget where the text starts.
Definition: text_box.hpp:222
Functions to load and save images from/to disk.
std::string hint_image_
Image (such as a magnifying glass) that accompanies the help text.
Definition: text_box.hpp:248
point resolution()
Definition: general.cpp:387
void handle_key_up_arrow(SDL_Keymod, bool &) override
Inherited from text_box_base.
Definition: text_box.hpp:258
std::unique_ptr< window > build(const builder_window::window_resolution &definition)
Builds a window.
map_location coordinate
Contains an x and y coordinate used for starting positions in maps.
text_history history_
The history text for this widget.
Definition: text_box.hpp:211
typed_formula< unsigned > text_y_offset
Definition: text_box.hpp:329
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:59
std::string hint_text_
Helper text to display (such as "Search") if the text box is empty.
Definition: text_box.hpp:245
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