1. Before adding a map control to a Canvas screen, you must first configure the global map settings in the Backstage view. Global map settings include the map provider, API key, and the CygNet facility attributes where latitude and longitude coordinates are stored. See Configuring Map Settings for more information.
2. In design mode, create a new Canvas screen.
3. Find the Map on the Toolbox pane and drag a desired object to your screen.

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

5. 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.
6. 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.

7. Configure the Location properties. See To configure location, size, resizing, layer, and visibility properties below.
8. 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.

9. Configure the general Map properties. See To configure general map properties below.
10. Configure the Map layer properties. See To configure a map layer below.
11. 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.

12. Configure other Map properties.
13. Save the screen.
14. 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 map properties.
3. Save the screen.
4. Run the screen to test your configuration.

1. Find the Map properties, which consist of the following:

1. Center — The Center property represents the center point of the map view when first displayed in run mode and is indicated by location coordinates. If no value is entered (default), the map is centered at 0°N 0°E, a point where the Prime Meridian intersects with the Equator, in the Gulf of Guinea off the coast of West Africa. Type the desired latitude and longitude location coordinates, for example, 29.76045,-95.36978, which represents the city of Houston, TX.
2. Distance unit — The Distance unit property specifies the distance units (or scale) to use for the map. Options are Kilometers or Miles (default).
3. Layers —

   The Layers property is where you configure the properties required to display the layers that will appear on your map. Layer properties include its name, visibility, data source, facility source, and visuals, which can be an image, a geometric shape, or a Canvas object. You can add as many layers and items as you want to your map. Click to open the Map Layer Configuration dialog box.

   See To configure a map layer below.
4. Mode —

   The Mode property indicates the map view mode to use when the map is first displayed. Options include:

   • Road — Displays road imagery with labels, which is a set of static tiles generated ahead of time and then stored and served. Road is the default mode and is supported by all map providers.
   • Aerial — Displays worldwide orthographic aerial and satellite imagery with labels. You can hide the labels at runtime using the map toolbar. Note that the Aerial mode is only supported by Bing Maps in Canvas and by Azure Maps in TWC. See Using a Map in Run Mode.
5. Zoom level —

   The Zoom level property represents the different levels of detail available on the map when initialized. The maximum level of available detail is determined by the location you are zooming into, for example, some areas can be zoomed in further than other areas. Type a value between 0 and 20. The default value is 0, which displays the whole world. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.

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

1. Find the Map Layer properties, and define the following properties for each map layer.

The Layers property is where you configure the properties required to display the layers that will appear on your map. Layer properties include its name, visibility, data source, facility source, and visuals, which can be an image, a geometric shape, or a Canvas object. You can add as many layers and items as you want to your map. Click to open the Map Layer Configuration dialog box.

2. Configure the Common properties for the map layer. The Layers > Common property group contains properties that configure the layer's name, visibility setting, and data source.

1. Name — The Name specifies the name of the map layer.
2. Visible — The Visible check box indicates whether to display the layer on the map in run mode.
3. Data source —

   The Data source specifies the source of the data used in the map layer. Only one option is available:

   • CygNet — The data used in the map layer will be sourced from the facility coordinates specified in the Facility service attributes. See Configuring Map Settings for more information.

3. Configure the Facility properties for the map layer. The Layers > Facility property group contains properties that tell the layer from where its facility is sourced. Options include <Self> or Screen.

1. Facility Source — The Facility property specifies the facility source for the map layer. Options include:
   • Source — Options include <Self> or Screen.
     • <Self> — Select <Self> to explicitly configure the facility for this layer, which can be further filtered. An override SiteService source and service can also be configured. <Self> is the default value.
     • Screen — Select Screen to inherit the facility from the screen for this map layer.

   Note: A specific map layer can act as a facility sender, which can be designated as the facility source on any other control configured to receive it. Whenever the visible items are updated (via pan, zoom, etc.) the dependent control’s facilities are updated accordingly.

2. Facility 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. SiteService — SiteService is only visible if the Facility Source is <Self>. The SiteService property specifies the source SiteService for the map layer. Options include:
   • 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 the Visuals properties for the map layer.

