# Viewer

The **Viewer** object represents a standalone [image viewer](../../../additional_functionality/viewing_images). A collection of **Viewer** objects is returned by the [**Viewers**](viewers) object, which is obtainable via the [**DOpus**](dopus)**.viewers** property. For functions launched from within a viewer (e.g. from its toolbar), the current **Viewer** object is provided by the [**ClickData**](clickdata)**.**[**func**](func)**.viewer** property.

| Property Name      | Return Type                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| bottom             | _int_                                                                                                        | Returns the bottom coordinate of the viewer window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                                                  |
| current            | _object:_[**Item**](item)                                                                                    | Returns an [**Item**](item) object representing the currently displayed image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                  |
| desktop            | _string_                                                                                                     | Returns the ID of the virtual desktop this viewer is on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                  |
| files              | _object:_[**Items**](items)                                                                                  | Returns an [**Items**](items) object representing the images in the viewer's list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                  |
| foreground         | _bool_                                                                                                       | Returns **True** if the viewer is currently the foreground (active) window in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                  |
| imagesize          | _object:_[**Rect**](rect)                                                                                    | Returns a [**Rect**](rect) object representing the size of the currently displayed image (native size, ignoring any scaling).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                  |
| index              | _int_                                                                                                        | Returns the index of the currently viewed image within the viewer's list of files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                  |
| lastactive         | _bool_                                                                                                       | Returns **True** if the viewer is the most recently active viewer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                  |
| left               | _int_                                                                                                        | Returns the left coordinate of the viewer window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                                  |
| parentlister       | _object:_[**Lister**](lister)                                                                                | <p>Returns a <a href="lister"><strong>Lister</strong></a> object representing the Lister that launched the viewer (if there was one, and if it still exists) or, if viewer re-use is enabled, last sent files to the viewer.</p><p>There may be a <strong>parentlister</strong> object in situations where there is no longer a <strong>parenttab</strong> object. For example, if the tab was closed since the viewer opened, or if a request to open an image from something other than a folder tab was received by the viewer, then there will no longer be a <strong>parenttab</strong> but the <strong>parentlister</strong> property will persist.</p><p>This property is a snapshot of the situation when the <strong>Viewer</strong> scripting object was created; it won't change in reaction to script actions.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                  |
| parentlisterlinked | _bool_                                                                                                       | <p>Returns <strong>True</strong> if the viewer is in <em>Lister-Linked</em> mode with the parent Lister. This means the viewer acts like a detached preview pane, displaying each file as it is selected in the Lister.</p><p>This property is a snapshot of the situation when the <strong>Viewer</strong> scripting object was created; it won't change in reaction to script actions.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                  |
| parenttab          | _object:_[**Tab**](tab)                                                                                      | <p>Returns a <a href="tab"><strong>Tab</strong></a> object representing the tab that launched the viewer (if there was one, and if it still exists) or, if viewer re-use is enabled, last sent files to the viewer.</p><p>If you want the <a href="lister"><strong>Lister</strong></a> rather than the Tab, the <strong>parentlister</strong> property (above) should be used, as it is more persistent. Additionally, do not assume <strong>parenttab</strong> is still the active tab in the Lister; query the Lister object if you need that.</p><p>This property is a snapshot of the situation when the <strong>Viewer</strong> scripting object was created; it won't change in reaction to script actions.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                  |
| right              | _int_                                                                                                        | Returns the right coordinate of the viewer window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                  |
| selection          | _object:_[**Rect**](rect)                                                                                    | Returns a [**Rect**](rect) object representing the current selection area (if any) of the image. If there's no selection the rectangle will be empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                  |
| title              | _string_                                                                                                     | <p>Returns or sets the title bar string for the viewer window.</p><p>You can use several special "tokens" in the title string to insert various pieces of information:</p><table><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>%P</strong></td><td>full path of the currently viewed image</td><td></td></tr><tr><td><strong>%N</strong></td><td>name of the current displayed image</td><td></td></tr><tr><td><strong>%R</strong></td><td>drive root of the current image</td><td></td></tr><tr><td><strong>%E</strong></td><td>displays * if the image's metadata has been modified and not saved</td><td></td></tr><tr><td><strong>%I</strong></td><td>current image's index (number) in the list of images</td><td></td></tr><tr><td><strong>%O</strong></td><td>total number of images in the list</td><td></td></tr><tr><td><strong>%W</strong></td><td>width of the current image</td><td></td></tr><tr><td><strong>%H</strong></td><td>height of the current image</td><td></td></tr><tr><td><strong>%D</strong></td><td>depth of the current image (bits per pixel)</td><td></td></tr><tr><td><strong>%M</strong></td><td>current image's dimensions</td><td></td></tr><tr><td><strong>%S</strong></td><td>file size on disk</td><td></td></tr><tr><td><strong>%F</strong></td><td>folder name</td><td></td></tr><tr><td><strong>%C</strong></td><td>collection name if current image is <a href="../../../additional_functionality/viewing_images/image_marking">marked</a></td><td></td></tr><tr><td><strong>%L</strong></td><td>any <a href="../../../file_operations/labels">labels</a> assigned to the current image</td><td></td></tr><tr><td><strong>%T</strong></td><td>original title (useful for simply adding a prefix or suffix to the title)</td><td></td></tr><tr><td><strong>%%%%%%</strong></td><td>insert a literal % character</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>top</td><td></td><td></td></tr></tbody></table><p><em>int</em></p> | Returns the top coordinate of the viewer window. |
|                    |                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%P**             | full path of the currently viewed image                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%N**             | name of the current displayed image                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%R**             | drive root of the current image                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%E**             | displays \* if the image's metadata has been modified and not saved                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%I**             | current image's index (number) in the list of images                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%O**             | total number of images in the list                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%W**             | width of the current image                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%H**             | height of the current image                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%D**             | depth of the current image (bits per pixel)                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%M**             | current image's dimensions                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%S**             | file size on disk                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%F**             | folder name                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%C**             | collection name if current image is [marked](../../../additional_functionality/viewing_images/image_marking) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%L**             | any [labels](../../../file_operations/labels) assigned to the current image                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%T**             | original title (useful for simply adding a prefix or suffix to the title)                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| **%%%%%%**         | insert a literal % character                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
|                    |                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
|                    |                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |
| top                |                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                  |

