Panda3D
Loading...
Searching...
No Matches
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...
get_name
Returns the name of the button.
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 ...
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