ZWidget

ZWidget is the base class of all widgets in Tui Widgets.

It defines the common state and behavior of widgets. Applications typically use derived classes as visual elements. Applications can define custom widgets be defining classes that inherit from ZWidget.

Size, Position and Visibility

The root widget of a widget tree needs to be connected to a Tui::ZTerminal instance using the setMainWidget(ZWidget *w) function. Its position is fixed to cover the terminal.

All other widgets have a parent widget and have a position relative to the parent. The position specifies the top-left cell the widget starts in. The widget then expands to the right and down as specified by its width and height.

If a widget is placed outside of its parent the parts that don’t overlap with the parent are not visible. They are clipped.

The widget has a visible property (isLocallyVisible() const, setVisible(bool v)) that determines if it is rendered and is considered for input. If the parent of a widget is not visible the widget itself is not rendered too. The visible property describes the state if the parent is visible. If determine the state that includes the visibility of all parents a widget can be queried for its effective visibility using isVisible() const.

All child widgets that share a parent are organised into a stacking order. When Widgets overlap the widget lower in this order is covered by the widget higher in the stacking order.

Widgets that are newly added to a parent at placed on top of other widgets with the same stacking layer. The stacking layer(setStackingLayer(int layer), stackingLayer() const) allows defining bands in the stacking that can be managed independently. For example to place popup menus or dialogs above normal user interface elements.

Points can be mapped from relative to a given widget to relative to the terminal and back using mapFromTerminal(const QPoint &pos) and mapToTerminal(const QPoint &pos).

Layout and Margins

Widgets can have margins. The margin of a widget defined how much whitespace should be placed around the contents of if. Not all widget classes support marging.

Often it is convinient to have the placement of widgets in a parent automated. This allows exact placement to automatically adapt to changes to the size of the widget and avoids doing position calculations manually or adhoc in the code using the widgets. This automated placement is done by so called “layouts”. Layouts like Tui::ZHBoxLayout and Tui::ZVBoxLayout are classes derived from Tui::ZLayout. Each widget can have one top level layout set using setLayout(ZLayout *l). Then child widgets can be added to that layout (or one of its nested layouts) using layout specific functions.

To customized the layout the functions setMaximumSize(QSize s), setMinimumSize(QSize s), setFixedSize(QSize s), SizePolicy policy) and SizePolicy policy) can be used. They allow specifing how the available space is allocated to the widgets.

Focus

Keyboard input and paste events are processed by the widget that currently has focus. Focus is a per terminal property. The focus can be placed on a widget by calling setFocus().

In a window, focus can be switched by the user using Tab and Shift+Tab. This cycles through visible and enabled widgets that have a focus policy that allows for keyboard focusing.

Tui::ZRoot implements switching focus between windows using F6 and Shift+F6.

Focus order can be setup using setFocusOrder(int order). For widgets with the same focus order value, focus follows the stacking order from bottom to top.

In addition to using the keyboard to move in the focus among the focus order the functions ZWidget *Tui::ZWidget::placeFocus(bool last), ZWidget *Tui::ZWidget::nextFocusable() and ZWidget *Tui::ZWidget::prevFocusable() can be used for focus management.

Widgets optionally can act as focus containers. This modifies how focus inside such widgets is handled.

For widgets that act as windows the focus container mode Tui::FocusContainerMode::Cycle can be used to restrict focus changes by Tab/Shift+Tab and via ZWidget *Tui::ZWidget::nextFocusable()/ZWidget *Tui::ZWidget::prevFocusable() from moving the focus outside of the widget. If the last focusable widget inside the widget marked with the mode was focused last the next widget to focus will be the first focusable widget in the container. Reverse focus movement works respectivly.

To restrict the scope of the effects of the focus order property the focus container mode Tui::FocusContainerMode::SubOrdering can be used.

Widgets can be enabled, that is ready for user interaction, or disabled. Similarily to how visibility works, enabled is a local setting but only is effective when the parent is also effecivly enabled.

Sometimes a widget needs to override focus handling and temporarily route all keyboard input to itself. This can be achieved by initiation of a keyboard grab using grabKeyboard().

Terminal

Widgets only fully work in conjunction with a terminal represented by a Tui::ZTerminal instance. A widget is connected to a terminal if itself is the main widget of a terminal or one of its ancestors is the main widget of a terminal.

Fully functional focus handling depends on the terminal, although unconnected widgets keep a note on calling setFocus(), as a fallback for the special case that a widget tree is constructed before setting the terminal’s main widget. Apart from this minimal support, focus, keyboard grabs, cursor configuration and even text measuring are not available without a terminal.

Usage of widgets

Generally a widget is created with a parent as a constructor parameter and then either manually placed using setGeometry(const QRect &geometry) or placed using a layout.

TODO example

The colors used in the widgets that are part of Tui Widgets are taken from a palette associated with the widget or one of its parents. In some situations the colors can also be influenced by the palette class set on a widget or one of its parents.

When using widgets in a window focus order if determined by void Tui::ZWidget::setFocusOrder(int order), where widgets with the same focus order are reached in order of their z-order from bottom (smaller values) to top (larger values).

Defining custom widgets

While Tui Widgets provides a set of useful widgets for common tasks, there are often situations where a custom widget is a good way to realize a part of the user interface.

Custom widgets are created by subclassing ZWidget. The widget behavior can then be customized by overriding virtual functions.

To customize rendering of the widget override ZPaintEvent *event). To customize input handling override ZKeyEvent *event) and ZPasteEvent *event). Also set the focus policy to receive input.

To customize reactions to changes in widget state use ZFocusEvent *event), ZFocusEvent *event), ZMoveEvent *event) and ZResizeEvent *event) .

Further customization is available using facet(const QMetaObject &metaObject) const, sizeHint() const and minimumSizeHint() const.

It is often useful to setup setPaletteClass(QStringList classes), setContentsMargins(QMargins m), setMinimumSize(QSize s), setMaximumSize(QSize s), setFixedSize(QSize s), setFocusMode(FocusContainerMode mode), FocusPolicy policy), SizePolicy policy), SizePolicy policy) and setStackingLayer(int layer) to a widget specific default in the widget constructor, but these are genereally reserved for customization by the widget user after construction.

ZWidget

class Tui::ZWidget : public QObject

This class is neither copyable nor movable. It does not define comparison operators.

Constructors

Tui::ZWidget::ZWidget(ZWidget *parent = nullptr)

Functions

void addPaletteClass(const QString &clazz)

ZCommandManager *commandManager() const

QMargins contentsMargins() const

QRect contentsRect() const

CursorStyle cursorStyle() const

QSize effectiveMinimumSize() const

QSize effectiveSizeHint() const

ZCommandManager *ensureCommandManager()

virtual QObject *facet(const QMetaObject &metaObject) const

template<typename T> T *findFacet() const

bool focus() const

FocusContainerMode focusMode() const

int focusOrder() const

Tui::FocusPolicy focusPolicy() const

QRect geometry() const

ZColor getColor(const ZImplicitSymbol &x)

void grabKeyboard()

void grabKeyboard(Private::ZMoFunc<void(QEvent*)> handler)

bool isAncestorOf(const ZWidget *child) const

bool isEnabled() const

bool isEnabledTo(const ZWidget *ancestor) const

bool isInFocusPath() const

bool isLocallyEnabled() const

bool isLocallyVisible() const

bool isVisible() const

bool isVisibleTo(const ZWidget *ancestor) const

ZLayout *layout() const

virtual QRect layoutArea() const

void lower()

QPoint mapFromTerminal(const QPoint &pos)

QPoint mapToTerminal(const QPoint &pos)

QSize maximumSize() const

QSize minimumSize() const

virtual QSize minimumSizeHint() const

ZWidget const *nextFocusable() const

ZWidget *nextFocusable()

const ZPalette &palette() const

QStringList paletteClass() const

ZWidget *parentWidget() const

const ZWidget *placeFocus(bool last = false) const

ZWidget *placeFocus(bool last = false)

ZWidget const *prevFocusable() const

ZWidget *prevFocusable()

void raise()

QRect rect() const

void releaseKeyboard()

void removePaletteClass(const QString &clazz)

void resetCursorColor()

virtual ZWidget *resolveSizeHintChain()

int stackingLayer() const

void stackUnder(ZWidget *w)

void setCommandManager(ZCommandManager *cmd)

void setContentsMargins(QMargins m)

void setCursorColor(int r, int b, int g)

void setCursorStyle(CursorStyle style)

void setEnabled(bool e)

void setFixedSize(QSize s)

void setFixedSize(int w, int h)

void setFocus(Tui::FocusReason reason = Tui::OtherFocusReason)

void setFocusMode(FocusContainerMode mode)

void setFocusOrder(int order)

void setFocusPolicy(Tui::FocusPolicy policy)

void setGeometry(const QRect &geometry)