The Layers > Visuals tab of the Map Layer Configuration dialog box is used to configure the visuals displayed on each map layer. A visual represents what will be displayed for the facility at the coordinates specified. By default, this could be an image or icon to represent a facility location on the map layer, for example, well facilities could show an oil droplet icon. Alternately, you can display a geometric shape at the facility location or a Canvas object (.cob file).

• Click Add visual to add a visual item to the map layer.
• Select the new row in the Visuals grid to reveal the configuration properties for the selected visual. Configure each visual as necessary:
  • Layers > Visuals > Image configuration
  • Layers > Visuals > Shape configuration
  • Layers > Visuals > Object configuration
• Or click (Delete visual) to remove a visual from the layer as necessary.

5. Configuration steps for each visual type are described below. See To configure an image visual, To configure a shape visual, or To configure an object visual.
6. Configure other map properties s necessary.
7. Save the screen.
8. Run the screen to test your configuration.

For the Image visual type configure all desired properties in the groups in the pane on the right: Common, Image, Value, Display, Font, Tooltip, and Hyperlink.

An icon and tooltip will display next to any property that is supported by the CygNet TWC web view.

1. Find Layers in the Properties pane and click to open the Map Layer Configuration dialog box.
2. Click Add layer to add a new layer to the map.
3. Select the new layer and configure the Common and Facility properties on the General tab.
4. Select the Visuals tab.
5. Click Add visual to add an item to the map layer. Select the visuals type from the drop-down menu: Image, Shape, or Object.

