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 (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)
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.
- FileOperationCompleteData:
This object is provided to the OnFileOperationComplete
method, which lets you receive notification when certain file
operations complete.
- 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.
- GetHelpContentData: This
object is provided to the OnGetHelpContent event, which
lets a script add its own content to the Opus F1 help.
- 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.
- 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.
- 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.
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.
- 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 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.
- 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.
- 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 Folders / Global
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.