Command modifier reference

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

Modifier
Description

@admin

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.

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).

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 (and if you need to include a literal sequence in the text you must escape the \ character, as in ).

This uses the evaluator to return a simple string; functionally this is no different to simply putting the Go DRIVEBUTTONS command on a toolbar button.

As a more complex example, the default Favorites Bar toolbar uses @ctx to build the displayed favorites list, by using the Evaluator to build a command line using the current localised name of the favorites bar branch:

This uses the evaluator LanguageStr() function to retrieve the translated name of a known string, and constructs a command line using the Favorites command to display that branch of the favorites tree.

@admin

elevate the entire function

@admin:notepad.exe {f}

only elevates Notepad

@admin:no

disable UAC prompts for any subsequent commands in this function

@admin:yes

re-enable UAC prompts for any subsequent commands

@async

@async:notepad.exe {f}

runs Notepad asynchronously

@codepage

@codepage:1258

sets the code page to Vietnamese

@confirm

@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

@ctx

@dirsonly

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

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 @disableifpathr

Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):

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,

The button will be enabled if a command clause test is true. This is similar to the conditional testing offered by the @if modifier described below.

@enableifpath @enableifpathr

Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):

@eval @evalalways

  • Code after @eval: is only run when dynamically updating the button's label, visibility and enabled/disabled state. It's not run when the button is clicked.

  • Code after @evalalways: also runs when the button is clicked. This lets you set up variables which are used both when executing commands and, e.g. also when updating their labels.

In this example, the type value is initialised once in the top line, and then referred to multiple times in the subsequent lines.

@dirsonly

operate only on directories

@disableif

@disableif:Set DUAL=toggle

button will be disabled if the Lister is in dual-display mode

@disableif:!Set DUAL=toggle

button will be disabled if the Lister is NOT in dual-display mode

@disableifpathr:^C:\

disable command if source path is on the C: drive

@disableifpath:!*\Work\*

disable unless source path is underneath a folder called Work

@disableifpath:!/desktop

disable unless in the Desktop folder

@disableifpath:!%SystemRoot%\System32

disable unless in C:\Windows\System32 (on a typical system)

@disableifpath:{apppath|dopus.exe}

disable if in the folder where Opus is installed

@disableifpath:shell

disable if in a hosted virtual folder

@disablenosel

@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

@disablenosel:numfiles=2

disable button unless exactly 2 files are selected

@disablenosel:maxfiles=5

disable button unless 5 files or fewer are selected

@disablenosel:mindirs=3,maxdirs=5

disable button unless 3, 4 or 5 folders are selected

@disablenosel:type=*.jpg

disable button when no files ending with ".jpg" are selected

@disablenosel:type=old

disable button when no files beginning with "old" are selected

@disablenosel:dirs,type=*.png

disable unless any folders, or any files ending with ".png", are selected

@disablenosel:!type=*.jpg

disable button if files ending with ".jpg" are selected

@enableif

@enableif:Set DUAL=toggle

button will be enabled if the Lister is in dual-display mode

@enableif:!Set DUAL=toggle

button will be enabled if the Lister is NOT in dual-display mode

@enableifpathr:^C:\

enable command if source path is on the C: drive

@enableifpath:!*\Work\*

enable unless source path is underneath a folder called Work

@enableifpath:!/desktop

enable unless in the Desktop folder

@enableifpath:!%SystemRoot%\System32

enable unless in C:\Windows\System32 (on a typical system)

@enableifpath:{apppath|dopus.exe}

enable if in the folder where Opus is installed

@enableifpath:shell

enable if in a hosted virtual folder

@externalonly

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.

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

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

The @hideblock modifier lets you use the various other modifiers to hide or show multiple buttons at once, without having to repeat the tests in each button.

Use @hideblock:begin on a button to begin the block, along with whichever other modifiers are appropriate. The buttons within the block will be hidden or shown depending on the state of the first button. For example,

This button begins a hide/show block based on the current view mode. If the current view is in thumbnails mode, the buttons will be visible - otherwise they'll be hidden.

