Panda3D

pgSliderBar.I
Go to the documentation of this file.
1 /**
2 * PANDA 3D SOFTWARE
3 * Copyright (c) Carnegie Mellon University. All rights reserved.
4 *
5 * All use of this software is subject to the terms of the revised BSD
6 * license. You should have received a copy of this license along
7 * with this source code in a file named "LICENSE."
8 *
9 * @file pgSliderBar.I
10 * @author masad
11 * @date 2004-10-19
12 */
13
14 /**
15 * Sets the object which will be notified when the PGSliderBar changes. Set
16 * this to NULL to disable this effect. The PGSliderBar does not retain
17 * ownership of the pointer; it is your responsibility to ensure that the
18 * notify object does not destruct.
19 */
20 INLINE void PGSliderBar::
21 set_notify(PGSliderBarNotify *notify) {
22 PGItem::set_notify(notify);
23 }
24
25 /**
26 * Returns the object which will be notified when the PGSliderBar changes, if
27 * any. Returns NULL if there is no such object configured.
28 */
29 INLINE PGSliderBarNotify *PGSliderBar::
30 get_notify() const {
31 return (PGSliderBarNotify *)PGItem::get_notify();
32 }
33
34 /**
35 * Specifies the axis of the slider bar's motion. This should be only one of
36 * four vectors: (1, 0, 0), (0, 0, 1), (-1, 0, 0), or (0, 0, -1).
37 *
38 * This specifies the vector in which the thumb moves when it is moving from
39 * the minimum to the maximum value.
40 *
41 * The axis must be parallel to one of the screen axes, and it must be
42 * normalized. Hence, it may only be one of the above four possibilities;
43 * anything else is an error and will result in indeterminate behavior.
44 *
45 * Normally, you should not try to set the axis directly.
46 */
47 INLINE void PGSliderBar::
48 set_axis(const LVector3 &axis) {
49 LightReMutexHolder holder(_lock);
50 _axis = axis;
51 _needs_remanage = true;
52 _needs_recompute = true;
53 }
54
55 /**
56 * Returns the axis of the slider bar's motion. See set_axis().
57 */
58 INLINE const LVector3 &PGSliderBar::
59 get_axis() const {
60 LightReMutexHolder holder(_lock);
61 return _axis;
62 }
63
64 /**
65 * Sets the minimum and maxmimum value for the slider.
66 */
67 INLINE void PGSliderBar::
68 set_range(PN_stdfloat min_value, PN_stdfloat max_value) {
69 LightReMutexHolder holder(_lock);
70 nassertv(min_value != max_value);
71 _min_value = min_value;
72 _max_value = max_value;
73 _needs_recompute = true;
74
75 if (has_notify()) {
76 get_notify()->slider_bar_set_range(this);
77 }
78 }
79
80 /**
81 * Returns the value when the slider is all the way to the left.
82 */
83 INLINE PN_stdfloat PGSliderBar::
84 get_min_value() const {
85 LightReMutexHolder holder(_lock);
86 return _min_value;
87 }
88
89 /**
90 * Returns the value when the slider is all the way to the right.
91 */
92 INLINE PN_stdfloat PGSliderBar::
93 get_max_value() const {
94 LightReMutexHolder holder(_lock);
95 return _max_value;
96 }
97
98 /**
99 * Specifies the amount the slider will move when the user clicks on the left
100 * or right buttons.
101 */
102 INLINE void PGSliderBar::
103 set_scroll_size(PN_stdfloat value) {
104 LightReMutexHolder holder(_lock);
105 _scroll_value = value;
106 _needs_recompute = true;
107 }
108
109 /**
110 * Returns the value last set by set_scroll_size().
111 */
112 INLINE PN_stdfloat PGSliderBar::
113 get_scroll_size() const {
114 LightReMutexHolder holder(_lock);
115 return _scroll_value;
116 }
117
118 /**
119 * Specifies the amount of data contained in a single page. This indicates
120 * how much the thumb will jump when the trough is directly clicked; and if
121 * resize_thumb is true, it also controls the visible size of the thumb
122 * button.
123 */
124 INLINE void PGSliderBar::
125 set_page_size(PN_stdfloat value) {
126 LightReMutexHolder holder(_lock);
127 _page_value = value;
128 _needs_recompute = true;
129 }
130
131 /**
132 * Returns the value last set by set_page_size().
133 */
134 INLINE PN_stdfloat PGSliderBar::
135 get_page_size() const {
136 LightReMutexHolder holder(_lock);
137 return _page_value;
138 }
139
140 /**
141 * Sets the current value of the slider programmatically. This should range
142 * between get_min_value() and get_max_value().
143 */
144 INLINE void PGSliderBar::
145 set_value(PN_stdfloat value) {
146 LightReMutexHolder holder(_lock);
147 set_ratio((value - _min_value) / (_max_value - _min_value));
148 }
149
150 /**
151 * Returns the current value of the slider.
152 */
153 INLINE PN_stdfloat PGSliderBar::
154 get_value() const {
155 LightReMutexHolder holder(_lock);
156 return get_ratio() * (_max_value - _min_value) + _min_value;
157 }
158
159 /**
160 * Sets the current value of the slider, expressed in the range 0 .. 1.
161 */
162 INLINE void PGSliderBar::
163 set_ratio(PN_stdfloat ratio) {
164 LightReMutexHolder holder(_lock);
165 if (!is_button_down()) {
166 internal_set_ratio(ratio);
167 }
168 }
169
170 /**
171 * Returns the current value of the slider, expressed in the range 0 .. 1.
172 */
173 INLINE PN_stdfloat PGSliderBar::
174 get_ratio() const {
175 LightReMutexHolder holder(_lock);
176 return _ratio;
177 }
178
179 /**
180 * Returns true if the user is currently holding down the mouse button to
181 * manipulate the slider. When true, calls to set_ratio() or set_value() will
182 * have no effect.
183 */
184 INLINE bool PGSliderBar::
185 is_button_down() const {
186 LightReMutexHolder holder(_lock);
187 return _dragging || _mouse_button_page ||
188 (_scroll_button_held != nullptr);
189 }
190
191 /**
192 * Sets the resize_thumb flag. When this is true, the thumb button's frame
193 * will be adjusted so that its width visually represents the page size. When
194 * this is false, the thumb button will be left alone.
195 */
196 INLINE void PGSliderBar::
197 set_resize_thumb(bool resize_thumb) {
198 LightReMutexHolder holder(_lock);
199 _resize_thumb = resize_thumb;
200 _needs_recompute = true;
201 }
202
203 /**
204 * Returns the resize_thumb flag. See set_resize_thumb().
205 */
206 INLINE bool PGSliderBar::
207 get_resize_thumb() const {
208 LightReMutexHolder holder(_lock);
209 return _resize_thumb;
210 }
211
212 /**
213 * Sets the manage_pieces flag. When this is true, the sub-pieces of the
214 * slider bar--that is, the thumb, and the left and right scroll buttons--are
215 * automatically positioned and/or resized when the slider bar's overall frame
216 * is changed.
217 */
218 INLINE void PGSliderBar::
219 set_manage_pieces(bool manage_pieces) {
220 LightReMutexHolder holder(_lock);
221 _manage_pieces = manage_pieces;
222 _needs_remanage = true;
223 _needs_recompute = true;
224 }
225
226 /**
227 * Returns the manage_pieces flag. See set_manage_pieces().
228 */
229 INLINE bool PGSliderBar::
230 get_manage_pieces() const {
231 LightReMutexHolder holder(_lock);
232 return _manage_pieces;
233 }
234
235 /**
236 * Sets the PGButton object that will serve as the thumb for this slider.
237 * This button visually represents the position of the slider, and can be
238 * dragged left and right by the user.
239 *
240 * It is the responsibility of the caller to ensure that the button object is
241 * parented to the PGSliderBar node.
242 */
243 INLINE void PGSliderBar::
244 set_thumb_button(PGButton *thumb_button) {
245 LightReMutexHolder holder(_lock);
246 if (_thumb_button != nullptr) {
247 _thumb_button->set_notify(nullptr);
248 }
249 _thumb_button = thumb_button;
250 if (_thumb_button != nullptr) {
251 _thumb_button->set_notify(this);
252 }
253 _needs_remanage = true;
254 _needs_recompute = true;
255 }
256
257 /**
258 * Removes the thumb button object from control of the frame. It is your
259 * responsibility to actually remove or hide the button itself.
260 */
261 INLINE void PGSliderBar::
262 clear_thumb_button() {
263 set_thumb_button(nullptr);
264 }
265
266 /**
267 * Returns the PGButton that serves as the thumb for this slider, or NULL if
268 * it is not set.
269 */
270 INLINE PGButton *PGSliderBar::
271 get_thumb_button() const {
272 LightReMutexHolder holder(_lock);
273 return _thumb_button;
274 }
275
276 /**
277 * Sets the PGButton object that will serve as the left scroll button for this
278 * slider. This button is optional; if present, the user can click on it to
279 * move scroll_size units at a time to the left.
280 *
281 * It is the responsibility of the caller to ensure that the button object is
282 * parented to the PGSliderBar node.
283 */
284 INLINE void PGSliderBar::
285 set_left_button(PGButton *left_button) {
286 LightReMutexHolder holder(_lock);
287 if (_left_button != nullptr) {
288 _left_button->set_notify(nullptr);
289 }
290 _left_button = left_button;
291 if (_left_button != nullptr) {
292 _left_button->set_notify(this);
293 }
294 _needs_remanage = true;
295 _needs_recompute = true;
296 }
297
298 /**
299 * Removes the left button object from control of the frame. It is your
300 * responsibility to actually remove or hide the button itself.
301 */
302 INLINE void PGSliderBar::
303 clear_left_button() {
304 set_left_button(nullptr);
305 }
306
307 /**
308 * Returns the PGButton that serves as the left scroll button for this slider,
309 * if any, or NULL if it is not set.
310 */
311 INLINE PGButton *PGSliderBar::
312 get_left_button() const {
313 LightReMutexHolder holder(_lock);
314 return _left_button;
315 }
316
317 /**
318 * Sets the PGButton object that will serve as the right scroll button for
319 * this slider. This button is optional; if present, the user can click on it
320 * to move scroll_size units at a time to the right.
321 *
322 * It is the responsibility of the caller to ensure that the button object is
323 * parented to the PGSliderBar node.
324 */
325 INLINE void PGSliderBar::
326 set_right_button(PGButton *right_button) {
327 LightReMutexHolder holder(_lock);
328 if (_right_button != nullptr) {
329 _right_button->set_notify(nullptr);
330 }
331 _right_button = right_button;
332 if (_right_button != nullptr) {
333 _right_button->set_notify(this);
334 }
335 _needs_remanage = true;
336 _needs_recompute = true;
337 }
338
339 /**
340 * Removes the right button object from control of the frame. It is your
341 * responsibility to actually remove or hide the button itself.
342 */
343 INLINE void PGSliderBar::
344 clear_right_button() {
345 set_right_button(nullptr);
346 }
347
348 /**
349 * Returns the PGButton that serves as the right scroll button for this
350 * slider, if any, or NULL if it is not set.
351 */
352 INLINE PGButton *PGSliderBar::
353 get_right_button() const {
354 LightReMutexHolder holder(_lock);
355 return _right_button;
356 }
357
358 /**
359 * Returns the prefix that is used to define the adjust event for all
360 * PGSliderBars. The adjust event is the concatenation of this string
361 * followed by get_id().
362 */
363 INLINE std::string PGSliderBar::
364 get_adjust_prefix() {
365 return "adjust-";
366 }
367
368 /**
369 * Returns the event name that will be thrown when the slider bar value is
370 * adjusted by the user or programmatically.
371 */
372 INLINE std::string PGSliderBar::
373 get_adjust_event() const {
374 LightReMutexHolder holder(_lock);
375 return get_adjust_prefix() + get_id();
376 }
377
378 /**
379 * Sets the current value of the slider, expressed in the range 0 .. 1,
380 * without checking whether the user is currently manipulating the slider.
381 */
382 INLINE void PGSliderBar::
383 internal_set_ratio(PN_stdfloat ratio) {
384 _ratio = std::max(std::min(ratio, (PN_stdfloat)1.0), (PN_stdfloat)0.0);
385 _needs_reposition = true;
386 adjust();
387 }
LightReMutexHolder
Similar to MutexHolder, but for a light reentrant mutex.
Definition: lightReMutexHolder.h:25
PGButton
This is a particular kind of PGItem that is specialized to behave like a normal button object.
Definition: pgButton.h:29
PGButton::set_notify
void set_notify(PGButtonNotify *notify)
Sets the object which will be notified when the PGButton changes.
Definition: pgButton.I:21
PGItem::set_notify
void set_notify(PGItemNotify *notify)
Sets the object which will be notified when the PGItem changes.
Definition: pgItem.I:43
PGItem::get_notify
PGItemNotify * get_notify() const
Returns the object which will be notified when the PGItem changes, if any.
Definition: pgItem.I:69
PGItem::get_id
const std::string & get_id() const
Returns the unique ID assigned to this PGItem.
Definition: pgItem.I:224
PGItem::has_notify
bool has_notify() const
Returns true if there is an object configured to be notified when the PGItem changes,...
Definition: pgItem.I:59
PGSliderBarNotify
Objects that inherit from this class can receive notify messages when a slider bar moves or otherwise...
Definition: pgSliderBarNotify.h:26
PGSliderBar::get_scroll_size
PN_stdfloat get_scroll_size() const
Returns the value last set by set_scroll_size().
Definition: pgSliderBar.I:113
PGSliderBar::set_resize_thumb
void set_resize_thumb(bool resize_thumb)
Sets the resize_thumb flag.
Definition: pgSliderBar.I:197
PGSliderBar::clear_left_button
void clear_left_button()
Removes the left button object from control of the frame.
Definition: pgSliderBar.I:303
PGSliderBar::get_axis
const LVector3 & get_axis() const
Returns the axis of the slider bar's motion.
Definition: pgSliderBar.I:59
PGSliderBar::get_manage_pieces
bool get_manage_pieces() const
Returns the manage_pieces flag.
Definition: pgSliderBar.I:230
PGSliderBar::is_button_down
bool is_button_down() const
Returns true if the user is currently holding down the mouse button to manipulate the slider.
Definition: pgSliderBar.I:185
PGSliderBar::set_scroll_size
void set_scroll_size(PN_stdfloat scroll_size)
Specifies the amount the slider will move when the user clicks on the left or right buttons.
Definition: pgSliderBar.I:103
PGSliderBar::set_page_size
void set_page_size(PN_stdfloat page_size)
Specifies the amount of data contained in a single page.
Definition: pgSliderBar.I:125
PGSliderBar::get_max_value
PN_stdfloat get_max_value() const
Returns the value when the slider is all the way to the right.
Definition: pgSliderBar.I:93
PGSliderBar::set_notify
void set_notify(PGSliderBarNotify *notify)
Sets the object which will be notified when the PGSliderBar changes.
Definition: pgSliderBar.I:21
PGSliderBar::set_thumb_button
void set_thumb_button(PGButton *thumb_button)
Sets the PGButton object that will serve as the thumb for this slider.
Definition: pgSliderBar.I:244
PGSliderBar::adjust
virtual void adjust()
This is a callback hook function, called whenever the slider value is adjusted by the user or program...
Definition: pgSliderBar.cxx:228
PGSliderBar::set_axis
void set_axis(const LVector3 &axis)
Specifies the axis of the slider bar's motion.
Definition: pgSliderBar.I:48
PGSliderBar::get_value
PN_stdfloat get_value() const
Returns the current value of the slider.
Definition: pgSliderBar.I:154
PGSliderBar::set_ratio
void set_ratio(PN_stdfloat ratio)
Sets the current value of the slider, expressed in the range 0 .
Definition: pgSliderBar.I:163
PGSliderBar::get_thumb_button
PGButton * get_thumb_button() const
Returns the PGButton that serves as the thumb for this slider, or NULL if it is not set.
Definition: pgSliderBar.I:271
PGSliderBar::get_adjust_prefix
static std::string get_adjust_prefix()
Returns the prefix that is used to define the adjust event for all PGSliderBars.
Definition: pgSliderBar.I:364
PGSliderBar::set_left_button
void set_left_button(PGButton *left_button)
Sets the PGButton object that will serve as the left scroll button for this slider.
Definition: pgSliderBar.I:285
PGSliderBar::get_right_button
PGButton * get_right_button() const
Returns the PGButton that serves as the right scroll button for this slider, if any,...
Definition: pgSliderBar.I:353
PGSliderBar::clear_thumb_button
void clear_thumb_button()
Removes the thumb button object from control of the frame.
Definition: pgSliderBar.I:262
PGSliderBar::get_page_size
PN_stdfloat get_page_size() const
Returns the value last set by set_page_size().
Definition: pgSliderBar.I:135
PGSliderBar::get_ratio
PN_stdfloat get_ratio() const
Returns the current value of the slider, expressed in the range 0 .
Definition: pgSliderBar.I:174
PGSliderBar::get_resize_thumb
bool get_resize_thumb() const
Returns the resize_thumb flag.
Definition: pgSliderBar.I:207
PGSliderBar::set_range
void set_range(PN_stdfloat min_value, PN_stdfloat max_value)
Sets the minimum and maxmimum value for the slider.
Definition: pgSliderBar.I:68
PGSliderBar::get_notify
PGSliderBarNotify * get_notify() const
Returns the object which will be notified when the PGSliderBar changes, if any.
Definition: pgSliderBar.I:30
PGSliderBar::set_manage_pieces
void set_manage_pieces(bool manage_pieces)
Sets the manage_pieces flag.
Definition: pgSliderBar.I:219
PGSliderBar::clear_right_button
void clear_right_button()
Removes the right button object from control of the frame.
Definition: pgSliderBar.I:344
PGSliderBar::get_adjust_event
std::string get_adjust_event() const
Returns the event name that will be thrown when the slider bar value is adjusted by the user or progr...
Definition: pgSliderBar.I:373
PGSliderBar::get_left_button
PGButton * get_left_button() const
Returns the PGButton that serves as the left scroll button for this slider, if any,...
Definition: pgSliderBar.I:312
PGSliderBar::set_right_button
void set_right_button(PGButton *right_button)
Sets the PGButton object that will serve as the right scroll button for this slider.
Definition: pgSliderBar.I:326
PGSliderBar::set_value
void set_value(PN_stdfloat value)
Sets the current value of the slider programmatically.
Definition: pgSliderBar.I:145
PGSliderBar::get_min_value
PN_stdfloat get_min_value() const
Returns the value when the slider is all the way to the left.
Definition: pgSliderBar.I:84