xplorer² Exponential growth to file management productivity

Advanced programming and scripting

User interface automation with macros

• Execute a command that launches a dialog
• Find windows (dialog control elements) like buttons, text fields etc
• Set text in edit controls
• Check radio buttons
• Select from lists
• Click buttons
• Wait for commands to finish

All in all you can do whatever any user could do using the keyboard and the mouse to operate the program, only do it in a tightly controlled fashion. You can string commands together that operate on a series of dialogs to achieve complex results. Many times you can get a head start using the macro recorder, where you just use the program for what you intend to capture with the macro, and get a skeleton implementation for free. However first let's do it the hard way, writing everything from scratch. Here is an example script:

# copy selected files with filter
COMMAND "copy to"
WAITWND
FINDWND filter
FINDCLASS combobox
SETTEXT *.pdf
OK

As you can tell from the command names, this macro is equivalent to clicking on the Copy To toolbar button, waiting for the dialog to appear, then finding the Filter box and setting its value to "*.pdf" ; and finally "clicking" the OK button to start copying the files with the selected options (only PDF files will be copied).

Use Customize > Macros > Edit macro menu and copy/paste the above script in the editor area as such:

Figure 48. Macro editor: compose new macro

Going quickly through the macro editor dialog, we see a Command drop-down that lists the most popular commands, which you can insert with guidance on the expected arguments. Clear button erases any previous macro so you can start fresh. When you are ready, click Run to execute the macro, or Debug button to troubleshoot problems. Save will add the current macro in Customize menu so you can use it again in the future.

Click Run to run the above macro. If you had any PDF files selected, it will copy them to the inactive pane, otherwise it will do nothing. When a macro is running you cannot work with the main program window. You will see dialog boxes opening and closing in auto-pilot mode, following the macro commands. A macro control window appears on top of other windows that shows the progress of the execution. To abort a macro mid-way through its execution click on the Cancel button. While a macro is running you should not switch to another window or application, otherwise the macro will probably fail. Nor should you interfere with random clicks or keypresses. Just hang in there till the macro is finished!

When you repeat a macro saved in Customize > Macros list, it works in silent mode; you won't see any dialogs poping up, just the result of the macro instructions. When the macro finishes, you will see a message on the statusbar — unless some error steals the show!

To abort a silent macro that seems stuck press <CTRL+BREAK> to stop it — if you can find the key!

Macro command syntax

COMMAND "copy to" # start the copy to dialog

The macro language instructions and searched command and window labels are all case insensitive. You can use any case you prefer, e.g. command "COPY TO" is just as valid as the above example.

Arguments are necessary for many commands. They are usually constant text strings as the name of the toolbar button you are trying to click. Use "quotes" whenever you have spaces in arguments (many words). Arguments can also be numbers e.g. 32793 is the equivalent identifier for "Copy to" toolbar button (use Help > Command finder menu to find numeric equivalents to commands). Most of the time it will be easier to use the text label, but sometimes there will be no alternative than to use the number, e.g. for hidden commands. Arguments can also be variables, which will be discussed below.

Many commands return a value, e.g. FINDWND returns the handle to the window found. You don't see this result immediately but it is stored in the last result register ($0). Subsequent macro commands may rely on the previous result to function properly, e.g. CLICK needs a window handle found earlier. The last result is piped from one command to its successor automatically.

9 elementary variables are supported to be used as arguments, called $1 to $9. Most of the time you will use $0 if you want to visualize the result of the last command (MESSAGE $0).

Finding windows and menu commands

If you are familiar with windows programming, you will know that each menu command and toolbar button appearing in a program's user interface correspond to a message number. Likewise, controls that appear in dialogs have an identifier number. For instance 32793 is the message number corresponding to "Copy to" toolbar button; and the OK button in most dialogs translates to number 1. Unless you are a big time geek <g> that can use Resource hacker or Spy++ you cannot be expected to know these numbers!

