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.
|
|
@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).
|
|
@codepage |
Changes the code page of an MS-DOS batch command. If not specified the default code page is 1252 (Windows-1252).
|
|
@confirm |
Displays a confirmation dialog. If the user clicks the cancel button,
the function is aborted at this point.
|
|
@dirsonly |
The function will operate only on selected folders, ignoring any files.
|
|
@disableif |
The button will be disabled if a command clause test is false. This is similar to the conditional testing offered by the @if modifier described below.
|
|
@disableifpath |
The button will be disabled if the current source path doesn't match the specified pattern. You can provide either an absolute path to test against, or a wildcard pattern (use @disableifpath for standard wildcards, and @disableifpathr for regular expressions).
Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):
|
|
@disablenosel |
The command will be disabled when no files or folders are selected, or optionally when no files of a certain type are selected. This is done automatically for certain standard commands and the modifier lets you make your own commands behave in a similar way. This is similar to @hidenosel.
For lister toolbars, you can use the minfiles, maxfiles and numfiles keywords to specify a minimum, maximum, or exact number of files which must be selected for the button to be enabled. Similarly, mindirs, maxdirs and numdirs can limit the number of selected folders.
Using the type keyword you can configure a button to be disabled unless at least one file is selected whose name matches the supplied wildcard pattern. (It is not required that all selected files match the pattern; only one.) You can also combine this with dirs for a button that works if a folder is selected or if a file of a certain type is selected. If you use type, it must be the last thing on the line, since everything after the = will be considered part of the pattern (allowing the pattern to include things which would otherwise be confused with other keywords and parameters).
You can also use a ! character to negate the test. It must be the first thing after the :. For example,
|
|
@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.
|
|
@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.
|
|
@filesonly |
The function will operate only on selected files, ignoring any folders.
|
|
@firstfileonly |
The function will operate on only the first selected file, irrespective of how many items are selected or dropped onto the button.
|
|
@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:
|
|
@hideif |
The button will be hidden if a command clause test is false. This is similar to the conditional testing offered by the @if modifier described below.
|
|
@hideifpath |
The button will be hidden if the current source path doesn't match the specified pattern. You can provide either an absolute path to test against, or a wildcard pattern (use @hideifpath for standard wildcards, and @hideifpathr for regular expressions).
Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):
|
|
@hidenosel |
The button will be hidden when no files or folders are selected, or optionally when no files of a certain type are selected. This is similar to @disablenosel.
For lister toolbars, you can use the minfiles, maxfiles and numfiles keywords to specify a minimum, maximum, or exact number of files which must be selected for the button to be visible. Similarly, mindirs, maxdirs and numdirs can limit the number of selected folders.
Using the type keyword you can configure a button to be hidden unless at least one file is selected whose name matches the supplied wildcard pattern. (It is not required that all selected files to match the pattern; only one.) You can also combine this with dirs for a button that is visible if a folder is selected or if a file of a certain type is selected. If you use type, it must be the last thing on the line, since everything after the = will be considered part of the pattern (allowing the pattern to include things which would otherwise be confused with other keywords and parameters).
You can also use a ! character to negate the test. It must be the first thing after the :. For example,
|
|
@icon |
The @icon directive lets you create buttons that
dynamically change their icon based on the test of a command clause,
typically via the Set command (similar to
@if and @ifset). The default View
Mode Cycle button uses this to change its icon to reflect
the current view mode.
If you are testing based on the Set command, the command name is technically optional and can be ommitted. For example, VIEW=LargeIcons on its own is the same as Set VIEW=LargeIcons. This ability is there to avoid breaking old buttons and, with new buttons, we recommend you include the command name in all cases to avoid problems in the future.
In the command editor, you can Ctrl+click the @icon: string to select the icon directly.
@icon can use the RECYCLEBINEMPTY argument to test if the recycle bin is empty or not. For example,
Toolbar buttons that use @icon with RECYCLEBINEMPTY will
refresh themselves automatically when the recycle bin state changes (this
lets you have a button whose icon reflects the state of the recycle
bin). |
|
@if @ifset |
Allows simple conditional behaviour based on tests for various commands.
@if is a general test which works with any command,
and @ifset is a specific test which only works with
the Set
command conditions. For example, @ifset:DUAL=on is
equivalent to @if:Set DUAL=on. The test @if actually performs is to evaluate whether a toolbar button with the specified command would appear highlighted or not. For example, if the Lister is in dual-display mode, a button with Set DUAL=toggle as the command would appear highlighted. Therefore, the @if:Set DUAL=toggle modifier would evaluate to true.
You can also evaluate whether a toolbar button would be enabled or not, using @if:enabled. For example, Navigation Lock is only enabled when a Lister is in dual-display mode. Therefore, the modifier @if:enabled Set NAVLOCK=Toggle would evaluate to true when the Lister was in dual-display mode.
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.
As another example, @ifset can use the RECYCLEBINEMPTY argument to test if the recycle bin is empty or not:
Conditional testing can also be used on buttons in the standalone viewer. The following function will toggle the display between 100% zoom and Grow To Page modes, by using @if to test the current zoom mode:
The possible forms of this modifier are:
You can negate the condition by prefixing it with a ! character. For example, all four of these are equivalent:
|
|
@ifexists |
Allows simple conditional behaviour based on whether the specified
drive or path exists.
|
|
@ifpath |
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 Images
file 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.
The possible forms of this modifier are:
You can negate the condition by prefixing it with a ! character. Examples:
|
|
@ifrunning |
Allows simple conditional behaviour based on whether a specified
process is currently running. You can use wildcards or (by prefixing
the pattern with regex:) regular
expressions.
|
|
@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.
The possible forms of this modifier are:
|
|
@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.
|
|
@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.
|
|
@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.
|
|
@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.
|
|
@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.
|
|
@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.
|
|
@noprogress |
Disables the automatic display of a progress indicator for this
function. You should use this with care as without a progress indicator
there is no way to abort the command or monitor its progress. Normally
only script functions should use this when they want to provide and
control their own progress indicator.
|
|
@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:
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:
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.
|
|
@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.
|
|
@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:
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.
|
|
@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.
|
|
@runonce |
Forces the command following the modifier to only be run once per function, instead of once per file.
|
|
@script |
Specifies the scripting language used for a script. This is mainly used for embedded rename scripts, because otherwise the script language is selected via a drop-down at the top of the script editor. The @script modifier must be followed by a keyword that specifies the scripting language (or in the case of script add-ins, the file extension of the add-in itself specifies the language).
For example,
|
|
@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,
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.
The src: and tab: scopes usually point to the same folder tab within commands. (The tab: scope was introduced so that status bar codes which use variables can refer to the side that the status bar is on, without worrying if it is the source, destination, left or right. It is supported in commands for consistency.)
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.
If you have buttons or status bar codes which react to variable changes, you may need to run the special @toggle:update command to make them update their appearances after making changes to variables. See the @toggle documentation, below.
|
|
@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).
|
|
@toggle |
For buttons that indicate or change state (e.g. Set VIEW=details), this modifier lets you change when the button appears highlighted. Depending on where the button is displayed, the highlight may appear as a checkmark (e.g. in a text-only menu), or as the icon or label background being drawn in a different color or style (similar to when the button is pushed). Taking the Set VIEW=details command as an example, ordinarily the button would appear highlighted when the file display was in details mode, and not highlighted when it was in any other mode. The @toggle modifier can change this:
The @toggle modifier can also control when a button appears highlighted by testing a command, similar to the way @if and @ifset test commands to decide what to run. You can use this to highlight a button based on a command which is different to, or in addition to, the commands which the button actually runs. For example, this button with no @toggle line will switch you to Details mode when clicked, and will appear highlighted when you are in Details mode as well:
When @toggle is not given, the highlighting (if any) is based on the first command in the button. Using @toggle you can do things like run one Set command while testing for another. As a simple, somewhat contrived example, the button below switches to Details mode when clicked but appears highlighted when in Power mode:
You can make the @toggle test in addition to the first
command, rather than instead of it, by putting an "&" character
after the "if":
Without the @toggle line, the button above would be
highlighted when the view mode was Details (due to the command)
and the highlight would not be affected by the Thumbnail column
(highlighting does not consider the second command). With the
@toggle line added, the button will only be highlighted
if the view mode is set to Details and the Thumbnail
column is present.
You can omit the "Set" command name from the @toggle line; it will assume you mean the Set command if no name is specified. However, this allowance is to avoid breaking old buttons and we recommend you always specify the command when making new ones.
You can test for multiple commands at once by separating them with semi-colons. For example, you could leave out the ampersand and still test for both Details mode and the Thumbnail column using the following directive (and this will work regardless of any other commands in the button, or even as the only line in the button):
@toggle:if !Set 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:
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 and will reverse the state of the variable: if the variable is set, it will be deleted; otherwise, it will be set. The end result is a button that performs no function except to toggle a variable and its visible state each time it is clicked. (This can be useful if the variable controls other things, such as the behaviors of other commands or scripts, or the visibility of status bar elements.)
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.
For example, if you have one button which highlights based on a variable but does not change that variable:
And if you have another button which changes that variable but does not highlight based on it, then you will need to add the @toggle:update line to ensure the first button's highlight is updated when you click the second button:
The @toggle:update command will also force all status bars to refresh, in case they are using variables to display or hide information.
|
|
@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.
|