Using Canvas Controls and Objects

The Alarm Grid is a CygNet-aware control that supports the creation of customizable and interactive tables for the display and management of large amounts of alarm data in columns and rows. Five customizable column types are supported: Alarm, Facility, Generic, Point, and a column displaying an alarm icon, which can be customized based on alarm priority for unacknowledged alarms. Alarm columns are mapped to an alarm attribute; facility columns are mapped to a facility attribute; generic columns can display any kind of scripted data of your choice and its cells can be edited in run mode; and point columns are mapped to point attribute. Data can be filtered using custom alarm filtering rules. Cell background color, text color, and border color can be manually configured or sourced from the colors configured in the CygNet point scheme for single color, foreground color, or background color. Colors in the control can be overridden when a custom color palette is selected for the screen. You can also configure whether to display alarm acknowledgment as a blinking cell background, blinking text, or blinking border when a point is in alarm. A context menu is available in run mode to facilitate alarm acknowledgment, alarm clearing, alarm hiding, and ad hoc alarm suppression.

The Button is a CygNet-aware tool that can be used to add square or rectangular forms to your screens, which can be easily scripted to manage user interaction with CygNet data, for example, trigger an event, confirm an action, interact with other screen controls or other screens, or even start other applications. The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties. The control can be configured with a valid point configuration but prevented from retrieving any CygNet data, allowing the display of static text while still allowing CygNet data context available from script. The control's background, text, and border color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Alarm indication (blinking) is supported for the control's text and border when the associated point is in alarm. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. The mouse cursor that appears when the mouse hovers over the control is configurable. Font sizing, text styling, and text weighting are also configurable. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart. Buttons also support the addition of a configurable image.

The Chart is a CygNet-aware control that provides a customizable means to visualize point values and historical CygNet data in several types of charts. The Canvas chart is highly configurable and supports the following options: an unlimited number of series that can be styled as desired, optionally displaying historical rollup values; configurable date ranges, both relative and absolute; live data updates at a configured interval allowing the chart to trend data at a real-time pace; the display of time slices and tooltips; optional, configurable legend options (date and value format, dynamic text display based on real-time properties); configurable x- and y-axis features (label color, position, tick color, and title); a configurable toolbar and its position, and dragging, panning, and zooming in run mode. The chart supports CygNet data natively and non-CygNet data via script. Other run mode options include stopping/restarting live updates, changing the date and time range, saving/opening a chart's configuration as a default chart, printing the current chart, export as an image, and export data to a CSV file.

The Check Box can be used for a singular true or false option on a screen. Multiple check boxes may be added to any screen, but they operate independently of each other. The check box can be configured to display in a checked (true) state. You can also add a label to appear on the left or right of the check box and the font size of the label is customizable. Script is required to facilitate user interaction with a check box object.

A Combo Box provides a drop-down list control for your screens, where a user may select one among a list of mutually exclusive values. The list of items in the drop-down list is defined using the combo box's Items property. Each item in the drop-down list has a Label and a Value, either of which can be called in script to facilitate user interaction. You can configure the list to default to the first item and add some explanatory text to guide your users when no option has been selected. The background color of the combo box 's header and the color of the text in the combo box list is configurable. Font sizing, text styling, and text weighting are also configurable.

The CygNet Grid is a CygNet-aware control that supports the creation of customizable and interactive tables for the display and management of large amounts of data in columns and rows. Four customizable column types are supported: Facility, Generic, History, and Point: facility columns are mapped to a facility attribute and can resolve to a relative facility; generic columns can display any kind of scripted data of your choice and its cells can be edited in run mode; history columns are used to add a sparkline chart in each cell for a specified UDC; point columns are mapped to a UDC and point attribute and the color can be explicitly configured or sourced from the point state color defined for the point represented in the row. The facility and SiteService are configured for the grid row and each can be explicitly set (and filtered) or sourced from other another control or the screen. Any column's background, text, and border color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Alarm indication (blinking) is supported for a point column's background, text, and border when the associated point is in alarm. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart. Each cell in a CygNet grid is like a text tool and the two controls share many color and point configuration properties.

The Detail control is a CygNet-aware tool, which displays real-time data for a single point in multiple formats within the same control. The control contains six elements:

• three tokenized text strings (top, middle and bottom). The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties.
• an alarm icon that can be configured to change color based on point state and change image based on alarm priority
• a small sparkline with configurable line color, x- and y-axis, date ranges, both relative and absolute, and live data updates
• an arrow that is scripted to flip the detail control when clicked and display an object of your choosing on the reverse side of the detail control. The object on the reverse side will receive its point configuration from the detail control.

The last three elements (alarm icon, sparkline, and flip icon) can be toggled on or off.

