Developing Custom Display Widget Plugins for DewesoftX Using C++

Course overview

The Custom Display Widget Plugins course empowers developers to extend DewesoftX’s visualization capabilities with fully custom, C++-based interface components. It starts by introducing the C++ Widget Plugin framework, which abstracts DewesoftX internals accessed via DCOM and enables seamless integration of new visual instruments.

You’ll then walk through setting up your development environment: installing Visual Studio, the DewesoftX widget plugin template (via VSIX), and configuring environment variables (DEWESOFT_EXE_X64 or X86) so your new widget can be automatically detected by DewesoftX.

Next, the course guides you in creating and customizing your first plugin. Using the Visual Studio wizard, you’ll generate boilerplate code and metadata before building a simple digital meter that renders channel values in real-time using drawCanvasData. Along the way, you’ll explore project structure, clean up sample code, and add configurable visual properties.

Advanced sessions dive into rich UI features: handling property changes, drawing performance on canvas, reacting to button clicks, and defining VisualProperties through methods like updateVisualProperties and visualPropertyChanged. You’ll also package your finished widget into a .vc bundle, ready for import into other DewesoftX setups .

Additionally, the course encourages best practices by demonstrating how to structure projects to include unit tests (via Google Test) to validate widget logic before deployment.

By course end, you’ll be proficient in designing, implementing, packaging, and deploying custom display widgets for DewesoftX—enabling powerful, application-specific visual tools tailored to your measurement needs.

Did you ever want to visualize some data in Dewesoft but just couldn't find the right widget? With the help of C++ Widget Plugin, you can create your own widgets and integrate them directly into Dewesoft. C++ Widget Plugin uses Dewesoft's DCOM interface to access its internals but abstracts the interaction away from the programmer.

C++ Widget Plugin allows you to create your very own widget and modify its behaviour to suit the needs of the data you want to present. The code is compiled into an external library and automatically recognized and loaded by Dewesoft. This is why your widget can be easily exported and imported for use on other computers.

The examples of C++ Widget plugins we mention in this tutorial are available on Dewesoft's webpage under Support > Dewesoft Downloads > Developer downloads > Online PRO training C++ plugin examples.

In order to start using C++ Widget Plugin, you must have Visual Studio IDE installed on your system. Some of the reasons we have chosen Visual Studio are its functionalities, powerful developer tooling, like IntelliSense code completion and debugging, fast code editor, easy modification/customization, and many more. 

You can download the DewesoftX Widget plugin template from our Dewesoft webpage, Support > Dewesoft Downloads >  Developer Downloads > Visual Studio Development Tool (2017/2019 or 2022). After downloading, just double-click the file and the VSIX installer will guide you through the installation process.

Once Visual Studio is downloaded and installed you will be able to download the Dewesoft plugin template using the New project window and selecting the DewesoftX C++ Widget plugin template. 

The new project window is accessed in File tab -> New -> Project.

To get a better understanding of how to work with C++ Widget Plugin we will implement a very simple widget similar to a Digital meter that already exists in Dewesoft. The Digital meter shows the value of the channel at the current timestamp, it allows one input channel at a time and it shows the name of the channel in the top left corner. 

The Digital meter that we will mimic looks like this:

Our widget will also allow only one channel at a time to be shown and we will only show the value of the channel and not the name. 

Now we go back to Visual Studio. To create a new C++ Widget Plugin we click the Project button in File tab > New > Project. We select the DewesoftX Widget plugin template as our template and fill in the name of our project. After clicking the Ok button a wizard window will appear to guide us through the creation of the plugin.

Since your plugin will be integrated inside Dewesoft, it needs to know Dewesoft's location. We can use our custom location (specifying the absolute path), or we can use the system variable DEWESOFT_EXE_X86 if we use a 32-bit version of Dewesoft or DEWESOFT_EXE_X64 if we use 64-bit Dewesoft. We set the variable using System properties window (it can be found pressing Windows key and searching for Edit the system environment variables), and under advanced tab clicking the Environment variables.

After clicking the Next button the following window appears which is used to set Plugin information such as plugin name, its ownership, and version.

• Plugin name - The name that will be seen in Dewesoft.

• Description - Short description of your plugin.

• Vendor - Company that created the plugin.

• Copyright - Owner of the plugin.

