AppSettings¶

class nmeasim::app::AppSettings · Applications

Persistent application preferences (not the simulation profile), stored with QSettings in the platform's native location.

Declared in src/app/app_settings.hpp (line 52)

Every accessor goes straight to QSettings, which makes a change visible at once to the other instances in the process (main and MainWindow each keep one) and writes it to storage later. The keys and their defaults:

Key	Accessors	Default
`profile/last_path`	`last_profile_path`, `set_last_profile_path`	empty
`window/geometry`	`window_geometry`, `save_window`	empty
`window/state`	`window_state`, `save_window`	empty
`simulation/autostart`	`autostart`, `set_autostart`	`false`
`map/online`	`map_online`, `set_map_online`	`true`
`map/tile_url`	`map_tile_url`, `set_map_tile_url`	empty
`map/tile_attribution`	`map_tile_attribution`, `set_map_tile_attribution`	unset
`map/zoom`	`map_zoom`, `set_map_zoom`	`12.0`
`map/cache_directory`	`map_cache_directory`, `set_map_cache_directory`	empty
`appearance/theme`	`theme`, `set_theme`	`night`

The store is chosen by QSettings from the organisation and application names that main sets (NMEASimulatorX for both) and, on macOS, the organisation domain: the registry key HKEY_CURRENT_USER\Software\NMEASimulatorX\NMEASimulatorX on Windows, ~/Library/Preferences/io.github.dimitrios-kafetzis.NMEASimulatorX.plist on macOS and ~/.config/NMEASimulatorX/NMEASimulatorX.conf on Linux.

Not copyable, because the QSettings member is not.

Note

Construct it only after the application and organisation names are set; an instance created earlier reads and writes a different store.

See also

docs/reference/desktop-app.md, section "Preferences".

Summary¶

Public member functions

Name	Description
`last_profile_path()`	Returns the profile to reopen at the next start (key `profile/last_path`).
`set_last_profile_path()`	Stores the profile to reopen at the next start (key `profile/last_path`).
`window_geometry()`	Returns the saved window geometry (key `window/geometry`).
`window_state()`	Returns the saved toolbar and dock layout (key `window/state`).
`save_window()`	Stores the window geometry and the dock layout (keys `window/geometry` and `window/state`).
`autostart()`	Returns whether the simulation starts as soon as the window opens (key `simulation/autostart`).
`set_autostart()`	Stores whether the simulation starts as soon as the window opens (key `simulation/autostart`).
`map_online()`	Returns whether missing map tiles are downloaded (key `map/online`).
`set_map_online()`	Stores whether missing map tiles are downloaded (key `map/online`).
`map_tile_url()`	Returns the tile server URL template (key `map/tile_url`).
`set_map_tile_url()`	Stores the tile server URL template (key `map/tile_url`).
`map_tile_attribution()`	Returns the attribution the map draws for the tile server (key `map/tile_attribution`).
`set_map_tile_attribution()`	Stores the attribution the map draws for the tile server (key `map/tile_attribution`).
`map_zoom()`	Returns the map zoom level of the last session (key `map/zoom`).
`set_map_zoom()`	Stores the map zoom level (key `map/zoom`).
`map_cache_directory()`	Returns the directory chosen for the map tile cache (key `map/cache_directory`).
`set_map_cache_directory()`	Stores the directory for the map tile cache (key `map/cache_directory`).
`theme()`	Returns the look chosen under View → Theme (key `appearance/theme`).
`set_theme()`	Stores the look chosen under View → Theme (key `appearance/theme`).

Public static member functions

Name	Description
`profiles_directory()`	Returns the directory the profile dialogs offer by default, creating it when missing.
`tile_cache_directory()`	Returns the directory where downloaded map tiles are kept, creating it when missing.
`resolve_profile_path()`	Returns the absolute path that a file path of a profile names.
`dialog_directory()`	Returns the folder that a file dialog for a file path of a profile starts in.

Private data members

Name	Description
`settings_`	The native settings store of the application, opened by the default `QSettings` constructor from the organisation and application names.

Public member functions¶

last_profile_path()¶

QString last_profile_path() const

Returns the profile to reopen at the next start (key profile/last_path).

Returns QString: The path of the profile last loaded or saved; empty when there is none.

Declared in src/app/app_settings.hpp:57 · defined in src/app/app_settings.cpp:46

set_last_profile_path()¶

void set_last_profile_path(const QString& path)

Stores the profile to reopen at the next start (key profile/last_path).

Parameters

Name	Type	Description
`path`	`const QString&`	Path of a profile file, stored as given; empty forgets the last one.

