1. In design mode, create a new Canvas screen.
2. Find the CygNet Grid on the Toolbox pane and drag a desired object to your screen.

3. Use the Settings pane to apply common settings (sizing, grouping, alignment, etc.) to this object (and others) on your screen.

4. Optionally, use the Name property to rename the object if you plan to reference it in another screen or control, or plan to script this control.
5. Configure the Style property.

1. Style —

   The Style property defines the style sheet applied to an object on a screen. A style sheet consists of a predetermined list of properties and property values configured for a particular control type.

   • Click to reveal a drop-down menu of predetermined styles configured for the selected control.
   • Select a desired style and its properties will be applied to the control.
   • Alternately, you can create a new style based on other property values configured for the control.
   • Or you can select <None> to remove subscription to any style.

   Styles are created in two ways:

   • In the control's Properties pane. Click (Add a new style based on this control) next to the Style property, after you have configured property values in the Properties pane. See Add a new style based on a control for more information.
   • In the Canvas Settings in the Backstage view. The default style for any control is configured in the Backstage view. See Manage style sheets in the Backstage view for more information.

   Tip: You can also change a control's Style on the Controls view of the Screen pane.

6. Configure the Location properties. See To configure location, size, resizing, layer, and visibility properties below.
7. Configure the Script property.

1. Include in script —

   The Include in script check box indicates that the control will appear in the objects collection of the screen (if scripting is enabled). To optimize performance, best practice dictates that you only include the controls you need to manipulate via script. Other controls should be excluded. When you add an event to a control, it will be automatically added to script and the Include in script property (and the In Script check box on the Controls view) will be set to True.

   Tip: You can also change the Include in Script setting on the Controls view of the Screen pane.

8. Configure the Grid properties to define specific grid options. See To configure grid properties below.
9. Configure the Hyperlink properties to indicate what to do when the cell or row is double-clicked. See To configure the hyperlink properties below.
10. Configure the Generic properties:

1. String — The String property specifies a generic string property that can be used when scripting this control. Type a string and reference it in your script as necessary.
2. Yes/No — The Yes/No property specifies a generic Boolean yes/no property that can be used when scripting this control. Click the check box to enable the property and reference it in your script as necessary.

11. Configure other grid properties.
12. Save the screen.
13. Run the screen to test your configuration.

1. Find the Location properties and configure the size and location properties for the control:

