DashboardWidget¶

class nmeasim::app::DashboardWidget · Applications

The instruments: a compass rose and a wind dial with the position, time and GNSS tiles on top, the grid of digital tiles below.

Inherits QWidget

Declared in src/app/widgets/dashboard_widget.hpp (line 122)

Displays the vessel state and lets the operator override values. The whole dashboard scrolls when the window is too small for it.

Tiles with an override control, their units and ranges, and the parameter each drives:

Heading, °T, [0, 359.9], core::simulation::Parameter::HeadingTrue;
Speed over ground, kn, [0, 999.9], Parameter::SpeedOverGround;
Speed through water, kn, [0, 999.9], Parameter::SpeedThroughWater;
Rudder, degrees positive to starboard, within the profile's rudder limit (see set_rudder_limit, [-35, 35] by default), Parameter::RudderAngle;
Depth, m below the transducer, [0, 99999.9], Parameter::Depth;
Water temperature, °C, [-5, 60], Parameter::WaterTemperature;
Altitude, m, [-500, 20000], Parameter::Altitude;
True wind direction, °T the wind comes from, [0, 359.9], Parameter::WindDirectionTrue;
True wind speed, kn, [0, 200], Parameter::WindSpeedTrue.

The display-only tiles are Position, Time (UTC), Course over ground (°T), Rate of turn (°/min, positive to starboard), Apparent wind (angle off the bow to port or starboard, as format_wind_angle writes it, and speed) and Destination. The GNSS tile carries a Fix check box and a Satellites spin box in [0, 12]; the Engines group holds one EngineTile per engine. Every child widget is owned by the dashboard through Qt parents.

See also

docs/reference/desktop-app.md, sections "Dashboard instruments" and "Dashboard tiles".

Summary¶

Public member functions

Name	Description
`DashboardWidget()`	Builds the dashboard with no engines, steering mode off and overrides enabled.
`update_state()`	Refreshes every tile from a state snapshot.
`sync_overrides()`	Reflects the current overrides of a source in the controls.
`set_steering_mode()`	Switches the controls between heading and rudder steering.
`set_overrides_enabled()`	Enables or disables every override control, for example while a track or a log drives the vessel and overrides would have no effect.
`set_rudder_limit()`	Limits the Rudder override to the rudder limit of a profile.
`overrides_enabled()`	Returns whether the override controls are enabled.
`engine_count()`	Returns the number of engine tiles.
`engine_tile()`	Returns one engine tile.
`destination_text()`	Returns the text of the Destination tile.
`apparent_wind_text()`	Returns the text of the Apparent wind tile.
`control()`	Returns the tile with the override control of a parameter.
`compass_dial()`	Returns the compass rose.
`wind_dial()`	Returns the wind dial.

Signals

Name	Description
`override_changed()`	Emitted when the operator ticks or unticks the override of a tile, or changes its value while the override is active.
`fix_changed()`	Emitted when the operator ticks or unticks the Fix check box.
`satellites_changed()`	Emitted when the operator changes the Satellites spin box.
`engine_changed()`	The operator changed an engine on its tile.

Private member functions

Name	Description
`add_tile()`	Creates a display-only tile and places it in the grid.
`dial_panel()`	A framed panel with a caption around a dial.
`sync_engines()`	Rebuilds the engine tiles when the number or the labels of the engines change.
`add_controllable()`	Creates a tile with an override control, connects it to `override_changed` and registers it in `controls_`.

Private data members

Name	Description
`content_`	Widget inside the scroll area that holds everything else; owned by the scroll area.
`grid_`	Grid of the digital tiles, three columns wide; owned by the content layout.
`compass_`	Compass rose; owned by its dial panel.
`wind_`	Wind dial; owned by its dial panel.
`controls_`	Tiles with an override control, one per `core::simulation::Parameter`.
`position_tile_`	`Position` in degrees and decimal minutes, on two lines.
`time_tile_`	Simulated clock in UTC.
`course_tile_`	Course over ground, °T.
`rate_of_turn_tile_`	Rate of turn, °/min, positive to starboard.
`apparent_wind_tile_`	Apparent wind angle off the bow, to port or starboard, and speed in knots.
`destination_tile_`	Destination summary, or `None` without a destination; spans the grid's width.
`gnss_tile_`	Fix state, satellites in use and HDOP, with the Fix and Satellites controls.
`engines_row_`	Layout of the Engines group, ending in a stretch after the tiles.
`engines_`	Engine tiles in engine order, owned by the Engines group.
`fix_check_`	Fix check box on the GNSS tile.
`satellites_spin_`	Satellites spin box on the GNSS tile, [0, 12].
`suppress_signals_`	True inside `update_state`, so that programmatic changes emit no signal.
`overrides_enabled_`	Whether the controls are enabled; see `set_overrides_enabled`.
`steering_mode_`	Whether steering mode is on; see `set_steering_mode`.

