Directory Opus Manual

User Tools

Site Tools

You are here: Introduction » Reference » Scripting Reference » Scripting Objects

Sidebar

reference:scripting_reference:scripting_objects

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.

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.
  • EverythingInterface: Provides an interface between Opus and Everything (by voidtools).
  • EverythingResult: Represents a search result returned from an Everything query.
  • 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 Favorites object.
  • 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.
  • FileChange: This object provides information about a file change that occurred during a command run from a script. It is obtained from the Results object.
  • 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).
  • HTTPRequest: This object lets you easily send an asynchronous HTTP request and receive the results. You can create this object using the Dialog.NewHTTPReq method.
  • 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 Listerobject). 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.
  • OrderedMap: This is the same as a Map except that the order of items added to the map is preserved rather than being sorted alphabetically. It is obtained from the DOpusFactory.OrderedMap method.
  • 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.
  • Signature: The Signature object is returned by the FSUtil.GetSignature method to provide information about the signature used to digitally sign an executable file.
  • 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.