中文 EN
Documentation

Qt-UI WidgetKit Docs

A Qt custom control library for industrial, data, and business systems, reducing repeated UI implementation work.

Back to Product View StyleKit Docs View ChartKit Docs

Overview

Qt-UI WidgetKit Overview

WidgetKit is a custom Qt Widgets control library for industrial software, business systems, device consoles, and data dashboards.

Use Cases

  • Dashboard and monitoring applications.
  • Device parameter configuration and status display.
  • Productized internal business systems.
  • Qt projects that need consistent interaction and visual behavior.

What It Includes

  • Enhanced basic controls such as buttons, edits, and checkboxes.
  • Containers, navigation controls, data views, and display components.
  • Unified theme, sizing, state, and JSON configuration behavior.
  • Demo projects and integration examples.

Base and Class Diagram

Most WidgetKit controls extend a Qt widget class and implement IUIGQWidgetBase for theme, layout ratio, opacity, type name, and JSON serialization support. Each concrete control also uses UIGQWidgetBase and a dedicated *Impl class internally for common state and drawing logic.

QObject
  └─ QWidget
      ├─ QPushButton
      │   └─ UIGQPushButton + IUIGQWidgetBase
      │       └─ UIGQRibbonPushButton
      ├─ QCheckBox
      │   └─ UIGQCheckBox + IUIGQWidgetBase
      ├─ QRadioButton
      │   └─ UIGQRadioButton + IUIGQWidgetBase
      ├─ QLineEdit
      │   └─ UIGQLineEdit + IUIGQWidgetBase
      ├─ QTextEdit
      │   └─ UIGQTextEdit + IUIGQWidgetBase
      ├─ QComboBox
      │   └─ UIGQComboBox + IUIGQWidgetBase
      ├─ QTableView
      │   └─ UIGQTableView + IUIGQWidgetBase
      ├─ QTreeView
      │   └─ UIGQTreeView + IUIGQWidgetBase
      ├─ QScrollArea
      │   └─ UIGQScrollView + IUIGQWidgetBase
      │       └─ UIGQPropertyList
      ├─ QLabel
      │   ├─ UIGQLabel + IUIGQWidgetBase
      │   └─ UIGQLabelEx + IUIGQWidgetBase
      ├─ QOpenGLWidget
      │   ├─ UIGQOpenGLWidget
      │   └─ UIGQOGLWidget
      ├─ UIGQContainer + IUIGQWidgetBase
      ├─ UIGQStackContainer + IUIGQWidgetBase
      ├─ UIGQTabWidget + IUIGQWidgetBase
      ├─ UIGQRibbonBar + IUIGQWidgetBase
      ├─ UIGQImage + IUIGQWidgetBase
      ├─ UIGQCanvas + IUIGQWidgetBase
      └─ UIGQSwitch + IUIGQWidgetBase

Quick Start

Quick Start

  1. Add WidgetKit and the minimal required UIGearsQtLib sources to your Qt project.
  2. Initialize the theme directory and load the desired theme.
  3. Create WidgetKit controls in C++ or from JSON configuration.
  4. Keep layout and theme names in configuration whenever possible.
auto* button = new UIGQPushButton(parent);
button->setText("Import");
button->setThemeName("PrimaryButton");

Use the smoke/demo project as the first build target when validating a new machine.

Usage Guide

Usage Guide

WidgetKit controls follow a common pattern:

  • Visual states are managed through theme names and style data.
  • Layout is configured through containers, docking, and policy-based sizing.
  • Runtime behavior is controlled with explicit C++ APIs.
  • JSON serialization is used for reusable UI configuration.

Recommended Practice

  • Prefer setThemeName(...) over direct color assignment for reusable visuals.
  • Keep hidden/transparent backgrounds as runtime behavior when the setting affects drawing logic.
  • Use absolute dock only for chrome, overlays, and fixed-position tool areas.
  • Use auto-size mode for absolute containers when the size should follow child controls.

Layout and Containers

Layout and Containers

Layout and container controls organize the structure of a WidgetKit interface.

