~~Title: Viewer ~~
<pageheader/>

The **Viewer** object represents a standalone [[:additional_functionality:viewing_images|image viewer]]. 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.

<commandtable columns="3" id="cmdtable_1">
$$ 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]]** 
$$ Returns a **[[lister|Lister]]** 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.

There may be a **parentlister** object in situations where there is no longer a **parenttab** 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 **parenttab** but the **parentlister** property will persist.

This property is a snapshot of the situation when the **Viewer** scripting object was created; it won't change in reaction to script actions.
$$ parentlisterlinked
$$ //bool//
$$ Returns **True** if the viewer is in //Lister-Linked// 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.

This property is a snapshot of the situation when the **Viewer** scripting object was created; it won't change in reaction to script actions.
$$ parenttab
$$ //object://**[[tab|Tab]]** 
$$ Returns a **[[tab|Tab]]** 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.

If you want the **[[lister|Lister]]** rather than the Tab, the **parentlister** property (above) should be used, as it is more persistent. Additionally, do not assume **parenttab** is still the active tab in the Lister; query the Lister object if you need that.

This property is a snapshot of the situation when the **Viewer** scripting object was created; it won't change in reaction to script actions.
$$ 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//
$$ Returns or sets the title bar string for the viewer window.

You can use several special "tokens" in the title string to insert various pieces of information:

|**%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 [[:additional_functionality:viewing_images:image_marking|marked]]|
|**%L**|any [[:file_operations:labels|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
$$ //int//
$$ Returns the top coordinate of the viewer window.
</commandtable>


<commandtable columns="4" id="cmdtable_2">
$$ Method Name
$$ **Arguments**
$$ Return Type
$$ Description
$$ AddFile
$$ <string:filepath>\\ <int:index>
$$ //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
$$ <string:command> or\\
<**[[command|Command]]**:command>
$$ //none//
$$ Runs a command in the context of this viewer window. You can either pass a string or a **[[command|Command ]]**object.

If the argument you pass is a string then it can only be a viewer command argument as documented for the **[[..:..:command_reference:internal_commands:show|Show]] VIEWERCMD** command. For example, **Command("next")** would run the **Show VIEWERCMD=next 
** command in the context of this viewer.

If you pass a **[[command|Command]]** object then all commands (internal or external) can be used.
$$ 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
$$ <int:index> or\\
<string:filepath>
$$ //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//
$$ 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.

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.

Returns true on success.
</commandtable>