[ Previous: Workspace Developer Tips and Tricks ] [ Up: Developer Tutorials ] [ Next: Writing a Workspace Operation ]

Introduction

A Workspace plugin is a collection of Operations, Datatypes and Widgets that are built on top of Workspace. For example, you could create a Workspace plugin that provides a suite of image processing operations. This tutorial is the first of a set of tutorials which will demonstrate how to create a simple Workspace plugin containing an operation, a datatype and a widget.

By the end of this, the first developer tutorial, you will:

Understand the concept of a Workspace plugin
Know how to use the built-in code wizard to create an empty Workspace plugin
Understand the code behind a Workspace plugin
Have built the plugin and loaded it into Workspace

In the follow-up tutorials, we will learn to add operations and datatypes to our plugin:

The following is suggested as pre-reading for this tutorial if you are unfamiliar with C++:

C++ For C Programmers

Sample files used in this tutorial

Using the "Create Plugin" code wizard

Workspace provides a set of code wizards which you can use to automatically generate the basic building blocks for a new Workspace plugin. To start the wizard for creating a plugin:

Navigate to the "Development" menu and select "Create Workspace plugin..."

Finding the code wizard

A window will be displayed that looks something like this:

The create plugin wizard

We can use this code wizard to generate the skeleton code we need to create our plugin. Start by filling in the fields on the form:

Directory: the directory into which the generated code will be placed.
Project name: the name of our project. This field is used internally in the code, so it must be a code-safe name. We will use the project name "Simple".
Display name: the name that will be displayed when the plugin is loaded into Workspace. We will again use the text "Simple".
Internal name: this name must be unique to the plugin. Workspace will use it to uniquely identify the plugin among the other plugins it loads. Generally, the best identifier is a URL format. We will use "www.csiro.au/workspace/simple". Note that it does have to be a valid URL.
Namespace(s): if you want your plugin code to be in a specific C++ namespace, specify it here. We will use the CSIRO namespace.

Note: At any time you can check the purpose of these fields by hovering over them with the mouse and reading the tooltips - see screenshot below for an example.

Our form will now look something like this:

Our values entered into the wizard

If we now look at the bottom of the plugin wizard, we will see some derived values. Workspace is showing us the name of the Class and CMake target that it is going to auto-generate. Next:

Click the Continue or Next button.
If your target directory doesn't exist, you will see a prompt. Click the "Yes" button.

If the directory doesn't exist...

You will now see a screen showing a list of plugins that can be linked to your plugin.

Selecting library dependencies

If your plugin depends on code in any of the provided plugins, you will need to select it here. In this tutorial:

Do not tick any libraries, and
select Continue or Next

The next screen shows copyright notices that you can include in each of the source files in your plugin.

Generate Copyright

For the purposes of this tutorial:

Leave the selection as None
Click the "Generate" button.

Note

To add your own copyright notice all you need to do is place a text file with a suitably descriptive name and containing your copyright text in the Workspace copyrights directory. The file's name becomes the selection in the dropdown list of copyrights. For example, under Windows the default Workspace copyrights directory is normally:

C:\Program Files\csiro.au\workspace\appdata\Workspace\copyrights

Workspace will now generate the code for your plugin, and place it in the directory that you specified . When completed it will display the following dialog, please read it and then click Finish.

Finish

If you navigate to the directory specified you will see that it has the following contents:

Plugin files generated by Workspace

For more details about the code generated, see Writing a Simple Workspace Plugin - looking at the code or click on one of the links to individual files below.

CMakeLists.txt This file contains the configuration settings for how to build your project. CMake will use this file to generate your build files.
simpleplugin_api.h This file defines the export specification for your project. The export specification is attached to class definitions in order to make them visible to Workspace and other external applications.
simpleplugin.h The C++ header for your plugin class. The plugin class is what Workspace uses to load your plugin's contents.
simpleplugin.cpp The C++ source for your plugin class.
pkg-simpleplugin.cmake This file is used by CMake to help others build against your plugin. We don't need to look into this file in the tutorial - just know that it is necessary.

Building your plugin with CMake

You are now ready to build your plugin. We will assume that you are using the same CMake build system used by Workspace. Building your plugin is a two-stage process. The first step is to run cmake on the CMakeLists.txt file and the second is to run make (or nmake or use Visual Studio on Windows). There are a few variations of the cmake step, but we will focus on the two easiest approaches here.

Running ccmake or cmake-gui

The easiest way to carry out the cmake step is to use the interactive tools ccmake or cmake-gui. They are essentially the same except ccmake is a text-based tool whereas cmake-gui is a graphical tool. The latter is perhaps a little easier to use, but the same general concepts apply to both.