void setLayout(ZLayout *l)

void setMaximumSize(QSize s)

void setMaximumSize(int w, int h)

void setMinimumSize(QSize s)

void setMinimumSize(int w, int h)

void setPalette(const ZPalette &pal)

void setPaletteClass(QStringList classes)

void setParent(ZWidget *newParent)

void setSizePolicyH(Tui::SizePolicy policy)

void setSizePolicyV(Tui::SizePolicy policy)

void setStackingLayer(int layer)

void setVisible(bool v)

void showCursor(QPoint position)

virtual QSize sizeHint() const

Tui::SizePolicy sizePolicyH() const

Tui::SizePolicy sizePolicyV() const

ZTerminal *terminal() const

void update()

void updateGeometry()

Protected Functions

void focusInEvent(Tui::ZFocusEvent *event)

void focusOutEvent(Tui::ZFocusEvent *event)

void keyEvent(Tui::ZKeyEvent *event)

void moveEvent(Tui::ZMoveEvent *event)

void paintEvent(Tui::ZPaintEvent *event)

void pasteEvent(Tui::ZPasteEvent *event)

void resizeEvent(Tui::ZResizeEvent *event)

Members

explicit ZWidget(ZWidget *parent = nullptr)

The constructed widget uses parent as its parent.

ZWidget *parentWidget() const

Returns the QObject parent if it is a widget or nullptr otherwise.

void setParent(ZWidget *newParent)

Sets the QObject parent to parent, updating Tui Widgets bookkeeping as well.

sends QEvent::ParentAboutToChange adjusts focus

Always use ZWidget::setParent instead of QObject::setParent. Otherwise events are not generated and various widget and terminal state is not correctly updated.

QRect geometry() const

void setGeometry(const QRect &geometry)

The geometry of a widget represents the position relative to its parent widget and its size.

QRect rect() const

Returns a QRect representing the whole widget in local coordinates. That is it starts at (0, 0) and has the same width and height as geometry() const.

QRect contentsRect() const

Returns a QRect representing the part of the widget inside the margins in local coordinates.

bool isEnabled() const

bool isLocallyEnabled() const

void setEnabled(bool e)

The enabled state describes if a widget is accepting user interaction. Commonly widgets that are disabled (i.e. not enabled) have a visible difference to their enabled state. Tui Widgets does not send either Tui::ZEventType::key() or Tui::ZEventType::paste() events to disabled widgets.

A widget is enabled if itself and all its parents are enabled. The local enabled state of the widget is availabe by calling isLocallyEnabled and can be changed by setEnabled.

setEnabled only directly effects the state returned by isEnabled if the parent widget’s effectivly enabled state (the return value of isEnabled) was already true.

Only changes to the effective enabled state trigger an event. The event sent is QEvent::EnabledChange.

If a change in the effective enabled state of a focused widget results in it beeing disabled, it looses its focus and the focus is either moved to the next focusable widget or if no such widget exists the focus is removed.

bool isVisible() const

bool isLocallyVisible() const

void setVisible(bool v)

The visiblity of a widget describes if the widget is rendered. Even if a widget is visible according to this property it can still be occluded by a widget higher in the stacking order or be in a position that is not visible to the user.

A widget is visible if itself and all its parents are visible. The local visibility state of the widget is availabe by calling isLocallyVisible and can be changed by setVisibile.

setVisible only directly effects the state returned by isVisible if the parent widget was already visible. Changing the local visibility state can trigger two kinds of events. Changes in the local visibility state trigger the events QEvent::ShowToParent and QEvent::HideToParent. Changes to the effective visibility state (the return value of isVisible) result in delivery of the events Tui::ZEventType::show() and Tui::ZEventType::hide().

If a change in the effective visibility state of a focused widget results in it beeing no longer visible, it looses its focus and the focus is either moved to the next focusable widget or if no such widget exists the focus is removed.

void setStackingLayer(int layer)

int stackingLayer() const

The z-order of widgets is organized into stacking layers. Stacking layers with higher number are higher. In each stacking layer widgets can be moved using raise(), lower() and stackUnder(ZWidget *w). But these functions can not move a widget outside of its stacking layer.

When moving a widget to a different stacking layer it is always placed as the top most widget of the new stacking layer.

void raise()

Move the widget to the top of its stacking layer.

void lower()

Move the widget to the bottom of its stacking layer.

void stackUnder(ZWidget *w)

Adjust z-order of the widget to be just below w. Does not move the widget from its stacking layer.

QSize minimumSize() const

