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