moon
/
enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #390 from cognitivegears/feature/view_documentation 

Feature/view documentation
This commit is contained in:
Bryan Ashby 2022-01-29 11:56:16 -07:00 committed by GitHub
parent e5c3cb33aa 7292ffe752
commit 18e8ff9eea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 728 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/_includes/nav.md
View File

@ -50,7 +50,16 @@
- [Themes]({{ site.baseurl }}{% link art/themes.md %})
- [MCI Codes]({{ site.baseurl }}{% link art/mci.md %})
- Views
- [Button]({{ site.baseurl }}{% link art/views/button_view.md %})
- [Edit Text]({{ site.baseurl }}{% link art/views/edit_text_view.md %})
- [Full Menu]({{ site.baseurl }}{% link art/views/full_menu_view.md %})
- [Horizontal Menu]({{ site.baseurl }}{% link art/views/horizontal_menu_view.md %})
- [Mask Edit Text]({{ site.baseurl }}{% link art/views/mask_edit_text_view.md %})
- [Predefined Label]({{ site.baseurl }}{% link art/views/predefined_label_view.md %})
- [Spinner Menu]({{ site.baseurl }}{% link art/views/spinner_menu_view.md %})
- [Text]({{ site.baseurl }}{% link art/views/text_view.md %})
- [Toggle Menu]({{ site.baseurl }}{% link art/views/toggle_menu_view.md %})
- [Vertical Menu]({{ site.baseurl }}{% link art/views/vertical_menu_view.md %})
- Servers
- Login Servers

21
docs/art/mci.md
View File

@ -116,16 +116,17 @@ a Vertical Menu (`%VM`): Old-school BBSers may recognize this as a lightbar menu
| Code | Name | Description | Notes |
|------|----------------------|------------------|-------|
| `TL` | Text Label | Displays text | Static content |
| `ET` | Edit Text | Collect user input | Single line entry |
| `ME` | Masked Edit Text | Collect user input using a *mask* | See **Mask Edits** below |
| `MT` | Multi Line Text Edit | Multi line edit control | Used for FSE, display of FILE_ID.DIZ, etc. |
| `BT` | Button | A button | ...it's a button |
| `VM` | Vertical Menu | A vertical menu | AKA a vertical lightbar; Useful for lists |
| `HM` | Horizontal Menu | A horizontal menu | AKA a horizontal lightbar |
| `FM` | Full Menu | A menu that can go both vertical and horizontal. See [Full Menu](views/full_menu_view.md) |
| `SM` | Spinner Menu | A spinner input control | Select *one* from multiple options |
| `TM` | Toggle Menu | A toggle menu | Commonly used for Yes/No style input |
| `TL` | Text Label | Displays text | Static content. See [Text View](views/text_view.md) |
| `ET` | Edit Text | Collect user input | Single line entry. See [Edit Text](views/edit_text_view.md) |
| `ME` | Masked Edit Text | Collect user input using a *mask* | See [Masked Edit](views/mask_edit_text_view.md) and **Mask Edits** below. |
| `MT` | Multi Line Text Edit | Multi line edit control | Used for FSE, display of FILE_ID.DIZ, etc. See [Multiline Text Edit](views/multi_line_edit_text_view.md) |
| `BT` | Button | A button | ...it's a button. See [Button](views/button_view.md) |
| `VM` | Vertical Menu | A vertical menu | AKA a vertical lightbar; Useful for lists. See [Vertical Menu](views/vertical_menu_view.md) |
| `HM` | Horizontal Menu | A horizontal menu | AKA a horizontal lightbar. See [Horizontal Menu](views/horizontal_menu_view.md) |
| `FM` | Full Menu | A menu that can go both vertical and horizontal. | See [Full Menu](views/full_menu_view.md) |
| `SM` | Spinner Menu | A spinner input control | Select *one* from multiple options. See [Spinner Menu](views/spinner_menu_view.md) |
| `TM` | Toggle Menu | A toggle menu | Commonly used for Yes/No style input. See [Toggle Menu](views/toggle_menu_view.md)|
| `PL` | Predefined Label | Show environment information | See [Predefined Label](views/predefined_label_view.md)|
| `KE` | Key Entry | A *single* key input control | Think hotkeys |
:information_source: Peek at [/core/mci_view_factory.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) to see additional information.

