panda3d.core.MouseWatcher

class MouseWatcher

Bases: DataNode, MouseWatcherBase

This TFormer maintains a list of rectangular regions on the screen that are considered special mouse regions; typically these will be click buttons. When the mouse passes in or out of one of these regions, or when a button is clicked while the mouse is in one of these regions, an event is thrown.

Mouse events may also be suppressed from the rest of the datagraph in these special regions.

This class can also implement a software mouse pointer by automatically generating a transform to apply to a piece of geometry placed under the 2-d scene graph. It will move the geometry around according to the mouse’s known position.

Finally, this class can keep a record of the mouse trail. This is useful if you want to know, not just where the mouse is, but the exact sequence of movements it took to get there. This information is mainly useful for gesture-recognition code. To use trail logging, you need to enable the generation of pointer events in the GraphicsWindowInputDevice and set the trail log duration in the MouseWatcher. Otherwise, the trail log will be empty.

Inheritance diagram

Inheritance diagram of MouseWatcher

__init__(name: str) → None
addGroup(group: MouseWatcherGroup) → bool

Adds the indicated group of regions to the set of regions the MouseWatcher will monitor each frame.

Since the MouseWatcher itself inherits from MouseWatcherBase, this operation is normally not necessary–you can simply add the Regions you care about one at a time. Adding a complete group is useful when you may want to explicitly remove the regions as a group later.

Returns true if the group was successfully added, or false if it was already on the list.

clearDisplayRegion() → None

Removes the display region constraint from the MouseWatcher, and restores it to the default behavior of watching the whole window.

clearGeometry() → None

Stops the use of the software cursor set up via setGeometry().

clearInactivityTimeout() → None

Removes the inactivity timeout and restores the MouseWatcher to its default behavior of allowing a key to be held indefinitely.

clearTrailLog() → None

Clears the mouse trail log. This does not prevent further accumulation of the log given future events.

clearTrailNode() → None

If you have previously fetched the trail node using get_trail_node, then the MouseWatcher is continually updating the trail node every frame. Using clear_trail_node causes the MouseWatcher to forget the trail node and stop updating it.

getButtonDownPattern() → str

Returns the string that indicates how event names are generated when a button is depressed. See setButtonDownPattern().

getButtonRepeatPattern() → str

Returns the string that indicates how event names are names are generated when a button is continuously held and generates keyrepeat “down” events. See setButtonRepeatPattern().

getButtonUpPattern() → str

Returns the string that indicates how event names are generated when a button is released. See setButtonDownPattern().

static getClassType() → TypeHandle
Return type

TypeHandle

getDisplayRegion() → DisplayRegion

Returns the display region the MouseWatcher is constrained to by setDisplayRegion(), or NULL if it is not constrained.

Return type

DisplayRegion

getEnterPattern() → str

Returns the string that indicates how event names are generated when the mouse enters a region. This is different from within_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

getExtraHandler() → EventHandler

As an optimization for the C++ Gui, an extra handler can be registered with a mouseWatcher so that events can be dealt with much sooner.

Return type

EventHandler

getFrame() → LVecBase4

Returns the frame of the MouseWatcher. See setFrame().

Return type

LVecBase4

getGeometry() → PandaNode

Returns the node that has been set as the software mouse pointer, or NULL if no node has been set. See hasGeometry() and setGeometry().

Return type

PandaNode

getGroup(n: int) → MouseWatcherGroup

Returns the nth group added to the MouseWatcher via addGroup().

Return type

MouseWatcherGroup

getGroups() → list
getInactivityTimeout() → float

Returns the inactivity timeout that has been set. It is an error to call this if hasInactivityTimeout() returns false.

getInactivityTimeoutEvent() → str

Returns the event string that will be generated when the inactivity timeout counter expires. See setInactivityTimeout().

getLeavePattern() → str

Returns the string that indicates how event names are generated when the mouse leaves a region. This is different from without_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

getModifierButtons() → ModifierButtons

Returns the set of buttons that are being monitored as modifier buttons, as well as their current state.

Return type

ModifierButtons