Public member functions¶

DashboardWidget()¶

explicit DashboardWidget(QWidget* parent = nullptr)

Builds the dashboard with no engines, steering mode off and overrides enabled.

Parameters

Name	Type	Description
`parent`	`QWidget*`	Parent widget, which owns the dashboard; may be null, in which case the caller owns it.

Declared in src/app/widgets/dashboard_widget.hpp:130 · defined in src/app/widgets/dashboard_widget.cpp:136

update_state()¶

void update_state(const core::model::VesselState& state)

Refreshes every tile from a state snapshot.

Tiles with an active override keep their control value.

The readouts, the dials, the Fix check box and the engine tiles follow the state; the Satellites spin box does too unless it has the keyboard focus. The engine tiles are rebuilt when the number or the labels of the engines changed. With a destination the compass shows the bearing to it and the Destination tile its name, bearing, distance and cross-track error in nautical miles with the side to steer. Emits no signal.

Parameters

Name	Type	Description
`state`	`const core::model::VesselState&`	The state to show; not kept.

Declared in src/app/widgets/dashboard_widget.hpp:142 · defined in src/app/widgets/dashboard_widget.cpp:318

sync_overrides()¶

void sync_overrides(const core::simulation::DeltaSource& source)

Reflects the current overrides of a source in the controls.

Each override control is ticked when its parameter is overridden and shows the pinned value, or the current simulated value when it is not. Emits no signal. The main window calls it after keyboard nudges, steering changes and loading a profile.

Parameters

Name	Type	Description
`source`	`const core::simulation::DeltaSource&`	The delta source whose overrides to show; not kept.

Declared in src/app/widgets/dashboard_widget.hpp:150 · defined in src/app/widgets/dashboard_widget.cpp:381

set_steering_mode()¶

void set_steering_mode(bool enabled)

Switches the controls between heading and rudder steering.

In steering mode the Rudder override control is enabled and the Heading one disabled; outside it the reverse. Neither is enabled while overrides are disabled.

Parameters

Name	Type	Description
`enabled`	`bool`	True for steering mode.

Declared in src/app/widgets/dashboard_widget.hpp:157 · defined in src/app/widgets/dashboard_widget.cpp:419

set_overrides_enabled()¶

void set_overrides_enabled(bool enabled)

Enables or disables every override control, for example while a track or a log drives the vessel and overrides would have no effect.

Covers the override controls, the Fix and Satellites controls and the engine tiles, and then applies the steering mode again.

Parameters

Name	Type	Description
`enabled`	`bool`	False to grey out every control.

Declared in src/app/widgets/dashboard_widget.hpp:165 · defined in src/app/widgets/dashboard_widget.cpp:425

set_rudder_limit()¶

void set_rudder_limit(double max_rudder_angle_deg)

Limits the Rudder override to the rudder limit of a profile.

The simulation clamps the rudder to the same limit, so the control never holds an angle the simulation does not use; its tooltip names the limit. The main window calls it when it applies a profile.

Parameters

Name	Type	Description
`max_rudder_angle_deg`	`double`	Largest rudder angle either side, in degrees, as `core::simulation::DeltaConfig::max_rudder_angle_deg`; positive.

Declared in src/app/widgets/dashboard_widget.hpp:174 · defined in src/app/widgets/dashboard_widget.cpp:270

overrides_enabled()¶

bool overrides_enabled() const noexcept

Returns whether the override controls are enabled.

Returns bool: The value last passed to set_overrides_enabled, true initially.

Declared in src/app/widgets/dashboard_widget.hpp:178

engine_count()¶

int engine_count() const noexcept

Returns the number of engine tiles.

Returns int: One per engine of the last state shown.

Declared in src/app/widgets/dashboard_widget.hpp:183

engine_tile()¶

EngineTile* engine_tile(int index) const

Returns one engine tile.

Parameters

Name	Type	Description
`index`	`int`	Engine index, from 0.

Returns EngineTile*: The tile, owned by the dashboard and valid until the engines are rebuilt by update_state; null when index is out of range.

Declared in src/app/widgets/dashboard_widget.hpp:189 · defined in src/app/widgets/dashboard_widget.cpp:253

destination_text()¶

QString destination_text() const

Returns the text of the Destination tile.

Returns QString: The destination summary, or None (translated) without a destination.

Declared in src/app/widgets/dashboard_widget.hpp:193 · defined in src/app/widgets/dashboard_widget.cpp:258

