# Events

Tui Widgets is an event driven framework. Events are deliviered primarily to instances of `Tui::ZWidget` but are also delivered to other classes derived from `QObject`.

Classes either override virtual functions for specific events (like `Tui::ZWidget::paintEvent()`) or override `QObject::event` and manually dispatching on the event type.

Tui Widgets defines its own event types and also reuses some event types from Qt.

class Tui::ZEventType

Events are identified by `QEvent::Type` values. Tui Widgets defines getter for the type values for its events. The Tui Widgets event types are:

Tui::ZEventType::paint()

  Requests a widget to paint itself (`Tui::ZPaintEvent`).

  Widgets can override `void Tui::ZWidget::paintEvent(Tui::ZPaintEvent *event)` to handle this event.

  The widgets can get the `Tui::ZPainter` instance for painting by calling the `Tui::ZPainter *Tui::ZPaintEvent::painter() const` function.

Tui::ZEventType::key()

  Signals a key press that the widget may handle (`Tui::ZKeyEvent`).

  Widgets can override `void Tui::ZWidget::keyEvent(Tui::ZKeyEvent *event)` to handle this event.

  A key event is either a character or a non character key.

  In case of a character the application can get the pressed character by reading `QString Tui::ZKeyEvent::text() const`. The function might return multiple unicode code points in the future for languages with clusters of multiple codepoints.

  In case of a non character key the application can get the key by reading `int Tui::ZKeyEvent::key() const`.

  Only on of these are meaningful at a given time. The other will be `Tui::Key_unknown` or the empty string.

  In both cases the application can get the modifier keys pressed when the key input happend by reading `Tui::KeyboardModifiers Tui::ZKeyEvent::modifiers() const`.

  Tui Widgets sends the key events in the accepted state (see `QEvent::isAccepted`). If the application passes the handling of the key event to the default implementations of `void Tui::ZWidget::keyEvent(Tui::ZKeyEvent *event)` and `void Tui::ZWidget::event(QEvent *event)` the accepted flag will be cleared.

  If a key event, that is dispatched to the focused widget, is not in the accepted state after dispatching to a ZWidget, it will bubble through all parents of the widget until reaching the root. It will be dispatched to each widget on the way until a widget accepts it.

  Widgets can also receive key events if they currently have the keyboard grab (see `void Tui::ZWidget::grabKeyboard()`), in this case the event will not bubble toward the root.

Tui::ZEventType::paste()

  Signals a clipboard paste that the widget may handle (`Tui::ZPasteEvent`).

  Widgets can override `void Tui::ZWidget::pasteEvent(Tui::ZPasteEvent *event)` to handle this event.

  The widget can get the pasted text by calling `QString Tui::ZPasteEvent::text() const`.

  Tui Widgets sends the paste events in the accepted state (see `QEvent::isAccepted`). If the application passes the handling of the paste event to the default implementations of `void Tui::ZWidget::pasteEvent(Tui::ZPasteEvent *event)` and `void Tui::ZWidget::event(QEvent *event)` the accepted flag will be cleared.

  If a paste event, that is dispatched to the focused widget, is not in the accepted state after dispatching to a ZWidget, it will bubble through all parents of the widget until reaching the root. It will be dispatched to each widget on the way until a widget accepts it.

  Widgets can also receive paste events if they currently have the keyboard grab (see `void Tui::ZWidget::grabKeyboard()`), in this case the event will not bubble toward the root.

Tui::ZEventType::queryAcceptsEnter()

  Queries if a widget will handle the `Enter` key (`QEvent`).

  If it will handle the key it should accept the event. This is used to determine the visual state of default widgets (i.e. default buttons) that react to `Enter`.

Tui::ZEventType::focusIn()

  Informs a widget that it gained keyboard focus (`Tui::ZFocusEvent`).

  Widgets can override `void Tui::ZWidget::focusInEvent(Tui::ZFocusEvent *event)` to handle this event.

  The widget can query the focus reason using `Tui::FocusReason Tui::ZFocusEvent::reason() const`

Tui::ZEventType::focusOut()

  Informs a widget that it lost keyboard focus (`Tui::ZFocusEvent`).

  Widgets can override `void Tui::ZWidget::focusOutEvent(Tui::ZFocusEvent *event)` to handle this event.

  The widget can query the focus reason using `Tui::FocusReason Tui::ZFocusEvent::reason() const`