1. Height —

   The Height property specifies the height of the control (or screen).

   Tip: You can also change the height of a control using the Settings pane (click on the (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

2. Horizontal resize mode —

   The Horizontal resize mode property specifies whether and how the control dynamically moves or resizes horizontally when the screen is resized in run mode. Options include:

   • None — No resizing occurs.
   • Shift — The object will shift horizontally.
   • Expand — The object will expand or shrink horizontally the same number of pixels as the screen.
   • Proportional — The object expands or shrinks proportionally to the screen.

   The default value is None.

3. Layer —

   The Layer property specifies the name of the layer to which this object is assigned. Layers can be used to show, hide, and edit multiple controls on one layer without affecting controls on another layer.

   • Type the name of the layer into the Layer field (the name can be a previously created layer or a new layer).
   • All layers are listed on the Layers pane, where you can manage the layers for the screen in design mode and run mode.

   Tip: You can also edit a control's Layer on the Controls view of the Screen pane.

   Note: Layer visibility can be controlled at runtime via the AddLayer, HideLayer, SetLayerVisibility, and ShowLayer methods on the Screen object.

4. Lock —

   The Lock property indicates whether the control is locked to the current position. A locked control cannot be moved via click and drag, or nudged with the arrow keys, or resized.

   Tip: You can also toggle the lock setting of a control using the Settings pane (click on the (Settings) to the right of the control in design mode).

5. Vertical resize mode —

   The Vertical resize mode property specifies whether and how the control dynamically moves or resizes vertically when the screen is resized in run mode. Options include:

   • None — No resizing occurs.
   • Shift — The object will shift vertically.
   • Expand — The object will expand or shrink vertically the same number of pixels as the screen.
   • Proportional — The object expands or shrinks proportionally to the screen.

   The default value is None.

6. Visible —

   The Visible check box indicates whether the control is visible in run mode.

   Tip: You can also change a control's Visible setting on the Controls view of the Screen pane.

7. Width —

   The Width property specifies the width of the control (or screen).

   Tip: You can also change the width of a control using the Settings pane (click on the (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

8. X —

   The X property specifies the location of the control along the horizontal axis. Use the up, down, left, and right arrow keys to nudge a control by 1 pixel. Arrow moves a control by 1 pixel. Ctrl+Arrow moves a control by 10 pixels. Ctrl+Shift+Arrow moves a control by 100 pixels.

   Tip: You can also change the location of the control using the Settings pane; click on the (Settings) to the right of the control in design mode.

9. Y —

   The Y property specifies the location of the control along the vertical axis. Use the up, down, left, and right arrow keys to nudge a control by 1 pixel. Arrow moves a control by 1 pixel. Ctrl+Arrow moves a control by 10 pixels. Ctrl+Shift+Arrow moves a control by 100 pixels.

   Tip: You can also change the location of the control using the Settings pane; click on the (Settings) to the right of the control in design mode.

10. Z index —

    The Z index property is used to determine the order in which controls are layered on top of each other. Controls with higher values will draw on top of those with lower values. The newest control added to a screen will always have the highest value and will be the top layer. Two or more controls can be on the same index (layer).

    Tip: You can also change the Z index of a control using the Settings pane (click on the (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

2. Configure other grid properties.
3. Save the screen.
4. Run the screen to test your configuration.

The Grid set of properties is where you configure specific grid options, including: columns, custom context menu items, facility sender mode, rows, row Summary update rate, selection mode, and selection unit.

1. Find the Grid properties and define the following properties for the CygNet Grid:

1. Color configuration —

   The Color configuration property is used to configure color settings for the header and background of the CygNet Grid. Click to reveal a set of color options where you can specify the source and color to be used, which are described below:

   • Header background color
   • Header text color
   • Grid background color

   Note: Cell color and alarm acknowledgment settings are configured in the Color property group in the Column configuration property.

   1. Header background color — The Header background color property specifies the color used for the background of the grid's header row.
   2. Header text color — The Header text color property specifies the color used for the text on the grid's header row.
   3. Grid background color — The Grid background color property specifies the color used for grid's background.

   For each color property select the Source and Color:

   • Source — Click to reveal two options:
     • Auto — The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). Where applicable, color-related properties will default to this configuration, allowing them to automatically follow the theme of the current client rather than fixing them to the one used when the screen was created. By using Auto for the color configuration, a screen developer can work in their preferred theme without affecting the presentation of the final screen when displayed by the user—avoiding display problems such as white text over a very light background, etc.

       Note:    Auto is not supported as a color source in TWC screens. If a property specifies Auto for color configuration, the screen will use the <Self> color that is specified in the Canvas file during the publishing process. See Color on TWC Screens.

     • Self — Select Self to explicitly configure the color. When Self is selected a Color field is automatically displayed beneath the Source field and must be configured.
   • Color — Only displays if the Source is Self. Click to customize the color using the color picker.
2. Column configuration —

   The Grid Column Configuration dialog box contains the properties required to configure each column in your grid. There are five types of columns that can be configured in a CygNet Grid: a Facility column, a Generic column, a History column, a Point column, and an Image column. The number of defined columns is listed on the property label once all are configured.

   Click to open Grid Column Configuration dialog box.

   1. See To configure a facility column below
   2. See To configure a generic column below
   3. See To configure a history column below
   4. See To configure a point column below
   5. See To configure an image column below

3. Context menu items — See To configure custom context menu items below.
4. Double click mode —

   The Double click mode property determines the action to take when you double-click a row in run mode. The Facility sender mode must be set to Double click. Options are:

   • Hyperlink — A double click will link to a screen in a new window via the hyperlink navigation option selected in the Hyperlink mode property. This control supports hyperlinking to other screens via configuration or scripting. A single click or double-click action will send any configured facility to the receiving screen. Hyperlink supports the following operational modes: Open, Modal open (a subordinate popup window), Open and close, Replace, Replace with navigation, and Close. Any configured script is disabled.

   • Script — A double click will disable hyperlink navigation and run any specified script.

   The default value is Hyperlink.

   Notes:

   • Grid cells can display a different facility from that configured for a grid row. The double-click hyperlink action will pass the cell or row’s facility to other controls on the screen configured to receive it AND to the receiving screen.

   • If Double click is selected for the Facility sender mode property, and Hyperlink is selected for the Double click mode property, and a Hyperlink mode and Screen path are configured, two actions will be performed when a row is double-clicked:

     1. the selected facility will be sent to any control(s) on the screen configured to receive its facility from the grid

        - and -

     2. the selected facility will be sent to the screen configured in the Screen path property.

     Script Event

     If Double click is selected for the Facility sender mode property, and Script is selected for the Double click mode property, the selected facility will be sent to any control(s) on the screen configured to receive its facility from the grid, and the script event Double Click Cell will fire using the facility received from the grid.

   • The script property for Double click mode is DoubleClickBehavior.
5. Facility sender mode — Configure the Facility sender mode property to determine the mode for sending a facility to other controls:

   The Facility sender mode property determines how facilities are sent to other controls. There are four options:

   • None — No facilities are sent. This is the default value.
   • Single click — A single click on a row will send a single facility to a receiving control on the same screen.
   • Double click — A double click on a row will send a single facility to a receiving control on the same screen. This option supports two actions when a row is double-clicked: 1. Sending a facility to anther control on the same screen; and 2. Sending a facility to another screen. See the note below.
   • All facilities — As soon as all facilities are received they will be sent to the receiving control on the screen. No click is required.

   Note:

   If Double click is selected for the Facility sender mode property, and Hyperlink is selected for the Double click mode property, and a Hyperlink mode and Screen path are configured, two actions will be performed when a row is double-clicked:

   1. the selected facility will be sent to any control(s) on the screen configured to receive its facility from the grid

      - and -

   2. the selected facility will be sent to the screen configured in the Screen path property.

   Script Event

   If Double click is selected for the Facility sender mode property, and Script is selected for the Double click mode property, the selected facility will be sent to any control(s) on the screen configured to receive its facility from the grid, and the script event Double Click Cell will fire using the facility received from the grid.

   Sending and receiving facility tags

   Some controls on the same screen allow for the sending of facility information from one control to another.

   1. On the sending control configure the Facility sender mode property to send facility tag information to another control on the same screen.
   2. On the receiving control configure the Selection mode property (in either CygNet connection or Point configuration section) to Facility tag and select the Facility Source to the sending control.
   3. On the receiving control configure a display tag that associates to a facility property, e.g., %FacilityTag%.

   Example

   Add a control to a screen (e.g., a Tag Chooser or Grid) and configure it as a facility sender to send a facility to the screen. Add another control to the screen (e.g., a Text Tool or Donut) and configure it to receive the facility from the screen. In this scenario the Tag Chooser or Grid will send a facility to the screen and the screen will then send the facility to a Text Tool or the Donut.

6. Row configuration — The Row configuration property is where you specify the source of the data to use for the rows of the CygNet Grid: either from facilities or a SiteService. The source for the facilities can be explicitly configured or received from the screen or another control. If the Facility source is set to <Self>, facilities can be filtered as necessary, and you need to provide a SiteService. Click to reveal a drop-down area where you can configure the source Facility and source SiteService for the grid's rows. See To configure the source of row data below.
7. Row summary update rate — The Row summary update rate property specifies the rate (in milliseconds) at which the grid will recalculate row summaries after a value changes in a point column. Longer rates will improve performance by not recalculating as often. When a value in a cell is updated, the summary row will be recalculated. However recalculation does not happen immediately or for every update; it is throttled by the Row summary update rate. When a recalculation is requested, Canvas will delay for the duration of the update rate. This allows other updates to come in that may affect the recalculated values. Recalculation requests that come in during that delay will be ignored. In this way, no matter how often values change, Canvas will not recalculate the summary row value more often than the set rate. The default value is 1000 milliseconds (1 second). Note: The Row summary update rate property does not apply to the CygNet TWC web view and is hidden in the Properties pane in Web client mode. The summary row data is recalculated every time there is a data update for the configured column. Also see To configure a point column below.
8. Selection mode —

   The grid controls offer three selection modes, which determine how many grid units may be selected in run mode. The grid units are determined by the Selection unit property. Options include:

   • Single — Only one item can be selected at a time.
   • Multiple — Items are added to the selection when they get clicked and get removed when they get clicked again.
   • Extended — Items are added to the selection only by combining mouse clicks with the Ctrl key or Shift key.

   The default value is Single.

   In script, use SelectionMode with the SelectAll method and SelectedRows property (read-only) to aid in multi-row selection:

   • SelectAll method — If the SelectionMode property is Multiple or Extended, SelectAll will select all rows in a grid and SelectedRows will return the matching DataRow objects. SelectAll will not obviously change the selection if SelectionMode is Single.
   • SelectedRows property (read-only) — SelectedRows will be restricted to a single row if SelectionMode is Single. Otherwise SelectedRows can contain multiple rows to be retrieved via script.
9. Selection unit —

   The CygNet Grid offers three selection units. The Selection unit property determines the grid units that may be selected in run mode. Options included:

   • Cell — Only the clicked cell is selected. Depending on the value of the Selection mode property you can have more than one selected cell
   • Full row — Clicking within any cell will select the entire row.
   • Mixed — Select any cell and you can also select a full row if you click on a row, but not on a cell from it.

   The default value is Full row.

2. Configure other grid properties.
3. Save the screen.
4. Run the screen to test your configuration.

A facility column presents data for a point by a facility attribute. You can choose to resolve the facility to a relative facility if desired.

1. In design mode, create a new Canvas screen and add a CygNet Grid.
2. Click to open Grid Column Configuration dialog box.
3. Click Add column to add a new, blank facility column to your grid. A <default> item is added to the list of columns. Complete the column configuration to suit your needs using the properties described below.
4. Click on the <default> column name to reveal the Common, Facility, and Color property groups for the column.
5. Configure the Common properties for each facility column:

1. Name — The Name specifies the name that appears in the column header.
2. Type — The Type property is a read-only text box that shows the column Type for the grid.
3. Visible — The Visible check box indicates whether to display the column in run mode.
4. Width — The Width property specifies the width of the column in pixels. Set the value to 0 to auto size the width. If the column width is not configured (i.e., the width is set to 0), the column will be auto sized. If the column width is configured with a fixed column width, no resizing will occur.
5. Text alignment — The Text alignment property specifies the horizontal alignment of the text in the column (all column types except Image). The options are Left, Right, Center, and Justify. The default value is Left. When published to TWC the Justify option is indistinguishable from the Left option.
6. Sort numerically —

   The Sort numerically property specifies whether this column can be sorted numerically (all column types except History and Image). In run mode, clicking a column header moves between the three states: sort ascending, sort descending, and unsorted. A small arrow indicates the sort order.

   Note: Any column with mixed string and numeric data (like the Value column of the Alarm Grid) will be sorted as a string.

   The Sort numerically property is by the Alarm Grid.

   The Sort numerically property does not apply to a History column of the CygNet Grid.

6. Configure the Facility properties for each facility column:

1. Facility attribute —

   The Facility attribute property specifies the facility attribute that will displayed in the column. Click to reveal a drop-down menu of all available CygNet facility attributes categorized by type:

   • Facility: General Attributes (The default value is Facility Description.)
   • Facility: Text Attributes
   • Facility: Table-driven Attributes
   • Facility: Yes/No Attributes

   Click to expand each category and select the desired facility attribute.

2. Resolve to a relative facility — The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed. See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links.
3. Relative link — The Relative link property specifies a list of all available relative facility paths. Click to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.
4. Order in type — The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box.

7. Configure the Color properties for each facility column:

1. Background color — The Background color property specifies the color used for the background of the grid cell.
2. Text color — The Text color property specifies the color used for the text of the grid cell.
3. Border color — The Border color property specifies the color used for the border of the grid cell.

For each color property select the Source and Color:

• Source — Click to reveal two options:
  • Auto — The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). Where applicable, color-related properties will default to this configuration, allowing them to automatically follow the theme of the current client rather than fixing them to the one used when the screen was created. By using Auto for the color configuration, a screen developer can work in their preferred theme without affecting the presentation of the final screen when displayed by the user—avoiding display problems such as white text over a very light background, etc.

    Note:    Auto is not supported as a color source in TWC screens. If a property specifies Auto for color configuration, the screen will use the <Self> color that is specified in the Canvas file during the publishing process. See Color on TWC Screens.

  • <Self> — Select <Self> to explicitly configure the color. When <Self> is selected a Color field is automatically displayed beneath the Source field and must be configured.
• Color — Only displays if the Source is <Self>. Click to customize the color using the color picker.

8. Configure other grid properties.
9. Save the screen.
10. Run the screen to test your configuration.

A generic column can display any kind of scripted data of your choosing using C# or VB.NET at runtime. First configure the column in Canvas and then reference the column by name to pull in CygNet or other values. A generic column can be used to discover data defined in a supporting script. If the column is defined, but no data is defined, then the column is hidden by default.

The cells in a generic column can be configured to be editable in run mode, so that, for example, users could make quick data changes to facilities in a grid format. Changed values are not saved anywhere but in the grid, but they can be saved or otherwise manipulated via script. Note that when a generic column is set to editable the Color properties are not configurable.

1. In design mode, create a new Canvas screen and add a CygNet Grid.
2. Click to open Grid Column Configuration dialog box.
3. Click Add column to add a new, blank generic column to your grid. A <default> item is added to the list of columns. Complete the column configuration to suit your needs using the properties described below.
4. Click on the <default> column name to reveal the Common and Color property groups for the column.
5. Configure the Common properties for each generic column:

1. Name — The Name specifies the name that appears in the column header.
2. Type — The Type property is a read-only text box that shows the column Type for the grid.
3. Visible — The Visible check box indicates whether to display the column in run mode.
4. Width — The Width property specifies the width of the column in pixels. Set the value to 0 to auto size the width. If the column width is not configured (i.e., the width is set to 0), the column will be auto sized. If the column width is configured with a fixed column width, no resizing will occur.
5. Text alignment — The Text alignment property specifies the horizontal alignment of the text in the column (all column types except Image). The options are Left, Right, Center, and Justify. The default value is Left. When published to TWC the Justify option is indistinguishable from the Left option.
6. Sort numerically —

   The Sort numerically property specifies whether this column can be sorted numerically (all column types except History and Image). In run mode, clicking a column header moves between the three states: sort ascending, sort descending, and unsorted. A small arrow indicates the sort order.

   Note: Any column with mixed string and numeric data (like the Value column of the Alarm Grid) will be sorted as a string.

   The Sort numerically property is by the Alarm Grid.

   The Sort numerically property does not apply to a History column of the CygNet Grid.

7. Read only — The Read only property indicates whether the cells in a Generic column are editable. (Generic column only)

6. Configure the Color properties for each generic column:

1. Background color — The Background color property specifies the color used for the background of the grid cell.
2. Text color — The Text color property specifies the color used for the text of the grid cell.
3. Border color — The Border color property specifies the color used for the border of the grid cell.

For each color property select the Source and Color:

• Source — Click to reveal two options:
  • Auto — The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). Where applicable, color-related properties will default to this configuration, allowing them to automatically follow the theme of the current client rather than fixing them to the one used when the screen was created. By using Auto for the color configuration, a screen developer can work in their preferred theme without affecting the presentation of the final screen when displayed by the user—avoiding display problems such as white text over a very light background, etc.

    Note:    Auto is not supported as a color source in TWC screens. If a property specifies Auto for color configuration, the screen will use the <Self> color that is specified in the Canvas file during the publishing process. See Color on TWC Screens.

  • <Self> — Select <Self> to explicitly configure the color. When <Self> is selected a Color field is automatically displayed beneath the Source field and must be configured.
• Color — Only displays if the Source is <Self>. Click to customize the color using the color picker.

7. Configure other grid properties.
8. Reference the generic column by its Name in script to pull in CygNet or other values as desired.
9. Save the screen.
10. Run the screen to test your configuration.

A history column is used to add a Sparkline chart in each cell for a specified UDC. You can choose to resolve the point to a relative facility, or use absolute or relative dates, if desired.

1. In design mode, create a new Canvas screen and add a CygNet Grid.
2. Click to open Grid Column Configuration dialog box.
3. Click Add column to add a new, blank history column to your grid. A <default> item is added to the list of columns. Complete the column configuration to suit your needs using the properties described below.
4. Click on the <default> column name to reveal the Common and History property groups for the column.
5. Configure the Common properties for each history column:

1. Name — The Name specifies the name that appears in the column header.
2. Type — The Type property is a read-only text box that shows the column Type for the grid.
3. Visible — The Visible check box indicates whether to display the column in run mode.
4. Width — The Width property specifies the width of the column in pixels. Set the value to 0 to auto size the width. If the column width is not configured (i.e., the width is set to 0), the column will be auto sized. If the column width is configured with a fixed column width, no resizing will occur.

5. Text alignment — The Text alignment property specifies the horizontal alignment of the text in the column (all column types except Image). The options are Left, Right, Center, and Justify. The default value is Left. When published to TWC the Justify option is indistinguishable from the Left option.

6. Configure the Sparkline properties for the history column:

1. UDC — The UDC property specifies the UDC for which the sparkline is to display data. Click to select a UDC using the Select UDC dialog box.
2. Resolve to a relative facility — The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed. See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links.
3. Relative link — The Relative link property specifies a list of all available relative facility paths. Click to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.
4. Order in type — The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box.
5. Color —

   The Sparkline color (or Color) property specifies the color of the sparkline. Click to customize the color using the color picker.

   Note: The default colors used for a Sparkline series are drawn from a set palette and are therefore not theme-specific. See themes for more information.

6. Start date — The Begin date or Start or Start date property specifies the start date and time for a control (or screen or chart or column) for an absolute date and time view window. The format is MM/DD/YYYY hh:mm:ss AM/PM. The default value is the system date and time at which the control was first added to the screen. Click to change the date using the date picker.
7. End date — The End date or End property specifies the end date and time for a control (or screen or chart or column) for an absolute date and time view window. The format is MM/DD/YYYY hh:mm:ss AM/PM. The default value is the system date and time at which the control was first added to the screen. Click to change the date using the date picker.
8. Use relative dates — The Use relative dates check box indicates whether to use relative dates and time in the history column of the CygNet Grid. If unchecked all dates and time will be absolute.
9. Relative start date — The Begin relative date or Relative start date or Start property specifies a wildcard string defining the amount of time by which to adjust the start date and time. The space-separated elements in this string must be of the form: "x-#", "x+#", or "x=#" where # is an integer and x is one of the following unit specifiers: y — Year, m — Month, d — Day, H — Hour, M — Minute, S — Second, and # is an integer. T wildcard is also supported and must be in the form: T, T+#, T-#, where T represent today at midnight, T-1 is yesterday at midnight, and T+1 is tomorrow at midnight, etc. Any integer can be used. For example, H-8 represents data from the 8 hours before the current hour, d+3 represents data 3 days after the current day, and d+2 H+1 M+30 represents data 2 days, 1 hour and 30 minutes after the current date and time. d-4 H=6 sets the relative start date and time to four days ago (d-4) at 6:00 a.m. (H=6). See Date and Time Wildcards for more information about adjusting relative time.
10. Relative end date — The End relative date or Relative end date or End property specifies a wildcard string defining the amount of time by which to adjust end date and time. The space-separated elements in this string must be of the form: "x-#", "x+#", or "x=#" where # is an integer and x is one of the following unit specifiers: y — Year, m — Month, d — Day, H — Hour, M — Minute, S — Second, and # is an integer. T wildcard is also supported and must be in the form: T, T+#, T-#, where T represent today at midnight, T-1 is yesterday at midnight, and T+1 is tomorrow at midnight, etc. Any integer can be used. For example, H-8 represents data from the 8 hours before the current hour, d+3 represents data 3 days after the current day, and d+2 H+1 M+30 represents data 2 days, 1 hour and 30 minutes after the current date and time. d-4 H=6 sets the relative end date and time to four days ago (d-4) at 6:00 a.m. (H=6). See Date and Time Wildcards for more information about adjusting relative time.
11. Auto range x-axis — The Auto range x-axis check box indicates whether the sparkline's x-axis is constrained to the range of values for the associated point or fixed to the configured time range (default). Configure the date and time range in the Range properties below.
12. Auto range y-axis — The Auto range y-axis check box indicates whether the sparkline's y-axis is constrained to the range of values for the associated points (default) or fixed to the configured minimum and maximum values. Configure the y-axis scale in the Maximum Y value and Minimum Y value below.
13. Maximum Y value — The Maximum Y value property specifies the maximum value to use on the sparkline's y-axis when the Auto range - y-axis property is set to fixed (disabled).
14. Minimum Y Value — The Minimum Y value property specifies the minimum value to use on the sparkline's y-axis when the Auto range - y-axis property is set to fixed (disabled).

7. Configure other grid properties.
8. Save the screen.
9. Run the screen to test your configuration.

A point column presents data for a point by UDC and point attribute. You can choose to resolve the point to a relative facility if desired.

Point column types also support a Summary row at the bottom of the grid that can show the following values for the data in the column: a total Count, a Sum, the Min value, the Max value, the Min and Max values, and the Mean value.

1. In design mode, create a new Canvas screen and add a CygNet Grid.
2. Click to open Grid Column Configuration dialog box.
3. Click Add column to add a new, blank point column to your grid. A <default> item is added to the list of columns. Complete the column configuration to suit your needs using the properties described below.
4. Click on the <default> column name to reveal the Common, Point, and Color property groups for the column.
5. Configure the Common properties for each point column:

1. Name — The Name specifies the name that appears in the column header.
2. Type — The Type property is a read-only text box that shows the column Type for the grid.
3. Visible — The Visible check box indicates whether to display the column in run mode.
4. Width — The Width property specifies the width of the column in pixels. Set the value to 0 to auto size the width. If the column width is not configured (i.e., the width is set to 0), the column will be auto sized. If the column width is configured with a fixed column width, no resizing will occur.
5. Text alignment — The Text alignment property specifies the horizontal alignment of the text in the column (all column types except Image). The options are Left, Right, Center, and Justify. The default value is Left. When published to TWC the Justify option is indistinguishable from the Left option.
6. Sort numerically —

   The Sort numerically property specifies whether this column can be sorted numerically (all column types except History and Image). In run mode, clicking a column header moves between the three states: sort ascending, sort descending, and unsorted. A small arrow indicates the sort order.

   Note: Any column with mixed string and numeric data (like the Value column of the Alarm Grid) will be sorted as a string.

   The Sort numerically property is by the Alarm Grid.

   The Sort numerically property does not apply to a History column of the CygNet Grid.

6. Configure the Point properties for each point column:

1. UDC — The UDC property specifies the UDC for which the control is to display data. Click to select a UDC using the Select UDC dialog box.
2. Point attribute —

   The Point attribute property specifies the CygNet point attribute that will be displayed in the column. Click to reveal a drop-down menu of all available CygNet point attributes categorized by type:

   • Current Values (The default value is Value.)
   • Point: General
   • Point: Alarm
   • Point: Point Reference
   • Point: Application
   • Point: Scaling
   • Point: Hyperpoint
   • Point: Alarm (Scheme 0)
   • Point: History
   • Current Value Status Bits

   Click to expand each category and select the desired point attribute.

3. Resolve to a relative facility — The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed. See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links.
4. Relative link — The Relative link property specifies a list of all available relative facility paths. Click to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.
5. Order in type — The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box.
6. Value format — The Value format property specifies the format for the point's value using any of the valid .NET standard or custom numeric format strings. The value format applies to a point's Value, Primary Value, and Alternate Value properties. The default value format is #,##0.00, which corresponds to 123,456,789.12. Formats use # and 0, with a period (.) as the decimal separator and comma (,) as the thousands separator. Add additional zeros to show more decimal places.
7. Date and time format —

   The Date and time format property specifies the format for a point's timestamp using any of the valid .NET standard or custom numeric format strings. The date and time format applies to any point's timestamp property. Use this property to override the Default date format, which is configured in the Application settings page of the Backstage view. The default date format is YYYY/MM/DD HH:MM:SS.fff, which corresponds to 2024/01/01 10:20:30.0001. All timestamps are local client time.

   If an invalid format is configured for the Date and time format, the control will automatically use the format configured for the Default date format saved in the global settings file, and configured in the Backstage view.

   Note: You can also use the Microsoft .NET Standard Date and Time Format Strings to define the text representation of a date and time value in Canvas. For example, "d" is the short date pattern and corresponds to 1/1/2024, "F" is the full date/time pattern and corresponds to Monday, January 1, 2024 1:45:30 PM.

7. Configure the Color properties for each point column:

1. Background color — The Background color property specifies the color used for the background of the grid cell.
2. Text color — The Text color property specifies the color used for the text of the grid cell.
3. Border color — The Border color property specifies the color used for the border of the grid cell.

For each color property select the Source and Color:

• Source — Click to reveal three options:
  • Auto — The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). Where applicable, color-related properties will default to this configuration, allowing them to automatically follow the theme of the current client rather than fixing them to the one used when the screen was created. By using Auto for the color configuration, a screen developer can work in their preferred theme without affecting the presentation of the final screen when displayed by the user—avoiding display problems such as white text over a very light background, etc.

    Note:    Auto is not supported as a color source in TWC screens. If a property specifies Auto for color configuration, the screen will use the <Self> color that is specified in the Canvas file during the publishing process. See Color on TWC Screens.

  • Point State — Select Point State to specify that the source of the color corresponds to the point state color defined for the point represented in the element. The default point state colors for a CygNet system are defined by the system’s point scheme.
  • <Self> — Select <Self> to explicitly configure the color. When <Self> is selected a Color field is automatically displayed beneath the Source field and must be configured.
• Color — Only displays if the Source is <Self>. Click to customize the color using the color picker.

4. Display alarm acknowledgment — If you want to be able to acknowledge alarms in run mode, configure any of these check boxes. In addition to seeing the Acknowledge alarm option on the context menu, the Text Tool will also blink for the selected region of the control.

   The Display alarm acknowledgment property enables the cell or Text Tool's background, text, and border to blink when the associated point is in alarm. Check each box to configure the:

   • Background — The background of the cell or Text Tool will blink when the associated point is in alarm.
   • Text — The text in the cell or Text Tool will blink when the associated point is in alarm.
   • Border — The border of the cell or Text Tool will blink when the associated point is in alarm.

   If none of these options are selected, no visual indication of a point in alarm will be presented. However, if the point is in alarm, an Acknowledge alarm option will be available from the context menu in run mode.

   Note: The blink interval is configurable in the Canvas Settings page in the Backstage view.

8. Configure the Summary properties for each point column:

1. Summary type —

   The Summary type property specifies the type of values presented in the grid summary row at the bottom of the grid. Click to select from one of the following options:

   • Sum — The sum of the values
   • Min — The minimum value
   • Max — The maximum value
   • MinMax — The minimum and maximum values
   • Count — The total number of rows
   • Mean — The mean value
2. Show label — The Show label check box indicates whether to display a label providing context for the grid summary row value. Options include: Sum:, Min:, Max:, MinMax:, Count:, and Mean:.
3. Row summary update rate — The Row summary update rate property specifies the rate (in milliseconds) at which the grid will recalculate row summaries after a value changes in a point column. Longer rates will improve performance by not recalculating as often. When a value in a cell is updated, the summary row will be recalculated. However recalculation does not happen immediately or for every update; it is throttled by the Row summary update rate. When a recalculation is requested, Canvas will delay for the duration of the update rate. This allows other updates to come in that may affect the recalculated values. Recalculation requests that come in during that delay will be ignored. In this way, no matter how often values change, Canvas will not recalculate the summary row value more often than the set rate. The default value is 1000 milliseconds (1 second). Note: The Row summary update rate property does not apply to the CygNet TWC web view and is hidden in the Properties pane in Web client mode. The summary row data is recalculated every time there is a data update for the configured column.

9. Configure other grid properties.
10. Save the screen.
11. Run the screen to test your configuration.

An image column presents a point-state image — a CygNet-aware image that will dynamically change based on the point state of the associated point. A default image is displayed if you configure point-state-aware images and no matching state exists.

1. In design mode, create a new Canvas screen and add a CygNet Grid.
2. Click to open Grid Column Configuration dialog box.
3. Click Add column to add a new, blank image column to your grid. A <default> item is added to the list of columns. Complete the column configuration to suit your needs using the properties described below.
4. Click on the <default> column name to reveal the Common and Image property groups for the column.
5. Configure the Common properties for each point column:

1. Name — The Name specifies the name that appears in the column header.
2. Type — The Type property is a read-only text box that shows the column Type for the grid.
3. Visible — The Visible check box indicates whether to display the column in run mode.
4. Width — The Width property specifies the width of the column in pixels. Set the value to 0 to auto size the width. If the column width is not configured (i.e., the width is set to 0), the column will be auto sized. If the column width is configured with a fixed column width, no resizing will occur.

6. Configure the Image properties for each image column:

1. UDC — The UDC property specifies the UDC for which the image is to display data. Click to select a UDC using the Select UDC dialog box.
2. Resolve to a relative facility — The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed. See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links.
3. Relative link — The Relative link property specifies a list of all available relative facility paths. Click to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.
4. Order in type — The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box.
5. Images —

The Image Selection dialog box is where you configure CygNet-aware images that will dynamically change based on the point state of the associated point. The point state preference is configured in the Resolution mode property. A default image is displayed if you configure point-state-aware images and no matching state exists.

Click to open the Image Selection dialog box.

Note: If no image is specified or the image is missing, a missing image icon () is displayed in both design and run mode.

6. Point scheme — The Point scheme property lists the point schemes used in this CygNet domain. The point scheme defines the point types, point alarms, point statuses, and default colors for a CygNet domain.
7. Point state — The Point state property lists the point states used in the selected point type. Point state is the highest precedented state for a point record as defined for each point scheme. The point state for a point record is based on 48 System, Configuration, and User status bits, which are associated with the four point types (Analog, Digital, String, Enumeration). A point record may contain up to 48 status bits, which are used to provide point status information about the point record in a CVS and the ELSALM. A point can be in multiple states at the same time, for example, in High Warning and High Alarm; however, the state defined to be the most severe is the one that is used for the point state (i.e., High Alarm, in this case).
8. Image — The Image property indicates the file path and file name of the image that will be substituted when the point state changes to the selected point state. Browse and select the desired image file. Click to select a path and file from the Open / Open File / Select File dialog box, where you can access: A thumbnail of the selected image, and its dimensions are displayed for each point state.
9. Image file path —

   This property specifies the path to the file, image file, video file, object file, or screen file. Depending on the selection in the source property the type of path is different. Click to access either the:

   • Select File dialog box —To access an APPS or BSS folder
   • Open File dialog box — To access a local or network file-system folder

   Note: If no image is specified or the image is missing, a missing image icon () is displayed in both design and run mode.

   Note: Point data and/or text will display in run mode, even if the no image is specified and the missing image icon () is displayed.

10. Size mode —

    The Size mode property specifies the method used to size the image so it can scale without distortion. Options include:

    • Stretch — Resizes the image to fill the entire area, while maintaining its native aspect ratio.
    • Auto — Displays the image using its raw size. If the image is too big to fit within the boundaries of the area, sizing follows the Stretch behavior.

    The default value is Auto.

11. Hide invalid tag —

    The Hide invalid tag check box indicates whether to hide the element (a control, button, image, or map visual item) if it resolves to an invalid or unknown tag.

    Note: Invalid point tags and relative facility resolution work in the following way for single-value controls: when a point tag is invalid or unknown, the tag can be hidden using the Hide invalid tag property. In this situation, a control with only facility-based tokens that has a valid relative facility resolution, but results in an invalid point tag, then the point tag will be treated as an invalid tag and displayed accordingly.

    There may be a scenario where you want to hide a control when using facility-based attributes and relative facilities. Say you have a templated screen with a Text Tool displaying a Gas Meter, but not all Wells have an associated Gas Meter. You could hide the control for a Well that does not have an associated Gas Meter, and by not specifying a UDC, you can always show (or hide) a facility resolution with facility-based attributes only.

7. Configure other grid properties.
8. Save the screen.
9. Run the screen to test your configuration.

The Row configuration property is where you specify the source of the data to use for the rows of the CygNet Grid: either from facilities or a SiteService. The source for the facilities can be explicitly configured or received from the screen or another control. If the Facility source is set to <Self>, facilities can be filtered as necessary, and you need to provide a SiteService. Click to reveal a drop-down area where you can configure the source Facility and source SiteService for the grid's rows.

1. Find the Grid properties and configure the desired source of the facility (and possibly SiteService) for your grid.
2. Click to reveal the Facility source selector.

• Source — Options include <Self>, Screen (default), or a list of Sender controls.
  • <Self> — Select <Self> to explicitly configure the facility for this control, which can be further filtered.
  • Screen — Select Screen to inherit the facility from the screen for this control. By default, the sender is the Screen control if no other senders have been configured. Once Screen is selected Inherited from Screen will display for the Facility property.
  • Sender — A list of sender controls that have been configured with a facility will be displayed. Select the name of the control that will send its facility to this control. By default, the sender is the Screen control if no other senders have been configured. Once a sender control has been specified its name will display in the Source field.
• Filter —

  The Facility filter option is visible only if the Facility Source is <Self>.

  Use the Facility filter property to limit the data presented in the control (or row or layer) to any CygNet facility attribute set up for your CygNet installation. Click to open the Facility Filter dialog box where you can create a custom filter rule. The filter rule is displayed in the property label; you do need to open the Facility Filter dialog box to edit the rule.

3. If the facility source is <Self> the SiteService option is available for configuration.
• Source — Options include <Self> or Screen.
  • <Self> — Select <Self> to explicitly configure the SiteService for this control or screen element. A SiteService selector is displayed:
    • SiteService — The SiteService property specifies the SiteService for which the control (or screen or screen element) is to display data. Click to select a service using the Select Service dialog box.
  • Screen — Select Screen to receive the SiteService from the screen for this control or screen element. By default, the sender is the Screen control if no other senders have been configured.

4. Configure other grid properties.
5. Save the screen.
6. Run the screen to test your configuration.

The Custom Context Menu Configuration dialog box is where you configure any custom context menu items that will appear in the right-click context menu for the screen or control. Each custom context menu option will call an event into script so that you can customize screen or control behavior. The custom context menu options will appear at the bottom of the fixed context menu options, separated by a line.

Perform the following steps to configure a custom context menu.

Sample Custom Context Menu Configuration dialog box

1. Click to open Custom Context Menu Configuration dialog box.
2. Click Add to add a menu item.
3. To add child menu items, select the parent menu item and click Add. You can add multiple nested menu items if desired.
4. Click to expand the menu items.
5. For each menu item click on <New> to reveal the properties:
   1. Title — The Title property specifies the menu name to be displayed in the runtime context menu.
   2. Is separator — The Is separator check box indicates whether this menu item will be a separator line in the menu at runtime. Once saved the separator has no configuration and no children. Separators do not have event IDs. Any event ID on a menu item when it’s converted to a separator is deleted. You can give it a title of 'Separator" or "----------" if desired.
   3. Script event ID — The Script event ID specifies the event ID that will be called when the menu item is selected from the runtime right-click context menu. The event ID is passed in as a parameter into the Custom Context Menu Action event, along with other relevant information in the context of the click, for example, facility or point tag, as appropriate.
6. Menu items can be easily reordered by dragging and dropping an item to a new location in the list.
7. Or click (Delete this item and its children) to remove a selected menu item as necessary.
8. Once the context menu items are configured, click OK to save.
9. Or click Cancel to abort and close the Custom Context Menu Configuration dialog box.

The CygNet Grid supports several operational modes to open a new window via hyperlink. Configure the facility sender mode, the double-click mode, the hyperlink mode, and add the screen that will be opened.

1. Find the Hyperlink properties and configure hyperlinking to another screen via a double-click action:
1. Facility sender mode — Select Double click to send facilities to other controls on the screen and send the facility to the configured screen. See Facility sender mode for more detail.
2. Double click mode — Hyperlink to link to a screen in a new window. See Double click mode for more detail.
3. Hyperlink mode —

   The Hyperlink mode property specifies how to handle navigation when clicking an element (e.g., row in a grid, Navigation Button, Shape, or Text Tool). Specify the Screen file source to open in the Screen path property. Several hyperlink navigation options are available:

   • Open — Open a designated screen in a new window (default).
   • Modal open — Open a designated screen in a new modal window. A modal window is a type of popup that is subordinate to a parent window that appears in front of the parent and usurps the parent’s control. You cannot interact with the parent window until the modal window has been closed. This type of window is used when you want a user to focus on or interact with information in the popup.
   • Open and close — Open a designated screen in a new window and close the current screen.
   • Replace — Replace the current screen with the designated screen.
   • Replace with navigation — Replace the current screen with the specified screen and add a navigation toolbar to the top of the screen.
   • Close — Close the current screen.

   The default value is Open.

   See Hyperlinking Screens for more information about this functionality.

4. Screen file source —

   This property specifies the source of the file, object file, screen file, image file, or video file. Options include:

   • BSS — Indicates that the file is stored in an APPS or BSS folder
   • Local — Indicates that the file is stored in a local or network file-system folder.
5. Screen path —

   The Screen path property specifies the screen that will open when an element (e.g., a row in a Grid, Image or Shape on a Map, Navigation Button, Shape, or Text Tool) is clicked. Browse for the screen file.

   Click to select a path and file from the Open / Open File / Select File dialog box, where you can access:

   • BSS — Indicates that the file is stored in an APPS or BSS folder
   • Local — Indicates that the file is stored in a local or network file-system folder.
2. Configure other grid properties.
3. Save the screen.
4. Run the screen to test your configuration.