The control's background and text color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. Font sizing, text styling, and text weighting are also configurable. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Donut is a CygNet-aware control, which displays real-time point data on a circular linear scale. Data is represented in a ring that fills the donut in a clock-wise direction to a value between a lower and upper bound. The source of the lower value bound and upper value bound can be either hard-coded to an explicit value, or dynamically determined for each facility by sourcing the value from an application-specific attribute of the associated point (using an Indexed field or a General data field). A donut on a templated screen supports different bounds for each source facility. By using a point attribute to store the bounds (for example, Indexed 1 for the lower value bound and Indexed 2 for the upper value bound), you can have a templated screen without having to script the control. A configurable value marker is displayed on the donut to indicate the point value. A second inner ring is supported to show alarm ranges that correspond to the alarm setpoints for the associated point. A donut can optionally be labeled with three tokenized text strings. The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties. The color of the donut's color properties can be explicitly configured or can be sourced from the point state of the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Font sizing, text styling, and text weighting are also configurable. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Edit Box can be added to a screen to allow single-line user input. Its purpose is to take user input, which can be retrieved via script using the Text property. The input could be used in a variety of ways. One of the most common implementations is to specify the value for a setpoint command; for example, to enter a maintenance date. Explanatory text for a user can be displayed when no other text has been entered. Script is required to facilitate user interaction with an edit box object.

The Heat Map is a CygNet-aware tool that can be used to display historical CygNet data in a two-dimensional representation in which data values are represented by a range of configurable colors. Its purpose is to visualize data in colored rectangular cells where the color of each cell represents the cell's value and makes it easy to compare all data values. Several other configuration properties are supported, including: configurable date ranges, both relative and absolute; historical rollup values; background, low range color, and high range color; visible color scale; cell padding, labels, and tooltips; visible top labels, and row height.

The Image control is a CygNet-aware tool that can be used to display images on your screens. Supported image file formats include scalable vector graphics (.svg), bitmap (.bmp), portable network graphics (.png), jpeg (.jpg and .jpeg), and graphics interchange format (.gif). The image can be configured to display a default static image or a dynamic image that changes based on the point state or the alarm condition of the associated point. The control can be configured with a valid point configuration but prevented from retrieving any CygNet data, allowing the display of static text while still allowing CygNet data context available from script. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. The mouse cursor that appears when the mouse hovers over the control is configurable. Font sizing, text styling, and text weighting are also configurable. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart. The image control does not support animated .gifs, or animated .svgs, at this time. If no default or custom point state image is specified, a missing image icon () is displayed at design and run mode.

The two Linear Gauge controls are CygNet-aware tools, which display real-time point data on a horizontal or vertical object. Two separate controls are supported: the Linear Gauge (Horizontal) the Linear Gauge (Vertical). Data is represented by a bar that fills the control to a calculated value between a lower and upper bound. The source of the lower value bound and upper value bound can be either hard-coded to an explicit value, or dynamically determined for each facility by sourcing the value from an application-specific attribute of the associated point (using an Indexed field, or a General data field). A guage on a templated screen supports different bounds for each source facility. By using a point attribute to store the bounds (for example, Indexed 1 for the lower value bound and Indexed 2 for the upper value bound), you can have a templated screen without having to script the control. Both linear gauges support a linear or logarithmic scale, with the scale values displayed along the bar from the lower to upper bound. A primary scale is displayed on the right side (Vertical) or bottom side (Horizontal) showing major and minor ticks. A secondary scale is displayed on the left side (Vertical) or top side (Horizontal) showing the lower and upper bound values. An optional text label based on point or facility attributes is centered below the vertical gauge or centered along the horizontal gauge. The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties. The color of the linear gauges' background, text label, the bar representing the value, and the empty bar portion can be explicitly configured or sourced from the point state of the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Font sizing, text styling, and text weighting are also configurable. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Navigator control is a navigation control that can be populated to display any number of Canvas screens and objects. Intrinsic to the control is a hierarchical menu on the left side, which can be configured to organize access to different categories of information. The navigation menu supports a single nested level of navigation; that is, you can configure multiple top-level menu items, each containing multiple sub-menu items. When a menu or sub-menu item is clicked a related screen will be displayed in the body of the control. The path to the linked screen can be a local or network Windows file-system folder or a CygNet APPS or BSS folder. Additionally, each menu item can display a configurable icon to the left of the menu's label. The navigation menu includes an adaptive display mode designed to preserve screen real estate: it can be configured to minimize all menu items, display only the top-level menu icon, or display the icon and menu item label. See the Tab control for a lighter version of the navigator.