Typical Controls

  • Window and top-level containers.
  • Horizontal and vertical layout containers.
  • Card and panel containers.
  • Absolute dock containers for overlays or window chrome.
  • Scrollable containers for large content areas.

Key Concepts

  • Direction: horizontal or vertical child flow.
  • Padding and spacing: internal layout rhythm.
  • Size policy: fixed size or ratio-based sizing.
  • Theme name: reusable visual appearance.
  • Draw background: whether the container paints its own background.

Class Diagram

QWidget
  ├─ UIGQContainer + IUIGQWidgetBase
  ├─ UIGQStackContainer + IUIGQWidgetBase
  ├─ QScrollArea
  │   └─ UIGQScrollView + IUIGQWidgetBase
  │       └─ UIGQPropertyList
  ├─ UIGQSplitter + IUIGQWidgetBase
  ├─ UIGQSpacer + IUIGQWidgetBase
  └─ UIGQGroupBox + IUIGQWidgetBase

Common APIs

Method Description Parameters Return
setChildLayout(UIGQContainer::AutoChildLayout layout) Sets the child layout direction or flow mode. layout: kHorizontal, kVertical, kHorizontalFlow, kVerticalFlow, or kUnset. void
setChildSpace(int space) Sets the gap between child controls. space: gap in pixels. void
setChildPadding(int left, int top, int right, int bottom) Sets container padding. left/top/right/bottom: padding values in pixels. void
addChildWidget(QWidget* child, int ratio = 1) Adds a child widget and assigns its layout ratio. child: child control; ratio: space weight. void
setChildRatio(QWidget* child, int ratio) Updates a child control's layout ratio. child: child control; ratio: space weight. void
setLayoutRatio(int ratio) Sets a widget's own ratio when it participates in parent layout. ratio: space weight. void
getLayoutRatio() const Reads the widget's current layout ratio. None. int

Use container themes for visible surfaces, and keep non-visual layout containers background-free.

Input Controls

Input Controls

Input controls collect user data and trigger actions.

Common Types

  • Push buttons.
  • Edit/input fields.
  • Checkboxes and radio buttons.
  • Sliders, spin boxes, and option selectors.

Class Diagram

QWidget
  ├─ QPushButton
  │   └─ UIGQPushButton + IUIGQWidgetBase
  │       └─ UIGQRibbonPushButton
  ├─ QCheckBox
  │   └─ UIGQCheckBox + IUIGQWidgetBase
  ├─ QRadioButton
  │   └─ UIGQRadioButton + IUIGQWidgetBase
  ├─ UIGQSwitch + IUIGQWidgetBase
  ├─ QLineEdit
  │   └─ UIGQLineEdit + IUIGQWidgetBase
  ├─ QTextEdit
  │   └─ UIGQTextEdit + IUIGQWidgetBase
  ├─ QComboBox
  │   └─ UIGQComboBox + IUIGQWidgetBase
  ├─ QSpinBox
  │   └─ UIGQSpinBox + IUIGQWidgetBase
  └─ QSlider
      └─ UIGQSlider + IUIGQWidgetBase

Implementation Notes

  • Keep text and placeholder content separate from visual style.
  • Use theme names for normal, hover, pressed, checked, disabled, and focus states.
  • Keep validation feedback visible and close to the input.
  • For icon buttons, prefer SVG icons with explicit color behavior.

Display Controls

Display Controls

Display controls present text, images, status, and visual summaries.

Common Types

  • Labels and text blocks.
  • Image controls.
  • Status cards.
  • Badges, tags, and counters.
  • Preview panels and summary cards.

Class Diagram

QWidget
  ├─ QLabel
  │   ├─ UIGQLabel + IUIGQWidgetBase
  │   └─ UIGQLabelEx + IUIGQWidgetBase
  ├─ UIGQImage + IUIGQWidgetBase
  ├─ QGraphicsView
  │   └─ UIGQSvgView + IUIGQWidgetBase
  ├─ QLCDNumber
  │   └─ UIGQLCDNumber + IUIGQWidgetBase
  └─ QProgressBar
      └─ UIGQProgressBar + IUIGQWidgetBase

Notes

