Script objects

The following is a summary of the changes to scripting objects.

CloseListerData

The CloseListerData object has the following new properties:

• prevent_save: Set this to True to prevent the closing Lister from being saved as the new default Lister.

You can use this to revert to the old behavior of not auto-saving Listers that close when the Synchronize or Duplicate File Finder panels are showing:

Script Type: VBScript

Function OnCloseLister(closeListerData)
    If closeListerData.lister.utilpane = 1 Then
        If closeListerData.lister.utilpage = "sync" Or closeListerData.lister.utilpage = "dupe" Then
            closeListerData.prevent_save = True
        End If
    End If
End Function

Column

The Column object has the following new properties:

• autosize: True if the column width is set to auto.

• collapse: True if the column width is set to collapse.

• expand: True if the column width is set to expand.

• fill: True if the column width is set to fill.

• header: provides the name of the column as displayed in the Lister column header.

• label: provides the name of the column as displayed in the Columns tab in the Folder Options dialog.

• max: Maximum width of the column, or “fill” if the maximum is set to fill.

Command

• IsSet: The IsSet() method now takes an optional second argument specifying the command to test against (defaults to "Set" if not provided).

Control

The Control object represents a control on a script dialog; it’s returned by the Dialog.Control method. It has the following methods and properties:

• AddItem: Add an item to the control (list box or combo box). The first parameter is the item's name, and the second optional parameter is a data value to associate with the string. The item is added to the end of the list. You can also pass a DialogListItem object obtained from another control.

• InsertItemAt: Inserts an item in the control (list box or combo box). The first parameter is the index to insert the item at (0-based), the second parameter is the item's name and the third (optional) parameter is a data value to associate with the item. Instead of a name/data value you can also pass a DialogListItem object obtained from another control.