When using cmake, you essentially build up a list of options and cache entries describing the system and the way the software should be built. It works by running cmake in a configure step repeatedly until nothing changes, then a final generate step to create the Makefile's (or whatever is the equivalent for your particular compiler and platform, e.g. Visual Studio project files). Each time the configure step is run, new cache variables may be created or modified, and both ccmake and cmake-gui highlight changed variables to the user. Only when a configure step results in no changes will the generate step be enabled.

The first time you run ccmake or cmake-gui on this example and on any example which has a similar CMakeLists.txt file, it is advisable to run the CMake GUI from the Development menu of the Workspace editor.

CMake GUI in the development menu

Depending on your platform, you may need to manually specify the path to cmake-gui executable in Workspace settings.

Workspace settings variables

This will set some environment variables so that CMake can find the various things it needs. If you run ccmake or cmake-gui without these environment changes, it will most likely complain that it could not find a bunch of thing. You are strongly advised to launch the CMake GUI from the Workspace editor to avoid having to deal with any of the files, directories, packages, etc. that cmake needs to find.

If you're planning to build your plugin with Visual Studio on Windows, you will need to ensure that you have the correct version of Visual Studio installed prior to launching CMake from the developer menu. If your version of Workspace was built against Visual Studio 2019, you will also need to have Visual Studio 2017 or Visual Studio 2019 installed on your machine. The CMake launcher will automatically launch CMake from a Visual Studio command prompt ensuring that all environment variables are set for CMake.

When you configure your CMakeLists.txt file in cmake-gui, it will ask you what type of project to build. If you will be using nmake from a command prompt or you are using Qt Creator, choose "NMake Makefiles". If you want to use Visual Studio 2019 project files, select Visual Studio 2019 (or 2019 64bit if you want to build on a 64bit platform).

Note that you should also run nmake from a Visual Studio command prompt, or alternatively if you are using Qt Creator, start it from a Visual Studio command prompt to avoid similar issues.

After you open CMake you will have to specify the source code directory where your plugin code is and the output directory. In the following screenshot, done on Windows, you can see that these have been set to:

C:\temp\Workspace\Sample

C:\temp\Workspace\Sample_Build

Once this is done you should click Configure.

Open CMake, set directories and click Configure

You may need to run Configure two (or more times), essentially until all the red sections disappear from the top pane and there are no errors reported in the bottom pane (although you may get some feedback messages in the bottom pane.) When CMake configures your project correctly you then need to click Generate to emit the build files.

Generate

You can then build the project. If on Windows and using Visual Studio 2019 your solution file should be located somewhere like this:

Visual Studio 2019 Solution File

Before building your plugin, ensure that your solution configuration is RelWithDebInfo.

Visual Studio 2019 Solution Configuration

You can then build the plugin like this:

Visual Studio 2019 Build

Loading a plugin into Workspace

Once you have managed to build the plugin, all that remains is to tell Workspace about it. Workspace will look in a directory relative to its install location and this is how it finds the plugins that come with it. There are three ways of specifying the location of plugins as indicated in Workspace Developer Tips and Tricks. Giving the second way as example, you can direct Workspace to find them through the Workspace editor's Settings --> Configure Application menu (or Workspace --> Preferences if you are on a Mac).

Click on "Plugins" in the list on the left and you will be able to add or remove additional plugins through the "Plugin libraries and search paths" box that appears. Note that any plugins you list here will take precedence over any others that Workspace finds with the same name. After you have added the path to your own plugin, restart the Workspace editor and your plugin should now be loaded and available for use.

Adding your plugin through the Plugins dialog

And finally you can see your Plugin loading when you next start Workspace!

Loading your Plugin in Workspace

Note: Since we have not yet added any operations to our Plugin you will not see the plugin listed in the Operation catalogue.

Summary of important points

Wow, this is a long and complex tutorial - congratulations on reaching the end!

This tutorial has introduced you to the essential elements of writing an empty Workspace plugin. The main points to remember are the following:

The easiest way to create a new plugin is by using the code wizard.
You can create a new Workspace plugin by subclassing WorkspacePlugin . The constructor defines the name, display name and version of the plugin and there must never be more than one instance of the plugin in existence at any time (ie it must be a singleton). The plugin must also provide a specifically named function within an extern "C" block for Workspace to be able to identify it as a Workspace plugin and to load it.
If you are building under Windows, ensure that you launch Qt Creator or cmake-gui from a Visual Studio command prompt or else your environment variables will not be set correctly.

Next steps

Now that we have an empty plugin, we need to add some useful things to it! The next three tutorials deal with this: