The Battle for Wesnoth  1.17.0-dev
label.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2021
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 a text, the text can be wrapped but no scrollbars are provided.
36  *
37  * Although the label itself has no event interaction it still has two states.
38  * The reason is that labels are often used as visual indication of the state of the widget it labels.
39  *
40  * Note: The above is outdated, if "link_aware" is enabled then there is interaction.
41  *
42  * The following states exist:
43  * * state_enabled - the label is enabled.
44  * * state_disabled - the label is disabled.
45  *
46  * Key |Type |Default |Description
47  * -------------------|------------------------------------|--------|-------------
48  * link_aware | @ref guivartype_f_bool "f_bool" |false |Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
49  * 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.
50  *
51  * The label specific variables:
52  * Key |Type |Default|Description
53  * -------------------|------------------------------------|-------|-------------
54  * wrap | @ref guivartype_bool "bool" |false |Is wrapping enabled for the label.
55  * 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.
56  */
57 class label : public styled_widget
58 {
60 
61 public:
62  explicit label(const implementation::builder_label& builder);
63 
64  /** See @ref widget::can_wrap. */
65  virtual bool can_wrap() const override
66  {
67  return can_wrap_ || characters_per_line_ != 0;
68  }
69 
70  /** See @ref styled_widget::get_characters_per_line. */
71  virtual unsigned get_characters_per_line() const override
72  {
73  return characters_per_line_;
74  }
75 
76  /** See @ref styled_widget::get_link_aware. */
77  virtual bool get_link_aware() const override
78  {
79  return link_aware_;
80  }
81 
82  /** See @ref styled_widget::get_link_aware. */
83  virtual color_t get_link_color() const override
84  {
85  return link_color_;
86  }
87 
88  /** See @ref styled_widget::set_active. */
89  virtual void set_active(const bool active) override;
90 
91  /** See @ref styled_widget::get_active. */
92  virtual bool get_active() const override
93  {
94  return state_ != DISABLED;
95  }
96 
97  /** See @ref styled_widget::get_state. */
98  virtual unsigned get_state() const override
99  {
100  return state_;
101  }
102 
103  /** See @ref widget::disable_click_dismiss. */
104  bool disable_click_dismiss() const override
105  {
106  return false;
107  }
108 
109  /** See @ref widget::can_mouse_focus. */
110  virtual bool can_mouse_focus() const override
111  {
112  return !tooltip().empty() || get_link_aware();
113  }
114 
115  /** See @ref styled_widget::update_canvas. */
116  virtual void update_canvas() override;
117 
118  /***** ***** ***** setters / getters for members ***** ****** *****/
119 
120  void set_can_wrap(const bool wrap)
121  {
122  can_wrap_ = wrap;
123  }
124 
125  void set_characters_per_line(const unsigned characters_per_line)
126  {
127  characters_per_line_ = characters_per_line;
128  }
129 
130  void set_link_aware(bool l);
131 
132  void set_link_color(const color_t& color);
133 
134  void set_can_shrink(bool can_shrink)
135  {
136  can_shrink_ = can_shrink;
137  }
138 
139  void set_text_alpha(unsigned short alpha);
140 
141 private:
142  /**
143  * Possible states of the widget.
144  *
145  * Note the order of the states must be the same as defined in settings.hpp.
146  */
147  enum state_t {
150  };
151 
152  void set_state(const state_t state);
153 
154  /**
155  * Current state of the widget.
156  *
157  * The state of the widget determines what to render and how the widget
158  * reacts to certain 'events'.
159  */
161 
162  /** Holds the label can wrap or not. */
163  bool can_wrap_;
164 
165  /**
166  * The maximum number of characters per line.
167  *
168  * The maximum is not an exact maximum, it uses the average character width.
169  */
171 
172  /**
173  * Whether the label is link aware, rendering links with special formatting
174  * and handling click events.
175  */
177 
178  /**
179  * What color links will be rendered in.
180  */
182 
184 
185  unsigned short text_alpha_;
186 
187  /** Inherited from styled_widget. */
188  virtual bool text_can_shrink() override
189  {
190  return can_shrink_;
191  }
192 
193 public:
194  /** Static type getter that does not rely on the widget being constructed. */
195  static const std::string& type();
196 
197 private:
198  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
199  virtual const std::string& get_control_type() const override;
200 
201  /***** ***** ***** signal handlers ***** ****** *****/
202 
203  /**
204  * Left click signal handler: checks if we clicked on a hyperlink
205  */
206  void signal_handler_left_button_click(bool& handled);
207 
208  /**
209  * Right click signal handler: checks if we clicked on a hyperlink, copied to clipboard
210  */
211  void signal_handler_right_button_click(bool& handled);
212 
213  /**
214  * Mouse motion signal handler: checks if the cursor is on a hyperlink
215  */
216  void signal_handler_mouse_motion(bool& handled, const point& coordinate);
217 
218  /**
219  * Mouse leave signal handler: checks if the cursor left a hyperlink
220  */
221  void signal_handler_mouse_leave(bool& handled);
222 
223  /**
224  * Implementation detail for (re)setting the hyperlink cursor.
225  */
226  void update_mouse_cursor(bool enable);
227 };
228 
229 // }---------- DEFINITION ---------{
230 
232 {
233 
234  explicit label_definition(const config& cfg);
235 
237  {
238  explicit resolution(const config& cfg);
239 
241  };
242 };
243 
244 // }---------- BUILDER -----------{
245 
246 namespace implementation
247 {
248 
250 {
251  builder_label(const config& cfg);
252 
254 
255  virtual widget* build() const override;
256 
257  bool wrap;
258 
260 
261  PangoAlignment text_alignment;
262 
265 };
266 
267 } // namespace implementation
268 
269 // }------------ END --------------
270 
271 } // namespace gui2
Base class of a resolution, contains the common keys for a resolution.
void set_can_shrink(bool can_shrink)
Definition: label.hpp:134
virtual widget * build() const =0
virtual bool get_link_aware() const override
See styled_widget::get_link_aware.
Definition: label.hpp:77
color_t link_color_
What color links will be rendered in.
Definition: label.hpp:181
void set_can_wrap(const bool wrap)
Definition: label.hpp:120
virtual color_t get_link_color() const override
See styled_widget::get_link_aware.
Definition: label.hpp:83
Base class for all widgets.
Definition: widget.hpp:49
A label displays a text, the text can be wrapped but no scrollbars are provided.
Definition: label.hpp:57
unsigned short text_alpha_
Definition: label.hpp:185
Generic file dialog.
Definition: field-fwd.hpp:23
unsigned characters_per_line_
The maximum number of characters per line.
Definition: label.hpp:170
std::string label
What to show in the filter&#39;s drop-down list.
Definition: manager.cpp:217
virtual unsigned get_state() const override
See styled_widget::get_state.
Definition: label.hpp:98
virtual bool can_mouse_focus() const override
See widget::can_mouse_focus.
Definition: label.hpp:110
virtual bool text_can_shrink() override
Inherited from styled_widget.
Definition: label.hpp:188
bool disable_click_dismiss() const override
See widget::disable_click_dismiss.
Definition: label.hpp:104
state_t state_
Current state of the widget.
Definition: label.hpp:160
bool link_aware_
Whether the label is link aware, rendering links with special formatting and handling click events...
Definition: label.hpp:176
state_t
Possible states of the widget.
Definition: label.hpp:147
Holds a 2D point.
Definition: point.hpp:24
Base class for all visible items.
bool can_shrink_
Definition: label.hpp:183
virtual bool can_wrap() const override
See widget::can_wrap.
Definition: label.hpp:65
virtual unsigned get_characters_per_line() const override
See styled_widget::get_characters_per_line.
Definition: label.hpp:71
virtual bool get_active() const override
See styled_widget::get_active.
Definition: label.hpp:92
void set_characters_per_line(const unsigned characters_per_line)
Definition: label.hpp:125
point resolution()
Definition: general.cpp:393
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.
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:61
Contains the implementation details for lexical_cast and shouldn&#39;t be used directly.
std::string tooltip
Shown when hovering over an entry in the filter&#39;s drop-down list.
Definition: manager.cpp:219
bool can_wrap_
Holds the label can wrap or not.
Definition: label.hpp:163