Skip to content

Commit 852347e

Browse files
docs: 全面更新 ui 模块文档,新增 ProgressView/Stepper/TextField扩展属性/Image.crop 等 API
1 parent e9e1b85 commit 852347e

3 files changed

Lines changed: 413 additions & 29 deletions

File tree

docs/ui-module-en.md

Lines changed: 142 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,10 @@
2424
16. [TableView](#16-tableview)
2525
17. [WebView](#17-webview)
2626
18. [ActivityIndicator](#18-activityindicator)
27+
18b. [ProgressView](#18b-progressview)
28+
18c. [Stepper](#18c-stepper)
2729
19. [NavigationView](#19-navigationview)
28-
20. [Custom View and Drawing](#20-custom-view-and-drawing)
30+
20. [Custom View and Drawing](#20-custom-view-and-drawing) (incl. Path, Image, ImageContext updates)
2931
21. [load_view and load_view_str](#21-load_view-and-load_view_str)
3032
22. [animate and Utility Functions](#22-animate-and-utility-functions)
3133
23. [Constants and Enums](#23-constants-and-enums)
@@ -63,6 +65,8 @@ The built-in `ui` module in Python IDE provides native iOS UI capabilities that
6365
| Table view | `ui.TableView` | List display; data_source, action, delegate |
6466
| Web view | `ui.WebView` | Load URL or HTML; supports eval_js |
6567
| Activity indicator | `ui.ActivityIndicator` | Loading spinner |
68+
| Progress view | `ui.ProgressView` | Linear progress bar (0–1) |
69+
| Stepper | `ui.Stepper` | +/- buttons with range and step |
6670
| Navigation view | `ui.NavigationView` | Stack-based navigation with navigation bar |
6771
| Canvas view | `ui.CanvasView` | Custom drawing; override draw |
6872

@@ -176,6 +180,10 @@ v = ui.View(frame=(0, 0, 320, 480))
176180
| `touch_enabled` | `bool` | Whether view receives touches; default True |
177181
| `multitouch_enabled` | `bool` | Multi-touch; default False |
178182
| `transform` | `ui.Transform` or `None` | Affine transform |
183+
| `clips_to_bounds` | `bool` | Clip subviews to view bounds |
184+
| `accessibility_label` | `str` | VoiceOver label |
185+
| `accessibility_value` | `str` | VoiceOver value |
186+
| `accessibility_hint` | `str` | VoiceOver hint |
179187
| `title` | `str` | Navigation bar title when presented |
180188
| `left_button_items` | `tuple` | Left bar button items |
181189
| `right_button_items` | `tuple` | Right bar button items |
@@ -200,7 +208,13 @@ v.background_color = '#ff000080' # With alpha
200208
| `remove_from_superview()` | Remove self from parent |
201209
| `bring_to_front()` | Move to front of siblings |
202210
| `send_to_back()` | Move to back of siblings |
211+
| `bring_subview_to_front(subview)` | Bring specific subview to front |
212+
| `send_subview_to_back(subview)` | Send specific subview to back |
203213
| `set_needs_display()` | Mark as needing redraw |
214+
| `set_needs_layout()` | Request layout update |
215+
| `size_to_fit()` | Resize to fit content |
216+
| `point_from_window(point)` | Convert window coords to view coords |
217+
| `point_to_window(point)` | Convert view coords to window coords |
204218

205219
### Read-Only Properties
206220

@@ -320,6 +334,9 @@ btn = ui.Button(frame=(50, 100, 200, 44))
320334
|----------|------|-------------|
321335
| `title` | `str` | Button title |
322336
| `title_color` | `str` or `tuple` | Title color |
337+
| `font` | `tuple` or `str` | Font, e.g. `('Helvetica-Bold', 18)` |
338+
| `image` | `ui.Image` | Foreground image |
339+
| `background_image` | `ui.Image` | Background image |
323340
| `enabled` | `bool` | Whether tap is enabled; default True |
324341

325342
### action Callback
@@ -399,16 +416,23 @@ tf = ui.TextField(text='Initial value')
399416
| `text` | `str` | Current text |
400417
| `placeholder` | `str` | Placeholder |
401418
| `text_color` | `str` or `tuple` | Text color |
419+
| `font` | `tuple` | Font, e.g. `('Helvetica', 16)` |
402420
| `alignment` | `int` | Alignment |
403421
| `secure` | `bool` | Password input (masked) |
404422
| `keyboard_type` | `int` | Keyboard type |
423+
| `autocapitalization_type` | `int` | Auto-caps (`0` none / `1` words / `2` sentences / `3` all) |
424+
| `autocorrection_type` | `int` | Auto-correct (`0` default / `1` off / `2` on) |
425+
| `spellchecking_type` | `int` | Spellcheck (`0` default / `1` off / `2` on) |
426+
| `clear_button_mode` | `int` | Clear button (`0` never / `1` while editing / `3` always) |
427+
| `return_key_type` | `int` | Return key (`0` default / `4` Search / `9` Done, etc.) |
428+
| `bordered` | `bool` | Show border style |
405429

406-
### action Callback
407-
408-
Fired when editing ends (blur or return):
430+
### Callbacks
409431

410432
```python
411-
tf.action = lambda sender: print('Input:', sender.text)
433+
tf.action = lambda sender: print('Input:', sender.text) # Return / blur
434+
tf.began_editing = lambda sender: print('Editing started') # Focus gained
435+
tf.ended_editing = lambda sender: print('Editing ended') # Focus lost
412436
```
413437

414438
---
@@ -431,6 +455,18 @@ tv = ui.TextView(text='Multi-line content')
431455
| `selectable` | `bool` | Whether selectable |
432456
| `text_color` | `str` or `tuple` | Text color |
433457
| `font` | `(name, size)` | Font |
458+
| `alignment` | `int` | Text alignment `ui.ALIGN_*` |
459+
| `selected_range` | `(start, length)` | Current selection range |
460+
| `content_size` | `(w, h)` | Read-only, text content size |
461+
| `content_offset` | `(x, y)` | Scroll offset |
462+
| `auto_content_inset` | `bool` | Auto-adjust inset for keyboard |
463+
464+
### Callbacks
465+
466+
```python
467+
tv.began_editing = lambda sender: print('Editing started')
468+
tv.ended_editing = lambda sender: print('Editing ended')
469+
```
434470

435471
### delegate
436472

@@ -439,6 +475,7 @@ Set an object implementing:
439475
| Method | Description |
440476
|--------|-------------|
441477
| `textview_did_begin_editing(textview)` | Fired when editing starts |
478+
| `textview_did_change(textview)` | Fired when content changes |
442479
| `textview_did_end_editing(textview)` | Fired when editing ends |
443480

444481
```python
@@ -606,6 +643,11 @@ sv.content_size = (320, 800)
606643
| `always_bounce_vertical` | `bool` | Always bounce vertically |
607644
| `scroll_enabled` | `bool` | Whether scrolling is enabled |
608645
| `paging_enabled` | `bool` | Paging mode |
646+
| `shows_vertical_scroll_indicator` | `bool` | Show vertical scroll indicator |
647+
| `shows_horizontal_scroll_indicator` | `bool` | Show horizontal scroll indicator |
648+
| `zoom_scale` | `float` | Current zoom scale |
649+
| `min_zoom_scale` | `float` | Minimum zoom scale |
650+
| `max_zoom_scale` | `float` | Maximum zoom scale |
609651

610652
### Methods
611653

@@ -657,6 +699,14 @@ tv.frame = (0, 0, 320, 400)
657699
| `data_source` | `list` | Data; see format below |
658700
| `action` | `callable` | Row selection callback |
659701
| `delegate` | `object` | Delegate object |
702+
| `row_height` | `float` | Default row height |
703+
| `editing` | `bool` | Whether in editing mode |
704+
| `selected_row` | `tuple` | Currently selected row `(section, row)` |
705+
| `separator_color` | `str` or `tuple` | Separator line color |
706+
| `allows_selection` | `bool` | Whether selection is enabled |
707+
| `allows_multiple_selection` | `bool` | Whether multi-selection is enabled |
708+
| `delete_enabled` | `bool` | Whether swipe-to-delete is enabled |
709+
| `move_enabled` | `bool` | Whether drag-to-reorder is enabled |
660710

661711
### data_source Format
662712

@@ -754,6 +804,56 @@ ai.stop() # or ai.stop_animating()
754804

755805
---
756806

807+
## 18b. ProgressView
808+
809+
### Creation
810+
811+
```python
812+
pv = ui.ProgressView()
813+
pv.frame = (20, 100, 280, 10)
814+
pv.progress = 0.5 # 50%
815+
```
816+
817+
### Properties
818+
819+
| Property | Type | Description |
820+
|----------|------|-------------|
821+
| `progress` | `float` | Progress value, 0.0 to 1.0 |
822+
| `progress_tint_color` | `str` or `tuple` | Completed portion color |
823+
| `track_tint_color` | `str` or `tuple` | Track (remaining) color |
824+
825+
---
826+
827+
## 18c. Stepper
828+
829+
### Creation
830+
831+
```python
832+
st = ui.Stepper()
833+
st.frame = (100, 100, 94, 29)
834+
```
835+
836+
### Properties
837+
838+
| Property | Type | Description |
839+
|----------|------|-------------|
840+
| `value` | `float` | Current value |
841+
| `minimum_value` | `float` | Minimum (default 0) |
842+
| `maximum_value` | `float` | Maximum (default 100) |
843+
| `step_value` | `float` | Step increment (default 1) |
844+
| `continuous` | `bool` | Continuous change on long press |
845+
| `wraps` | `bool` | Wrap around when exceeding range |
846+
| `tint_color` | `str` or `tuple` | Tint color |
847+
| `enabled` | `bool` | Whether enabled |
848+
849+
### Callback
850+
851+
```python
852+
st.action = lambda sender: print('Value:', sender.value)
853+
```
854+
855+
---
856+
757857
## 19. NavigationView
758858

759859
See [5. present and Display](#5-present-and-display).
@@ -815,20 +915,55 @@ cv.render = draw_canvas
815915
| `path.move_to(x, y)` / `path.line_to(x, y)` | Line path |
816916
| `path.add_arc(...)` | Arc |
817917
| `path.add_curve(...)` | Bezier curve |
918+
| `path.add_rect(x, y, w, h)` | Rectangle sub-path |
919+
| `path.add_oval(x, y, w, h)` | Oval sub-path |
920+
| `path.copy()` | Deep copy of path |
921+
| `path.hit_test(x, y)` | Test if point is inside path |
922+
| `path.get_bounding_box()` | Bounding rect `(x, y, w, h)` |
818923
| `GState()` | Save / restore state |
819924
| `ui.set_blend_mode(mode)` | Blend mode |
820925
| `ui.set_shadow(...)` | Shadow |
821926

822927
### ImageContext
823928

929+
**Method 1: Context manager (recommended)**
930+
824931
```python
825932
with ui.ImageContext(200, 200) as ctx:
826933
ui.set_color('blue')
827934
ui.fill_rect(0, 0, 200, 200)
828-
# ... more drawing ...
829-
img = ctx.get_image() # Returns PIL.Image
935+
img = ctx.get_image() # ui.Image
830936
```
831937

938+
**Method 2: Functional API**
939+
940+
```python
941+
ui.begin_image_context(200, 200)
942+
ui.set_color('red')
943+
ui.fill_rect(0, 0, 200, 200)
944+
img = ui.get_image_from_current_context() # ui.Image
945+
ui.end_image_context()
946+
```
947+
948+
### Image Class
949+
950+
| Entry | Description |
951+
|-------|-------------|
952+
| `ui.Image.named(name)` | Built-in or bundled resource |
953+
| `ui.Image.from_data(data)` | From bytes |
954+
| `ui.Image.from_image_context()` | From current offscreen context |
955+
| `ui.Image(name)` | Equivalent to `Image.named(name)` |
956+
957+
| Property / Method | Description |
958+
|-------------------|-------------|
959+
| `size` | `(w, h)` |
960+
| `to_png()` | PNG `bytes` |
961+
| `resized(size)` | Resized copy |
962+
| `cropped(rect)` | Cropped copy |
963+
| `crop(rect)` | Crop `(x, y, w, h)`; native implementation |
964+
| `clip_to_mask(mask)` | Clip using another Image's alpha channel |
965+
| `with_rendering_mode(mode)` | Template / original rendering mode |
966+
832967
---
833968

834969
## 21. load_view and load_view_str

0 commit comments

Comments
 (0)