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::resizeEvent(Tui::ZResizeEvent *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::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 signals 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.