Zuble QML Types   |  Zuble C++ Classes   |  Table of Contents

Zuble QML Stack

QML Stack

Zuble provides a standard QML stack that implements a common plug-and-play architecture allowing QML components to be mixed and matched into custom SNAP applications using Zuble, the Qt5 toolchain, and snapcraft.

Zuble applications consist of workpads, navigation buttons, and a toolbox of context-sensitive widgets called tools. These visual objects are displayed in a standard application frame.

The QML stack depends on Zuble's core QML extension plugin and the zbl runtime environment.

Applications can create a custom QML stack instead of using Zuble's. Simply create a "main.qml" file in your Zuble application directory and when Zuble starts up your custom QML stack will be loaded instead of zblmain.qml .

{Zuble QML Stack Block Diagram}

Application Architecture

A model-view-controller architecture is implemented that centers around three components:

QML Data Models

QML data models are the standard means of passing data to views in the QML scene. Zuble uses QML types: ListModel, XMLDataModel, and its own ZTableModel for this purpose. ZTableModel is thread-safe so that data can be passed from background threads to QML views in the foreground.

Main Application Window

Views are hosted by Zuble's application frame window. Zuble currently provides a single, standard application window frame, zblmain.qml, in which workpads, menu, and context-sensitive tools are be displayed.

{Screenshot of Application Main Frame Window}


Workpads occupy the main portion of the Zuble application scene in an area called the workspace, and are the UI components that typically display content and accept input from the user. Multiple workpads may be loaded simultaneously however only one is displayed at a time.

A menu is displayed horizontally across the top of the workspace that shows available tools which can can be used based upon the context of the currently displayed workpad. Clicking on a menu item causes the workpad to scroll down, sliding the toolbox area into view, overlapping and occluding the workpad area. Clicking on the menu item again or on the "close toolbox" button closes the toolbox by sliding the current workpad back into view. Workpads can programatically show and hide the toolbox as well, and can modify the menu dynamically at run time based on the current UI context.

A workpad selector is displayed in a column on the left of the screen that allows switching between workpads. It's implemented as a scrollable list of buttons. (The current implementation can't be hidden but it's envisioned to be hidable by an affordance as yet to be determined in a future update before initial release.)


Tools are windows dedicated to specific context-sensitive tasks and may be implemented as simple dialog boxes or as more sophisticated UI components, as necessitated by the application design. Tools are implemented as QML list delegates and displayed in a list object. Since list delegates are stateless entities Zuble provides a means of preserving workpad tool state within the workpad itself and for preserving that state across application instances within the application settings files.

Zuble provides a set of standard tools for performing common tasks such as a file selection dialog box.


Zuble's main application window loads a ZController object at startup that contains application control modules created by extending the ZControlModule type. Application control modules are specified by <control_module> elements in the application's zblconfig.xml file.

The control module architecture allows Zuble applications to peacefully coexist within the zbl runtime environment. Each application can implement one or more control modules that receive commands via a standard command queue and dispatch those commands to handler functions automatically. Control modules typically use ZScriptThread objects to execute I/O in background threads, utilizing a REST-type command/respond API through the command queue.

Application Settings Manager

Zuble provides an application settings management system that provides a standardized way for Zuble applications to initialize and edit application settings as well as a platform-independent was to store settings files.

{Screenshot of Application Settings Workpad}

Settings Metadata Files

Zuble applications specify settings metadata files. These XML files describe each application setting and default value. Zuble automatically creates the settings, applying the default values at application startup if the settings don't already exist.

If an application doesn't provide an application settings metadata file Zuble creates a default settings metadata file to contain the application's configuration data specific to Zuble itself. Zuble applications can override this behavior by providing a default Zuble application settings file (zblsettings.xml) in their QML application directory and including the Zuble-specific settings there.

Platform Independent Settings Format

Zuble settings files are stored in the JSON custom settings format. Zuble doesn't use the native settings format due to both platform incompatibilites and the desire to store hierarchical data structures consistently across platforms.

Standardized Settings UI

Settings can be displayed automatically by a Zuble-provided workpad, AppSettings. The workpad uses "settings bundles" as input. A settings bundle consists of a settings data file location (either app name/organization or file path) and a settings metadata file location (file path). Settings metadata may also be provided programatically by a text string.

Settings metadata describes the settings data (or a subset) from the specified data file that will be shown on the settings page. Settings bundles are specified in the application's zblconfig.xml file.

This approach allows multiple settings pages to show data from the same file but limits each page to containing settings from only a single settings data file. Applicaitons can provide their own settings workpads or tools to override these limitations if necessary.