Use labels for text, image controls for raster/SVG assets, and containers for grouped display surfaces. Keep display controls read-only and avoid mixing editing behavior into them.

Data Controls

Data Controls

Data controls present structured information.

Common Types

  • Tables and policy rows.
  • Lists and item collections.
  • Tree views.
  • Scroll areas with horizontal and vertical scroll bars.

Class Diagram

QWidget
  ├─ QTableView
  │   └─ UIGQTableView + IUIGQWidgetBase
  ├─ QTreeView
  │   └─ UIGQTreeView + IUIGQWidgetBase
  ├─ QListView
  │   └─ UIGQListView + IUIGQWidgetBase
  ├─ QListWidget
  │   └─ UIGQList + IUIGQWidgetBase
  └─ QScrollArea
      └─ UIGQScrollView + IUIGQWidgetBase
          └─ UIGQPropertyList

Notes

Keep row height, column width, and selection states stable. For large datasets, prefer incremental loading or virtualization strategies instead of creating every row at once.

Common APIs

Method Description Parameters Return
setItemHeight(int height) Sets row or item height. height: height in pixels. void
setCheckstyle(bool enabled) Enables the table checkbox style. enabled: whether checkbox style is enabled. void
setColumnWidget(int column, UIGQContainer* widget) Configures a custom control container for a table column. column: column index; widget: custom container. void
selectedRows() const Returns selected table rows. None. QList<int>
headerCheckedChanged(bool checked) Signal emitted when the header checkbox changes. checked: header checkbox state. void
customControlClicked(int row, const QString& name) Signal emitted when a custom cell control is clicked. row: row index; name: control name. void

Navigation Controls

Navigation Controls

Navigation controls help users move between views and modes.

Common Types

  • Sidebar navigation.
  • Tab-like segmented controls.
  • Breadcrumb-style labels.
  • Header toolbar actions.
  • Page switch buttons.

Class Diagram

QWidget
  ├─ UIGQTabWidget + IUIGQWidgetBase
  ├─ QMenu
  │   └─ UIGQMenu + IUIGQWidgetBase
  ├─ QMenuBar
  │   └─ UIGQMenuBar + IUIGQWidgetBase
  ├─ UIGQRibbonBar + IUIGQWidgetBase
  │   ├─ UIGQRibbonArea
  │   ├─ UIGQRibbonPage
  │   ├─ UIGQRibbonGroup
  │   └─ UIGQRibbonPanel
  ├─ QPushButton
  │   └─ UIGQPushButton + IUIGQWidgetBase
  │       └─ UIGQRibbonPushButton
  └─ QScrollBar
      └─ UIGQScrollBar + IUIGQWidgetBase

Notes

Navigation controls should have clear selected, hover, and disabled states. Keep destructive actions visually separate from navigation.

Common APIs

Method Description Parameters Return
addTab(const QString& itemName, const QString& icon, const QString& iconSelected) Adds a navigation tab item. itemName: tab text; icon: normal icon; iconSelected: selected icon. void
setSelectedIndex(int selectedIdx) Sets the selected tab index. selectedIdx: target tab index. void
getSelectedIndex() Reads the selected tab index. None. int
setIsHor(bool isHorizontal) Sets horizontal or vertical tab layout. isHorizontal: true for horizontal, false for vertical. void
setShowText(bool show) Shows or hides tab text. show: whether text is visible. void
setShowIcon(bool show) Shows or hides tab icons. show: whether icons are visible. void
currentChanged(int index) Signal emitted when the selected tab changes. index: selected tab index. void

Graphics and Canvas

Graphics and Canvas

Graphics controls host custom drawing, OpenGL scenes, SVG imagery, and lightweight visualization surfaces.

Chart-specific controls belong to ChartKit. WidgetKit graphics controls are intended for non-chart rendering surfaces, previews, and custom painted UI.

Class Diagram

QWidget
  ├─ UIGQCanvas + IUIGQWidgetBase
  └─ QOpenGLWidget
      ├─ UIGQOpenGLWidget + OpenGLFunctions
      └─ UIGQOGLWidget

