Code360 powered by Coding Ninjas X Code360 powered by Coding Ninjas X
Table of contents
Mouse events
Changing the mouse cursor
Mouse exclusivity
Frequently Asked Questions
What are different mouse events?
Is there any way to hide the mouse cursor?
What is mouse exclusivity?
Last Updated: Mar 27, 2024

Playing with the Mouse in Pyglet

Master Python: Predicting weather forecasts
Ashwin Goyal
Product Manager @


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):


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):

def on_mouse_release(x, y, button, modifiers):

def on_mouse_drag(x, y, dx, dy, buttons, modifiers):


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:



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:


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):

def on_mouse_leave(x, y):


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):


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.

Get the tech career you deserve, faster!
Connect with our expert counsellors to understand how to hack your way to success
User rating 4.7/5
1:1 doubt support
95% placement record
Akash Pal
Senior Software Engineer
326% Hike After Job Bootcamp
Himanshu Gusain
Programmer Analyst
32 LPA After Job Bootcamp
After Job

Changing the mouse cursor

The mouse pointer or cursor can be changed to one of the system cursors, a custom image, or completely hidden. The cursor change will be applied only to the window in which it is made. To make the mouse cursor invisible, use set_mouse_visible():

win = pyglet.window.Window()


If the mouse would obscure the text that the user is typing, this can be useful. If you want to hide the mouse cursor in a game, consider making the mouse exclusive instead; see Mouse exclusivity, below.

In order to change the appearance of the mouse cursor, use set_mouse_cursor(). A mouse cursor is a MouseCursor instance. The get_system_mouse_cursor() returns the operating system-defined cursors:

cursor = win.get_system_mouse_cursor(win.CURSOR_HELP)


The cursors defined by pyglet are listed below, along with how they typically appear on Windows and Mac OS X. On Linux, the pointer image is determined by the window manager.

You can also use your image as the mouse cursor. Use of pyglet.image.load() the image, then create an ImageMouseCursor with the image and the cursor's "hot-spot". The hot-spot is an image point. The hot spot corresponds to the actual mouse pointer location on the screen, such as the point of the arrow:

image = pyglet.image.load('cursor.png')
cursor = pyglet.window.ImageMouseCursor(image, 16, 8)


OpenGL can even render a mouse cursor directly. For example, you could create a 3-dimensional cursor or a particle trail. Subclass MouseCursor and implement your draw method to accomplish this. Even if you use a different projection in the rest of your application, the default pyglet window projection will be used when calling the draw method.

Mouse exclusivity

You can completely control the mouse for your application, preventing it from being used to activate other programs. This is especially beneficial in immersive games such as first-person shooters.

The mouse cursor disappears when you enable mouse-exclusive mode. It isn't just hidden; no amount of mouse movement will cause it to leave your application. And also because there is no longer a mouse cursor, the x and y parameters of mouse events are no longer useful; only the dx and dy parameters should be used to determine how the mouse was moved.

Set the mouse to exclusive mode using set_exclusive_mouse():

win = pyglet.window.Window()


Even if your window is full-screen, you should enable mouse exclusive mode: it will prevent the window from "hitting" the screen's edges and will behave correctly in multi-monitor setups.

It's worth noting that on Linux, setting exclusive mouse disables Alt+Tab and other application switching hotkeys. There is currently no workaround for this.

Check out this problem - Optimal Strategy For A Game

Frequently Asked Questions

What are different mouse events?

Different mouse events are motion (press, release), drag, leave and scroll.

Is there any way to hide the mouse cursor?

Yes, you can hide the mouse cursor by turning set_mouse_visible() off or you can make the mouse exclusive.

What is mouse exclusivity?

The mouse cursor is hidden, and all mouse events are directed to the window.


In this article, we have extensively discussed the working of mouse in pyglet. You should check this out to know more about pyglet applications. You should also check out this; it will help you with the concept of pygame, a python project. If you would like to learn more, check out our articles here. Do upvote our blog to help other ninjas grow.

Refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. Enroll in our courses and refer to the mock test and problems available, interview puzzles. Also, look at the interview experiences and interview bundle for placement preparations. Please look at this YouTube tutorial to explore the preparation strategy for SDE placements.

Happy learning!

Previous article
Working with the Keyboard in Pyglet
Next article
Working with Other Input devices in Pyglet
Live masterclass