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