• GetItemAt: Returns a DialogListItem object representing the specified item in the list box or combo box control (specify the item's 0-based index).

• GetItemByName: Returns a DialogListItem object representing the specified item in the list box or combo box control (specify the item's name).

• RemoveItem: Removes an item from a list box or combo box. You can pass either the index of the item to remove (0-based), or a DialogListItem obtained from the GetItemAt or GetItemByName methods.

• SelectItem: Selects an item in a list box or combo box. You can pass either the index of the item to select (0-based), or a DialogListItem obtained from the GetItemAt or GetItemByName methods.

• SelectRange: Selects text within an edit control (or the edit field in a combo box). The two parameters represent the start and end position of the desired selection. To select the entire contents, use SelectRange(0, -1). The return value is a Vector with two members that provide the current start and end of the selection. To query the range without changing it, simply call SelectRange() with no arguments.

• count: Returns the number of items contained in the control.

• enabled: Set or query the enabled state of the control.

• visible: Set or query the visible state of the control.

• focus: Set or query the input focus state of the control.

• label: Set or query the control's label.

• value: Set or query the control's value. This property depends on the type of the control:

  • Edit control: returns or accepts a string representing the current contents of the edit control.

  • Checkbox: for a simple on/off checkbox, returns or accepts a bool - True for checked, False for unchecked. For a tri-state checkbox, returns or accepts a long - 0 (unchecked), 1(checked) or 2 (indeterminate).

  • Radio button: returns or accepts a bool - True for checked, False for unchecked.

  • Tab: returns or accepts a long indicating the current page.

  • List box / combo box: returns or accepts a DialogListItem representing the selected item. When setting the value, also accepts a long representing the 0-based index of the item.

CustomFieldData

The CustomFieldData object is passed to a rename script’s OnGetNewName method via the GetNewNameData.custom property. If a rename script adds custom fields to the Rename dialog using OnGetCustomFields, this object lets you access the values the user provided for each field.

Dialog

The Dialog object has the following new properties and methods:

• detach: Set to True if you want a script dialog to run in “detached” mode, where your script provides its message loop.

• language: Set this property to create a script dialog in a particular language (if one or more language overlays have been provided), rather than the currently selected language.

• template: Set this to the name of the script dialog to display.

• Create: Instead of setting detach to True and then calling Show, you can instead call Dialog.Create. This creates the dialog but does not show it immediately, letting you initialize controls first before the dialog goes visible. Call the Show method once you're ready to show the dialog.

• Control: Returns a Control object corresponding to one of the controls on the dialog. The first parameter is the name of the control; the optional second parameter is the name of the dialog (if you have any child dialogs hosted in tabs), and the optional third parameter is the name of the tab control (if you have multiple tab controls hosting the same dialog).

• EndDlg: Ends a dialog running in detached mode. Normally dialogs end automatically when the user clicks the close button or another button that has its Close Dialog property set to True. This method lets you end a dialog under script control. The optional parameter specifies the result code that the Dialog.result property will return.

• GetMsg: Returns a Msg object representing the most recent input event in the dialog (only used in detached mode).

• RunDlg: Turns a previously detached dialog into a non-detached one, by taking over and running the default message loop. The RunDlg method won’t return until the dialog has closed.

DialogListItem

The DialogListItem object is returned by the Control.GetItemAt and Control.GetItemByName methods. It represents an item in a combo or listbox control in a script dialog. It has the following properties:

• data: Returns or sets the optional data value associated with this item.

• index: Returns the 0-based index of this item within the control.

• name: Returns or sets the item's name.

DOpus

The DOpus object has the following changes:

• DPI: Returns a DPI object which provides information and utility methods relating to the system DPI setting.

• strings: Returns a ScriptStrings object which lets your script access any strings defined as string resources.

• viewers: Returns a Viewers object which represents any currently open standalone image viewers (each one is represented by a Viewer object).

• Output: Scripts can now request timestamps for log messages via an optional 3rd argument to DOpus.Output. e.g. DOpus.Output("Hello", false, true). Timestamps only appear in the utility panel, not in places like the Button Editor's output panel. Error messages always get timestamps so if the second argument is true then the third is ignored.

DPI

The DPI object is returned via the DOpus.DPI property. It contains the following properties and methods:

• factor: Returns the DPI settings as a “scale factor” (e.g. 100, 125, 200).

• dpi: Returns the system DPI setting as a “dpi value” (e.g. 96, 192).

• Scale: Scales the provided size by the system DPI; e.g. if the system DPI was set to 200%, DPI.Scale(75) would return 150.

• Divide: Divides the provided size by the system DPI; e.g. if the system DPI was set to 150%, DPI.Divide(60) would return 40.

Format

The Format object has the following new properties:

• hide_dirs_regex: True if the current hide_dirs pattern is using regular expressions.

• hide_files_regex: True if the current hide_files pattern is using regular expressions.

• manual_sort: Returns True if the manual sort option is active.

• manual_sort_name: If manual sort is active, returns the name of the current sort order (if it has one).

• manual_sort_order: If manual sort is active, returns a SortOrder object which lets you query and change the sort order.

• show_dirs_regex: True if the current show_dirs pattern is using regular expressions.

• show_files_regex: True if the current show_files pattern is using regular expressions.

FSUtil

• OpenFile: The OpenFile method now accepts "NoElevate" or "ElevateNoAsk" to prevent triggering UAC prompts when opening files. "NoElevate" avoids elevation entirely while "ElevateNoAsk" gains elevation only if something else has already triggered it within the script's context. Script columns which open files should use these to avoid triggering annoying UAC prompts in the background.

• ReadDir: The ReadDir method can now optionally enumerate using the shell, which means non-filesystem folders like \\server\ or /mycomputer can be enumerated. Set the optional third parameter for this method to True to use this.

• GetShellPropertyList: Returns a list of shell properties, optionally matching the supplied wildcard pattern.

• GetShellProperty: Returns the value of one or more shell properties for the specified file. You can either provide the name of the property or a Map object to retrieve multiple properties at once.

Item

The Item object has the following changes:

• current: This is only present for Item objects obtained from a Viewer. It will be True if the item represents the currently displayed image.

• name_stem_m: Returns the name stem, taking multi-part file extensions into account (e.g. "cat.and.dog" instead of "cat.and.dog.part1")

• ext_m: Returns the file extension, taking multi-part file extensions into account (e.g. ".part1.rar" instead of ".rar")

• ShellProp: Returns the value of a shell property for the item.

• Open: The Open method now accepts "NoElevate" or "ElevateNoAsk" to prevent triggering UAC prompts when opening files. "NoElevate" avoids elevation entirely while "ElevateNoAsk" gains elevation only if something else has already triggered it within the script's context. Script columns which open files should use these to avoid triggering annoying UAC prompts in the background.

Lister

The Lister object has the following new property:

• utilpage: If the utility panel is open, returns a string representing the currently selected utility page.

GetCopyQueueNameData

This object is passed to the new OnGetCopyQueueName event. It lets a script override the name of the automatically-generated copy queue. The properties are:

• dest: Returns a Path object indicating the destination path of the copy operation.
• desttab: Returns the destination Tab object.
• dest_drives: Returns a binary string indicating the physical drive indices that the destination path is located on (if any).
• move: True if this is a move operation.
• name: The default name of the copy queue. To override this, return the new queue name from the OnGetCopyQueueName event. To accept the default name, return False.
• source: Returns a Path object indicating the source path of the copy operation.
• sourcetab: Returns the source Tab object.
• source_drives: Returns a binary string indicating the physical drive indices that the source path is located on (if any).

GetCustomFieldData

If a rename script implements the OnGetCustomFields method it will be passed a GetCustomField data object that it can use to add custom fields to the Rename dialog. The object contains the following properties:

• fields: Assign values to sub-properties of the fields property to add a field. For example, fields.my_option = True would create a Boolean field called “my_option”.

• field_labels: A Map that lets you provide display names for your fields. For example, fields.field_labels("my_option") = "Option name".

• field_tips: A Map that lets you provide cue banner text for text fields. For example, fields.field_tips("my_text") = "Enter your text here".

GetNewNameData

The GetNewNameData object has the following new properties:

• custom: Returns a CustomFieldData object which lets your script access the values of any custom fields you added via the OnGetCustomFields method.

• oldname_field: content of the Old Name field in the rename dialog (synonym of existing oldname property, which still works).

• newname_field: content of the New Name field in the rename dialog; was previously not available to scripts.
• newname_ext: the proposed new name, extension only, just the last part e.g. ".rar".
• newname_stem: the proposed new name, everything before newname_ext.
• newname_ext_m: the proposed new name, extension only, handles multi-part extensions e.g. ".part1.rar".
• newname_stem_m: the proposed new name, everything before newname_ext_m.

Msg

The Msg object represents a script dialog input event message. It’s returned by the Dialog.GetMsg method which you call when running the message loop for a detached dialog. It has the following properties:

• default value: Returns True if the message is valid, or False if the dialog has been closed (which means you should exit your message loop).

• control:The name of the control involved.

• data:The data associated with the current selection (for a combo box or list box).For a check box or radio button, indicates the check state of the control.

• dialog:The name of the dialog involved.

• event:The event that occurred (invalid, click, dblclk, selchange, editchange).

• focus:True if the control had input focus when the message was generated.

• index:The current selection index (for a combo box or list box).

• result:Returns True if the message is valid or False if the dialog has been closed.

• tab: The name of the tab control hosting the dialog (if any).

• value:The current text value of the control (e.g. for an edit control).

Path

The Path object has the following changes:

• stem: Returns the name stem, not taking multi-part file extensions into account (e.g. "cat.and.dog.part1" instead of "cat.and.dog")

• stem_m: Returns the name stem, taking multi-part file extensions into account (e.g. "cat.and.dog" instead of "cat.and.dog.part1")

• ext_m: Returns the file extension, taking multi-part file extensions into account (e.g. ".part1.rar" instead of ".rar").

Script

The Script object has the following new method:

• LoadResources: Load script resources from an external file (or a raw XML string). If the script is included in a package the file must have .odxml as a file extension.

ScriptColumn

• autorefresh: This property can now be set to 2 to force Opus to update the value for the column when the file's attributes change (normally it would only update if the file modification time or size changed).
• userdata: Allows you to associate a data value with a column. The value will be passed to your column handler in the ScriptColumnData.userdata property.

ScriptColumnData

• userdata: Returns the user data value associated with this column. 

ScriptInitData

The ScriptInitData object has the following new properties:

• group: Lets you specify an arbitrary group for this script. If scripts specify a group they will be displayed in that group in the list in Preferences.
• url: Lets you provide a URL where the user can go to find out more information about the script.
• config_groups: Lets you place configuration values in groups (which can make their display in Preferences easier for the user if you have a lot of options). Accepts a Map object in the same way as the config_desc property.

ScriptStrings

The ScriptStrings object is returned by the DOpus.strings property. It lets you access any strings defined via string resources. It contains the following methods and properties:

• langs: Returns a Vector of strings representing the languages that strings are defined for.

• Get: Returns the text of a specified string (by name). Optionally accepts a second parameter, specifying a language (otherwise the string is returned in current language if it’s defined).

ShellProperty

The ShellProperty object represents a shell property - an item of metadata for a file or folder that comes from Windows or third-party extensions (as opposed to metadata from Opus's native metadata system).

The FSUtil.GetShellPropertyList method lets you retrieve a list of available shell properties. You can then use FSUtil.GetShellProperty or Item.ShellProp to retrieve the value of a property for a particular file.

• defwidth: The default width a column displaying this property should use.
• display_name: The display name of this property (the name that should be shown to users).
• justify: The default column justification for this property (left, right, center).
• pkey: The PKEY (property key) for this property. This is a property's unique ID and the canonical way to refer to a property. You can use the raw_name and display_name values to access properties as well, but they are potentially inaccurate (since it's possible to have two properties with the same name) and also slower as the property has to be looked up by name each time.
• raw_name: An internal name used by the property provider.
• type: The type of data this property returns; string, number, datetime are the only supported types currently.
  

SortOrder

The SortOrder object is returned by the Format.manual_sort_order property if manual sort mode is active. It lets you query and modify the sort order. The object supports the following properties:

• GetOrder: Returns a Vector of strings representing the current sort order of files in the folder. You can optionally provide the name of a sort order as a parameter if you have defined more than one.

• SetOrder: Pass this method a Vector of strings to change the sort order. You can optionally provide the name of a sort order as the second parameter if you’ve got more than one sort order defined.

• ResetOrder: Resets the current sort order to the default. You can optionally provide the name of a sort order as a parameter if you have defined more than one.

Tab

The Tab object has the following new property:

• color: Returns the current color of the tab (in “R,G,B” format) if one has been assigned.

Viewer

The Viewer object represents a standalone image viewer. A collection of Viewer objects is returned by the Viewers object, which is obtainable via the DOpus.viewers property. As well as querying its properties, you can also use a Viewer object as the parameter for the Command.SetSourceTab method, which lets you run commands against a viewer window.

The Viewer object contains the following properties and methods:

• current: Returns an Item object representing the currently displayed image.

• bottom: Returns the bottom coordinate of the viewer window.

• files: Returns a collection of Item objects representing the images in the viewer’s list.

• foreground: True if the viewer is currently the foreground (active) window in the system.

• lastactive: True if the viewer is the last active viewer.

• left: Returns the left coordinate of the viewer window.

• right: Returns the right coordinate of the viewer window.

• top: Returns the top coordinate of the viewer window.

• Command: Runs a command in the context of this viewer. You can either pass a command string (e.g. Command(“Show VIEWERCMD=next”) or a Command object).

Viewers

This object is obtained from the DOpus.viewers property. It represents all currently open standalone image viewers. It is a collection of Viewer objects and can be enumerated as such. It also has the following property:

• lastactive: Returns a Viewer object representing the last active viewer.

ViewerEventData

This object is passed to the OnViewerEvent method, whenever certain events occur in a standalone image viewer.

• event: A string indicating the event that occurred. The events currently defined are create, setfocus, killfocus, destroy and load.
• item: An Item object representing the image file involved (if applicable).
• viewer: A Viewer object representing the viewer the event occurred in.