The Battle for Wesnoth  1.17.21+dev
slider.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 
20 
23 
24 namespace gui2
25 {
26 namespace implementation
27 {
28 struct builder_slider;
29 }
30 
31 // ------------ WIDGET -----------{
32 
33 /**
34  * @ingroup GUIWidgetWML
35  *
36  * A slider is a control that can select a value by moving a grip on a groove.
37  * Key |Type |Default |Description
38  * -------------------------|------------------------------------|---------|-----------
39  * minimum_positioner_length| @ref guivartype_unsigned "unsigned"|mandatory|The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner.
40  * maximum_positioner_length| @ref guivartype_unsigned "unsigned"|0 |The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum.
41  * left_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the left side which can't be used by the positioner.
42  * right_offset | @ref guivartype_unsigned "unsigned"|0 |The number of pixels at the right side which can't be used by the positioner.
43  * Variables:
44  * Key |Type |Default |Description
45  * -------------------------|------------------------------------|---------|-----------
46  * best_slider_length | @ref guivartype_unsigned "unsigned"|0 |The best length for the sliding part.
47  * minimum_value | @ref guivartype_int "int" |0 |The minimum value the slider can have.
48  * maximum_value | @ref guivartype_int "int" |0 |The maximum value the slider can have.
49  * step_size | @ref guivartype_unsigned "unsigned"|0 |The number of items the slider's value increases with one step.
50  * value | @ref guivartype_int "int" |0 |The value of the slider.
51  * minimum_value_label | @ref guivartype_t_string "t_string"|"" |If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
52  * maximum_value_label | @ref guivartype_t_string "t_string"|"" |If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
53  * The following states exist:
54  * * state_enabled - the slider is enabled.
55  * * state_disabled - the slider is disabled.
56  * * state_pressed - the left mouse button is down on the positioner of the slider.
57  * * state_focussed - the mouse is over the positioner of the slider.
58  */
59 class slider : public slider_base, public integer_selector
60 {
62 
63 public:
64  explicit slider(const implementation::builder_slider& builder);
65 
66  /***** ***** ***** ***** layout functions ***** ***** ***** *****/
67 
68 private:
69  /** See @ref widget::calculate_best_size. */
70  virtual point calculate_best_size() const override;
71 
72 public:
73  /***** ***** ***** ***** Inherited ***** ***** ***** *****/
74 
75  /** Inherited from integer_selector. */
76  virtual void set_value(int value) override;
77 
78  /** Inherited from integer_selector. */
79  virtual int get_value() const override
80  {
82  }
83 
84  /** Inherited from integer_selector. */
85  virtual int get_minimum_value() const override
86  {
87  return minimum_value_;
88  }
89 
90  /** Inherited from integer_selector. */
91  virtual int get_maximum_value() const override
92  {
93  // The number of items needs to include the begin and end so count - 1.
95  }
96 
97  int get_item_count() const
98  {
99  assert(step_size_ != 0);
100  return slider_get_item_last() * step_size_ + 1;
101  }
102 
103  unsigned get_step_size() const
104  {
105  return step_size_;
106  }
107 
108  void set_step_size(int step_size);
109 
110  /***** ***** ***** setters / getters for members ***** ****** *****/
111  void set_best_slider_length(const unsigned length)
112  {
113  best_slider_length_ = length;
114  queue_redraw(); // TODO: draw_manager - does the above change the size?
115  }
116 
117  void set_value_range(int min_value, int max_value);
118 
119  void set_minimum_value_label(const t_string& minimum_value_label)
120  {
121  minimum_value_label_ = minimum_value_label;
122  }
123 
124  void set_maximum_value_label(const t_string& maximum_value_label)
125  {
126  maximum_value_label_ = maximum_value_label;
127  }
128 
129  void set_value_labels(const std::vector<t_string>& value_labels);
130 
131  using label_generator = std::function<t_string(int /*current position*/, int /*num positions*/)>;
132 
134  {
136  }
137 
138  /**
139  * Returns the label shown for the current value.
140  *
141  * @returns The label for the current value, if no label
142  * for the current label is defined, it returns
143  * the result of get_value().
144  */
145  t_string get_value_label() const;
146 
147 protected:
148  /** Inherited from scrollbar_base. */
149  virtual void child_callback_positioner_moved() override;
150 
151 private:
152  /** The best size for the slider part itself, if 0 ignored. */
154 
155  /**
156  * The minimum value the slider holds.
157  *
158  * The maximum value is minimum + item_last_.
159  * The current value is minimum + item_position_.
160  */
163 
164  /** Inherited from scrollbar_base. */
165  virtual unsigned get_length() const override
166  {
167  return get_width();
168  }
169 
170  /** Inherited from scrollbar_base. */
171  int positioner_length() const override;
172 
173  /** Inherited from scrollbar_base. */
174  unsigned offset_before() const override;
175 
176  /** Inherited from scrollbar_base. */
177  unsigned offset_after() const override;
178 
179  /** Inherited from scrollbar_base. */
180  bool on_positioner(const point& coordinate) const override;
181 
182  /** Inherited from scrollbar_base. */
183  int on_bar(const point& coordinate) const override;
184 
185  /** Inherited from scrollbar_base. */
186  int get_length_difference(const point& original, const point& current) const override
187  {
188  return current.x - original.x;
189  }
190 
191  /** Inherited from scrollbar_base. */
192  // void move_positioner(const int distance) override;
193 
194  /** See @ref styled_widget::update_canvas. */
195  virtual void update_canvas() override;
196 
197  /**
198  * When the slider shows the minimum value can show a special text.
199  * If this text is not empty this text is shown else the minimum value.
200  */
202 
203  /**
204  * When the slider shows the maximum value can show a special text.
205  * If this text is not empty this text is shown else the maximum value.
206  */
208 
209  /**
210  * Function to output custom value labels for the slider. When set
211  * its output is shown instead of the numeric values. It also overrides
212  * minimum_value_label_ and maximum_value_label_.
213  */
215 
216  /**
217  * When initially pressing the positioner and every time a new value is chosen through dragging,
218  * this value is updated with the mouse position at the time. This allows the widget to track
219  * how far the mouse has moved since setting the last value.
220  */
222 
223  // void update_current_item_mouse_position();
224 
225 public:
226  /** Static type getter that does not rely on the widget being constructed. */
227  static const std::string& type();
228 
229 private:
230  /** Inherited from styled_widget, implemented by REGISTER_WIDGET. */
231  virtual const std::string& get_control_type() const override;
232 
233  /**
234  * Handlers for keyboard input
235  */
236  void handle_key_decrease(bool& handled);
237  void handle_key_increase(bool& handled);
238 
239  /**
240  * Signal handlers:
241  */
242  void signal_handler_sdl_key_down(const event::ui_event event, bool& handled, const SDL_Keycode key);
243 
244  // void signal_handler_left_button_down(const event::ui_event event, bool& handled);
245 
246  // In this subclass, only used to grab keyboard focus -
247  // see scrollbar_base class for more handling of this event.
248  void signal_handler_left_button_up(const event::ui_event event, bool& handled);
249 };
250 
251 // }---------- DEFINITION ---------{
252 
254 {
255  explicit slider_definition(const config& cfg);
256 
258  {
259  explicit resolution(const config& cfg);
260 
262 
263  unsigned left_offset;
264  unsigned right_offset;
265  };
266 };
267 
268 // }---------- BUILDER -----------{
269 
270 namespace implementation
271 {
273 {
274  explicit builder_slider(const config& cfg);
275 
277 
278  virtual std::unique_ptr<widget> build() const override;
279 
280 private:
284  unsigned step_size_;
285  int value_;
286 
289 
290  /* This vector should have the same number of items as the slider's values. */
291  std::vector<t_string> value_labels_;
292 };
293 
294 } // namespace implementation
295 
296 // }------------ END --------------
297 
298 } // namespace gui2
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
Basic template class to generate new items.
Small abstract helper class.
Base class for a scroll bar.
Definition: slider_base.hpp:41
unsigned slider_get_item_last() const
unsigned get_slider_position() const
A slider is a control that can select a value by moving a grip on a groove.
Definition: slider.hpp:60
void set_step_size(int step_size)
Definition: slider.cpp:277
virtual void child_callback_positioner_moved() override
Inherited from scrollbar_base.
Definition: slider.cpp:120
t_string maximum_value_label_
When the slider shows the maximum value can show a special text.
Definition: slider.hpp:207
static const std::string & type()
Static type getter that does not rely on the widget being constructed.
void handle_key_decrease(bool &handled)
Handlers for keyboard input.
Definition: slider.cpp:186
unsigned best_slider_length_
The best size for the slider part itself, if 0 ignored.
Definition: slider.hpp:153
unsigned offset_before() const override
Inherited from scrollbar_base.
Definition: slider.cpp:132
void signal_handler_sdl_key_down(const event::ui_event event, bool &handled, const SDL_Keycode key)
Signal handlers:
Definition: slider.cpp:204
unsigned get_step_size() const
Definition: slider.hpp:103
void set_maximum_value_label(const t_string &maximum_value_label)
Definition: slider.hpp:124
int minimum_value_
The minimum value the slider holds.
Definition: slider.hpp:161
virtual int get_minimum_value() const override
Inherited from integer_selector.
Definition: slider.hpp:85
int on_bar(const point &coordinate) const override
Inherited from scrollbar_base.
Definition: slider.cpp:156
void handle_key_increase(bool &handled)
Definition: slider.cpp:195
std::function< t_string(int, int)> label_generator
Definition: slider.hpp:131
virtual void set_value(int value) override
Inherited from integer_selector.
Definition: slider.cpp:82
virtual point calculate_best_size() const override
See widget::calculate_best_size.
Definition: slider.cpp:63
int step_size_
Definition: slider.hpp:162
virtual int get_maximum_value() const override
Inherited from integer_selector.
Definition: slider.hpp:91
void set_value_range(int min_value, int max_value)
Definition: slider.cpp:251
virtual int get_value() const override
Inherited from integer_selector.
Definition: slider.hpp:79
label_generator value_label_generator_
Function to output custom value labels for the slider.
Definition: slider.hpp:214
int get_item_count() const
Definition: slider.hpp:97
t_string get_value_label() const
Returns the label shown for the current value.
Definition: slider.cpp:107
int positioner_length() const override
Inherited from scrollbar_base.
Definition: slider.cpp:125
point current_item_mouse_position_
When initially pressing the positioner and every time a new value is chosen through dragging,...
Definition: slider.hpp:221
virtual unsigned get_length() const override
Inherited from scrollbar_base.
Definition: slider.hpp:165
int get_length_difference(const point &original, const point &current) const override
Inherited from scrollbar_base.
Definition: slider.hpp:186
slider(const implementation::builder_slider &builder)
Definition: slider.cpp:45
t_string minimum_value_label_
When the slider shows the minimum value can show a special text.
Definition: slider.hpp:201
bool on_positioner(const point &coordinate) const override
Inherited from scrollbar_base.
Definition: slider.cpp:146
void signal_handler_left_button_up(const event::ui_event event, bool &handled)
Definition: slider.cpp:228
void set_minimum_value_label(const t_string &minimum_value_label)
Definition: slider.hpp:119
virtual const std::string & get_control_type() const override
Inherited from styled_widget, implemented by REGISTER_WIDGET.
void set_value_labels(const label_generator &generator)
Definition: slider.hpp:133
virtual void update_canvas() override
Inherited from scrollbar_base.
Definition: slider.cpp:176
void set_value_labels(const std::vector< t_string > &value_labels)
Definition: slider.cpp:244
unsigned offset_after() const override
Inherited from scrollbar_base.
Definition: slider.cpp:139
void set_best_slider_length(const unsigned length)
Definition: slider.hpp:111
void queue_redraw()
Indicates that this widget should be redrawn.
Definition: widget.cpp:442
unsigned get_width() const
Definition: widget.cpp:326
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.
rng * generator
This generator is automatically synced during synced context.
Definition: random.cpp:61
map_location coordinate
Contains an x and y coordinate used for starting positions in maps.
builder_slider(const config &cfg)
Definition: slider.cpp:323
virtual std::unique_ptr< widget > build() const override
Definition: slider.cpp:344
std::vector< t_string > value_labels_
Definition: slider.hpp:291
virtual std::unique_ptr< widget > build() const=0
Base class of a resolution, contains the common keys for a resolution.
resolution(const config &cfg)
Definition: slider.cpp:304
slider_definition(const config &cfg)
Definition: slider.cpp:296
Holds a 2D point.
Definition: point.hpp:25