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

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

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

1. Style —

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

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

   Styles are created in two ways:

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

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

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

1. Include in script —

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

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

8. Configure the Nested View properties to configure specific control options (source of the Nested View).

1. Border color —

   The Border color property specifies the color used for the border of the Media Viewer or the Nested View. Click to customize the color using the color picker.

   Note: If no color is specified, the border color will automatically follow the theme color. If your choose a color, but later want to revert back to the theme color, choose the "Transparent" option, and the color will default to the theme color.

2. CygNet connection — See To configure the CygNet connection below.
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 —

   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

Linking between Canvas screens, objects, and Nested Views is quite flexible. You don't need to specify the service or folder information in the path to find related screens, objects, or Nested Views, although you can if desired. When specifying a path to another file, the following notes apply:

If the screen or object file is in an APPS or BSS folder, you can specify the:

• full path of the file
• folder\filename.can of the file (Canvas uses the source file's service)
• filename.can of the file (Canvas uses source file's service and folder)

If the screen or object file is in the local file system, you can specify the:

• full path of the file
• filename.can of the file (Canvas uses source file's path)

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

10. Configure the General properties to configure the basic properties of the object.

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

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

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

1. Height —

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

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

2. Horizontal resize mode —

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

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

   The default value is None.

3. Layer —

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

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

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

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

4. Lock —

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

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

5. Vertical resize mode —

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

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

   The default value is None.

6. Visible —

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

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

7. Width —

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

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

8. X —

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

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

9. Y —

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

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

10. Z index —

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

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

2. Configure any other Nested View properties.
3. Save the screen.
4. Run the screen to test your configuration.

The source of your CygNet data can be explicitly configured for the control or it can be received from the screen or another control.

1. Expand the CygNet property group to reveal the CygNet connection property — The CygNet connection property is used to configure the facility and SiteService associated with this control or screen. Two selection modes are available: a) by Facility tag or b) by SiteService / Facility. This split configuration allows for the inheritance of these properties from other controls, or the specific configuration of the SiteService or the facility, while dynamically changing the other. This use case may be rare; therefore, the Facility tag option is the default. Click to reveal a drop-down area where you can configure the Selection mode, source SiteService, and source Facility. Each option is described below.

1. Selection mode —

   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.

2. SiteService — 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.

3. Facility — 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: Click to reveal the 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.

2. Configure other control properties as necessary.
3. Save the screen.
4. Run the screen to test your configuration.

Canvas has streamlined the mechanism for communicating from a parent screen down to a child screen and from a child screen up to a parent screen allowing for more refined sub-screen messaging and manipulation. A parent screen can call on a nested screen to pass in a message and/or an object to a child nested screen and vice versa.

SendMessage method

Use the SendMessage method on any nested screen to pass in a message to another nested screen. In addition to messages, you can also send and receive objects which can be used to manipulate the receiving screen, including:

• the sending parent or child screen itself
• message arguments that allow access to all controls and properties in the receiving screen
• controls (for example, a grid or button)
• data structures
• lists

In the following examples, a parent screen calls on the Nested View to pass in a message to the child screen ("Message from Parent to Child") and includes an object, which can be anything the sender wants. In this case, the sender (the child screen) sends a reference to its screen properties to the receiver (the parent screen). Since now the parent’s script has a reference to the child’s screen properties, the parent can make changes to those properties, such as changing the SiteService or facility. Here, it changes the child screen’s background color to orange.

In the second example, the child screen returns a message ("Message from Child to Parent") and includes an object to change the parent screen’s background color to pink.

Example — Send and receive a message or object from a parent screen

The following code example shows how a parent screen sends and receives a message and object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
    public class ScreenClass    
    {    
        public static void Main()
        {
            ScreenClass c = new ScreenClass();
        }    
        public ScreenClass()        
        {        
            // control event handler code goes here -- do not modify        
            Objects.Button1.Click += new EventHandler(this.Button1_Click);        
            Objects.Screen.NestedViewMessageReceived += new EventHandler(this.Screen_NestedViewMessageReceived);
            Objects.Button2.Click += new EventHandler(this.Button2_Click);        
        }
        #region Button2        
        private void Button2_Click(object sender, EventArgs args)        
        {        
            // send a message from the Parent to the nested Child screen        
            Objects.View1.SendMessage("Message from Parent to Child", Objects.Screen);        
        }        
        #endregion

        #region Screen        
        private void Screen_NestedViewMessageReceived(object sender, EventArgs args)        
        {        
            // process message sent from the nested Child screen        
            var messageArguments = args as NestedViewMessageEventArgs;        
            var child = messageArguments.Data as CanvasScreenPropertiesViewModel;
            MessageBox.Show("Message received from nested screen: " + messageArguments.ID);        
            child.BackgroundColor = "Orange";        
        }        
        #endregion
        #region Button1        
        private void Button1_Click(object sender, EventArgs args)        
        {        
            // send a message from the Parent to the nested Child screen        
            Objects.View1.SendMessage("Message from Parent to Child", Objects.Screen);        
        }        
        #endregion    
    }
}

Example — Send and receive a message or object from a child screen

The following code example shows how a child screen sends and receives a message and object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    public class ScreenClass
    {
        public static void Main()
        {
            ScreenClass c = new ScreenClass();
        }
        public ScreenClass()
        {
            // control event handler code goes here -- do not modify
            Objects.Button1.Click += new EventHandler(this.Button1_Click);
            Objects.Screen.NestedViewMessageReceived += new EventHandler(this.Screen_NestedViewMessageReceived);
        }
        #region Screen
        private void Screen_NestedViewMessageReceived(object sender, EventArgs args)
        {
            // process message sent from Parent
            var messageArguments = args as NestedViewMessageEventArgs;
            var parent = messageArguments.Data as CanvasScreenPropertiesViewModel;
            MessageBox.Show("Message received: " + messageArguments.ID);
            parent.BackgroundColor = "Pink";
        }
        #endregion
         
        #region Button1
        private void Button1_Click(object sender, EventArgs args)
        {
            // send message from Child to Parent
            Objects.Screen.SendParentMessage("Message from Child to Parent", Objects.Screen);
        }
        #endregion
    }
}