Workspace  6.13.0
Creating a standalone application

Introduction

As well as being able to create and run workflows both from the command line (via workspace-batch), and from within the Workspace editor, it is possible to build arbitrarily-sized standalone applications using a workflow and your own Qt user interface (UI). This tutorial shows you how to get started by using the Workspace's simple application generation wizard to create a basic application. The example provided is quite basic but should demonstrate enough to allow you to attempt something more complex. We are going to generate an application that utilises elements from earlier tutorials - we will create a standalone rectangle area calculator.


Contents


Pre-requisites

Before using this wizard, and to follow this tutorial, you should have generated the Simple plugin following the previous tutorials. Note: Before proceeding, it is wise to backup your existing code. If anything goes wrong you can then reinstate this backup and restart.


Sample files used in this tutorial


Workflow to be used by the application

Before we proceed with the generation of the application, we create a workflow that we will use to drive it.

  1. Launch the Workspace editor application as usual
  2. We will need to create a CalculateRectangleArea operation:
    • Find the CalculateRectangleArea operation in the catalog and drag it onto the canvas
  3. On the "Rectangle" input, right-mouse-button to open the context menu and select "Compose object group"
  4. To drive the workflow create an output:
    • Expand the master output rack
    • Right mouse button click on the output called "Area" to show the context menu
    • Select "Create workspace output"
  5. The workflow should now look like this:
    tutsimpleapp_workflowlooky1.png
    Workflow
  6. We now need to assign global names to the relevant inputs and output. Doing this allows us to connect the data in the workflow to the UI elements:
    • On the newly created "Compose Rectangle" operation:
      • Right mouse button on the "Width" input and select "Assign global name"
        tutsimpleapp_globalnamecontextmenuforrectanglewidth.png
        Assigning a global name to Width
      • Set the global name to "width"
        tutsimpleapp_globalnameforrectanglewidth.png
        Global name dialog
      • Similarly, for the "Height" input, assign a global name called "height"
      • Also assign the global name "area" to the output "Area" on the "Calculate Rectangle Area" operation
        tutsimpleapp_globalnameforrectanglearea.png
        Global name on area output
  7. Pin the Input and Output racks by clicking on the triangle above them
  8. The workflow should now look like this (note the indicator G on the items with global names):
    tutsimpleapp_workflowlooky2.png
    Workflow
  9. The workflow is now ready to be used in our application. Make sure you have saved it in a known location. NOTE: The workflow will be copied to a new location (<plugin directory>/Application/Resources) - make any changes to this copy.

Using the "Create simple application" code wizard

We now move on to creating the application code, along with the widget .ui file and associated code. To start the wizard:

  1. Navigate to the "Development" menu and select "Create simple application...":
    tutsimpleapp_createsimpleappmenu.png
    Finding the code wizard
  2. A window will be displayed that looks like this:
    tutsimpleapp_createsimpleappwizardpageone.png
    The first page of the wizard
    This wizard will generate the skeleton code required for a standalone application. The code generated expects the plugin code generated by the associated wizard to already have been created. If you have not done this, then the wizard will not be able to function correctly. We now fill out the fields:
    • Application name:The name for the application. This will also determine the name of the directory under your top level project and executable name.
    • Top level directory: The top level directory for your plugin. Point this to the same location as your plugin source.
    • Namespace(s): The namespace to be used for the widget class.
  1. Click Next to show the next wizard page: This page allows you to specify whether to create a new UI file (which will be blank), or to base the UI on an existing widget. You must also specify a class name for the widget - use the usual naming convention to specify this class name. If you choose to import an existing ui file - specifically, the rectanglewidget.ui created in the last tutorial, click on the folder icon to open a dialog and navigate to where your rectanglewidget.ui file was created (this will be in the top level of the plugin area):
    tutsimpleapp_createsimpleappwizardpagetwo.png
    The second page of the wizard
  2. Click Next to show the next wizard page: We now point the wizard to the workflow we created at the beginning of this tutorial:
    tutsimpleapp_createsimpleappwizardpagethree.png
    The third page of the wizard
    Recall that this workflow will be copied to a new location (<plugin directory>/Application/Resources) and any future development of your workflow should take place on this copy.
  3. Click Next to show the next wizard page: We can now choose which menu items to include in our application:
    tutsimpleapp_createsimpleappwizardpagefour.png
    The fourth page of the wizard
    The three options are:
    • "Include serialization menu items" - this adds Save and Load functionality to the application. This serialization will record the value of all global names associated with inputs (outputs are not recorded as they are calculated as a result of executing a workflow).
    • "Include help menu items" - this adds the option to display an about box, the contents of which can be set in the MainWidget::onHelpAboutTriggered method in the new mainwidget.cpp source file.
    • "Include menu item to inspect running workflow" - this will add a menu option that opens an embedded version of the Workspace editor canvas attached to your application workflow. This allows you to inspect and debug the running workflow during execution of your application.
  4. Click Next to show the next wizard page: We can now choose which libraries / plugins we will depend on. Since we are using the code generated from previous tutorials, we need to ensure that we check the option to include the "Simple" plugin:
    tutsimpleapp_createsimpleappwizardpagefive.png
    The fifth page of the wizard
    No other plugins are required for this example.
  5. Click Generate to show the final wizard page, which should look like this if all has gone well:

    tutsimpleapp_createsimpleappwizardpagesix.png
    The sixth page of the wizard

    At this stage, the code has been generated in the same location as your plugin. You should see the following file and directory structure:

    • <top level project source area>
      • CalculateArea
        • Resources
          • calculatearea_application_resources.qrc
          • CMakeLists.txt
          • mainworkflow.wsx
          • splashscreen.png
          • app-logo.ico
        • Widgets
        • CMakeLists.txt
        • main.cpp
      • Designer
        • CMakeLists.txt
        • simpleplugindesigner.cpp
        • simpleplugindesigner.h
        • simpleplugindesigner_api.h
      • calculaterectanglearea.cpp
      • calculaterectanglearea.h
      • CMakeLists.txt
      • pkg-simpleplugin.cmake
      • rectangle.cpp
      • rectangle.h
      • rectanglewidget.cpp
      • rectanglewidget.h
      • rectanglewidget.ui
      • rectanglewidgetconnector.cpp
      • rectanglewidgetconnector.h
      • rectanglewidgetfactory.cpp
      • rectanglewidgetfactory.h
      • simpleplugin.cpp
      • simpleplugin.h
      • simpleplugin_api.h

    We can now build the application.

