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

Zuble Application Files

Application Directory Structure and Files

Application Directory

Zuble applications consist of a directory hierarchy containing QML source files, XML configuration files, and JSON data files. Optionally QML plugin modules may be included.

Each Zuble application has an application root directory that occupies the top directory level. All Zuble application root directories for a SNAP deployment are contained in the same parent directory. Within each application root directory three optional files control the configuration and initial execution of a Zuble application program. These are zblconfig.xml, main.qml, and settings metadata files.

The application directories are contained in the read-only area of the SNAP.


This file determines what application resources to load for a Zuble application instance.

This XML file is loaded by zbl and by the QML documents zblmain, ContentPane and ContextPane. It specifies the following application components to be loaded at startup:

Document Root Node

Resource Bundles
<zblconfig><settings>A collection of settings bundles.
<settings><setting_bundle xml:id="test-bundle-1">Defines a settings metafile and its data path, xml:id is the bundle name.
<setting_bundle><meta_path>Path to settings metafile, defines application setting groups, names, and default values.
<data_path>Path to file where bundle settings values will be stored.
Page Theme Files
<zblconfig><styles>A collection of Zuble style files to load at application startup time.
<styles><style_path>Path to a Zuble style file.
Control Modules
<zblconfig><controller>Determines which controller zbl loads on startup.
<controller><control_path>(Optional) Path to a controller for Zuble to load. If <control_path> is not present zblmain.qml will default to loading ZController.
<modules>A collection of control modules for ZController to load. Zuble ignores this element when <control_path> is present.
<modules><control_module>Defines a control module for ZController to load.
<control_module><module_path>Path to control module file.
Menu Tools
<zblconfig><toolbox>A collection of menu tools.
<toolbox><menu_map>Defines a menu tool to be loaded at zbl startup.
<menu_map><menu_label>Label to display in the application menu.
<menu_name>Name of the menu tool - MUST be unique across all application modules within an application.
<menu_path>Path to the menu tool's QML file.
<menu_mode>Toolbox mode when displaying the tool, either modal or modeless
<zblconfig><workspace>A collection of workpads to load at zbl startup time.
<workspace><workpad closeable="true">Defines a workpad to load at zbl startup time. closable (true/false) determines whether user can close the workpad.
<workpad><content_name>Unique name for this workpad type. Name must be unique among all workpads within a Zuble application.
<url>Path to the QML file for this workpad.
<bk_color>Workpad background color.
<menus>Initial menu items to be displayed for this workpad.
<workpad_label>Label to display in workpad selector control for this workpad.
<workpad_json>JSON object to be passed to this workpad.
<menu_action>Defines the menu action button tray contents for this workpad.

Example zblconfig.xml file:

<?xml version="1.0" encoding="UTF-8" ?>


<setting_bundle xml:id="test-bundle-1">


      <control_module module_name="org.zuble.apps.zlogger">




    <workpad closeable="true">
    <!-- Zuble application settings -->

        <menus>stock.logCategoryMenu zlogger.AboutMenu</menus>
        <workpad_label>Log Control</workpad_label>
        <workpad_json>{"logController": "true"}</workpad_json>

        <!-- Histogram log view -->
        <menus>stock.logDetailMenu zlogger.searchMenu zlogger.bookmarkMenu zlogger.AboutMenu</menus>
        <workpad_json>{"logRecordMenuName": "stock.logDetailMenu", "histogram": true}</workpad_json>


If this file exists it is loaded and executed by zbl instead of loading zblmain.qml from Zuble's core resource file. Use this configuration to override Zuble's workpad/toolbox window hierarchy and provide your own custom application window hierarchy. This configuration is appropriate for applications that build their own QML stack.

Settings Metadata Files

A settings metadata file is an XML file that specifies the application's settings group/names and default values. These are used by the ZSettings object to link settings metadata to a specific settings file. Zuble checks for these settings at application startup time and creates them with default values if they don't already exist.

Zuble provides the AppSettings workpad that displays settings files automatically based on input from a settings metadata file.

[TBD: This design conflates the definition of settings data with its presentation in the metadata file. That might not be an issue for simple cases but it's bad practice in general so we might want to revisit this. -rsd]

The following table describes the settings metadata format:

Document Root Node

Settings Idenfication
<appsettings><organization>Organization url under which application settings will be stored.
<name>Name under which application settings will be stored.
Settings Groups
<appsettings><setgroups>List of settings groups.
<setgroups><setgroup xml:id="group-name">Defines a settings group. xml:id is the group name.
<setgroup><name>The label to display for the group on the applications settings workpad.
Settings Items
<appsettings><settings>A collection of settings items.
<settings><setting xml:id="setting-name" group="group-name">Defines a settings item. xml:id is setting name (MUST be unique). group-name is the group name to which this setting belongs.
<setting><name>Label the settings workpad will display for this setting item.
<type>The data type of this item. Currently supported types are: bool, string, and choice.
<default>The default value for this setting when first initialized.
<status>Defines the set of values this settings item can contain.
<status><state>Defines one of a set of values that a settings item can contain.
<setting><desc>Description the settings workpad will display for this settings item.

Example Settings Metadata file:

<?xml version="1.0" encoding="UTF-8" ?>


     <setgroup xml:id="group-1">
         <name>Group One</name>
     <setgroup xml:id="group-2">
        <name>Group Two</name>

     <setting xml:id="captureMessages" group="group-1">
        <name>Message capture.</name>
           <state value="false">Disabled</state>
           <state value="true">Enabled</state>
        <desc>Redirects messges to the status feed.</desc>

     <setting xml:id="test-setting-1" group="group-1">
        <name>Test Setting One</name>
        <default>Yogi Bear</default>
        <desc>This is test setting one. Default is Yogi Bear.</desc>

     <setting xml:id="test-setting-2" group="group-2">
        <name>Test Setting 2</name>
        <desc>This is test setting 2. Default is Bambi.</desc>

     <setting xml:id="choiceList-1" group="group-2">
        <name>Fruit Choice:</name>
              <desc>Fruit of the Pyrus communis tree</desc>
              <desc>Keeps the doctor away</desc>
              <desc>Florida sunshine citrus fruit</desc>
        <desc>Choose a fruit from the selection. Default is apple.</desc>

If this file exists it is loaded by Zuble's settings manager. It's a special settings metadata file that specifies the application's settings group/names and default values. If this file exists it should contain Zuble's basic set of settings plus that of the specific application. If this file doesn't exist Zuble uses its own internal version of the file. In either case Zuble creates the settings automatically with default values the first time the Zuble application starts.

Data Directory

Zuble creates a data directory in the home directory of each Zuble application user. This directory, named .zuble, contains a separate data directory for each Zuble application that the user runs. Zuble applications can access this directory by using the data:// file prefix.

Zuble creates a set of data files for each running Zuble application. These include the following:

Workspace Files

A workspace file (workpad-settings.json) contains the workpad configuration data for each currently opened workpad.

Style Files

Zuble users can create custom style files. These are stored in the the data directory.

Log Files

The Zuble log manager creates its log files in logs directory under the application data directory.

Data Files

Application specific data files are stored under the Zuble application's data directory.

Workpad Persistence

[some stuff about how workpad configuration settings are saved in settings files.]