Laymen needn't worry. Instead of fumbling with cryptic numbers, you can use the text that appears on a menu, toolbar or dialog button to tell the macro which command you are after. Take note which text appears on the menu command you want to issue, and use it as the argument to COMMAND. For toolbars use the tooltip if the button you are after has no text showing. It is best to use the full command text as it appears in the GUI, which will ensure that the intended command will be issued. Partial names can be used too, but keep in mind that the first matching name will be used, which may be some other command or window! All

Finding buttons on dialogs is easy, just use the name of the button with FINDWND. Other controls have some descriptive text label before them, which may be used to locate the control. Sometimes a control has no useful text or label; in these cases locate the control nearest to the unlabelled one, then move forward or backward with NEXTWND or PREVWND instructions till you hit the desired dialog control. The directions "forward" and "backward" correspond to the tab order in the dialog — or in plain english, what happens when you press <TAB> key to move around in a dialog window.

Dealing with syntax and execution errors

• One macro instruction per line. Don't use ; to terminate commands
• Some instructions expect arguments, some don't
• If your arguments contain spaces, enclose them in "quotation marks"
• Are there matching unique labels for all jump instructions?

• 1: unknown?: mystery error code probably caused by an error message during executing the command in the GUI
• 2: Wrong argument: you passed an empty variable to a command that expects an argument
• 3: Search failed: a command or window could not be found (or is disabled)
• 4: Wrong window class: you tried to operate a window in an unsupported way, e.g. change the text of a button or click an edit control
• 6: Command disabled: the command or window cannot be manipulated because it is disabled

When you get an unexplained error 3 (not found), it could be that the dialog didn't have time to appear. If you use COMMAND and expect to operate the dialog controls, use WAITWND to make sure that the dialog is visible before you start manipulating its controls. FINDWND instruction is searching the dialog that is currently active (excluding the macro dialog itself).

Finally you may realize that a running macro is doing crazy things that were not intended. In that case click on Cancel button to abort the macro execution.

Debugging macros

When you run a macro and it errors out, you are offered to run it again in debug mode. Or click Debug button in the macro editor to enter the debugger.

Figure 49. Running a macro step by step

In debug mode, the running macro (modeless) dialog is taller — you can resize it to taste. Instead of running the macro wholesale, it runs one line at a time. The current instruction is highlighted. Click on step button to proceed with the next instruction. Each command shows a little information in the Debug log area which you can examine to see if it does what you meant to do.

A cool feature is that it will  highlight  the last dialog control found — notice the thick border around the Filter combobox in the above picture.

It isn't quite in the same class as WINDBG, but with all the information shown, you should understand what the problem is, and go back to the macro editor to correct it.

Conditional execution

Once you turn off the automatic error handling, the last result $0 variable will reflect the execution status of the last instruction. You can test for success using the JUMPOK instruction, which will jump to a label (i.e. move the point of execution) only if everything goes well — otherwise the instruction immediately below it will execute. Here's an example that looks for a window called test and stops execution manually if not found:

ERRORSTOP 0
FINDWND test
JUMPOK found
MESSAGE "window not found"
EXIT
LABEL found
CLICK

Simple loops are also possible using a control variable as a countdown counter, as such:

POP 5 # repeat 5 times
STORE $1
LABEL repeat
MESSAGE $1
DECR $1
JUMPOK repeat
# end of loop

Macro command reference

The macro composition dialog has a listbox with the most common commands so you don't need to remember the names. Below you will find the full list of supported macro instructions and their expected arguments.

A typical instruction accepts a single argument, but there are some that apparently work on thin air without arguments. This is because they use the result of the previous command as their argument — this is called pipe argument. For example CLICK operates on the result of an earlier FINDWND command. If a command fails the result is zero (void).

Arguments can be either constants (strings or numbers) or variables ($0 to $9). Variables represent strings, numbers or window handles, depending on what is stored in them. The last result is kept in variable $0. Unless otherwise stated, the following table uses name for either a string or number, furnished either as a constant or variable.

Harnessing macros will take some practice. Below you will find some sample macros you can play with. Try running them in debug mode (line by line) to see what they do with xplorer². Observe the inline comments for extra explanations.