6. Configure the various image properties in the pane on the right.
   1. Configure the Common properties for the image visual.
      1. Name — The Name specifies the name of the visual item on the map layer.
      2. Visibility —

         The Visibility property specifies the visibility mode and zoom level of a visual item on a map layer. Use this property to restrict the item to a zoom range. By assigning different zoom ranges to different visuals you can change what is displayed as you zoom in and out of the map. For example, you could display an small image (e.g., a well icon) to designate facility locations when zoomed out to a state level, which could then change to display a Canvas object displaying additional facility information as you zoom into a neighborhood where facilities are located.

         The Visibility options include:

         • On — Visibility for the visual item is always on and is based on the configured Zoom level property.
         • Zoom — Specify the zoom range for the visual item. Type a value to indicate the minimum and maximum zoom level for this visual. See Restrict a Visual Item to a Zoom Range for more information.
           • Minimum zoom — The Minimum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
           • Maximum zoom — The Maximum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
   2. Configure the Image for the image visual.

      Note: To prevent unexpected resizing of images we recommend that you use a uniform-sized image for the default image and any point-state alarm images to be displayed. You may be tempted to create different-sized images for different point states, but the map control does not resize images as the point state changes. The image size remains constant at the size displayed when the control is initialized.

      1. Image file path * —

         If the item on the map layer is an image, you can specify an image to represent facility locations on the map layer, for example, wells could show an oil droplet image. The common image types are supported (.svg, .bmp, .jpg, .png, etc…). Browse for the image 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. Image size * — The Image size property indicates the size of the item on the map layer.
      3. Image height * — The Image height property indicates the height of the configurable image to be displayed on the map layer.
      4. Image width * — The Image width property indicates the width of the configurable image to be displayed on the map layer.
      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.

         Sample Image Selection dialog box

         1. Click to open Image Selection dialog box.
         2. Select the appropriate Point scheme. The point scheme defines the point types, point alarms, point statuses, and default colors for a CygNet domain.
         3. Select the Point type to access the point states on the right. The point types are configured for the selected point scheme for your CygNet system. The default CygNet Standard Point Scheme has eight point types: Analog Input & Analog Output, Digital Input & Digital Output, Enumeration Input & Enumeration Output, and String Input & String Output.
         4. Click on the Point state for which you want to configure an image to use when the point state changes in the control. 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).
         5. For each point state perform the following:
            1. 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.
            2. Repeat for each point state.
         6. To remove an image, delete the path in the Image field.
         7. Once the images are configured, click OK to save.
         8. Or click Cancel to abort and close 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. Resolution mode —

         The Resolution mode property determines how a point's status should be used to select images to display. The image will display based on the point state or the alarm condition of the associated point. The point state of the associated point is evaluated to determine which image to display. Options include:

         • Point state — all possible point states are included
         • Alarm condition — only point states marked explicitly as an alarm condition in the CVSMetadata are included (point states with the alarm condition attribute set to "true")

         The default option is Point state. Point-state-aware images are configured in the Images property.

         Additional Resources

         For more information about Point State and Alarm Condition, see Points > Points Overview > Point State and Alarm Condition.

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

      
      If the Image height and/or Image width values exceed the boundaries of the visual, the image uses the selected Size mode behavior and is uniformly stretched to fit the item's boundaries. If the Image height and/or Image width values are smaller than the boundaries of the item, the image will be centered within the item's boundaries.
   3. Configure the Value properties for the image visual.
      1. UDC * — The UDC property specifies the UDC to use with the list of facilities to generate the points that will populate this map visual. Click to select a UDC using the Select UDC dialog box.
      2. Suppress data retrieval * —

         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.

      3. 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.
      4. 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.

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

   4. Configure the Display for the image visual.
      1. Text —

         The Text property specifies the text that will appear on the face of the visual item. 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 to configure the static text and/or property tokens using the CygNet Property String dialog box.

         Notes:
         

         • Image — If you’d like to include a Text description on the image visual item, we recommend that you set the Width of the image to a value approximately equal to the width of the text, otherwise Canvas will clip the text. Set the Height of the image equal to the actual image size specified.

         • Shape — If you’d like to include a Text description on the shape visual item, we recommend that you set the Width of the shape to a value approximately equal to the width of the text, otherwise Canvas will clip the text. Set the Height of the shape to a value that will fit the text Font size. As the shape will stretch to fill the rectangular bounding box of the control, you should modify the shape’s Stretch property to either Uniform or None depending on the configuration of the actual shape.
      2. Mouse cursor — 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 ().
   5. Configure the Font for the image visual.
      1. Font size — The Font size property specifies the font size of the text on the control or map visual.
      2. Text style — 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.
      3. Text weight — 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.
   6. Configure the Tooltip for the image visual.
      1. Tooltip mode —

         The Tooltip mode property specifies how the tool 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.

         The default value is Text.

         Note: Scripted tooltips are supported for a scripted map via a TooltipOpening event where a custom tooltip can be constructed.

      2. Tooltip enabled — The Tooltip enabled property indicates whether to display a tooltip when the mouse hovers over the map visual.
      3. Tooltip —

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

         Multi-line tooltip example

   7. Configure the Hyperlink properties to indicate what to do when the image is clicked.
      1. Click mode —

         The Click mode property determines the type of click to use when clicking on an image or a shape visual item on a map. Any associated facility will be passed to the specified screen (or script). Options are:

         • None — No hyperlink action is taken, however if a script is coded on the control’s Click event, the script will be executed.
         • Single click — A single click will open the specified screen, and the control’s Click event is disabled.

         None is the default value.

         

      2. Hyperlink mode —

      The Hyperlink mode property specifies how to handle navigation when clicking an image or shape on a Map. Specify the Screen file source to open in the Screen path property. Three 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.
      • Replace — Replace the current screen with the designated screen.

      The default value is Open.

      See Hyperlinking Screens for more information about this functionality.

      3. 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.
      4. 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.
   * As a commonly configured property, this property appears in two locations in the configuration pane: at the top with other Common properties and within its own property category. The property can be configured in either location.

7. Click (Delete visual) to remove an item from the layer, as necessary.
8. Click (Delete layer) to remove a layer from the map, as necessary.
9. Once the layers and visuals are configured, click OK to save.
10. Or click Cancel to abort and close the Map Layer Configuration dialog box.

For the Shape visual type configure all desired properties in the groups in the pane on the right: Common, Shape, Value, Color configuration, Display, Font, Tooltip, and Hyperlink.

1. Find Layers in the Properties pane and click to open the Map Layer Configuration dialog box.
2. Click Add layer to add a new layer to the map.
3. Select the new layer and configure the Common and Facility properties on the General tab.
4. Select the Visuals tab.
5. Click Add visual to add an item to the map layer. Select the visuals type from the drop-down menu: Image, Shape, or Object.

