The Name property specifies the unique identifier for this control. Valid characters are A-Z, 0-9, and underscore (_). Special characters and spaces are not permitted. Names cannot start with a number; an underscore will be prefixed if the control name starts with a number. The default value is the object name and the numeric instance. The control's Name is also displayed on the Controls view of the Screen pane.

The read-only Type property displays the type for the control: Button, Chart, CygNet Grid, Edit Box, Object Container, Search Box, Tag Chooser, etc. … The control's Type is also displayed on the Controls view of the Screen pane.

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

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.

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.

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.

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.

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

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

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.

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.

The Color configuration drop-down contains all options required to specify the color properties of the control. Click to reveal a set of color options where you can specify the source of the color to be used for the elements of the control. The Color configuration box consists of the following options.

The Background color property specifies the color used for the background of the control.

The color can be sourced from one of three options provided in the Source drop-down menu:

1. The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). The default value is Auto.
2. The color will be sourced from the point state of the associated point (by selecting Point State).
3. The color can be customized (by selecting <Self>).

Options include:

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.

The Text color property specifies the color used for the text on the control or map visual.

The color can be sourced from one of three options provided in the Source drop-down menu:

1. The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). The default value is Auto.
2. The color will be sourced from the point state of the associated point (by selecting Point State).
3. The color can be customized (by selecting <Self>).

Options include:

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.

The Border color property specifies the color used for the border of the control.

The color can be sourced from one of three options provided in the Source drop-down menu:

1. The color will automatically follow the selected client theme regardless of the underlying color palette (by selecting Auto). The default value is Auto.
2. The color will be sourced from the point state of the associated point (by selecting Point State).
3. The color can be customized (by selecting <Self>).

Options include:

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.

The Display alarm acknowledgment property enables the button'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 button will blink when the associated point is in alarm
• Text — The text on the button will blink when the associated point is in alarm
• Border — The border of the button 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.

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 item 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.

Each custom context menu item has a title and an event script ID; items can be designated as a separator; and custom context menus support nested menu items.

Click to open the Custom Context Menu Configuration dialog box.

The Title property specifies the menu name to be displayed in the runtime context menu.

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.

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.

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.

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.

The Point configuration property is used to configure the CygNet point associated with the control. Click to reveal a drop-down area where you can configure the Selection mode, source Facility tag, source SiteService, source Facility, and the UDC or Long Point ID for the point. Each option is described below.

The Selection mode property is used to determine how the control will receive CygNet information from other controls or from itself. Two options are available; click the desired radio button:

• Facility tag — The Facility tag selector consists of a Source chooser and Resolve to a relative facility check box. If the Source is <Self> a Facility tag selector and relative facility options are also displayed. Facility tag is the default option.
• SiteService / Facility — The SiteService / Facility selector consists of Source and SiteService and facility choosers.

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.

The Facility tag or Facility property is where you specify the source of the facility for the control (or screen) to use. The source for the facility can be explicitly configured for this control or it can be received from another control on the same screen, or from the screen, or from another screen. Click to reveal the Facility tag or Facility selector. Options include:

• Source — Options include <Self>, Screen (default), or a list of Sender controls.
  • <Self> — Select <Self> to explicitly configure the facility for this control. A Facility tag or Facility selector is displayed, depending on the Selection mode:
    • Facility — The Facility property specifies the facility for which the control (or screen) is to display data. Click to select a facility using the Select Facility dialog box.
    • Facility Tag — The Facility tag property specifies the full facility tag identifier for which the control (or screen) is to display data. Click to select a facility using the Select Facility Tag dialog box.
  • 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.

• 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.
  • 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.
  • 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.

The SiteService property is where you specify the source of the SiteService for the control (or screen) to use. The source for the SiteService can be explicitly configured for this control or it can be received from another control on the same screen, or from the screen, or from another screen. Click to reveal the SiteService selector. Options include:

• Source — Options include <Self> or Screen (default):
  • <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.

The Point property is used to determine how the CygNet point will be configured. Click the appropriate radio button to reveal the desired field.

• 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.
• Long point ID — The Long point ID property specifies the long point ID of the CygNet point for which the control is to display data. Type the tag into the field.

