0
# Input Widgets
1

2
Input widgets enable user interaction through various interface elements like buttons, text entry, checkboxes, sliders, and selection lists. These widgets form the core interactive elements of GUI applications.
3

4
## Capabilities
5

6
### Push Button
7

8
The PushButton widget creates clickable buttons that execute commands when pressed.
9

10
```python { .api }
11
class PushButton:
12
    def __init__(self, master, command=None, args=None, text="Button", 
13
                 image=None, pady=10, padx=10, grid=None, align=None, 
14
                 icon=None, visible=True, enabled=None, width=None, 
15
                 height=None):
16
        """
17
        Create a clickable button widget.
18
        
19
        Args:
20
            master: Parent widget (App, Window, or container)
21
            command (function): Function to call when clicked
22
            args (list): Arguments to pass to command function
23
            text (str): Button text
24
            image (str): Path to image file for button
25
            pady (int): Vertical padding in pixels
26
            padx (int): Horizontal padding in pixels
27
            grid (list): Grid position [x, y] for grid layout
28
            align (str): Alignment ("left", "right", "top", "bottom")
29
            icon (str): Path to icon file
30
            visible (bool): Initial visibility state
31
            enabled (bool): Initial enabled state
32
            width (int): Button width in pixels
33
            height (int): Button height in pixels
34
        """
35
        
36
    def toggle(self):
37
        """Toggle button state (for toggle buttons)."""
38
        
39
    @property
40
    def text(self) -> str:
41
        """Get/set the button text."""
42
        
43
    @text.setter
44
    def text(self, value: str): ...
45
        
46
    @property
47
    def image(self) -> str:
48
        """Get/set the button image."""
49
        
50
    @image.setter
51
    def image(self, value: str): ...
52
        
53
    @property
54
    def icon(self) -> str:
55
        """Get/set the button icon."""
56
        
57
    @icon.setter
58
    def icon(self, value: str): ...
59
        
60
    # Event handlers
61
    @property
62
    def when_clicked(self):
63
        """Callback function when button is clicked."""
64
        
65
    @when_clicked.setter
66
    def when_clicked(self, callback): ...
67
        
68
    @property
69
    def when_left_button_pressed(self):
70
        """Callback when left mouse button is pressed."""
71
        
72
    @when_left_button_pressed.setter
73
    def when_left_button_pressed(self, callback): ...
74
        
75
    @property
76
    def when_left_button_released(self):
77
        """Callback when left mouse button is released."""
78
        
79
    @when_left_button_released.setter
80
    def when_left_button_released(self, callback): ...
81
```
82

83
### Text Box
84

85
The TextBox widget provides single-line or multi-line text input capabilities.
86

87
```python { .api }
88
class TextBox:
89
    def __init__(self, master, text="", width=10, height=1, grid=None,
90
                 align=None, visible=True, enabled=None, multiline=False,
91
                 scrollbar=False, command=None, hide_text=False):
92
        """
93
        Create a text input widget.
94
        
95
        Args:
96
            master: Parent widget (App, Window, or container)
97
            text (str): Initial text content
98
            width (int): Width in characters
99
            height (int): Height in lines (for multiline)
100
            grid (list): Grid position [x, y] for grid layout
101
            align (str): Alignment ("left", "right", "top", "bottom")
102
            visible (bool): Initial visibility state
103
            enabled (bool): Initial enabled state
104
            multiline (bool): Enable multiple lines
105
            scrollbar (bool): Show scrollbar for multiline
106
            command (function): Callback when text changes
107
            hide_text (bool): Hide text for password entry
108
        """
109
        
110
    def clear(self):
111
        """Clear all text from the text box."""
112
        
113
    def append(self, text):
114
        """
115
        Append text to the end of the text box.
116
        
117
        Args:
118
            text (str): Text to append
119
        """
120
        
121
    def get(self):
122
        """Get the current text content."""
123
        
124
    @property
125
    def value(self) -> str:
126
        """Get/set the text content."""
127
        
128
    @value.setter
129
    def value(self, text: str): ...
130
        
131
    @property
132
    def hide_text(self) -> bool:
133
        """Get/set password mode (hide text with asterisks)."""
134
        
135
    @hide_text.setter
136
    def hide_text(self, value: bool): ...
137
        
138
    @property
139
    def multiline(self) -> bool:
140
        """Get/set multiline mode."""
141
        
142
    @multiline.setter
143
    def multiline(self, value: bool): ...
144
        
145
    # Event handlers
146
    @property
147
    def when_clicked(self):
148
        """Callback when text box is clicked."""
149
        
150
    @when_clicked.setter
151
    def when_clicked(self, callback): ...
152
        
153
    @property
154
    def when_key_pressed(self):
155
        """Callback when a key is pressed."""
156
        
157
    @when_key_pressed.setter
158
    def when_key_pressed(self, callback): ...
159
        
160
    @property
161
    def when_key_released(self):
162
        """Callback when a key is released."""
163
        
164
    @when_key_released.setter
165
    def when_key_released(self, callback): ...
166
```
167