| Method Name        | **Arguments**                                                                                    | Return Type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AddFile            | <p>&#x3C;string:filepath><br>&#x3C;int:index></p>                                                | _none_      | Adds the specified file to the viewer's current list of files. You can either pass a string or a [**Path**](path) object to indicate the file to add to the list. By default the file will be added to the end of the list, unless you specify a 0-based index as the second argument.                                                                                                                                                                                                                                                                                                                                                   |
| Command            | <p>&#x3C;string:command> or<br>&#x3C;<a href="command"><strong>Command</strong></a>:command></p> | _none_      | <p>Runs a command in the context of this viewer window. You can either pass a string or a **<a href="command">Command</a>**object.</p><p>If the argument you pass is a string then it can only be a viewer command argument as documented for the <a href="../../command_reference/internal_commands/show"><strong>Show</strong></a> <strong>VIEWERCMD</strong> command. For example, <strong>Command("next")</strong> would run the **Show VIEWERCMD=next ** command in the context of this viewer.</p><p>If you pass a <a href="command"><strong>Command</strong></a> object then all commands (internal or external) can be used.</p> |
| IsOnCurrentDesktop | _none_                                                                                           | _bool_      | Returns **True** if the viewer is on the current virtual desktop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| MoveToDesktop      | \<string:desktop>                                                                                | _bool_      | Moves the viewer window to the specified virtual desktop. Returns **True** if successful.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| RemoveFile         | <p>&#x3C;int:index> or<br>&#x3C;string:filepath></p>                                             | _none_      | Removes the specified file from the viewer's current list of files. You can either pass the 0-based index of the file to remove, or the filepath (either as a string or a [**Path**](path) object).                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| SetTaskbarGroup    | \<string:group>                                                                                  | _bool_      | <p>Used to change how the viewer window is grouped with other Opus windows on the taskbar. Specify a group name to move the window into an alternative group, or omit the group argument to reset back to the default group. If one or more windows are moved into the same group, they will be grouped together, separate from other the default group.</p><p>This only works when taskbar grouping is enabled. Group names are limited to 103 characters and will be truncated if longer. Spaces and dots in group names are automatically converted to underscores.</p><p>Returns true on success.</p>                                |
