0
# Window Management
1

2
Complete window lifecycle management including creation, destruction, properties, state control, and callbacks. Windows provide the rendering surface for OpenGL and Vulkan applications.
3

4
## Capabilities
5

6
### Window Creation and Destruction
7

8
Create and destroy windows with associated OpenGL or Vulkan contexts.
9

10
```python { .api }
11
def create_window(width: int, height: int, title: str, monitor, share):
12
    """
13
    Create a window and its associated OpenGL or OpenGL ES context.
14
    
15
    Parameters:
16
        width: Window width in screen coordinates
17
        height: Window height in screen coordinates  
18
        title: Window title (UTF-8 encoded string)
19
        monitor: Monitor for fullscreen mode, or None for windowed
20
        share: Window whose context to share resources with, or None
21
        
22
    Returns:
23
        GLFWwindow: Window handle, or None if creation failed
24
    """
25

26
def destroy_window(window) -> None:
27
    """
28
    Destroy the window and its context.
29
    
30
    Parameters:
31
        window: Window to destroy
32
    """
33
```
34

35
### Window Hints
36

37
Configure window properties before creation.
38

39
```python { .api }
40
def default_window_hints() -> None:
41
    """Reset all window hints to their default values."""
42

43
def window_hint(hint: int, value: int) -> None:
44
    """
45
    Set window creation hint.
46
    
47
    Parameters:
48
        hint: Window hint identifier
49
        value: Hint value
50
    """
51

52
def window_hint_string(hint: int, value: str) -> None:
53
    """
54
    Set string window hint.
55
    
56
    Parameters:
57
        hint: Window hint identifier
58
        value: Hint string value
59
    """
60
```
61

62
#### Window Hint Constants
63

64
```python { .api }
65
# Window properties
66
FOCUSED: int = 0x00020001
67
ICONIFIED: int = 0x00020002
68
RESIZABLE: int = 0x00020003
69
VISIBLE: int = 0x00020004
70
DECORATED: int = 0x00020005
71
AUTO_ICONIFY: int = 0x00020006
72
FLOATING: int = 0x00020007
73
MAXIMIZED: int = 0x00020008
74
CENTER_CURSOR: int = 0x00020009
75
TRANSPARENT_FRAMEBUFFER: int = 0x0002000A
76
HOVERED: int = 0x0002000B
77
FOCUS_ON_SHOW: int = 0x0002000C
78
MOUSE_PASSTHROUGH: int = 0x0002000D
79
POSITION_X: int = 0x0002000E
80
POSITION_Y: int = 0x0002000F
81

82
# Framebuffer properties
83
RED_BITS: int = 0x00021001
84
GREEN_BITS: int = 0x00021002
85
BLUE_BITS: int = 0x00021003
86
ALPHA_BITS: int = 0x00021004
87
DEPTH_BITS: int = 0x00021005
88
STENCIL_BITS: int = 0x00021006
89
SAMPLES: int = 0x0002100D
90
SRGB_CAPABLE: int = 0x0002100E
91
DOUBLEBUFFER: int = 0x00021010
92

93
# Context properties
94
CLIENT_API: int = 0x00022001
95
CONTEXT_VERSION_MAJOR: int = 0x00022002
96
CONTEXT_VERSION_MINOR: int = 0x00022003
97
CONTEXT_REVISION: int = 0x00022004
98
CONTEXT_ROBUSTNESS: int = 0x00022005
99
OPENGL_FORWARD_COMPAT: int = 0x00022006
100
OPENGL_DEBUG_CONTEXT: int = 0x00022007
101
OPENGL_PROFILE: int = 0x00022008
102
CONTEXT_RELEASE_BEHAVIOR: int = 0x00022009
103
CONTEXT_NO_ERROR: int = 0x0002200A
104
CONTEXT_CREATION_API: int = 0x0002200B
105
```
106

107
### Window State
108

109
Query and control window state and lifecycle.
110

111
```python { .api }
112
def window_should_close(window) -> int:
113
    """
114
    Check the close flag of the window.
115
    
116
    Parameters:
117
        window: Window to query
118
        
119
    Returns:
120
        int: 1 if window should close, 0 otherwise
121
    """
122

123
def set_window_should_close(window, value: int) -> None:
124
    """
125
    Set the close flag of the window.
126
    
127
    Parameters:
128
        window: Window to modify
129
        value: Close flag value (1 to close, 0 to keep open)
130
    """
131

132
def iconify_window(window) -> None:
133
    """Iconify (minimize) the window."""
134

135
def restore_window(window) -> None:
136
    """Restore the window from iconified/maximized state."""
137

138
def maximize_window(window) -> None:
139
    """Maximize the window."""
140

141
def show_window(window) -> None:
142
    """Make the window visible."""
143

144
def hide_window(window) -> None:
145
    """Hide the window."""
146

147
def focus_window(window) -> None:
148
    """Bring the window to front and set input focus."""
149

150
def request_window_attention(window) -> None:
151
    """Request user attention to the window."""
152
```
153