57
docs/art/views/button_view.md Normal file
View File

@ -0,0 +1,57 @@
---
layout: page
title: Button View
---
## Button View
A button view supports displaying a button on a screen.
## General Information
:information_source: A button view is defined with a percent (%) and the characters BT, followed by the view number. For example: `%BT1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `text` | Sets the text to display on the button |
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `width` | Sets the width of a view to display one or more columns horizontally (default 15)|
| `focus` | If set to `true`, establishes initial focus |
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `argName` | Sets the argument name for this selection in the form |
| `justify` | Sets the justification of each item in the list. Options: left (default), right, center |
| `fillChar` | Specifies a character to fill extra space longer than the text length. Defaults to an empty space |
| `textOverflow` | If the button text cannot be displayed due to `width`, set overflow characters. See **Text Overflow** below |
### Text Overflow
The `textOverflow` option is used to specify what happens when a text string is too long to fit in the `width` defined.
:information_source: If `textOverflow` is not specified at all, a button can become wider than the `width` if needed to display the text value.
:information_source: Setting `textOverflow` to an empty string `textOverflow: ""` will cause the item to be truncated if necessary without any characters displayed
:information_source: Otherwise, setting `textOverflow` to one or more characters will truncate the value if necessary and display those characters at the end. i.e. `textOverflow: ...`
## Example
![Example](../../assets/images/button_view_example1.gif "Button")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
BT1: {
submit: true
justify: center
argName: btnSelect
width: 17
focusTextStyle: upper
text: Centered button
}
```
</div>
</details>

42
docs/art/views/edit_text_view.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: page
title: Edit Text View
---
## Edit Text View
An edit text view supports editing form values on a screen. This can be for new entry as well as editing existing values defined by the module.
## General Information
:information_source: An edit text view is defined with a percent (%) and the characters ET, followed by the view number. For example: `%ET1`. This is generally used on a form in order to allow a user to enter or edit a text value.
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets the focus text style. See **Text Styles** in [MCI](../mci.md) |
| `width` | Sets the width of a view for the text edit (default 15)|
| `argName` | Sets the argument name for this value in the form |
| `maxLength` | Sets the maximum number of characters that can be entered |
| `focus` | Set to true to capture initial focus |
| `justify` | Sets the justification of the text entry. Options: left (default), right, center |
| `fillChar` | Specifies a character to fill extra space in the text entry with. Defaults to an empty space |
## Example
![Example](../../assets/images/edit_text_view_example1.gif "Edit Text View")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
ET1: {
maxLength: @config:users.usernameMax
argName: username
focus: true
}
```
</div>
</details>

16
docs/art/views/full_menu_view.md
View File

@ -11,14 +11,14 @@ Items can be selected on a menu via the cursor keys, Page Up, Page Down, Home, a
:information_source: A full menu view is defined with a percent (%) and the characters FM, followed by the view number. For example: `%FM1`
:information_source: See [Art](../general.md) for general information on how to use views and common configuration properties available for them.
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [Art](../general.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [Art](../general.md)|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `itemSpacing` | Used to separate items vertically in the menu |
| `itemHorizSpacing` | Used to separate items horizontally in the menu |
| `height` | Sets the height of views to display multiple items vertically (default 1) |
@ -29,11 +29,11 @@ Items can be selected on a menu via the cursor keys, Page Up, Page Down, Home, a
| `hotKeySubmit` | Set to submit a form on hotkey selection |
| `argName` | Sets the argument name for this selection in the form |
| `justify` | Sets the justification of each item in the list. Options: left (default), right, center |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** in [Art](../general.md) |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** in [MCI](../mci.md) |
| `fillChar` | Specifies a character to fill extra space in the menu with. Defaults to an empty space |
| `textOverflow` | If a single column cannot be displayed due to `width`, set overflow characters. See **Text Overflow** below |
| `items` | List of items to show in the menu. See **Items** below.
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** in [Art](../general.md) |
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** in [MCI](../mci.md) |
### Hot Keys
@ -66,6 +66,12 @@ items: [
]
```
If the list is for display only (there is no form action associated with it) you can omit the data element, and include the items as a simple list:
```
["First item", "Second item", "Third Item"]
```
### Text Overflow
The `textOverflow` option is used to specify what happens when a text string is too long to fit in the `width` defined. Note, because columns are automatically calculated, this can only occur when the text is too long to fit the `width` using a single column.

