Command modifier reference

The following is a list of the various command modifiers supported in toolbar buttons and hotkeys.

 

Modifier

Description

@admin

The function requires administrator permissions under Vista and above. This modifier will result in a UAC prompt appearing (unless the Lister is already in administrator mode), and any external programs run by this function will be elevated.

If used by itself, this modifier affects the entire function. It can also be used to elevate a specific command rather than the entire button.

 

@admin                           - elevate the entire function
@admin:notepad.exe {f}  - only elevates Notepad

 

@async

The command following this modifier will be run asynchronously - Opus will not wait for it to exit before running the next command in the function (or before running this command again for the next selected file).

The default behaviour is for a function that consists of a single command to run that command asynchronously for each selected file; a function that consists of multiple commands will run each command synchronously. The default behaviour can be changed with the function_default_async option on the Miscellaneous / Advanced page in Preferences, or it can be overridden on a per-command basis with this modifier.

 

@async:notepad.exe {f}   - runs Notepad asynchronously

 

@codepage

Changes the code page of an MS-DOS batch command. If not specified the default code page is 1252 (Windows-1252).

 

@codepage:1258             - sets the code page to Vietnamese

 

@confirm

Displays a confirmation dialog. If the user clicks the cancel button, the function is aborted at this point.

The template for this modifier is: @confirm:<message>|<positive text>|<negative text>

<message> is the text shown in the dialog, <positive text> is the text shown on the "OK" button, and <negative text> is the text shown on the "Cancel" button. These three strings are all optional - if not provided, default strings will be used. If you provide <positive text> but not <negative text> then the dialog will have an "OK" button but no "Cancel" button at all.

You can include line-breaks in the message text using the special code \n (and if you need to include a literal \n sequence in the text you must escape the \ character, as in \\n).

 

@confirm:Really copy files?                   - uses default text for the OK and Cancel buttons

@confirm:Really proceed?|Oui!|Non!     - specifies custom text for the two buttons

@confirm:All finished|Acknowledged     - custom text for the OK button; no Cancel button at all

 

@dirsonly

The function will operate only on selected folders, ignoring any files.

 

@dirsonly                        - operate only on directories

 

@disablenosel

The command will be disabled when no files or folders are selected. This is done automatically for certain standard commands and the modifier lets you make your own commands behave in a similar way.

 

@disablenosel                   - disable button when nothing is selected

@disablenosel:files           - disable button when no files are selected

@disablenosel:dirs            - disable button when no folders are selected

 

@externalonly

Ignores any Opus internal commands specified in the function, and treats all commands as external. This lets you configure an MS-DOS batch function using commands like copy which would normally be overridden by the internal command set.

 

@externalonly                  - external commands only

 

@filesfromdroponly

Accepts files and folders only via drag-and-drop. A button with this modifier will ignore any selected files or folders in the Lister - only files dropped onto the button will be used by a command within it.

 

@filesfromdroponly          - accept files only via drag-and-drop

 

@filesonly

The function will operate only on selected files, ignoring any folders.

 

@filesonly                         - operate only on files

 

@firstfileonly

The function will operate on only the first selected file, irrespective of how many items are selected or dropped onto the button.

 

@firstfileonly                    - operate on only the first selected file

 

@functype

This directive is only used within an embedded function. It lets you specify the type of the embedded function (if not specified, the embedded function is assumed to be a standard function - Opus or external command). For example, the following command would open a new Lister with an embedded script function that runs in the context of the new Lister:


Go NEW
[
@functype:script
@script:vbscript
' script function here
]


 

@functype:script               - the embedded function is a script
@functype:msdos              - the embedded function is an MS-DOS batch function

 

@icon
@icon!
@iconp

The @icon directive lets you create buttons that dynamically change their icon based on the test of a Set-command clause (similar to @ifset). The default View Mode Cycle button uses this to change its icon to reflect the current view mode.

 

Set VIEW=Cycle
@icon:largeicons,VIEW=LargeIcons
@icon:smallicons,VIEW=SmallIcons
@icon:listmode,VIEW=List
@icon:powermode,VIEW=Power
@icon:thumbnails,VIEW=Thumbnails
@icon:tile,VIEW=Tiles
@icon:detailsmode,VIEW=Details


Each @icon directive in the button specifies the icon to use, and the Set directive to test for. For example, if VIEW=LargeIcons tests as true, the icon called largeicons will be displayed on the button. If none of the @icon tests match then the icon set in the button itself will be used as the default image.