168
### Check Box
169

170
The CheckBox widget provides a boolean checkbox input for yes/no or on/off selections.
171

172
```python { .api }
173
class CheckBox:
174
    def __init__(self, master, text="", command=None, grid=None, align=None, 
175
                 visible=True, enabled=None, width=None, height=None):
176
        """
177
        Create a checkbox widget.
178
        
179
        Args:
180
            master: Parent widget (App, Window, or container)
181
            text (str): Label text next to checkbox
182
            command (function): Callback when state changes
183
            grid (list): Grid position [x, y] for grid layout
184
            align (str): Alignment ("left", "right", "top", "bottom")
185
            visible (bool): Initial visibility state
186
            enabled (bool): Initial enabled state
187
            width (int): Widget width in pixels
188
            height (int): Widget height in pixels
189
        """
190
        
191
    @property
192
    def value(self) -> int:
193
        """Get/set checkbox state (1 for checked, 0 for unchecked)."""
194
        
195
    @value.setter
196
    def value(self, state: int): ...
197
        
198
    @property
199
    def text(self) -> str:
200
        """Get/set the checkbox label text."""
201
        
202
    @text.setter
203
    def text(self, value: str): ...
204
        
205
    # Event handler
206
    @property
207
    def when_clicked(self):
208
        """Callback when checkbox is clicked."""
209
        
210
    @when_clicked.setter
211
    def when_clicked(self, callback): ...
212
```
213

214
### Radio Button
215

216
The RadioButton widget creates individual radio buttons. **Note**: RadioButton is designed for internal use by ButtonGroup and should not typically be instantiated directly unless you provide your own StringVar for coordination.
217

218
```python { .api }
219
class RadioButton:
220
    def __init__(self, master, text, value, variable, command=None, grid=None, 
221
                 align=None, visible=True, enabled=None):
222
        """
223
        Create a radio button widget (typically used internally by ButtonGroup).
224
        
225
        Args:
226
            master: Parent widget (App, Window, or container)
227
            text (str): Label text next to radio button (required)
228
            value: Value associated with this radio button (required)
229
            variable: StringVar object to coordinate with other radio buttons (required)
230
            command (function): Callback when selected
231
            grid (list): Grid position [x, y] for grid layout
232
            align (str): Alignment ("left", "right", "top", "bottom")
233
            visible (bool): Initial visibility state
234
            enabled (bool): Initial enabled state
235
        """
236
        
237
    @property
238
    def value(self):
239
        """Get/set the radio button value."""
240
        
241
    @value.setter
242
    def value(self, val): ...
243
        
244
    @property
245
    def text(self) -> str:
246
        """Get/set the radio button label text."""
247
        
248
    @text.setter
249
    def text(self, value: str): ...
250
```
251

252
### Slider
253

254
The Slider widget provides a draggable slider for selecting numeric values within a range.
255

256
```python { .api }
257
class Slider:
258
    def __init__(self, master, start=0, end=100, horizontal=True, command=None, 
259
                 grid=None, align=None, visible=True, enabled=None, 
260
                 width=None, height=None):
261
        """
262
        Create a slider widget for numeric input.
263
        
264
        Args:
265
            master: Parent widget (App, Window, or container)
266
            start (int): Minimum value
267
            end (int): Maximum value
268
            horizontal (bool): True for horizontal, False for vertical
269
            command (function): Callback when value changes
270
            grid (list): Grid position [x, y] for grid layout
271
            align (str): Alignment ("left", "right", "top", "bottom")
272
            visible (bool): Initial visibility state
273
            enabled (bool): Initial enabled state
274
            width (int): Widget width in pixels
275
            height (int): Widget height in pixels
276
        """
277
        
278
    @property
279
    def value(self) -> int:
280
        """Get/set the slider value."""
281
        
282
    @value.setter
283
    def value(self, val: int): ...
284
        
285
    @property
286
    def start(self) -> int:
287
        """Get/set the minimum value."""
288
        
289
    @start.setter
290
    def start(self, val: int): ...
291
        
292
    @property
293
    def end(self) -> int:
294
        """Get/set the maximum value."""
295
        
296
    @end.setter  
297
    def end(self, val: int): ...
298
```
299

300
### Combo Box
301

302
The Combo widget creates a dropdown list for selecting from predefined options.
303