91
docs/art/views/horizontal_menu_view.md Normal file
View File

@ -0,0 +1,91 @@
---
layout: page
title: Horizontal Menu View
---
## Horizontal Menu View
A horizontal menu view supports displaying a list of times on a screen horizontally (side to side, in a single row) similar to a lightbox.
## General Information
Items can be selected on a menu via the cursor keys, Page Up, Page Down, Home, and End, or by selecting them via a `hotKey` - see ***Hot Keys*** below.
:information_source: A horizontal menu view is defined with a percent (%) and the characters HM, followed by the view number (if used.) For example: `%HM1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `itemSpacing` | Used to separate items horizontally in the menu |
| `width` | Sets the width of a view to display one or more columns horizontally (default 15)|
| `focus` | If set to `true`, establishes initial focus |
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `hotKeys` | Sets hot keys to activate specific items. See **Hot Keys** below |
| `hotKeySubmit` | Set to submit a form on hotkey selection |
| `argName` | Sets the argument name for this selection in the form |
| `justify` | Sets the justification of each item in the list. Options: left (default), right, center |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** in [MCI](../mci.md) |
| `fillChar` | Specifies a character to fill extra space in the menu with. Defaults to an empty space |
| `items` | List of items to show in the menu. See **Items** below.
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** in [MCI](../mci.md) |
### Hot Keys
A set of `hotKeys` are used to allow the user to press a character on the keyboard to select that item, and optionally submit the form.
Example:
```
hotKeys: { A: 0, B: 1, C: 2, D: 3 }
hotKeySubmit: true
```
This would select and submit the first item if `A` is typed, second if `B`, etc.
### Items
A horizontal menu, similar to other menus, take a list of items to display in the menu. For example:
```
items: [
{
text: First Item
data: first
}
{
text: Second Item
data: second
}
]
```
If the list is for display only (there is no form action associated with it) you can omit the data element, and include the items as a simple list:
```
["First item", "Second item", "Third Item"]
```
## Example
![Example](../../assets/images/horizontal_menu_view_example1.gif "Horizontal menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
HM2: {
focus: true
width: 60 // set as desired
submit: true
argName: navSelect
items: [
"prev", "next", "details", "toggle queue", "rate", "help", "quit"
]
}
```
</div>
</details>

64
docs/art/views/mask_edit_text_view.md Normal file
View File

