0
# ImGui
1

2
Python bindings for the amazing Dear ImGui C++ library - a bloat-free immediate mode graphical user interface toolkit. ImGui enables Python developers to create modern GUI applications with a simple, immediate-mode paradigm where UI elements are defined in code and rendered on-demand, making it ideal for tools, debugging interfaces, games, and rapid prototyping.
3

4
## Package Information
5

6
- **Package Name**: imgui
7
- **Language**: Python (with Cython extensions)
8
- **Installation**: `pip install imgui[full]` (includes all rendering backends)
9
- **License**: BSD
10
- **GitHub**: https://github.com/pyimgui/pyimgui
11

12
## Core Imports
13

14
Basic imgui import provides access to all core functionality:
15

16
```python
17
import imgui
18
```
19

20
For integration with specific rendering backends:
21

22
```python
23
from imgui.integrations.glfw import GlfwRenderer
24
from imgui.integrations.pygame import PygameRenderer
25
from imgui.integrations.pyglet import PygletRenderer
26
from imgui.integrations.sdl2 import SDL2Renderer
27
```
28

29
## Basic Usage
30

31
```python
32
import imgui
33
import glfw
34
from imgui.integrations.glfw import GlfwRenderer
35
import OpenGL.GL as gl
36

37
def main():
38
    # Initialize the rendering backend
39
    imgui.create_context()
40
    window = init_glfw()  # Your GLFW window setup
41
    impl = GlfwRenderer(window)
42
    
43
    # Main application loop
44
    while not glfw.window_should_close(window):
45
        glfw.poll_events()
46
        impl.process_inputs()
47
        
48
        # Start new ImGui frame
49
        imgui.new_frame()
50
        
51
        # Create a simple window
52
        if imgui.begin("Hello, ImGui!"):
53
            imgui.text("This is a simple ImGui window")
54
            
55
            if imgui.button("Click me!"):
56
                print("Button was clicked!")
57
            
58
            # Input widgets
59
            text_value = imgui.input_text("Enter text:", "default")[1]
60
            slider_value = imgui.slider_float("Slider", 0.0, 0.0, 1.0)[1]
61
            
62
            # Color picker
63
            color = imgui.color_edit4("Color", 1.0, 0.0, 0.0, 1.0)
64
            
65
        imgui.end()
66
        
67
        # Render
68
        gl.glClear(gl.GL_COLOR_BUFFER_BIT)
69
        imgui.render()
70
        impl.render(imgui.get_draw_data())
71
        glfw.swap_buffers(window)
72
    
73
    impl.shutdown()
74

75
if __name__ == "__main__":
76
    main()
77
```
78

79
## Architecture
80

81
ImGui follows an immediate mode design pattern with these key components:
82

83
- **Context**: Central state manager that tracks all ImGui data and settings
84
- **Frames**: Each application loop creates a new frame where all UI elements are defined
85
- **Windows**: Top-level containers that can be moved, resized, and contain widgets
86
- **Widgets**: Interactive elements like buttons, sliders, text inputs that return their state
87
- **Draw Lists**: Generated rendering commands sent to the graphics backend
88
- **Backends**: Integration layers for different rendering systems (OpenGL, DirectX, etc.)
89

90
The immediate mode approach means no widget objects are retained - UI is rebuilt every frame based on application state, making it extremely simple to create dynamic, reactive interfaces.
91

92
## Capabilities
93

94
### Context Management
95

96
Essential functions for initializing and managing ImGui contexts. These functions are critical for proper ImGui setup and cleanup.
97

98
```python { .api }
99
def create_context() -> None: ...
100
def destroy_context() -> None: ...
101
def get_current_context(): ...
102
def set_current_context(context) -> None: ...
103
def get_io(): ...
104
def get_style(): ...
105
def new_frame() -> None: ...
106
def end_frame() -> None: ...
107
def render() -> None: ...
108
def get_draw_data(): ...
109
def show_demo_window(closable: bool = False) -> None: ...
110
def show_metrics_window(closable: bool = False) -> None: ...
111
def show_about_window(closable: bool = False) -> None: ...
112
def show_user_guide() -> None: ...
113
def get_version() -> str: ...
114
```
115

116
### Core Window Management
117

118
Essential window operations including creating, positioning, sizing, and managing window states. Windows are the fundamental containers for all ImGui content.
119

120
```python { .api }
121
def begin(label: str, closable: bool = False, flags: int = 0) -> bool: ...
122
def end() -> None: ...
123
def set_next_window_size(width: float, height: float, condition: int = ALWAYS) -> None: ...
124
def set_next_window_position(x: float, y: float, condition: int = ALWAYS, pivot_x: float = 0, pivot_y: float = 0) -> None: ...
125
```
126

127
[Window Management](./windows.md)
128

129
### Widget System
130

131
Comprehensive collection of interactive UI elements including buttons, text inputs, sliders, checkboxes, combo boxes, color pickers, and more. These widgets handle user input and return their current state.
132

133
```python { .api }
134
def button(label: str, width: float = 0, height: float = 0) -> bool: ...
135
def input_text(label: str, value: str, buffer_length: int, flags: int = 0) -> tuple[bool, str]: ...
136
def slider_float(label: str, value: float, v_min: float, v_max: float, format: str = "%.3f") -> tuple[bool, float]: ...
137
def checkbox(label: str, state: bool) -> tuple[bool, bool]: ...
138
```
139