The Nested View is a CygNet-aware container that shows another screen, meaning you can show a screen within another screen. This allows for more templated screens or dynamic screens, which can be swapped out at run-time based on user selection. The source file path for the nested view screen can be a local or network Windows file-system folder or a CygNet APPS or BSS folder. You can add as many nested views as you want to a single screen; you can also nest as many screens as you want within a nested view – there is no limit to the number of levels within each nested view.

An Object is a simple Canvas screen containing one or more controls, which can be used on one or many screens. The controls on an object might represent assets such as a well or compressor or device or facility. Once configured, you can drop an object onto many different screens. If you need to make a single edit to any one control on an object, you simply change the master object, save the object, and all screens containing that object will be automatically updated. Any change made to an object will affect all instances of that object on any Canvas screen where it is used. Objects are analogous to templated screens in CygNet Studio. An object and a screen share the same configuration properties, events, and methods.

The Object Container is a CygNet-aware control that dynamically populates itself using Canvas object files (.cob) and passed-in facilities. The control determines how many Canvas objects to draw based on facility inheritance, and then fills itself in with an object for each child of the parent facility. The object container allows the creation of sophisticated, easy-to-maintain Canvas screens, it:

• can be connected to a tag chooser or any other facility sender for its facility context
• supports relative facilities and facility filtering to specify exactly what to display in the container
• will dynamically resize and re-orient objects appropriately
• eliminates the need for complex white-space management scripting

In design mode a Canvas object is viewed in an Object Viewer control. The Object Viewer's properties are listed in the Properties pane in an Object Viewer control and have the same properties, events, and methods as the Nested View control. You can interact with an Object Viewer control via script in the same way you can with any Canvas control. An Object Viewer control can also have its own styles.

The Radio Button can be used to add a list of mutually exclusive items; that is, a list from which the user can select only a single item. Script is required to attach commands to the radio button, which will be executed when the radio button is clicked in run mode. Additionally, you can define a Group name to specify which radio buttons are mutually exclusive.

The Screen is where you create flexible and interactive diagrams and layouts for your users. By configuring a screen with controls and tools, you can create a data-rich visualization of devices, facilities, and other elements in your CygNet environment, convey information about the state of a process via charts, grids, gauges, images, and other data-visualization tools, and design workflows where objects are scripted to accept and implement an operator's control instructions in run mode. The Canvas screen is where you create the HMI for your users in the field and is analogous to TheFrame/TheView in CygNet Studio.

Canvas screens and objects share the same configuration properties. Screens (and objects) support a broadcast feature that allows you to manipulate and pass the SiteService and facility from one screen to another using the Canvas user interface without writing script. Screens (and objects) support navigation by facility to link to a facility's associated screen, using one of six navigation modes. Screen hyperlinking is supported via script. Screens and objects support a default or on-demand chart, which can be invoked anytime from a Canvas or Canvas View screen in design or run mode in the form of a separate dialog box. The default chart supports configurable date ranges, both relative and absolute; live data updates at a configured interval allowing the chart to trend data at a real-time pace. Other configurable screen features include: background color, custom color palette for point state, pan zoom control, title, layout grid (color, height, and snap action), and whether the alarm notifier is visible on the screen when opened in Canvas View and Canvas View Lite.

The Search Box is a powerful CygNet-aware tool for searching facilities or other objects in your CygNet environment. Two search modes are available:

Facility Search

This mode will search all facilities in the specified Facility service and return any matching facility names. Three options are supported when a desired search result is selected:

1. Facility Sender — the search box acts as a facility sender and sends the selected facility to any controls on the screen configured to receive it.
2. Navigation — the search box navigates by facility and links to the selected facility's associated screen. The navigation mode is determined by the Facility navigation mode setting on the screen displaying the search box.
3. Script — an action can be scripted to execute when a facility is selected from the search results.

You can limit the search box to execute a search against a Facility service associated with a current value service (CVS), against a custom filter rule, and against a list of facility properties.

Custom Search

In this mode the search box can be scripted to perform a custom search against any object, for example, a SQL database, a .csv file, even a web site. Further custom actions can be executed when selecting an item in the search results.

The Shape control is a CygNet-aware tool, which supports the drawing of geometric shapes, such as ellipses, triangles, rectangles, polygons, lines, lines with arrowheads, and other custom paths on your screens. You can use one of several predefined shapes or line types or specify a geometric syntax to draw a custom path or line style. A shape's fill color, text color, and line color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties. The control can be configured with a valid point configuration but prevented from retrieving any CygNet data, allowing the display of static text while still allowing CygNet data context available from script. Font sizing, text styling, and text weighting are also configurable. Date, time, and value formatting for the text displayed on the control is supported. The control can be hidden if the associated point is invalid. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. The mouse cursor that appears when the mouse hovers over the control is configurable. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Sparkline chart is a CygNet-aware control that historical data for a single point on a single line. This lightweight line chart is drawn without axes, labels, or legend, and is typically used to understand the shape of historical data: trends up or down, highlight maximum or minimum values, and identify spikes in the data. A sparkline supports configurable line and background color, configurable x-axis and y-axis, configurable date ranges, both relative and absolute, and live data updates to allow the sparkline to request new data at a configured interval giving the appearance that the sparkline is trending data at a real-time pace. A sparkline can be added to other controls, including: a CygNet grid, a Detail control, and a Tile View control.