void setMinimumSize(QSize s)

void setMinimumSize(int w, int h)

QSize maximumSize() const

void setMaximumSize(QSize s)

void setMaximumSize(int w, int h)

void setFixedSize(QSize s)

void setFixedSize(int w, int h)

The minimum and maximum size represent contraints for layouting. setFixedSize is just a short form for setting maximum and minimum size to the same value. Direct usage of setGeometry(const QRect &geometry) is not constrained by these properties.

Tui::SizePolicy sizePolicyH() const

void setSizePolicyH(Tui::SizePolicy policy)

Tui::SizePolicy sizePolicyV() const

void setSizePolicyV(Tui::SizePolicy policy)

The size policy of an widget is used by layouts to determine how space is allocated to the widget. See Tui::SizePolicy for details.

QSize sizeHint() const

Returns the calculated size of the widget.

This is used by the layout system when placing the widget.

When implementing widgets, override this to return the preferred size of the widget. The meaning depends on the set size policy.

QSize minimumSizeHint() const

Returns the calculated minimum size of the widget.

QSize effectiveSizeHint() const

QSize effectiveMinimumSize() const

QRect layoutArea() const

Returns a QRect describing the area in the widget that should be used for layouts to place the child widgets.

ZLayout *layout() const

void setLayout(ZLayout *l)

The layout of a widget allows automatically placing child widgets in the widget’s layout area.

If a layout is set it will control the size request of the widget based on the size requests of the widgets in the layout.

See also: ZLayout

void showCursor(QPoint position)

Place the terminal cursor to widget relative position position if possible.

Placing the cursor is possible if:

• If this widget has focus and the keyboard focus is not grabbed, or the widget is the grabbing widget

• The cursor is inside the clipping region of the widget and all its parent widgets.

This function can only be used while handling the void paintEvent(Tui::ZPaintEvent *event) because the cursor position is reset at the start of each rendering cycle.

CursorStyle cursorStyle() const

void setCursorStyle(CursorStyle style)

The cursor style used to display the cursor in this widget. Support of this depends on the terminal’s capabilities.

void resetCursorColor()

void setCursorColor(int r, int b, int g)

The color used to display the cursor in this widget. Support of this depends on the terminal’s capabilities.

The range for r, g, b for setting a cursor color is 0 - 255. A special value of (-1, -1, -1) represents using the terminal default cursor color.

ZTerminal *terminal() const

Returns the terminal this widget is connected to.

void update()

Requests the widget to be redrawn.

When creating a custom widget the implementation must call this function whenever the the visible contents of the widget changes. It should never be needed to call this when just using a widget.

void updateGeometry()

Requests the layouts containing the widgets to be updated.

When creating a custom widget the implementation must call this function whenever properties that influence the layout of this widget or its direct children change. It should never be needed to call this when just using a widget.

void setFocus(Tui::FocusReason reason = Tui::OtherFocusReason)

Requests focus for the widget.

void setFocusPolicy(Tui::FocusPolicy policy)

Tui::FocusPolicy focusPolicy() const

The focus policy determines how this widget can gain focus. If the focus policy contains Tui::TabFocus the widget is focusable by keyboard navigation (i.e. using Tab etc).

Tui::StrongFocus includes Tui::TabFocus.

void setFocusMode(FocusContainerMode mode)

FocusContainerMode focusMode() const

See Tui::FocusContainerMode for details.

void setFocusOrder(int order)

int focusOrder() const

Defines the ordering of the widget in the focus order. Higher values yield a later position in the focus order. If two widgets in the same focus container have the same focus order, their relative z-order is used to determine focus order.

QMargins contentsMargins() const

void setContentsMargins(QMargins m)

Margins allow to add empty space around the contents of a widget.

const ZPalette &palette() const

void setPalette(const ZPalette &pal)

A widgets palette sets or modifies the palette colors for a widget and its decendents.

Usually the root of the widget tree needs a palette that sets up all the standard colors for an application. This is usually done by using Tui::ZRoot as root widget.

Other widgets don’t need to have a palette set, but it can be useful to set a palette for changing colors of specific widgets. In that case the usual way is to retrieve the palette, set some overriding color definitions and set the resulting palette on the widget.

See ZPalette for details.

ZColor getColor(const ZImplicitSymbol &x)

Get a specific palette color named by x.

If the color is not properly defined this function will just return red as an error indicator. Many colors are only defined for widgets that are contained in windows.