6. Configure the various shape properties in the pane on the right.
   1. Configure the Common properties for the shape visual.
      1. Name — The Name specifies the name of the visual item on the map layer.
      2. Visibility —

         The Visibility property specifies the visibility mode and zoom level of a visual item on a map layer. Use this property to restrict the item to a zoom range. By assigning different zoom ranges to different visuals you can change what is displayed as you zoom in and out of the map. For example, you could display an small image (e.g., a well icon) to designate facility locations when zoomed out to a state level, which could then change to display a Canvas object displaying additional facility information as you zoom into a neighborhood where facilities are located.

         The Visibility options include:

         • On — Visibility for the visual item is always on and is based on the configured Zoom level property.
         • Zoom — Specify the zoom range for the visual item. Type a value to indicate the minimum and maximum zoom level for this visual. See Restrict a Visual Item to a Zoom Range for more information.
           • Minimum zoom — The Minimum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
           • Maximum zoom — The Maximum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
   2. Configure the Shape properties for the shape visual.
      1. Custom line style — The Custom line style property specifies a special abbreviated syntax that defines the line's pattern. If you want to manually modify these values, set the Line style type to Custom. For example, 1 3 1 renders a dot-dash-dot effect.
      2. Line style — The Line style property specifies the style of the Shape's border line. Click to select from the following options: Custom, Solid, Dashed, and Dotted. The default value is Solid. Select Custom to define your own line style and enter the values in the Custom line style property.
      3. Line width — The Line width property specifies the width of the Shape's border line.
      4. Shape geometry * — The Shape geometry property specifies a special abbreviated syntax that defines the shape's geometry. If you want to manually modify these values, set the Shape type to Custom. See Configuring Your Own Custom Shapes for information about how to create your own custom shapes.
      5. Shape type * —

         The Shape type property specifies the type of shape to draw on the map layer. Click to select from the following options:

         • Circle
         • Custom (default)
         • Diamond
         • Horizontal Line
         • Vertical Line
         • Square
         • Triangle
         • Horizontal Valve
         • Vertical Valve

         The default value is Custom. Select Custom to define your own shape and enter the values in the Shape geometry property.

         See Configuring Your Own Custom Shapes for information about how to create your own custom shapes.

      6. Shape size * — The Shape size property indicates the height and width of the shape on the map layer.
      7. Shape height * — The Shape height property indicates the height of the shape to be displayed on the map layer.
      8. Shape width * — The Shape width property indicates the width of the shape to be displayed on the map layer.

      9. Stretch —

         The Stretch property describes how the shape is resized to fill its allocated space. Click to select from the following options:

         • None — The shape preserves its original size.
         • Fill — The shape is resized to fill the destination dimensions. The aspect ratio is not preserved.
         • Uniform — The shape is resized to fit in the destination dimensions while it preserves its native aspect ratio.
         • UniformToFill — The shape is resized to fill the destination dimensions while it preserves its native aspect ratio. If the aspect ratio of the destination rectangle differs from the source, the shape is clipped to fit in the destination dimensions.

         The default value is Fill.

   3. Configure the Value properties for the shape visual.
      1. UDC * — The UDC property specifies the UDC to use with the list of facilities to generate the points that will populate this map visual. Click to select a UDC using the Select UDC dialog box.
      2. Suppress data retrieval * —

         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.

      3. 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.
      4. 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.

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

   4. Configure the Color configuration for the shape visual.
      1. Fill color —

         The Fill color property specifies the color used for the internal body of the Shape.

         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.

         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.

      2. Text color —

         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.

         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.

      3. Line color —

         The Line color property specifies the color used for the border line of the Shape.

         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.

         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.

   5. Configure the Display for the shape visual.
      1. Text —

         The Text property specifies the text that will appear on the face of the visual item. 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 to configure the static text and/or property tokens using the CygNet Property String dialog box.

         Notes:
         

         • Image — If you’d like to include a Text description on the image visual item, we recommend that you set the Width of the image to a value approximately equal to the width of the text, otherwise Canvas will clip the text. Set the Height of the image equal to the actual image size specified.

         • Shape — If you’d like to include a Text description on the shape visual item, we recommend that you set the Width of the shape to a value approximately equal to the width of the text, otherwise Canvas will clip the text. Set the Height of the shape to a value that will fit the text Font size. As the shape will stretch to fill the rectangular bounding box of the control, you should modify the shape’s Stretch property to either Uniform or None depending on the configuration of the actual shape.
      2. Mouse cursor — 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 ().
   6. Configure the Font for the shape visual.
      1. Font size — The Font size property specifies the font size of the text on the control or map visual.
      2. Text style — 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.
      3. Text weight — 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.
   7. Configure the Tooltip for the shape visual.
      1. Tooltip mode —

         The Tooltip mode property specifies how the tool 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.

         The default value is Text.

         Note: Scripted tooltips are supported for a scripted map via a TooltipOpening event where a custom tooltip can be constructed.

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

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

         Multi-line tooltip example

   8. Configure the Hyperlink properties to indicate what to do when the shape is clicked.
      1. Click mode —

         The Click mode property determines the type of click to use when clicking on an image or a shape visual item on a map. Any associated facility will be passed to the specified screen (or script). Options are:

         • None — No hyperlink action is taken, however if a script is coded on the control’s Click event, the script will be executed.
         • Single click — A single click will open the specified screen, and the control’s Click event is disabled.

         None is the default value.

         

      2. Hyperlink mode —

      The Hyperlink mode property specifies how to handle navigation when clicking an image or shape on a Map. Specify the Screen file source to open in the Screen path property. Three 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.
      • Replace — Replace the current screen with the designated screen.

      The default value is Open.

      See Hyperlinking Screens for more information about this functionality.

      3. 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.
      4. 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.
   * As a commonly configured property, this property appears in two locations in the configuration pane: at the top with other Common properties and within its own property category. The property can be configured in either location.

