The Battle for Wesnoth  1.15.12+dev
label.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2018 by Mark de Wever <koraq@xs4all.nl>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 #pragma once
16 
18 
21 
22 namespace gui2
23 {
24 namespace implementation
25 {
26  struct builder_label;
27 }
28 
29 // ------------ WIDGET -----------{
30 
31 /**
32  * @ingroup GUIWidgetWML
33  *
34  * A label displays a text, the text can be wrapped but no scrollbars are provided.
35  *
36  * Although the label itself has no event interaction it still has two states.
37  * The reason is that labels are often used as visual indication of the state of the widget it labels.
38  *
39  * Note: The above is outdated, if "link_aware" is enabled then there is interaction.
40  *
41  * The following states exist:
42  * * state_enabled - the label is enabled.
43  * * state_disabled - the label is disabled.
44  *
45  * Key |Type |Default |Description
46  * -------------------|------------------------------------|--------|-------------
47  * 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.
48  * 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.
49  *
50  * The label specific variables:
51  * Key |Type |Default|Description
52  * -------------------|------------------------------------|-------|-------------
53  * wrap | @ref guivartype_bool "bool" |false |Is wrapping enabled for the label.
54  * 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.
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 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
Base class of a resolution, contains the common keys for a resolution.
void set_can_shrink(bool can_shrink)
Definition: label.hpp:133
virtual widget * build() const =0
virtual bool get_link_aware() const override
See styled_widget::get_link_aware.
Definition: label.hpp:76
color_t link_color_
What color links will be rendered in.
Definition: label.hpp:180
void set_can_wrap(const bool wrap)
Definition: label.hpp:119
virtual color_t get_link_color() const override
See styled_widget::get_link_aware.
Definition: label.hpp:82
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:56
unsigned short text_alpha_
Definition: label.hpp:184
Generic file dialog.
Definition: field-fwd.hpp:22
unsigned characters_per_line_
The maximum number of characters per line.
Definition: label.hpp:169
std::string label
What to show in the filter&#39;s drop-down list.
Definition: manager.cpp:216
virtual unsigned get_state() const override
See styled_widget::get_state.
Definition: label.hpp:97
virtual bool can_mouse_focus() const override
See widget::can_mouse_focus.
Definition: label.hpp:109
virtual bool text_can_shrink() override
Inherited from styled_widget.
Definition: label.hpp:187
bool disable_click_dismiss() const override
See widget::disable_click_dismiss.
Definition: label.hpp:103
state_t state_
Current state of the widget.
Definition: label.hpp:159
bool link_aware_
Whether the label is link aware, rendering links with special formatting and handling click events...
Definition: label.hpp:175
state_t
Possible states of the widget.
Definition: label.hpp:146
Holds a 2D point.
Definition: point.hpp:23
Base class for all visible items.
bool can_shrink_
Definition: label.hpp:182
virtual bool can_wrap() const override
See widget::can_wrap.
Definition: label.hpp:64
virtual unsigned get_characters_per_line() const override
See styled_widget::get_characters_per_line.
Definition: label.hpp:70
virtual bool get_active() const override
See styled_widget::get_active.
Definition: label.hpp:91
void set_characters_per_line(const unsigned characters_per_line)
Definition: label.hpp:124
point resolution()
Definition: general.cpp:387
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:59
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:218
bool can_wrap_
Holds the label can wrap or not.
Definition: label.hpp:162