# 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.