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.

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
• 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 support a 64 bit integer type).
• 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 tabs.
• 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.
• Variant - a variable of any type (this is used with a few objects - for example, a Var object can store a variant)

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.

There are also 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 Toolbars / Scripts Preferences page.
• 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.
• GetNewNameData: This object is provided to the OnGetNewName method, which is one of the supported methods a rename script can provide.
• 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.
• 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.

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.
• 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.
• 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.
• 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.
• ExeMeta: This object provides metadata properties relating to executable (program) files. It is obtained from the Metadata object.
• 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.
• 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).
• 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).
• ImageMeta: This object provides metadata properties relating to image files. It is obtained from the Metadata object.
• 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.
• Lister: This object represents a Lister window. A collection of currently open Listers is 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.
• OtherMeta: This object provides general metadata properties relating to files and folders. It is obtained from the Metadata object.
• 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.
• 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.
• 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.
• 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.
• 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).
• 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.
• 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.
• 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.