getMouse() → LPoint2

It is only valid to call this if hasMouse() returns true. If so, this returns the current position of the mouse within the window.

Return type

LPoint2

getMouseX() → float

It is only valid to call this if hasMouse() returns true. If so, this returns the current X position of the mouse within the window.

getMouseY() → float

It is only valid to call this if hasMouse() returns true. If so, this returns the current Y position of the mouse within the window.

getNumGroups() → int

Returns the number of separate groups added to the MouseWatcher via addGroup().

getOverRegion() → MouseWatcherRegion

Returns the smallest region the mouse is currently over, or NULL if it is over no region.

Return type

MouseWatcherRegion

getOverRegion(pos: LPoint2) → MouseWatcherRegion

Returns the preferred region the mouse is over. In the case of overlapping regions, the region with the largest sort order is preferred; if two regions have the same sort order, then the smaller region is preferred.

Return type

MouseWatcherRegion

getOverRegion(x: float, y: float) → MouseWatcherRegion

Returns the smallest region the indicated point is over, or NULL if it is over no region.

Return type

MouseWatcherRegion

getTrailLog() → PointerEventList

Obtain the mouse trail log. This is a PointerEventList. Does not make a copy, therefore, this PointerEventList will be updated each time process_events gets called.

To use trail logging, you need to enable the generation of pointer events in the GraphicsWindowInputDevice and set the trail log duration in the MouseWatcher. Otherwise, the trail log will be empty.

Return type

PointerEventList

getTrailNode() → GeomNode

Returns a GeomNode that represents the mouse trail. The intent is that you should reparent this GeomNode to Render2D, and then forget about it. The MouseWatcher will continually update the trail node. There is only one trail node, it does not create a new one each time you call get_trail_node.

This is not a particularly beautiful way to render a mouse trail. It is intended more for debugging purposes than for finished applications. Even so, It is suggested that you might want to apply a line thickness and antialias mode to the line — doing so makes it look a lot better.

Return type

GeomNode

getWithinPattern() → str

Returns the string that indicates how event names are generated when the mouse wanders over a region. This is different from enter_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

getWithoutPattern() → str

Returns the string that indicates how event names are generated when the mouse wanders out of a region. This is different from leave_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

hasDisplayRegion() → bool

Returns true if the MouseWatcher has been constrained to a particular region of the screen via setDisplayRegion(), or false otherwise. If this returns true, getDisplayRegion() may be used to return the particular region.

hasGeometry() → bool

Returns true if a software mouse pointer has been setup via setGeometry(), or false otherwise. See setGeometry().

hasInactivityTimeout() → bool

Returns true if an inactivity timeout has been set, false otherwise.

hasMouse() → bool

Returns true if the mouse is anywhere within the window, false otherwise. Also see isMouseOpen().

isButtonDown(button: ButtonHandle) → bool

Returns true if the indicated button is currently being held down, false otherwise.

isMouseOpen() → bool

Returns true if the mouse is within the window and not over some particular MouseWatcherRegion that is marked to suppress mouse events; that is, that the mouse is in open space within the window.

isOverRegion() → bool

Returns true if the mouse is over any rectangular region, false otherwise.

isOverRegion(pos: LPoint2) → bool

Returns true if the mouse is over any rectangular region, false otherwise.

isOverRegion(x: float, y: float) → bool

Returns true if the mouse is over any rectangular region, false otherwise.

noteActivity() → None

Can be used in conjunction with the inactivity timeout to inform the MouseWatcher that the user has just performed some action which proves he/she is present. It may be necessary to call this for external events, such as joystick action, that the MouseWatcher might otherwise not know about. This will reset the current inactivity timer. When the inactivity timer reaches the length of time specified by setInactivityTimeout(), with no keyboard or mouse activity and no calls to noteActivity(), then any buttons held will be automatically released.

numTrailRecent() → size_t

This counter indicates how many events were added to the trail log this frame. The trail log is updated once per frame, during the process_events operation.

Return type

size_t

removeGroup(group: MouseWatcherGroup) → bool

