Settings

Reference for the settings window of an OctoMY™ app: its columns, marks, levels, buttons and keys. The second half covers where settings are stored and the few node keys that you edit in a file.

For step-by-step guides, see Settings how-to guides.

The settings window

The window has a left side and a right side:

Filter

Columns

Right-click a header to show or hide a column. Reset columns in that menu returns to the default set. Drag a header edge to resize a column.

Inputs

The mouse wheel scrolls the table. It changes a value only in the cell that is being edited.

Marks

Levels

An app can keep a setting at more than one level, in priority order. A value at a higher level overrides the value at a lower level. An app with one level shows no Write to and no Source column.

The levels of Construct are New scenes, Scene and Camera: ‹name›. See Where Construct settings live.

Footer buttons

A step is one edit, one drag, one reset, one Reset all or one import. A change made by an OPAL task of the config family is a step too. The file format is in Move settings between machines.

Keyboard

Where settings are stored

OctoMY™ keeps settings through a Settings class over Qt's QSettings, in one of two modes:

The file mode keeps each personality apart: its settings live inside its own directory and go with it when the personality is nuked. For the folders that an app uses on each platform, see Where your data lives.

A personality directory holds these files:

Node::nuke() removes every file in the directory except personality_manifest.json.

In an INI file, a key group/name sits under [group] as name. A deeper key keeps its rest with backslashes, so batch/remote/forwarded-types is stored as:

[batch]
remote\forwarded-types=construct/thumbnail_update

There is no other channel. OctoMY™ reads no environment variable for a setting: a value comes from the settings window, a settings file, the node configuration or a command-line option.

Node keys you edit in a file

Most settings are in the settings window, which shows the description of each one. The keys below are the exception: you set them in the settings file before the node starts, or another surface writes them.

See Fleet for the configuration the fleet keys hold.

Settings API

Code reads and writes settings through Settings (app/Settings.hpp).

#include "app/Settings.hpp"

// From a Node or an Activity
Settings *settings = node()->settings().data();

QString name = settings->getCustomSetting("network/name", "default");
settings->setCustomSetting("network/name", "MyRobot");

bool enabled = settings->getCustomSettingBool("discovery/enabled", true);
int port = settings->getCustomSettingInt("network/localPort", 8124);
double rate = settings->getCustomSettingDouble("sensor/updateRate", 50.0);
qint64 seen = settings->getCustomSettingLong("session/lastSeen", 0);
QByteArray state = settings->getCustomSettingByteArray("splitter/state");
QRect geometry = settings->getCustomSettingRect("window/geometry", QRect(100, 100, 800, 600));

if (settings->hasCustomSetting("pairing/skipped")) { /* ... */ }

settings->sync();                // Write now. Writes are normally batched
settings->resetConfiguration();  // Clear every setting

Most setters have a …Durable form that writes to disk at once, past the batching. A file-based Settings takes the path of its INI file:

Settings platformDefault("group", "OctoMY Agent", "1.0");
Settings fileBased("group", "OctoMY Agent", "1.0", "/path/to/personality/settings.ini");

AppContext makes the file-based form when the app starts with --base-dir.

Node settings in the settings window

Hub, Agent and Remote show the settings of the node in one settings window. Open it in one of these ways:

• Push Settings in the setup menu of the node.
• Push Ctrl+,. Where the platform has its own Preferences key, that key also opens the window, for example Ctrl+Shift+, on KDE.

The window title is "Settings — Hub", "Settings — Agent" or "Settings — Remote". On Android the settings open as a page of the app, not as a window.

Each row is kept in the app::Settings of the node, under the key in the tables below. The keys did not change when the window replaced the Preferences page, so a node keeps its values. Each value is kept for each node: two nodes on one machine keep their own values.

The OPAL tasks config.get, config.set and config.list reach the same rows. Use the schema id in the first column of each table.

Node schema (node)

The microphone, the speaker and the output level are also on the Banter screen of the comms channels. That screen writes the same rows, so a change on one shows on the other.

A log row applies immediately. When the node opens its main window, it applies the stored levels. A category that the --log option raised for this run keeps the level of the option.

Swarm schema (swarm, Hub only)

Trove schema (trove, Hub only)

The trove settings have their own window, "Settings — Trove". The Settings button of the projects wall and of a project board opens it. The trove schema has two levels:

• All projects (app): the key below, in the settings of the node.
• Project (project): an override for one project, kept in trove/projects.json. A row that a project does not set uses the value of all projects. The board of a project opens the window with "Write to" set to that project.

RTS schema (rts, Hub only)

The RTS settings have their own window, "Settings — RTS". To open it, push Settings in the RTS menu, in the match lobby, or in the match panel of the game. Ctrl+, opens it too while the RTS menu, the match browser, the lobby or the game has the keyboard. Everywhere else in the Hub, Ctrl+, opens the settings of the Hub.

The two swatches of the match lobby write these rows. Factory reset in the lobby removes both keys, so the colors follow the identity of the node again.

See also

• Settings how-to guides
• Config OPAL tasks
• CLI options
• Where your data lives