The Battle for Wesnoth  1.17.21+dev
label.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2023
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 
22 
23 namespace gui2
24 {
25 namespace implementation
26 {
27  struct builder_label;
28 }
29 
30 // ------------ WIDGET -----------{
31 
32 /**
33  * @ingroup GUIWidgetWML
34  *
35  * A label displays text that can be wrapped but no scrollbars are provided.
36  *
37  * A label has two states because labels are often used as visual indication of the state of the widget it labels.
38  *
39  * The following states exist:
40  * * state_enabled - the label is enabled.
41  * * state_disabled - the label is disabled.
42  *
43  * Key |Type |Default |Description
44  * -------------------|------------------------------------|--------|-------------
45  * link_color | @ref guivartype_string "string" |\#ffff00|The color to render links with. This string will be used verbatim in pango markup for each link.
46  *
47  * The label specific variables:
48  * Key |Type |Default|Description
49  * -------------------|------------------------------------|-------|-------------
50  * wrap | @ref guivartype_bool "bool" |false |Is wrapping enabled for the label.
51  * characters_per_line| @ref guivartype_unsigned "unsigned"|0 |Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text.
52  * text_alignment | @ref guivartype_h_align "h_align" |left |The way the text is aligned inside the canvas.
53  * can_shrink | @ref guivartype_bool "bool" |false |Whether the label can shrink past its optimal size.
54  * link_aware | @ref guivartype_bool "bool" |false |Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
55  */
56 class label : public styled_widget
57 {
59 
60 public:
61  explicit label(const implementation::builder_label& builder);
62 
63  /** See @ref widget::can_wrap. */
64  virtual bool can_wrap() const override
65  {
66  return can_wrap_ || characters_per_line_ != 0;
67  }
68 
69  /** See @ref styled_widget::get_characters_per_line. */
70  virtual unsigned get_characters_per_line() const override
71  {
72  return characters_per_line_;
73  }
74 
75  /** See @ref styled_widget::get_link_aware. */
76  virtual bool get_link_aware() const override
77  {
78  return link_aware_;
79  }
80 
81  /** See @ref styled_widget::get_link_aware. */
82  virtual color_t get_link_color() const override
83  {
84  return link_color_;
85  }
86 
87  /** See @ref styled_widget::set_active. */
88  virtual void set_active(const bool active) override;
89 
90  /** See @ref styled_widget::get_active. */
91  virtual bool get_active() const override
92  {
93  return state_ != DISABLED;
94  }
95 
96  /** See @ref styled_widget::get_state. */
97  virtual unsigned get_state() const override
98  {
99  return state_;
100  }
101 
102  /** See @ref widget::disable_click_dismiss. */
103  bool disable_click_dismiss() const override
104  {
105  return false;
106  }
107 
108  /** See @ref widget::can_mouse_focus. */
109  virtual bool can_mouse_focus() const override
110  {
111  return !tooltip().empty() || get_link_aware();
112  }
113 
114  /** See @ref styled_widget::update_canvas. */
115  virtual void update_canvas() override;
116 
117  /***** ***** ***** setters / getters for members ***** ****** *****/
118 
119  void set_can_wrap(const bool wrap)
120  {
121  can_wrap_ = wrap;
122  }
123 
124  void set_characters_per_line(const unsigned characters_per_line)
125  {
126  characters_per_line_ = characters_per_line;
127  }
128 
129  void set_link_aware(bool l);
130 
131  void set_link_color(const color_t& color);
132 
133  void set_can_shrink(bool can_shrink)
134  {
135  can_shrink_ = can_shrink;
136  }
137 
138  void set_text_alpha(unsigned short alpha);
139 
140 private:
141  /**
142  * Possible states of the widget.
143  *
144  * Note the order of the states must be the same as defined in settings.hpp.
145  */
146  enum state_t {
149  };
150 
151  void set_state(const state_t state);
152 
153  /**
154  * Current state of the widget.
155  *
156  * The state of the widget determines what to render and how the widget
157  * reacts to certain 'events'.
158  */
160 
161  /** Holds the label can wrap or not. */
162  bool can_wrap_;
163 
164  /**
165  * The maximum number of characters per line.
166  *
167  * The maximum is not an exact maximum, it uses the average character width.
168  */
170 
171  /**
172  * Whether the label is link aware, rendering links with special formatting
173  * and handling click events.
174  */
176 
177  /**
178  * What color links will be rendered in.
179  */
181 
183 
184  unsigned short text_alpha_;
185 
186  /** Inherited from styled_widget. */
187  virtual bool text_can_shrink() override
188  {
189  return can_shrink_;
190  }
191 
192 public:
193  /** Static type getter that does not rely on the widget being constructed. */
194  static const std::string& type();
195 
196 private:
197  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
198  virtual const std::string& get_control_type() const override;
199 
200  /***** ***** ***** signal handlers ***** ****** *****/
201 
202  /**
203  * Left click signal handler: checks if we clicked on a hyperlink
204  */
205  void signal_handler_left_button_click(bool& handled);
206 
207  /**
208  * Right click signal handler: checks if we clicked on a hyperlink, copied to clipboard
209  */
210  void signal_handler_right_button_click(bool& handled);
211 
212  /**
213  * Mouse motion signal handler: checks if the cursor is on a hyperlink
214  */
215  void signal_handler_mouse_motion(bool& handled, const point& coordinate);
216 
217  /**
218  * Mouse leave signal handler: checks if the cursor left a hyperlink
219  */
220  void signal_handler_mouse_leave(bool& handled);
221 
222  /**
223  * Implementation detail for (re)setting the hyperlink cursor.
224  */
225  void update_mouse_cursor(bool enable);
226 };
227 
228 // }---------- DEFINITION ---------{
229 
231 {
232 
233  explicit label_definition(const config& cfg);
234 
236  {
237  explicit resolution(const config& cfg);
238 
240  };
241 };
242 
243 // }---------- BUILDER -----------{
244 
245 namespace implementation
246 {
247 
249 {
250  builder_label(const config& cfg);
251 
253 
254  virtual std::unique_ptr<widget> build() const override;
255 
256  bool wrap;
257 
259 
260  PangoAlignment text_alignment;
261 
264 };
265 
266 } // namespace implementation
267 
268 // }------------ END --------------
269 
270 } // namespace gui2
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
A label displays text that can be wrapped but no scrollbars are provided.
Definition: label.hpp:57
virtual const std::string & get_control_type() const override
Inherited from styled_widget, implemented by REGISTER_WIDGET.
void set_can_shrink(bool can_shrink)
Definition: label.hpp:133
unsigned short text_alpha_
Definition: label.hpp:184
bool can_shrink_
Definition: label.hpp:182
virtual bool get_link_aware() const override
See styled_widget::get_link_aware.
Definition: label.hpp:76
void signal_handler_left_button_click(bool &handled)
Left click signal handler: checks if we clicked on a hyperlink.
Definition: label.cpp:118
virtual bool text_can_shrink() override
Inherited from styled_widget.
Definition: label.hpp:187
static const std::string & type()
Static type getter that does not rely on the widget being constructed.
void set_link_color(const color_t &color)
Definition: label.cpp:101
void signal_handler_mouse_leave(bool &handled)
Mouse leave signal handler: checks if the cursor left a hyperlink.
Definition: label.cpp:199
color_t link_color_
What color links will be rendered in.
Definition: label.hpp:180
void signal_handler_right_button_click(bool &handled)
Right click signal handler: checks if we clicked on a hyperlink, copied to clipboard.
Definition: label.cpp:153
bool disable_click_dismiss() const override
See widget::disable_click_dismiss.
Definition: label.hpp:103
bool link_aware_
Whether the label is link aware, rendering links with special formatting and handling click events.
Definition: label.hpp:175
virtual unsigned get_state() const override
See styled_widget::get_state.
Definition: label.hpp:97
void set_can_wrap(const bool wrap)
Definition: label.hpp:119
virtual void update_canvas() override
See styled_widget::update_canvas.
Definition: label.cpp:66
void set_state(const state_t state)
Definition: label.cpp:110
void set_characters_per_line(const unsigned characters_per_line)
Definition: label.hpp:124
state_t
Possible states of the widget.
Definition: label.hpp:146
virtual bool get_active() const override
See styled_widget::get_active.
Definition: label.hpp:91
state_t state_
Current state of the widget.
Definition: label.hpp:159
virtual void set_active(const bool active) override
See styled_widget::set_active.
Definition: label.cpp:85
virtual unsigned get_characters_per_line() const override
See styled_widget::get_characters_per_line.
Definition: label.hpp:70
unsigned characters_per_line_
The maximum number of characters per line.
Definition: label.hpp:169
void update_mouse_cursor(bool enable)
Implementation detail for (re)setting the hyperlink cursor.
Definition: label.cpp:213
virtual color_t get_link_color() const override
See styled_widget::get_link_aware.
Definition: label.hpp:82
virtual bool can_mouse_focus() const override
See widget::can_mouse_focus.
Definition: label.hpp:109
label(const implementation::builder_label &builder)
Definition: label.cpp:46
void set_link_aware(bool l)
Definition: label.cpp:92
void set_text_alpha(unsigned short alpha)
Definition: label.cpp:76
virtual bool can_wrap() const override
See widget::can_wrap.
Definition: label.hpp:64
void signal_handler_mouse_motion(bool &handled, const point &coordinate)
Mouse motion signal handler: checks if the cursor is on a hyperlink.
Definition: label.cpp:181
bool can_wrap_
Holds the label can wrap or not.
Definition: label.hpp:162
Base class for all visible items.
const t_string & tooltip() const
bool empty() const
Definition: tstring.hpp:187
Generic file dialog.
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.
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
virtual std::unique_ptr< widget > build() const override
Definition: label.cpp:260
builder_label(const config &cfg)
Definition: label.cpp:250
virtual std::unique_ptr< widget > build() const=0
resolution(const config &cfg)
Definition: label.cpp:236
label_definition(const config &cfg)
Definition: label.cpp:228
Base class of a resolution, contains the common keys for a resolution.
Holds a 2D point.
Definition: point.hpp:25