DDS Text Tool Properties

Property icon The DDS Text Tool supports the following properties, which are available via the Properties pane and the Canvas script editor. Click next to any property name in the Properties pane to see a short description for the selected property.

See Accessing Screen Objects for more information about how to view control objects in script in the Canvas application.

Categorizing, Sorting, and Finding Properties

You can click Categorize (Categorize), click Alphabetize (Alphabetical within Category) or click Search (Search) within the properties using the features located immediately above the properties list. The search box is useful to help locate a property when an object contains many properties. For clarity, when you enter a search term, items matching your entry string remain displayed and non-matching items are temporarily hidden. Clear the search box to display the full properties list again.

You can expand and collapse each property category by clicking Down arrow or Up arrow next to the group name or simply clicking anywhere in the category heading.

DDS Text Tool Properties

The following tables describe the property names visible in the Properties pane user interface (UI) and the corresponding script property name.
UI Property Script Property Description
Name Type Style

Name

ControlName

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.

Type

ControlType

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.

Style

 

Not supported by TWC 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 Down arrow 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 (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.
LocationBack to top

Height

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 icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

Horizontal resize mode

HorizontalResizeMode

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.

Layer

Layer

Not supported by TWC 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.

Lock

IsLocked

Not supported by TWC 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 icon (Settings) to the right of the control in design mode).

Vertical resize mode

VerticalResizeMode

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.

Visible

IsVisible

Not supported by TWC 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.

Width

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 icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

X

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 icon (Settings) to the right of the control in design mode.

Y

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 icon (Settings) to the right of the control in design mode.

Z index

ZIndex

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 icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.
ScriptBack to top

Include in script

Scripting is not supported by TWC 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.
Text ToolBack to top

Border width

BorderWidth

The Border width property specifies the width of the Text Tool's border.

Horizontal alignment

HorizontalAlignment

The Horizontal alignment property specifies the horizontal position of the text within the boundary of the control. Click Down arrow to select from the following options: Left, Right, Center, or Justify. The default value is Center.

Text trimming

TextTrimming

The Text trimming property determines the text trimming behavior to use when content overflows the content area. Options include:

  • None — The text is not trimmed.
  • Character ellipsis — The text is trimmed at a character boundary. An ellipsis (...) is added in place of the remaining text.
  • Word ellipsis —The text is trimmed at a word boundary. An ellipsis (...) is added in place of the remaining text.

The default value is Character ellipsis.

Text wrapping

TextWrapping

The Text wrapping property determines whether the text wraps when it reaches the edge of the content area. Options include:

  • No wrap — The text is not wrapped.
  • Wrap — The text is wrapped. Very long words will be broken over multiple lines.
  • Wrap with overflow — The text is wrapped. Very long words will be pushed to next line and truncated.

The default value is No wrap.

Vertical alignment

VerticalAlignment

The Vertical alignment property specifies the vertical position of the text within the boundary of the control. Click Down arrow to select from the following options: Top, Center, Bottom, or Stretch. The default value is Center.
TooltipBack to top

Tooltip

TooltipText

Not supported by TWC The Tooltip property specifies the text that will appear on the tooltip. The text display a static text string, such as a label, legend, tooltip, or a dynamic text string 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. In run mode, the tokens are replaced with the attribute's value. Click Open dialog box to configure the static text and/or property tokens using the CygNet Property String dialog box.

Note: A tooltip can be single-line or multi-line.

Type any text, select tokens, and press Enter to separate the lines. If more than five lines are entered, a scroll bar will appear in design mode. The scroll bar does not display in run mode.

Also see the Tooltip Opening event for controls that support tooltips.

  

Tooltip example

Multi-line tooltip example

Note: For tooltips on DDS-based controls, only Facility tokens can be configured if you have a facility tag associated with the control. Point tokens are not supported as there is no point associated with the control.

Tooltip enabled

TooltipEnabled

TooltipDuration

TooltipBetweenShowDelay

TooltipInitialShowDelay

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

Tooltip mode

TooltipMode

Not supported by TWC 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.

Tooltip object path

TooltipObjectPath

TooltipObjectSource

Not supported by TWC The Tooltip object path property specifies the path used for the tooltip when Object mode is selected. Click Open dialog box to select a path and file from the Open / Open File / Select File dialog box, where you can access:

DDSBack to top

Transaction configuration

TransactionConfiguration

The Transaction configuration property is where you specify the name of the Source DDS Button sending the transaction data and the specific Data element Ids (DEIDs) to show in the DDS Text Tool.

Transaction config > Source

TransactionConfiguration.Source

TransactionConfiguration.SourceReceiver

The Source property specifies the name of the source DDS Button sending the transaction data to the DSS Text Tool.

Transaction config >

Data element Id

TransactionConfiguration.DeviceDataElements

The Data element Id property is where you specify what to display on the DDS Text Tool when the DDS Button is clicked. Click Open dialog box to open the Configure Device Types and Device Element Ids dialog box, where you specify the Device type, Data element Id, and Type. Each option is described below.