Declared in src/app/app_settings.hpp:61 · defined in src/app/app_settings.cpp:50

window_geometry()¶

QByteArray window_geometry() const

Returns the saved window geometry (key window/geometry).

Returns QByteArray: The bytes of QWidget::saveGeometry; empty before the window was first closed, which QWidget::restoreGeometry rejects, leaving the default size.

Declared in src/app/app_settings.hpp:67 · defined in src/app/app_settings.cpp:54

window_state()¶

QByteArray window_state() const

Returns the saved toolbar and dock layout (key window/state).

Returns QByteArray: The bytes of QMainWindow::saveState; empty before the window was first closed, which makes QMainWindow::restoreState fail and the window lay out its docks for a first start.

Declared in src/app/app_settings.hpp:73 · defined in src/app/app_settings.cpp:58

save_window()¶

void save_window(const QByteArray& geometry, const QByteArray& state)

Stores the window geometry and the dock layout (keys window/geometry and window/state).

Parameters

Name	Type	Description
`geometry`	`const QByteArray&`	The bytes of `QWidget::saveGeometry`.
`state`	`const QByteArray&`	The bytes of `QMainWindow::saveState`.

Declared in src/app/app_settings.hpp:79 · defined in src/app/app_settings.cpp:62

autostart()¶

bool autostart() const

Returns whether the simulation starts as soon as the window opens (key simulation/autostart).

Returns bool: The stored flag; false when it was never set.

Declared in src/app/app_settings.hpp:85 · defined in src/app/app_settings.cpp:67

set_autostart()¶

void set_autostart(bool enabled)

Stores whether the simulation starts as soon as the window opens (key simulation/autostart).

Parameters

Name	Type	Description
`enabled`	`bool`	True to start on launch.

Declared in src/app/app_settings.hpp:90 · defined in src/app/app_settings.cpp:71

map_online()¶

bool map_online() const

Returns whether missing map tiles are downloaded (key map/online).

Returns bool: The stored flag; true when it was never set, so a first start downloads the tiles it shows.

Declared in src/app/app_settings.hpp:96 · defined in src/app/app_settings.cpp:75

set_map_online()¶

void set_map_online(bool online)

Stores whether missing map tiles are downloaded (key map/online).

Parameters

Name	Type	Description
`online`	`bool`	True to download, false to use the tiles on disk only.

Declared in src/app/app_settings.hpp:100 · defined in src/app/app_settings.cpp:79

map_tile_url()¶

QString map_tile_url() const

Returns the tile server URL template (key map/tile_url).

The application has no control for this key; it is edited in the settings store.

Returns QString: A URL with {z}, {x} and {y} placeholders; empty when it was never set, in which case the tile cache keeps its OpenStreetMap default.

Declared in src/app/app_settings.hpp:107 · defined in src/app/app_settings.cpp:83

set_map_tile_url()¶

void set_map_tile_url(const QString& url)

Stores the tile server URL template (key map/tile_url).

Parameters

Name	Type	Description
`url`	`const QString&`	A URL with `{z}`, `{x}` and `{y}` placeholders; empty returns to the OpenStreetMap server at the next start.

Declared in src/app/app_settings.hpp:112 · defined in src/app/app_settings.cpp:87

map_tile_attribution()¶

std::optional<QString> map_tile_attribution() const

Returns the attribution the map draws for the tile server (key map/tile_attribution).

The application has no control for this key; it is edited in the settings store, usually together with map/tile_url.

Returns std::optional<QString>: The stored text, empty to draw no attribution; std::nullopt when the key was never set, in which case the map credits OpenStreetMap for the OpenStreetMap tile servers and draws nothing for any other server (see map::default_attribution).

Declared in src/app/app_settings.hpp:121 · defined in src/app/app_settings.cpp:91

set_map_tile_attribution()¶

void set_map_tile_attribution(const std::optional<QString>& attribution)

Stores the attribution the map draws for the tile server (key map/tile_attribution).

Parameters

Name	Type	Description
`attribution`	`const std::optional<QString>&`	Text to draw, empty to draw none; `std::nullopt` removes the key, so that the map returns to its default at the next start.

Declared in src/app/app_settings.hpp:126 · defined in src/app/app_settings.cpp:98

map_zoom()¶

double map_zoom() const

Returns the map zoom level of the last session (key map/zoom).

Returns double: A fractional slippy map zoom level as stored, not checked here; 12 when it was never set or is not a finite number. A whole level stored by earlier versions reads as that level. The map clamps it to its range of [1, 19].

