Adding Controls Via Script

You can dynamically add controls to a screen via script during runtime. This allows you to create a control from Canvas.Controls or other plugin control assemblies you may have added to Canvas.

Some potential reasons why you might want to do this include:

• Improve screen templating. By adding scripted controls, you can take screen templating to a new level via dynamic screens. For example, you could create a well-pad screen that queries facilities and facility attributes and builds itself on-the-fly.
• Limit screen size and time-to-load. You could use custom annotations to build a dynamic screen without increasing screen size or time-to-load. For example, you could create a dense piping and instrumentation diagram (P&ID) type screen with hundreds of Text Tools that creates (and removes) additional visual elements for alarm indication, without doubling or tripling the number of controls on the screen.

Before You Start

• Load the Windows Software Developer Pack and Development Kit (SDK), required to manage and reference system assemblies. See the Canvas System Requirements where the SDK is called out.
• See Managing Plugins and Managing External Assemblies for more information about using the Canvas Assembly Manager to view and select assemblies to make them available for use in script.

Example

Start with the following simple script example, which generally shows how to create and remove a control during runtime:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// we can get control view models via Objects.Screen.GetAllScreenControls(), but
// when adding/removing controls, we need access to the view, so it can be easier
// to maintain direct references to the view classes
 
private List<ICanvasControlView> _addedControls = new List<ICanvasControlView>();
 
private void AddControl(int x, int y)
{
    //create a variable with the control’s view
    var shape = new Canvas.Controls.Shape.CanvasShape();
     
    //create a variable with the control’s view model
    var shapeViewModel = shape.ViewModel as Canvas.Controls.Shape.CanvasShapeViewModel;
     
    //modify properties of the view model
    shapeViewModel.X = x;
    shapeViewModel.Y = y;
    shapeViewModel.Height = 20;
    shapeViewModel.Width = 20;
    shapeViewModel.LineStyle = Canvas.Controls.Shape.CanvasShapeViewModel.CanvasShapeLineStyle.Dotted;
     
    //add control’s view to screen
    Objects.Screen.AddControl(shape);
     
    //add control’s view to list to keep track of all added controls
    _addedControls.Add(shape);
}
 
private void RemoveAllControls()
{
    foreach (var controls in _addedControls)
    {
        Objects.Screen.RemoveControl(controls);
    }
    _addedControls.Clear();
}

Scripting Notes

The following notes will get you started.

Canvas.Helpers

The sample script has the following line:

5
private List<ICanvasControlView> _addedControls = new List<ICanvasControlView>();

ICanvasControlView requires that you add a using statement for Canvas.Helpers (using Canvas.Helpers) in order for this to work. The using statement for Canvas.Helpers goes with all of the other using statements at the very top of the script. The Canvas.Helpers assembly is added by default, but you need to add the using statement in order to address any errors ICanvasControlView may produce.

Adding Assemblies

When dynamically adding controls, you must add control assemblies as references for the screen. This is done via the Assembly Manager.

Once you have installed the Microsoft .NET Framework 4.7.2 Developer Pack or later , open the Assembly Manger for the scripted screen (click in the screen's toolbar).

Select System Assemblies and click Use default system path for .NET SDK.

All necessary assemblies will be listed, and you can select the required ones. Review any script errors to determine which assemblies are required. You will need to select those assemblies for inclusion.

Control View, ViewModel, Properties

In general, you must create a variable for the control’s view you are interested in, for example:

10
var shape = new Canvas.Controls.Shape.CanvasShape();

Then create a separate variable for the control’s view model, for example:

13
var shapeViewModel = shape.ViewModel as Canvas.Controls.Shape.CanvasShapeViewModel;

Then modify the view model’s properties with desired values, for example:

16
17
18
19
20
shapeViewModel.X = x;
shapeViewModel.Y = y;
shapeViewModel.Height = 20;
shapeViewModel.Width = 20;
shapeViewModel.LineStyle = Canvas.Controls.Shape.CanvasShapeViewModel.CanvasShapeLineStyle.Dotted;

Then add the control’s view to the screen, for example:

23
Objects.Screen.AddControl(shape);

Control View and ViewModel Location

Most of the control view and view models are located in the same general place (Canvas.Controls.<control>). However, the following controls deviate from this rule:

Chart

The Chart's View and ViewModel are located here:

• View — Canvas.Controls.GenericChart.View.GenericChart()
• ViewModel — Canvas.Controls.GenericChart.ViewModel.GenericChartViewModel

Navigator

The Navigator's View and ViewModel are located here:

• View — Canvas.Controls.Support.Navigator.NavigatorControl()
• View model — Canvas.Controls.Support.Navigator.NavigatorControlViewModel

Tag Chooser

The Tag Chooser's View and ViewModel are located here:

• View — Canvas.Controls.TagChooser.TagChooser()
• View model — Canvas.Shared.ViewModel.CanvasCygNetTagChooserViewModel