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 (
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
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(
stackingLayer() const) allows defining bands in the stacking that can be managed
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”.
Tui::ZVBoxLayout are classes derived from
Each widget can have one top level layout set using
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
SizePolicy policy) and
SizePolicy policy) can be used.
They allow specifing how the available space is allocated to the widgets.
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
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
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
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::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
Widgets only fully work in conjunction with a terminal represented by a
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.
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
To customize input handling override
ZKeyEvent *event) and
Also set the
focus policy to receive input.
To customize reactions to changes in widget state use
ZMoveEvent *event) and
ZResizeEvent *event) .
Further customization is available using
facet(const QMetaObject &metaObject) const,
sizeHint() const and
It is often useful to setup
SizePolicy policy) and
to a widget specific default in the widget constructor, but these are genereally reserved for customization by the
widget user after construction.
class Tui::ZWidget : public QObject¶
This class is neither copyable nor movable. It does not define comparison operators.
Tui::ZWidget::ZWidget(ZWidget *parent = nullptr)
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.
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
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::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
isLocallyEnabledand can be changed by
setEnabledonly directly effects the state returned by
isEnabledif 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
isLocallyVisibleand can be changed by
setVisibleonly directly effects the state returned by
isVisibleif 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
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
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.
Move the widget to the top of its stacking layer.
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.
void setMinimumSize(int w, int h)¶
void setMaximumSize(int w, int h)¶
void setFixedSize(int w, int h)¶
The minimum and maximum size represent contraints for layouting.
setFixedSizeis 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
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
QRect layoutArea() const¶
Returns a QRect describing the area in the widget that should be used for layouts to place the child widgets.
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
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 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
bfor setting a cursor color is 0 - 255. A special value of (-1, -1, -1) represents using the terminal default cursor color.
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.
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::TabFocusthe widget is focusable by keyboard navigation (i.e. using Tab etc).
void setFocusMode(FocusContainerMode mode)¶
FocusContainerMode focusMode() const¶
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.
void setContentsMargins(QMargins m)¶
Margins allow to add empty space around the contents of a widget.
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::ZRootas 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
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 removePaletteClass(const QString &clazz)¶
The list of palette classes modifies which colors are active from the palette.
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¶
childis an ancestor of this widget. If the widget is passed as
childit returns true too.
bool isEnabledTo(const ZWidget *ancestor) const¶
Returns true if all widgets on the path from the widget to
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, 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 mapToTerminal(const QPoint &pos)¶
Map the point
posbetween local coordinates and terminal coordinates.
Returns the next/previous widget in the focus order or nullptr if no such widget exists.
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.
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.
If no command manager is associated with the widget, sets a new
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
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.
void keyEvent(Tui::ZKeyEvent *event)¶
This event handler is used in widget implementations to handle the key event.
void pasteEvent(Tui::ZPasteEvent *event)¶
This event handler is used in widget implementations to handle the paste event.
void focusInEvent(Tui::ZFocusEvent *event)¶
This event handler is used in widget implementations to handle the focus in event.
void focusOutEvent(Tui::ZFocusEvent *event)¶
This event handler is used in widget implementations to handle the focus out event.
void resizeEvent(Tui::ZResizeEvent *event)¶
This event handler is used in widget implementations to handle the resize event.
void moveEvent(Tui::ZMoveEvent *event)¶
This event handler is used in widget implementations to handle the move event.