zydronium/enigma-bbs
1
0
Fork 0
mirror of https://github.com/NuSkooler/enigma-bbs.git synced 2025-08-03 00:12:01 +02:00
Code Issues Projects Releases Packages Wiki Activity

Automatically generate the navigation

Browse source
This commit is contained in:
Nathan Byrd 2022-02-04 08:51:03 -06:00
parent 4793ad0492
commit b5b0cc3ac5
94 changed files with 236 additions and 335 deletions
Download patch file Download diff file Expand all files Collapse all files

174
docs/_docs/art/general.md Normal file
View file

@ -0,0 +1,174 @@
---
layout: page
title: General Art Information
---
## General Art Information
One of the most basic elements of BBS customization is through it's artwork. ENiGMA½ supports a variety of ways to select, display, and manage art.
### Art File Locations
As a general rule, art files live in one of two places:
1. The `art/general` directory. This is where you place common/non-themed art files.
2. Within a _theme_ such as `art/themes/super_fancy_theme`.
### MCI Codes
All art can contain [MCI Codes](mci.md).
### Art in Menus
While art can be displayed programmatically such as from a custom module, the most basic and common form is via `menu.hjson` entries. This usually falls into one of two forms:
#### Standard
A "standard" entry where a single `art` spec is utilized:
```hjson
{
mainMenu: {
art: main_menu.ans
}
}
```
#### Module Specific / Multiple Art
An entry for a custom module where multiple pieces are declared and used. The second style usually takes the form of a `config.art` block with two or more entries:
```hjson
{
nodeMessage: {
config: {
art: {
header: node_msg_header
footer: node_msg_footer
}
}
}
}
```
A menu entry has a few elements that control how art is selected and displayed. First, the `art` *spec* tells the system how to look for the art asset. Second, the `config` block can further control aspects of lookup and display. The following table describes such entries:
| Item | Description|
|------|------------|
| `font` | Sets the [SyncTERM](http://syncterm.bbsdev.net/) style font to use when displaying this art. If unset, the system will use the art's embedded [SAUCE](http://www.acid.org/info/sauce/sauce.htm) record if present or simply use the current font. See Fonts below. |
| `pause` | If set to `true`, pause after displaying. |
| `baudRate` | Set a [SyncTERM](http://syncterm.bbsdev.net/) style emulated baud rate when displaying this art. In other words, slow down the display. |
| `cls` | Clear the screen before display if set to `true`. |
| `random` | Set to `false` to explicitly disable random lookup. |
| `types` | An optional array of types (aka file extensions) to consider for lookup. For example : `[ '.ans', '.asc' ]` |
| `readSauce` | May be set to `false` if you need to explicitly disable SAUCE support. |
#### Art Spec
In the section above it is mentioned that the `art` member is a *spec*. The value of a `art` spec controls how the system looks for an asset. The following forms are supported:
* `FOO`: The system will look for `FOO.ANS`, `FOO.ASC`, `FOO.TXT`, etc. using the default search path. Unless otherwise specified if `FOO1.ANS`, `FOO2.ANS`, and so on exist, a random selection will be made.
* `FOO.ANS`: By specifying an extension, only the exact match will be searched for.
* `rel/path/to/BAR.ANS`: Only match a path (relative to the system's `art` directory).
* `/path/to/BAZ.ANS`: Exact path only.
ENiGMA½ uses a fallback system for art selection. When a menu entry calls for a piece of art, the following search is made:
1. If a direct or relative path is supplied, look there first.
2. In the users current theme directory.
3. In the system default theme directory.
4. In the `art/general` directory.
#### ACS-Driven Conditionals
The [ACS](../configuration/acs.md) system can be used to make conditional art selection choices. To do this, provide an array of possible values in your art spec. As an example:
```hjson
{
fancyMenu: {
art: [
{
acs: GM[l33t]
art: leet_art.ans
}
{
// default
art: newb.asc
}
]
}
}
```
#### SyncTERM Style Fonts
ENiGMA½ can set a [SyncTERM](http://syncterm.bbsdev.net/) style font for art display. This is supported by many other popular BBS terminals as well. A common usage is for displaying Amiga style fonts for example. The system will use the `font` specifier or look for a font declared in an artworks SAUCE record (unless `readSauce` is `false`).
The most common fonts are probably as follows:
* `cp437`
* `c64_upper`
* `c64_lower`
* `c128_upper`
* `c128_lower`
* `atari`
* `pot_noodle`
* `mo_soul`
* `microknight_plus`
* `topaz_plus`
* `microknight`
* `topaz`
...and some examples:
![cp437](../assets/images/cp437.png "cp437")<br>
![pot_noodle](../assets/images/pot_noodle.png "pot_noodle")<br>
![mo_soul](../assets/images/mo_soul.png "mo_soul")<br>
![microknight_plus](../assets/images/microknight_plus.png "microknight_plus")<br>
![topaz_plus](../assets/images/topaz_plus.png "topaz_plus")<br>
![microknight](../assets/images/microknight.png "microknight")<br>
![topaz](../assets/images/topaz.png "topaz")<br>
Other "fonts" also available:
* `cp1251`
* `koi8_r`
* `iso8859_2`
* `iso8859_4`
* `cp866`
* `iso8859_9`
* `haik8`
* `iso8859_8`
* `koi8_u`
* `iso8859_15`
* `iso8859_4`
* `koi8_r_b`
* `iso8859_4`
* `iso8859_5`
* `ARMSCII_8`
* `iso8859_15`
* `cp850`
* `cp850`
* `cp885`
* `cp1251`
* `iso8859_7`
* `koi8-r_c`
* `iso8859_4`
* `iso8859_1`
* `cp866`
* `cp437`
* `cp866`
* `cp885`
* `cp866_u`
* `iso8859_1`
* `cp1131`
:information_source: See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information.
#### SyncTERM Style Baud Rates
The `baudRate` member can set a [SyncTERM](http://syncterm.bbsdev.net/) style emulated baud rate. May be `300`, `600`, `1200`, `2400`, `4800`, `9600`, `19200`, `38400`, `57600`, `76800`, or `115200`. A value of `ulimited`, `off`, or `0` resets (disables) the rate.
:information_source: See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information.
### Common Example
```hjson
fullLogoffSequenceRandomBoardAd: {
art: OTHRBBS
desc: Logging Off
next: logoff
config: {
baudRate: 57600
pause: true
cls: true
}
}
```
### See Also
See also the [Show Art Module](../modding/show-art.md) for more advanced art display!

238
docs/_docs/art/mci.md Normal file
View file

@ -0,0 +1,238 @@
---
layout: page
title: MCI Codes
---
## MCI Codes
ENiGMA½ supports a variety of MCI codes. Some **predefined** codes produce information about the current user, system, or other statistics while others are used to instantiate a **View**.
## General Information
MCI codes are composed of two characters and are prefixed with a percent (%) symbol.
:information_source: To explicitly tie a MCI to a specific View ID, suffix the MCI code with a number. For example: `%BN1`.
:information_source: Standard (non-focus) and focus colors are set by placing duplicate codes back to back in art files:
![Example](../assets/images/mci-example1.png "MCI Colors")
Some MCI codes have additional options that may be set directly from the code itself while others -- and more advanced options -- are controlled via the current theme.
## Relationship with Menus, Art, and Themes
A MCI code that appears in a `menu.hjson` entry corresponds to that found in it's associated art file. This same MCI code can be referenced in the `theme.hjson` in order to apply a theme.
See [Menus](../docs/configuration/menu-hjson.md) and [Themes](themes.md) for more information.
## Predefined Codes
There are many predefined MCI codes that can be used anywhere on the system (placed in any art file).
| Code | Description |
|------|--------------|
| `BN` | Board Name |
| `VL` | Version *label*, e.g. "ENiGMA½ v0.0.12-beta" |
| `VN` | Version *number*, eg.. "0.0.12-beta" |
| `SN` | SysOp username |
| `SR` | SysOp real name |
| `SL` | SysOp location |
| `SA` | SysOp affiliations |
| `SS` | SysOp sex |
| `SE` | SysOp email address |
| `UN` | Current user's username |
| `UI` | Current user's user ID |
| `UG` | Current user's group membership(s) |
| `UR` | Current user's real name |
| `LO` | Current user's location |
| `UA` | Current user's age |
| `BD` | Current user's birthday (using theme date format) |
| `US` | Current user's sex |
| `UE` | Current user's email address |
| `UW` | Current user's web address |
| `UF` | Current user's affiliations |
| `UT` | Current user's theme name |
| `UD` | Current user's *theme ID* (e.g. "luciano_blocktronics") |
| `UC` | Current user's login/call count |
| `ND` | Current user's connected node number |
| `IP` | Current user's IP address |
| `ST` | Current user's connected server name (e.g. "Telnet" or "SSH") |
| `FN` | Current user's active file base filter name |
| `DN` | Current user's number of downloads |
| `DK` | Current user's download amount (formatted to appropriate bytes/megs/etc.) |
| `UP` | Current user's number of uploads |
| `UK` | Current user's upload amount (formatted to appropriate bytes/megs/etc.) |
| `NR` | Current user's upload/download ratio |
| `KR` | Current user's upload/download *bytes* ratio |
| `MS` | Current user's account creation date (using theme date format) |
| `PS` | Current user's post count |
| `PC` | Current user's post/call ratio |
| `MD` | Current user's status/viewing menu/activity |
| `MA` | Current user's active message area name |
| `MC` | Current user's active message conference name |
| `ML` | Current user's active message area description |
| `CM` | Current user's active message conference description |
| `SH` | Current user's term height |
| `SW` | Current user's term width |
| `AC` | Current user's total achievements |
| `AP` | Current user's total achievement points |
| `DR` | Current user's number of door runs |
| `DM` | Current user's total amount of time spent in doors |
| `DT` | Current date (using theme date format) |
| `CT` | Current time (using theme time format) |
| `OS` | System OS (Linux, Windows, etc.) |
| `OA` | System architecture (x86, x86_64, arm, etc.) |
| `SC` | System CPU model |
| `NV` | System underlying Node.js version |
| `AN` | Current active node count |
| `TC` | Total login/calls to the system *ever* |
| `TT` | Total login/calls to the system *today* |
| `RR` | Displays a random rumor |
| `SD` | Total downloads, system wide |
| `SO` | Total downloaded amount, system wide (formatted to appropriate bytes/megs/etc.) |
| `SU` | Total uploads, system wide |
| `SP` | Total uploaded amount, system wide (formatted to appropriate bytes/megs/etc.) |
| `TF` | Total number of files on the system |
| `TB` | Total amount of files on the system (formatted to appropriate bytes/megs/gigs/etc.) |
| `TP` | Total messages posted/imported to the system *currently* |
| `PT` | Total messages posted/imported to the system *today* |
Some additional special case codes also exist:
| Code | Description |
|--------|--------------|
| `CF##` | Moves the cursor position forward _##_ characters |
| `CB##` | Moves the cursor position back _##_ characters |
| `CU##` | Moves the cursor position up _##_ characters |
| `CD##` | Moves the cursor position down _##_ characters |
| `XY` | A special code that may be utilized for placement identification when creating menus or to extend an otherwise empty space in an art file down the screen. |
:information_source: More are added all
the time so also check out [core/predefined_mci.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js)
for a full listing.
:memo: Many codes attempt to pay homage to Oblivion/2, iNiQUiTY, etc.
## Views
A **View** is a control placed on a **form** that can display variable data or collect input. One example of a View is
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. 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.
### Mask Edits
Mask Edits (`%ME`) use the special `maskPattern` property to control a _mask_. This can be useful for gathering dates, phone numbers, so on.
`maskPattern`'s can be composed of the following characters:
* `#`: Numeric 0-9
* `A`: Alpha a-z, A-Z
* `@`: Alphanumeric (combination of the previous patterns)
* `&`: Any "printable" character
Any other characters are literals.
An example of a mask for a date may look like this: `##/##/####`.
Additionally, the following theme stylers can be applied:
* `styleSGR1`: Controls literal character colors for non-focused controls
* `styleSGR2`: Controls literal character colors for focused controls
* `styleSGR3`: Controls fill colors (characters that have not yet received input).
All of the style properties can take pipe codes such as `|00|08`.
### View Identifiers
As mentioned above, MCI codes can (and often should) be explicitly tied to a *View Identifier*. Simply speaking this is a number representing the particular view. These can be useful to reference in code, apply themes, etc.
A view ID is tied to a MCI code by specifying it after the code. For example: `%VM1` or `%SM10`.
## Properties & Theming
Predefined MCI codes and other Views can have properties set via `menu.hjson` and further *themed* via `theme.hjson`. See [Themes](themes.md) for more information on this subject.
### Common Properties
| Property | Description |
|-------------|--------------|
| `textStyle` | Sets the standard (non-focus) text style. See **Text Styles** below |
| `focusTextStyle` | Sets focus text style. See **Text Styles** below. |
| `itemSpacing` | Used to separate items in menus such as Vertical Menu and Horizontal Menu Views. |
| `height` | Sets the height of views such as menus that may be > 1 character in height |
| `width` | Sets the width of a view |
| `focus` | If set to `true`, establishes initial focus |
| `text` | (initial) text of a view |
| `submit` | If set to `true` any `accept` action upon this view will submit the encompassing **form** |
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** below |
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** below |
These are just a few of the properties set on various views. *Use the source Luke*, as well as taking a look at the default `menu.hjson` and `theme.hjson` files!
### Custom Properties
Often a module will provide custom properties that receive format objects (See **Entry Formatting** below). Custom property formatting can be declared in the `config` block. For example, `browseInfoFormat10`..._N_ (where _N_ is up to 99) in the `file_area_list` module received a fairly extensive format object that contains `{fileName}`, `{estReleaseYear}`, etc.
### Text Styles
Standard style types available for `textStyle` and `focusTextStyle`:
| Style | Description |
|----------|--------------|
| `normal` | Leaves text as-is. This is the default. |
| `upper` | ENIGMA BULLETIN BOARD SOFTWARE |
| `lower` | enigma bulletin board software |
| `title` | Enigma Bulletin Board Software |
| `first lower` | eNIGMA bULLETIN bOARD sOFTWARE |
| `small vowels` | eNiGMa BuLLeTiN BoaRD SoFTWaRe |
| `big vowels` | EniGMa bUllEtIn bOArd sOftwArE |
| `small i` | ENiGMA BULLETiN BOARD SOFTWARE |
| `mixed` | EnIGma BUlLEtIn BoaRd SOfTWarE (randomly assigned) |
| `l33t` | 3n1gm4 bull371n b04rd 50f7w4r3 |
### Entry Formatting
Various strings can be formatted using a syntax that allows width & precision specifiers, text styling, etc. Depending on the context, various elements can be referenced by `{name}`. Additional text styles can be supplied as well. The syntax is largely modeled after Python's [string format mini language](https://docs.python.org/3/library/string.html#format-specification-mini-language).
### Additional Text Styles
Some of the text styles mentioned above are also available in the mini format language:
| Style | Description |
|-------|-------------|
| `normal` | Leaves text as-is. This is the default. |
| `toUpperCase` or `styleUpper` | ENIGMA BULLETIN BOARD SOFTWARE |
| `toLowerCase` or `styleLower` | enigma bulletin board software |
| `styleTitle` | Enigma Bulletin Board Software |
| `styleFirstLower` | eNIGMA bULLETIN bOARD sOFTWARE |
| `styleSmallVowels` | eNiGMa BuLLeTiN BoaRD SoFTWaRe |
| `styleBigVowels` | EniGMa bUllEtIn bOArd sOftwArE |
| `styleSmallI` | ENiGMA BULLETiN BOARD SOFTWARE |
| `styleMixed` | EnIGma BUlLEtIn BoaRd SOfTWarE (randomly assigned) |
| `styleL33t` | 3n1gm4 bull371n b04rd 50f7w4r3 |
Additional text styles are available for numbers:
| Style | Description |
|-------------------|---------------|
| `sizeWithAbbr` | File size (converted from bytes) with abbreviation such as `1 MB`, `2.2 GB`, `34 KB`, etc. |
| `sizeWithoutAbbr` | Just the file size (converted from bytes) without the abbreviation. For example: 1024 becomes 1. |
| `sizeAbbr` | Just the abbreviation given a file size (converted from bytes) such as `MB` or `GB`. |
| `countWithAbbr` | Count with abbreviation such as `100 K`, `4.3 B`, etc. |
| `countWithoutAbbr` | Just the count |
| `countAbbr` | Just the abbreviation such as `M` for millions. |
| `durationHours` | Converts the provided *hours* value to something friendly such as `4 hours`, or `4 days`. |
| `durationMinutes` | Converts the provided *minutes* to something friendly such as `10 minutes` or `2 hours` |
| `durationSeconds` | Converts the provided *seconds* to something friendly such as `23 seconds` or `2 minutes` |
#### Examples
Suppose a format object contains the following elements: `userName` and `affils`. We could create a `itemFormat` entry that builds a item to our specifications: `|04{userName!styleFirstLower} |08- |13{affils}`. This may produce a string such as this:
![Example](../assets/images/text-format-example1.png "Text Format")
:bulb: Remember that a Python [string format mini language](https://docs.python.org/3/library/string.html#format-specification-mini-language) style syntax is available for widths, alignment, number prevision, etc. as well. A number can be made to be more human readable for example: `{byteSize:,}` may yield "1,123,456".

167
docs/_docs/art/themes.md Normal file
View file

@ -0,0 +1,167 @@
---
layout: page
title: Themes
---
## Themes
ENiGMA½ comes with an advanced theming system allowing system operators to highly customize the look and feel of their boards. A given installation can have as many themes as you like for your users to choose from.
## General Information
Themes live in `art/themes/`. Each theme (and thus it's *theme ID*) is a directory within the `themes` directory. The theme itself is simply a collection of art files, and a `theme.hjson` file that further defines layout, colors & formatting, etc.
ENiGMA½ comes with a default theme by [Luciano Ayres](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`.
## Art
For information on art files, see [General Art Information](general.md). In general, to theme a piece of art, create a version of it in your themes directory.
:memo: Remember that by default, the system will allow for randomly selecting art (in one of the directories mentioned above) by numbering it: `FOO1.ANS`, `FOO2.ANS`, etc.!
## Theme Sections
Themes are some important sections to be aware of:
| Config Item | Description |
|-------------|----------------------------------------------------------|
| `info` | This section describes the theme. |
| `customization` | The beef! |
### Info Block
The `info` configuration block describes the theme itself.
| Item | Required | Description |
|-------------|----------|----------------------------------------------------------|
| `name` | :+1: | Name of the theme. Be creative! |
| `author` | :+1: | Author of the theme/artwork. |
| `group` | :-1: | Group/affils of author. |
| `enabled` | :-1: | Boolean of enabled state. If set to `false`, this theme will not be available to your users. If a user currently has this theme selected, the system default will be selected for them at next login. |
### Customization Block
The `customization` block in is itself broken up into major parts:
| Item | Description |
|-------------|---------------------------------------------------|
| `defaults` | Default values to use when this theme is active. These values override system defaults, but can still be overridden themselves in specific areas of your theme. |
| `menus` | The bulk of what you theme in the system will be here. Any menu (that is, anything you find in `menu.hjson`) can be tweaked. |
| `prompts` | Similar to `menus`, this section themes `prompts`. |
#### Defaults
Override system defaults.
| Item | Description |
|-------------|---------------------------------------------------|
| `passwordChar` | Character to display in password fields. Defaults to `*` |
| `dateFormat` | Sets the [moment.js](https://momentjs.com/docs/#/displaying/) style `short` and/or `long` format for dates. |
| `timeFormat` | Sets the [moment.js](https://momentjs.com/docs/#/displaying/) style `short` and/or `long` format for times. |
| `dateTimeFormat` | Sets the [moment.js](https://momentjs.com/docs/#/displaying/) style `short` and/or `long` format for date/time combinations. |
Example:
```hjson
defaults: {
dateTimeFormat: {
short: MMM Do h:mm a
}
}
```
#### Menus Block
Each *key* in the `menus` block matches up with a key found in your `menu.hjson`. For example, consider a `matrix` menu defined in `menu.hjson`. In addition to perhaps providing a `MATRIX.ANS` in your themes directory, you can also theme other parts of the menu via a `matrix` entry in `theme.hjson`.
Major areas to override/theme:
* `config`: Override and/or provide additional theme information over that found in the `menu.hjson`'s entry. Common entries here are for further overriding date/time formats, and custom range info formats (`<someFormName>InfoFormat<num>`). See Entry Formatting in [MCI Codes](mci.md) and Custom Range Info Formatting below.
* `mci`: Set per-MCI code properties such as `height`, `width`, text styles, etc. See [MCI Codes](mci.md) for a more information.
Two formats for `mci` blocks are allowed:
* Shorthand if only a single/first form is needed.
* Verbose where a form ID(s) are supplied (required if multiple forms are used)
Example: Shorthand `mci` format:
```hjson
matrix: {
mci: {
VM1: {
itemFormat: "|03{text}"
focusItemFormat: "|11{text!styleFirstLower}"
}
}
}
```
Example: Verbose `mci` with form IDs:
```hjson
newUserFeedbackToSysOp: {
0: {
mci: {
TL1: { width: 19, textOverflow: "..." }
ET2: { width: 19, textOverflow: "..." }
ET3: { width: 19, textOverflow: "..." }
}
}
1: {
mci: {
MT1: { height: 14 }
}
}
}
```
##### Custom Range Info Formatting
Many modules support "custom range" MCI items. These are MCI codes that are left to the user to define using a format object specific to the module. For example, consider the `msg_area_list` module: This module sets MCI codes 10+ (`%TL10`, `%TL11`, etc.) as "custom range". When theming you can place these MCI codes in your artwork then define the format in `theme.hjson`:
```hjson
messageAreaChangeCurrentArea: {
config: {
areaListInfoFormat10: "|15{name}|07: |03{desc}"
}
}
```
## Creating Your Own
:warning: ***IMPORTANT!*** Do not make any customizations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead:
1. Copy `/art/themes/luciano_blocktronics` to `art/themes/your_board_theme`
2. Update the `info` block at the top of the theme.hjson file:
``` hjson
info: {
name: Awesome Theme
author: Cool Artist
group: Sick Group
enabled: true // default
}
```
3. If desired, you may make this the default system theme in `config.hjson` via `theme.default`. `theme.preLogin` may be set if you want this theme used for pre-authenticated users. Both of these values also accept `*` if you want the system to randomly pick.
``` hjson
theme: {
default: your_board_theme
preLogin: *
}
```
## Theming Example
Let's run through an example!
Consider the following `menu.hjson` entry:
```hjson
superFancyMenu: {
art: FANCY.ANS
// ...some other stuff...
}
```
With a file of `FANCY.ANS` in `art/themes/fancy_theme` containing the following MCI codes:
* TL1 (Generic text label)
* BN2 (Predefined: Board Name)
An entry in your `theme.hjson` could look like this:
```hjson
superFancyMenu: {
mci: {
TL1: {
// supply the full format of the TL1 View
text: |02ENiGMA|10½ |08v|03|VN
}
BN2: {
// Make Board Name l33t style
style: l33t
}
}
}
```

57
docs/_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/_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>

240
docs/_docs/art/views/full_menu_view.md Normal file
View file

@ -0,0 +1,240 @@
---
layout: page
title: Full Menu View
---
## Full Menu View
A full menu view supports displaying a list of times on a screen in a very configurable manner. A full menu view supports either a single row or column of values, similar to Horizontal Menu (HM) and Vertical Menu (VM), or in multiple columns.
## 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 full menu view is defined with a percent (%) and the characters FM, followed by the view number. For example: `%FM1`
: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 |
| `itemHorizSpacing` | Used to separate items horizontally in the menu |
| `height` | Sets the height of views to display multiple items vertically (default 1) |
| `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 |
| `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 [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 full 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"]
```
### 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.
:information_source: If `textOverflow` is not specified at all, a menu can become wider than the `width` if needed to display a single column.
: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: ...`
## Examples
### A simple vertical menu - similar to VM
![Example](../../assets/images/full_menu_view_example1.gif "Vertical menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
FM1: {
submit: true
argName: navSelect
width: 1
items: [
{
text: login
data: login
}
{
text: apply
data: new user
}
{
text: about
data: about
}
{
text: log off
data: logoff
}
]
}
```
</div>
</details>
### A simple horizontal menu - similar to HM
![Example](../../assets/images/full_menu_view_example2.gif "Horizontal menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
FM2: {
focus: true
height: 1
width: 60 // set as desired
submit: true
argName: navSelect
items: [
"prev", "next", "details", "toggle queue", "rate", "help", "quit"
]
}
```
</div>
</details>
### A multi-column navigation menu with hotkeys
![Example](../../assets/images/full_menu_view_example3.gif "Multi column menu")
<details>
<summary>Configuration fragment (expand to view)</summary>
<div markdown="1">
```
FM1: {
focus: true
height: 6
width: 60
submit: true
argName: navSelect
hotKeys: { M: 0, E: 1, D: 2 ,F: 3,!: 4, A: 5, C: 6, Y: 7, S: 8, R: 9, O: 10, L:11, U:12, W: 13, B:14, G:15, T: 16, Q:17 }
hotKeySubmit: true
items: [
{
text: M) message area
data: message
}
{
text: E) private email
data: email
}
{
text: D) doors
data: doors
}
{
text: F) file base
data: files
}
{
text: !) global newscan
data: newscan
}
{
text: A) achievements
data: achievements
}
{
text: C) configuration
data: config
}
{
text: Y) user stats
data: userstats
}
{
text: S) system stats
data: systemstats
}
{
text: R) rumorz
data: rumorz
}
{
text: O) onelinerz
data: onelinerz
}
{
text: L) last callers
data: callers
}
{
text: U) user list
data: userlist
}
{
text: W) whos online
data: who
}
{
text: B) bbs list
data: bbslist
}
{
text: G) node-to-node messages
data: nodemessages
}
{
text: T) multi relay chat
data: mrc
}
{
text: Q) quit
data: quit
}
]
}
```
</div>
</details>

91
docs/_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/_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/_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/_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/_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/_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/_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/_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>