Keyboard and mouse¶
malibx tells you about input by calling hooks: functions you register on a window. They run during the event step of each frame.
The hook functions¶
| Function | When f is called |
f gets |
|---|---|---|
key_hook(win, f, param=None) |
A key is released | (keysym, param) |
mouse_hook(win, f, param=None) |
A mouse button is pressed | (button, x, y, param) |
expose_hook(win, f, param=None) |
The window is first shown | (param) |
hook(win, x_event, x_mask, f, param=None) |
Any supported event | depends on the event |
key_hook fires on key release
This matches MiniLibX, but it's a surprise for many people. For games,
where things should react when a key goes down, use
hook(win, 2, 1 << 0, f, param) (KeyPress) instead. See
Smooth movement.
Keys¶
Keys are reported as X11 keysyms, the same numbers MiniLibX gives you on Linux. This keeps code portable: malibx reports these same values on macOS and Windows too.
- Letters are their lowercase ASCII code, even with Shift held:
ord("a")is0x61. Useord("w")rather than memorizing numbers. - Digits are their ASCII code:
ord("0")toord("9"). - Special keys have codes in the
0xFFxxrange:
| Key | Keysym | Key | Keysym | |
|---|---|---|---|---|
| Esc | 0xFF1B |
Left | 0xFF51 |
|
| Enter | 0xFF0D |
Up | 0xFF52 |
|
| Space | 0x0020 |
Right | 0xFF53 |
|
| Tab | 0xFF09 |
Down | 0xFF54 |
|
| Backspace | 0xFF08 |
Shift (left / right) | 0xFFE1 / 0xFFE2 |
|
| Del | 0xFFFF |
Ctrl (left / right) | 0xFFE3 / 0xFFE4 |
|
| F1 … F12 | 0xFFBE … 0xFFC9 |
Alt (left / right) | 0xFFE9 / 0xFFEA |
A handy set of constants to copy into your program:
ESC, ENTER, SPACE, TAB = 0xFF1B, 0xFF0D, 0x20, 0xFF09
LEFT, UP, RIGHT, DOWN = 0xFF51, 0xFF52, 0xFF53, 0xFF54
W, A, S, D = map(ord, "wasd")
Find any key's code
Not sure what a key sends? Print it:
The keys example in the repository (make run EXAMPLE=keys) prints
every key and mouse event.
Quit on Esc¶
Mouse¶
def on_click(button, x, y, param):
print(f"button {button} at ({x}, {y})")
malibx.mouse_hook(win, on_click)
x and y are in window pixels, with (0, 0) at the top-left corner, the
same coordinates you draw with. Buttons are numbered like X11:
button |
Meaning |
|---|---|
1 |
Left |
2 |
Middle (wheel click) |
3 |
Right |
4 |
Scroll up |
5 |
Scroll down |
Each step of the scroll wheel is reported as a press and release of button 4 or 5.
Click to paint¶
There's no loop hook and no redrawing here. The window keeps its pixels, so each dot stays until you clear it.
Any event with hook¶
hook is the general version of the functions above. x_event is an X11
event number. These are the ones malibx reports:
x_event |
Event | f gets |
Fires when |
|---|---|---|---|
2 |
KeyPress | (keysym, param) |
a key goes down, and again on auto-repeat while it's held |
3 |
KeyRelease | (keysym, param) |
a key goes up |
4 |
ButtonPress | (button, x, y, param) |
a mouse button goes down |
5 |
ButtonRelease | (button, x, y, param) |
a mouse button goes up |
6 |
MotionNotify | (x, y, param) |
the mouse moves inside the window |
12 |
Expose | (param) |
the window is first shown |
17 |
DestroyNotify | (param) |
the user closes the window |
x_mask is accepted so that MiniLibX code works unchanged, but malibx
ignores it. Pass the usual X11 mask (1 << 0 for KeyPress, 1 << 1 for
KeyRelease, …) or 0. It makes no difference.
One hook per event per window
Each window holds one function per event number. Registering again for
the same event replaces the old function. The shortcut functions use
the same slots: key_hook is event 3, mouse_hook is event 4 and
expose_hook is event 12. So key_hook(win, f) replaces a
hook(win, 3, …), and the other way round.
Event numbers from 0 to 35 are accepted, so MiniLibX code that registers other
events still runs, but those hooks never fire. Numbers outside that range
raise ValueError.
The close button¶
When the user clicks the window's close button, malibx closes the window
right away, then calls your event 17 hook (if any). To close a window from
code, use destroy_window; that doesn't
call the hook. Use the hook for
cleanup or for a goodbye message. You can't cancel the close, and the window
is already gone, so don't draw to it from this hook.
def on_close(param):
print("saving…")
malibx.loop_end(mlx) # also stop if other windows are still open
malibx.hook(win, 17, 0, on_close)
If this was the last open window, loop returns on its own after the hook.
Smooth movement¶
To move something smoothly while a key is held, track which keys are down and move in the loop hook. Moving inside the KeyPress hook makes movement stutter: the hook only fires once, then pauses until the operating system's key repeat starts.
- A
setignores auto-repeat: adding a key that's already held changes nothing. For the opposite (one action per press, however long it's held) calldo_key_autorepeatoff. - Every held key moves the player once per frame. Holding two arrows moves diagonally.
Following the mouse¶
MotionNotify (event 6) reports the pointer position whenever it moves inside the window:
Store the position in your state and use it in the loop hook, the same way as held keys. Or skip the hook and ask for it whenever you need it:
You can also move the pointer with
mouse_move, and hide it with
mouse_hide, for example to draw your own
cursor or for first-person mouse-look.
Summary¶
key_hookis key release; usehook(win, 2, …)for key press.- Keys are X11 keysyms: lowercase ASCII for letters,
0xFFxxfor special keys. - Mouse buttons 1/2/3 are left/middle/right, and 4/5 are the scroll wheel.
- One hook per event per window. Registering again replaces it.
- The close button closes the window first, then calls event 17.
- For smooth movement, track held keys in a
setand move in the loop hook.
You've finished Getting started. You know how to open windows, run the
loop, draw with pixels, text and images, and respond to input. The
examples in the
repository put all of it together. sprites.py, an animated XPM skull with
glowing eyes, is a good one to read next.