Building the application

At this stage, the purpose of building the application is to ensure the files have been set up correctly. If we then run the application, we will not have a useful UI since we have not connected up the workflow elements, nor is the UI complete.

To build the application, follow exactly the same procedure as in Writing a Simple Workspace Plugin. In summary:

  1. From the "Development" menu, launch "CMake GUI":
    tutsimpleapp_createsimpleapplaunchcmake.png
    Launching CMake GUI
  2. Click "Configure"
  3. Click "Generate"
  4. Run Developer Studio and build (or build however you have configured it - e.g. with makefiles).

If everything built without error you can move on to the next section. You can also check the application runs correctly.

Finalizing the UI and connecting the workflow elements

We now need to edit the UI and connect various elements to the workflow.

  1. Launch the Workspace editor
  2. Launch Qt Designer from the "Development" menu:
    tutsimpleapp_createsimpleapplaunchqdesigner.png
    Launching Qt Designer
  3. Now we open the .ui file created by the wizard earlier. This is located in below the top level plugin directory here: Application/Widgets/mainwidget.ui. In this example it is called mainwidget.ui. The UI widget we use here is the one we created as a blank one:
    tutsimpleapp_initialmainwindow.png
    The UI as it is before any changes
  4. Add some new UI elements :
    • Create a new "Label" with the text "Width".
    • Create a new "Double Spin Box".
    • Repeat the previous steps for "Height" and "Area" as well.
      tutsimpleapp_mainwindowwithnewelements.png
      Updated main window
    • Set the "objectName" property of each "Double Spin Box" to "width", "height" and "area" to aid in identifying it in the Qt Designer "Object Inspector":
      tutsimpleapp_areaobjectname.png
      Spin box name changed
    • Uncheck the "enabled" property of "area" in the "Property Editor":
      tutsimpleapp_spinboxnotenabled.png
      Unchecked "enabled" spin box property
      This will reinforce to the user that this is a read-only item in the UI. You can also choose to remove the spin buttons or align them differently (these are other properties that you can find in the objects properties window). Also ensure that the "maximum" property is set to 999999999.000000 (the highest number it will display). The widget should now look like this:
      tutsimpleapp_mainwidgetedited.png
      Main window widget
  5. Now we connect the workflow elements to the UI using the global names:
    • Back in the Workspace GUI, load the copied version of the workflow we created at the start of this tutorial - this will be located below the top level plugin directory here: Application/Resources/mainworkflow.wsx.
    • Left-mouse button on the height input and drag onto the height double spin box in Designer's "Object Inspector":
      tutsimpleapp_connectglobals1.png
      Global name "height" on workflow
      tutsimpleapp_connectglobals2.png
      "height" spin box in "Object Inspector"
    • Select "Global name: height" from the context menu:
      tutsimpleapp_connectglobals3.png
      Context menu
    • Repeat for:
      • width
      • area
  6. Quit Qt Designer and Workspace Editor

Rebuilding the application

To rebuild the application, repeat the procedure in Building the application. You should now be able to launch the executable from 'Sample_build\Install\bin' directory (this will ensure that the environment is correctly set up). The application should look like this:

tutsimpleapp_finallook.png
The application

Running the application

The application should have been installed in the directory specified by the CMake variable CSIRO_INSTALL_AREA (you can see this in the "Ungrouped Entries" section when you run CMake GUI):

tutsimpleapp_createsimpleappinstallarea.png
Install area

If you want to run from inside Visual Studio, do the following:

  1. Run the workspace editor from the command line in the following way:
    • workspace-gui –launch devenv <wherever the .sln file is>/SIMPLE.sln This will ensure that the correct environment variables are set for the run.

What next?