The Battle for Wesnoth  1.19.0-dev
slider_base.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 
19 
20 
21 namespace gui2
22 {
23 /**
24  * Base class for a scroll bar.
25  *
26  * class will be subclassed for the horizontal and vertical scroll bar.
27  * It might be subclassed for a slider class.
28  *
29  * To make this class generic we talk a lot about offset and length and use
30  * pure virtual functions. The classes implementing us can use the heights or
31  * widths, whichever is applicable.
32  *
33  * The NOTIFY_MODIFIED event is send when the position of slider is changed.
34  *
35  * Common signal handlers:
36  * - connect_signal_notify_modified
37  */
38 class slider_base : public styled_widget
39 {
40 public:
41  slider_base(const implementation::builder_styled_widget& builder, const std::string& control_type);
42 
43  /**
44  * scroll 'step size'.
45  *
46  * When scrolling we always scroll a 'fixed' amount, these are the
47  * parameters for these amounts.
48  */
49  enum scroll_mode {
50  BEGIN, /**< Go to begin position. */
51  ITEM_BACKWARDS, /**< Go one item towards the begin. */
52  HALF_JUMP_BACKWARDS, /**< Go half the visible items towards the begin. */
53  JUMP_BACKWARDS, /**< Go the visible items towards the begin. */
54  END, /**< Go to the end position. */
55  ITEM_FORWARD, /**< Go one item towards the end. */
56  HALF_JUMP_FORWARD, /**< Go half the visible items towards the end. */
57  JUMP_FORWARD /**< Go the visible items towards the end. */
58  };
59 
60  /** Helper container for the slider's current position. */
62  {
63  int offset;
65  };
66 
67  /**
68  * Sets the item position.
69  *
70  * We scroll a predefined step.
71  *
72  * @param scroll 'step size' to scroll.
73  */
74  void scroll(const scroll_mode scroll);
75 
76 protected:
77  /** Is the positioner at the beginning of the slider? */
78  bool at_begin() const
79  {
80  return item_position_ == 0;
81  }
82 
83  /**
84  * Is the positioner at the and of the slider?
85  *
86  * Note both begin and end might be true at the same time.
87  */
88  bool at_end() const
89  {
90  return item_position_ >= item_last_;
91  }
92 
93  void update_slider_position(slider_position_t& pos);
94 
95 public:
96  void finalize_setup();
97 
98  /***** ***** ***** ***** layout functions ***** ***** ***** *****/
99 
100  /** See @ref widget::place. */
101  virtual void place(const point& origin, const point& size) override;
102 
103  /***** ***** ***** ***** Inherited ***** ***** ***** *****/
104 
105  /** See @ref styled_widget::set_active. */
106  virtual void set_active(const bool active) override;
107 
108  /** See @ref styled_widget::get_active. */
109  virtual bool get_active() const override;
110 
111  /** See @ref styled_widget::get_state. */
112  virtual unsigned get_state() const override;
113 
114  /**
115  * Possible states of the widget.
116  *
117  * Note the order of the states must be the same as defined in settings.hpp.
118  */
120 
121 protected:
122  /***** ***** ***** setters / getters for members ***** ****** *****/
123 
124  void slider_set_item_last(const unsigned item_last)
125  {
126  item_last_ = item_last;
127  recalculate();
128  }
129 
130  unsigned slider_get_item_count() const
131  {
132  return item_last_ + 1;
133  }
134 
135  unsigned slider_get_item_last() const
136  {
137  return item_last_;
138  }
139 
140  /**
141  * Note the position isn't guaranteed to be the wanted position
142  * the step size is honored. The value will be rounded down.
143  */
144  void set_slider_position(int item_position);
145 
146  unsigned get_slider_position() const
147  {
148  return item_position_;
149  }
150 
151  unsigned get_positioner_offset() const
152  {
153  return positioner_offset_;
154  }
155 
156  unsigned get_positioner_length() const
157  {
158  return positioner_length_;
159  }
160 
161  /**
162  * See @ref styled_widget::update_canvas.
163  *
164  * After a recalculation the canvasses also need to be updated.
165  */
166  virtual void update_canvas() override;
167 
168  /**
169  * Callback for subclasses to get notified about positioner movement.
170  *
171  * @todo This is a kind of hack due to the fact there's no simple
172  * callback slot mechanism. See whether we can implement a generic way to
173  * attach callback which would remove quite some extra code.
174  */
176  {
177  }
178 
179  virtual int jump_size() const
180  {
181  return 1;
182  }
183 
184 private:
185  void set_state(const state_t state);
186 
187  /**
188  * Current state of the widget.
189  *
190  * The state of the widget determines what to render and how the widget
191  * reacts to certain 'events'.
192  */
194 
195  /** one less than the number items the slider 'holds'. */
197 
198  /** The item the positioner is at, starts at 0. */
200 
201  /**
202  * The position the mouse was when draggin the slider was started.
203  *
204  * This is used during dragging the positioner.
205  */
207 
208  /**
209  * The offset in pixels the slider was when dragging the positioner was started.
210  */
212 
213  /**
214  * The start offset of the positioner.
215  *
216  * This takes the offset before in consideration.
217  */
219 
220  /** The current length of the positioner. */
222 
223  /** Whether the slider should 'snap' into its supported values or not. */
224  bool snap_;
225 
226  /***** ***** ***** ***** Pure virtual functions ***** ***** ***** *****/
227 
228  /** Get the length of the slider. */
229  virtual unsigned get_length() const = 0;
230 
231  int available_length() const
232  {
233  return get_length() - offset_before() - offset_after();
234  }
235 
236  int max_offset() const
237  {
238  return std::max(0, available_length() - positioner_length());
239  }
240 
241  /**
242  * The number of pixels we can't use since they're used for borders.
243  *
244  * These are the pixels before the widget (left side if horizontal,
245  * top side if vertical).
246  */
247  virtual unsigned offset_before() const = 0;
248 
249  /**
250  * The number of pixels we can't use since they're used for borders.
251  *
252  * These are the pixels after the widget (right side if horizontal,
253  * bottom side if vertical).
254  */
255  virtual unsigned offset_after() const = 0;
256 
257  /**
258  * Is the coordinate on the positioner?
259  *
260  * @param coordinate Coordinate to test whether it's on the
261  * positioner.
262  *
263  * @returns Whether the location on the positioner is.
264  */
265  virtual bool on_positioner(const point& coordinate) const = 0;
266 
267  /**
268  * Is the coordinate on the bar?
269  *
270  * @param coordinate Coordinate to test whether it's on the
271  * bar.
272  *
273  * @returns Whether the location on the bar is.
274  * @retval -1 Coordinate is on the bar before positioner.
275  * @retval 0 Coordinate is not on the bar.
276  * @retval 1 Coordinate is on the bar after the positioner.
277  */
278  virtual int on_bar(const point& coordinate) const = 0;
279 
280  /**
281  * Gets the relevant difference in between the two positions.
282  *
283  * This function is used to determine how much the positioner needs to be
284  * moved.
285  */
286  virtual int get_length_difference(const point& original, const point& current) const = 0;
287 
288  /***** ***** ***** ***** Private functions ***** ***** ***** *****/
289 
290  /**
291  * Updates the slider.
292  *
293  * Needs to be called when something changes eg number of items or available size.
294  * It can only be called once we have a size otherwise we can't calculate a thing.
295  */
296  void recalculate();
297 
298  /**
299  * Updates the positioner.
300  *
301  * This is a helper for recalculate().
302  */
303  virtual int positioner_length() const = 0;
304 
306  {
308  }
309 
310  /**
311  * Moves the positioner.
312  *
313  * @param offset The new offset in pixels of the positioner;
314  */
315  void move_positioner(int offset);
316 
317  /***** ***** ***** signal handlers ***** ****** *****/
318 
319  void signal_handler_mouse_enter(const event::ui_event event, bool& handled, bool& halt);
320 
321  void signal_handler_mouse_motion(const event::ui_event event, bool& handled, bool& halt, const point& coordinate);
322 
323  void signal_handler_mouse_leave(const event::ui_event event, bool& handled);
324 
325  void signal_handler_left_button_down(const event::ui_event event, bool& handled);
326 
327  void signal_handler_left_button_up(const event::ui_event event, bool& handled);
328 };
329 
330 } // namespace gui2
Base class for a scroll bar.
Definition: slider_base.hpp:39
int item_position_
The item the positioner is at, starts at 0.
point drag_initial_mouse_
The position the mouse was when draggin the slider was started.
unsigned slider_get_item_count() const
virtual int positioner_length() const =0
Updates the positioner.
void set_state(const state_t state)
bool at_end() const
Is the positioner at the and of the slider?
Definition: slider_base.hpp:88
virtual unsigned offset_after() const =0
The number of pixels we can't use since they're used for borders.
unsigned slider_get_item_last() const
void signal_handler_mouse_enter(const event::ui_event event, bool &handled, bool &halt)
state_t
Possible states of the widget.
void recalculate_positioner()
virtual int get_length_difference(const point &original, const point &current) const =0
Gets the relevant difference in between the two positions.
bool at_begin() const
Is the positioner at the beginning of the slider?
Definition: slider_base.hpp:78
int drag_initial_offset_
The offset in pixels the slider was when dragging the positioner was started.
virtual void update_canvas() override
See styled_widget::update_canvas.
void signal_handler_left_button_up(const event::ui_event event, bool &handled)
virtual void set_active(const bool active) override
See styled_widget::set_active.
int positioner_offset_
The start offset of the positioner.
void recalculate()
Updates the slider.
virtual bool on_positioner(const point &coordinate) const =0
Is the coordinate on the positioner?
bool snap_
Whether the slider should 'snap' into its supported values or not.
void signal_handler_mouse_motion(const event::ui_event event, bool &handled, bool &halt, const point &coordinate)
int max_offset() const
scroll_mode
scroll 'step size'.
Definition: slider_base.hpp:49
@ ITEM_FORWARD
Go one item towards the end.
Definition: slider_base.hpp:55
@ HALF_JUMP_BACKWARDS
Go half the visible items towards the begin.
Definition: slider_base.hpp:52
@ ITEM_BACKWARDS
Go one item towards the begin.
Definition: slider_base.hpp:51
@ JUMP_BACKWARDS
Go the visible items towards the begin.
Definition: slider_base.hpp:53
@ JUMP_FORWARD
Go the visible items towards the end.
Definition: slider_base.hpp:57
@ BEGIN
Go to begin position.
Definition: slider_base.hpp:50
@ HALF_JUMP_FORWARD
Go half the visible items towards the end.
Definition: slider_base.hpp:56
@ END
Go to the end position.
Definition: slider_base.hpp:54
virtual unsigned get_state() const override
See styled_widget::get_state.
slider_base(const implementation::builder_styled_widget &builder, const std::string &control_type)
Definition: slider_base.cpp:43
int item_last_
one less than the number items the slider 'holds'.
unsigned get_positioner_offset() const
void move_positioner(int offset)
Moves the positioner.
virtual bool get_active() const override
See styled_widget::get_active.
void signal_handler_mouse_leave(const event::ui_event event, bool &handled)
state_t state_
Current state of the widget.
unsigned get_slider_position() const
virtual unsigned offset_before() const =0
The number of pixels we can't use since they're used for borders.
void signal_handler_left_button_down(const event::ui_event event, bool &handled)
int positioner_length_
The current length of the positioner.
void slider_set_item_last(const unsigned item_last)
virtual void child_callback_positioner_moved()
Callback for subclasses to get notified about positioner movement.
void update_slider_position(slider_position_t &pos)
void set_slider_position(int item_position)
Note the position isn't guaranteed to be the wanted position the step size is honored.
void scroll(const scroll_mode scroll)
Sets the item position.
Definition: slider_base.cpp:66
int available_length() const
virtual unsigned get_length() const =0
Get the length of the slider.
virtual int on_bar(const point &coordinate) const =0
Is the coordinate on the bar?
unsigned get_positioner_length() const
virtual int jump_size() const
virtual void place(const point &origin, const point &size) override
See widget::place.
Base class for all visible items.
ui_event
The event sent to the dispatcher.
Definition: handler.hpp:115
Generic file dialog.
map_location coordinate
Contains an x and y coordinate used for starting positions in maps.
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:85
Helper container for the slider's current position.
Definition: slider_base.hpp:62
Holds a 2D point.
Definition: point.hpp:25