Multi-Monitor Clients

Multiple Desktops

In some situations, such as control rooms, or workstations with multiple monitors, it may be preferable to have clients open on several monitors so that different windows are simultaneously in view. Instead of opening several different clients, it is possible to open a single client, and spawn multiple Desktops through scripting. Desktops are additional workspaces where windows may be opened. They are similar in functionality to a standalone Client in that they may be positioned and resized independently of other Desktops and Clients, but share a session ID with the initial Client that spawned the Desktop.

Client Tags and Property Values

The value of Client Tags are shared between each Desktop. This provides an easy method to change values on one desktop from another without interacting with other Clients: simply write to a Client Tag.

Desktops act as separate clients in regard to property values. For example, if a Text Field is placed on a window, and multiple Desktops open that same window, values entered into one Desktop will not overwrite the other Text Fields. If synchronization on these components is preferred, then simply bind the property to a Tag.

Handles

When creating a new Desktop, an optional handle may be assigned to the Desktop. This acts as a name, or reference to the Desktop. If a handle is not provided, then the Desktop may be referenced by the screen index. Handles and indices are useful when trying to interact with specific Desktops from a Python script.

Spotting the Primary Desktop

When multiple Desktops are open, it is important to know that only the Primary Desktop will have a menu bar. Additionally, the title bar on the client will show the name of the project. Additional Desktops will instead show the handle or index of the Desktop by default. However, a custom title may be used when the Desktop is invoked.

Below we see two Desktops. The highlighted Desktop is displaying the title of the project (Documentation). Because this is the Primary Desktop, a menu bar is present. The other Desktop was given a title of "Secondary Desktop". A menu bar is not present because this Desktop is not the primary.

Project Updates

When a project update is pushed to a Client, the Update banner will only appear on the Primary Desktop (assuming the Update Mode of the project is set to Notify). Updating the Primary Desktop will also push the changes to all other local Desktops, so there is no need to update each Desktop individually.

On this page ...

Multi-Monitor Clients

Watch the Video

Opening Another Desktop

Another Desktop may be opened by calling system.gui.openDesktop:

#This will open a new deskop without any windows, and a name of "0"
system.gui.openDesktop()

However, without specifying which windows to open, the Desktop will open without any opened windows. It is recommended to specify at least one window, a title, and a handle for the new desktop. Assuming a window exists at the path "Main Windows/Main Window", the following would open a new Desktop, open the specified window, and specify a title and handle for the window.

#Create a list of window paths to open in the new desktop
windowToOpen = ["Main Windows/Main Window"]
 
#Defines a name for the Desktop, which will be used as both the the title and handle of the window. 
name = "2nd Desktop"

#Creates a new desktop. The desktop will open the windows listed above. 
system.gui.openDesktop(windows=windowToOpen, title=name, handle=name)

Navigating Windows in Desktops

Functions for the gui and nav scripting modules will execute in the Desktop that originated the call: If the Primary Desktop calls system.nav.swapTo, then the Primary Desktop will swap to a new window, but all other desktops will remain unaffected. However, it is possible for a script on one Desktop to force a navigation or GUI change on another Desktop with the following functions:

# to open a popup in your second desktop
# if you are identifying desktops by number, they are zero indexed
system.nav.desktop(1).openWindow('Popups/Popup')

Additional scripting functions that interact with desktops exist in the gui and nav scripting modules. Please see the Scripting Appendix for more details.

Opening a Desktop on Each Monitor

Sometimes you may want your client to open a new desktop on each of your other monitors. It's pretty simple to get all of your monitors and open a client on each, but then you will have two on your main monitor. The following code block shows you how to skip the primary monitor and even how to open specific windows on each new desktop. This example assumes you have a 'Main Window/Overview' window, and that window has a custom string property in the root container named 'Display' to pass values into. Bind a label component to that custom property to easily check your script. This script is best placed in a Client Startup Script to open a client for each monitor on startup.

# Get the screen information for all of your monitors.
# The getScreens() function returns a dataset of the index (0 based), width, and height for each monitor.
screensDataset = system.gui.getScreens()
 
# Open the first window of the project in the (current) primary monitor.
screenIndex = screensDataset[0][0]
monitorNum = screenIndex + 1
primaryScreenText = 'This is Monitor %d' %monitorNum
system.nav.swapTo('Main Windows/Overview', {'Display':primaryScreenText})
 
# Step through all of the screen information, starting with index 1 instead of 0. 
for screenDetails in screensDataset[1:]:
	# unpacks the tuple that is returned for each of the monitors present. Consists of screen index, width, and height of the screen. 
	screenIndex, screenWidth, screenHeight = screenDetails
	monitorNum = screenIndex + 1
	screenText = "This is Monitor %d" %monitorNum
 
	# Open an empty frame on the next monitor. 
	# Assign a handle and apply the width/height for the monitor you are opening on
	handleName = "Monitor %d" %monitorNum
	system.gui.openDesktop(screen=screenIndex, handle=handleName, width=screenWidth, height=screenHeight)
 
	# Open the Main Window on this new desktop and pass the parameters needed.
	system.nav.desktop(handleName).swapTo('Main Windows/Overview', {'Display':screenText})

Contents

Strategic Partner Links

Resources

All Manual Versions