Commands

Tui Widgets uses commands to decouple user interface elements from application logic.

A command is identifed by a Tui::ZSymbol.

The two main classes of the command system are Tui::ZCommandManager and Tui::ZCommandNotifier.

User interface elements get the command manager instance from a suitable Tui::ZWidget and use it to get information about the command (e.g. if it is currently enabled) and to trigger the command.

Application code creates a Tui::ZCommandNotifier instance with a parent in the widget hierarchy to interact with the command system. It can then set the enabled state of the command and bind to the activated signal.

ZCommandNotifier

class Tui::ZCommandNotifier : public QObject

ZCommandNotifier is not copyable or movable. It does not define comparision operators.

ZCommandNotifier creates a command (potentially local to a widget or window). The void activated() signal must be connected to define what the command does.

Constructors

explicit ZCommandNotifier(ZImplicitSymbol command, QObject *parent, Tui::ShortcutContext context = Tui::ApplicationShortcut)

Creates a ZCommandNotifier instance for command command. The command notifier will be active for commands triggered in the context context relative to parent.

Functions

ZSymbol command() const

Returns the command this notifier is bound to.

Tui::ShortcutContext context() const

Returns the context in from which this command can be triggered.

bool isEnabled() const

void setEnabled(bool s)

If a command notifier is not enabled the command will not be activated and the corrosponding user interface elements might be shown in disabled state.

bool isContextSatisfied() const

Returns true if the currently focused widget satisfies the context of this command notifier.

The return value can be a bit out of date, as it is cached and is updated when e.g. focus changes or the just before painting.

Signals

void activated()

This signal is emitted when the command was activated by some user interface element.

void enabledChanged(bool s)

This signal is emitted when the compound value of the enabled status combined (by logical and) the value of isContextSatisfied() const changes.

As the value of isContextSatisfied is cached and only updated at specific events this signal can be emitted with a delay relative to the time when the change happens.

ZCommandManager

class Tui::ZCommandManager : public QObject

ZCommandManager is not copyable or movable. It does not define comparision operators.

ZCommandManager is used to implement widgets that display and trigger commands. It is also used in the implementation of Tui::ZCommandNotifier.

void registerCommandNotifier(ZCommandNotifier *notifier)

void deregisterCommandNotifier(ZCommandNotifier *notifier)

Used internally in Tui::ZCommandNotifier.

bool isCommandEnabled(ZSymbol command) const

Queries the effective enabled state of a command.

The state depends on the currently focused widget and on the state of the Tui::ZCommandNotifier instances for the command command.

void activateCommand(ZSymbol command)

Activates the command command if possible.

Which (if any) Tui::ZCommandNotifier instance is triggered depends on the currently focused widget and on the state of the applicable instance.

commandStateChanged(ZSymbol command)

This signal is emitted when the effective state of command command changes.