• Major version - Sets the initial major version. The value should change when a breaking change occurs (it's incompatible with previous versions).

• Minor version - Sets the initial minor version. The value should change when new features and bug fixes are added without breaking compatibility.

• Release version - Sets the initial release version. The value should change if the new changes contain only bugfixes.

All fields are optional except for the Plugin name. 

After clicking the Next button a final window appears. This window is used to set your Base class name. It is used as a prefix for class and project name. When the Base class name is set, we can click the Finish button and the wizard will generate the plugin template based on your choices. 

Structure of the solution

When a new C++ Widget plugin project is created, the wizard will create the basic files and project structure needed for development. In the picture below you can see the structure of a project in a tree view with collapsed items. In our case, ProTutorial refers to text which was used as the Base class name.

• ProTutorialPlugin - The actual plugin implementation

• ProTutorialPluginTest - Solution for writing unit tests for ProTutorialPlugin.

• gtest - Simple library, required by ProTutorialPluginTest for unit testing your plugin. This project should not be modified. 

As mentioned before, our plugin implementation is inside the ProTutorialPlugin project. It contains files for writing the main code and the Dewesoft_internal folder with methods for interacting with Dewesoft. The main code of the plugin is written in the plugin.h and plugin.cpp files. Here we connect the input channels and write the code for behavior of our custom widget. We can also set additional properties of the plugin and save the setup variables. 

When our project is successfully generated, we will be able to extend Dewesoft. But before implementing the logic behind our plugin, let's take a look at how our plugin is integrated into Dewesoft by default. In order to do that, we have to start our program using the shortcut F5 or pressing the Start button in the center of Visual Studio's main toolbar. 

After Dewesoft loads, our Widget can be accessed in Measure mode under Measure > More > TestWidgetExample. 

As we can see, it already contains an example of widge

As mentioned before, when we create a new C++ Widget Plugin it already contains an example of a widget. Before we write our own widget we will remove the code of this example. We will also remove all the methods we won't use for writing our plugin.

It is important to keep in mind that C++ uses header files (you can recognize them by the .h extension) in addition to source files. Header files are designed to provide information about your class and are used for declaration of variables and methods, while their initialization is done in the source files with .cpp extension.  In order for our plugin to still work we need to remove the code from both the .h file and .cpp file.

The plugin.h  file should now look like this:

1#pragma once
2#include "interface/plugin_base.h"
3#include "dcomlib/dcom_utils/colors.h"
4
5struct VisualProperties
6{
7};
8
9class ProTutorialWidget : public Dewesoft::Widgets::Api::Widget
10{
11public:
12    ProTutorialWidget();
13    ~ProTutorialWidget() override;
14
15    static void getPluginProperties(PluginProperties& props);
16
17    void drawCanvasData(DrawDataParams& drawParams) override;
18    void acceptInputSlots() override;
19
20    void updateSetup(Setup& setup) override;
21
22    void initVisualProperties(VCProperties& visualProperties) override;
23    void updateVisualProperties(VCProperties& visualProperties) override;
24    void visualPropertyChanged(std::string& groupId, VCProperty& visualProperty) override;
25    void visualPropertyButtonClick(std::string& groupId, VCProperty& visualProperty, int buttonIndex) override;
26private:
27    VCPropertiesGroup group;
28};

and the plugin.cpp file should now look like this:

1#include "StdAfx.h"
2#include "plugin.h"
3#include <cstdlib>
4#include <algorithm>
5#include <assert.h>
6
7namespace dcom = Dewesoft::Utils::Dcom::Utils;
8
9ProTutorialWidget::ProTutorialWidget()
10{
11}
12
13ProTutorialWidget::~ProTutorialWidget()
14{
15}
16
17void ProTutorialWidget::getPluginProperties(PluginProperties& props)
18{
19    props.name = "Pro tutorial";
20    props.description = "Pro tutorial example example";
21    props.maxAllowedInputChannels = 4;
22    props.width = 400;
23    props.height = 300;
24    props.extendOnAdd = true;
25    props.hasUnifiedProperties = true;
26    props.supportsFreezeMode = true;
27}
28
29void ProTutorialWidget::drawCanvasData(DrawDataParams& drawParams)
30{
31}
32
33void ProTutorialWidget::acceptInputSlots()
34{
35    InputSlots inputSlots = getInputSlots();
36    InputSlot slot = inputSlots.addSlot();
37    slot.setOnAcceptChannel([](IInputSlotPtr slot, IInputChPtr inputCh) {
38        return true;
39    });
40
41    slot.setOnAcceptGroup([](IInputSlotPtr slot, IInputGroupPtr inputGroup) {
42        return true;
43    });
44}
45
46void ProTutorialWidget::updateSetup(Setup& setup)
47{
48}
49
50void ProTutorialWidget::initVisualProperties(VCProperties& visualProperties)
51{
52}
53
54void ProTutorialWidget::updateVisualProperties(VCProperties& visualProperties)
55{
56}
57
58void ProTutorialWidget::visualPropertyChanged(std::string& groupId, VCProperty& visualProperty)
59{
60}
61
62void ProTutorialWidget::visualPropertyButtonClick(std::string& groupId, VCProperty& visualProperty, int buttonIndex)
63{
64}

When we now run the plugin you should get an empty black window when you add the widget to your display.

In order for our plugin to work it needs to communicate with Dewesoft. The plugin communicates with Dewesoft through files and functions found in Dewesoft_internals but we will access this code through functions and variables found in plugin.h and plugin.cpp files of the project. These files contain functions and events, that are triggered at a certain time (e.g. when measuring is started, when measuring is stopped, when setup is saved,...). 

In the rest of this section, we describe methods which were modified so our plugin works as it should. 

getPluginProperties

This method gets called when your plugin gets loaded into Dewesoft, this happens every time you start Dewesoft. The properties set in this method are set only once and cannot be changed later on. We can set the properties for the name and description of the widget, the default width and height of the window when widget is first added to the display and the number of channels the widget can display at once. SupportsFreezeMode property enables the widget to also have the data available in freeze mode. 

1void ProTutorialWidget::getPluginProperties(PluginProperties& props)
2{
3    props.name = "Pro tutorial";
4    props.description = "Widget example for Pro tutorial";
5    props.maxAllowedInputChannels = 4;
6    props.width = 400;
7    props.height = 300;
8    props.supportsFreezeMode = true;
9    props.extendOnAdd = true;
10    props.hasUnifiedProperties = true
11}

The last two properties to set affect the behavior of the widget when it is extended to contain multiple controls. These two properties are connected to the drawing region properties found in the upper part of the left panel that is seen when the widget is selected. You can add or remove the number of widget by clicking the  or  Controls buttons (see picture below). If the .extendOnAdd property is set to true, then when you add a new widget it is the same size as the first control. But if this property is set to false then both widgets get scaled to fit in the window of the size set for the first widget. 

These multiple widgets can have unified properties, this means that for example when a user sets the display color for one widget it gets changed for all of them or if the user changes the graph type from line to histogram then the type of the graph changes for all widgets. If we do not want to give the user the option to change widget setting uniformly then we set the .hasUnifiedProperties property to false. If this property is set to true the user can still manually disable it by unchecking the checkbox next to Unified properties (see picture below).

Widget

The very first procedure that gets called when a new widget is created. We will set the channel precision and font size to the default values and also check if the default values are correct

1ProTutorialWidget::ProTutorialWidget()
2{
3    userChannelPrecision = kDefaultChannelPrecision;
4    userFontSize = kDefaultFontSize;
5
6    assert(userChannelPrecision >= 0 && "Precision can not be smaller than 0.");
7    assert(userFontSize > 0  && "Font size must be greater than 0.");
8}

In order for the above code to work, we also need to define the variables we used in the header file of the plugin. To do that we will add the following code to the private section ProTutorialWidget class inside the plugin.h file.

1int kDefaultChannelPrecision = 3;
2int kDefaultFontSize = 36;
3
4int userChannelPrecision;
5int userFontSize;

acceptInputSlots

Our widget might not work for all channel types and we want to prevent the user from adding the channel to the widget as this may produce an error. In our example, we only want to display the scalar channels and not allow the user to choose to display vector or matrix channels. We also won't allow any channels groups.
In order to do that we use the acceptInputSlots() method. An input slot is a placeholder for an individual channel or channel group that can be assigned. This method gets called every time a channel is added from the widget. Every time an input slot gets assigned then a new one must be added. This is done with the addSlot() method. On this new input slot we define which channel types or group can be added. This is done with a lambda function for setOnAcceptChannel() and setOnAcceptGroup(). This function gets called for every channel and group available in the current setup of Dewesoft and if the return value for some channel or group is true it is then visible on the right panel of the display when the widget is selected. 

1void ProTutorialWidget::acceptInputSlots()
2{
3    InputSlots inputSlots = getInputSlots();
4    InputSlot slot = inputSlots.addSlot();
5
6    slot.setOnAcceptChannel([](IInputSlotPtr slot, IInputChPtr inputCh) {
7        return !inputCh->Ch->ArrayChannel;
8    });
9
10    slot.setOnAcceptGroup([](IInputSlotPtr slot, IInputGroupPtr inputGroup) {
11        return false;
12    });
13}

drawCanvasData

Now we are ready to actually visualize the data from our channels. This is done in the drawCanvasData() method which usually gets called with a rate of 50 Hz. This number depends on the refresh rate set in Dewesoft settings or current system performance. The input parameter of this method is a structure called DrawDataParams that holds the canvas, rect, and colorPalette. 

Before we continue with our example let us take a closer look at these parameters and how to use them.

The colorPalette parameter holds the information about common colors that all widgets use and are defined by the selected Dewesoft theme. The following colors are specified:

• backColor - the background color of the control

• highlightBackColor - the background color of controls that have some sort of user interaction or must be emphasized

• fontColor - the color of the font

• ticksColor - the color of axis ticks (if drawing graphs)

• subticksColor - the color of axis subticks (if drawing graphs)

The rect parameter holds the information of the location and size of the drawing region (rectangle) of the widget. The location of the rectangle is relative to the display, meaning that the upper left corner of the widget will always have coordinates (0, 0) no matter where on the display it is located. We will use the rect parameter to calculate the middle of the drawing region to determine where to display the text. 

1int x = int(round(rect.x + (rect.width - rect.x) / 2 - (canvas.getTextWidth(text) / 2)));    
2int y = int(round(rect.y + (rect.height - rect.y) / 2 - (canvas.getTextHeight(text) / 2)));

The canvas parameter holds the functions and properties used for drawing. The Font is used for setting the text, the Brush is used for setting the text and drawn objects (rectangle, circle, etc.) background the Pen is used for setting the borders of drawn objects (lines, rectangles, etc.) We can set the following properties:

Font:

• Color - the color of the font set as a long dcom::Color

• Style - the style of the font (bold, italic, underline, strikeout) set as a custom enum, you can combine them by creating a vector of styles like {cbsBold, cbsUnderline} 

• Size - the size of the font set in pixels as an integer

• Name - the name of the font family (arial, tahoma, sanserif, etc.) set as a string

Brush:

• Color - the color of the brush set as a long dcom::Color

• Style - the pattern for the brush (clear, solid, diagonal, vertical, etc.) set as a custom enum

Pen:

• Color - the color of the pen set as a long dcom::Color

• Style - the style in which the pen draws lines (solid, dot, dash, clear, etc.) set as a custom enum

• Width - the width of the pen in pixels set as an integer

• Mode - determine how the color of the pen interacts with the color on the canvas (always black, the inverse of canvas background color, unchanged, etc.)

Majority of the properties are of type integer and to make the code more descriptive we use predefined custom enums to set them. All enums follow the same naming principle, the prefix of the enum is the first letters of the property you want to set (the prefix of the enum for setting canvas.getPen().setMode to cpm) followed by the general name of the setting. For example, if we want to set the font style to bold we would write canvas.getFont().setStyle({cfsBold}) or if we want to set the pen style to dashed we would write canvas.getPen().setStyle({cpsDash}).

The properties of the font, brush, and pen have to be set before we start drawing to the canvas as our drawing functions will use them to draw the objects. To draw on the canvas we use the predefined functions. If we want to just write a text to our widget we use the textOut() or textRect(). The difference between these two functions is that the textRect() function outputs the text inside a rectangle if the text is too long for the rectangle it gets clipped to fit inside it. We can also draw a rectangle: use the rectangle() function, an ellipse: use the ellipse() function, and a line: use the moveTo() and lineTo() functions. The input parameters to all of these functions is the location of the object.

To get all the input channels the user selected to show on the widget we use the getInputChannels() method and to get the current value of the channel we use the getCurrentValue() method on the channel to read the value from.

In our example, we will just write the current value of the input channel to the canvas. We will use the textOut() function and we will set the font color to match the color of the channel and the brush style to be clear. The full code in the drawCanvasData() should look like this.

1void ProTutorialWidget::drawCanvasData(DrawDataParams& drawParams)
2{
3    if (getInputChannels().getCount() < 1)
4        return;
5
6    Canvas& canvas = drawParams.canvas;
7    Rect& controlRect = drawParams.rect;
8    Channel& channel = getInputChannels()[0];
9
10    double currentValue = channel.getCurrentValue();
11    std::wstring text = (std::wstringstream() << std::setprecision(userChannelPrecision) << std::fixed << currentValue).str();
12
13    canvas.getFont().setSize(userFontSize);
14
15    int x = int(round(controlRect.x + (controlRect.width - controlRect.x) / 2 - (canvas.getTextWidth(text) / 2)));
16    int y = int(round(controlRect.y + (controlRect.height - controlRect.y) / 2 - (canvas.getTextHeight(text) / 2)));
17
18    canvas.getFont().setColor(channel.getMainDisplayColor());
19    canvas.getBrush().setStyle(cbsClear);
20    canvas.textOut(x, y, text);
21}

updateSetup

Even though the user can not change the precision of the channel or the font size of the text just yet (we will do this in the next section of this tutorial) we still want our plugin to remember and set these values if we save or load the setup with our widget. Saving or loading a variable is done with the update() function on setup.

• The first parameter of the function is the name of XML element under which your setting is saved. This parameter should be unique for every setting.

• The second parameter is the actual value to be stored.

• The optional third parameter specifies what the default value should be.

Updating our settings inside plugin.cpp file is done in updateSetup() as seen in the code below.

1void ProTutorialWidget::updateSetup(Setup& setup)
2{
3    setup.update("fontSize", userFontSize);
4    setup.update("channelPrecision", userChannelPrecision);
5}

If we now run the plugin by pressing F5 and go to measure tab we can add our widget to the display. On the picture below you can see how the widget looks like. The channel outputted on the widget is the time signal, you can create it in the Ch. Setup -> Math -> Formula and under Signals tab choosing time signal.

But what if the user wants a bigger font for the text or wants the output to have more digits. We can add an option to allow the user to change those settings. We do this by defining the visual properties that can be seen on the left panel when the widget is selected. We will add a drop-down menu for allowing users to change the font size and a text box for allowing the user to change the precision of the channel. We will also add a reset button to reset the changed values back to default.

We will define these visual properties as a struct of the type VisualProperties in the plugin.h file

1struct VisualProperties
2{
3    static constexpr char FontSizeSelect[] = "FontSizeSelect";
4    static constexpr char ResetButton[] = "ResetButton";
5    static constexpr char PrecisionEdit[] = "PrecisionEdit";
6};

In the background, Dewesoft searches and uses these properties by its names defined as strings.

initVisualProperties

We initialize the visual properties we want to add to our widget in the initVisualProperties method. We add them to a group that we can name. We can create as many groups as we want to visually group the properties and make them easier to use. 

As mentioned before, we will add a drop-down menu, a text box, and a button. All the visual properties are added to the panel with add...Property(const std::string& propertyId, const std::wstring& name) functions. The first parameter of the function is a string name of the property and the second parameter is the text we want to display next to the property.

We add the drop-down menu with addSelectProperty() function. To add the available font sizes to the drop-down we use the add() call, we add the sizes as strings. 

To add the text box for precision we call the addFloatProperty() function which adds a text box that only allows number inputs. We also set the minimal and maximal number of decimal points we will allow users to input using the minValue and maxValue properties of the FloatProperty. If the user inputs invalid precision number the plugin will not take into account the property change. 

The reset button is added to the panel with addLabelProperty() function call. We still need to then add a button to this property with addButton() function, the first parameter of the function is a hint and the second is the name of the icon. The addButton() function is only available on the label property.

1void ProTutorialWidget::initVisualProperties(VCProperties& visualProperties)
2{
3    group = visualProperties.addOrFindGroup("Advanced");
4    group.setName(L"Drawing Options");
5
6    SelectVCProperty fontSizeDropDown(group.addSelectProperty(VisualProperties::FontSizeSelect, L"Font size"));
7    fontSizeDropDown.add(L"36");
8    fontSizeDropDown.add(L"40");
9    fontSizeDropDown.add(L"44");
10    fontSizeDropDown.add(L"48");
11
12    FloatVCProperty precisionEdit(group.addFloatProperty(VisualProperties::PrecisionEdit, L"Number of decimals"));
13    precisionEdit.setMinValue(0);
14    precisionEdit.setMaxValue(15);
15
16    LabelVCProperty resetButton(group.addLabelProperty(VisualProperties::ResetButton, L"Reset to default"));
17    resetButton.addButton(L"Reset properties to default", "REFRESH");
18}

updateVisualProperties

The updateVisualProperties() procedure gets called immediately after initVisualProperties() and every time after a visual property changes on visualPropertyChanged(). Here we set the values of the properties, but they must be initialized beforehand. We will set the drop-down menu's chosen item to the value saved in the userFontSize variable and we will display the userChannelPrecision value in the precision text box.

1void ProTutorialWidget::updateVisualProperties(VCProperties& visualProperties)
2{
3    group = visualProperties.findGroup("Advanced");
4
5    SelectVCProperty fontSizeDropDown(group.findProperty(VisualProperties::FontSizeSelect));
6    if (fontSizeDropDown.isAssigned())
7    {
8        std::wstring fontSizeText = std::to_wstring(userFontSize);
9        fontSizeDropDown.setItemIndex(0);
10        for (int i = 0; i < fontSizeDropDown.getCount(); i++)
11        {
12            if (fontSizeDropDown.getItem(i) == fontSizeText)
13            {
14                fontSizeDropDown.setItemIndex(i);
15                userFontSize = std::stoi(fontSizeDropDown.getItem(i));
16            }
17        }
18    }
19
20    FloatVCProperty precisionEdit(group.findProperty(VisualProperties::PrecisionEdit));
21    if (precisionEdit.isAssigned())
22        precisionEdit.setValue(userChannelPrecision);
23}

visualPropertyChanged

The procedure which gets called every time a property changes, for example when the user chooses a different font size in the drop-down menu or when they input a new valid precision. We check which property has changed and assign the changed property value to the corresponding variable.

1void ProTutorialWidget::visualPropertyChanged(std::string& groupId, VCProperty& visualProperty)
2{
3    std::string propID = visualProperty.getId();
4
5    if (propID == VisualProperties::PrecisionEdit)
6    {
7        FloatVCProperty precisionText(visualProperty);
8        userChannelPrecision = precisionText.getValue();
9    }
10    else if (propID == VisualProperties::FontSizeSelect)
11    {
12        SelectVCProperty select(visualProperty);
13        userFontSize = std::stoi(select.getItem(select.getItemIndex()));
14    }
15}

visualPropertyButtonClick

Every time a button on the visual property panel is clicked the visualPropertyButtonClick() procedure gets called. In our case, we will set the font size and precision back to default when the user clicks the reset button.

1void ProTutorialWidget::visualPropertyButtonClick(std::string& groupId, VCProperty& visualProperty, int buttonIndex)
2{
3    FloatVCProperty precisionText(group.findProperty(VisualProperties::PrecisionEdit));
4    if (precisionText.isAssigned())
5    {
6        precisionText.setValue(kDefaultChannelPrecision);
7        userChannelPrecision = kDefaultChannelPrecision;
8    }
9    SelectVCProperty fontSizeDropDown(group.findProperty(VisualProperties::FontSizeSelect));
10    if (fontSizeDropDown.isAssigned())
11    {
12        fontSizeDropDown.setItemIndex(0);
13        userFontSize = kDefaultFontSize;
14    }
15}

After all the previous steps our custom widget will look like this:

The input channels our widget accepts are scalar channels and the user can change the font size, precision and then with a click of the button resets the changes back to default values.

In the previous sections of this tutorial, we created a very simple digital meter that accepts scalar channels and displays the current value of the channel. But let us now move on to a more complicated example. 

We will implement a horizontal bar graph with the value of the channel written at the beginning of the bar and the value visually represented with the fullness of the bar. This widget will accept multiple channels of scalar, vector or matrix type. We will allow the user to set the font size of the text displaying the channel name and the minimum and maximum value of the channel. The user could also choose if they want to use the set minimum and maximum value of the channel. We will also add a reset button for resetting settings back to default.

In the end, our widget will look like this:

To create this widget, we can create an entirely new plugin or change the one we have. In any case, we should again remove all the code from our plugin and the plugin.h and plugin.cpp files should again look like this. 

getPluginProperties

For this example we will set the plugin properties to allow multiple input channels to be displayed at once, we will allow the maximum number of input channels to be 4 and we will also make the default window size of the widget a little bit bigger than in the previous case. 

1void ProTutorialWidget::getPluginProperties(PluginProperties& props)
2{
3    props.name = "Pro tutorial";    
4    props.description = "Widget example for Pro tutorial";
5    props.maxAllowedInputChannels = 4;
6    props.width = 400;
7    props.height = 300;
8    props.extendOnAdd = true;
9    props.hasUnifiedProperties = true;
10    props.supportsFreezeMode = true;
11}

As mentioned we will allow the user to choose the minimum and maximum value of the channel, this is why we have to add the variables to hold this values to the private section of the ProTutorialWidget class in the plugin.h file. At this point we will also add the variables to hold the information for the font size and whether or not to use the limits for the channel value the user selected.

1int userFontSize = 12;
2bool useManualLimits = false;
3double minChannelValue = -10.0;
4double maxChannelValue = 10.0;

Widget

In the constructor of the class, we will check if the minimum and maximum channel values we defined are valid.

1ProTutorialWidget::ProTutorialWidget()
2{
3    assert(minChannelValue <= maxChannelValue && "Minimum channel value cannot be greater than maximum channel value.");
4}

acceptInputSlots

As mentioned we will create a widget that can display all channel types this is why we will just simply allow all the channels found in the current setup to be the input channels to our widget.

1void ProTutorialWidget::acceptInputSlots()
2{
3    InputSlots inputSlots = getInputSlots();
4    InputSlot slot = inputSlots.addSlot();
5
6    slot.setOnAcceptChannel([](IInputSlotPtr slot, IInputChPtr inputCh) {
7        return true;
8    });
9 
10    slot.setOnAcceptGroup([](IInputSlotPtr slot, IInputGroupPtr inputGroup) {
11        return false;
12    });
13}

updateSetup

When loading the setup with our widget we want to also load the information of the font size, the minimum and maximum value of the channel and whether or not to use the limits. In order to do that we need to update the variables that hold this information in the updateSetup() method.

1void ProTutorialWidget::updateSetup(Setup& setup)
2{
3    setup.update("fontSize", userFontSize);
4    setup.update("minChannelValue", minChannelValue);
5    setup.update("maxChannelValue", maxChannelValue);
6    setup.update("useManualLimits", useManualLimits);
7}

The drawCanvasData() function will be a little more complicated than in the example before. To make it a little more understandable we will split the code into multiple smaller functions performing only a specific task. The main drawCanvasData()  function and the corresponding helper functions are written and explained in the next section.

In the code for drawing the widget, we will use a lot of constant values for variables like horizontal and vertical spacing between two objects, the height of the bar, etc. We will define these values as constants in the private section of the ProTutorialWidget class in the plugin.h file, to distinguish them from other variables we will use the prefix "k". The names of the constants should be descriptive enough for other developers to know what they mean and what they are used for when they see them.

1const int kBarHeight = 18;
2
3const int kYSpacing = 30;
4const int kXSpacing = 30; 
5 
6const int kTitleFontSize = 10;
7const int kValueFontSize = 8;
8
9const double kValidatorMaxLimit = 1000;
10const double kValidatorMinLimit = -1000;

The main drawCanvasData() function for our example will look like this:

1void ProTutorialWidget::drawCanvasData(DrawDataParams& drawParams)
2{
3    Canvas& canvas = drawParams.canvas;
4    Rect& controlRect = drawParams.rect;
5
6    int yScreenCoordinate = kYSpacing;
7    Rect titleRect(0, 0, controlRect.width, yScreenCoordinate);
8
9    drawGraphTitle(drawParams, titleRect, L"Widget example");
10    yScreenCoordinate += kYSpacing;
11
12    size_t maxChannelsOnVisibleArea = (size_t)round(controlRect.height / kYSpacing);
13
14    int channelIndex = 0;
15    ChannelList inputChannels = getInputChannels();
16    while ((channelIndex < inputChannels.getCount()) && (maxChannelsOnVisibleArea > 0))
17    {
18        Channel channel = inputChannels[channelIndex];
19
20        drawChannelName(channel, drawParams, kXSpacing, yScreenCoordinate);
21        yScreenCoordinate += canvas.getTextHeight(channel.getName());
22
23        drawChannelValue(channel, drawParams, controlRect.width, yScreenCoordinate, maxChannelsOnVisibleArea);
24        yScreenCoordinate += channel.getArraySize() * kYSpacing;
25        channelIndex++;
26    }
27}

As we can see we will create two local variables one to remember the index of the last displayed channel and the other to keep track of how much horizontal space on the widget we already used. We will also create a title rectangular for displaying the global title of the widget and display it with the drawGraphTitle() function that we implemented ourselves. We will also implement a function for drawing the current channel's name, value and unit. Our functions for drawing are defined in the private section of the ProTutorialWidget  class in the plugin.h file. We will also need a lot of additional helper functions, you can see their definitions in the code below. 

1class ProTutorialWidget : public Dewesoft::Widgets::Api::Widget
2{
3public:
4    // ...
5
6private:
7    // ...
8
9    double getChannelMinValue(Channel& ch);
10    double getChannelMaxValue(Channel& ch);
11
12    int getCenterTextCoordinate(DrawDataParams& drawParams, Rect& rect, const std::wstring& text);
13    int getBarWidth(double currentValue, double minValue, double maxValue, Rect& barRect);
14
15    void drawBar(Channel& channel, size_t arrayIndex, DrawDataParams& drawParams, Rect& barRect);
16    void drawGraphTitle(DrawDataParams& drawParams, Rect& titleRect, const std::wstring& text);
17    void drawChannelName(Channel& channel, DrawDataParams& drawParams, int x, int y);
18    void drawChannelValue(Channel& channel, DrawDataParams& drawParams, int controlRectWidth, int y, size_t& maxChannelsOnVisibleArea);
19
20    std::wstring buildBarText(Channel& channel, size_t arrayIndex, double currentValue);
21    void drawUnit(Channel& channel, DrawDataParams& drawParams, Rect& barRect);
22
23    std::wstring getChannelAxisValue(Channel& ch, int axisIndex, int index);

1void ProTutorialWidget::drawGraphTitle(DrawDataParams& drawParams, Rect& titleRect, const std::wstring& text) 
2{
3    Canvas& canvas = drawParams.canvas;
4    ColorPalette& colorPalette = drawParams.colorPalette;
5    CanvasTextFormats textFormat = { ctfCenter };
6
7    int textCenterXY = getCenterTextCoordinate(drawParams, titleRect, text);
8
9    CanvasFont& canvasFont = canvas.getFont();
10    canvasFont.setSize(kTitleFontSize);
11    canvasFont.setColor(colorPalette.fontColor);
12    canvas.getBrush().setStyle(cbsClear);
13    canvas.textRect(titleRect.x, textCenterXY, titleRect.width, titleRect.height, text, textFormat); 
14}

The drawGraphTitle() function accepts drawParams, title rectangle, and title text as parameters and it draws the text inside a textRect(). We want to output the text in the center on the top of the rectangle. The center of the rectangular is calculated with the getCenterTextCoordinate() function whose implementation looks like this.

1int ProTutorialWidget::getCenterTextCoordinate(DrawDataParams& drawParams, Rect& rect, const std::wstring& text)
2{
3    return int(round(rect.y + (rect.height - rect.y) / 2 - (drawParams.canvas.getTextHeight(text) / 2)));
4}

1void ProTutorialWidget::drawChannelName(Channel& channel, DrawDataParams& drawParams, int x, int y)
2{
3    Canvas& canvas = drawParams.canvas;
4    CanvasFont& canvasFont = canvas.getFont();
5    canvasFont.setSize(userFontSize);
6    canvasFont.setColor(channel.getMainDisplayColor());
7    canvas.getBrush().setStyle(cbsClear);
8    canvas.textOut(x, y, channel.getName());
9}

The drawChannelName() is a very simple function that sets the font size and color of the text we want to display and then displays the name of the current channel. The position of the text is calculated beforehand in the drawCanvasData() function.

1void ProTutorialWidget::drawChannelValue(Channel& channel, DrawDataParams& drawParams, int controlRectWidth, int y, size_t& maxChannelsOnVisibleArea)
2{
3    Rect barRect(kXSpacing, y, controlRectWidth - 4 * kYSpacing, kBarHeight);
4
5    drawUnit(channel, drawParams, barRect);
6
7    size_t arrayIndex = 0;
8    while ((arrayIndex < static_cast<size_t>(channel.getArraySize())) && (maxChannelsOnVisibleArea > 0))
9    {
10        drawBar(channel, arrayIndex, drawParams, barRect);
11        maxChannelsOnVisibleArea--;
12        arrayIndex++;
13    }
14}

Now we just need to draw the channel value inside a bar. The bar will be represented as a rectangular and inside of it we first draw the value of the channel and then fill the rectangular to match the channel value. We will create an additional function drawBar() for drawing the actual bar. We also add additional helper functions getBarWidth() for calculating how much of the bar we have to fill, buildBarText() for reading the correct text from the channel and getChannelAxisValue() if the input channel is vector or matrix to read the values from the axis. The drawChannelValue() function gets called for every channel that will be displayed on our widget. If the channel is of vector or matrix type then we will display every axis value as its own bar with name and unit. We also need to keep track of how many channels we been already drawn on widget because we do not want to draw a channel on an area of the widget that can not be seen by the user.

1void ProTutorialWidget::drawUnit(Channel& channel, DrawDataParams& drawParams, Rect& barRect) 
2{ 
3    Canvas& canvas = drawParams.canvas;
4    CanvasFont canvasFont = canvas.getFont();
5    ColorPalette& colorPalette = drawParams.colorPalette;
6
7    canvasFont.setSize(kValueFontSize);
8    canvasFont.setColor(colorPalette.fontColor);
9    canvas.getBrush().setStyle(cbsClear);
10    canvas.textOut(barRect.x + barRect.width + 10, barRect.y, channel.getUnit());
11}

The drawUnit() is again a very simple function that sets the font size and color and displays the unit of the channel at the end of the bar.

1void ProTutorialWidget::drawBar(Channel& channel, size_t arrayIndex, DrawDataParams& drawParams, Rect& barRect)
2{
3    Canvas& canvas = drawParams.canvas;
4    CanvasFont canvasFont = canvas.getFont();
5    CanvasBrush canvasBrush = canvas.getBrush();
6    CanvasPen canvasPen = canvas.getPen();
7    ColorPalette& colorPalette = drawParams.colorPalette;
8
9    double maxValue = getChannelMaxValue(channel);
10    double minValue = getChannelMinValue(channel);
11
12    double currentValue = channel.getCurrentValue(static_cast<int>(arrayIndex));
13
14    canvasBrush.setColor(colorPalette.backColor);
15    canvasPen.setColor(colorPalette.fontColor);
16    canvas.rectangle(barRect.x, barRect.y, barRect.x + barRect.width, barRect.y + barRect.height);
17
18    canvasBrush.setColor(channel.getMainDisplayColor());
19    canvasPen.setColor(colorPalette.fontColor);
20    canvas.fillRect(barRect.x + 1, barRect.y + 1, getBarWidth(currentValue, minValue, maxValue, barRect), barRect.y + barRect.height);
21
22    canvasFont.setSize(kValueFontSize);
23    canvasFont.setColor(dcom::Color::White);
24    canvasBrush.setStyle(cbsClear);
25    canvas.textOut(barRect.x + 2, barRect.y + 2, buildBarText(channel, arrayIndex, currentValue));
26
27    barRect.y += kYSpacing;
28}

The drawBar() function draws the value of the channel and fills the bar in the ratio to the value and the minimal and maximal value of the channel. To draw a the container of the bar we use the rectangle() function with the specified rectangle dimensions. To fill the bar (rectangle) we use the fillRect() function and with the helper function getBarWidth() we calculate the point to which the bar needs to be filled. We will also write a getter function for reading the minimum and maximum values of the channel whether they are user-defined or default.

1double ProTutorialWidget::getChannelMinValue(Channel& ch)
2{
3    if (useManualLimits)
4        return minChannelValue;
5    else
6        return ch.getTypicalMinValue();
7}
8
9double ProTutorialWidget::getChannelMaxValue(Channel& ch)
10{
11    if (useManualLimits)
12        return maxChannelValue;
13    else
14        return ch.getTypicalMaxValue();
15}
16
17int ProTutorialWidget::getBarWidth(double currentValue, double minValue, double maxValue, Rect& barRect) 
18{ 
19    currentValue = std::clamp(currentValue, minValue, maxValue);
20    int currentValueInPixels = (maxValue - minValue == 0.0) ? 0 : static_cast<int>(round((currentValue - minValue) / (maxValue - minValue) * barRect.width));
21    return barRect.x + currentValueInPixels - 1;
22} 
23
24std::wstring ProTutorialWidget::buildBarText(Channel& channel, size_t arrayIndex, double currentValue) 
25{ 
26    if (channel.getArrayChannel()) 
27        return getChannelAxisValue(channel, 0, arrayIndex) + L": " + std::to_wstring(currentValue);
28    else
29        return std::to_wstring(currentValue); 
30}

Because array channels have axis values we also need to add a function for reading the values. Array channels can have multiple axes so we need to specify the index of which axis information we would like to access in the getAxisDefinition() function. The axis values can be of three types: string, float or a linear function but we don't need to worry about that because the  getAxisValue() function will handle all that for us and return the correct axis value based on its type.

1std::wstring ProTutorialWidget::getChannelAxisValue(Channel& ch, int axisIndex, int index)
2{
3    AxisDefiniton axisDef = ch.getArrayInfo().getAxisDefinition(axisIndex);
4    return axisDef.getAxisValue(index);
5}

Our widget will now show the data like this:

The image shows two input channels both of them are the output channels of the FFT Analyser with one begin scalar channel (FFT block count) and the other one being a vector channel (AI 1/AmplFFT).

The last thing we need to do now is add the visual properties for manipulating our widget. We will add a drop-down menu for choosing the font size, a checkbox for choosing whether or not to use manual minimum and maximum limits, two text boxes for inputting the limits, and a reset button for resetting the changed properties back to default. In the end, our left panel should look like this:

As before we will first define these visual properties as enums of the type VisualProperties in the plugin.h file 

1struct VisualProperties
2{
3    static constexpr char MinEditText[] = "MinEditText";
4    static constexpr char MaxEditText[] = "MaxEditText";
5    static constexpr char FontSizeSelect[] = "FontSizeSelect";
6    static constexpr char ResetLabel[] = "ResetLabel";
7    static constexpr char ManualLimitsCheckbox[] = "ManualLimitsCheckbox";
8};

initVisualProperties

We will initiate the visual properties the same way we did in the first example. The drop-down menu, the reset button, and the text box are all properties we used before. We need to add a checkbox with addCheckBoxProperty().

1void ProTutorialWidget::initVisualProperties(VCProperties& visualProperties)
2{
3    group = visualProperties.addOrFindGroup("Advanced");
4    group.setName(L"Drawing Options");
5    SelectVCProperty fontSizeDropDown(group.addSelectProperty(VisualProperties::FontSizeSelect, L"Font size"));
6    fontSizeDropDown.add(L"12");
7    fontSizeDropDown.add(L"14");
8    fontSizeDropDown.add(L"16");
9    fontSizeDropDown.add(L"18");
10
11    group.addCheckBoxProperty(VisualProperties::ManualLimitsCheckbox, L"Use manual limits");
12    group.addFloatProperty(VisualProperties::MaxEditText, L"Max channel value");
13    group.addFloatProperty(VisualProperties::MinEditText, L"Min channel value");
14    LabelVCProperty labelButton(group.addLabelProperty(VisualProperties::ResetLabel, L"Reset to default"));
15    labelButton.addButton(L"Reset properties to default", "REFRESH");
16}

Before we look at the other functions we still need to implement, we will add functions for updating the validators for minimum and maximum channel values. We need to make sure that the minimum channel value is always lower than the maximum channel value. We will also enable or disable the text boxes based on the users choice to use the manual limits or not.

Our functions for setting the validator are defined in the private section of the ProTutorialWidget class in the plugin.h file.

1class ProTutorialWidget : public Dewesoft::Widgets::Api::Widget { public:    
2    // ...
3 private:    
4    // ... 
5    void updateMinEditValidator(); 
6    void updateMaxEditValidator();  
7}

The implementation of the functions in the plugin.cpp file looks like this:

1void ProTutorialWidget::updateMinEditValidator()
2{
3    FloatVCProperty minEditText(group.findProperty(VisualProperties::MinEditText));
4    if (minEditText.isAssigned())
5    {
6        minEditText.setMinValue(kValidatorMinLimit);
7        minEditText.setMaxValue(maxChannelValue);
8        minEditText.setEnabled(useManualLimits);
9    }
10}
11
12void ProTutorialWidget::updateMaxEditValidator()
13{
14    FloatVCProperty maxEditText(group.findProperty(VisualProperties::MaxEditText));
15    if (maxEditText.isAssigned())
16    {
17        maxEditText.setMinValue(minChannelValue);
18        maxEditText.setMaxValue(kValidatorMaxLimit);
19        maxEditText.setEnabled(useManualLimits);
20    }
21}

updateVisualProperties

We update all the visual properties to the value of the corresponding variables.

1void ProTutorialWidget::updateVisualProperties(VCProperties& visualProperties)
2{
3    group = visualProperties.findGroup("Advanced");
4
5    CheckBoxVCProperty manualLimitsCheckbox(group.findProperty(VisualProperties::ManualLimitsCheckbox));
6    if (manualLimitsCheckbox.isAssigned())
7        manualLimitsCheckbox.setChecked(useManualLimits);
8
9    FloatVCProperty minEditText(group.findProperty(VisualProperties::MinEditText));
10    if (minEditText.isAssigned())
11    {
12        minEditText.setValue(minChannelValue);
13        updateMaxEditValidator();
14    }
15
16    FloatVCProperty maxEditText(group.findProperty(VisualProperties::MaxEditText));
17    if (maxEditText.isAssigned())
18    {
19        maxEditText.setValue(maxChannelValue);
20        updateMinEditValidator();
21    }
22
23    SelectVCProperty fontSizeDropDown(group.findProperty(VisualProperties::FontSizeSelect));
24    if (fontSizeDropDown.isAssigned())
25    {
26        std::wstring fontSizeText = std::to_wstring(userFontSize);
27        fontSizeDropDown.setItemIndex(0);
28        for (int i = 0; i < fontSizeDropDown.getCount(); i++)
29        {
30            if (fontSizeDropDown.getItem(i) == fontSizeText)
31            {
32                fontSizeDropDown.setItemIndex(i);
33               userFontSize = std::stoi(fontSizeDropDown.getItem(i));
34            }
35        }
36    }
37}

visualPropertyChanged

When one of the visual properties changes we save the new value of the property to a corresponding variable.

1void ProTutorialWidget::visualPropertyChanged(std::string& groupId, VCProperty& visualProperty)
2{
3    std::string propID = visualProperty.getId();
4
5    if (propID == VisualProperties::ManualLimitsCheckbox)
6    {
7        CheckBoxVCProperty manualLimitsCheckbox(visualProperty);
8        useManualLimits = manualLimitsCheckbox.getChecked();
9    }
10    else if (propID == VisualProperties::MinEditText)
11    {
12        FloatVCProperty minText(visualProperty);
13        minChannelValue = minText.getValue();
14    }
15    else if (propID == VisualProperties::MaxEditText)
16    {
17        FloatVCProperty maxText(visualProperty);
18        maxChannelValue = maxText.getValue();
19    }
20    else if (propID == VisualProperties::FontSizeSelect)
21    {
22        SelectVCProperty select(visualProperty);
23        userFontSize = std::stoi(select.getItem(select.getItemIndex()));
24    }
25}

visualPropertyButtonClick

When the user clicks the reset button we will call a function resetPropertiesToDefault() to set the visual properties back to default.

1void ProTutorialWidget::visualPropertyButtonClick(std::string& groupId, VCProperty& visualProperty, int buttonIndex)
2{
3    if (visualProperty.getId() == VisualProperties::ResetLabel)
4        resetPropertiesToDefault();
5}

The function should first be defined in the private section of the ProTutorialWidget class in the plugin.h file. 

1class ProTutorialWidget: public Dewesoft::Widgets::Api::Widget
2{
3public:
4    // ...
5
6private
7    // ...
8    void resetPropertiesToDefault();
9}

The implementation of the function in the plugin.cpp file looks like this:

1void ProTutorialWidget::resetPropertiesToDefault()
2{
3    FloatVCProperty minEditText(group.findProperty(VisualProperties::MinEditText));
4    if (minEditText.isAssigned())
5    {
6        minEditText.setValue(0);
7        minChannelValue = 0.0;
8    }
9
10    FloatVCProperty maxEditText(group.findProperty(VisualProperties::MaxEditText));
11    if (maxEditText.isAssigned())
12    {
13        maxEditText.setValue(0);
14        maxChannelValue = 0.0;
15    }
16
17    SelectVCProperty fontSizeDropDown(group.findProperty(VisualProperties::FontSizeSelect));
18    if (fontSizeDropDown.isAssigned())
19    {
20        fontSizeDropDown.setItemIndex(0);
21        userFontSize = 12;
22    }
23}

After all the steps in the previous sections, we should get a widget that looks like this. It accepts input channels of any type (scalar, vector or matrix) and displays the current value of the channel or the axis and the channel name and unit. It also displays the title of the graph. User can change the font type and set manual minimum and maximum limits of the channel. We also added a reset button to reset the changed values back to default. 

The channels displayed on the image above are the time signal and the output channels from the FFT Analysis when the acquisition sample rate is set to 100 and the resolution of the FFT is set to 5 lines.

In this Pro Training, we have created two new widgets. We might want to use them in other setups or on other computers. C++ Widget Plugin packs your plugin into an external library, which can be inserted into any Dewesoft around the world.

Your C++ Widget Plugin is found inside a file with .vc extension (it contains instructions that Dewesoft can call upon to do certain things, based on the purpose of your plugin). To export it, you need to locate these files first. It can be found inside DEWESoftX\DEWEsoft\Bin\Addons folder in a folder with the same name as the plugin base class name.

To import your plugin you have to copy and paste a file with .vc extension into any Dewesoft that requires your plugin. You need to paste it inside Addons folder so Dewesoft will be able to automatically recognize and load it.