7. Click (Delete visual) to remove an item from the layer, as necessary.
8. Click (Delete layer) to remove a layer from the map, as necessary.
9. Once the layers and visuals are configured, click OK to save.
10. Or click Cancel to abort and close the Map Layer Configuration dialog box.

For the Object visual type configure properties in the pane on the right: Name, Visibility, and Object file path.

1. Find Layers in the Properties pane and click to open the Map Layer Configuration dialog box.
2. Click Add layer to add a new layer to the map.
3. Select the new layer and configure the Common and Facility properties on the General tab.
4. Select the Visuals tab.
5. Click Add visual to add an item to the map layer. Select the visuals type from the drop-down menu: Image, Shape, or Object.

6. Configure the various object properties in the pane on the right.
   1. Configure the Common properties for the object visual.
      1. Name — The Name specifies the name of the visual item on the map layer.
      2. Visibility —

         The Visibility property specifies the visibility mode and zoom level of a visual item on a map layer. Use this property to restrict the item to a zoom range. By assigning different zoom ranges to different visuals you can change what is displayed as you zoom in and out of the map. For example, you could display an small image (e.g., a well icon) to designate facility locations when zoomed out to a state level, which could then change to display a Canvas object displaying additional facility information as you zoom into a neighborhood where facilities are located.

         The Visibility options include:

         • On — Visibility for the visual item is always on and is based on the configured Zoom level property.
         • Zoom — Specify the zoom range for the visual item. Type a value to indicate the minimum and maximum zoom level for this visual. See Restrict a Visual Item to a Zoom Range for more information.
           • Minimum zoom — The Minimum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
           • Maximum zoom — The Maximum zoom level where this visual item will be displayed on the map layer. For reference, the following values approximate the zoom levels: World = 2, State = 4, Region = 10, City = 14, Neighborhood = 18.
   2. Configure the Object properties for the object visual.
      1. Object file path —

      If the visual item on the map layer is an object, you can specify a Canvas object file (.cob) to represent facility locations on the map layer, for example, a small object could display details about a facility location on the map. Browse for the object file (.cob).

      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.

      Note: If you want the object visual item to display tooltips, they must be configured for the controls that are included in the object file (.cob).

7. Click (Delete visual) to remove an item from the layer, as necessary.
8. Click (Delete layer) to remove a layer from the map, as necessary.
9. Once the layers and visuals are configured, click OK to save.
10. Or click Cancel to abort and close the Map Layer Configuration dialog box.