---
title: "system.vision.desktop"
description: "Allows for invoking system.vision functions on a specific desktop."
---

# system.vision.desktop

> Allows for invoking system.vision functions on a specific desktop.

:::info Backwards Compatibility
This function replaces both [system.gui.desktop](versioned_docs/version-8.1/appendix/scripting-functions/system-gui/system-gui-desktop.md) and [system.nav.desktop](versioned_docs/version-8.1/appendix/scripting-functions/system-nav/system-nav-desktop.md). Any scripts containing Vision Client scoped functions that were replaced with system.vision syntax will still work to maintain backwards compatibility.
:::

This function is used in **Python Scripting**.

## Description
See the [Multi-Monitor Clients](ignition-modules\vision\common-tasks-in-vision\multi-monitor-clients\multi-monitor-clients.md) page for more details.

## Client Permission Restrictions
This scripting function has no [Client Permission](../../../ignition-modules/vision/vision-project-properties/vision-project-properties.md#vision-permissions-properties) restrictions.

## Syntax
`system.vision.desktop(handle)`

### Parameters
Type | Parameter | Description 
------- | ------- | ------
String | `handle` | The handle for the desktop to use. The screen index cast as a string may be used instead of the handle. If omitted, this will default to the primary desktop. Alternatively, the handle "primary" can be used to refer to the primary desktop.

### Returns

**VisionUtilities** - A copy of [system.vision](system-vision.md) ([VisionUtilities](https://sdk.inductiveautomation.com/javadoc/ignition83/latest/com/inductiveautomation/factorypmi/application/script/builtin/VisionUtilities.html)) that will be relative to the desktop named by the given handle.

### Scope
Vision Client

## Code Examples

```python title="Example #1"
# Attempts to swap to a window at path "Main Windows/Main Window" on a specific Desktop. 
# This example assumes a desktop with the handle "2nd Desktop" is already open.  
system.vision.desktop("2nd Desktop").swapTo("Main Windows/Main Window")
```

```python title="Example #2 - Opening Message Box in a Different Desktop"
# The following example makes a message box appear on the primary desktop,
# regardless of where the script originates.
# system.vision.desktop() function requires a handle be passed to it for this example
# to work properly.

system.vision.desktop().showMessage("This will appear on the Primary Desktop")
```

```python title="Example #3 - Showing Open Windows in a Specific Desktop"
# Retrieves a list of open windows in a specific Desktop. 
# This example assumes a desktop with the handle "2nd Desktop" exists.
name = "2nd Desktop"
# Returns a tuple of open windows in the Desktop named "2nd Desktop".
windows = system.vision.desktop(name).getOpenedWindows()
 
# Converts the tuple to a string, and shows the items in a message box.
system.vision.showMessage(str(windows))
```