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