154
### Window Properties
155

156
Get and set window title, position, size, and other properties.
157

158
```python { .api }
159
def set_window_title(window, title: str) -> None:
160
    """Set the window title."""
161

162
def get_window_title(window) -> str:
163
    """Get the window title."""
164

165
def get_window_pos(window) -> tuple[int, int]:
166
    """
167
    Get the position of the window's client area.
168
    
169
    Returns:
170
        tuple: (x, y) position in screen coordinates
171
    """
172

173
def set_window_pos(window, xpos: int, ypos: int) -> None:
174
    """Set the position of the window's client area."""
175

176
def get_window_size(window) -> tuple[int, int]:
177
    """
178
    Get the size of the window's client area.
179
    
180
    Returns:
181
        tuple: (width, height) in screen coordinates
182
    """
183

184
def set_window_size(window, width: int, height: int) -> None:
185
    """Set the size of the window's client area."""
186

187
def get_framebuffer_size(window) -> tuple[int, int]:
188
    """
189
    Get the size of the framebuffer in pixels.
190
    
191
    Returns:
192
        tuple: (width, height) in pixels
193
    """
194

195
def get_window_frame_size(window) -> tuple[int, int, int, int]:
196
    """
197
    Get the size of the frame around the window.
198
    
199
    Returns:
200
        tuple: (left, top, right, bottom) frame sizes in screen coordinates
201
    """
202

203
def get_window_content_scale(window) -> tuple[float, float]:
204
    """
205
    Get the content scale for the window.
206
    
207
    Returns:
208
        tuple: (x_scale, y_scale) content scale factors
209
    """
210
```
211

212
### Window Constraints
213

214
Set size limits and aspect ratio constraints.
215

216
```python { .api }
217
def set_window_size_limits(window, minwidth: int, minheight: int, 
218
                          maxwidth: int, maxheight: int) -> None:
219
    """
220
    Set the size limits of the window.
221
    
222
    Parameters:
223
        minwidth: Minimum width, or DONT_CARE
224
        minheight: Minimum height, or DONT_CARE
225
        maxwidth: Maximum width, or DONT_CARE  
226
        maxheight: Maximum height, or DONT_CARE
227
    """
228

229
def set_window_aspect_ratio(window, numer: int, denom: int) -> None:
230
    """
231
    Set the aspect ratio of the window.
232
    
233
    Parameters:
234
        numer: Numerator of aspect ratio, or DONT_CARE
235
        denom: Denominator of aspect ratio
236
    """
237
```
238

239
### Window Attributes
240

241
Query and modify window attributes.
242

243
```python { .api }
244
def get_window_attrib(window, attrib: int) -> int:
245
    """
246
    Get a window attribute.
247
    
248
    Parameters:
249
        attrib: Attribute to query
250
        
251
    Returns:
252
        int: Attribute value
253
    """
254

255
def set_window_attrib(window, attrib: int, value: int) -> None:
256
    """
257
    Set a modifiable window attribute.
258
    
259
    Parameters:
260
        attrib: Attribute to set
261
        value: New attribute value
262
    """
263

264
def get_window_opacity(window) -> float:
265
    """
266
    Get the opacity of the window.
267
    
268
    Returns:
269
        float: Window opacity (0.0-1.0)
270
    """
271

272
def set_window_opacity(window, opacity: float) -> None:
273
    """
274
    Set the opacity of the window.
275
    
276
    Parameters:
277
        opacity: Opacity value (0.0-1.0)
278
    """
279
```
280

281
### Window User Data
282

283
Associate custom data with windows.
284

285
```python { .api }
286
def set_window_user_pointer(window, pointer) -> None:
287
    """
288
    Set the user pointer of the window.
289
    
290
    Parameters:
291
        pointer: User data (any Python object)
292
    """
293

294
def get_window_user_pointer(window):
295
    """
296
    Get the user pointer of the window.
297
    
298
    Returns:
299
        User data object previously set
300
    """
301
```
302

303
### Window Icons
304

305
Set custom window icons.
306

307
```python { .api }
308
def set_window_icon(window, count: int, images) -> None:
309
    """
310
    Set the icon of the window.
311
    
312
    Parameters:
313
        count: Number of images in the array
314
        images: Array of image data or PIL Image objects
315
    """
316
```
317

318
### Window Monitor Association
319

320
Manage fullscreen and windowed mode.
321

322
```python { .api }
323
def get_window_monitor(window):
324
    """
325
    Get the monitor that the window uses for fullscreen mode.
326
    
327
    Returns:
328
        GLFWmonitor: Monitor handle, or None if windowed
329
    """
330

331
def set_window_monitor(window, monitor, xpos: int, ypos: int, 
332
                      width: int, height: int, refresh_rate: int) -> None:
333
    """
334
    Set the mode, monitor, video mode and placement of a window.
335
    
336
    Used to switch between fullscreen and windowed mode or change
337
    the monitor and video mode of a fullscreen window.
338
    
339
    Parameters:
340
        monitor: Target monitor, or None for windowed mode
341
        xpos: Window x-position for windowed mode
342
        ypos: Window y-position for windowed mode  
343
        width: Window/video mode width
344
        height: Window/video mode height
345
        refresh_rate: Video mode refresh rate, or DONT_CARE
346
    """
347
```
348

