synit
/
synit-manual
1
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity

More protocol docs

This commit is contained in:
Tony Garnock-Jones 2022-10-13 10:17:58 +02:00
parent 8e304902a8
commit 51463c324b
4 changed files with 80 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/operation/howto/manage-user-settings.md
View File

@ -1,8 +1,9 @@
# How to manage user settings
Send a [`user-settings-command`]() message containing an `assert` or `retract` record
containing the setting assertion to add or remove. Use the [`!` operator of the configuration
language](../scripting.md#SendInstruction) to send a message (as opposed to make an assertion):
Send a [`user-settings-command`](../../protocols/synit/userSettings.md) message containing an
`assert` or `retract` record containing the setting assertion to add or remove. Use the [`!`
operator of the configuration language](../scripting.md#SendInstruction) to send a message (as
opposed to make an assertion):
```preserves
! <user-settings-command <assert <mobile-data-enabled>>>

2
src/operation/synit-config.md
View File

@ -390,7 +390,7 @@ The remainder of modem.pr handles cellular data, configured via the
<depends-on <qmi-wwan "/dev/cdc-wdm0"> <service-state <daemon eg25-manager> up>>
```
When the [user settings](#user-setting) `mobile-data-enabled` and `mobile-data-apn` are both
When the [user settings](#user-settings) `mobile-data-enabled` and `mobile-data-apn` are both
present, it responds to `qmi-wwan` service requests by invoking `qmi-wwan-manager`, a small
shell script, for each particular device and APN combination:

110
src/protocols/synit/ui.md
View File

@ -59,12 +59,12 @@ SortKey = @double double / @string string .
Widgets acting as containers for other widgets may be of either `column` or `row` type. Leaf
widgets may be `blank` (for spacing/padding/layout), `text` (a label or editable field), a
`slider`, an `image`, or a [FontAwesome](https://fontawesome.com/) `icon`.
`slider`, or a [FontAwesome](https://fontawesome.com/) `icon`.
```
WidgetType = NodeType / LeafType .
NodeType = =column / =row .
LeafType = =blank / =text / =slider / =image / =icon .
LeafType = =blank / =text / =slider / =icon .
```
## Configuring widgets
@ -129,14 +129,56 @@ replaced in future by an entity-reference-based system.)
WidgetInstance = <widget-instance @id WidgetId @instance #!any> .
```
## <span id="attribute-keys"></span>Widget Attributes
## <span id="attribute-keys"></span>Widget attributes
### General attributes
### General attributes, for any widget type
interactive - boolean - ?
name - string - morphic name for the widget
| Key | Value type | Description |
|-----------------|-----------------------|-----------------------------------------------------------------------------------|
| padding | `BoxSize` | Layout: padding |
| spacing | `BoxSize` | Layout: spacing |
| size | `BoxSize` | Layout: explicit widget size |
| backgroundColor | `Color` | The background color of the widget |
| foregroundColor | `Color` | Text color in a label or editable field; icon color for FontAwesome icons |
| cornerStyle | `square` or `rounded` | The widget's corner style. Defaults to `square` |
| cornerRadius | number | The widget's corner radius (where `cornerStyle` is `rounded`), measured in points |
| interactive | boolean | If true, enables touch and click events |
| name | string | Sets the Morphic "name" for the widget |
### Color and style
### Icon attributes
| Key | Value type | Description |
|------------|------------|-------------------------------------------|
| icon | symbol | The FontAwesome icon name for icons |
| icon-style | symbol | The FontAwesome icon style name for icons |
### Slider attributes
| Key | Value type | Description |
|-------------|----------------------------|---------------|
| max | number | Maximum value |
| min | number | Minimum value |
| value | number | Initial value |
| orientation | `vertical` or `horizontal` | Orientation |
### Text attributes
| Key | Value type | Description |
|----------|------------|--------------------------------------------------------------|
| fontSize | number | The font size, measured in points |
| readOnly | boolean | If true or absent, a label; if false, an editable text field |
| value | string | Initial value |
### Row and column attributes
| Key | Value type | Description |
|------------|------------|------------------------------------------------------------------------------|
| cells | integer | Number of cells per row (column) in a grid; if absent, just one row (column) |
| scrollable | boolean | Whether the container is a scrollable viewport or fixed-size |
## Widget value types
### Color values
The `Color` type describes an RGBA color value where the components are `double`s in the range
`0.0` to `1.0` (inclusive).
@ -145,60 +187,14 @@ The `Color` type describes an RGBA color value where the components are `double`
Color = <rgba @red double @green double @blue double @alpha double> .
```
#### backgroundColor: Color
### `BoxSize`: layout sizes
Sets the background color of the widget.
#### foregroundColor: Color
Text color in a label or editable field; icon color for FontAwesome icons.
#### cornerStyle: `square` or `rounded`
Sets the widget's corner style. Defaults to `square`.
#### cornerRadius: number
Sets the widget's corner radius (where `cornerStyle` is `rounded`), measured in points.
#### fontSize: number
Sets the font size, measured in points.
#### icon: symbol
Sets the FontAwesome icon name for icons.
#### icon-style: symbol
Sets the FontAwesome icon style name for icons.
### Layout
The `BoxSize` type is a pair of `Sizing`s, one for the horizontal and one for the vertical
dimension. Each `Sizing` describes an *ideal* size, measured in points, plus a "stretch" and a
"shrink" specification of `Fill` type, loosely modelled on the TeX concept of "boxes and glue".
```
; Box-and-glue layout
Fill = @fixed double / <fill @weight int @rank int> .
Sizing = <sizing @ideal double @stretch Fill @shrink Fill> .
BoxSize = <box-size @horizontal Sizing @vertical Sizing> .
```
padding - BoxSize - layout padding
size - BoxSize
spacing - BoxSize
### Sliders
max - number
min - number
orientation - `vertical` or `horizontal` - for sliders
value - number - slider value
### Text fields (labels and editable fields)
readOnly - boolean - set to false to turn a label into an editable field
value - string - label or editable field contents
### Column and row attributes
cells - integer - number of cells per row (column) of the layout matrix - if none, just one row (column) exists
scrollable - boolean

28
src/protocols/synit/userSettings.md
View File

@ -2,17 +2,33 @@
- [`[synit]/protocols/schemas/userSettings.prs`](https://git.syndicate-lang.org/synit/synit/src/branch/main/protocols/schemas/userSettings.prs)
**Implementation.** The
[`user-settings-daemon`](https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/usr/lib/synit/python/synit/daemon/user_settings_daemon.py)
program reacts to `CommandRPC` and `CommandEvent` requests by updating files in its configured
`settingsDir`. See [here](../../operation/synit-config.md#user-settings) for more information
on the `user-settings-daemon`.
## Updating user settings
Assert `CommandRPC` containing an `action` for the settings daemon to perform and a `reply`
entity-reference for it to tell you when it is done. After it completes the `action`, it will
assert a `CommandReply` using the `reply` capability. Alternatively, send a `CommandEvent`
message containing an `action` if you do not require notification of completion.
```
version 1 .
; Assertion.
CommandRPC = <user-settings-command @action Action @reply #!CommandReply> .
; Message.
CommandEvent = <user-settings-command @action Action> .
CommandReply = =done .
Action = <assert @item any> / <retract @item any> .
```
; Assertion.
See also [this how-to](../../operation/howto/manage-user-settings.md).
## Reading user settings
Configured user settings are published to the main `$config` dataspace contained within a
`Value` record to reliably distinguish them from system assertions.
```
Value = <user-setting @item any> .
```