This internally uses ZColor Tui::ZPalette::getColor(ZWidget *targetWidget, ZImplicitSymbol x).

QStringList paletteClass() const

void setPaletteClass(QStringList classes)

void addPaletteClass(const QString &clazz)

void removePaletteClass(const QString &clazz)

The list of palette classes modifies which colors are active from the palette.

void grabKeyboard()

void grabKeyboard(Private::ZMoFunc<void(QEvent*)> handler)

void releaseKeyboard()

The keyboard grab allows to temporarily override keyboard focus and redirect input to this widget or to a dedicated event handling closure.

bool isAncestorOf(const ZWidget *child) const

Returns true if child is an ancestor of this widget. If the widget is passed as child it returns true too.

bool isEnabledTo(const ZWidget *ancestor) const

Returns true if all widgets on the path from the widget to ancestor (excluding ancestor, but including the widget) are locally enabled.

bool isVisibleTo(const ZWidget *ancestor) const

Returns true if all widgets on the path from the widget to ancestor (excluding ancestor, but including the widget) are locally visible.

bool focus() const

Returns true if the widget has focus.

bool isInFocusPath() const

Returns true if the widget or any of its descendants has focus.

QPoint mapFromTerminal(const QPoint &pos)

QPoint mapToTerminal(const QPoint &pos)

Map the point pos between local coordinates and terminal coordinates.

ZWidget const *prevFocusable() const

ZWidget *prevFocusable()

ZWidget const *nextFocusable() const

ZWidget *nextFocusable()

Returns the next/previous widget in the focus order or nullptr if no such widget exists.

const ZWidget *placeFocus(bool last = false) const

ZWidget *placeFocus(bool last = false)

Returns the first/last widget in the widget and its decendents that can take focus or nullptr of no such widget exists.

ZWidget *resolveSizeHintChain()

Applications can override this function to customize which widgets are considered linked by chained layouts for layout cycles.

The base implementation considers widgets to be linked to their parent if the parent has a layout set.

Application should only need to override this if they implement automatic widget layouting without using layouts.

void setCommandManager(ZCommandManager *cmd)

ZCommandManager *commandManager() const

The command manager associated with the widget is responsible for connection command and command notifiers.

ZCommandManager *ensureCommandManager()

If no command manager is associated with the widget, sets a new ZCommandManager instance.

It then returns the existing or newly created command manager.

QObject *facet(const QMetaObject &metaObject) const

A facet is a way to add additionals interfaces to a widget without coupeling it to the widget’s implementation class. This is used for example for window related behavior using the ZWindowFacet and for default controls using ZDefaultWidgetManager.

It returns a reference to a class implementing the interface of metaObject.

template<typename T>
T *findFacet() const

Returns a facet from this widget or the nearest parent implementing it.

void paintEvent(Tui::ZPaintEvent *event)

This event handler is used in widget implementations to handle the paint event.

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

void keyEvent(Tui::ZKeyEvent *event)

This event handler is used in widget implementations to handle the key event.

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

void pasteEvent(Tui::ZPasteEvent *event)

This event handler is used in widget implementations to handle the paste event.

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

void focusInEvent(Tui::ZFocusEvent *event)

This event handler is used in widget implementations to handle the focus in event.

See Tui::ZEventType::focusIn() for details.

void focusOutEvent(Tui::ZFocusEvent *event)

This event handler is used in widget implementations to handle the focus out event.

See Tui::ZEventType::focusOut() for details.

void resizeEvent(Tui::ZResizeEvent *event)

This event handler is used in widget implementations to handle the resize event.

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

void moveEvent(Tui::ZMoveEvent *event)

This event handler is used in widget implementations to handle the move event.

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

Related Types

enum Tui::SizePolicy

The enum describes how layout should allocate space to an item.

enumerator Fixed

The item should be be kept at the size indicated by the size hint.

enumerator Minimum

The size hint is the minimum acceptable size.

enumerator Maximum

The size hint is the maximum acceptable size.

enumerator Preferred

The item can shrink and expand.

enumerator Expanding

The item can shrink and expand. Items with this policy should be preferred over items with other policies when expanding.

enum Tui::FocusContainerMode

If not None the widget with this mode is a focus container.

enumerator None

The widget is not a focus container.

enumerator Cycle

A widget with this mode will not pass focus to the parent widget or to its siblings. Use this for windows and dialogs.

enumerator SubOrdering

A widget with this mode will determine focus order locally using the focus order property. If all widgets inside this widgets are passed throught it will pass focus to the parent widget or to its siblings.