Rsclub2_2/kst4contest
1
0
Fork 0
mirror of https://github.com/praktimarc/kst4contest.git synced 2026-08-26 12:06:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

manual: overhaul en-variables and macros

Browse Source
This commit is contained in:
Marc Froehlich
2026-08-26 00:56:33 +02:00
parent 5955ba4ecf
commit 4f88101ab7
1 changed files with 275 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
github_docs/en-Macros-and-Variables.md
+275 -82
View File
@@ -2,175 +2,368 @@
> 🇬🇧 You are reading the English version | 🇩🇪 [Deutsche Version](de-Makros-und-Variablen) > 🇬🇧 You are reading the English version | 🇩🇪 [Deutsche Version](de-Makros-und-Variablen)
KST4Contest offers a flexible system of text snippets, shortcuts and built-in variables that significantly speed up the chat workflow during contests. KST4Contest distinguishes between shortcut buttons, text snippets and variables. Shortcuts and snippets contain prepared text. Variables add information which may change during operation.
Inserted text remains visible in the send field and can be checked or edited before transmission.
--- ---
## Overview ## Overview
| Type | Access | Purpose | | Mechanism | Access | Use |
|---|---|---| |---|---|---|
| **Shortcuts** | Button in the toolbar | Quick text insert into the send field | | **Shortcut** | Button above the send field | Inserts configured text into the send field |
| **Snippets** | Right-click / Ctrl+1..0 | Text building blocks, optional PM sending | | **Snippet** | Context menu or `Ctrl+1` through `Ctrl+0` | Prepares text for the selected station |
| **Variables** | Usable in all text fields | Dynamic values (QRG, locator, AP data) | | **Variable** | Placeholder within message text | Inserts current QRG, locator, direction, station or AirScout information |
Shortcuts and snippets store text. Variables supply the corresponding current values.
A shortcut such as
```text
pse sked?
```
always inserts the same text. A shortcut containing
```text
pse call me at MYQRGSHORT
```
instead uses the QRG stored in KST4Contest when the button is pressed.
--- ---
## Shortcuts (Quick-Access Buttons) ## Shortcut Buttons
Configurable in Preferences → **Shortcut Settings**. Shortcuts are configured under **Preferences → Shortcut Settings**.
- Each configured text creates **one button** in the user interface. ![Configuration of shortcut buttons and text snippets](client_settings_window_shortcuts.png)
- Clicking a button inserts the text into the **send field**.
- **All variables** can be used in shortcuts and are resolved immediately when inserted.
- Longer texts are also possible.
**Tip**: Set up frequently used abbreviations like "pse", "rrr", "tnx", "73" as shortcuts. Each entry creates one button in the main window. Pressing it appends the configured text to the existing contents of the send field. Text which has already been prepared is not removed.
If a shortcut contains a variable, the variable is resolved when the text is inserted. For example,
```text
pse call me at MYQRGSHORT
```
may become:
```text
pse call me at 144.388
```
The exact entries `MYQRG` and `SECONDQRG` are highlighted as QRG buttons. They insert the current QRG of the first or second chat category respectively.
The shortcut
```text
/SETNAME MYQRG
```
is highlighted as well. Pressing it resolves `MYQRG` and inserts the resulting server command into the send field. The command is not transmitted automatically.
The order of the entries in the settings determines the button order in the main window. Editing, sorting and saving are described under [Configuration – Shortcut Settings](en-Configuration#shortcut-settings).
--- ---
## Snippets (Text Building Blocks) ## Text Snippets
Configurable in Preferences → **Snippet Settings**. Snippets are configured under **Preferences → Snippet Settings**. They are intended primarily for recurring messages to a particular station.
### Access Snippets can be opened:
- **Right-click** on a callsign in the user list - by right-clicking a station in the user list,
- **Right-click** in the CQ message table - by right-clicking a public message,
- **Right-click** in the PM message table - by right-clicking a private message, or
- **Keyboard shortcuts**: `Ctrl+1` to `Ctrl+0` for the first 10 snippets - with `Ctrl+1` through `Ctrl+0` for the first ten entries in the snippet list.
### Behaviour with a Selected Callsign ### Using the Context Menu
When a callsign is selected in the user list, the snippet is addressed as a **private message**: Selecting a station or message will normally have prepared the corresponding `/cq` destination in the send field. A snippet subsequently chosen from the context menu is appended to this text.
``` Existing message text can therefore be extended deliberately.
/CQ CALLSIGN <snippet text>
### Using the Keyboard
A snippet invoked with `Ctrl+1` through `Ctrl+0` replaces the previous contents of the send field with a complete directed message:
```text
/cq CALLSIGN snippet text
``` ```
Then **Enter** can be pressed to send directly – even if the send field does not have focus. The complete visible callsign, including any suffix, is retained. Selecting `9A0BB-70` may therefore produce:
### Hardware Macro Keyboard ```text
/cq 9A0BB-70 pse ur qrg?
```
*(Idea by IU3OAR, Gianluca Costantino)* KST4Contest also retains the selected station's chat category internally. A snippet for `9A0BB-70` is therefore not accidentally transmitted through the other active chat category.
The key combinations `Ctrl+1` to `Ctrl+0` can be assigned to a programmable macro keyboard. One key press triggers the snippet, another press (mapped to Enter) sends it immediately. In contest operation this saves considerable time. If no station is selected, or no snippet exists for the selected key combination, nothing is inserted.
### Predefined Default Snippets The prepared text is not sent automatically:
On first start, some snippets are pre-configured, e.g.: - `Enter` or **TX** sends the message.
- `Esc` clears the send field.
- `Hi OM, try sked?` ### Keyboard Mapping
- `I am calling cq ur dir, pse lsn to me at MYQRG`
- `pse ur qrg?`
- `rrr, I move to your qrg nw, pse ant dir me`
These can be customised or deleted in the Preferences. The mapping follows the order of the snippet list:
| Key combination | Entry used |
|---|---:|
| `Ctrl+1` | first entry |
| `Ctrl+2` | second entry |
| … | … |
| `Ctrl+9` | ninth entry |
| `Ctrl+0` | tenth entry |
The key combinations can also be assigned to a programmable macro keyboard. The idea for this method came from IU3OAR, Gianluca Costantino.
KST4Contest does not define a mandatory set of default snippets. The useful texts depend on the station's own contest operation and operating method.
Editing, sorting and saving are described under [Configuration – Snippet Settings](en-Configuration#snippet-settings).
--- ---
## Variables ## Variables
Variables in written texts (snippets, shortcuts, beacon, send field) are replaced by their current values at runtime. Simply type the variable name in **uppercase** in the text. Variables are reserved placeholders within message text. They must be written in uppercase and are case-sensitive.
### MYQRG Variables can be used in:
Replaced by the current transceiver frequency. - shortcuts,
- snippets,
- beacon texts, and
- message text entered or pasted directly into the send field.
- Source: TRX sync via UDP from the logging software (if enabled) Variables in a shortcut or snippet are resolved when the text is inserted into the send field. Variables entered or pasted directly into the send field are resolved immediately before the message is placed in the transmission queue.
- Fallback: Manually entered value in the MYQRG text field to the right of the send button
- Format: `144.388.03`
**Example**: `calling cq at MYQRG` → `calling cq at 144.388.03` Station-specific variables always use the currently selected station. KST4Contest does not derive this station from a `/cq` destination entered manually in the message text.
### MYQRGSHORT ---
Like MYQRG, but only the first 7 characters. ## Global Variables
- Format: `144.388` Global variables do not require a selected remote station.
**Example**: `qrg: MYQRGSHORT` → `qrg: 144.388` | Variable | Replacement value |
|---|---|
| `MYQRG` | current QRG of the first or primary chat category |
| `MYQRGSHORT` | first seven characters of `MYQRG` |
| `SECONDQRG` | current QRG of the second chat category |
| `MYLOCATOR` | complete locator configured for the local station |
| `MYLOCATORSHORT` | first four characters of the local locator |
| `MYCALL` | configured local callsign |
| `MYQTF` | current antenna direction as a numeric value in degrees |
### MYLOCATOR For example,
Replaced by your own Maidenhead locator (6 characters). ```text
cq at MYQRGSHORT, qtf MYQTF, loc MYLOCATOR
```
- Format: `JO51IJ` may be resolved to:
**Example**: `my loc: MYLOCATOR` → `my loc: JO51IJ` ```text
cq at 144.388, qtf 135, loc JO51IJ
```
### MYLOCATORSHORT ### QRG Variables
Like MYLOCATOR, but only the first 4 characters. `MYQRG` contains the QRG of the first chat category. The value may come from TRX synchronisation with the logging software or from the manually edited QRG field.
- Format: `JO51` `MYQRGSHORT` uses the same value, but limits it to the first seven characters:
**Example**: `loc: MYLOCATORSHORT` → `loc: JO51` ```text
144.388.03 → 144.388
```
`SECONDQRG` contains the QRG of the second chat category. Selecting a station from the second chat does not change the meaning of `MYQRG`. Use `SECONDQRG` explicitly when the QRG of the second category is required.
### Locator Variables
`MYLOCATOR` inserts the complete configured locator of the local station:
```text
JO51IJ
```
`MYLOCATORSHORT` uses only the first four characters:
```text
JO51
```
### MYQTF
`MYQTF` inserts the current antenna direction stored in KST4Contest as a numeric angle in degrees.
For example,
```text
ant MYQTF deg
```
may become:
```text
ant 135 deg
```
The direction is not converted into compass terms such as `north`, `north-east` or `south-west`.
---
## Variables for the Selected Station
These variables require a selected remote station:
| Variable | Replacement value |
|---|---|
| `QRZNAME` | name of the selected station, or its complete callsign if no name is available |
| `FIRSTAP` | description and arrival time of the first aircraft reported by AirScout |
| `SECONDAP` | description and arrival time of the second aircraft reported by AirScout |
For example,
```text
Hi QRZNAME, FIRSTAP, pse lsn at MYQRGSHORT
```
may become:
```text
Hi David, a very big AP in 2 min, pse lsn at 144.388
```
### QRZNAME ### QRZNAME
Replaced by the **name** of the currently selected station from the chat name field. KST4Contest uses the name from the selected station's name field. If that field does not contain a usable name, the complete visible callsign is inserted instead.
**Example**: `Hi QRZNAME, sked?` → `Hi Gianluca, sked?`
### FIRSTAP ### FIRSTAP
Replaced by data of the first reflectable aircraft to the selected station (if available). If an AirScout candidate is available, `FIRSTAP` contains its description and the expected time until the reflection window.
- Condition: AirScout is active and an aircraft is available. For example:
- Example format: `a very big AP in 1 min`
**Example**: `AP info: FIRSTAP` → `AP info: a very big AP in 1 min` ```text
a very big AP in 2 min
```
If no aircraft is available for the selected station, KST4Contest inserts:
```text
no ap available
```
### SECONDAP ### SECONDAP
Like FIRSTAP, but for the second available aircraft. `SECONDAP` uses the second available AirScout candidate.
- Example format: `Next big AP in 9 min` For example:
**Example**: `also: SECONDAP` → `also: Next big AP in 9 min` ```text
Next big AP in 9 min
```
### MYQTF *(planned for v1.3)* If there is no second candidate, `SECONDAP` is replaced with an empty string.
Replaced by the current antenna direction in words (e.g. `north`, `north east`, `east`, …). Further information about the aircraft data is available under [AirScout Integration](en-AirScout-Integration#ap-variables-in-messages).
- Source: Degree value in the MYQTF input field (to the right of the MYQRG field) ### Behaviour Without a Selected Station
If no station is selected, `QRZNAME`, `FIRSTAP` and `SECONDAP` remain visible in the text. KST4Contest does not remove these placeholders automatically.
A visible unresolved placeholder is clearer than a formally complete message which silently lacks important information. Before transmission, check that the intended station is selected and that all required variables have been resolved.
--- ---
## Variables in the Beacon ## Variables in the Beacon
A public beacon has no selected remote station. It can therefore make meaningful use only of variables which depend on the local station and its current configuration: A public beacon has no selected remote station. It can therefore use only global variables:
| Variable | Value used in the beacon | - `MYQRG`
|---|---| - `MYQRGSHORT`
| `MYQRG` | current QRG of the primary chat category | - `SECONDQRG`
| `MYQRGSHORT` | first seven characters of the primary QRG | - `MYLOCATOR`
| `SECONDQRG` | current QRG of the second chat category | - `MYLOCATORSHORT`
| `MYLOCATOR` | complete configured locator of the local station | - `MYCALL`
| `MYLOCATORSHORT` | four-character locator of the local station | - `MYQTF`
| `MYCALL` | configured local callsign |
| `MYQTF` | current antenna heading |
`QRZNAME`, `FIRSTAP` and `SECONDAP` require a selected remote station. They are therefore not resolved in a public beacon. `QRZNAME`, `FIRSTAP` and `SECONDAP` are not resolved in a beacon and should not be used there.
A suitable configuration for the primary category is: A possible template for the first chat category is:
```text ```text
calling cq at MYQRGSHORT, ant MYQTF deg, loc MYLOCATOR calling cq at MYQRGSHORT, ant MYQTF deg, loc MYLOCATOR
``` ```
For the second category, use `SECONDQRG` if that category should publish a different frequency: If the second chat category uses a different QRG, its template must contain `SECONDQRG`:
```text ```text
calling cq at SECONDQRG, ant MYQTF deg, loc MYLOCATOR calling cq at SECONDQRG, ant MYQTF deg, loc MYLOCATOR
``` ```
Global variables are evaluated again on every timer run. A QRG updated by the logging software can therefore appear in the next beacon message. Global variables are evaluated again on every timer run. A QRG updated by the logging software can therefore already appear in the next beacon message.
The completely resolved text must contain at least one valid character and must not exceed 120 characters. The protocol separator `|` and line breaks are not permitted. If the text is still empty or invalid when transmission is due, that beacon run is skipped. The fully resolved beacon text:
The common interval and the behaviour of both chat categories are described under [Configuration – Beacon Settings](en-Configuration#beacon-settings). - must contain at least one valid character,
- must not exceed 120 characters,
- must not contain the protocol separator `|`, and
- must not contain line breaks.
If the text is empty or invalid when transmission is due, that beacon run is skipped.
The interval, activation and behaviour of both categories are described under [Configuration – Beacon Settings](en-Configuration#beacon-settings).
---
## Example Snippet Workflow
For example, the first configured snippet may contain:
```text
Hi QRZNAME, pse sked? I call at MYQRGSHORT
```
The workflow can then look like this:
1. Select `DL1ABC-432` in the user list.
2. Press `Ctrl+1`.
3. KST4Contest prepares the directed message and resolves its variables.
4. Check the complete text in the send field.
5. If the remote station has proposed another QRG, edit the text accordingly.
6. Press `Enter` or **TX** to send the message.
The result may be:
```text
/cq DL1ABC-432 Hi Peter, pse sked? I call at 432.088
```
The complete callsign determines the recipient. The selected chat category determines the transmission path. Variables reduce repeated typing, but they do not decide whether the inserted information still matches the current operating situation.
---
## Limits of Variable Resolution
Variables reflect the information available to KST4Contest at the time they are resolved.
In particular:
- A QRG supplied by the logging software may have changed in the meantime.
- A manually entered QRG remains active until it is changed again.
- `MYQRG` remains the QRG of the primary category even if a station from the second category is selected.
- The selected station may differ from a `/cq` destination entered manually.
- AirScout may not provide current aircraft data for the path in question.
- Station-specific variables remain visible when no station is selected.
- Inserted text is not checked automatically for operational correctness.
The send field therefore remains editable after a shortcut or snippet has been inserted. Variables avoid repeated input; the final check remains the operator's responsibility.
--- ---