140
[Widgets](./widgets.md)
141

142
### Layout and Positioning
143

144
Tools for controlling widget placement, spacing, grouping, and alignment. Includes cursor positioning, same-line placement, indentation, and grouping functions.
145

146
```python { .api }
147
def same_line(position: float = 0.0, spacing: float = -1.0) -> None: ...
148
def separator() -> None: ...
149
def spacing() -> None: ...
150
def indent(width: float = 0.0) -> None: ...
151
```
152

153
[Layout](./layout.md)
154

155
### Input and Interaction
156

157
Mouse and keyboard input handling, item state queries, and focus management. Provides detailed information about user interactions with widgets and windows.
158

159
```python { .api }
160
def is_item_hovered(flags: int = 0) -> bool: ...
161
def is_item_clicked(mouse_button: int = 0) -> bool: ...
162
def is_key_pressed(key_index: int, repeat: bool = False) -> bool: ...
163
def get_mouse_pos() -> tuple[float, float]: ...
164
```
165

166
[Input Handling](./input.md)
167

168
### Styling and Theming
169

170
Comprehensive styling system for customizing colors, spacing, fonts, and visual appearance. Supports style stacks, color themes, and custom styling.
171

172
```python { .api }
173
def push_style_color(variable: int, r: float, g: float, b: float, a: float = 1.0) -> None: ...
174
def pop_style_color(count: int = 1) -> None: ...
175
def push_style_var(variable: int, value: float) -> None: ...
176
def style_colors_dark() -> None: ...
177
```
178

179
[Styling](./styling.md)
180

181
### Tables and Data Display
182

183
Modern table system with sorting, resizing, reordering, and scrolling capabilities. Ideal for displaying structured data with interactive features.
184

185
```python { .api }
186
def begin_table(label: str, column: int, flags: int = 0) -> bool: ...
187
def table_setup_column(label: str, flags: int = 0, init_width_or_weight: float = 0.0) -> None: ...
188
def table_next_row() -> None: ...
189
def table_next_column() -> bool: ...
190
```
191

192
[Tables](./tables.md)
193

194
### Menu Systems
195

196
Complete menu bar and popup menu functionality for creating application menus, context menus, and modal dialogs.
197

198
```python { .api }
199
def begin_main_menu_bar() -> bool: ...
200
def begin_menu(label: str, enabled: bool = True) -> bool: ...
201
def menu_item(label: str, shortcut: str = "", selected: bool = False, enabled: bool = True) -> tuple[bool, bool]: ...
202
def begin_popup(label: str, flags: int = 0) -> bool: ...
203
```
204

205
[Menus and Popups](./menus.md)
206

207
### Tabs and Organization
208

209
Tab bar system for organizing content into multiple views with support for reordering, closing, and dynamic tab management.
210

211
```python { .api }
212
def begin_tab_bar(identifier: str, flags: int = 0) -> bool: ...
213
def begin_tab_item(label: str, opened: bool = None, flags: int = 0) -> tuple[bool, bool]: ...
214
def tab_item_button(label: str, flags: int = 0) -> bool: ...
215
```
216

217
[Tabs](./tabs.md)
218

219
### Drawing and Graphics
220

221
Low-level drawing capabilities for custom graphics, shapes, text rendering, and advanced visual effects using draw lists.
222

223
```python { .api }
224
def get_window_draw_list(): ...
225
def get_background_draw_list(): ...
226
class _DrawList:
227
    def add_line(self, p1: tuple, p2: tuple, color: int, thickness: float = 1.0) -> None: ...
228
    def add_rect(self, p_min: tuple, p_max: tuple, color: int, rounding: float = 0.0) -> None: ...
229
```
230

231
[Drawing](./drawing.md)
232

233
### Python Utilities
234

235
Python-specific helper functions and utilities that extend ImGui's functionality with convenient features for Python developers.
236

237
```python { .api }
238
from imgui import extra
239

240
def extra.text_ansi(text: str) -> None: ...
241
def extra.text_ansi_colored(text: str) -> None: ...
242
def extra.font(font_object): ...
243
def extra.styled(style_vars: dict): ...
244
def extra.colored(color_vars: dict): ...
245
def extra.vertex_buffer_vertex_pos_offset() -> int: ...
246
def extra.vertex_buffer_vertex_uv_offset() -> int: ...
247
def extra.vertex_buffer_vertex_col_offset() -> int: ...
248
def extra.vertex_buffer_vertex_size() -> int: ...
249
def extra.index_buffer_index_size() -> int: ...
250
```
251

252
### Advanced Internal API
253

254
Low-level internal ImGui functions for advanced use cases and custom widget development. Use with caution as these APIs may change between versions.
255

256
```python { .api }
257
from imgui import internal
258

259
def internal.push_item_flag(option: int, enabled: bool) -> None: ...
260
def internal.pop_item_flag() -> None: ...
261
```
262

263
### Integration Backends
264

265
Renderer integrations for various graphics libraries and frameworks including GLFW, SDL2, Pygame, Pyglet, and Cocos2D.
266

267
```python { .api }
268
class GlfwRenderer:
269
    def __init__(self, window) -> None: ...
270
    def process_inputs() -> None: ...
271
    def render(draw_data) -> None: ...
272
```
273

274
[Integration Backends](./integrations.md)