In the special case of a three-button button, @iconp: and @icon!: directives can also be used in any of the child buttons to change the icon of the parent. @iconp: used in one of the child buttons will set the icon of the parent (but do nothing to the child button). icon!: used in one of the child buttons will set the icon of the parent as well as of that child button.

 

In the command editor, you can Ctrl+click the @icon: string to select the icon directly.
 

@ifexists

Allows simple conditional behaviour based on whether the specified drive or path exists.
 

@ifexists:<drive or path>     - test if drive or path exists
@ifexists:else                      - an "else" clause that is executed if the path doesn't exist
@ifexists:common             - common instructions that are always executed
 

@ifpath
@ifpathr

Allows simple conditional behaviour based on the current source path. You can provide either an absolute path to test against, or a wildcard pattern (use @ifpath for standard wildcards, and @ifpathr for regular expressions).

For example, you could use this to open different programs when double-clicking on an image file, depending on where the file is stored. If the following command was added to the Left double-click event for the Imagesfile type group, pictures located on the network will be opened in the Opus viewer when they are double-clicked, whereas files located on a local drive would open in Photoshop.

@ifpath:\\*                                           // if path begins with \\
Show                                                       //   invoke the Opus viewer
@ifpath:else                                            // otherwise
Photoshop.exe {f}                                  //   open in Photoshop (the full path would
                                                                      generally need to be specified - this is just
                                                                      an example)

 The possible forms of this modifier are:

 

@ifpath:<path or wildcard>     - test for a path (using standard pattern matching)
@ifpathr:<regular expression> - test for a path (using regular expressions)
@ifpath:else                        - an "else" clause that is executed if nothing else matches
@ifpath:common                 - common instructions that are always executed

 

@ifset

Allows simple conditional behaviour based on tests for various Set command conditions. You can also test if a variable has been set by the @set directive. Additionally, a button on the File Display toolbar can test if it's tied to the left or right file display.

For example, you could configure a button to read a folder into the right file display in a dual-display Lister, or into the current file display otherwise.

@ifset:DUAL=on                                //  if DUAL mode is on
Set FOCUS=right
                               //     give focus to the right file display
Go /mypictures OPENINRIGHT
         //     read directory into that file display
@ifset:else
                                        //  otherwise
Go /mypictures
                                //      read directory into current file display
@ifset:common
                                //  common commands (always executed)
Set VIEW=thumbnails
                     //  set view to thumbnails mode

 

 The possible forms of this modifier are:

 

@ifset:<Set argument> - test for a specific Set command condition
@ifset:$foo                  - test if a variable called "foo" has been set
@ifset:$glob:bar          - test if a global variable called "bar" has been set
@ifset:SIDE=left         - test if the toolbar is tied to the left file display
@ifset:SIDE=right      - test if the toolbar is tied to the right file display
@ifset:else                  - an "else" clause that is executed if nothing else matches
@ifset:common           - common instructions that are always executed

 

@keydown

Allows simple conditional behaviour based on whether various qualifier keys are held down when the function is run.

The qualifiers to test for are specified using one or more keywords (shift, ctrl and alt) which represent the Shift, Control and Alt keys. For example, you could configure a button to select all files, then copy, move or create shortcuts to them, depending on which keys were held down.

Select ALL                         // select all items (always executed)
@keydown:none               // if no qualifiers are down
Copy                                 //    copy files to destination
@keydown:shift               // else if shift key is down
Copy MOVE                      //    move files to destination
@keydown:ctrlshift         // else if control and shift keys are down
Copy MAKELINK              //    make shortcuts in destination

 

The possible forms of this modifier are:

@keydown:<qualifiers>   - test for a qualifier key or combination of keys
@keydown:any               - tests if any qualifier keys are held down
@keydown:none
            - instructions that are executed if no qualifiers are held down
@keydown:common       - common instructions that are always executed

 

@leavedoswindowopen

The console window opened for an MS-DOS batch function will remain open when the function has completed. Without this modifier the window will close when the function finishes, which may make it hard to read the output of any command-line programs.

Leaving the DOS window opens relies on passing a particular argument (/K) to the system command interpreter, cmd.exe. If you have modified the default command processor on your system by setting the %ComSpec% environment variable, Opus will not pass /K as there is no way for it to know if this argument would be understood by the new command processor. Instead, you can set the %ComSpecLeaveOpenArg% environment variable, and this will be used instead of %ComSpec% whenever @leavedoswindowopen is used.

 