⊕ Click here to show sample macros →

# select files modified before 2017
# ---------------------------------
COMMAND "matching a rule"
WAITWND
FINDWND clear
CLICK
COMMAND "add new"
WAITWND
FINDWND property
SELECT modified
FINDCLASS SysDateTimePick32
SETTEXT 0 # clear date
FINDCLASS SysDateTimePick32 # next one
SETTEXT "1 jan 2017"
OK
OK

# copy selected files with filter
# -------------------------------
COMMAND "copy to"
WAITWND
FINDWND filter
FINDCLASS combobox
SELECT "only source" # saved filter
FINDCLASS combobox
SELECT default
OK

# execute Diff command from TSVN context menu
# (operates on active view's selected item)
# -------------------------------------------
GETFOCUS
CMENU diff
GETFOCUS
SENDKEY down # select next item

# browse C:\ folder
# -----------------
FINDWND address
FINDCLASS combobox
SETTEXT "c:\"
SENDKEY enter

# show paths for all items in left pane
# -------------------------------------
FINDWND "left pane"
STORE $1 # listview window
GETCOUNT $2 # total items, process in reverse
LABEL loop
POP $1 # restore window
SELECT $2
COMMAND "copy names"
WAITIDLE # command finished?
INPUT 0 # import clipboard
MESSAGE $0 
DECR $2
JUMPOK loop

# show the last column of the selected item
# -----------------------------------------
COMMAND "copy columns"
INPUT 0 # from clipboard -> $0
# first line is the header, skip it
CHOPSTR \n2 # \n is for newline
# columns separated by tabs
CHOPSTR \t-1
MESSAGE $0

# search in selected folders
# --------------------------
GETFOCUS
STORE $1 # browser window
# create comma separated list of selected paths
# SENDKEY alt+ctrl+C # easy way; let's do it hard!
COMMAND "selected only" # hide unselected
WAITIDLE
POP $1 # restore window
GETCOUNT $2 # total items, process in reverse
LABEL loop
POP $1
SELECT $2
COMMAND "copy names"
WAITIDLE
INPUT 0 # import clipboard
STORE $4
POP $3
ADDSTR $4
ADDSTR ","
STORE $3
DECR $2
JUMPOK loop
COMMAND "find file"
WAITWND
WAIT 1000 # 1 sec, dialog appeared?
FINDWND look
SETTEXT $3
# now add search criteria

# remove duplicate tabs (same folders)
# ------------------------------------
GETFOCUS
PARENTWND
FINDCLASS WTL_DNTabCtrl
STORE $1 # tab window
LABEL restart
GETCOUNT $2 # total tabs
DECR $2 # exclude close button
LABEL loop
POP $1 # tab window
GETITEMTEXT $2
STORE $3 # path to find
POP $1 
GETCOUNT $4
DECR $4
LABEL inner
POP $2
EQUAL $4
JUMPOK skip # skip current tab
POP $1
GETITEMTEXT $4
EQUAL $3
JUMPERR skip
POP $1
SELECT $4
COMMAND "close tab" # close duplicate
POP $1
GOTO restart # tabs changed
LABEL skip
DECR $4
JUMPOK inner
DECR $2
JUMPOK loop

Automatic macro recorder

If you don't need the full power (and learning hassle) of the scripting language, you can record simple macros pressing <F12> key to start the macro recorder (or use Customize > Macros > Record macro menu command). Use the mouse and the keyboard to do what you like (issue commands, tweak dialog controls and buttons, etc), then click on finish button to stop recording. The equivalent script representing your actions will be generated automatically and presented to you, just as if you had typed in the instructions. Then you can do slight modifications with the macro editor.

The recorder will only generate plain macros (without loops), and the resulting code looks spaghetti, but it should be adequate for the average macro requirements — and you don't need to do any "programming". If you start the recorder and click Finish immediately, without any actions, you will be presented with the last macro used.

Saving and reusing macros