Tui::ZEventType::move()

  Informs a widget that its position relative to its parents has changed (`Tui::ZMoveEvent`).

  Widgets can override `void Tui::ZWidget::moveEvent(Tui::ZMoveEvent *event)` to handle this event.

  The widget can query the previous position using `QPoint Tui::ZMoveEvent::oldPos() const` and the new position using `QPoint Tui::ZMoveEvent::pos() const`.

Tui::ZEventType::resize()

  Informs a widget that its size has changed (`Tui::ZResizeEvent`).

  Widgets can override `void Tui::ZWidget::resizeEvent(Tui::ZResizeEvent *event)` to handle this event.

  The widget can query the previous size using `QSize Tui::ZResizeEvent::oldSize() const` and the new size using `QSize Tui::ZResizeEvent::size() const`.

Tui::ZEventType::otherChange()

  This event is sent to every QObject in widget tree on some changes (`Tui::ZOtherChangeEvent`).

  The application can use `bool Tui::ZOtherChangeEvent::match(const QEvent *event, Tui::ZSymbol changed)` to match the event against a type of change.

Tui::ZEventType::show()

  Informs the widget that it has become visible (`QEvent`).

  See also QEvent::ShowToParent.

Tui::ZEventType::hide()

  Informs the widget that it is no longer visible (`QEvent`).

  See also QEvent::HideToParent.

Tui::ZEventType::terminalChange()

  Informs the widget that its terminal attachment has changed (`QEvent`).

  The new terminal can be queried using `Tui::ZWidget::terminal()`, which on terminal detach will return nullptr and otherwise the newly attached terminal.

Tui::ZEventType::close()

  Used as query to decide if a window should be closed (`Tui::ZCloseEvent`).

  Classes derived from `Tui::ZWindow` can override `void Tui::ZWindow::closeEvent(Tui::ZCloseEvent *event)` to handle this event.

  See the section on the close request protcol for details.

Tui::ZEventType::updateRequest()

  This event is used internally to coordinate the emission of paint events (`Tui::ZPaintEvent`).

Tui::ZEventType::terminalNativeEvent()

  This event is dispatched on `ZTerminal` when processing native events from the low level terminal abstraction library (`Tui::ZTerminalNativeEvent`).

  Applications that need to customize low level terminal handling can intercept it by subclassing ZTerminal or using an event filter.

Tui::ZEventType::rawSequence()

  This event is dispatched on `ZTerminal` while processing terminal input sequences (`Tui::ZRawSequenceEvent`).

  Applications that need to customize low level terminal handling can intercept it by subclassing ZTerminal or using an event filter.

Tui::ZEventType::pendingRawSequence()

  This event is dispatched on `ZTerminal` while processing terminal input sequences that are not completely received yet (`Tui::ZRawSequenceEvent`).

  Applications that need to customize low level terminal handling can intercept it by subclassing ZTerminal or using an event filter.

The following Qt events are used by Tui Widgets:

QEvent::LayoutRequest

  Used in `Tui::ZWidget` and `Tui::ZTerminal` to trigger relayout (`QEvent`).

QEvent::ShowToParent

  Informs a widget that is is now locally visible (`QEvent`).

  If the effective visibility changed the widget will have received a `Tui::ZEventType::show()` event before this event.

QEvent::HideToParent

  Informs a widget that is is no longer locally visible (`QEvent`).

  If the effective visibility changed the widget will have received a `Tui::ZEventType::hide()` event before this event.

QEvent::EnabledChange

  Informs a widget that its enabled state has changed.

  This event is sent whenever the the effective enabled state is changed.

## ZEvent

class Tui::ZEvent : public QEvent

  ZEvent is the base class of all event classes defined by Tui Widgets.

  It is copyable and does not define comparison operators.

  It has no user accessable constructors or functions.

## ZPaintEvent

class Tui::ZPaintEvent : public Tui::ZEvent

  See `Tui::ZEventType::paint()` for usage details.

  ZPaintEvent(Tui::ZPainter *painter)

    Creates a `Tui::ZEventType::paint()` event using the painter `painter`.

  ZPaintEvent(Tui::ZPaintEvent::Update, Tui::ZPainter *painter)

    Creates a `Tui::ZEventType::updateRequest()` event using the painter `painter`.

  Tui::ZPainter *painter() const

    Returns the painter associated with the event.

  class Update
  static constexpr Update update{}

    Used as tag to select the constructor of this class.

## ZKeyEvent

