Panda3D
Loading...
Searching...
No Matches
mouseWatcher.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 mouseWatcher.I
10 * @author drose
11 * @date 2002-03-12
12 */
13
14/**
15 * Returns true if the mouse is anywhere within the window, false otherwise.
16 * Also see is_mouse_open().
17 */
18INLINE bool MouseWatcher::
19has_mouse() const {
20 return _has_mouse;
21}
22
23/**
24 * Returns true if the mouse is within the window and not over some particular
25 * MouseWatcherRegion that is marked to suppress mouse events; that is, that
26 * the mouse is in open space within the window.
27 */
28INLINE bool MouseWatcher::
29is_mouse_open() const {
30 return _has_mouse && (_internal_suppress & MouseWatcherRegion::SF_mouse_position) == 0;
31}
32
33/**
34 * It is only valid to call this if has_mouse() returns true. If so, this
35 * returns the current position of the mouse within the window.
36 */
37INLINE const LPoint2 &MouseWatcher::
38get_mouse() const {
39#ifndef NDEBUG
40 static LPoint2 bogus_mouse(0.0f, 0.0f);
41 nassertr(_has_mouse, bogus_mouse);
42#endif
43 return _mouse;
44}
45
46/**
47 * It is only valid to call this if has_mouse() returns true. If so, this
48 * returns the current X position of the mouse within the window.
49 */
50INLINE PN_stdfloat MouseWatcher::
51get_mouse_x() const {
52 nassertr(_has_mouse, 0.0f);
53 return _mouse[0];
54}
55
56/**
57 * It is only valid to call this if has_mouse() returns true. If so, this
58 * returns the current Y position of the mouse within the window.
59 */
60INLINE PN_stdfloat MouseWatcher::
61get_mouse_y() const {
62 nassertr(_has_mouse, 0.0f);
63 return _mouse[1];
64}
65
66/**
67 * Sets the frame of the MouseWatcher. See the next flavor of this method for
68 * a more verbose explanation.
69 */
70INLINE void MouseWatcher::
71set_frame(PN_stdfloat left, PN_stdfloat right, PN_stdfloat bottom, PN_stdfloat top) {
72 set_frame(LVecBase4(left, right, bottom, top));
73}
74
75/**
76 * Sets the frame of the MouseWatcher. This determines the coordinate space
77 * in which the MouseWatcherRegions should be expected to live. Normally,
78 * this is left at -1, 1, -1, 1, which is the default setting, and matches the
79 * mouse coordinate range.
80 *
81 * Whatever values you specify here indicate the shape of the full screen, and
82 * the MouseWatcherRegions will be given in coordinate space matching it. For
83 * instance, if you specify (0, 1, 0, 1), then a MouseWatcherRegion with the
84 * frame (0, 1, 0, .5) will cover the lower half of the screen.
85 */
86INLINE void MouseWatcher::
87set_frame(const LVecBase4 &frame) {
88 _frame = frame;
89}
90
91/**
92 * Returns the frame of the MouseWatcher. See set_frame().
93 */
94INLINE const LVecBase4 &MouseWatcher::
95get_frame() const {
96 return _frame;
97}
98
99/**
100 * Returns true if the mouse is over any rectangular region, false otherwise.
101 */
102INLINE bool MouseWatcher::
103is_over_region() const {
104 return get_over_region() != nullptr;
105}
106
107/**
108 * Returns true if the mouse is over any rectangular region, false otherwise.
109 */
110INLINE bool MouseWatcher::
111is_over_region(PN_stdfloat x, PN_stdfloat y) const {
112 return get_over_region(x, y) != nullptr;
113}
114
115/**
116 * Returns true if the mouse is over any rectangular region, false otherwise.
117 */
118INLINE bool MouseWatcher::
119is_over_region(const LPoint2 &pos) const {
120 return get_over_region(pos) != nullptr;
121}
122
123/**
124 * Returns the smallest region the mouse is currently over, or NULL if it is
125 * over no region.
126 */
128get_over_region() const {
129 return _preferred_region;
130}
131
132/**
133 * Returns the smallest region the indicated point is over, or NULL if it is
134 * over no region.
135 */
137get_over_region(PN_stdfloat x, PN_stdfloat y) const {
138 return get_over_region(LPoint2(x, y));
139}
140
141/**
142 * Returns true if the indicated button is currently being held down, false
143 * otherwise.
144 */
145INLINE bool MouseWatcher::
146is_button_down(ButtonHandle button) const {
147 return _inactivity_state != IS_inactive && _current_buttons_down.get_bit(button.get_index());
148}
149
150/**
151 * Sets the pattern string that indicates how the event names are generated
152 * when a button is depressed. This is a string that may contain any of the
153 * following:
154 *
155 * %r - the name of the region the mouse is over %b - the name of the button
156 * pressed.
157 *
158 * The event name will be based on the in_pattern string specified here, with
159 * all occurrences of the above strings replaced with the corresponding
160 * values.
161 */
162INLINE void MouseWatcher::
163set_button_down_pattern(const std::string &pattern) {
164 _button_down_pattern = pattern;
165}
166
167/**
168 * Returns the string that indicates how event names are generated when a
169 * button is depressed. See set_button_down_pattern().
170 */
171INLINE const std::string &MouseWatcher::
173 return _button_down_pattern;
174}
175
176/**
177 * Sets the pattern string that indicates how the event names are generated
178 * when a button is released. See set_button_down_pattern().
179 */
180INLINE void MouseWatcher::
181set_button_up_pattern(const std::string &pattern) {
182 _button_up_pattern = pattern;
183}
184
185/**
186 * Returns the string that indicates how event names are generated when a
187 * button is released. See set_button_down_pattern().
188 */
189INLINE const std::string &MouseWatcher::
190get_button_up_pattern() const {
191 return _button_up_pattern;
192}
193
194/**
195 * Sets the pattern string that indicates how the event names are generated
196 * when a button is continuously held and generates keyrepeat "down" events.
197 * This is a string that may contain any of the following:
198 *
199 * %r - the name of the region the mouse is over %b - the name of the button
200 * pressed.
201 *
202 * The event name will be based on the in_pattern string specified here, with
203 * all occurrences of the above strings replaced with the corresponding
204 * values.
205 */
206INLINE void MouseWatcher::
207set_button_repeat_pattern(const std::string &pattern) {
208 _button_repeat_pattern = pattern;
209}
210
211/**
212 * Returns the string that indicates how event names are names are generated
213 * when a button is continuously held and generates keyrepeat "down" events.
214 * See set_button_repeat_pattern().
215 */
216INLINE const std::string &MouseWatcher::
218 return _button_repeat_pattern;
219}
220
221/**
222 * Sets the pattern string that indicates how the event names are generated
223 * when the mouse enters a region. This is different from within_pattern, in
224 * that a mouse is only "entered" in the topmost region at a given time, while
225 * it might be "within" multiple nested regions.
226 */
227INLINE void MouseWatcher::
228set_enter_pattern(const std::string &pattern) {
229 _enter_pattern = pattern;
230}
231
232/**
233 * Returns the string that indicates how event names are generated when the
234 * mouse enters a region. This is different from within_pattern, in that a
235 * mouse is only "entered" in the topmost region at a given time, while it
236 * might be "within" multiple nested regions.
237 */
238INLINE const std::string &MouseWatcher::
239get_enter_pattern() const {
240 return _enter_pattern;
241}
242
243/**
244 * Sets the pattern string that indicates how the event names are generated
245 * when the mouse leaves a region. This is different from without_pattern, in
246 * that a mouse is only "entered" in the topmost region at a given time, while
247 * it might be "within" multiple nested regions.
248 */
249INLINE void MouseWatcher::
250set_leave_pattern(const std::string &pattern) {
251 _leave_pattern = pattern;
252}
253
254/**
255 * Returns the string that indicates how event names are generated when the
256 * mouse leaves a region. This is different from without_pattern, in that a
257 * mouse is only "entered" in the topmost region at a given time, while it
258 * might be "within" multiple nested regions.
259 */
260INLINE const std::string &MouseWatcher::
261get_leave_pattern() const {
262 return _leave_pattern;
263}
264
265/**
266 * Sets the pattern string that indicates how the event names are generated
267 * when the mouse wanders over a region. This is different from
268 * enter_pattern, in that a mouse is only "entered" in the topmost region at a
269 * given time, while it might be "within" multiple nested regions.
270 */
271INLINE void MouseWatcher::
272set_within_pattern(const std::string &pattern) {
273 _within_pattern = pattern;
274}
275
276/**
277 * Returns the string that indicates how event names are generated when the
278 * mouse wanders over a region. This is different from enter_pattern, in that
279 * a mouse is only "entered" in the topmost region at a given time, while it
280 * might be "within" multiple nested regions.
281 */
282INLINE const std::string &MouseWatcher::
283get_within_pattern() const {
284 return _within_pattern;
285}
286
287/**
288 * Sets the pattern string that indicates how the event names are generated
289 * when the mouse wanders out of a region. This is different from
290 * leave_pattern, in that a mouse is only "entered" in the topmost region at a
291 * given time, while it might be "within" multiple nested regions.
292 */
293INLINE void MouseWatcher::
294set_without_pattern(const std::string &pattern) {
295 _without_pattern = pattern;
296}
297
298/**
299 * Returns the string that indicates how event names are generated when the
300 * mouse wanders out of a region. This is different from leave_pattern, in
301 * that a mouse is only "entered" in the topmost region at a given time, while
302 * it might be "within" multiple nested regions.
303 */
304INLINE const std::string &MouseWatcher::
305get_without_pattern() const {
306 return _without_pattern;
307}
308
309/**
310 * Sets the node that will be transformed each frame by the mouse's
311 * coordinates. It will also be hidden when the mouse goes outside the
312 * window. This can be used to implement a software mouse pointer for when a
313 * hardware (or system) mouse pointer is unavailable.
314 */
315INLINE void MouseWatcher::
316set_geometry(PandaNode *node) {
317 _geometry = node;
318}
319
320/**
321 * Returns true if a software mouse pointer has been setup via set_geometry(),
322 * or false otherwise. See set_geometry().
323 */
324INLINE bool MouseWatcher::
325has_geometry() const {
326 return !_geometry.is_null();
327}
328
329/**
330 * Returns the node that has been set as the software mouse pointer, or NULL
331 * if no node has been set. See has_geometry() and set_geometry().
332 */
334get_geometry() const {
335 return _geometry;
336}
337
338/**
339 * Stops the use of the software cursor set up via set_geometry().
340 */
341INLINE void MouseWatcher::
343 _geometry.clear();
344}
345
346/**
347 * As an optimization for the C++ Gui, an extra handler can be registered with
348 * a mouseWatcher so that events can be dealt with much sooner.
349 */
350INLINE void MouseWatcher::
352 _eh = eh;
353}
354
355/**
356 * As an optimization for the C++ Gui, an extra handler can be registered with
357 * a mouseWatcher so that events can be dealt with much sooner.
358 */
360get_extra_handler() const {
361 return _eh;
362}
363
364/**
365 * Sets the buttons that should be monitored as modifier buttons for
366 * generating events to the MouseWatcherRegions.
367 */
368INLINE void MouseWatcher::
370 _mods = mods;
371}
372
373/**
374 * Returns the set of buttons that are being monitored as modifier buttons, as
375 * well as their current state.
376 */
378get_modifier_buttons() const {
379 return _mods;
380}
381
382/**
383 * Constrains the MouseWatcher to watching the mouse within a particular
384 * indicated region of the screen. DataNodes parented under the MouseWatcher
385 * will observe the mouse and keyboard events only when the mouse is within
386 * the indicated region, and the observed range will be from -1 .. 1 across
387 * the region.
388 *
389 * Do not delete the DisplayRegion while it is owned by the MouseWatcher.
390 */
391INLINE void MouseWatcher::
393 _display_region = dr;
394 _button_down_display_region = nullptr;
395}
396
397/**
398 * Removes the display region constraint from the MouseWatcher, and restores
399 * it to the default behavior of watching the whole window.
400 */
401INLINE void MouseWatcher::
403 _display_region = nullptr;
404 _button_down_display_region = nullptr;
405}
406
407/**
408 * Returns the display region the MouseWatcher is constrained to by
409 * set_display_region(), or NULL if it is not constrained.
410 */
412get_display_region() const {
413 return _display_region;
414}
415
416/**
417 * Returns true if the MouseWatcher has been constrained to a particular
418 * region of the screen via set_display_region(), or false otherwise. If this
419 * returns true, get_display_region() may be used to return the particular
420 * region.
421 */
422INLINE bool MouseWatcher::
423has_display_region() const {
424 return (_display_region != nullptr);
425}
426
427/**
428 * Sets an inactivity timeout on the mouse activity. When this timeout (in
429 * seconds) is exceeded with no keyboard or mouse activity, all currently-held
430 * buttons are automatically released. This is intended to help protect
431 * against people who inadvertently (or intentionally) leave a keyboard key
432 * stuck down and then wander away from the keyboard.
433 *
434 * Also, when this timeout expires, the event specified by
435 * set_inactivity_timeout_event() will be generated.
436 */
437INLINE void MouseWatcher::
438set_inactivity_timeout(double timeout) {
439 _has_inactivity_timeout = true;
440 _inactivity_timeout = timeout;
442}
443
444/**
445 * Returns true if an inactivity timeout has been set, false otherwise.
446 */
447INLINE bool MouseWatcher::
449 return _has_inactivity_timeout;
450}
451
452/**
453 * Returns the inactivity timeout that has been set. It is an error to call
454 * this if has_inactivity_timeout() returns false.
455 */
456INLINE double MouseWatcher::
458 nassertr(_has_inactivity_timeout, 0.0);
459 return _inactivity_timeout;
460}
461
462/**
463 * Removes the inactivity timeout and restores the MouseWatcher to its default
464 * behavior of allowing a key to be held indefinitely.
465 */
466INLINE void MouseWatcher::
468 _has_inactivity_timeout = false;
469 _inactivity_timeout = 0.0;
471}
472
473/**
474 * Specifies the event string that will be generated when the inactivity
475 * timeout counter expires. See set_inactivity_timeout().
476 */
477INLINE void MouseWatcher::
478set_inactivity_timeout_event(const std::string &event) {
479 _inactivity_timeout_event = event;
480}
481
482/**
483 * Returns the event string that will be generated when the inactivity timeout
484 * counter expires. See set_inactivity_timeout().
485 */
486INLINE const std::string &MouseWatcher::
488 return _inactivity_timeout_event;
489}
490
491/**
492 * Called internally to indicate the mouse pointer has moved within the
493 * indicated region's boundaries.
494 */
495INLINE void MouseWatcher::
496within_region(MouseWatcherRegion *region, const MouseWatcherParameter &param) {
497 region->within_region(param);
498 throw_event_pattern(_within_pattern, region, ButtonHandle::none());
499 if (_enter_multiple) {
500 enter_region(region, param);
501 }
502}
503
504/**
505 * Called internally to indicate the mouse pointer has moved outside of the
506 * indicated region's boundaries.
507 */
508INLINE void MouseWatcher::
509without_region(MouseWatcherRegion *region, const MouseWatcherParameter &param) {
510 if (_enter_multiple) {
511 exit_region(region, param);
512 }
513 region->without_region(param);
514 throw_event_pattern(_without_pattern, region, ButtonHandle::none());
515}
516
517/**
518 * Clears the mouse trail log. This does not prevent further accumulation of
519 * the log given future events.
520 */
521INLINE void MouseWatcher::
523 _trail_log->clear();
524}
525
526/**
527 * Obtain the mouse trail log. This is a PointerEventList. Does not make a
528 * copy, therefore, this PointerEventList will be updated each time
529 * process_events gets called.
530 *
531 * To use trail logging, you need to enable the generation of pointer events
532 * in the GraphicsWindowInputDevice and set the trail log duration in the
533 * MouseWatcher. Otherwise, the trail log will be empty.
534 */
535INLINE CPT(PointerEventList) MouseWatcher::
536get_trail_log() const {
537 return _trail_log;
538}
539
540/**
541 * This counter indicates how many events were added to the trail log this
542 * frame. The trail log is updated once per frame, during the process_events
543 * operation.
544 */
545INLINE size_t MouseWatcher::
546num_trail_recent() const {
547 return _num_trail_recent;
548}
bool get_bit(int index) const
Returns true if the nth bit is set, false if it is cleared.
Definition bitArray.I:99
A ButtonHandle represents a single button from any device, including keyboard buttons and mouse butto...
get_index
Returns the integer index associated with this ButtonHandle.
A rectangular subregion within a window for rendering into.
A class to monitor events from the C++ side of things.
This class monitors the state of a number of individual buttons and tracks whether each button is kno...
This is sent along as a parameter to most events generated for a region to indicate the mouse and but...
This is the class that defines a rectangular region on the screen for the MouseWatcher.
virtual void within_region(const MouseWatcherParameter &param)
This is a callback hook function, called whenever the mouse moves within the boundaries of the region...
virtual void without_region(const MouseWatcherParameter &param)
This is a callback hook function, called whenever the mouse moves completely outside the boundaries o...
void set_enter_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when the mouse enters a regi...
void set_button_down_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when a button is depressed.
const std::string & get_within_pattern() const
Returns the string that indicates how event names are generated when the mouse wanders over a region.
void set_frame(PN_stdfloat left, PN_stdfloat right, PN_stdfloat bottom, PN_stdfloat top)
Sets the frame of the MouseWatcher.
const std::string & get_button_up_pattern() const
Returns the string that indicates how event names are generated when a button is released.
bool is_mouse_open() const
Returns true if the mouse is within the window and not over some particular MouseWatcherRegion that i...
bool has_geometry() const
Returns true if a software mouse pointer has been setup via set_geometry(), or false otherwise.
void clear_geometry()
Stops the use of the software cursor set up via set_geometry().
const std::string & get_without_pattern() const
Returns the string that indicates how event names are generated when the mouse wanders out of a regio...
void set_inactivity_timeout_event(const std::string &event)
Specifies the event string that will be generated when the inactivity timeout counter expires.
bool has_inactivity_timeout() const
Returns true if an inactivity timeout has been set, false otherwise.
void clear_inactivity_timeout()
Removes the inactivity timeout and restores the MouseWatcher to its default behavior of allowing a ke...
bool has_display_region() const
Returns true if the MouseWatcher has been constrained to a particular region of the screen via set_di...
void note_activity()
Can be used in conjunction with the inactivity timeout to inform the MouseWatcher that the user has j...
const std::string & get_leave_pattern() const
Returns the string that indicates how event names are generated when the mouse leaves a region.
PN_stdfloat get_mouse_x() const
It is only valid to call this if has_mouse() returns true.
void set_leave_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when the mouse leaves a regi...
bool is_button_down(ButtonHandle button) const
Returns true if the indicated button is currently being held down, false otherwise.
void set_modifier_buttons(const ModifierButtons &mods)
Sets the buttons that should be monitored as modifier buttons for generating events to the MouseWatch...
void set_within_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when the mouse wanders over ...
void set_inactivity_timeout(double timeout)
Sets an inactivity timeout on the mouse activity.
const std::string & get_enter_pattern() const
Returns the string that indicates how event names are generated when the mouse enters a region.
const LPoint2 & get_mouse() const
It is only valid to call this if has_mouse() returns true.
void set_button_repeat_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when a button is continuousl...
double get_inactivity_timeout() const
Returns the inactivity timeout that has been set.
const std::string & get_inactivity_timeout_event() const
Returns the event string that will be generated when the inactivity timeout counter expires.
MouseWatcherRegion * get_over_region() const
Returns the smallest region the mouse is currently over, or NULL if it is over no region.
DisplayRegion * get_display_region() const
Returns the display region the MouseWatcher is constrained to by set_display_region(),...
void set_geometry(PandaNode *node)
Sets the node that will be transformed each frame by the mouse's coordinates.
void set_without_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when the mouse wanders out o...
bool has_mouse() const
Returns true if the mouse is anywhere within the window, false otherwise.
const std::string & get_button_repeat_pattern() const
Returns the string that indicates how event names are names are generated when a button is continuous...
bool is_over_region() const
Returns true if the mouse is over any rectangular region, false otherwise.
EventHandler * get_extra_handler() const
As an optimization for the C++ Gui, an extra handler can be registered with a mouseWatcher so that ev...
PandaNode * get_geometry() const
Returns the node that has been set as the software mouse pointer, or NULL if no node has been set.
const std::string & get_button_down_pattern() const
Returns the string that indicates how event names are generated when a button is depressed.
PN_stdfloat get_mouse_y() const
It is only valid to call this if has_mouse() returns true.
void clear_trail_log()
Clears the mouse trail log.
void clear_display_region()
Removes the display region constraint from the MouseWatcher, and restores it to the default behavior ...
const LVecBase4 & get_frame() const
Returns the frame of the MouseWatcher.
ModifierButtons get_modifier_buttons() const
Returns the set of buttons that are being monitored as modifier buttons, as well as their current sta...
void set_extra_handler(EventHandler *eh)
As an optimization for the C++ Gui, an extra handler can be registered with a mouseWatcher so that ev...
void set_display_region(DisplayRegion *dr)
Constrains the MouseWatcher to watching the mouse within a particular indicated region of the screen.
void set_button_up_pattern(const std::string &pattern)
Sets the pattern string that indicates how the event names are generated when a button is released.
A basic node of the scene graph or data graph.
Definition pandaNode.h:65
Records a set of pointer events that happened recently.