You can save useful macros for later in Customize > Macros list. The saving procedure is a bit unorthodox, but straightforward. First finalize the macro commands and test it well with the editor. When you are done, bring up the editor again (use Edit macro menu command to edit the last macro), click Save [1] button, give it a descriptive name [2] for the list, then Run [3] the macro. If you don't run it, it won't be saved. If you don't want to run it fully, you can "cheat" clicking the Debug button, then cancel the debugging without running anything. This way you will save the macro without running it. The macro list menu works like bookmarks, use its Organize menu command to add icons for toolbar and keyboard shortcuts for easy access. You can also edit an existing macro from organize dialog, adding or removing instructions, but it will feel a bit crumped. Another way to modify a saved macro is to first run it, then edit it (as the last macro used with Edit macro menu), and finally save it with the same name — which will overwrite the previous definition.

Programmable column: file property algebra

You may be familiar with DeskRule's desktop detective panel that enables searching with combinations of file properties and attributes. xplorer² (ultimate edition only) programmable column is an extension to this concept: it allows you to combine file properties, boolean and arithmetic operators and a few functions into expressions, whose result is the value of the Programmable [S] stock column. This result can be then used as any other column, for display, sorting, filtering and searching for matching files. It is really versatile and the possible uses are too many to enumerate — just use your imagination!

To use the programmable column, switch to detailed view mode, right click on the column header row and pick Programmable from the menu. This will allow you to change the expression and will show the programmable column too:

Figure 50. Define programmable column expression

The programmable column definition dialog has controls that guide you to create expressions, with drop-down lists for file properties, boolean and arithmetic operators and some simple functions. Or just type your expression in the edit box provided. As you type, it will autocomplete file property names for the more experienced users. Say you type $EXT (the dollar is very important) a popup will find all the matching properties that have ext in their name and you can insert them easily — press the <Down> arrow key to select from the completion list.
All elements of programmable expressions are case insensitive

Click preview button to see the results of your expression on the selected file in the active folder pane. If something goes wrong, it will pop a syntax error with the likely error location.

All file properties (columns) can be used in the calculations. The rules can also search in files (GREP function) and extract specific file bytes (FBYTES function). The result of the expression can be either text or number or even a date, depending on the properties and operators used. If you use conjunctions of boolean operators, the result will be 1 or 0, for true or false respectively.

For instance the above example expression if(FBYTES(1,3)="50.4E.47", "its PNG!", ${Extension}) will check each file's contents to detect whether it is PNG format, in which case it will show "its PNG!"; for other file types it will show the extension. See how it works for the few files in figure 50 above.

If programmable column is enabled, it applies the last expression you defined on each and every file, and shows the end result. There is only one programmable column, but you can save expressions you use frequently by supplying a name in the Predefined box in the above dialog and clicking Save button. This is similar to storing hyperfilters for search commands. Then expressions become available for future use from the history drop-down dialog control — pick one from the list and the programmable column display will be updated.

File attribute algebra

This dialog allows you to do amazing feats which would normally require you to write a program or advanced shell script. You can combine any file property with arithmetic (add/subtract/multiply etc), relational (equal, greater than etc) and boolean operators (and/or etc) to create arbitrary expressions that can be evaluated for each file. For example take the expression:

(${Modified} > ${Created} + 2) & ${Size} + 5KB < ${Size on disk}

It will match files whose modification date is later than the creation date + 2 days, and (&) their reported size plus 5 kilobytes is less than its total size on disk. As this uses the & (AND) boolean operator, the result will be 0 (false) or 1 (true). This value will show in the programmable column, and can be used as a search rule to identify files with custom qualities.

When you become familiar with the "official" property names and operators, you can type such expressions manually (press <Ctrl+DownArrow> key to autocomplete properties), or you can use the dialog drop-down lists to help you compose a complex rule with properties, operators and functions. A few clarifications are in order:

• Variables. These are file attributes, enclosed in braces with a leading dollar ($) sign; ${Modified} is the date last modified property (consistent with their use in $-tokens). The name inside the bracket is the same as the column name — it may include spaces. Type a $ then start typing part of the property name and the dialog will offer you the possible name completions.
  If you use special properties that not all files possess, the expression may fail. If for example you try to use "date taken" property on a text file, the expression will come up blanc (false always) — it is only supported for JPG files.
  
   
• Constants. Anything that is not a variable or a recognized operator is considered a constant. The type is automatically deciphered, e.g. 2 is a number, 3.4 is a floating point number, 25/12/15 is a date and so on. Numbers can be followed by KB/MB etc if you prefer size units.
   
• Date constants. Except for regular dates, you can use things like "yesterday" or "last year" (use quotation marks to preserve space characters). You can also use constants like "March 2015" which would match any date within the said month. For date ranges use the > and < operators in a conjunction e.g. ${modified} > "25 feb 2015" & ${modified} < "1 jun 2015"
   
• Wildcards and regular expressions. A string constant can be either a literal like "hello world" or wildcard like test.*. Many of the special characters that appear in regular expressions could be mistaken for arithmetic operators, so please put wildcards and regular expressions in single quotes e.g. 'FILE[1-9].TXT'. Also note that when comparing string operands, equal (=) implies identical strings (ignoring case), whereas the approximate (~) operator means that one string needs to be part of the other, e.g. a partial match.
  Sometimes it is hard for the program to automatically fathom out a regular expression or differentiate it from a wildcard, if there are not enough special characters present. In that case, to force a regular expression enclose it all in brackets e.g. '(a.+)'. The meaning of the regexp will be the same and it will be unambiguously recognized as such.
  
   
• Unusual operators. Most operators have their usual sense, e.g. 1+2=3 will always be true. Here are a few exceptions:
  • When you subtract dates, the result is a number (their difference in days).
  • $date + number increases the date by that many days
  • Adding strings concatenates them "str"+"ing" = "string"
  • You can compare strings, e.g. "a" < "box" is true (like sorting strings)
  • All string comparisons are case insensitive so "A"="a" is true
  • Using brackets you can have really complex expressions with nesting.
  • Arithmetic operators are calculated first, followed by comparisons. Boolean operators execute last. Use brackets to override the default operator precedence.
  • Arithmetic between mixed types (except those mentioned above) will likely result in a syntax error
  
  
• Helper functions. Various string and date functions are supported like len(text) which returns the number of characters in the string argument (=4 in this case). Functions require one or more arguments that should be enclosed in brackets and separated with commas, e.g. find(abc,b), and return values that can be used even within other functions, e.g. mid(${Name}, find(${Name},'12'), 5) will extract a substring of 5 characters in the filename, after the first occurrence of 12 in said filename. Anything goes inside function arguments, including arithmetic operations etc. If you supply the wrong number or/and kind of argument to a function, a syntax error will be triggered. See the table below for all the supported functions.
  TIP: If you want to use a string constant that happens to be a reserved function name, use quotes, e.g. len("len") is a valid expression that would return 3.

If there is some problem with the complex expression like a misspelled file property or an operation between incompatible arguments, xplorer² will report a syntax error, highlighting the trouble spot. Correct the typo and you are ready to search.

Sometimes a property name on its own can be a useful rule, e.g. ${Keywords} without any other operators will match files that have some tags defined. Or combine it with a leading NOT (!) operator to match files that do not have tags! Bare property names are also convenient for yes/no properties like ${IsFolder}, otherwise you must be careful to compare them only against zero (=false or no).

The programmable column is useful for many advanced search tasks, e.g. find pictures whose width/height ratio is 4/3. It will also allow general tomfoolery like (${Modified} - ${Date taken})/2 = ${Size}, which arguably is not much use <g>. A final note is that extracting this column is rather slow; the more properties you use in an expression, the slower it gets. If you use multiple properties in a search expression, use the faster ones like filename and size first, and leave the slower ones (e.g. GREP) at the very end.

 

◀ DOS commands |   Contents   | Customization ►

---

© 2002-2024 ZabKat LTD, All Rights Reserved
zabkat.com