@ -0,0 +1,64 @@
---
layout: page
title: Mask Edit Text View
---
## Mask Edit Text View
A mask edit text view supports editing form values on a screen. This can be for new entry as well as editing existing values. Unlike a edit text view, the mask edit text view uses a mask pattern to specify what format the values should be entered in.
## General Information
:information_source: A mask edit text view is defined with a percent (%) and the characters ME, followed by the view number. For example: `%ME1`. This is generally used on a form in order to allow a user to enter or edit a text value.
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets the focus text style. See **Text Styles** in [MCI](../mci.md) |
| `argName` | Sets the argument name for this value in the form |
| `maxLength` | Sets the maximum number of characters that can be entered. *Not normally useful, set the mask pattern as needed instead* |
| `focus` | Set to true to capture initial focus |
| `maskPattern` | Sets the mask pattern. See **Mask Pattern** below |
| `fillChar` | Specifies a character to fill extra space in the text entry with. Defaults to an empty space |
### Mask Pattern
A `maskPattern` must be set on a mask edit text view (not doing so will cause the view to be focusable, but no text can be input). The `maskPattern` is a set of characters used to define input, as well as optional literal characters that can be entered into the pattern that will always be entered into the input. The following mask characters are supported:
| Mask Character | Description |
|----------------|--------------|
| # | Numeric input, one of 0 through 9 |
| A | Alphabetic, one of a through z or A through Z |
| @ | Alphanumeric, matches one of either Numeric or Alphabetic above |
| & | Printable, matches one printable character including spaces |
Any value other than the entries above is treated like a literal value to be displayed in the patter. Multiple pattern characters are combined for longer inputs. Some examples could include:
| Pattern | Description |
|---------|--------------|
| `AA` | Matches up to two alphabetic characters, for example a state name (i.e. "CA") |
| `###` | Matches up to three numeric characters, for example an age (i.e. 25) |
| `###-###-####` | A pattern matching a phone number with area code |
| `##/##/####` | Matches a date of type month/day/year or day/month/year (i.e. 01/01/2000) |
| `##-AAA-####` | Matches a date of type day-month-year (i.e. 01-MAR-2010) |
| `# foot ## inches`| Matches a height in feet and inches (i.e. 6 foot 2 inches) |
## Example
![Example](../../assets/images/mask_edit_text_view_example1.gif "Masked Text Edit View")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
ME1: {
argName: height
fillChar: "#"
maskPattern: "# ft. ## in."
}
```
</div>
</details>

53
docs/art/views/multi_line_edit_text_view.md Normal file
View File

@ -0,0 +1,53 @@
---
layout: page
title: Multi Line Edit Text View
---
## Multi Line Edit Text View
A text display / editor designed to edit or display a message.
## General Information
:information_source: A multi line edit text view is defined with a percent (%) and the characters MT, followed by the view number. For example: `%MT1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `text` | Sets the text to display - only useful for read-only and preview, otherwise use a specific module |
| `width` | Sets the width of a view to display horizontally (default 15) |
| `height` | Sets the height of a view to display vertically |
| `argName` | Sets the argument name for the form |
| `mode` | One of edit, preview, or read-only. See **Mode** below |
### Mode
The mode of a multi line edit text view controls how the view behaves. The following modes are allowed:
| Mode | Description |
|-------------|--------------|
| edit | edit the contents of the view |
| preview | preview the text, including scrolling |
| read-only | No scrolling or editing the view |
:information_source: If `mode` is not set, the default mode is "edit"
:information_source: With mode preview, scrolling the contents is allowed, but is not with read-only.
## Example
![Example](../../assets/images/multi_line_edit_text_view_example1.gif "Multi Line Edit Text View")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
ML1: {
width: 79
argName: message
mode: edit
}
```
</div>
</details>

49
docs/art/views/predefined_label_view.md Normal file
View File

@ -0,0 +1,49 @@
---
layout: page
title: Predefined Label View
---
## Predefined Label View
A predefined label view supports displaying a predefined MCI label on a screen.
## General Information
:information_source: A predefined label view is defined with a percent (%) and the characters PL, followed by the view number and then the predefined MCI value in parenthesis. For example: `%PL1(VL)` to display the Version Label. *NOTE*: this is an alternate way of placing MCI codes, as the MCI can also be placed on the art page directly with the code. For example `%VL`. The difference between these is that the PL version can have additional formatting options applied to it.
:information_source: See *Predefined Codes* in [MCI](../mci.md) for the list of available MCI codes.
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `justify` | Sets the justification of the MCI value text. Options: left (default), right, center |
| `fillChar` | Specifies a character to fill extra space in the view. Defaults to an empty space |
| `width` | Specifies the width that the value should be displayed in (default 3) |
| `textOverflow` | If the MCI is wider than width, set overflow characters. See **Text Overflow** below |
### Text Overflow
The `textOverflow` option is used to specify what happens when a predefined MCI string is too long to fit in the `width` defined.
:information_source: If `textOverflow` is not specified at all, a predefined label view can become wider than the `width` if needed to display the MCI value.
:information_source: Setting `textOverflow` to an empty string `textOverflow: ""` will cause the item to be truncated if necessary without any characters displayed
:information_source: Otherwise, setting `textOverflow` to one or more characters will truncate the value if necessary and display those characters at the end. i.e. `textOverflow: ...`
## Example
![Example](../../assets/images/predefined_label_view_example1.png "Predefined label")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
PL1: {
textStyle: upper
}
```
</div>
</details>

104
docs/art/views/spinner_menu_view.md Normal file
View File

