Introduction
A three-button mouse with a two-dimensional scroll wheel can be used to control all pyglet windows. The operating system typically draws the mouse pointer, but you can override this by requesting a different cursor shape or providing our image or animation.
In this article, we will discuss how the mouse works in pyglet. So let’s get started.
Mouse events
The window that receive the event from the operating system dispatches all mouse events. This is typically the window with the mouse cursor, but this is not always the case due to mouse exclusivity and drag operations.
The mouse pointer's coordinate space is relative to the window's bottom-left corner on the screen. By increasing Y values and approaching the top of the screen (note that this is a "backward" option as compared to many other windowing toolkits, but it is consistent with the default OpenGL projection in pyglet).
The mouse pointer's coordinate space.
The most fundamental mouse event is on_mouse_motion(), which is called whenever the mouse is moved:
def on_mouse_motion(x, y, dx, dy):
pass
Here the x and y parameters specify the mouse pointer's position concerning the bottom-left corner of the window.
When the operating system detects a mouse movement, the event is triggered. This does not have to be done for each pixel moved - the operating system usually samples the mouse at a predetermined frequency, and the mouse can be moved quicker. If your application is not processing events quickly enough, several queued-up mouse events may be dispatched in a single dispatch_events() call. You should not be concerned about these issues; the queued-up mouse events rarely cause problems.
Many games aren't concerned with the actual position of the mouse cursor, but rather with the direction in which it has moved. In a first-person game, for example, the mouse controls the player's gaze but the mouse pointer is not visible.
The dx and dy parameters Here are for this purpose: they indicate how far the mouse traveled along each axis to arrive at its current position. This is easily calculated by storing the previous x and y parameters after each mouse event. Still, it is tedious to code and ignores the effects of other obscuring windows. Instead, the dx and dy parameters should be used.
The following events occur when a mouse button is pressed or released, or when any button is held down and the mouse pointer is moved.
def on_mouse_press(x, y, button, modifiers):
pass
def on_mouse_release(x, y, button, modifiers):
pass
def on_mouse_drag(x, y, dx, dy, buttons, modifiers):
pass
Here the x, y, dx, and dy parameters are identical to those used in the on_mouse_motion() event. The dx and dy parameters are not required for the press and release events because they would be zero in this case.
The button parameter, which is one of the following constants, indicates which of the mouse button was pressed:
pyglet.window.mouse.LEFT
pyglet.window.mouse.MIDDLE
pyglet.window.mouse.RIGHT
The on_mouse_drag() button's parameter is a bitwise combination of all the mouse buttons that are currently pressed. To see if the user is performing a drag gesture with the left button, for example:
from pyglet.window import mouse
def on_mouse_drag(x, y, dx, dy, buttons, modifiers):
if buttons & mouse.LEFT:
pass
When a user initiates a drag operation (by pressing and holding a mouse button and then moving the mouse pointer), the window that initiated the drag will continue to receive the on_mouse_drag() event for as long as the button is held down. This is true even if the mouse pointer moves away from the window. Generally, you do not need to handle this differently: dragging is a gesture rather than a direct manipulation of the user interface widget, which is a convention shared by all operating systems
When the mouse exits or enters a window, the following events occur:
def on_mouse_enter(x, y):
pass
def on_mouse_leave(x, y):
pass
The on_mouse_leave() coordinates will be outside of your window. While a drag operation is in progress, these events are not dispatched.
The on_mouse_scroll() event is triggered by the mouse scroll wheel:
def on_mouse_scroll(x, y, scroll_x, scroll_y):
pass
Here the scroll_y parameter indicates how many "clicks" the wheel moved, with positive values indicating that the wheel was pushed forward. Most mouse have a scroll_x parameter of 0; however, some new mouse, such as the Apple Mighty Mouse, use a ball rather than a wheel; in this case, the scroll_x parameter provides horizontal movement.; in this case, the scroll_x parameter provides horizontal movement. The scale of these numbers is unknown; it is usually configured by the user in their operating system preferences.
84+ registered