diff --git a/src/operation/howto/manage-user-settings.md b/src/operation/howto/manage-user-settings.md index 2cba7f4..eda49a0 100644 --- a/src/operation/howto/manage-user-settings.md +++ b/src/operation/howto/manage-user-settings.md @@ -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 ! >> diff --git a/src/operation/synit-config.md b/src/operation/synit-config.md index aa53a70..19479a2 100644 --- a/src/operation/synit-config.md +++ b/src/operation/synit-config.md @@ -390,7 +390,7 @@ The remainder of modem.pr handles cellular data, configured via the 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: diff --git a/src/protocols/synit/ui.md b/src/protocols/synit/ui.md index c37a3c2..02ff48b 100644 --- a/src/protocols/synit/ui.md +++ b/src/protocols/synit/ui.md @@ -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 Attributes +## 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 = . ``` -#### 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 / . Sizing = . BoxSize = . ``` - -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 diff --git a/src/protocols/synit/userSettings.md b/src/protocols/synit/userSettings.md index ad26a34..1691603 100644 --- a/src/protocols/synit/userSettings.md +++ b/src/protocols/synit/userSettings.md @@ -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 = . -; Message. CommandEvent = . - CommandReply = =done . Action = / . +``` -; 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 = . ```