apparent_wind_text()¶

QString apparent_wind_text() const

Returns the text of the Apparent wind tile.

Returns QString: The angle off the bow, as format_wind_angle writes it, and the speed, for example 104°P at 8.7 kn; -- before the first update_state.

Declared in src/app/widgets/dashboard_widget.hpp:198 · defined in src/app/widgets/dashboard_widget.cpp:262

control()¶

InstrumentTile* control(core::simulation::Parameter parameter) const

Returns the tile with the override control of a parameter.

Parameters

Name	Type	Description
`parameter`	`core::simulation::Parameter`	`Parameter` the tile drives.

Returns InstrumentTile*: The tile, owned by the dashboard; never null, as every core::simulation::Parameter has one.

Declared in src/app/widgets/dashboard_widget.hpp:204 · defined in src/app/widgets/dashboard_widget.cpp:266

compass_dial()¶

CompassDial* compass_dial() const noexcept

Returns the compass rose.

Returns CompassDial*: The dial, owned by the dashboard; never null.

Declared in src/app/widgets/dashboard_widget.hpp:208

wind_dial()¶

WindDial* wind_dial() const noexcept

Returns the wind dial.

Returns WindDial*: The dial, owned by the dashboard; never null.

Declared in src/app/widgets/dashboard_widget.hpp:212

Signals¶

override_changed()¶

void override_changed(nmeasim::core::simulation::Parameter parameter, bool active, double value)

Emitted when the operator ticks or unticks the override of a tile, or changes its value while the override is active.

The main window calls core::simulation::DeltaSource::set_override when active is true and core::simulation::DeltaSource::clear_override otherwise. Not emitted from sync_overrides or update_state.

Parameters

Name	Type	Description
`parameter`	`nmeasim::core::simulation::Parameter`	The parameter the tile controls.
`active`	`bool`	True to pin the parameter, false to release it.
`value`	`double`	Value of the control, in the parameter's unit.

Declared in src/app/widgets/dashboard_widget.hpp:225

fix_changed()¶

void fix_changed(bool has_fix)

Emitted when the operator ticks or unticks the Fix check box.

The main window passes it to core::simulation::DeltaSource::set_fix. Not emitted from update_state.

Parameters

Name	Type	Description
`has_fix`	`bool`	True when the box is ticked.

Declared in src/app/widgets/dashboard_widget.hpp:233

satellites_changed()¶

void satellites_changed(int in_use)

Emitted when the operator changes the Satellites spin box.

The main window passes it to core::simulation::DeltaSource::set_satellites, keeping the satellites in view. Not emitted from update_state.

Parameters

Name	Type	Description
`in_use`	`int`	Satellites used in the fix, in [0, 12].

Declared in src/app/widgets/dashboard_widget.hpp:240

engine_changed()¶

void engine_changed(int index, const nmeasim::core::model::Engine& engine)

The operator changed an engine on its tile.

Emitted whenever an EngineTile emits EngineTile::changed. The main window passes it to core::simulation::DeltaSource::set_engine.

Parameters

Name	Type	Description
`index`	`int`	Engine index, from 0.
`engine`	`const nmeasim::core::model::Engine&`	The engine as the tile now describes it.

Declared in src/app/widgets/dashboard_widget.hpp:248

Private member functions¶

add_tile()¶

InstrumentTile* add_tile(const QString& title, const QString& unit, int row, int column)

Creates a display-only tile and places it in the grid.

Parameters

Name	Type	Description
`title`	`const QString&`	Caption of the tile.
`unit`	`const QString&`	Unit next to the readout; empty for none.
`row`	`int`	Grid row, from 0.
`column`	`int`	Grid column, from 0 to 2.

Returns InstrumentTile*: The tile, owned by the dashboard's content widget.

Declared in src/app/widgets/dashboard_widget.hpp:258 · defined in src/app/widgets/dashboard_widget.cpp:277

dial_panel()¶

QFrame* dial_panel(const QString& title, QWidget* dial)

A framed panel with a caption around a dial.

Parameters

Name	Type	Description
`title`	`const QString&`	Caption above the dial.
`dial`	`QWidget*`	The dial; reparented to the panel and given a minimum size of 200 by 200 pixels.

Returns QFrame*: The panel, owned by the dashboard's content widget.

Declared in src/app/widgets/dashboard_widget.hpp:265 · defined in src/app/widgets/dashboard_widget.cpp:284

sync_engines()¶

void sync_engines(const std::vector<core::model::Engine>& engines)

Rebuilds the engine tiles when the number or the labels of the engines change.

Old tiles are deleted later from the event loop; new ones start editable when overrides are enabled.