The Show context menu check box indicates whether a right-click context menu will be available or suppressed in run mode. The default context menu will allow alarm acknowledgment, access to point history and alarm history, point configuration, and facility configuration.

The Command drop-down box contains the general properties required to configure the options used by the UIS Command Button: the UIS command to execute for a specified facility, any pre-defined command parameters and their values, a status point UDC used to monitor the status of the command, and whether the enable or disable the button while the command is in progress. Configure the UIS Command Button to prompt a user for a parameter value using the Command prompt property.

Click to reveal a set of options where you can configure the general command options and the optional command prompt options. The UIS Command Configuration box consists of the following options.

The Command property specifies the name of the UIS command for the facility as defined in the DDS. Click to select a UIS Command using the Select UIS Command dialog box.

The Value parameter name property specifies the name of the command's 'value' parameter: the component parameter for which the button is going to set a value. Refer to the command component parameters in the DDS for the actual component parameter name.

• Enter only the parameter name. A value(s) can be pre-defined in the Parameters property or the user can be prompted for a value by configuring the Command prompt property.
• Leave this field blank: 1) if the command and parameters are fully defined in the DDS; or 2) if all parameter names and their values are specified using the Parameters property.

The Parameters property specifies the command’s parameter(s) and their values. That is, the component parameter for which the button is going to set a value. Typical parameters include values, start dates, end dates, and counts.

• Set the parameter value to a literal value (e.g., Value=100, where Value is the parameter name and 100 is its value).

The optional Status point UDC property specifies the UDC of the status point used to monitor the status of a UIS command. A status point is a special CygNet point that is used to monitor the status of a UIS command. One purpose of the status point is to prevent users from repeatedly clicking the button and queuing up messages. See Status point enables/disabled button for more information about using a status point. Click to select a UDC using the Select UDC dialog box.

The optional Status point enables/disables button check box indicates whether to enable or disable the button while the command is in progress. If enabled and the button's command is in progress (that is, it’s in the communications queue), the value of the status point is set to "1:In Progress" and the button is disabled. The button remains disabled as long as the message is in the queue. Once the command fails or succeeds, the value of the status point is set to "2:Failed" or "3:Succeeded," respectively, and the button is re-enabled.

• Click to enable or disable the button while the command is in progress.

The Command prompt drop-down box contains the properties required to configure the prompt for value popup optionally required by the UIS Command Button: the type of prompt to display, whether to set a default value, the default value, and whether to display a confirmation that the command is sent.

Click to reveal a set of options where you can configure the general command options and the optional command prompt options. The UIS Command Configuration box consists of the following options.

The Prompt type property contains three radio buttons to indicate what type of prompt to display. Select the desired option:

• No prompt — No prompt will show and the UIS command will be sent when the button is clicked. This is the default option.
• Prompt for confirmation — A prompt will show asking the user to Confirm that they want to send the UIS command. If the user clicks Cancel the command is not sent.
• Prompt for value — A prompt will show asking the user to enter a parameter value for the command and then click Send to execute the command.

Click the Set default value check box to indicate whether to set a default value for the prompt.

The Default value property is used to optionally specify the default value for the prompt. This can be a static value or the current value of a point. If specifying a current value it must be a fully qualified tag string. Enter a default value in the field.

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

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.

The Show image property indicates whether to display an image on the button.

The Size property indicates the size of the image on the control.

The Mouse cursor property determines which mouse cursor will appear when the mouse hovers over this control or map visual. Select an option from the drop-down menu: Arrow (), Hand (), Wait (), or Help (). The default cursor is the Arrow ().

The Tooltip enabled property indicates whether to display a tooltip when the mouse hovers over the control or map visual.

The Tooltip mode property specifies how the tooltip will be displayed. Options include:

• Text — The tooltip displays as plain and/or tokenized text defined in the Tooltip property, using resolved point and facility properties.
• Object — The tooltip displays as a Canvas object, passing in the facility tag of the control.
• Script — A TooltipOpening event is fired to allow script to create a custom tooltip.

The default value is Text.

The Font size property specifies the font size of the text on the control or map visual.

The Text style property specifies the style to use for the text that appears on the control or map visual. Options include: Normal, Italic, or Oblique. The default value is Normal.

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.