Create a Custom Widget

If you decide that you need a widget with features that cannot be built in the Idea Studio, you can extend a widget that was started there or write a completely new one.

The module must be declared in the [(65282) group of the application's AppRoot.SRC file:

  [ (65282)
    QuickPump Module "Widgets\QuickPump.SRC";
    QuickValve Module "Widgets\QuickValve.SRC";
  ]

You have a choice when it comes to linking your custom widget to your custom tag. You can declare the widget in the [(Graphics) section of your custom tag.

[ (GRAPHICS)
    Shared QuickPump;

Or, you can work within the widget to declare the list of tags to which that widget can be linked. Note that this task is best done within the Idea Studio, using the Tag Types tool of the Widget Properties ribbon.

  Shared DrainValve (POINTS);
  Shared AnalogStatus(POINTS);

This option is the only one available for linking a custom widget to a VTScada tag. You cannot modify the source code for any of the built-in tags to add your custom widget to its list of graphics.

Each widget must have its own module, where there is one widget per module. This may be a submodule of your tag or more commonly, a separate file.

The following are common elements of a custom widget. Required elements are noted.

Optional: Module reference box coordinates.

All of the VTScada widget modules begin with reference box coordinates. While not mandatory, and not part of widgets created in the Idea Studio, you should consider adding these. See: Reference Boxes and Scaling.

(0, 160, 160, 0) { Meter 1 reference box }

Parameters for configuring the object.

At a minimum, these should include the Disable options for operator-interface controls. "Status" is a keyword, flagging these parameters as Boolean.

(
  DisableTrend      Status;
  DisableNavigation Status;
  DisableTooltip    Status;
)

Create a parameter for every aspect of the widget, over which developers will have control. For example, the CommLine widget has parameters for three colors and pen orientation

DrawLabel constant

The name of the module will be taken as the name of the widget unless you specify otherwise with a constant declaration named "DrawLabel". This should refer to a property that you add to your Settings.Dynamic file.

  Constant  DrawLabel = "MyWidgetLabel";

In an Idea Studio widget, the keyword Title will be used and will use whatever was assigned when the widget was created. If there is a chance that your widget will be used for alternate languages then you are urged to replace Title with DrawLabel as described here.

Other variables and constants as required

If you intend to provide a configuration panel where developers can set values for the widget's parameters, then it is common to create constants that determine the size of that panel. A widget's configuration panel is created in exactly the same way as a tag's configuration panel, therefore you must also create constants enumerating the parameters, just as is done for tag parameters.

Optional: Initialization state

If used, this will set default values if required (colors, fonts, sizes, etc.) and call's the module's main state.

Main state

The main state should include the steady state graphics command that define the drawing object.

The main state must also launch a call to the tag's Common module.

Optional: Panel submodule

A submodule named "Panel" should be included if the widget has parameters. If a Panel module is not supplied, VTScada will generate a basic configuration box for the parameters when the object is placed on the screen.

Panel must be declared with one parameter, Parms. This will be a pointer to an array that contains the initial values of the tag's parameters and that will be modified to contain the values entered by the user while editing.

You will need to create a Menu Item tag for your widget if you want to see it in any of the Idea Studio palettes. This is done automatically for widgets created in the Idea Studio.