Use @hideblock:end on another button to end the block. All buttons between the beginning and end will be hidden or shown as one. Note that the beginning and ending buttons are never shown outside of Customize mode.

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 @hideifpathr

Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):

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 @icon! @iconp

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.

Each @icon directive in the button specifies the icon to use, and the command directive to test for. For example, if Set 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.

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).

@externalonly

external commands only

@filesfromdroponly

@filesfromdroponly

accept files only via drag-and-drop

@filesonly

@filesonly

operate only on files

@firstfileonly

@firstfileonly

operate on only the first selected file

@functype

@functype:script

the embedded function is a script

@functype:msdos

the embedded function is an MS-DOS batch function

@hideblock

@hideblock:begin

begin a hide block

@hideblock:end

end a hide block

@hideif

@hideif:Set DUAL=toggle

button will be hidden if the Lister is in dual-display mode

@hideif:!Set DUAL=toggle

button will be hidden if the Lister is NOT in dual-display mode

@hideifpathr:^C:\

hide command if source path is on the C: drive

@hideifpath:!*\Work\*

hide unless source path is underneath a folder called Work

@hideifpath:!/desktop

hide unless in the Desktop folder

@hideifpath:!%SystemRoot%\System32

hide unless in C:\Windows\System32 (on a typical system)

@hideifpath:{apppath|dopus.exe}

hide if in the folder where Opus is installed

@hidenosel

@hidenosel

hide button when nothing is selected

@hidenosel:files

hide button when no files are selected

@hidenosel:dirs

hide button when no folders are selected

@hidenosel:numfiles=2

hide button unless exactly 2 files are selected

@hidenosel:maxfiles=5

hide button unless 5 files or fewer are selected

@hidenosel:mindirs=3,maxdirs=5

hide button unless 3, 4 or 5 folders are selected

@hidenosel:type=*.jpg

hide button when no files ending with ".jpg" are selected

@hidenosel:type=old

hide button when no files beginning with "old" are selected

@hidenosel:dirs,type=*.png

hide unless any folders, or any files ending with ".png", are selected

@hidenosel:!type=*.jpg

hide button if files ending with ".jpg" are selected

@if @ifset

Allows simple conditional behaviour based on tests for various commands.

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:

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:

@if:<command line>

test if a specific command condition is true

@ifset:<Set command argument>

test for a specific Set command condition

@if:enabled <command>

test if a command button would be enabled (rather than highlighted)

@if:$foo

test if a variable called "foo" has been set

@if:$glob:bar

test if a global variable called "bar" has been set

@if:SIDE=left

test if the toolbar is tied to the left file display

@if:SIDE=right

test if the toolbar is tied to the right file display

@if:&&ARG&&=value

@if:&&ARG&&!=value

@if:else

an "else" clause that is executed if nothing else matches

@if:common

common instructions that are always executed

@ifexists

Lets a function do different things depending on file or folder selection. The available tests are the same as for the @disablenosel modifier (documented above).

For example,

@ifexists:

<drive or path> - test if drive or path exists

@ifexists:wild:

<drive or path> - test if drive or path exists. Allows wildcards in the final path component

@ifexists:!

<drive or path> - test if drive or path does not exist

@ifexists:else

an "else" clause that is executed if the path doesn't exist

@ifexists:common

common instructions that are always executed

@ifsel

@ifpath @ifpathr

The possible forms of this modifier are:

You can negate the condition by prefixing it with a ! character.

Examples:

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.

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, Ctrl 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:

TOBEDONE

@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

@ifpath:C:\Program Files

Tests you are in C:\Program Files

@ifpath:!C:\Program Files

Tests you are anywhere but C:\Program Files

@ifpath:C:\Program Files\*

Tests you're in a folder below C:\Program Files (does not include Program Files itself)

@ifpath:!C:\Program Files\*

Tests you are not in a folder below C:\Program Files

@ifrunning

@ifrunning:notepad.exe

test if Notepad is running

@ifrunning:!note*

test if a process starting with "note" is not running

@ifrunning:else

an "else" clause that is executed if the process doesn't exist

