The Battle for Wesnoth  1.19.0-dev
text_box_base.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 
18 //#include "gui/core/event/dispatcher.hpp"
20 #include "font/text.hpp" // We want the file in src/
21 
22 #include <string>
23 
24 #include <functional>
25 
26 namespace gui2
27 {
28 namespace implementation
29 {
30  struct builder_styled_widget;
31 }
32 
33 /**
34  * Abstract base class for text items.
35  *
36  * All other text classes should inherit from this base class.
37  *
38  * The NOTIFY_MODIFIED event is send when the text is modified.
39  *
40  * @todo Validate whether the NOTIFY_MODIFIED is always fired properly. The
41  * current implementation is added for some quick testing so some cases might
42  * be forgotten.
43  *
44  * Common signal handlers:
45  * - connect_signal_pre_key_press
46  */
48 {
49 
50 public:
51  text_box_base(const implementation::builder_styled_widget& builder, const std::string& control_type);
52 
54 
55  /** See @ref styled_widget::set_active. */
56  virtual void set_active(const bool active) override;
57 
58  /** See @ref styled_widget::get_active. */
59  virtual bool get_active() const override;
60 
61  /** See @ref styled_widget::get_state. */
62  virtual unsigned get_state() const override;
63 
64  /***** ***** ***** ***** expose some functions ***** ***** ***** *****/
65 
66  void set_maximum_length(const std::size_t maximum_length);
67 
68  /**
69  * Wrapper function, returns length of the text in pango column offsets.
70  * See @ref font::pango_text::get_length.
71  */
72  std::size_t get_length() const
73  {
74  return text_.get_length();
75  }
76 
77  /**
78  * Wrapper function, returns a vector with the lines.
79  * See @ref font::pango_text::get_lines.
80  */
81  std::vector<std::string> get_lines()
82  {
83  return text_.get_lines();
84  }
85 
86  /**
87  * Wrapper function, return number of lines.
88  * See @ref font::pango_text::get_lines_count.
89  */
90  unsigned get_lines_count() const
91  {
92  return text_.get_lines_count();
93  }
94 
95  /**
96  * Wrapper function, returns corrected column offset from pango.
97  * See @ref font::pango_text::get_byte_offset.
98  */
99  int get_byte_offset(const unsigned column) const
100  {
101  return text_.get_byte_offset(column);
102  }
103 
104  /**
105  * Wrapper function, sets the area between column start and end
106  * offset to be highlighted in a specific color.
107  * See @ref font::pango_text::set_highlight_area.
108  */
109  void set_highlight_area(const unsigned start_offset, const unsigned end_offset, const color_t& color)
110  {
111  text_.set_highlight_area(start_offset, end_offset, color);
112  }
113 
114  /***** ***** ***** setters / getters for members ***** ****** *****/
115 
116  /**
117  * The set_value is virtual for the @ref password_box class.
118  *
119  * That class overrides the set_value function to replace it with asterisk.
120  * There might be more generic way to do it when more classes are needed.
121  */
122  virtual void set_value(const std::string& text);
123  std::string get_value() const
124  {
125  return text_.text();
126  }
127 
128  const std::string& text() const
129  {
130  return text_.text();
131  }
132 
133  /** Set the text_changed callback. */
135  std::function<void(text_box_base* textbox, const std::string text)> cb)
136  {
138  }
139 
140  /**
141  * Sets or clears the text selection.
142  *
143  * Setting the selection range will re-position the cursor depending on the
144  * selection direction, specified by the length's sign. Selecting beyond the
145  * start or end of the text is safe; the final selection will be limited
146  * accordingly.
147  *
148  * @note The range extents are measured in Unicode characters, not bytes.
149  * Using byte offsets may produce unexpected results depending on the
150  * text contents.
151  *
152  * @param start Start offset, in characters.
153  * @param length Selection length, in characters. If zero, the
154  * current selection is canceled. If negative, the
155  * selection extends towards the start of the text
156  * and the cursor will be re-positioned in that
157  * direction as well; otherwise the selection and
158  * cursor extend towards the end.
159  */
160  void set_selection(std::size_t start, int length);
161 
162  void set_editable(bool editable)
163  {
164  editable_ = editable;
165  update_canvas();
166  }
167 
168  bool is_editable()
169  {
170  return editable_;
171  }
172 
173 protected:
174  /** Get length of composition text by IME **/
175  size_t get_composition_length() const;
176 
177  /**
178  * Moves the cursor to the end of the line.
179  *
180  * @param select Select the text from the original cursor
181  * position till the end of the line?
182  */
183  virtual void goto_end_of_line(const bool select = false) = 0;
184 
185  /**
186  * Moves the cursor to the end of all text.
187  *
188  * For a single line text this is the same as goto_end_of_line().
189  *
190  * @param select Select the text from the original cursor
191  * position till the end of the data?
192  */
193  virtual void goto_end_of_data(const bool select = false)
194  {
195  set_cursor(text_.get_length(), select);
196  }
197 
198  /**
199  * Moves the cursor to the beginning of the line
200  *
201  * @param select Select the text from the original cursor
202  * position till the beginning of the line?
203  */
204  virtual void goto_start_of_line(const bool select = false) = 0;
205 
206  /**
207  * Moves the cursor to the beginning of the data.
208  *
209  * @param select Select the text from the original cursor
210  * position till the beginning of the data?
211  */
212  virtual void goto_start_of_data(const bool select = false)
213  {
214  set_cursor(0, select);
215  }
216 
217  /** Selects all text. */
218  void select_all()
219  {
220  selection_start_ = 0;
221  goto_end_of_data(true);
222  }
223 
224  /**
225  * Moves the cursor at the wanted position.
226  *
227  * @param offset The wanted new cursor position.
228  * @param select Select the text from the original cursor
229  * position till the new position?
230  */
231  virtual void set_cursor(const std::size_t offset, const bool select);
232 
233  /**
234  * Inserts a character at the cursor.
235  *
236  * This function is preferred over set_text since it's optimized for
237  * updating the internal bookkeeping.
238  *
239  * @param unicode The unicode value of the character to insert.
240  */
241  virtual void insert_char(const std::string& unicode);
242 
243  /**
244  * Deletes the character.
245  *
246  * @param before_cursor If true it deletes the character before the
247  * cursor (backspace) else the character after
248  * the cursor (delete).
249  */
250  virtual void delete_char(const bool before_cursor) = 0;
251 
252  /** Deletes the current selection. */
253  virtual void delete_selection() = 0;
254 
255  /** Copies the current selection. */
256  virtual void copy_selection(const bool mouse);
257 
258  /** Pastes the current selection. */
259  virtual void paste_selection(const bool mouse);
260 
261  /***** ***** ***** ***** expose some functions ***** ***** ***** *****/
262 
263  point get_cursor_position(const unsigned column,
264  const unsigned line = 0) const
265  {
266  return text_.get_cursor_position(column, line);
267  }
268 
269  point get_column_line(const point& position) const
270  {
271  return text_.get_column_line(position);
272  }
273 
275  {
276  return font_family_;
277  }
278 
280  {
281  font_family_ = fclass;
283  }
284 
285  void set_font_size(const unsigned font_size)
286  {
287  text_.set_font_size(font_size);
288  }
289 
291  {
292  text_.set_font_style(font_style);
293  }
294 
295  void set_maximum_width(const int width)
296  {
297  text_.set_maximum_width(width);
298  }
299 
300  void set_maximum_height(const int height, const bool multiline)
301  {
302  text_.set_maximum_height(height, multiline);
303  }
304 
305  void set_ellipse_mode(const PangoEllipsizeMode ellipse_mode)
306  {
307  text_.set_ellipse_mode(ellipse_mode);
308  }
309 
310  /***** ***** ***** setters / getters for members ***** ****** *****/
311 
312  std::size_t get_selection_start() const
313  {
314  return selection_start_;
315  }
316  void set_selection_start(const std::size_t selection_start);
317 
318  std::size_t get_selection_length() const
319  {
320  return selection_length_;
321  }
322  void set_selection_length(const int selection_length);
323 
324  std::size_t get_composition_start() const
325  {
326  return ime_start_point_;
327  }
328 
329 public:
330  bool is_composing() const
331  {
332  return ime_composing_;
333  }
334 
335  void interrupt_composition();
336 
337  /** Note the order of the states must be the same as defined in
338  * settings.hpp. */
339  enum state_t {
344  };
345 
346 private:
347  void set_state(const state_t state);
348 
349  virtual void toggle_cursor_timer(bool enable);
350 
351  /** Implements blinking cursor functionality. */
352  virtual void cursor_timer_callback();
353 
354  virtual void reset_cursor_state();
355 
356  void update_mouse_cursor(bool enable);
357 
358  /**
359  * Current state of the widget.
360  *
361  * The state of the widget determines what to render and how the widget
362  * reacts to certain 'events'.
363  */
365 
366  /** The text entered in the widget. */
368 
369  /** font family */
371 
372  /** Cached version of the text without any pending IME modifications. */
373  std::string text_cached_;
374 
375  /** Start of the selected text. */
376  std::size_t selection_start_;
377 
378  /**
379  * Length of the selected text.
380  *
381  * * positive selection_len_ means selection to the right.
382  * * negative selection_len_ means selection to the left.
383  * * selection_len_ == 0 means no selection.
384  */
386 
387  /** If this text_box_base is editable */
388  bool editable_;
389 
390  // Values to support input method editors
393 
394  std::size_t cursor_timer_;
395 
396  unsigned short cursor_alpha_;
397  unsigned short cursor_blink_rate_ms_;
398 
399  /****** handling of special keys first the pure virtuals *****/
400 
401  /**
402  * Every key can have several behaviors.
403  *
404  * Unmodified No modifier is pressed.
405  * Control The control key is pressed.
406  * Shift The shift key is pressed.
407  * Alt The alt key is pressed.
408  *
409  * If modifiers together do something else as the sum of the modifiers
410  * it's listed separately eg.
411  *
412  * Control Moves 10 steps at the time.
413  * Shift Selects the text.
414  * Control + Shift Inserts 42 in the text.
415  *
416  * There are some predefined actions for results.
417  * Unhandled The key/modifier is ignored and also reported
418  * unhandled.
419  * Ignored The key/modifier is ignored and it's
420  * _expected_ the inherited classes do the same.
421  * Implementation defined The key/modifier is ignored and it's expected
422  * the inherited classes will define some meaning
423  * to it.
424  */
425 
426  /**
427  * Up arrow key pressed.
428  *
429  * The behavior is implementation defined.
430  */
431  virtual void handle_key_up_arrow(SDL_Keymod modifier, bool& handled) = 0;
432 
433  /**
434  * Down arrow key pressed.
435  *
436  * The behavior is implementation defined.
437  */
438  virtual void handle_key_down_arrow(SDL_Keymod modifier, bool& handled) = 0;
439 
440  /**
441  * Clears the current line.
442  *
443  * Unmodified Clears the current line.
444  * Control Ignored.
445  * Shift Ignored.
446  * Alt Ignored.
447  */
448  virtual void handle_key_clear_line(SDL_Keymod modifier, bool& handled) = 0;
449 protected:
450  /**
451  * Left arrow key pressed.
452  *
453  * Unmodified Moves the cursor a character to the left.
454  * Control Like unmodified but a word instead of a letter
455  * at the time.
456  * Shift Selects the text while moving.
457  * Alt Ignored.
458  */
459  virtual void handle_key_left_arrow(SDL_Keymod modifier, bool& handled);
460 
461  /**
462  * Right arrow key pressed.
463  *
464  * Unmodified Moves the cursor a character to the right.
465  * Control Like unmodified but a word instead of a letter
466  * at the time.
467  * Shift Selects the text while moving.
468  * Alt Ignored.
469  */
470  virtual void handle_key_right_arrow(SDL_Keymod modifier, bool& handled);
471 
472 private:
473  /**
474  * Home key pressed.
475  *
476  * Unmodified Moves the cursor a to the beginning of the
477  * line.
478  * Control Like unmodified but to the beginning of the
479  * data.
480  * Shift Selects the text while moving.
481  * Alt Ignored.
482  */
483  virtual void handle_key_home(SDL_Keymod modifier, bool& handled);
484 
485  /**
486  * End key pressed.
487  *
488  * Unmodified Moves the cursor a to the end of the line.
489  * Control Like unmodified but to the end of the data.
490  * Shift Selects the text while moving.
491  * Alt Ignored.
492  */
493  virtual void handle_key_end(SDL_Keymod modifier, bool& handled);
494 
495  /**
496  * Backspace key pressed.
497  *
498  * Unmodified Deletes the character before the cursor,
499  * ignored if at the beginning of the data.
500  * Control Ignored.
501  * Shift Ignored.
502  * Alt Ignored.
503  */
504  virtual void handle_key_backspace(SDL_Keymod modifier, bool& handled);
505 
506  /**
507  * Delete key pressed.
508  *
509  * Unmodified If there is a selection that's deleted.
510  * Else if not at the end of the data the
511  * character after the cursor is deleted.
512  * Else the key is ignored.
513  * ignored if at the beginning of the data.
514  * Control Ignored.
515  * Shift Ignored.
516  * Alt Ignored.
517  */
518  virtual void handle_key_delete(SDL_Keymod modifier, bool& handled);
519 
520  /**
521  * Page up key.
522  *
523  * Unmodified Unhandled.
524  * Control Ignored.
525  * Shift Ignored.
526  * Alt Ignored.
527  */
528  virtual void handle_key_page_up(SDL_Keymod /*modifier*/, bool& /*handled*/)
529  {
530  }
531 
532  /**
533  * Page down key.
534  *
535  * Unmodified Unhandled.
536  * Control Ignored.
537  * Shift Ignored.
538  * Alt Ignored.
539  */
540  virtual void handle_key_page_down(SDL_Keymod /*modifier*/, bool& /*handled*/)
541  {
542  }
543 
544  /**
545  * Tab key.
546  *
547  * Unmodified Implementation defined.
548  * Control Implementation defined.
549  * Shift Implementation defined.
550  * Alt Implementation defined.
551  */
552  virtual void handle_key_tab(SDL_Keymod /*modifier*/, bool& /*handled*/)
553  {
554  }
555 
556  /**
557  * Enter key.
558  *
559  * Unmodified Handled by Window.
560  * Control Implementation defined.
561  * Shift Implementation defined.
562  * Alt Implementation defined.
563  */
564  virtual void handle_key_enter(SDL_Keymod /*modifier*/, bool& /*handled*/)
565  {
566  }
567 
568 protected:
569  virtual void handle_commit(bool& handled,
570  const std::string& unicode);
571  virtual void handle_editing(bool& handled,
572  const std::string& unicode,
573  int32_t start,
574  int32_t length);
575 
576 private:
577  /**
578  * Text changed callback.
579  *
580  * This callback is called in key_press after the key_press event has been
581  * handled by the styled_widget. The parameters to the function are:
582  * - The widget invoking the callback
583  * - The new text of the textbox.
584  */
585  std::function<void(text_box_base* textbox, const std::string text)>
587 
588  /***** ***** ***** signal handlers ***** ****** *****/
589 
591  bool& handled);
592 
594  bool& handled,
595  const SDL_Keycode key,
596  SDL_Keymod modifier);
597 
599  bool& handled,
600  const std::string& unicode,
601  int32_t start,
602  int32_t len);
603 
606 
607  void signal_handler_mouse_enter(const event::ui_event event, bool& handled);
608  void signal_handler_mouse_leave(const event::ui_event event, bool& handled);
609 };
610 
611 } // namespace gui2
Text class.
Definition: text.hpp:82
unsigned get_lines_count() const
Get number of lines in the text.
Definition: text.hpp:247
pango_text & set_font_style(const FONT_STYLE font_style)
Definition: text.cpp:428
void set_highlight_area(const unsigned start_offset, const unsigned end_offset, const color_t &color)
Mark a specific portion of text for highlighting.
Definition: text.hpp:311
int get_byte_offset(const unsigned column) const
Gets the correct number of columns to move the cursor from Pango.
Definition: text.cpp:196
std::size_t get_length() const
Gets the length of the text in bytes.
Definition: text.hpp:255
point get_column_line(const point &position) const
Gets the column of line of the character at the position.
Definition: text.cpp:315
pango_text & set_family_class(font::family_class fclass)
Definition: text.cpp:406
std::vector< std::string > get_lines() const
Retrieves a list of strings with contents for each rendered line.
Definition: text.cpp:979
pango_text & set_ellipse_mode(const PangoEllipsizeMode ellipse_mode)
Definition: text.cpp:499
point get_cursor_position(const unsigned column, const unsigned line=0) const
Gets the location for the cursor, in drawing coordinates.
Definition: text.cpp:219
pango_text & set_font_size(unsigned font_size)
Definition: text.cpp:416
pango_text & set_maximum_height(int height, bool multiline)
Definition: text.cpp:474
pango_text & set_maximum_width(int width)
Definition: text.cpp:447
const std::string & text() const
Definition: text.hpp:273
Base class for all visible items.
virtual void update_canvas()
Updates the canvas(ses).
Abstract base class for text items.
unsigned short cursor_blink_rate_ms_
virtual void handle_key_backspace(SDL_Keymod modifier, bool &handled)
Backspace key pressed.
std::size_t get_length() const
Wrapper function, returns length of the text in pango column offsets.
virtual void handle_commit(bool &handled, const std::string &unicode)
virtual bool get_active() const override
See styled_widget::get_active.
virtual unsigned get_state() const override
See styled_widget::get_state.
void set_font_size(const unsigned font_size)
virtual void paste_selection(const bool mouse)
Pastes the current selection.
std::function< void(text_box_base *textbox, const std::string text)> text_changed_callback_
Text changed callback.
void update_mouse_cursor(bool enable)
point get_column_line(const point &position) const
virtual void goto_start_of_line(const bool select=false)=0
Moves the cursor to the beginning of the line.
virtual void handle_key_delete(SDL_Keymod modifier, bool &handled)
Delete key pressed.
virtual void insert_char(const std::string &unicode)
Inserts a character at the cursor.
virtual void handle_editing(bool &handled, const std::string &unicode, int32_t start, int32_t length)
SDL_TEXTEDITING handler.
void set_state(const state_t state)
void signal_handler_sdl_text_input(const event::ui_event event, bool &handled, const std::string &unicode, int32_t start, int32_t len)
virtual void handle_key_left_arrow(SDL_Keymod modifier, bool &handled)
Left arrow key pressed.
virtual void toggle_cursor_timer(bool enable)
text_box_base(const implementation::builder_styled_widget &builder, const std::string &control_type)
std::string get_value() const
void set_editable(bool editable)
void set_highlight_area(const unsigned start_offset, const unsigned end_offset, const color_t &color)
Wrapper function, sets the area between column start and end offset to be highlighted in a specific c...
state_t state_
Current state of the widget.
virtual void goto_end_of_line(const bool select=false)=0
Moves the cursor to the end of the line.
std::size_t get_composition_start() const
void signal_handler_mouse_leave(const event::ui_event event, bool &handled)
void set_selection(std::size_t start, int length)
Sets or clears the text selection.
std::size_t selection_start_
Start of the selected text.
size_t get_composition_length() const
Get length of composition text by IME.
virtual void handle_key_enter(SDL_Keymod, bool &)
Enter key.
int selection_length_
Length of the selected text.
unsigned short cursor_alpha_
std::size_t cursor_timer_
virtual void handle_key_up_arrow(SDL_Keymod modifier, bool &handled)=0
Every key can have several behaviors.
const std::string & text() const
point get_cursor_position(const unsigned column, const unsigned line=0) const
void set_font_style(const font::pango_text::FONT_STYLE font_style)
unsigned get_lines_count() const
Wrapper function, return number of lines.
void signal_handler_mouse_enter(const event::ui_event event, bool &handled)
virtual void handle_key_tab(SDL_Keymod, bool &)
Tab key.
std::string text_cached_
Cached version of the text without any pending IME modifications.
void set_font_family(font::family_class fclass)
virtual void set_value(const std::string &text)
The set_value is virtual for the password_box class.
state_t
Note the order of the states must be the same as defined in settings.hpp.
font::pango_text text_
The text entered in the widget.
void signal_handler_lose_keyboard_focus(const event::ui_event event)
void signal_handler_sdl_key_down(const event::ui_event event, bool &handled, const SDL_Keycode key, SDL_Keymod modifier)
virtual void handle_key_right_arrow(SDL_Keymod modifier, bool &handled)
Right arrow key pressed.
std::size_t get_selection_length() const
virtual void handle_key_clear_line(SDL_Keymod modifier, bool &handled)=0
Clears the current line.
void set_maximum_height(const int height, const bool multiline)
font::family_class font_family_
font family
void set_ellipse_mode(const PangoEllipsizeMode ellipse_mode)
font::family_class get_font_family()
void set_selection_start(const std::size_t selection_start)
virtual void set_cursor(const std::size_t offset, const bool select)
Moves the cursor at the wanted position.
std::vector< std::string > get_lines()
Wrapper function, returns a vector with the lines.
void set_maximum_width(const int width)
virtual void handle_key_page_up(SDL_Keymod, bool &)
Page up key.
virtual void handle_key_home(SDL_Keymod modifier, bool &handled)
Home key pressed.
void set_text_changed_callback(std::function< void(text_box_base *textbox, const std::string text)> cb)
Set the text_changed callback.
virtual void handle_key_down_arrow(SDL_Keymod modifier, bool &handled)=0
Down arrow key pressed.
void signal_handler_receive_keyboard_focus(const event::ui_event event)
virtual void goto_end_of_data(const bool select=false)
Moves the cursor to the end of all text.
void signal_handler_middle_button_click(const event::ui_event event, bool &handled)
virtual void handle_key_end(SDL_Keymod modifier, bool &handled)
End key pressed.
virtual void handle_key_page_down(SDL_Keymod, bool &)
Page down key.
std::size_t get_selection_start() const
virtual void set_active(const bool active) override
See styled_widget::set_active.
void set_selection_length(const int selection_length)
virtual void copy_selection(const bool mouse)
Copies the current selection.
bool is_composing() const
bool editable_
If this text_box_base is editable.
virtual void goto_start_of_data(const bool select=false)
Moves the cursor to the beginning of the data.
virtual void cursor_timer_callback()
Implements blinking cursor functionality.
virtual void reset_cursor_state()
void set_maximum_length(const std::size_t maximum_length)
virtual void delete_selection()=0
Deletes the current selection.
virtual void delete_char(const bool before_cursor)=0
Deletes the character.
void select_all()
Selects all text.
int get_byte_offset(const unsigned column) const
Wrapper function, returns corrected column offset from pango.
void line(int from_x, int from_y, int to_x, int to_y)
Draw a line.
Definition: draw.cpp:181
EXIT_STATUS start(bool clear_id, const std::string &filename, bool take_screenshot, const std::string &screenshot_filename)
Main interface for launching the editor from the title screen.
family_class
Font classes for get_font_families().
ui_event
The event sent to the dispatcher.
Definition: handler.hpp:115
Generic file dialog.
Contains the implementation details for lexical_cast and shouldn't be used directly.
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
Holds a 2D point.
Definition: point.hpp:25