kopia lustrzana https://github.com/peterhinch/micropython-micro-gui
README.md: Add note about callback execution speed.
rodzic
ca5e2b2a20
commit
923caaa6df
71
README.md
71
README.md
|
@ -155,7 +155,7 @@ under development so check for updates.
|
||||||
9. [Realtime applications](./README.md#9-realtime-applications) Accommodating tasks requiring fast RT performance.
|
9. [Realtime applications](./README.md#9-realtime-applications) Accommodating tasks requiring fast RT performance.
|
||||||
10. [ePaper displays](./README.md#10-epaper-displays) Guidance on using ePaper displays.
|
10. [ePaper displays](./README.md#10-epaper-displays) Guidance on using ePaper displays.
|
||||||
|
|
||||||
[Appendix 1 Application design](./README.md#appendix-1-application-design) Tab order, button layout, encoder interface, use of graphics primitives
|
[Appendix 1 Application design](./README.md#appendix-1-application-design) Tab order, button layout, encoder interface, use of graphics primitives, more on callbacks.
|
||||||
[Appendix 2 Freezing bytecode](./README.md#appendix-2-freezing-bytecode) Optional way to save RAM.
|
[Appendix 2 Freezing bytecode](./README.md#appendix-2-freezing-bytecode) Optional way to save RAM.
|
||||||
[Appendix 3 Cross compiling](./README.md#appendix-3-cross-compiling) Another way to save RAM.
|
[Appendix 3 Cross compiling](./README.md#appendix-3-cross-compiling) Another way to save RAM.
|
||||||
|
|
||||||
|
@ -629,7 +629,7 @@ Before running a different demo the host should be reset (ctrl-d) to clear RAM.
|
||||||
|
|
||||||
These will run on screens of 128x128 pixels or above. The initial ones are
|
These will run on screens of 128x128 pixels or above. The initial ones are
|
||||||
minimal and aim to demonstrate a single technique.
|
minimal and aim to demonstrate a single technique.
|
||||||
* `simple.py` Minimal demo discussed below. `Button` presses print to REPL.
|
* `simple.py` Minimal demo discussed below. `Button` presses print to REPL.
|
||||||
* `checkbox.py` A `Checkbox` controlling an `LED`.
|
* `checkbox.py` A `Checkbox` controlling an `LED`.
|
||||||
* `slider.py` A `Slider` whose color varies with its value.
|
* `slider.py` A `Slider` whose color varies with its value.
|
||||||
* `slider_label.py` A `Slider` updating a `Label`. Good for trying precision
|
* `slider_label.py` A `Slider` updating a `Label`. Good for trying precision
|
||||||
|
@ -653,7 +653,7 @@ minimal and aim to demonstrate a single technique.
|
||||||
* `qrcode.py` Display a QR code. Requires the uQR module.
|
* `qrcode.py` Display a QR code. Requires the uQR module.
|
||||||
* `calendar.py` Demo of grid widget.
|
* `calendar.py` Demo of grid widget.
|
||||||
* `epaper.py` Warts-and-all demo for an ePaper display. Currently the only
|
* `epaper.py` Warts-and-all demo for an ePaper display. Currently the only
|
||||||
supported display is the
|
supported display is the
|
||||||
[Waveshare pico_epaper_42](https://www.waveshare.com/pico-epaper-4.2.htm)
|
[Waveshare pico_epaper_42](https://www.waveshare.com/pico-epaper-4.2.htm)
|
||||||
with Pico or other host.
|
with Pico or other host.
|
||||||
|
|
||||||
|
@ -809,6 +809,10 @@ are passed, bearing in mind the first arg described above. An incorrect
|
||||||
argument count results in puzzling tracebacks which appear to implicate the GUI
|
argument count results in puzzling tracebacks which appear to implicate the GUI
|
||||||
code. This is because it is the GUI which actually executes the callbacks.
|
code. This is because it is the GUI which actually executes the callbacks.
|
||||||
|
|
||||||
|
Callbacks should complete quickly. See
|
||||||
|
[Appendix 1 Application design](./README.md#appendix-1-application-design) for
|
||||||
|
discussion of this.
|
||||||
|
|
||||||
###### [Contents](./README.md#0-contents)
|
###### [Contents](./README.md#0-contents)
|
||||||
|
|
||||||
## 2.3 Colors
|
## 2.3 Colors
|
||||||
|
@ -925,7 +929,7 @@ The constructor takes the following positional args:
|
||||||
Class variables:
|
Class variables:
|
||||||
* `verbose=True` Causes a message to be printed indicating whether an encoder
|
* `verbose=True` Causes a message to be printed indicating whether an encoder
|
||||||
was specified.
|
was specified.
|
||||||
|
|
||||||
### 3.2.1 Encoder usage
|
### 3.2.1 Encoder usage
|
||||||
|
|
||||||
If an encoder is used, it should be connected to the pins assigned to
|
If an encoder is used, it should be connected to the pins assigned to
|
||||||
|
@ -936,7 +940,7 @@ To specify to the GUI that an encoder is in use an integer should be passed to
|
||||||
the `Display` constructor `encoder` arg. Its value represents the division
|
the `Display` constructor `encoder` arg. Its value represents the division
|
||||||
ratio. A value of 1 defines the native rate of the encoder; if the native rate
|
ratio. A value of 1 defines the native rate of the encoder; if the native rate
|
||||||
is 32 pulses per revolution, a value of 4 would yield a virtual device with
|
is 32 pulses per revolution, a value of 4 would yield a virtual device with
|
||||||
8 pulses per rev. A value of 4 matches most encoders with mechanical detents.
|
8 pulses per rev. A value of 4 matches most encoders with mechanical detents.
|
||||||
|
|
||||||
If an encoder is used but the `encoder` arg is `False`, response to the encoder
|
If an encoder is used but the `encoder` arg is `False`, response to the encoder
|
||||||
will be erratic.
|
will be erratic.
|
||||||
|
@ -1460,7 +1464,7 @@ Methods:
|
||||||
provided, should be a button in the set. If supplied and the button is not
|
provided, should be a button in the set. If supplied and the button is not
|
||||||
active the currency changes to the supplied button, which is displayed. By
|
active the currency changes to the supplied button, which is displayed. By
|
||||||
default the callback of the previous button is run, otherwise the callback of
|
default the callback of the previous button is run, otherwise the callback of
|
||||||
the newly displayed button.
|
the newly displayed button.
|
||||||
|
|
||||||
Always returns the active button.
|
Always returns the active button.
|
||||||
|
|
||||||
|
@ -1747,7 +1751,7 @@ class BaseScreen(Screen):
|
||||||
els = (('hydrogen', cb, ('H2',)),
|
els = (('hydrogen', cb, ('H2',)),
|
||||||
('helium', cb, ('He',)),
|
('helium', cb, ('He',)),
|
||||||
('neon', cb, ('Ne',)),
|
('neon', cb, ('Ne',)),
|
||||||
('xenon', cb, ('Xe',)),
|
('xenon', cb, ('Xe',)),
|
||||||
('radon', cb_radon, ('Ra',)))
|
('radon', cb_radon, ('Ra',)))
|
||||||
Dropdown(wri, 2, 2, elements = els,
|
Dropdown(wri, 2, 2, elements = els,
|
||||||
bdcolor = RED, fgcolor=RED, fontcolor = YELLOW)
|
bdcolor = RED, fgcolor=RED, fontcolor = YELLOW)
|
||||||
|
@ -1766,7 +1770,7 @@ from gui.widgets import DialogBox # File: dialog.py
|
||||||
![Image](./images/dialog.JPG)
|
![Image](./images/dialog.JPG)
|
||||||
|
|
||||||
An active dialog box. Auto generated dialogs contain only `pushbutton`
|
An active dialog box. Auto generated dialogs contain only `pushbutton`
|
||||||
instances, but user created dialogs may contain any widget.
|
instances, but user created dialogs may contain any widget.
|
||||||
|
|
||||||
This implements a modal dialog box based on a horizontal row of pushbuttons.
|
This implements a modal dialog box based on a horizontal row of pushbuttons.
|
||||||
Any button press will close the dialog. The caller can determine which button
|
Any button press will close the dialog. The caller can determine which button
|
||||||
|
@ -1932,7 +1936,7 @@ Keyword only args:
|
||||||
displayed to the right hand side of the meter, starting at the bottom. E.G.
|
displayed to the right hand side of the meter, starting at the bottom. E.G.
|
||||||
`('0.0', '0.5', '1.0')`
|
`('0.0', '0.5', '1.0')`
|
||||||
* `value=0` Initial value.
|
* `value=0` Initial value.
|
||||||
|
|
||||||
Methods:
|
Methods:
|
||||||
1. `value` Args: `n=None, color=None`.
|
1. `value` Args: `n=None, color=None`.
|
||||||
* `n` should be a float in range 0 to 1.0. Causes the meter to be updated.
|
* `n` should be a float in range 0 to 1.0. Causes the meter to be updated.
|
||||||
|
@ -2072,7 +2076,7 @@ Optional keyword only arguments:
|
||||||
the centre of the control along which the slider moves. Defaults to the
|
the centre of the control along which the slider moves. Defaults to the
|
||||||
background color.
|
background color.
|
||||||
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
||||||
to yellow to for a visual indication. An alternative color can be provided.
|
to yellow to for a visual indication. An alternative color can be provided.
|
||||||
`WHITE` will defeat this change.
|
`WHITE` will defeat this change.
|
||||||
* `callback=dolittle` Callback function which runs whenever the control's
|
* `callback=dolittle` Callback function which runs whenever the control's
|
||||||
value changes. If the control is `active` it also runs on instantiation. This
|
value changes. If the control is `active` it also runs on instantiation. This
|
||||||
|
@ -2146,7 +2150,7 @@ Constructor mandatory positional args:
|
||||||
2. `row` Location on screen.
|
2. `row` Location on screen.
|
||||||
3. `col`
|
3. `col`
|
||||||
|
|
||||||
Optional keyword only arguments:
|
Optional keyword only arguments:
|
||||||
* `ticks=200` Number of "tick" divisions on scale. Must be divisible by 2.
|
* `ticks=200` Number of "tick" divisions on scale. Must be divisible by 2.
|
||||||
* `value=0.0` Initial value.
|
* `value=0.0` Initial value.
|
||||||
* `height=0` Default is a minimum height based on the font height.
|
* `height=0` Default is a minimum height based on the font height.
|
||||||
|
@ -2159,7 +2163,7 @@ Optional keyword only arguments:
|
||||||
be drawn. If a color is provided, a border line will be drawn around the
|
be drawn. If a color is provided, a border line will be drawn around the
|
||||||
control.
|
control.
|
||||||
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
||||||
to yellow to for a visual indication. An alternative color can be provided.
|
to yellow to for a visual indication. An alternative color can be provided.
|
||||||
`WHITE` will defeat this change.
|
`WHITE` will defeat this change.
|
||||||
* `pointercolor=None` Color of pointer. Defaults to `.fgcolor`.
|
* `pointercolor=None` Color of pointer. Defaults to `.fgcolor`.
|
||||||
* `fontcolor=None` Color of legends. Default `fgcolor`.
|
* `fontcolor=None` Color of legends. Default `fgcolor`.
|
||||||
|
@ -2220,7 +2224,7 @@ The above arithmetic aims to show the logic. It can (obviously) be simplified.
|
||||||
|
|
||||||
This callback enables the tick color to be changed dynamically. For example a
|
This callback enables the tick color to be changed dynamically. For example a
|
||||||
scale might change from green to orange, then to red as it nears the extremes.
|
scale might change from green to orange, then to red as it nears the extremes.
|
||||||
The callback takes two args, being the value of the tick (in range
|
The callback takes two args, being the value of the tick (in range
|
||||||
-1.0 <= v <= 1.0) and the default color. It must return a color. This example
|
-1.0 <= v <= 1.0) and the default color. It must return a color. This example
|
||||||
is taken from the `scale.py` demo:
|
is taken from the `scale.py` demo:
|
||||||
```python
|
```python
|
||||||
|
@ -2290,7 +2294,7 @@ Constructor mandatory positional args:
|
||||||
2. `row` Location on screen.
|
2. `row` Location on screen.
|
||||||
3. `col`
|
3. `col`
|
||||||
|
|
||||||
Keyword only arguments (all optional):
|
Keyword only arguments (all optional):
|
||||||
* `decades=5` Defines the control's maximum value (i.e. `10**decades`).
|
* `decades=5` Defines the control's maximum value (i.e. `10**decades`).
|
||||||
* `value=1.0` Initial value for control. Will be constrained to
|
* `value=1.0` Initial value for control. Will be constrained to
|
||||||
`1.0 <= value <= 10**decades` if outside this range.
|
`1.0 <= value <= 10**decades` if outside this range.
|
||||||
|
@ -2304,7 +2308,7 @@ Keyword only arguments (all optional):
|
||||||
be drawn. If a color is provided, a border line will be drawn around the
|
be drawn. If a color is provided, a border line will be drawn around the
|
||||||
control.
|
control.
|
||||||
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
||||||
to yellow to for a visual indication. An alternative color can be provided.
|
to yellow to for a visual indication. An alternative color can be provided.
|
||||||
`WHITE` will defeat this change.
|
`WHITE` will defeat this change.
|
||||||
* `pointercolor=None` Color of pointer. Defaults to `.fgcolor`.
|
* `pointercolor=None` Color of pointer. Defaults to `.fgcolor`.
|
||||||
* `fontcolor=None` Color of legends. Default `WHITE`.
|
* `fontcolor=None` Color of legends. Default `WHITE`.
|
||||||
|
@ -2327,7 +2331,7 @@ Methods:
|
||||||
* `greyed_out` Optional Boolean argument `val=None`. If `None` returns the
|
* `greyed_out` Optional Boolean argument `val=None`. If `None` returns the
|
||||||
current 'greyed out' status of the control. Otherwise enables or disables it,
|
current 'greyed out' status of the control. Otherwise enables or disables it,
|
||||||
showing it in its new state.
|
showing it in its new state.
|
||||||
|
|
||||||
Class variable:
|
Class variable:
|
||||||
* `encoder_rate=5` If the hardware uses an encoder, this determines the rate
|
* `encoder_rate=5` If the hardware uses an encoder, this determines the rate
|
||||||
of change when the value is adjusted. Increase to raise the rate.
|
of change when the value is adjusted. Increase to raise the rate.
|
||||||
|
@ -2540,7 +2544,7 @@ Optional keyword only arguments:
|
||||||
* `bdcolor=False` Color of border. If `False` no border will be drawn. If a
|
* `bdcolor=False` Color of border. If `False` no border will be drawn. If a
|
||||||
color is provided, a border line will be drawn around the control.
|
color is provided, a border line will be drawn around the control.
|
||||||
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
* `prcolor=None` If `active`, in precision mode the white focus border changes
|
||||||
to yellow for a visual indication. An alternative color can be provided.
|
to yellow for a visual indication. An alternative color can be provided.
|
||||||
`WHITE` defeats this change; `False` disables precision mode.
|
`WHITE` defeats this change; `False` disables precision mode.
|
||||||
* `callback=dolittle` Callback function runs when the user moves the knob or
|
* `callback=dolittle` Callback function runs when the user moves the knob or
|
||||||
the value is changed programmatically.
|
the value is changed programmatically.
|
||||||
|
@ -2812,7 +2816,7 @@ Static Method:__
|
||||||
* `make_buffer` args `version`, `scale`. Returns a buffer big enough to hold
|
* `make_buffer` args `version`, `scale`. Returns a buffer big enough to hold
|
||||||
the QR code bitmap. Use of this is optional: it is a solution if memory errors
|
the QR code bitmap. Use of this is optional: it is a solution if memory errors
|
||||||
are encountered when instantiating a `QRMap`.
|
are encountered when instantiating a `QRMap`.
|
||||||
|
|
||||||
Note on image sizes. The size of a QR code bitmap depends on the `version` and
|
Note on image sizes. The size of a QR code bitmap depends on the `version` and
|
||||||
`scale` parameters according to this formula:
|
`scale` parameters according to this formula:
|
||||||
`edge_length_in_pixels = (4 * version + 17) * scale`
|
`edge_length_in_pixels = (4 * version + 17) * scale`
|
||||||
|
@ -3170,7 +3174,7 @@ In general ePaper displays do not work well with micro-gui because refresh is
|
||||||
slow (seconds) and visually intrusive. Some displays support partial refresh
|
slow (seconds) and visually intrusive. Some displays support partial refresh
|
||||||
which is faster (hundreds of ms) and non-intrusive. The penalty is "ghosting"
|
which is faster (hundreds of ms) and non-intrusive. The penalty is "ghosting"
|
||||||
where pixels which change from black to white do so imperfectly, leaving a grey
|
where pixels which change from black to white do so imperfectly, leaving a grey
|
||||||
trace behind. The degree of ghosting varies between display types.
|
trace behind. The degree of ghosting varies between display types.
|
||||||
|
|
||||||
The [Waveshare pico_epaper_42](https://www.waveshare.com/pico-epaper-4.2.htm)
|
The [Waveshare pico_epaper_42](https://www.waveshare.com/pico-epaper-4.2.htm)
|
||||||
has quite a low level of ghosting. A full refresh takes about 2.1s and partial
|
has quite a low level of ghosting. A full refresh takes about 2.1s and partial
|
||||||
|
@ -3197,7 +3201,7 @@ async def set_partial(): # Ensure 1st refresh is a full refresh
|
||||||
ssd.set_partial()
|
ssd.set_partial()
|
||||||
```
|
```
|
||||||
The application then runs in partial mode with a reasonably quick and visually
|
The application then runs in partial mode with a reasonably quick and visually
|
||||||
satisfactory response to user inputs such as button events. See the
|
satisfactory response to user inputs such as button events. See the
|
||||||
[epaper demo](https://github.com/peterhinch/micropython-micro-gui/blob/main/gui/demos/epaper.py).
|
[epaper demo](https://github.com/peterhinch/micropython-micro-gui/blob/main/gui/demos/epaper.py).
|
||||||
|
|
||||||
It is likely that applications will provide a full refresh method to clear any
|
It is likely that applications will provide a full refresh method to clear any
|
||||||
|
@ -3282,7 +3286,7 @@ have the following bound variables, which should be considered read-only:
|
||||||
* `width` Ditto.
|
* `width` Ditto.
|
||||||
* `mrow` Maximum absolute row occupied by the widget (including border).
|
* `mrow` Maximum absolute row occupied by the widget (including border).
|
||||||
* `mcol` Maximum absolute col occupied by the widget (including border).
|
* `mcol` Maximum absolute col occupied by the widget (including border).
|
||||||
|
|
||||||
A further aid to metrics is the `Writer` method `.stringlen(s)`. This takes a
|
A further aid to metrics is the `Writer` method `.stringlen(s)`. This takes a
|
||||||
string as its arg and returns its length in pixels when rendered using that
|
string as its arg and returns its length in pixels when rendered using that
|
||||||
`Writer` instance's font.
|
`Writer` instance's font.
|
||||||
|
@ -3339,6 +3343,31 @@ micro-gui.
|
||||||
|
|
||||||
The `primitives.py` demo provides a simple example.
|
The `primitives.py` demo provides a simple example.
|
||||||
|
|
||||||
|
## Callbacks
|
||||||
|
|
||||||
|
Callback functions should execute quickly, otherwise screen refresh will be
|
||||||
|
delayed until the callback is complete. Where a time consuming task is to be
|
||||||
|
triggered by a callback an `asyncio` task should be launched. In the following
|
||||||
|
sample an `LED` widget is to be cycled through various colors in response to
|
||||||
|
a callback.
|
||||||
|
```python
|
||||||
|
def callback(self, button, val):
|
||||||
|
asyncio.create_task(self.flash_led())
|
||||||
|
|
||||||
|
async def flash_led(self):
|
||||||
|
self.led.color(RED)
|
||||||
|
self.led.value(True) # Turn on LED
|
||||||
|
await asyncio.sleep_ms(500)
|
||||||
|
self.led.color(YELLOW)
|
||||||
|
await asyncio.sleep_ms(500)
|
||||||
|
self.led.color(GREEN)
|
||||||
|
await asyncio.sleep_ms(500)
|
||||||
|
self.led.value(False) # Turn it off. Task is complete.
|
||||||
|
```
|
||||||
|
The `callback()` executes fast, with the `flash_led()` running as a background
|
||||||
|
task. For more information on asyncio, see
|
||||||
|
[the tutorial](https://github.com/peterhinch/micropython-async/blob/master/v3/docs/TUTORIAL.md).
|
||||||
|
|
||||||
###### [Contents](./README.md#0-contents)
|
###### [Contents](./README.md#0-contents)
|
||||||
|
|
||||||
## Appendix 2 Freezing bytecode
|
## Appendix 2 Freezing bytecode
|
||||||
|
|
Ładowanie…
Reference in New Issue