Your first window¶
This page builds a complete malibx program one step at a time. It covers the three things every malibx program does: connect, open a window, and run the loop.
The whole program¶
| first_window.py | |
|---|---|
- Creates the connection handle. Nearly every other function takes it as its first argument.
- Opens a 640 × 480 window titled my window and returns a window handle.
- Draws one white pixel in the middle of the window.
- Draws purple text. The position
(20, 30)is the left end of the text's baseline. - Shows the window and handles events until it's closed.
Run it with python first_window.py. A black window opens with a white dot in
the middle and "hi!" in the top-left corner.
Step by step¶
1. Connect with init¶
init() returns an Mlx object, the equivalent of MiniLibX's void *mlx_ptr.
It keeps track of your windows and runs the main loop. You need only one per
program.
2. Open a window with new_window¶
| Parameter | Meaning |
|---|---|
mlx |
The connection from init() |
size_x, size_y |
Width and height of the drawing area, in pixels |
title |
Text in the title bar |
It returns a Window. A new window is black. You can open several windows,
and each one has its own pixels and its own event hooks.
Not on screen yet
new_window creates the window, but nothing you draw is shown until the
loop runs. That's why you can draw before calling loop.
3. Draw something¶
The window has a pixel grid with its origin in the top-left corner.
x grows to the right and y grows downwards:
(0,0) ──────────────► x
│
│ (320,240) ● ← middle of a 640×480 window
│
▼
y (639,479) is the bottom-right pixel
Colors are integers written as 0xRRGGBB:
| Value | Color |
|---|---|
0xFF0000 |
red |
0x00FF00 |
green |
0x0000FF |
blue |
0xFFFFFF |
white |
0xB040FF |
purple |
Drawing outside the window does nothing. It doesn't raise an error, so you don't need to check bounds yourself.
Drawing covers pixels, text and images in detail.
4. Run the loop¶
loop is where your program spends its time. It shows your windows,
redraws them about 60 times a second, and calls your event hooks. It
returns when:
- every window has been closed, or
- you call
malibx.loop_end(mlx), for example from a key handler.
Code after loop(mlx) runs once the loop ends, so you can use it to save
state or print a goodbye.
Stopping a stuck program
Press Ctrl+C in the terminal. loop checks for it every frame and
raises KeyboardInterrupt.
Make it close on Esc¶
Most programs also close when you press Esc. Register a key hook that ends the loop:
The hook gets the key's code (an X11 keysym, as in MiniLibX) and the param
you registered it with. Here param is None because none was passed.
Keyboard and mouse explains keysyms and the other hooks.
Two windows¶
Each window has its own drawing area:
import malibx
mlx = malibx.init()
left = malibx.new_window(mlx, 300, 200, "left")
right = malibx.new_window(mlx, 300, 200, "right")
malibx.string_put(mlx, left, 20, 30, 0xFF4040, "I'm on the left")
malibx.string_put(mlx, right, 20, 30, 0x40A0FF, "I'm on the right")
malibx.loop(mlx) # returns when both windows are closed
Drawing to a window after the user has closed it raises
RuntimeError: window is closed.
Recap¶
- [x]
init()once, to get the connection - [x]
new_window(mlx, w, h, title)for each window - [x] Draw with
pixel_putandstring_put;(0, 0)is the top-left corner - [x]
loop(mlx)shows everything and runs until the windows close orloop_endis called
Next: The main loop . This is how anything on screen moves.