Declared in src/app/app_settings.hpp:132 · defined in src/app/app_settings.cpp:106

set_map_zoom()¶

void set_map_zoom(double zoom)

Stores the map zoom level (key map/zoom).

Parameters

Name	Type	Description
`zoom`	`double`	A fractional slippy map zoom level, stored unchecked.

Declared in src/app/app_settings.hpp:136 · defined in src/app/app_settings.cpp:112

map_cache_directory()¶

QString map_cache_directory() const

Returns the directory chosen for the map tile cache (key map/cache_directory).

The application has no control for this key; it is edited in the settings store. The tests set it to a temporary directory.

Returns QString: The directory as stored, under which tile_cache_directory keeps its tiles sub-directory; empty when it was never set, in which case the platform's cache directory is used.

Declared in src/app/app_settings.hpp:145 · defined in src/app/app_settings.cpp:116

set_map_cache_directory()¶

void set_map_cache_directory(const QString& directory)

Stores the directory for the map tile cache (key map/cache_directory).

Takes effect at the next start, when MainWindow opens the tile cache.

Parameters

Name	Type	Description
`directory`	`const QString&`	An existing or creatable directory, stored unchecked; empty returns to the platform's cache directory.

Declared in src/app/app_settings.hpp:152 · defined in src/app/app_settings.cpp:120

theme()¶

QString theme() const

Returns the look chosen under View → Theme (key appearance/theme).

Returns QString: system, night or day as stored; night when it was never set. Any other stored text is returned as is and read as night by theme::mode_from_string.

Declared in src/app/app_settings.hpp:158 · defined in src/app/app_settings.cpp:124

set_theme()¶

void set_theme(const QString& theme)

Stores the look chosen under View → Theme (key appearance/theme).

Parameters

Name	Type	Description
`theme`	`const QString&`	`system`, `night` or `day`, as `theme::to_string` writes them; stored unchecked.

Declared in src/app/app_settings.hpp:163 · defined in src/app/app_settings.cpp:128

Public static member functions¶

profiles_directory()¶

static QString profiles_directory()

Returns the directory the profile dialogs offer by default, creating it when missing.

Returns QString: The profiles sub-directory of the application's configuration directory (QStandardPaths::AppConfigLocation). A failure to create it is ignored; the path is returned anyway.

Declared in src/app/app_settings.hpp:170 · defined in src/app/app_settings.cpp:142

tile_cache_directory()¶

static QString tile_cache_directory()

Returns the directory where downloaded map tiles are kept, creating it when missing.

Reads map/cache_directory from the settings store of the application and organisation names set at the time of the call.

Returns QString: The tiles sub-directory of map/cache_directory when that key is set, else of the application's cache directory (QStandardPaths::CacheLocation), on Linux ~/.cache/NMEASimulatorX/NMEASimulatorX/tiles. The tiles level keeps Clear map tile cache, which deletes this directory, away from the other contents of a chosen directory. A failure to create it is ignored; the path is returned anyway.

Declared in src/app/app_settings.hpp:182 · defined in src/app/app_settings.cpp:132

resolve_profile_path()¶

static QString resolve_profile_path(const QString& profile_directory, const QString& path)

Returns the absolute path that a file path of a profile names.

The file dialogs use it, so that they find a file named relative to the profile file where SimulationRunner finds it.

Parameters

Name	Type	Description
`profile_directory`	`const QString&`	The directory that the relative paths of the profile are relative to, `io::Profile::base_directory`; empty for a profile without a file, whose relative paths are relative to the working directory.
`path`	`const QString&`	A track, log or output file path as written in the profile; may be empty.

Returns QString: path made absolute against profile_directory and cleaned; empty when path is empty.

Declared in src/app/app_settings.hpp:194 · defined in src/app/app_settings.cpp:149

dialog_directory()¶

static QString dialog_directory(const QString& profile_directory, const QString& path)

Returns the folder that a file dialog for a file path of a profile starts in.

Parameters

Name	Type	Description
`profile_directory`	`const QString&`	As for `resolve_profile_path`.
`path`	`const QString&`	As for `resolve_profile_path`.

Returns QString: The folder that contains the path resolved by resolve_profile_path, whether or not it exists; the documents folder (QStandardPaths::DocumentsLocation) when path is empty.

Declared in src/app/app_settings.hpp:203 · defined in src/app/app_settings.cpp:157

Private data members¶

settings_¶

QSettings settings_

The native settings store of the application, opened by the default QSettings constructor from the organisation and application names.

Declared in src/app/app_settings.hpp:209