Parameters

Name	Type	Description
`engines`	`const std::vector<core::model::Engine>&`	The engines of the state being shown.

Declared in src/app/widgets/dashboard_widget.hpp:272 · defined in src/app/widgets/dashboard_widget.cpp:229

add_controllable()¶

InstrumentTile* add_controllable(
    core::simulation::Parameter parameter,
    const QString& title,
    const QString& unit,
    int row,
    int column,
    double minimum,
    double maximum,
    double step,
    int decimals)

Creates a tile with an override control, connects it to override_changed and registers it in controls_.

Parameters

Name	Type	Description
`parameter`	`core::simulation::Parameter`	The parameter the control drives.
`title`	`const QString&`	Caption of the tile.
`unit`	`const QString&`	Unit next to the readout.
`row`	`int`	Grid row, from 0.
`column`	`int`	Grid column, from 0 to 2.
`minimum`	`double`	Smallest override value, in the unit.
`maximum`	`double`	Largest override value, in the unit.
`step`	`double`	Spin box step, in the unit.
`decimals`	`int`	Decimals of the spin box.

Returns InstrumentTile*: The tile, owned by the dashboard's content widget.

Declared in src/app/widgets/dashboard_widget.hpp:286 · defined in src/app/widgets/dashboard_widget.cpp:304

Private data members¶

content_¶

QWidget* content_

Widget inside the scroll area that holds everything else; owned by the scroll area.

Declared in src/app/widgets/dashboard_widget.hpp:291

grid_¶

QGridLayout* grid_

Grid of the digital tiles, three columns wide; owned by the content layout.

Declared in src/app/widgets/dashboard_widget.hpp:293

compass_¶

CompassDial* compass_

Compass rose; owned by its dial panel.

Declared in src/app/widgets/dashboard_widget.hpp:295

wind_¶

WindDial* wind_

Wind dial; owned by its dial panel.

Declared in src/app/widgets/dashboard_widget.hpp:297

controls_¶

std::map<core::simulation::Parameter, InstrumentTile *> controls_

Tiles with an override control, one per core::simulation::Parameter.

Declared in src/app/widgets/dashboard_widget.hpp:299

position_tile_¶

InstrumentTile* position_tile_

Position in degrees and decimal minutes, on two lines.

Declared in src/app/widgets/dashboard_widget.hpp:301

time_tile_¶

InstrumentTile* time_tile_

Simulated clock in UTC.

Declared in src/app/widgets/dashboard_widget.hpp:303

course_tile_¶

InstrumentTile* course_tile_

Course over ground, °T.

Declared in src/app/widgets/dashboard_widget.hpp:305

rate_of_turn_tile_¶

InstrumentTile* rate_of_turn_tile_

Rate of turn, °/min, positive to starboard.

Declared in src/app/widgets/dashboard_widget.hpp:307

apparent_wind_tile_¶

InstrumentTile* apparent_wind_tile_

Apparent wind angle off the bow, to port or starboard, and speed in knots.

Declared in src/app/widgets/dashboard_widget.hpp:309

destination_tile_¶

InstrumentTile* destination_tile_

Destination summary, or None without a destination; spans the grid's width.

Declared in src/app/widgets/dashboard_widget.hpp:311

gnss_tile_¶

InstrumentTile* gnss_tile_

Fix state, satellites in use and HDOP, with the Fix and Satellites controls.

Declared in src/app/widgets/dashboard_widget.hpp:313

engines_row_¶

QHBoxLayout* engines_row_

Layout of the Engines group, ending in a stretch after the tiles.

Declared in src/app/widgets/dashboard_widget.hpp:315

engines_¶

std::vector<EngineTile *> engines_

Engine tiles in engine order, owned by the Engines group.

Declared in src/app/widgets/dashboard_widget.hpp:317

fix_check_¶

QCheckBox* fix_check_

Fix check box on the GNSS tile.

Declared in src/app/widgets/dashboard_widget.hpp:319

satellites_spin_¶

QSpinBox* satellites_spin_

Satellites spin box on the GNSS tile, [0, 12].

Declared in src/app/widgets/dashboard_widget.hpp:321

suppress_signals_¶

bool suppress_signals_{false}

True inside update_state, so that programmatic changes emit no signal.

Declared in src/app/widgets/dashboard_widget.hpp:323

overrides_enabled_¶

bool overrides_enabled_{true}

Whether the controls are enabled; see set_overrides_enabled.

Declared in src/app/widgets/dashboard_widget.hpp:325

steering_mode_¶

bool steering_mode_{false}

Whether steering mode is on; see set_steering_mode.

Declared in src/app/widgets/dashboard_widget.hpp:327