Panda3D
pgItem.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 pgItem.I
10 * @author drose
11 * @date 2002-03-13
12 */
13
14/**
15 *
16 */
17INLINE void PGItem::
18set_name(const std::string &name) {
19 Namable::set_name(name);
20 _lock.set_name(name);
21}
22
23/**
24 * Returns the MouseWatcherRegion associated with this item. Every PGItem has
25 * a MouseWatcherRegion associated with it, that is created when the PGItem is
26 * created; it does not change during the lifetime of the PGItem. Even items
27 * that do not have a frame have an associated MouseWatcherRegion, although it
28 * will not be used in this case.
29 */
31get_region() const {
32 LightReMutexHolder holder(_lock);
33 return _region;
34}
35
36/**
37 * Sets the object which will be notified when the PGItem changes. Set this
38 * to NULL to disable this effect. The PGItem does not retain ownership of
39 * the pointer; it is your responsibility to ensure that the notify object
40 * does not destruct.
41 */
42INLINE void PGItem::
43set_notify(PGItemNotify *notify) {
44 LightReMutexHolder holder(_lock);
45 if (_notify != nullptr) {
46 _notify->remove_item(this);
47 }
48 _notify = notify;
49 if (_notify != nullptr) {
50 _notify->add_item(this);
51 }
52}
53
54/**
55 * Returns true if there is an object configured to be notified when the
56 * PGItem changes, false otherwise.
57 */
58INLINE bool PGItem::
59has_notify() const {
60 LightReMutexHolder holder(_lock);
61 return (_notify != nullptr);
62}
63
64/**
65 * Returns the object which will be notified when the PGItem changes, if any.
66 * Returns NULL if there is no such object configured.
67 */
69get_notify() const {
70 LightReMutexHolder holder(_lock);
71 return _notify;
72}
73
74/**
75 * Sets the bounding rectangle of the item, in local coordinates. This is the
76 * region on screen within which the mouse will be considered to be within the
77 * item. Normally, it should correspond to the bounding rectangle of the
78 * visible geometry of the item.
79 */
80INLINE void PGItem::
81set_frame(PN_stdfloat left, PN_stdfloat right, PN_stdfloat bottom, PN_stdfloat top) {
82 set_frame(LVecBase4(left, right, bottom, top));
83}
84
85/**
86 * Sets the bounding rectangle of the item, in local coordinates. This is the
87 * region on screen within which the mouse will be considered to be within the
88 * item. Normally, it should correspond to the bounding rectangle of the
89 * visible geometry of the item.
90 */
91INLINE void PGItem::
92set_frame(const LVecBase4 &frame) {
93 LightReMutexHolder holder(_lock);
94 if (!_has_frame || _frame != frame) {
95 _has_frame = true;
96 _frame = frame;
97 frame_changed();
98 }
99}
100
101/**
102 * Returns the bounding rectangle of the item. See set_frame(). It is an
103 * error to call this if has_frame() returns false.
104 */
105INLINE const LVecBase4 &PGItem::
106get_frame() const {
107 LightReMutexHolder holder(_lock);
108 nassertr(has_frame(), _frame);
109 return _frame;
110}
111
112/**
113 * Returns true if the item has a bounding rectangle; see set_frame().
114 */
115INLINE bool PGItem::
116has_frame() const {
117 LightReMutexHolder holder(_lock);
118 return _has_frame;
119}
120
121/**
122 * Removes the bounding rectangle from the item. It will no longer be
123 * possible to position the mouse within the item; see set_frame().
124 */
125INLINE void PGItem::
126clear_frame() {
127 LightReMutexHolder holder(_lock);
128 if (_has_frame) {
129 _has_frame = false;
130 frame_changed();
131 }
132}
133
134/**
135 * Sets the "state" of this particular PGItem.
136 *
137 * The PGItem node will render as if it were the subgraph assigned to the
138 * corresponding index via set_state_def().
139 */
140INLINE void PGItem::
141set_state(int state) {
142 LightReMutexHolder holder(_lock);
143 _state = state;
144}
145
146/**
147 * Returns the "state" of this particular PGItem. See set_state().
148 */
149INLINE int PGItem::
150get_state() const {
151 LightReMutexHolder holder(_lock);
152 return _state;
153}
154
155/**
156 * Returns whether the PGItem is currently active for mouse events. See
157 * set_active().
158 */
159INLINE bool PGItem::
160get_active() const {
161 LightReMutexHolder holder(_lock);
162 return (_flags & F_active) != 0;
163}
164
165/**
166 * Returns whether the PGItem currently has focus for keyboard events. See
167 * set_focus().
168 */
169INLINE bool PGItem::
170get_focus() const {
171 LightReMutexHolder holder(_lock);
172 return (_flags & F_focus) != 0;
173}
174
175/**
176 * Returns whether background_focus is currently enabled. See
177 * set_background_focus().
178 */
179INLINE bool PGItem::
180get_background_focus() const {
181 LightReMutexHolder holder(_lock);
182 return (_flags & F_background_focus) != 0;
183}
184
185/**
186 * This is just an interface to set the suppress flags on the underlying
187 * MouseWatcherRegion. See MouseWatcherRegion::set_suppress_flags().
188 */
189INLINE void PGItem::
190set_suppress_flags(int suppress_flags) {
191 LightReMutexHolder holder(_lock);
192 _region->set_suppress_flags(suppress_flags);
193}
194
195/**
196 * This is just an interface to get the suppress flags on the underlying
197 * MouseWatcherRegion. See MouseWatcherRegion::get_suppress_flags().
198 */
199INLINE int PGItem::
200get_suppress_flags() const {
201 LightReMutexHolder holder(_lock);
202 return _region->get_suppress_flags();
203}
204
205/**
206 * Returns the Node that is the root of the subgraph that will be drawn when
207 * the PGItem is in the indicated state. The first time this is called for a
208 * particular state index, it may create the Node.
209 */
210INLINE NodePath &PGItem::
211get_state_def(int state) {
212 nassertr(state >= 0 && state < 1000, get_state_def(0)); // Sanity check.
213
214 LightReMutexHolder holder(_lock);
215 return do_get_state_def(state);
216}
217
218/**
219 * Returns the unique ID assigned to this PGItem. This will be assigned to
220 * the region created with the MouseWatcher, and will thus be used to generate
221 * event names.
222 */
223INLINE const std::string &PGItem::
224get_id() const {
225 LightReMutexHolder holder(_lock);
226 return _region->get_name();
227}
228
229/**
230 * Set the unique ID assigned to this PGItem. It is the user's responsibility
231 * to ensure that this ID is unique.
232 *
233 * Normally, this should not need to be called, as the PGItem will assign
234 * itself an ID when it is created, but this function allows the user to
235 * decide to redefine the ID to be something possibly more meaningful.
236 */
237INLINE void PGItem::
238set_id(const std::string &id) {
239 LightReMutexHolder holder(_lock);
240 _region->set_name(id);
241}
242
243/**
244 * Returns the prefix that is used to define the enter event for all PGItems.
245 * The enter event is the concatenation of this string followed by get_id().
246 */
247INLINE std::string PGItem::
249 return "enter-";
250}
251
252/**
253 * Returns the prefix that is used to define the exit event for all PGItems.
254 * The exit event is the concatenation of this string followed by get_id().
255 */
256INLINE std::string PGItem::
258 return "exit-";
259}
260
261/**
262 * Returns the prefix that is used to define the within event for all PGItems.
263 * The within event is the concatenation of this string followed by get_id().
264 */
265INLINE std::string PGItem::
267 return "within-";
268}
269
270/**
271 * Returns the prefix that is used to define the without event for all
272 * PGItems. The without event is the concatenation of this string followed by
273 * get_id().
274 */
275INLINE std::string PGItem::
277 return "without-";
278}
279
280/**
281 * Returns the prefix that is used to define the focus_in event for all
282 * PGItems. The focus_in event is the concatenation of this string followed
283 * by get_id().
284 *
285 * Unlike most item events, this event is thrown with no parameters.
286 */
287INLINE std::string PGItem::
289 return "fin-";
290}
291
292/**
293 * Returns the prefix that is used to define the focus_out event for all
294 * PGItems. The focus_out event is the concatenation of this string followed
295 * by get_id().
296 *
297 * Unlike most item events, this event is thrown with no parameters.
298 */
299INLINE std::string PGItem::
301 return "fout-";
302}
303
304/**
305 * Returns the prefix that is used to define the press event for all PGItems.
306 * The press event is the concatenation of this string followed by a button
307 * name, followed by a hyphen and get_id().
308 */
309INLINE std::string PGItem::
311 return "press-";
312}
313
314/**
315 * Returns the prefix that is used to define the repeat event for all PGItems.
316 * The repeat event is the concatenation of this string followed by a button
317 * name, followed by a hyphen and get_id().
318 */
319INLINE std::string PGItem::
321 return "repeat-";
322}
323
324/**
325 * Returns the prefix that is used to define the release event for all
326 * PGItems. The release event is the concatenation of this string followed by
327 * a button name, followed by a hyphen and get_id().
328 */
329INLINE std::string PGItem::
331 return "release-";
332}
333
334/**
335 * Returns the prefix that is used to define the keystroke event for all
336 * PGItems. The keystroke event is the concatenation of this string followed
337 * by a hyphen and get_id().
338 */
339INLINE std::string PGItem::
341 return "keystroke-";
342}
343
344/**
345 * Returns the event name that will be thrown when the item is active and the
346 * mouse enters its frame, but not any nested frames.
347 */
348INLINE std::string PGItem::
349get_enter_event() const {
350 LightReMutexHolder holder(_lock);
351 return get_enter_prefix() + get_id();
352}
353
354/**
355 * Returns the event name that will be thrown when the item is active and the
356 * mouse exits its frame, or enters a nested frame.
357 */
358INLINE std::string PGItem::
359get_exit_event() const {
360 LightReMutexHolder holder(_lock);
361 return get_exit_prefix() + get_id();
362}
363
364/**
365 * Returns the event name that will be thrown when the item is active and the
366 * mouse moves within the boundaries of the frame. This is different from the
367 * enter_event in that the mouse is considered within the frame even if it is
368 * also within a nested frame.
369 */
370INLINE std::string PGItem::
371get_within_event() const {
372 LightReMutexHolder holder(_lock);
373 return get_within_prefix() + get_id();
374}
375
376/**
377 * Returns the event name that will be thrown when the item is active and the
378 * mouse moves completely outside the boundaries of the frame. This is
379 * different from the exit_event in that the mouse is considered within the
380 * frame even if it is also within a nested frame.
381 */
382INLINE std::string PGItem::
383get_without_event() const {
384 LightReMutexHolder holder(_lock);
385 return get_without_prefix() + get_id();
386}
387
388/**
389 * Returns the event name that will be thrown when the item gets the keyboard
390 * focus.
391 */
392INLINE std::string PGItem::
393get_focus_in_event() const {
394 LightReMutexHolder holder(_lock);
395 return get_focus_in_prefix() + get_id();
396}
397
398/**
399 * Returns the event name that will be thrown when the item loses the keyboard
400 * focus.
401 */
402INLINE std::string PGItem::
403get_focus_out_event() const {
404 LightReMutexHolder holder(_lock);
405 return get_focus_out_prefix() + get_id();
406}
407
408/**
409 * Returns the event name that will be thrown when the item is active and the
410 * indicated mouse or keyboard button is depressed while the mouse is within
411 * the frame.
412 */
413INLINE std::string PGItem::
414get_press_event(const ButtonHandle &button) const {
415 LightReMutexHolder holder(_lock);
416 return get_press_prefix() + button.get_name() + "-" + get_id();
417}
418
419/**
420 * Returns the event name that will be thrown when the item is active and the
421 * indicated mouse or keyboard button is continuously held down while the
422 * mouse is within the frame.
423 */
424INLINE std::string PGItem::
425get_repeat_event(const ButtonHandle &button) const {
426 LightReMutexHolder holder(_lock);
427 return get_repeat_prefix() + button.get_name() + "-" + get_id();
428}
429
430/**
431 * Returns the event name that will be thrown when the item is active and the
432 * indicated mouse or keyboard button, formerly clicked down is within the
433 * frame, is released.
434 */
435INLINE std::string PGItem::
436get_release_event(const ButtonHandle &button) const {
437 LightReMutexHolder holder(_lock);
438 return get_release_prefix() + button.get_name() + "-" + get_id();
439}
440
441/**
442 * Returns the event name that will be thrown when the item is active and any
443 * key is pressed by the user.
444 */
445INLINE std::string PGItem::
446get_keystroke_event() const {
447 LightReMutexHolder holder(_lock);
448 return get_keystroke_prefix() + get_id();
449}
450
451/**
452 * Changes the TextNode object that will be used by all PGItems to generate
453 * default labels given a string. This can be loaded with the default font,
454 * etc.
455 */
456INLINE void PGItem::
457set_text_node(TextNode *node) {
458 _text_node = node;
459}
460
461/**
462 * Returns the one PGItem in the world that currently has keyboard focus, if
463 * any, or NULL if no item has keyboard focus. Use PGItem::set_focus() to
464 * activate or deactivate keyboard focus on a particular item.
465 */
468 return _focus_item;
469}
470
471/**
472 * Returns the inverse of the frame transform matrix
473 */
474INLINE LMatrix4 PGItem::
475get_frame_inv_xform() const {
476 LightReMutexHolder holder(_lock);
477 return _frame_inv_xform;
478}
479
480/**
481 * Computes the area of the indicated frame.
482 */
483INLINE PN_stdfloat PGItem::
484compute_area(const LVecBase4 &frame) {
485 return (frame[1] - frame[0]) * (frame[3] - frame[2]);
486}
487
488/**
489 * Given that largest is the pointer to the largest frame so far, and
490 * largest_area is its area, compare that to the area of the new frame; if the
491 * new frame is larger, adjust largest and largest_area appropriately.
492 */
493INLINE void PGItem::
494compare_largest(const LVecBase4 *&largest, PN_stdfloat &largest_area,
495 const LVecBase4 *new_frame) {
496 PN_stdfloat new_area = compute_area(*new_frame);
497 if (new_area > largest_area) {
498 largest = new_frame;
499 largest_area = new_area;
500 }
501}
502
503/**
504 *
505 */
506INLINE PGItem::StateDef::
507StateDef() :
508 _frame_stale(true)
509{
510}
A ButtonHandle represents a single button from any device, including keyboard buttons and mouse butto...
Definition: buttonHandle.h:26
get_name
Returns the name of the button.
Definition: buttonHandle.h:61
void set_name(const std::string &name)
The mutex name is only defined when compiling in DEBUG_THREADS mode.
Similar to MutexHolder, but for a light reentrant mutex.
NodePath is the fundamental system for disambiguating instances, and also provides a higher-level int...
Definition: nodePath.h:159
Objects that inherit from this class can receive specialized messages when PGItems change in certain ...
Definition: pgItemNotify.h:27
This is the base class for all the various kinds of gui widget objects.
Definition: pgItem.h:53
void set_notify(PGItemNotify *notify)
Sets the object which will be notified when the PGItem changes.
Definition: pgItem.I:43
const LVecBase4 & get_frame() const
Returns the bounding rectangle of the item.
Definition: pgItem.I:106
bool get_active() const
Returns whether the PGItem is currently active for mouse events.
Definition: pgItem.I:160
static std::string get_press_prefix()
Returns the prefix that is used to define the press event for all PGItems.
Definition: pgItem.I:310
void clear_frame()
Removes the bounding rectangle from the item.
Definition: pgItem.I:126
static std::string get_focus_out_prefix()
Returns the prefix that is used to define the focus_out event for all PGItems.
Definition: pgItem.I:300
std::string get_keystroke_event() const
Returns the event name that will be thrown when the item is active and any key is pressed by the user...
Definition: pgItem.I:446
std::string get_without_event() const
Returns the event name that will be thrown when the item is active and the mouse moves completely out...
Definition: pgItem.I:383
std::string get_focus_out_event() const
Returns the event name that will be thrown when the item loses the keyboard focus.
Definition: pgItem.I:403
PGItemNotify * get_notify() const
Returns the object which will be notified when the PGItem changes, if any.
Definition: pgItem.I:69
static std::string get_within_prefix()
Returns the prefix that is used to define the within event for all PGItems.
Definition: pgItem.I:266
int get_suppress_flags() const
This is just an interface to get the suppress flags on the underlying MouseWatcherRegion.
Definition: pgItem.I:200
std::string get_exit_event() const
Returns the event name that will be thrown when the item is active and the mouse exits its frame,...
Definition: pgItem.I:359
void set_frame(PN_stdfloat left, PN_stdfloat right, PN_stdfloat bottom, PN_stdfloat top)
Sets the bounding rectangle of the item, in local coordinates.
Definition: pgItem.I:81
static std::string get_focus_in_prefix()
Returns the prefix that is used to define the focus_in event for all PGItems.
Definition: pgItem.I:288
static std::string get_keystroke_prefix()
Returns the prefix that is used to define the keystroke event for all PGItems.
Definition: pgItem.I:340
LMatrix4 get_frame_inv_xform() const
Returns the inverse of the frame transform matrix.
Definition: pgItem.I:475
bool get_focus() const
Returns whether the PGItem currently has focus for keyboard events.
Definition: pgItem.I:170
bool get_background_focus() const
Returns whether background_focus is currently enabled.
Definition: pgItem.I:180
PGMouseWatcherRegion * get_region() const
Returns the MouseWatcherRegion associated with this item.
Definition: pgItem.I:31
int get_state() const
Returns the "state" of this particular PGItem.
Definition: pgItem.I:150
static void set_text_node(TextNode *node)
Changes the TextNode object that will be used by all PGItems to generate default labels given a strin...
Definition: pgItem.I:457
std::string get_press_event(const ButtonHandle &button) const
Returns the event name that will be thrown when the item is active and the indicated mouse or keyboar...
Definition: pgItem.I:414
std::string get_within_event() const
Returns the event name that will be thrown when the item is active and the mouse moves within the bou...
Definition: pgItem.I:371
const std::string & get_id() const
Returns the unique ID assigned to this PGItem.
Definition: pgItem.I:224
void set_suppress_flags(int suppress_flags)
This is just an interface to set the suppress flags on the underlying MouseWatcherRegion.
Definition: pgItem.I:190
get_state_def
Returns the Node that is the root of the subgraph that will be drawn when the PGItem is in the indica...
Definition: pgItem.h:135
static std::string get_enter_prefix()
Returns the prefix that is used to define the enter event for all PGItems.
Definition: pgItem.I:248
static PGItem * get_focus_item()
Returns the one PGItem in the world that currently has keyboard focus, if any, or NULL if no item has...
Definition: pgItem.I:467
std::string get_repeat_event(const ButtonHandle &button) const
Returns the event name that will be thrown when the item is active and the indicated mouse or keyboar...
Definition: pgItem.I:425
bool has_notify() const
Returns true if there is an object configured to be notified when the PGItem changes,...
Definition: pgItem.I:59
static std::string get_release_prefix()
Returns the prefix that is used to define the release event for all PGItems.
Definition: pgItem.I:330
static std::string get_exit_prefix()
Returns the prefix that is used to define the exit event for all PGItems.
Definition: pgItem.I:257
bool has_frame() const
Returns true if the item has a bounding rectangle; see set_frame().
Definition: pgItem.I:116
static std::string get_without_prefix()
Returns the prefix that is used to define the without event for all PGItems.
Definition: pgItem.I:276
std::string get_release_event(const ButtonHandle &button) const
Returns the event name that will be thrown when the item is active and the indicated mouse or keyboar...
Definition: pgItem.I:436
void set_id(const std::string &id)
Set the unique ID assigned to this PGItem.
Definition: pgItem.I:238
std::string get_enter_event() const
Returns the event name that will be thrown when the item is active and the mouse enters its frame,...
Definition: pgItem.I:349
static std::string get_repeat_prefix()
Returns the prefix that is used to define the repeat event for all PGItems.
Definition: pgItem.I:320
std::string get_focus_in_event() const
Returns the event name that will be thrown when the item gets the keyboard focus.
Definition: pgItem.I:393
This is a specialization on MouseWatcherRegion, to add a bit more fields that are relevant to the PG ...
set_state
Sets the complete RenderState that will be applied to all nodes at this level and below.
Definition: pandaNode.h:173
The primary interface to this module.
Definition: textNode.h:48