Data element Id > Device type

The Device type property specifies the device type of the remote field device. This corresponds to the deviceType attribute in the device template’s device definition, and is the same value that appears in the Device Type column in the DDS view in CygNet Explorer.

Data element Id > Data element Id

The Data element Id property specifies a single data group element as defined in the device template file. The DDS Text Tool supports two DEID types: Value and Description.

Data element Id > Type

The Type property specifies what type of DEID to display in the DDS Text Tool. Options are: Value or Description.
DisplayBack to top

Suppress data retrieval

SuppressDataRetrieval

The Suppress data retrieval check box indicates whether all CygNet data retrieval is suppressed for the control or map visual. Use this if you want to store point information in the control but don't want to automatically query services for data. Tokens will not be replaced and point state colors will be ignored.

You can configure the control with a valid point configuration but the control will not retrieve any CygNet data. This allows you to display static text for a control, while still allowing CygNet data context available from script.

If a control has a point configured, but Suppress data retrieval is enabled, Canvas won’t do much point processing. The one exception is point validity. If the control is configured to Hide invalid tag, then Canvas will check if the current tag is valid, even if Suppress data retrieval is enabled. This will allow you to configure some static text that will dynamically hide in the case of a templated screen for a facility that doesn’t have that particular point.

Text

Text

The Text property specifies the text that will appear on the face of the control. The item can display a static text string, such as a label, legend, tooltip, or a dynamic text string 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. In run mode, the tokens are replaced with the attribute's value. Click Open dialog box to configure the static text and/or property tokens using the CygNet Property String dialog box. For most controls there is no default. For the Detail, Donut, and Tile View controls the default value is the %Value% token.
ValueBack to top

Color configuration

ColorConfiguration

The Color configuration drop-down contains all options required to specify the color properties of the control. Click Down arrow 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.

Color config >

Background color

ColorConfiguration.BackgroundSource

ColorConfiguration.BackgroundSelfColor

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

The color can be sourced from one of two 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 can be customized (by selecting <Self>).

Options include:

For each color property select the Source and Color:

  • Source — Click Down arrow 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:  Not supported by TWC  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 Down arrow to customize the color using the color picker.

Note: You can override the default point state colors for this element by creating a custom color palette. See Configuring Color Palettes and Color palette for a screen or object for more information. Not supported by TWC

Color config >

Text color

ColorConfiguration.TextColorSource

ColorConfiguration.TextSelfColor

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 two 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 can be customized (by selecting <Self>).

Options include:

For each color property select the Source and Color:

  • Source — Click Down arrow 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:  Not supported by TWC  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 Down arrow to customize the color using the color picker.

Note: You can override the default point state colors for this element by creating a custom color palette. See Configuring Color Palettes and Color palette for a screen or object for more information. Not supported by TWC

Color config >

Border color

ColorConfiguration.BorderColorSource

ColorConfiguration.BorderSelfColor

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

The color can be sourced from one of two 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 can be customized (by selecting <Self>).

Options include:

For each color property select the Source and Color:

  • Source — Click Down arrow 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:  Not supported by TWC  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 Down arrow to customize the color using the color picker.

Note: You can override the default point state colors for this element by creating a custom color palette. See Configuring Color Palettes and Color palette for a screen or object for more information. Not supported by TWC

Context menu items

CustomContextMenuItems

Not supported by TWC 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 Configure custom context menu items to open the Custom Context Menu Configuration dialog box.

Context menu items > Title

Not supported by TWC The Title property specifies the menu name to be displayed in the runtime context menu.

Context menu items > Is separator

Not supported by TWC 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.

Context menu items > Script event ID

Scripting is not supported by TWC 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.

Show context menu

ShowContextMenu

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.

Note: The CygNet Thin Web Client supports its own context menu in the web view. When activated the context menu appears on the right side of the page. From the CygNet TWC web view context menu you can view point values, acknowledge a point in alarm, view and edit alarm values, and add a selected point to an ad-hoc chart. See Using the Thin Web Client Context Menu.

Not supported by TWC For a context menu on a DDS-based control in the Canvas Native view, the Facility configuration is the only option available when a facility tag is associated with the control. Point tokens are not supported as there is no point associated with the control.

  

DDS Button Context Menu - Facility configuration

DDS Button Context menu example

FontBack to top

Font size

FontSize

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

Font size mode

FontSizeMode

The Font size mode property specifies the method used to size the text on the control. Options include:

  • Auto — Automatically size the text relative to the size of control.
  • Fixed — Size the text using the values specified in the Font size property.

The default value is Auto. The default value for the Text Tool is Fixed.

Text style

TextStyle

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.

Text weight

TextWeight

The Text weight property specifies the weight to use for the text that appears on the control or map visual. Options are: Normal or Bold. The default value is Normal.
GenericBack to top

String

String

Not supported by TWC 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.

Yes/No

YesNo

Not supported by TWC 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.