@ -0,0 +1,104 @@
---
layout: page
title: Spinner Menu View
---
## Spinner Menu View
A spinner menu view supports displaying a set of times on a screen as a list, with one item displayed at a time. This is generally used to pick one option from a list. Some examples could include selecting from a list of states, themes, etc.
## General Information
Items can be selected on a menu via the cursor keys or by selecting them via a `hotKey` - see ***Hot Keys*** below.
:information_source: A spinner menu view is defined with a percent (%) and the characters SM, followed by the view number (if used.) For example: `%SM1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `focus` | If set to `true`, establishes initial focus |
| `width` | Sets the width of a view on the display (default 15)|
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `hotKeys` | Sets hot keys to activate specific items. See **Hot Keys** below |
| `hotKeySubmit` | Set to submit a form on hotkey selection |
| `argName` | Sets the argument name for this selection in the form |
| `justify` | Sets the justification of each item in the list. Options: left (default), right, center |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** in [MCI](../mci.md) |
| `fillChar` | Specifies a character to fill extra space in the menu with. Defaults to an empty space |
| `items` | List of items to show in the menu. See **Items** below.
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** in [MCI](../mci.md) |
### Hot Keys
A set of `hotKeys` are used to allow the user to press a character on the keyboard to select that item, and optionally submit the form.
Example:
```
hotKeys: { A: 0, B: 1, C: 2, D: 3 }
hotKeySubmit: true
```
This would select and submit the first item if `A` is typed, second if `B`, etc.
### Items
A spinner menu, similar to other menus, take a list of items to display in the menu. For example:
```
items: [
{
text: First Item
data: first
}
{
text: Second Item
data: second
}
]
```
If the list is for display only (there is no form action associated with it) you can omit the data element, and include the items as a simple list:
```
["First item", "Second item", "Third Item"]
```
## Example
![Example](../../assets/images/spinner_menu_view_example1.gif "Spinner menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
SM1: {
submit: true
argName: themeSelect
items: [
{
text: Light
data: light
}
{
text: Dark
data: dark
}
{
text: Rainbow
data: rainbow
}
{
text: Gruvbox
data: gruvbox
}
]
}
```
</div>
</details>

48
docs/art/views/text_view.md Normal file
View File

@ -0,0 +1,48 @@
---
layout: page
title: Text View
---
## Text View
A text label view supports displaying simple text on a screen.
## General Information
:information_source: A text label view is defined with a percent (%) and the characters TL, followed by the view number. For example: `%TL1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `text` | Sets the text to display on the label |
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `width` | Sets the width of a view to display horizontally (default 15)|
| `justify` | Sets the justification of the text in the view. Options: left (default), right, center |
| `fillChar` | Specifies a character to fill extra space in the view with. Defaults to an empty space |
| `textOverflow` | Set overflow characters to display in case the text length is less than the width. See **Text Overflow** below |
### Text Overflow
The `textOverflow` option is used to specify what happens when a text string is too long to fit in the `width` defined.
:information_source: If `textOverflow` is not specified at all, a text label can become wider than the `width` if needed to display the text value.
:information_source: Setting `textOverflow` to an empty string `textOverflow: ""` will cause the item to be truncated if necessary without any characters displayed
:information_source: Otherwise, setting `textOverflow` to one or more characters will truncate the value if necessary and display those characters at the end. i.e. `textOverflow: ...`
## Example
![Example](../../assets/images/text_label_view_example1.png "Text label")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
TL1: {
text: Text label
}
```
</div>
</details>

83
docs/art/views/toggle_menu_view.md Normal file
View File