@ifrunning:common

common instructions that are always executed

@keydown

@keydown:<qualifiers>

test for a qualifier key or combination of keys

@keydown:!<qualifiers>

test for a qualifier key or combination of keys NOT being down

@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//

@label

@leavedoswindowopen

Instructs Windows to log usage of programs or documents opened by this function. Typically this means any files used will be added to the recent documents list, and any programs that are launched are added to the recent applications list.

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.

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.

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.

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.

Outputs all text on the rest of the line to the Script Log. Useful for debugging. The output can also be viewed in the Command Editor when its *Run With Logging* mode is on.

Allows a block of commands to be run once per file. Normally, functions containing multiple command lines run each command separately for all selected files.

For example,

With two files, "Apple.txt" and "Banana.txt" selected, this would output:

Using @perfile around these commands like so:

This would output:

Use @perfile:begin to mark the beginning of the per-file block and @perfile:end to mark the end.

@leavedoswindowopen

leave DOS prompt open when function finishes

@logusage

@logusage

log usage of files and applications

@nocall

@nocall:<batch file>

invoke external batch file, do not return control to this function

@nodeselect

@nodeselect

do not deselect items used by this function

@noexpandenv

@noexpandenv

do not expand environment variables

@nofilenamequoting

@nofilenamequoting

do not automatically quote file names and paths

@nolocalizefiles

@nolocalizefiles

do not automatically localize (download) remote files

@noprogress

@noprogress

do not display an automatic progress dialog for this function

@norunbatch

@norunbatch

do not split batch functions because of internal commands

@output

@output <message>

sends <message> to the Script Log

@perfile

@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.

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.

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

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.

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,

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.

@resolvelinks

resolve shortcut targets when passing filenames to commands

@runbatch

@runbatch

force a DOS batch function to execute at a certain point

@runmode

@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

@runonce:<command>

the specified command will only be run once

@script

@script:<language>

specifies scripting language for Rename command

@set

src:<name>

variable will be scoped to the source folder tab

dst:<name>

variable will be scoped to the destination folder tab

left:<name>

variable will be scoped to the left folder tab

right:<name>

variable will be scoped to the right folder tab

tab:<name>

variable will be scoped to the active folder tab (see below)

lst:<name>

variable will be scoped to the Lister (the whole window)

glob:<name>

variable will be scoped globally

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

@showif

The button will be shown if a command clause test is false. This is similar to the conditional testing offered by the @if modifier.

Sends the specified keystroke to the system. The key will be routed to whichever window currently has focus. For example, @sendkey:win+v sends the Win+V key to the system, which opens the Windows clipboard viewer.

Supported qualifier keys are shift, ctrl, alt and win.

As well as letters and numbers, the following named keys are also supported: backspace, capslock, delete, down, end, enter, escape, home, insert, left, numlock, pagedown, pageup, pause, printscr, right, scrlock, space, tab, up.

@showif:Set DUAL=toggle

button will be shown if the Lister is in dual-display mode

@showif:!Set DUAL=toggle

button will be shown if the Lister is NOT in dual-display mode

@sendkey

@showifpath @showifpathr

Paths may use aliases, environment variables, {apppath} codes, and so on, only when using wildcards (not regular expressions):

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).

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):

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:

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:

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:

You can also use @toggle:update to ensure buttons with dynamic labels (via @label, above) are updated after changing variables or other details the label depends on. This also ensures toolbar layouts are adjusted if the label widths change.

@showifpathr:^C:\

show command if source path is on the C: drive

@showifpath:!*\Work\*

show unless source path is underneath a folder called Work

@showifpath:!/desktop

show unless in the Desktop folder

@showifpath:!%SystemRoot%\System32

show unless in C:\Windows\System32 (on a typical system)

@showifpath:{apppath|dopus.exe}

show if in the folder where Opus is installed

@sync

@sync:notepad.exe {f}

runs Notepad synchronously

@toggle

@toggle:invert

inverts the usual highlight state of the toolbar button

@toggle:disable

prevents the button from ever appearing highlighted

@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

最后更新于