class Tui::ZKeyEvent : public Tui::ZEvent

  See `Tui::ZEventType::key()` for usage details.

  ZKeyEvent(int key, Tui::KeyboardModifiers modifiers, const QString &text)

    Creates a `Tui::ZEventType::key()` event using the key `key`, text `text` and modifiers `modifiers`.

  int key() const

    Returns the key associated with the event.

  QString text() const

    Returns the text associated with the event.

  Tui::KeyboardModifiers modifiers() const

    Returns the modifiers associated with the event.

## ZPasteEvent

class Tui::ZPasteEvent : public Tui::ZEvent

  See `Tui::ZEventType::paste()` for usage details.

  ZPasteEvent(const QString &text)

    Creates a `Tui::ZEventType::key()` event using text `text`.

  QString text() const

    Returns the text associated with the event.

## ZFocusEvent

class Tui::ZFocusEvent : public Tui::ZEvent

  See `Tui::ZEventType::focusIn()` and `Tui::ZEventType::focusOut()` for usage details.

  ZFocusEvent(Tui::ZFocusEvent::FocusIn, Tui::FocusReason reason = Tui::OtherFocusReason)

    Creates a `Tui::ZEventType::focusIn()` event using reason `reason`.

  ZFocusEvent(Tui::ZFocusEvent::FocusOut, Tui::FocusReason reason = Tui::OtherFocusReason)

    Creates a `Tui::ZEventType::focusOut()` event using reason `reason`.

  Tui::FocusReason reason() const

    Returns the focus reason associated with the event.

  class FocusIn
  static constexpr FocusIn focusIn{}
  class FocusOut
  static constexpr FocusOut focusOut{}

    Used as tags to select the constructor of this class.

## ZMoveEvent

class Tui::ZMoveEvent : public Tui::ZEvent

  See `Tui::ZEventType::move()` for usage details.

  ZMoveEvent(QPoint pos, QPoint oldPos)

    Creates a `Tui::ZEventType::move()` event using position `pos` and old position `oldPos`.

  QPoint pos() const

    Returns the position associated with the event.

  QPoint oldPos() const

    Returns the old position associated with the event.

## ZResizeEvent

class Tui::ZResizeEvent : public Tui::ZEvent

  See `Tui::ZEventType::resize()` for usage details.

  ZResizeEvent(QSize size, QSize oldSize)

    Creates a `Tui::ZEventType::resize()` event using size `size` and old size `oldSize`.

  QSize size() const

    Returns the size associated with the event.

  QSize oldSize() const

    Returns the old size associated with the event.

## ZOtherChangeEvent

class Tui::ZOtherChangeEvent : public Tui::ZEvent

  See `Tui::ZEventType::otherChange()` for usage details.

  ZOtherChangeEvent(QSet<Tui::ZSymbol> unchanged)

    Creates a `Tui::ZEventType::otherChange()` event using `unchanged` as set of unchanged symbols.

  QSet<Tui::ZSymbol> unchanged() const

    Returns the set of unchanged symbols associated with the event.

  static QSet<Tui::ZSymbol> all()

    Returns a list of all known change symbols.

  bool match(const QEvent *event, Tui::ZSymbol changed)

    Matches the event `event` against the change symbol `changed`. It is safe to use this with any valid QEvent.

## ZCloseEvent

class Tui::ZCloseEvent : public Tui::ZEvent

  See `Tui::ZEventType::close()` for usage details.

  ZCloseEvent(QStringList skipChecks)

    Creates a `Tui::ZEventType::close()` event using `skipChecks` as list of checks to skip.

  QStringList skipChecks() const

    Returns the list of checks to skip associated with the event.

## ZRawSequenceEvent

class Tui::ZRawSequenceEvent : public Tui::ZEvent

  See `Tui::ZEventType::rawSequence()` and `Tui::ZEventType::pendingRawSequence()` for usage details.

  ZRawSequenceEvent(QByteArray seq)

    Creates a `Tui::ZEventType::rawSequence()` event using `seq` as sequence.

  ZRawSequenceEvent(Pending, QByteArray seq)

    Creates a `Tui::ZEventType::pendingRawSequence()` event using `seq` as sequence.

  QByteArray sequence() const

    Returns the sequence associated with the event.

  class Pending
  static constexpr Pending pending{}

    Used as tag to select the constructor of this class.

## ZTerminalNativeEvent

class Tui::ZTerminalNativeEvent : public Tui::ZEvent

  See `Tui::ZEventType::terminalNativeEvent()` for usage details.

  ZTerminalNativeEvent(void *native)

    Initializes native pointer to `native`.

  void *nativeEventPointer() const

    Returns a pointer to the native terminal event.

    Currently it returns a pointer to a `termpaint_event`.