@ -0,0 +1,83 @@
---
layout: page
title: Toggle Menu View
---
## Toggle Menu View
A toggle menu view supports displaying a list of options on a screen horizontally (side to side, in a single row) similar to a [Horizontal Menu](horizontal_menu_view.md). It is designed to present one of two choices easily.
## General Information
Items can be selected on a menu via the left and right cursor keys, or by selecting them via a `hotKey` - see ***Hot Keys*** below.
:information_source: A toggle menu view is defined with a percent (%) and the characters TM, followed by the view number (if used.) For example: `%TM1`
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `focus` | If set to `true`, establishes initial focus |
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `hotKeys` | Sets hot keys to activate specific items. See **Hot Keys** below |
| `hotKeySubmit` | Set to submit a form on hotkey selection |
| `argName` | Sets the argument name for this selection in the form |
| `items` | List of items to show in the menu. Must include exactly two (2) items. See **Items** below. |
### Hot Keys
A set of `hotKeys` are used to allow the user to press a character on the keyboard to select that item, and optionally submit the form.
Example:
```
hotKeys: { A: 0, B: 1, Q: 1 }
hotKeySubmit: true
```
This would select and submit the first item if `A` is typed, second if `B`, etc.
### Items
A toggle menu, similar to other menus, take a list of items to display in the menu. Unlike other menus, however, there must be exactly two items in a toggle menu. For example:
```
items: [
{
text: First Item
data: first
}
{
text: Second Item
data: second
}
]
```
If the list is for display only (there is no form action associated with it) you can omit the data element, and include the items as a simple list:
```
["First item", "Second item"]
```
## Example
![Example](../../assets/images/toggle_menu_view_example1.gif "Toggle menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
TM2: {
focus: true
submit: true
argName: navSelect
focusTextStyle: upper
items: [ "yes", "no" ]
}
```
</div>
</details>

106
docs/art/views/vertical_menu_view.md Normal file
View File

@ -0,0 +1,106 @@
---
layout: page
title: Vertical Menu View
---
## Vertical Menu View
A vertical menu view supports displaying a list of times on a screen vertically in a single column, similar to a lightbar. This type of control is often useful for lists of items or menu controls.
## General Information
Items can be selected on a menu via the cursor keys, Page Up, Page Down, Home, and End, or by selecting them via a `hotKey` - see ***Hot Keys*** below.
:information_source: A vertical menu view is defined with a percent (%) and the characters VM, followed by the view number (if used.) For example: `%VM1`.
:information_source: See [MCI](../mci.md) for general information on how to use views and common configuration properties available for them.
### Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** in [MCI](../mci.md) |
| `focusTextStyle` | Sets focus text style. See **Text Styles** in [MCI](../mci.md)|
| `itemSpacing` | Used to separate items vertically in the menu |
| `height` | Sets the height of views to display multiple items vertically (default 1) |
| `focus` | If set to `true`, establishes initial focus |
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `hotKeys` | Sets hot keys to activate specific items. See **Hot Keys** below |
| `hotKeySubmit` | Set to submit a form on hotkey selection |
| `argName` | Sets the argument name for this selection in the form |
| `justify` | Sets the justification of each item in the list. Options: left (default), right, center |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** in [MCI](../mci.md) |
| `fillChar` | Specifies a character to fill extra space in the menu with. Defaults to an empty space |
| `items` | List of items to show in the menu. See **Items** below.
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** in [MCI](../mci.md) |
### Hot Keys
A set of `hotKeys` are used to allow the user to press a character on the keyboard to select that item, and optionally submit the form.
Example:
```
hotKeys: { A: 0, B: 1, C: 2, D: 3 }
hotKeySubmit: true
```
This would select and submit the first item if `A` is typed, second if `B`, etc.
### Items
A vertical menu, similar to other menus, take a list of items to display in the menu. For example:
```
items: [
{
text: First Item
data: first
}
{
text: Second Item
data: second
}
]
```
If the list is for display only (there is no form action associated with it) you can omit the data element, and include the items as a simple list:
```
["First item", "Second item", "Third Item"]
```
## Example
![Example](../../assets/images/vertical_menu_view_example1.gif "Vertical menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
VM1: {
submit: true
argName: navSelect
items: [
{
text: login
data: login
}
{
text: apply
data: new user
}
{
text: about
data: about
}
{
text: log off
data: logoff
}
]
}
```
</div>
</details>

BIN
docs/assets/images/button_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.1 KiB

BIN
docs/assets/images/edit_text_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.2 KiB

BIN
docs/assets/images/horizontal_menu_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

BIN
docs/assets/images/mask_edit_text_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

BIN
docs/assets/images/multi_line_edit_text_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/assets/images/predefined_label_view_example1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
docs/assets/images/spinner_menu_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.9 KiB

BIN
docs/assets/images/text_label_view_example1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
docs/assets/images/toggle_menu_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.6 KiB

BIN
docs/assets/images/vertical_menu_view_example1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.0 KiB