The Tab control is a navigation tool that incorporates a collection of tabs across the top of the control and an optional nested view linked to associated content. The tabs allow you to easily switch between different Canvas screens and objects within a single container. The path to the linked screen can be a local or network Windows file-system folder or a CygNet APPS or BSS folder. The nested view is only visible if a screen path is configured for that particular tab. The tab control is a lighter version of the Navigator.

The Tag Chooser displays a hierarchical tree of CygNet facilities and points, allowing the creation and implementation of templated screens in Canvas. It can be used as the primary navigational control on your screens to drive other controls by passing in facilities and point values. The tag chooser supports both facility and point resolution. Point resolution is optional at the facility level and can be turned off or on simply by selecting the Show points check box at design time. Facilities are designated with a dark yellow diamond () and points are designated with a blue circle () in the tag chooser hierarchy.

Hierarchy Type

The tag chooser offers two hierarchy types: by Facility service attributes, or by Group service nodes:

• Facility service configuration — This tag chooser hierarchy is organized by the global attributes configured in your CygNet Facility service. You can further limit the tag chooser by any CygNet filter attribute set up for your system.
• Group service configuration — This tag chooser hierarchy is organized by the nodes configured in your CygNet Group service. You can further filter the tag chooser by a facility type. This must be a valid facility type in your system.

The Text Tool is a CygNet-aware control that can be used to display text on your Canvas screens. The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties. The control can be configured with a valid point configuration but prevented from retrieving any CygNet data, allowing the display of static text while still allowing CygNet data context available from script. The control's background, text, and border color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. Alarm indication (blinking) is supported for the control's text, background, and border when the associated point is in alarm. The control can be hidden if the associated point is invalid. Date, time, and value formatting for the text displayed on the control is supported. Font sizing, text alignment, trimming, wrapping, styling, and weighting are also configurable. This control supports tooltips, which can be displayed as tokenized text, a Canvas object, or the tooltip can be scripted to retrieve and display values for related points or CygNet notes. A context menu is available in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Tile View is a CygNet-aware container that displays real-time data in a series of tiled Detail controls, one for each facility provided. The tile view determines how many detail tiles to draw based on facility inheritance, and then fills itself in with a tile for each child of the parent facility, adjusting layout accordingly. The tile view allows you to build screens in a dynamic way with little maintenance, and easily add new points or facilities to a screen without additional scripting. Each detail tile in a tile view displays six elements:

• three tokenized text strings (top, middle and bottom). The control can display static text, such as a label, or dynamic text based on point or facility attributes. Dynamic text is built using tokens, which can represent real-time CVS point properties, point configuration properties, and facility properties.
• an alarm icon that can be configured to change color based on point state and change image based on alarm priority
• a small sparkline with configurable line color, date ranges, both relative and absolute, and live data updates
• an arrow icon that is scripted to flip the tile when clicked and display an object of your choosing showing related data on the reverse side of the detail tile. The object on the reverse side will receive its point configuration from the detail control.

The last three elements (alarm icon, sparkline, and flip icon) can be toggled on or off. The control's background and text color can be explicitly configured or sourced from the point state color defined for the associated point. Colors in the control can be overridden when a custom color palette is selected for the screen. The tile view has two display modes for its tiles:

• Single UDC — Where data for a single UDC is displayed and a tile will be created for each child of a parent facility
• Each UDC for Facility — Where facilities are queried for their associated UDCs and a tile will be created for each one

Additionally, each tile in the tile view includes a title bar showing the facility name and a maximize button. When clicked in run mode the tile will maximize and open a screen, object, or CygNet Studio screen populated with related data for the passed-in facility from the originating tile. The maximized screen or object can be minimized to return to the initial tile view. Each tile displays a context menu in run mode with access to CygNet point and alarm data, including alarm acknowledgment, current and history values, point and facility configuration, and trending point data on a default chart.

The Tree Map is a CygNet-aware tool that can be used to display historical or real-time data as a set of relatively-sized and colored rectangles. Each rectangle has an area proportional to its numerical value. Several other configuration properties are supported, including: configurable date ranges, both relative and absolute; background, low range color, and high range color; display mode (best fit or vertically stacked); filtering to show only top or bottom items; and historical rollup values.