Scripting Objects

Scripts can interact with Opus using a number of different objects. For example, the Lister object represents a physical Lister window, providing information about that Lister to the script and letting the script modify or control that Lister.

An object has two main types of interface that you can call on:

• Properties let the script query (and sometimes set) a simple value. For example, the Lister object has a title property that lets the script retrieve the Lister window's title string.

• Methods are functions an object provides that the script can invoke to perform a task. For example, the DOpus object has an Output method that lets the script output a text string to the script log.

The main distinction between properties and methods is that methods can (but don't always) accept arguments that modify their behavior, and don't have to (but often do) return a result.

Variable types

Properties and methods that return a result can return a number of different types of variables, and methods often take one or more parameters that can also be a number of types. ActiveX scripting languages are generally typeless - that is, a variable's type does not have to be defined in advance, and conversion from one type to another is often (but not always) automatic. Opus scripting mainly uses variables of the following types:

• Int - a whole number (signed; valid range is -2147483648 to 2147483647).

• Currency - this is a standard variant type, and is used by Opus in just a couple of cases that require numbers larger than an Int can hold (unfortunately ActiveX scripting does not always support a 64 bit integer type).

• Decimal - an unsigned 64 bit value (maximum value 18,446,744,073,709,551,616). Not all languages support this - JScript does, but VBScript does not.

• String - a text string

• Bool - a Boolean (either True or False)

• Date - a date/time value

• Collection - a collection of multiple objects of (generally) the same type. Collections can be easy enumerated in some languages (e.g. in VBScript, using the For Each construct). Collections are only returned by Opus - unlike an array (or a Vector object), they are never created or modified directly (although some script methods can be used to modify them in certain cases). For example, the Tab object has a property called selected that represents all currently selected items in that tab - it is a collection of items.

• Object - an Opus script object with defined methods and properties (one of the object types listed below). Some objects can be both an object and a collection - that is, they have methods and properties, but can also be enumerated like a collection. Some objects also have a default value - that is, simply using the object's name without any method or property will return a value of its own. For example, the Metadata object's default value is a string indicating the primary type of metadata available. You can also refer to an object's default value using the special def_value property name.

• Variant - a variable of any type (this is used with a few objects - for example, a Var object can store a variant)

Global objects

There are two objects that are provided to scripts as global variables when they are invoked by Opus:

• DOpus: This** **object is available to all scripts. It provides various helper methods, and collections that let you access things like Listers and toolbars.

• Script: This** **object is provided to script add-ins when their various event handlers are invoked. It provides information relating to the script itself.

Event objects

There are a number of objects that Opus provides as parameters to methods within a script. For example, when a script function is invoked (e.g. when the button is clicked), Opus calls its OnClick method, passing it a ClickData object.

• AboutData: This object is provided to the OnAboutScript method, which is called when the user clicks the About button for a script in the Script Management dialog.

• ActivateListerData: This object is provided to the OnActivateLister method, which is called whenever a Lister window is activated or deactivated.

• ActivateTabData: This object is provided to the OnActivateTab method, which is called whenever a tab is activated.

• AddCmdData: This object is provided to the OnAddCommands method, which allows a script to add new internal commands.

• AddColData: This object is provided to the OnAddColumns method, which allows a script to add new information columns.

• AfterFolderChangeData: This object is provided to the OnAfterFolderChange method, which is called after a new folder has been read.

• BeforeFolderChangeData: This object is provided to the OnBeforeFolderChange method, which is called before a new folder is read.

• ClickData: This object is provided to the OnClick method, which is called whenever a script function is invoked (e.g. when the button is clicked or hotkey pressed).

• CloseListerData: This object is provided to the OnCloseLister method, which is called before a Lister closes.

• CloseTabData: This object is provided to the OnCloseTab method, which is called before a tab closes.

• ConfigChangeData: This object is provided to the OnScriptConfigChange method, which notifies a script when the user edits the script's configuration.

• DisplayModeChangeData: This object is provided to the OnDisplayModeChange method, which is called when the display mode changes in a tab.

• DoubleClickData: This object is provided to the OnDoubleClick method, which is called when a file or folder is double-clicked.

• FileOperationCompleteData: This object is provided to the OnFileOperationComplete method, which lets you receive notification when certain file operations complete.

• FilesystemChangeData: This object is provided to the OnFilesystemChange method, after you've established monitoring for file or folder changes via the FSUtil.WatchChanges method.

• FlatViewChangeData: This object is provided to the OnFlatViewChange method, which is called when the Flat View mode changes in a tab.

• GetCopyQueueNameData: This object is provided to the OnGetCopyQueueName event, which is called whenever a copy operation begins that uses automatically-managed copy queues.

• GetCustomFieldData: This object is provided to the **OnGetCustomFields**event, which lets a rename script add its own fields to the Rename dialog.

• GetNewNameData: This object is provided to the OnGetNewName method, which is one of the supported methods a rename script can provide.

• ListerResizeData: This object is provided to the OnListerResize event, which is called whenever a Lister window is resized.

• ListerUIChangeData: This object is provided to the OnListerUIChange method, which is called when various user interface elements (tree, viewer, etc) are open or closed in a Lister.

• OpenListerData: This object is provided to the OnOpenLister method, which is called when a new Lister is opened.

• OpenTabData: This object is provided to the OnOpenTab method, which is called when a new tab is opened.

• ScriptColumnData: This object is provided to the script-specified method used to add new columns to Opus.

• ScriptCommandData: This object is provided to the script-specified method used to add new internal commands to Opus.

• ScriptFAYTCommandData: This object is provided to the script-specified method used to extend the FAYT field.

• ScriptInitData: This object is provided to the OnInit method, which is called once to initialize each script in the Script Addins folder.

• ShutdownData: This object is provided to the OnShutdown method, which is called before Opus shuts down.

• SourceDestData: This object is provided to the OnSourceDestChange method, which is called when the source or destination state of a tab changes.

• StartupData: This object is provided to the OnStartup method, which is called when Opus starts up.

• StyleSelectedData: This object is provided to the OnStyleSelected method, which is called when a new style is chosen in a Lister.

• SystemSettingChangeData: This object is provided to the OnSystemSettingChange method, which is called when various system settings change.

• TabClickData: This object is provided to the OnTabClick event, which is called whenever a tab is clicked with a qualifier key held down.

• ViewerEventData: This object is provided to the OnViewerEvent event, which is called whenever certain events occur in a standalone image viewer.

Other objects

The remaining objects are all obtained using methods or properties provided by the objects listed above. For example, a Lister object is obtained using the DOpus.listers collection property, and a Vector object is obtained using the DOpusFactory.Vector method.

• Alias: This object represents a folder alias, and is retrieved using the Aliases object.

• Aliases: This object is a collection of all defined folder aliases. It is retrieved using the DOpus.aliases collection property.

• Args: This object represents the arguments supplied on the command line for script-defined internal commands. It is retrieved from the ScriptCommandData.Func.args property.

• AudioMeta: This object provides metadata properties relating to audio files. It is obtained from the Metadata object.

• AudioCoverArt: This object provides access to an audio file's embedded cover art. It is obtained from the AudioMeta.coverart property.

• Blob: This object provides a simple interface for dealing with binary data. It is obtained from the DOpusFactory.Blob method and also returned by the AudioCoverArt.data property.

• BusyIndicator: A BusyIndicator object lets you control the breadcrumbs bar busy indicator from your script.

• Column: This object represents a column that has been added to the display in a tab. A collection of columns can be obtained from the Format object.

• Command: This object is used to run Opus commands. It is obtained from the ScriptCommandData.func or ClickData.func properties, and can also be created by the DOpusFactory.Command method.

• Control: The Control object represents a control on a script dialog; it lets you read and modify a control's value (and contents).

• CustomFieldData: The CustomFieldData object is provided to a rename script via the GetNewNameData.custom property. It provides access to the value of any custom fields that your script added to the Rename dialog.

• Date: This object is provided to make it easier to deal with variables representing dates. It is obtained from the DOpusFactory.Date method as well as various properties in other objects.

• Dialog: This object is used to display dialogs or popup menus. It is obtained from the Func.Dlg, Command.Dlg or DOpus.Dlg methods.

• DialogListColumn: The DialogListColumn object represents a column in a Details mode list view control in a script dialog. It's obtained by enumerating the DialogListColumns object.~control

• DialogListColumns: The DialogListColumns object lets you query or modify the columns in a Details mode list view control in a script dialog. Use the Control.columns property to obtain a DialogListColumns object.

• DialogListGroup: The DialogListGroup object represents a group in a list view control in a script dialog. It's returned by the Control.GetGroupById method.

• DialogListItem: The DialogListItem object represents an item in a combo box or list box control in a script dialog. It's returned by the Control.GetItemAt and Control.GetItemByName methods.

• DialogOption: This object is used in conjunction with the Dialog object. It lets you specify a checkbox option that is added to the dialog.

• Dock: This object represents a floating toolbar. The Toolbar object provides a collection that represents all instances of that toolbar that are currently floating.

• DocMeta: This object provides metadata properties relating to document files. It is obtained from the Metadata object.

• DOpusFactory: This object is a helper object that you can use to create various other objects like Map and Vector. It is obtained from the DOpus.Create method.

• DPI: The DPI object is a helper object that provides a number of methods and properties relating to the system DPI setting. It's returned via the DOpus.DPI property.

• Drive: The Drive object provides information about a drive (hard drive, CD ROM, etc) on your system. A Vector of drives on your system can be obtained from the FSUtil.Drives method.

• ExeMeta: This object provides metadata properties relating to executable (program) files. It is obtained from the Metadata object.

• Favorite: The Favorite object represents a favorite folder. It is retrieved by enumerating or indexing the Favoritesobject.

• Favorites: The Favorites object holds a collection of all the defined favorite folders. It is retrieved from the DOpus.favorites method.

• File: This object lets you read or write binary data from or to a file. It is obtained from the FSUtil.OpenFile and Item.Open methods.

• FileAttr: This object represents file attributes (like read only, archived, etc). It used by the Item and Format objects, and can be created by the FSUtil.NewFileAttr method.

• FileGroup: This object exposes information about a file group (when a Tab is set to group by a particular column). It is used by the Item and Tab objects.

• FileSize: This object is used to represent a size in bytes (mainly because ActiveX scripting doesn't have proper support for 64 bit integers). It is used by the Item and TabStats objects.

• FiletypeGroup: This object represents a file type group (as configured in the File Type Groups section of the file type editor).

• FiletypeGroups: This object represents a collection of one or more file type groups.

• Filter: Lets you create a complex filter that can be used with commands like Copy when run from a script.

• FilterParseError: Used to access information about a parsing error when working with Filter objects.

• FolderEnum: This object lets a script enumerate the contents of a folder. It is obtained using the FSUtil.ReadDir method.

• FontMeta: This object provides metadata properties relating to font files. It is obtained from the Metadata object.

• Format: This object provides information about the display format in a tab. It is obtained from the Tab.format property.

• FSUtil: This object provides various utility methods relating to file system activity. It is obtained from the DOpus.FSUtil property.

• Func: This object is passed to a script function (via ClickData.func) or script-defined internal command (via ScriptCommandData.func). It provides information relating to the function invocation (source and destination tabs, arguments, etc).

• GlobalFilters: This object lets you access information about the global filter settings (configured on the Filters page in Preferences).

• Image: This object represents an image file or icon loaded from disk that can be displayed in a script dialog.

• ImageMeta: This object provides metadata properties relating to image files. It is obtained from the Metadata object.

• IncludeFileInitData: If an include file script implements the optional oninitincludefile method, it receives this object to let it provide information about the include file.

• Item: This object represents a file or a folder. It can be returned from various methods of the Tab object, when enumerating a folder using the FSUtil.ReadDir method, and is used to provide files for a command to act on using the Command object.

• Items: The Items object lets you enumerate a list of one or more Item objects.

• Lister: This object represents a Lister window.

• Listers: The **Listers**object is a collection of all currently open Lister windows (each one represented by a **Lister**object). It can be obtained from the DOpus.listers property.

• Map: This object is similar to an array or vector (e.g. Vector) in that it can store one or more objects, but has the advantage of using a dictionary system to locate objects rather than numeric indexes. It is obtained from the DOpusFactory.Map method.

• Metadata: This object represents a file or folder's metadata. It can be obtained from the Item.metadata property, as well as the FSUtil.GetMetadata method.

• 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.

• OtherMeta: This object provides general metadata properties relating to files and folders. It is obtained from the Metadata object.

• PairedFolder: This object represents a paired folder retrieved from the FSUtil.GetFolderPair method.

• Path: This object represents a file system path. It contains several methods to manipulate the path. Path objects are returned by several properties and can be created by the FSUtil.NewPath method.

• Progress: This object represents a progress dialog, that lets you visually indicate to the user the progress of your script function. It is obtained from the Command.progress property.

• QuickFilter: This object provides information about the state of the quick filter in a tab. It's obtained from the Tab.quickfilter property.

• Rect: The Rect object represents a rectangle.

• Results: This object represents the results of a command (the error code in the case of failure, plus any new tabs or Listers created by the command). It is obtained from the Command.results property.

• ScriptColorPair: This object bundles a pair of colors (text / background) together.

• ScriptColumn: This object represents a script-defined column. It is obtained from the ScriptInitData.AddColumn method, while processing the OnInit event.

• ScriptCommand: This object represents a script-defined internal command. It is obtained from the ScriptInitData.AddCommand method, while processing the OnInit event.

• ScriptFAYTCommand: This object is provided as a property of the ScriptCommand object for script add-ins that extend the FAYT field.

• ScriptConfig: This object represents script-defined configuration data that Opus stores for each script. The configuration items are initialised via the ScriptInitData.config property, and are then available to the script via the Script.config property.

• ScriptStrings: The ScriptStrings object is returned by the DOpus.strings property. It lets you access any strings defined via string resources.

• 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. The FSUtil.GetShellPropertyList method lets you retrieve a list of available shell properties.

• SmartFavorite: A SmartFavorite object represents an entry for a folder in the SmartFavorites table. It is retrieved by enumerating or indexing the SmartFavorites object.

• SmartFavorites: The SmartFavorites object lets you query the contents of the SmartFavorites table. It is retrieved from the DOpus.smartfavorites property.

• 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.

• StringTools: This object provides utility functions for string encoding and decoding. It is obtained from the DOpusFactory.StringTools method.

• StringSet: This object is similar to an array or vector (e.g. Vector) of strings, but has the advantage of using a dictionary system to locate strings rather than numeric indexes. It is obtained from the DOpusFactory.StringSet and StringSetI methods.

• SysInfo: The SysInfo object is created by the DOpusFactory.SysInfo method. It lets scripts access miscellaneous system information that may not be otherwise easy to obtain from a script.

• Tab: This object represents a folder tab in a Lister. A Lister's tabs are available via various Lister object properties (e.g. Lister.activetab) and also used to specify the source/destination of a command (e.g. Command.sourcetab).

• TabGroup: This object represents a folder tab group. It's accessed by enumerating the **TabGroups**object.

• TabGroups: This object provides access to and lets you modify the configured list of folder tab groups. It's obtained from the DOpus.tabgroups property.

• TabGroupTabEntry: This object represents a folder tab in a tab group.

• TabGroupTabList: This object represents a list of folder tabs in a tab group.

• TabStats: This object provides various statistics about a folder tab (the number of selected files, total number of items, etc). It is obtained from the Tab.stats and Tab.selstats properties.

• Toolbar: This object represents a toolbar. It is obtained with the DOpus.toolbars and Lister.toolbars properties.

• Toolbars: The Toolbars object lets you enumerate all the defined toolbars in your Directory Opus configuration (whether currently turned on or not).

• UnorderedSet: Similar to a **StringSet**but can store elements of any type rather than just strings.

• Var: This object represents a variable. Toolbar buttons, hotkeys and scripts can read and store variables, and variables can be saved from one session of Opus to another. The Var object is obtained from the Vars collection.

• Vars: This object represents a collection of variables. Depending on the variables' scope it can be obtained from the DOpus.vars, Lister.vars, Tab.vars, Command.vars or Script.vars properties.

• Vector: This object is similar to an array - it can store an unlimited number of elements of any type. Several properties and methods in the Opus scripting interface use Vectors, and you can use them interchangeably with arrays in most cases. The Vector is provided because some scripting languages only offer incomplete or incompatible arrays - using Vectors means the object can be used consistently across any ActiveX scripting language. A Vector is created by the DOpusFactory.Vector method.

• Version: This object represents information about the current Opus version. It is obtained from the DOpus.Version property.

• VideoMeta: This object provides metadata properties relating to movie files. It is obtained from the Metadata object.

• Viewer: The Viewer object represents a standalone image viewer.

• Viewers: The Viewers object is a collection of all currently open standalone image viewers. It can be obtained via the DOpus.viewers property

• Wild: This object allows a script to access the in-built pattern matching functions in Opus. It is obtained from the FSUtil.NewWild method.

• WinVer: This object represents information about the current Windows version. It is obtained from the Version.winver property.