The Battle for Wesnoth  1.15.12+dev
slider.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 
19 
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  {
80  return minimum_value_ + get_slider_position() * get_step_size();
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.
93  return minimum_value_ + slider_get_item_last() * step_size_;
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  set_is_dirty(true);
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  {
134  value_label_generator_ = generator;
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 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
Base class of a resolution, contains the common keys for a resolution.
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 widget * build() const =0
std::function< t_string(int, int)> label_generator
Definition: slider.hpp:130
void set_value_labels(const label_generator &generator)
Definition: slider.hpp:132
Base class for all widgets.
Definition: widget.hpp:49
t_string maximum_value_label_
When the slider shows the maximum value can show a special text.
Definition: slider.hpp:206
Small abstract helper class.
int x
x coordinate.
Definition: point.hpp:44
Generic file dialog.
Definition: field-fwd.hpp:22
void set_minimum_value_label(const t_string &minimum_value_label)
Definition: slider.hpp:118
t_string minimum_value_label_
When the slider shows the minimum value can show a special text.
Definition: slider.hpp:200
virtual int get_maximum_value() const override
Inherited from integer_selector.
Definition: slider.hpp:90
int get_item_count() const
Definition: slider.hpp:96
void set_maximum_value_label(const t_string &maximum_value_label)
Definition: slider.hpp:123
Basic template class to generate new items.
unsigned best_slider_length_
The best size for the slider part itself, if 0 ignored.
Definition: slider.hpp:152
int minimum_value_
The minimum value the slider holds.
Definition: slider.hpp:160
Holds a 2D point.
Definition: point.hpp:23
virtual int get_value() const override
Inherited from integer_selector.
Definition: slider.hpp:78
std::vector< t_string > value_labels_
Definition: slider.hpp:290
rng * generator
This generator is automatically synced during synced context.
Definition: random.cpp:60
unsigned get_step_size() const
Definition: slider.hpp:102
label_generator value_label_generator_
Function to output custom value labels for the slider.
Definition: slider.hpp:213
A slider is a control that can select a value by moving a grip on a groove.
Definition: slider.hpp:58
int step_size_
Definition: slider.hpp:161
int get_length_difference(const point &original, const point &current) const override
Inherited from scrollbar_base.
Definition: slider.hpp:185
point resolution()
Definition: general.cpp:387
Base class for a scroll bar.
Definition: slider_base.hpp:39
std::unique_ptr< window > build(const builder_window::window_resolution &definition)
Builds a window.
void set_best_slider_length(const unsigned length)
Definition: slider.hpp:110
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
virtual unsigned get_length() const override
Inherited from scrollbar_base.
Definition: slider.hpp:164
virtual int get_minimum_value() const override
Inherited from integer_selector.
Definition: slider.hpp:84
Contains the implementation details for lexical_cast and shouldn&#39;t be used directly.
ui_event
The event send to the dispatcher.
Definition: handler.hpp:47