Removes the indicated group from the set of extra groups associated with the MouseWatcher. Returns true if successful, or false if the group was already removed or was never added via addGroup().

removeRegion(region: MouseWatcherRegion) → bool

Removes the indicated region from the group. Returns true if it was successfully removed, or false if it wasn’t there in the first place.

replaceGroup(old_group: MouseWatcherGroup, new_group: MouseWatcherGroup) → bool

Atomically removes old_group from the MouseWatcher, and replaces it with new_group. Presumably old_group and new_group might have some regions in common; these are handled properly.

If old_group is not already present, simply adds new_group and returns false. Otherwise, removes old_group and adds new_group, and then returns true.

setButtonDownPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when a button is depressed. This is a string that may contain any of the following:

%r - the name of the region the mouse is over %b - the name of the button pressed.

The event name will be based on the in_pattern string specified here, with all occurrences of the above strings replaced with the corresponding values.

setButtonRepeatPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when a button is continuously held and generates keyrepeat “down” events. This is a string that may contain any of the following:

%r - the name of the region the mouse is over %b - the name of the button pressed.

The event name will be based on the in_pattern string specified here, with all occurrences of the above strings replaced with the corresponding values.

setButtonUpPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when a button is released. See setButtonDownPattern().

setDisplayRegion(dr: DisplayRegion) → None

Constrains the MouseWatcher to watching the mouse within a particular indicated region of the screen. DataNodes parented under the MouseWatcher will observe the mouse and keyboard events only when the mouse is within the indicated region, and the observed range will be from -1 .. 1 across the region.

Do not delete the DisplayRegion while it is owned by the MouseWatcher.

setEnterPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when the mouse enters a region. This is different from within_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

setExtraHandler(eh: EventHandler) → None

As an optimization for the C++ Gui, an extra handler can be registered with a mouseWatcher so that events can be dealt with much sooner.

setFrame(frame: LVecBase4) → None

Sets the frame of the MouseWatcher. This determines the coordinate space in which the MouseWatcherRegions should be expected to live. Normally, this is left at -1, 1, -1, 1, which is the default setting, and matches the mouse coordinate range.

Whatever values you specify here indicate the shape of the full screen, and the MouseWatcherRegions will be given in coordinate space matching it. For instance, if you specify (0, 1, 0, 1), then a MouseWatcherRegion with the frame (0, 1, 0, .5) will cover the lower half of the screen.

setFrame(left: float, right: float, bottom: float, top: float) → None

Sets the frame of the MouseWatcher. See the next flavor of this method for a more verbose explanation.

setGeometry(node: PandaNode) → None

Sets the node that will be transformed each frame by the mouse’s coordinates. It will also be hidden when the mouse goes outside the window. This can be used to implement a software mouse pointer for when a hardware (or system) mouse pointer is unavailable.

setInactivityTimeout(timeout: float) → None

Sets an inactivity timeout on the mouse activity. When this timeout (in seconds) is exceeded with no keyboard or mouse activity, all currently-held buttons are automatically released. This is intended to help protect against people who inadvertently (or intentionally) leave a keyboard key stuck down and then wander away from the keyboard.

Also, when this timeout expires, the event specified by setInactivityTimeoutEvent() will be generated.

setInactivityTimeoutEvent(event: str) → None

Specifies the event string that will be generated when the inactivity timeout counter expires. See setInactivityTimeout().

setLeavePattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when the mouse leaves a region. This is different from without_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

setModifierButtons(mods: ModifierButtons) → None

Sets the buttons that should be monitored as modifier buttons for generating events to the MouseWatcherRegions.

setTrailLogDuration(duration: float) → None

If the duration is nonzero, causes the MouseWatcher to log the mouse’s trail. Events older than the specified duration are discarded. If the duration is zero, logging is disabled.

setWithinPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when the mouse wanders over a region. This is different from enter_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.

setWithoutPattern(pattern: str) → None

Sets the pattern string that indicates how the event names are generated when the mouse wanders out of a region. This is different from leave_pattern, in that a mouse is only “entered” in the topmost region at a given time, while it might be “within” multiple nested regions.