@leavedoswindowopen        - leave DOS prompt open when function finishes

 

@nocall

An MS-DOS batch function function that invokes an external .bat file will run it directly, rather than using call semantics. This means that control will not return to the parent function once the external .bat file has finished. The default behaviour is to use the DOS call instruction which returns control to the parent function at the end.

 

@nocall:<batch file>            - invoke external batch file, do not return control to this function

 

@nodeselect

Files and folders will remain selected at the end of the function. This lets you override the Deselect files used in functions option on the File Operations / Options page in Preferences, on a per-function basis.

 

@nodeselect                     - do not deselect items used by this function

 

@noexpandenv

Prevent the expansion of any environment variables in the function. Normally environment variables like %USERPROFILE% are expanded during the function parsing phase - this modifier causes variable names to be left intact.

 

@noexpandenv                  - do not expand environment variables

 

@nofilenamequoting

Disables the automatic quoting that Opus performs when external codes like {filepath} are used to pass the name of a file that contains spaces. By default Opus will wrap names with embedded spaces in quotes, but occasionally you may want to disable this - some external programs may not need or understand quotes on their command line, and you may also want to provide explicit quotes in a function in case the automatic quoting gets confused by complicated command structures.

 

@nofilenamequoting          - do not automatically quote file names and paths

 

@nolocalizefiles

Prevents Opus from automatically downloading or extracting non-filesystem files when passing their paths to external programs. For example, you may want to use {filepath} to pass the ftp:// path of a file on a remote FTP server to an external program. By default Opus will download the file to a temporary file, and pass the name of the temporary file to the program - with this modifier, Opus will instead pass the original file path.

 

@nolocalizefiles                 - do not automatically localize (download) remote files

 

@norunbatch

When an MS-DOS batch function combines internal and external commands, the default behaviour is for Opus to split the function at every internal command, and execute all the external commands that came before it. For example, imagine the following (rather pointless) function:

echo one
Help ABOUT
echo two
@leavedoswindowopen

 

The default behaviour of this function would be to open a DOS window and print the string "one", then display the Opus About dialog, and then open another DOS window and print the string "two". If, however, the function were changed as follows:

@norunbatch
echo one
Help ABOUT
echo two
@leavedoswindowopen

 

The new behaviour would be to first display the About dialog, and then open a single DOS window and print both the strings "one" and "two". The @norunbatch modifier causes all Opus internal commands to be executed first, followed by all external commands.

 

@norunbatch                  - do not split batch functions because of internal commands

 

@resolvelinks

Shortcuts or links passed to commands in this function will be resolved to their targets. Without this modifier, a selected .lnk file would be passed as-is.

 

@resolvelinks                  - resolve shortcut targets when passing filenames to commands

 

@runbatch

Force the execution of an MS-DOS batch function at a certain point. The default behaviour is for such functions to be executed at the very end of the function - using this modifier you can force a break in the function at any line. For example:

echo one
@runbatch
echo two
@leavedoswindowopen

 

This will cause two separate DOS windows to open, one displaying the text "one" and the other displaying "two". Without the @runbatch directive, the two commands would have been executed in the one window.

 

@runbatch                     - force a DOS batch function to execute at a certain point

 

@runmode

Modifies the "run" state of external programs launched by the function - that is, how its main window should appear. This is equivalent to the Run drop-down on the simple command editor. Not all programs will support this setting, so you will need to use trial and error to some extent. You should only set the mode to hide if you are sure of what you are doing - it is most useful for hiding the otherwise brief flash of a DOS window when running a DOS program.

 

@runmode:min               - minimize the program's main window
@runmode:max              - maximize the program's main window
@runmode:hide              - hide the program's main window

 

@runonce

Forces the command following the modifier to only be run once per function, instead of once per file.

 

@runonce:<command>     - the specified command will only be run once

 

@script

Specifies the scripting language used for a script. This is used for both Rename Scripts (including embedded rename scripts) and for Script Functions. The @script modifier must be followed by a keyword that specifies the scripting language. For example,

Rename PATTERN * TO *
@script:vbscript
Function ....

 

Note that @script is not used for script add-ins, as in that case the file extension of the add-in itself specifies the language.

 

@script:<language>          - specifies scripting language

 

@set