349
### Window Callbacks
350

351
Register callback functions for window events.
352

353
```python { .api }
354
def set_window_pos_callback(window, cbfun) -> callable:
355
    """
356
    Set the window position callback.
357
    
358
    Parameters:
359
        cbfun: Callback function or None
360
            Signature: callback(window, xpos: int, ypos: int)
361
    """
362

363
def set_window_size_callback(window, cbfun) -> callable:
364
    """
365
    Set the window size callback.
366
    
367
    Parameters:
368
        cbfun: Callback function or None
369
            Signature: callback(window, width: int, height: int)
370
    """
371

372
def set_window_close_callback(window, cbfun) -> callable:
373
    """
374
    Set the window close callback.
375
    
376
    Parameters:
377
        cbfun: Callback function or None
378
            Signature: callback(window)
379
    """
380

381
def set_window_refresh_callback(window, cbfun) -> callable:
382
    """
383
    Set the window refresh callback.
384
    
385
    Parameters:
386
        cbfun: Callback function or None
387
            Signature: callback(window)
388
    """
389

390
def set_window_focus_callback(window, cbfun) -> callable:
391
    """
392
    Set the window focus callback.
393
    
394
    Parameters:
395
        cbfun: Callback function or None
396
            Signature: callback(window, focused: int)
397
    """
398

399
def set_window_iconify_callback(window, cbfun) -> callable:
400
    """
401
    Set the window iconify callback.
402
    
403
    Parameters:
404
        cbfun: Callback function or None  
405
            Signature: callback(window, iconified: int)
406
    """
407

408
def set_window_maximize_callback(window, cbfun) -> callable:
409
    """
410
    Set the window maximize callback.
411
    
412
    Parameters:
413
        cbfun: Callback function or None
414
            Signature: callback(window, maximized: int)
415
    """
416

417
def set_framebuffer_size_callback(window, cbfun) -> callable:
418
    """
419
    Set the framebuffer size callback.
420
    
421
    Parameters:
422
        cbfun: Callback function or None
423
            Signature: callback(window, width: int, height: int)
424
    """
425

426
def set_window_content_scale_callback(window, cbfun) -> callable:
427
    """
428
    Set the window content scale callback.
429
    
430
    Parameters:
431
        cbfun: Callback function or None
432
            Signature: callback(window, xscale: float, yscale: float)
433
    """
434
```
435

436
## Usage Examples
437

438
### Basic Window Creation
439

440
```python
441
import glfw
442

443
# Initialize GLFW
444
glfw.init()
445

446
# Create a windowed mode window and its OpenGL context
447
window = glfw.create_window(640, 480, "Hello World", None, None)
448

449
if not window:
450
    glfw.terminate()
451
    raise Exception("Failed to create window")
452

453
# Make the window's context current
454
glfw.make_context_current(window)
455

456
# Main loop
457
while not glfw.window_should_close(window):
458
    glfw.poll_events()
459
    glfw.swap_buffers(window)
460

461
glfw.terminate()
462
```
463

464
### Window with Modern OpenGL Context
465

466
```python
467
import glfw
468

469
glfw.init()
470

471
# Request OpenGL 3.3 Core Profile
472
glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 3)
473
glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 3)
474
glfw.window_hint(glfw.OPENGL_PROFILE, glfw.OPENGL_CORE_PROFILE)
475
glfw.window_hint(glfw.OPENGL_FORWARD_COMPAT, glfw.TRUE)  # macOS compatibility
476

477
window = glfw.create_window(800, 600, "Modern OpenGL", None, None)
478

479
if not window:
480
    glfw.terminate()
481
    raise Exception("Failed to create window")
482

483
glfw.make_context_current(window)
484
# ... rest of application
485
```
486

487
### Fullscreen Window
488

489
```python
490
import glfw
491

492
glfw.init()
493

494
# Get the primary monitor
495
monitor = glfw.get_primary_monitor()
496
mode = glfw.get_video_mode(monitor)
497

498
# Create fullscreen window
499
window = glfw.create_window(mode.size.width, mode.size.height, 
500
                           "Fullscreen", monitor, None)
501
```
502

503
### Window Callbacks
504

505
```python
506
import glfw
507

508
def window_size_callback(window, width, height):
509
    print(f"Window resized to {width}x{height}")
510

511
def window_close_callback(window):
512
    print("Window close requested")
513
    # Could prevent closing by not setting the close flag
514
    # glfw.set_window_should_close(window, False)
515

516
glfw.init()
517
window = glfw.create_window(640, 480, "Callbacks Example", None, None)
518

519
# Set callbacks
520
glfw.set_window_size_callback(window, window_size_callback)
521
glfw.set_window_close_callback(window, window_close_callback)
522

523
# Main loop...
524
```