304
```python { .api }
305
class Combo:
306
    def __init__(self, master, options=[], selected=None, command=None, 
307
                 grid=None, align=None, visible=True, enabled=None, 
308
                 width=None, height=None):
309
        """
310
        Create a dropdown/combobox widget.
311
        
312
        Args:
313
            master: Parent widget (App, Window, or container)
314
            options (list): List of available options
315
            selected: Initially selected option
316
            command (function): Callback when selection changes
317
            grid (list): Grid position [x, y] for grid layout
318
            align (str): Alignment ("left", "right", "top", "bottom")
319
            visible (bool): Initial visibility state
320
            enabled (bool): Initial enabled state
321
            width (int): Widget width in pixels
322
            height (int): Widget height in pixels
323
        """
324
        
325
    def append(self, option):
326
        """
327
        Add an option to the dropdown.
328
        
329
        Args:
330
            option: Option to add
331
        """
332
        
333
    def remove(self, option):
334
        """
335
        Remove an option from the dropdown.
336
        
337
        Args:
338
            option: Option to remove
339
        """
340
        
341
    def clear(self):
342
        """Remove all options from the dropdown."""
343
        
344
    def insert(self, index, option):
345
        """
346
        Insert an option at a specific position.
347
        
348
        Args:
349
            index (int): Position to insert at
350
            option: Option to insert
351
        """
352
        
353
    @property
354
    def options(self) -> list:
355
        """Get/set the list of available options."""
356
        
357
    @options.setter
358
    def options(self, option_list: list): ...
359
        
360
    @property
361
    def value(self):
362
        """Get/set the selected option."""
363
        
364
    @value.setter
365
    def value(self, option): ...
366
```
367

368
### List Box
369

370
The ListBox widget displays a scrollable list of items that users can select from.
371

372
```python { .api }
373
class ListBox:
374
    def __init__(self, master, items=[], selected=None, command=None, 
375
                 multiselect=False, scrollbar=False, grid=None, align=None, 
376
                 visible=True, enabled=None, width=None, height=None):
377
        """
378
        Create a list selection widget.
379
        
380
        Args:
381
            master: Parent widget (App, Window, or container)
382
            items (list): List of items to display
383
            selected: Initially selected item(s)
384
            command (function): Callback when selection changes
385
            multiselect (bool): Allow multiple selections
386
            scrollbar (bool): Show scrollbar when needed
387
            grid (list): Grid position [x, y] for grid layout
388
            align (str): Alignment ("left", "right", "top", "bottom")
389
            visible (bool): Initial visibility state
390
            enabled (bool): Initial enabled state
391
            width (int): Widget width in pixels
392
            height (int): Widget height in pixels
393
        """
394
        
395
    def append(self, item):
396
        """
397
        Add an item to the list.
398
        
399
        Args:
400
            item: Item to add
401
        """
402
        
403
    def remove(self, item):
404
        """
405
        Remove an item from the list.
406
        
407
        Args:
408
            item: Item to remove
409
        """
410
        
411
    def clear(self):
412
        """Remove all items from the list."""
413
        
414
    def insert(self, index, item):
415
        """
416
        Insert an item at a specific position.
417
        
418
        Args:
419
            index (int): Position to insert at
420
            item: Item to insert
421
        """
422
        
423
    @property
424
    def items(self) -> list:
425
        """Get/set the list of items."""
426
        
427
    @items.setter
428
    def items(self, item_list: list): ...
429
        
430
    @property
431
    def value(self):
432
        """Get/set the selected item(s)."""
433
        
434
    @value.setter
435
    def value(self, item): ...
436
```
437

438
## Common Input Widget Patterns
439

440
### Form Validation
441

442
```python
443
from guizero import App, Text, TextBox, PushButton
444

445
app = App()
446

447
name_label = Text(app, text="Name:")
448
name_box = TextBox(app)
449

450
email_label = Text(app, text="Email:")
451
email_box = TextBox(app)
452

453
result_text = Text(app)
454

455
def validate_form():
456
    if not name_box.value.strip():
457
        result_text.value = "Name is required"
458
        result_text.text_color = "red"
459
    elif "@" not in email_box.value:
460
        result_text.value = "Valid email is required"
461
        result_text.text_color = "red"
462
    else:
463
        result_text.value = "Form is valid!"
464
        result_text.text_color = "green"
465

466
submit_button = PushButton(app, text="Submit", command=validate_form)
467

468
app.display()
469
```
470

471
### Dynamic Option Updates
472

473
```python
474
from guizero import App, Combo, ListBox, PushButton
475

476
app = App()
477

478
# Combo box with dynamic options
479
combo = Combo(app, options=["Option 1", "Option 2"])
480

481
def add_option():
482
    new_option = f"Option {len(combo.options) + 1}"
483
    combo.append(new_option)
484

485
add_button = PushButton(app, text="Add Option", command=add_option)
486

487
app.display()
488
```
489

490
### Event Handling
491

492
```python
493
from guizero import App, TextBox, Text
494

495
app = App()
496

497
text_input = TextBox(app)
498
status_text = Text(app)
499

500
def on_key_press(event_data):
501
    status_text.value = f"Key pressed: {event_data.key}"
502

503
def on_text_change():
504
    status_text.value = f"Text length: {len(text_input.value)}"
505

506
text_input.when_key_pressed = on_key_press
507
text_input.when_clicked = on_text_change
508

509
app.display()
510
```