Sets the value of a named variable that can be used by the remainder of the commands in the function. You can pass the value of a variable to internal and external commands using the {$} control code. Variables are most useful in the situation where the value is defined by a {dlgstring} code. For example,

@set dir={dlgstring|Enter new folder name to copy files to}
CreateFolder ".\{$dir}"
Copy TO ".\{$dir}"

 

Normally variables do not persist from one invocation of the function to another, and you can not refer to variables set in one function from another. However this can be accomplished by prefixing the variable name with a special scope marker that determines which scope the variable will live in.

 

src:<name>        - variable will be scoped to the source tab
dst:<name>        - variable will be scoped to the destination tab
lst:<name>         - variable will be scoped to the Lister
glob:<name>      - variable will be scoped globally

 

You can also mark variables to be saved on disk - their values will be remembered from one Opus session to the next. To accomplish this, simply add an exclamation mark (!) to the scope marker. For example, glob!:<name> refers to a variable with global scope that will be saved on disk.
 

@set <name>=<value>     - sets the named variable to the specified value

@set<name>                    - deletes the named variable
 

 

@sync

The command following this modifier will be run synchronously - Opus will wait for it to exit before running the next command in the function (or before running this command again for the next selected file).

The default behaviour is for a function that consists of a single command to run that command asynchronously for each selected file; a function that consists of multiple commands will run each command synchronously. The default behaviour can be changed with the function_default_async option on the Miscellaneous / Advanced page in Preferences, or it can be overridden on a per-command basis with this modifier.

 

@sync:notepad.exe {f}    - runs Notepad synchronously

 

@toggle

For buttons that act as toggles (e.g. Set VIEW=details), this modifier lets you change the highlight state of the button. Taking this command as an example, ordinarily the button would appear highlighted when the file display was in details mode, and unhighlighted when it was in any other mode. The @toggle modifier can change this:

 

@toggle:invert                - inverts the usual highlight state of the toolbar button
@toggle:disable              - prevents the button from ever appearing highlighted


This directive can also control whether a button appears highlighted based on the test of a Set-command clause (similar to @ifset). Normally buttons that run the Set command appear checked or unchecked based on the state of that Set command itself, but using @toggle you can run one Set command and test for another. You can also test for multiple Set clauses at once. For example:


Set VIEW=Details
Set COLUMNSADD=thumbnail(0,96)
@toggle:if&COLUMNSTOGGLE=thumbnail


Normally this button would appear checked whenever the view mode was set to Details. However using @toggle we have added an additional test - the Thumbnail column must also be present for the button to be checked (the ampersand specifies that the test is in addition to the one provided by the command - if you leave out the ampersand then only the clauses in the @toggle directive will be tested).

You can test for multiple Set clauses by separating them with semi-colons. For example, you could leave out the ampersand and still test both the view mode and the column using the following directive:


@toggle:if VIEW=Details;COLUMNSTOGGLE=thumbnail


You can also negate the result of a test with the exclamation mark in front of the Set clause. For example, to make the button appear checked in any mode other than Details:


@toggle:if !VIEW=Details


The @toggle directive can also test for the existence of a variable (one set via the @set directive). For this to work, the directive must be the very first line of the button, and the variable you are testing must have tab, Lister or global scope. You can use this to create your own custom toggle buttons that keep track of their state using scoped variables. For example:


@toggle:if $glob:TestVar
@ifset:$glob:TestVar
@set glob:TestVar
@ifset:else
@set glob:TestVar=on


This button tests for the existence of a global variable called TestVar. If the variable exists, the button will appear highlighted. Clicking the button evaluates the @ifset: directives which simply act reverse the state of the variable - if the variable is set, it's deleted, otherwise it's set. The end result is a button that performs no function except to toggle its state every time it is clicked.


A button that begins with @toggle:if in this way will automatically update its appearance (to reflect a change in the state of the variable) whenever @set is used within it. If you use @set in a separate button or hotkey to change the variable, you need to force an update of the toggle button's appearance using the special command @toggle:update.

 

@ifset:$glob:TestVar
@set glob:TestVar
@ifset:else
@set glob:TestVar=on
@ifset:common
@toggle:update


@useactivelister

The function will operate on the active Lister rather than the current source Lister. Normally these will be the same thing, but this could be useful for a hotkey that you want to have operate on whatever Lister window is currently active, without having to make sure that Lister is set to source first.

 

@useactivelister             - use active Lister instead of source lister