Notes

  • Keep drawing logic separate from layout code.
  • Use stable canvas dimensions where possible.
  • Validate high-DPI behavior.
  • For SVG display, decide whether the original SVG color or runtime tint color should be used.

Button

Button

Button controls trigger commands and actions.

Inheritance

UIGQPushButton extends the WidgetKit base widget behavior and wraps Qt push-button interaction with theme, icon, state, and serialization support.

QWidget
  └─ QPushButton
      └─ UIGQPushButton + IUIGQWidgetBase

Common APIs

Method Description Parameters Return
setText(const QString& text) Sets the visible label. text: button text. void
setIcon(const QString& iconPath) Sets an icon resource path. iconPath: Qt resource or file path. void
setThemeName(const QString& themeName) Applies a themed appearance. themeName: theme configuration name. void
setDrawBackground(bool drawBackground) Enables or disables background drawing for icon-only or transparent buttons. drawBackground: whether to paint the button background. void
setFadeEnabled(bool enabled) Enables or disables Hot/Normal fade feedback on the button. enabled: whether fade is enabled. void

JSON Properties

Property Type Description
type string Control type, usually qtbutton.
name string Object/configuration name.
text string Button text.
icon string Optional icon resource path.
style array State style bindings.
x/y/w/h number Position and size when used by a layout/configuration.

Keep command meaning in text or tooltip, and keep visual state in theme configuration.

Edit

Edit

Edit controls collect single-line or multi-line user input.

Inheritance

Edit widgets follow the WidgetKit base widget model and add text editing, placeholder, focus, disabled, and serialization behavior.

QWidget
  └─ QLineEdit
      └─ UIGQLineEdit + IUIGQWidgetBase

Common APIs

Method Description Parameters Return
setText(const QString& text) Sets current text. text: edit content. void
text() const Returns current text. None. QString
setPlaceholderText(const QString& text) Sets placeholder text. text: placeholder content. void
setThemeName(const QString& themeName) Applies themed borders, background, and text colors. themeName: theme configuration name. void
setReadOnly(bool readOnly) Switches between editable and read-only behavior. readOnly: whether editing is disabled. void

JSON Properties

Property Type Description
type string Control type, usually an edit/input type.
name string Object/configuration name.
text string Initial text.
placeholder string Placeholder text.
style array Normal, focus, disabled, and error style bindings.
x/y/w/h number Position and size.

Use validation outside the control unless the project defines a shared validation component.

Checkbox

Checkbox

Checkbox controls represent binary choices.

Inheritance

QWidget
  └─ QCheckBox
      └─ UIGQCheckBox + IUIGQWidgetBase

Common APIs

Method Description Parameters Return
setChecked(bool checked) Sets whether the checkbox is checked. checked: checked state. void
isChecked() const Returns whether the checkbox is checked. None. bool
setText(const QString& text) Sets checkbox label text. text: label text. void
setThemeName(const QString& themeName) Applies the themed checkbox appearance. themeName: theme configuration name. void

Notes

Use a checkbox when the option can be toggled independently. Use radio buttons or segmented controls when the user must choose exactly one option from a group.

SVG Icons

SVG Icons

WidgetKit supports SVG icon usage in image controls and icon buttons.

Color Modes

  • Use original SVG colors when the asset already contains the desired palette.
  • Use runtime tint color when the icon should follow theme state.

Notes

Prefer simple path-based SVG icons. Avoid SVGs with complex filters when the icon is expected to be tinted, because filters can introduce unexpected dark artifacts.

Dashboard

Dashboard

Dashboard screens combine containers, cards, navigation, data rows, charts, and command buttons into a product-like interface.

Recommended Structure

  • Header: product name, user profile, help, and window controls.
  • Sidebar: navigation and status entry points.
  • Workspace: cards, tables, preview panels, and summary panels.
  • Footer or overlays: optional feedback and notifications.

Use theme names for surfaces and keep direct visual settings out of page code whenever possible.

License

License

WidgetKit provides community and commercial editions.

The community edition is suitable for learning and evaluation. Commercial editions are intended for production projects and include source packages, examples, resources, and update rights according to the purchased plan.

Actual licensing scope follows the order and agreement at purchase time.