Desktop Rules

Find needles in a haystack

TABLE OF CONTENTS
Introduction

Program Interface
  Search modes

Search for files and folders
  Property selector | Rule definition | Boolean algebra | Normal search mode | Desktop detective | Picture geolocation

Inspect search results

Program Settings
  Search template customization | Advanced tweaking

Macro commands

Licensing and registration

Miscellaneous

Are you in a hurry? Too bored to read manuals? Make sure you watch the demo videos (look out for demo video signs)


Introduction

This is a new generation desktop search tool, that uses the "new" property system supported by windows VISTA+. It helps you find stuff (files) on your desktop, and does so in a fast, powerful and easy to use manner. It will help you find (among other things):

There are 1000+ properties available for shell items, and I believe that around 300 of them are usable for file queries. That is around 295 more than you or anybody else are using at present. Such a waste must be ameliorated! Wouldn't you care to find all your pictures taken at a particular GPS location? You bet!

Existing desktop search tools and file managers like windows explorer and xplorer² (another ZabKat product) do not tap into the extended property system, they are limited to old-school shell column handlers. DeskRule (as we will be calling this program from now on) ignores completely column handlers and focuses on system properties. These include all the legacy column handlers but add many other interesting attributes like picture people tags (face recognition data embedded in JPG files) and much more.

DeskRule is not a generic file manager like xplorer². Its main and only job is to find files on your desktop using a rich set of attributes and complex boolean algebra. Once you find what you are looking for, you can open the document or picture or what have you, and use some other simple desktop operations like drag-drop and shell context menu (copy/delete/properties and the like). But you will not have the rich toolset of file management functions; for that you will still need a tool like xplorer².

DeskRule is more like an explorer with desktop search. Here are the general ideas:

DeskRule is fully shell integrated. This means that it can search everywhere your windows explorer can, not just in filesystem folders, and it supports all standard shell extensions and handlers. You can improve your search and the presentation of the results downloading from the array of available content and preview handlers.


Program Interface demo video: overview of program features

The program window is split in two major parts, the top half where you define the search parameters (where and what to search for), and the lower half that shows the items matching the search criteria and found during the search.

main window
Figure 1. The main window

Here is a brief description of the main window elements:

The tool is minimalistic, without a menu bar. A few commands will be found right-clicking on the window titlebar (or system menu — top left corner) and various context (right click) menus. You can also use the usual drag-drop operations.

Search modes

Managing 300 search attributes is not an easy job and could lead to confusing GUIs. How do you tell DeskRule you need to search by Date picture taken and Rating attributes? There are four ways to do it, in order of increasing complexity (and finer search control):

Simple search mode
Figure 1a. Simple/Plain search mode

Deskrule starts in normal mode with the most frequently used search boxes present. You can type in any one (or all of them simultaneously) to define your query, then click on Start search button. If you want something simpler than that click on the first toolbar button (simple search, depicted by a magnifying glass). Now you will only see one search box called Find. You can tightly arrange the toolbars as you can see in the picture 1a above. In this super simple mode the advanced panel is hidden. Click on the magnifying glass again to restore the normal search mode.

The simple mode relies heavily on windows search index. If you are searching in folders where WDS cannot reach then only filenames will be fetched. No wildcards or special characters are allowed in search keywords. For more control please switch to the normal search mode (click on the simple mode magnifying glass toolbar icon to turn it on/off).


There are two issues in searching, where and what. DeskRule uses traditional (filesystem) folder hierarchies to explore and look for matching items. You supply the root folder of the search in the addressbar (see figure 1), and DeskRule will search this folder and everything under it (picture the root folder and its subfolders in windows explorer folder tree control). You can type the folder name or use one of the easier alternatives:

That covers the where to search part.

You can search in special folders like ZIP archives, FTP, connected phones and the like, as well as normal folders on your hard disk. To search in special folders make sure you enable the option Enter virtual folders (press <F12> key for program settings). You can search in compressed archives like 7Z and RAR if you install a special shell extension.

The what part is more complicated, on account on the large number of available file properties and the complex boolean algebra available for declaring search rules. The search rule can be something simple as a filename, but it can also include any number of file attributes out of the available system properties. The more rules you use, the more accurate the search results, and less matching items will be found — and the longer it will take to find them!

First we will discuss the advanced search mode. demo video: advanced search mode

Property selector

Double click on Add new rule to bring up the property selector dialog. This is the only dialog in the program (not counting the About dialog :) and looks like this:

property selector dialog
Figure 2. Choose property dialog

The approximately 300 system properties available for search rules are organized in categories (general, audio, picture, music, document etc). However the easier way to find a property is to set the category selector [2] to All properties then use the auto-filter box [1] to find your property. You can add any number of keywords separated with spaces to find the property you need. Matching properties are shown in the list [3] with further explanations. Use double-click to choose the desired property.

If you see an [I] mark in a property's type this means that the property is in the windows search index and can be used for fast searches.

A special type of property is Contents, which allows you to search for text within documents. It is available under the "Simple" category along with other stuff you frequently search for. Also under the Legacy category you will find some of xplorer² stock columns and even older windows XP column handlers (TSVN and the like) and WDX content plugins. Finally if you want to search for folders only, add IsFolder attribute.

Rule definition

Each property (search attribute) you add has to be further determined with a desired value. When you add the Name property you must add what name you are looking for. To change rule property values, first you select the rule in the search panel. The available tweakings for the selected rule will appear in the property control [5] (see figure 1).

There are 3 main classes of file properties, text, numbers and dates. Each category has variations, e.g. a date could be a range or something simple like "yesterday". Number attributes can be defined either as a range, or fixed to a value (equal/not equal). As you roam about the property control, you see explanatory text for the active (selected) row that should help you understand how to go about setting modes and values.

Text rules have the richest set of available options. Tweaking the Text mode you can supply a single keyword or expression to find, or a list of keywords to include/exclude, or complex boolean text expressions like this AND (that OR "the other"). When you leave the default Auto wildcards mode on, each keyword can be a wildcard or a regular expression — DeskRule guesses what it is from what you type, e.g. *.jpg will be assumed a wildcard and file[1-4] a regular expression. If you insert any uppercase letters, the whole string expression becomes case sensitive — have all characters in lowercase if you are not interested matching the case.

The property control will appear awkward at first but it is well thought out and easy to operate using the keyboard:

Here you also set the boolean context of the file property rule (in relation to other rules you add)

Proper boolean algebra

Unlike xplorer² where individual search rules are stringed in a linear fashion (this AND that OR other), DeskRule supports full boolean algebra including nested brackets, so you can test for things like:

(size > 100 AND Modified in 2013) OR (kind=document AND (extension=pdf OR NOT name=something))

How do you put expressions in "brackets" in a user friendly manner? The search rule composition window uses indentation. To push a rule inside brackets you indent it right, using either the pop-up toolbar or the context menu (or use the keyboard shortcut <Ctrl+Right>). So you can have: (+ is AND, ^ is OR):

+RULE1
	+RULE2
	+RULE3
^RULE4
	+RULE5

which corresponds to (RULE1+RULE2+RULE3) OR (RULE4+RULE5). The leading (unindented) item is the first in the bracket; the bracket "closes" when you indent some item to the left, beginning a new group. This way you can have arbitrarily deep nesting and subexpressions. A bit quirky but that's the "easiest" idea I had — please feel free to suggest something easier if you have an inspiration.

Using other menu commands you can move rules up and down (rules are evaluated in the order shown, so try to put slower rules like contents search toward the end for quicker search results), duplicate or delete rules etc. To clear all the rules, first select all with <Ctrl+A> then press <DEL> key and start afresh.

Normal search mode demo video: normal search mode

The advanced search mode is powerful and expressive, but can be also taxing to operate. The normal search mode is much simpler to use albeit at the expense of accurate control in rule definition. Still you can use all the system properties in this mode.

To activate the normal mode, minimize the advanced search panel clicking on its pin and use just the toolbar input fields. By default you can search by Name, Date modified, Type and file contents (keywords) but you can add more rules using the green plus [+] toolbar button. To remove a rule click on the red [X] button to the right of the rule's input field. Use the Reset toolbar button to default to the 4 basic search rules. You can choose your own default rules using Set default command from the reset button's drop-down menu.

You can size and move around each box rule dragging it from its gripper handle to the left — this way you can customize the appearence of the normal mode to taste. Or right click on a toolbar and pick Auto-arrange menu command to have the boxes arranged automatically for you.

You don't have to fill up all the normal mode boxes, just fill in the parameters you want, e.g. specify a Name and leave the date and contents fields empty to search only for filenames.

Properties as usual come in 4 varieties, text, number, dates and enumerations (lists). Except for the latter mode, the input boxes are plain text fields where you can type in what you want to search. The enumerated mode is for parameters like System.Kind where you must choose one of the predefined options from a drop-down list.

Rules that accept numbers like Size, can be defined in a variety of ways e.g. all the next inputs are valid:
5 kbfind files that are exactly 5KB in size
>=4096  search for files at least 4096 bytes large
<=6MBsize up to 6 MB
5 .. 10size in range from 5 to 10 (note use of .. range operator)
~1GBsize approximately 1GB (10% tolerance)
<> 5Not equal to 5

Many numeric properties can have units, for example searching for file size you can either specify 1024 or 1KB which are equivalent. Audio length can be specified in the form MM:SS and GPS coordinates as 145°3'0" (degrees/minutes/seconds). Note some properties are shown in units different to those that are used to find files, e.g. to search for audio bitrate you must enter the number in bps not kbps (128000 vs 128). The units are often shown in the Property details section in the Rule property control [5] — click on the [+] box to see this information.

The same operators can be used for date fields e.g. >=30/3/2014 would mean a date newer than March 30, 2014. Partial dates like "December 2015" or just "2015" are also allowed. Date inputs also accept strings like "yesterday", "last month" etc, through a drop-down list. You can click on the little clock icon to compose a date if you are too bored to type it!

For text rules, usually you put one keyword, which can also be a wildcard or regular expression — these are automatically identified from their special characters like * or {}. If you put in more than one keyword then all must be present (in any order) for a successful match. If you need to match a whole expression put it "in quotes".

Text searches are much faster if you don't use wildcards and regular expressions. In this case only stems are matched, that is beginnings of words. For example, searching for TEST by name will find files called TESTME.TXT and FIRST TEST.TXT, but will not find A1TEST.DOC. To find the last file you must use explicit wildcards like *TEST*. To match exactly (is instead of contains) use a leading equal sign (=TEST)

The normal mode is good but it cannot match all the breadth of options offered in the advanced mode. In particular you cannot do any of the following:

Desktop detective demo video: detective search mode

All the search tools you are used to will allow you to search for fixed file properties, e.g. finding files that are Modified this year. But what if you want to check file properties against each other? Say search for files whose Modification date is older than their Creation date? Introducing the unique desktop detective mode!

Desktop detective panel
Figure 2a. Desktop detective search panel

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

($System.DateModified < $System.DateCreated + 2) & $System.Size + 5KB < $Stock.TotalFileSize

It will match files whose modification date is earlier than the creation date + 2 days, and (&) their reported size plus 5 kilobytes is less than its total size on disk. You don't see that every day in a desktop search program <g>. 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 form buttons (Insert property and Insert operator) to help you compose a complex rule. A few clarifications are in order:

Function Description
num=LEN(str) Return the number of characters in string, e.g. len('abc') returns 3
substr=MID(str, nStart, nLen) Extract a substring out of a bigger text string, starting at position nStart and extracting nLen characters, for example mid('abc12', 2, 3) would return the string 'bc1'. Can be also used to access individual characters if nLen is 1.
str=TRIM(str) Eliminate whitespace around a string, if any. It cuts off any leading or trailing spaces, e.g. trim(' ab ') would return 'ab'
num=FIND(strHaystack, strNeedle) Find a needle in a haystack and return the position of the first occurrence — or 0 if nothing is found. find(abc12,bc) would return 2. The search isn't case sensitive.
num=DPART(date,str) Access parts of the date, e.g. dpart('march 2016', year) would return 2016. The second argument str can return other parts of the date e.g. month or day (or even just d).
xxx=MIN(xxx,xxx) Compare the two arguments and return the smaller one. This function accepts all kind of argument types (numbers, dates, etc) and returns the same kind. So min(-1,2) would return -1.
xxx=MAX(xxx,xxx) Similar to MIN function, this returns the larger of the 2 arguments
xxx=IF(term, if_true, if_false) Evaluates term and if it is true returns the second argument, else the third. The 3 arguments can be whatever makes sense for your conditional logic. term is true if it isn't empty or if it is non-zero.
num=ABS(num) Returns the absolute value of a number, e.g. abs(-1.3) would be 1.3
str=STR(xxx) Convert any type of argument into a string, useful for passing dates and numeric variables to other string functions
num=GREP(str) Search file contents for occurrence of text (can be a wildcard). If successful a positive value is returned, else 0 if keyword is not present in file.
Table 1. Supported helper functions

If there is some problem with the complex expression like a misspelled system property or an operation between incompatible arguments, Deskrule 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. $System.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 $System.IsFolder, otherwise you must be careful to compare them only against zero (=false or no).

Desktop detective 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 ($DateModified - $DateTaken)/2 = $Size, which arguably is not much use <g>. A final note is that this search mode is rather slow; comparing file properties is not something the WDS index was designed for, therefore all searches are performed the hard way, file by file. The more properties you use in an expression, the slower it gets. You can minimize the inconvenience by narrowing the search in smaller parts of the filesystem (that is choose the search root folder wisely).

Find pictures using a map demo video: find pictures by location

Pictures shot with modern cameras and mobile phones contain much more than imagery. JPG picture format contains EXIF tags with information like "date picture taken", "camera model" and the like. Nowadays they may also include the map coordinates where the picture was shot. If your phone has a GPS receiver, chances are that your pictures already have the so called geotags that can be used with google maps to show you the picture location.

If you right click on a JPG picture and choose to see its properties, you will find all the stored EXIF information in the Details tab. If you see a GPS section, the picture knows where it was shot; two numbers Latitude and Longitude define the exact spot on the earth's surface. Deskrule has a Map data property category that allows you to search for pictures in a given location, but you would be hard pushed to know that New York is found at latitude 40°45'31"N and longitude 74°1'17"W !

map dialog
Figure 2b. Define picture search space using a map

Enter Deskrule's unique picture map tool. If you click on the map toolbar button, you will see a dialog that shows you the map of the earth, where you can define a search area intuitively. Click on the World button to see all of the earth, then scroll and zoom in to find your desired location. Whatever you see on the map will be searched; if you pan onto the whole of USA, you will find pictures shot anywhere in the USA. Or zoom in more to find pictures shot in New York, or even in Central park!

Click on the OK button to close the map. Deskrule will then use the map data to define a range of latitudes and longitudes to search for, e.g. the range 40..41 latitude defines most of New York. Note the use of the range .. operator that defines the range of numbers to match. Click Start search and off you go! Searching for geotags isn't different than searching for any other file property; you would still have to define a starting search location (e.g. inside My Pictures folder) etc.

The map dialog allows you to save locations you wish to search for time and again. Just type in a Location name in the respective box and this will become available in the map toolbar button drop-down menu (see figure 2c below). This will save you the effort of zooming and panning the map for your frequently used search locations.

saved map locations
Figure 2c. Manage map locations

The only down-side to picture geolocation searches is that latitude and longitude data aren't indexed by windows search. Deskrule will search for the geo properties, but rather slowly. But if you consider that no other tool allows such geo searches at present, it is a valuable first step.

TIP: Browsing picture search results is more convenient if you switch to thumbnail view mode. In the search results pane right click "nowhere" (not on any filename) and from the background menu tick Thumbnails menu item. If you are not interested in file details, tick off Show details command in the same menu

Inspect search results

Once you have defined where and what to look for, click on Start search button to get the ball rolling. Search results are added as they are discovered and are available to operate on as in any shell explorer window. To keep the interface simple there is no button to Pause the search, but you can effectively pause it if you open any dialog window, e.g. click on the settings button. To resume the search dismiss the settings dialog; to cancel the ongoing search altogether click on Stop search button.

The search is performed in two stages. First WDS index is used to obtain results fast, whenever possible. If you don't see what you are looking for among the results, you can click on the footer button Click for robust search. Then the same search will execute bypassing WDS. Results will be slower to come but if your file is there it will be found.

The default view mode is details. The columns shown are implicitly defined by whatever search rules are active (e.g. if you search for Author there will be an Author column for all matching items), plus a few standard columns like Name/Size/Date modified that are always present. You can switch to plain list mode using the background right click menu. Using the same menu you can opt for normal icons or thumbnails (interestingly you can even have thumbnails combined with details!).

To operate on search results, first select them using all the usual methods (e.g. Ctrl+Click, mouse lasso etc) then drag them off the window with the left or right mouse button. The right click menu when items are selected shows the standard shell context menu, including some extra commands:

You arrange the search results by clicking on the column header. You can sort by secondary columns holding down <Shift> key while clicking on a column (as in xplorer²). Finally use the quick filter toolbar [3] to show only items matching some text. To see all the results clear the quickfilter contents or double click on the statusbar filter pane.

You can also export the search results as text in the clipboard. Hit <Ctrl+A> key to select everything, then press <Ctrl+P> to copy all the information as text. You can then paste them in any text editor or in MS Excel for printing or log-keeping.


Program Settings

Click on the settings toolbar button to modify various program options. The options are organized by category and you can see what each option does at the bottom of the settings dialog as you choose each option. Click on the Defaults button to reset all settings to "factory" values.

You can change most settings by double clicking on the name. For more information see the property control in the search panel.

settings window
Figure 3. The program settings dialog

DeskRule normally saves its settings in the registry, but you can have it in a portable mode too, keeping a file called DESKRULE.INI next to the program (say if you use it off a USB stick).

Search template customization demo video: customization features

You can define and reuse templates for different properties to search for in normal mode. First add and remove the search rule boxes you need using the toolbar [8], then use the drop-down menu under the Default rules button (see figure 4) to add a search box template. Use a descriptive name to remember what it is all about. Then you can activate any saved template from the drop-down menu.

customize toolbar layout
Figure 4. Manage rule boxes

You can also save search parameters (attributes) for repeating a search in the future. Define and start searching, then once the search is through use Save search button to keep it for later. To repeat a saved search use the drop-down menu next to the Save search button. If you want to keep the search folder along with the saved search parameters, turn on the respective option using Program settings dialog.

Both these customized lists are managed in a simple fashion. The most recently saved entry is placed first in the list. If there is an older item with the same name it gets overwritten. To remove a saved item right click on the menu and use the context menu (in the menu!)

Advanced settings tweaking

Some advanced program tweaks are possible through registry editing (or editing the INI settings file). You must first fully quit DeskRule pressing <Alt+X> key (or right click on the titlebar for the menu command), then fire up the registry editor typing REGEDIT.EXE in Start > Run dialog (<Win+R> key). Then locate the main registry key HKCU\Software\ZabaraKatranemia Plc\Desk_Rule and change values documented below. It goes without saying that if you are not familiar with registry editing you should stop right here!

EDITING THE REGISTRY CAN RENDER YOUR COMPUTER UNUSABLE.
Unless you are 100% certain you know what you are doing, you are advised not to modify it in any way.

Names that start with "bin" imply values that are made up as the sum of individual bits. Please sum up all the numbers representing the options you want and set this total number to the value. Don't modify any bits that are not documented in the table.
Key Value Data Explanation
General binFlags x80 minimize overhead for slow folders (e.g. plain icons for network items)
x100 enable searching in very deep folders (overall path >260 letters )
x800 disable fast searching filenames using MFT for NTFS drives
x1000 follow junction points, search them like normal folders
x8000000 disable fast desktop search through windows index
binSearchFlags 8 clear this bit to stop searching in filtered documents like DOC/PDF; only search plain text files
bin1OffNotify Set this to 0 to reset all the "don't show this again" type of messages and see them all over again
bSantasLittleHelper Set this to 0 to disable background threading (not recommended)
rgbViewBgcol xBBGGRR background color for search results, -1 for the default windows color
szGrepExcludeTypes list Comma separated list of file types (extensions) that you don't want to search for text. E.g. set it to pdf,doc if you don't want to search in PDF and Office documents
szTextViewerPath path Full path for editor you want to associate with <F3> command to view text files (if xplorer² is installed this defaults to editor², else notepad is used)
szPluginINI path Path to total commander plugin settings file. Default location is %APPDATA%\zabkat\tcplugins.ini. You only need this if you are using WDX/WLX plugins to extend DeskRule.
szFileCountRule wildcard Comma separated list of wildcards for Stock.FileCount property. E.g. *.txt,*.log would count items with txt and log extensions. This can also be a name of a saved search, enabling you to use very complex filters. The default value * counts all the direct subitems in a folder.
szSimplePropertyList list Comma separated list of system properties to search for simple mode, e.g. System.ItemNameDisplay,System.Search.Contents. Only text properties are allowed.
view_e900 nMaxListColumnWidth pixels Maximum pixel width of list view mode. Set it to 0 for unrestricted size
QuickView binMiscOptions 4 Preview in a background thread for responsiveness
8 Use internal text viewer for all text content
File types title list Extend the file types that appear in the Type selector (a default legacy property). You can both edit the default types or add new ones. Each type is a comma-separated list of extensions (without the dot)


Automate routine tasks with macro commands

A simple in-app "programming language" allows you to automate many program tasks. It is not a full blown scripting language (as e.g. the one in MS Excel) but it is surprisingly versatile and easy to use. You write scripts, that is sequences of simple text commands that manipulate the program window as if a robot was in control. You can do these sorts of tasks:

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. Here is an example script:
# script to add FRAME RATE rule on the toolbar
COMMAND "add rule"
WAITWND
FINDWND categories
SELECT video
NEXTWND # focus on the listview control
SELECT "frame rate"
OK
As you can tell from the command names, this macro is equivalent to clicking on the Add Rule toolbar button, waiting for the dialog to appear, then find and select the Frame Rate property and finally "clicking" the OK button to finish and insert the boxrule for the Frame Rate property.

Press <F9> key to start the macro editor (or use the system menu which holds a Macro command), then copy/paste the above script, then click Run button to see it working. When a macro is running you cannot work with the main program window. 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.

macro control
Figure 4a. Running macro dialog
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!

Macro command syntax

Each line of a macro contains just one command and its arguments, if any. For example:
COMMAND "add rule" # start the rule dialog
COMMAND is the reserved command name that tells the macro what to do, "Add rule" is the argument (which program command to execute), and the rest is the comment. Comments are ignored by the script but help you to make sense what each command is doing. Inline comments begin with the hash # symbol.

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. 32821 is the equivalent identifier for "Add rule" toolbar button. 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

The most important operations you will be using all the time is finding control windows (buttons, edit controls etc) to operate, and issuing message commands (using menu or toolbars) to the program — using FINDWND and COMMAND respectively.

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 32821 is the message number corresponding to "Add rule" 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!

TIP: When troubleshooting macros, insert a MESSAGE $0 instruction under a FINDWND or COMMAND. This will show you which window or command was found ($0 is the last result variable). Once you are done debugging you can delete or comment out these MESSAGE $0 instructions.

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

When searching for commands and windows, keep in mind that the search is within the active window. If no dialogs show, that means the main program window; if a dialog is showing, the search is within the dialog controls. Use the wait instructions (e.g. WAITWND) to make sure the window you want to manipulate has had time to show up.

Dealing with syntax and execution errors

When you first start working with macros, inevitably you will make mistakes. For example you can misspell an instruction name or forget a necessary argument. In that case a syntax error will result and the macro editor will highlight the token that caused the trouble. Here are some pointers to keep in mind: Once the basic syntax is correct, you can try running the macro. Here you may encounter subtle problems that will cause execution errors. The macro will stop, highlight the command that faulted and show an error message. Here are the runtime error codes explained: Error code 2 (wrong argument) is raised also when an instruction cannot find the correct last result from the previous command. For example you cannot use CLICK without a preceding FINDWND. Most commands that operate on dialog controls require a window handle in the last result $0.

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.

Conditional execution

By default all execution errors are terminal and stop the macro dead. However you may want to take responsibility and manage the execution despite previous errors. For example, if a control cannot be found you may want to try to search for another. If you want to ignore all errors, use the instruction: ERRORSTOP 0.

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
Using conditional jumps and GOTO instructions you can modify the order that script lines execute. Instead of linearly executing all lines in sequence, you can jump to earlier or later lines depending on your logic. Jump destination points (LABEL) can be any text you like to make sense of your script. If you have multiple jump points, make sure each label gets a unique name.

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
The trick is that DECR instruction updates (decreases by 1) the counter variable $1 and the last result, so when it reaches zero, you break the loop (JUMPOK fails). Also note the roundabout way to initialize the counter variable using POP then STORE.

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.

Instruction Argument Pipe arg. Result Description
FINDWND name window Find a window by name on it or next to it (if labelled). Searching for part of the name is ok if you are sure that it will uniquely match the window. Also finds by window numeric identifier. The search is in the topmost active dialog or the main window. FINDWND 0 returns the currently active dialog.
FINDCLASS name window window Find a window by its exact class name (e.g. edit, button etc). If the prior result is a window, it finds the next window of the same class, if any, possibly cycling from the top.
FINDFRAME title window Find a top level window by its titlebar text and switch to it (make it active). The window must be selectable, e.g. not blocked by a modal dialog.
NEXTWND window window Returns the next window in the tab order
PREVWND window window Returns the previous window in the tab order
CHILDWND window window Returns the first child window (of whatever was found earlier)
PARENTWND window window Returns the parent window
CLICK window status Clicks on the window found earlier. May fail if the button is disabled
CLICKDEF name window status Executes the default accessibility command for child name (if using a number, start from 1). This is for non-standard buttons that don't have window handles (exposed through MSAA)
SETTEXT name window status Sets the window text to name. Only meant for edit controls and combo boxes.
GETTEXT $var window Gets the text of the last result window and stores it in variable $0 - $9
GETCOUNT $var window Gets the number of items in listview control and stores it in variable $0 - $9
GETITEMTEXT index window text Extracts individual item text from windows like listview controls. Items should be specified by a number from 1 to GETCOUNT.
SELECT name window status Selects an item in a combo, list or listview control either by name or by number (1 → max items present). SELECT 0 will unselect everything
SETCHECK 1/0 window status Checks or clears a checkbox or radio button, if enabled
OK status Terminates the active dialog. It is a combination of FINDWND "ok" followed by CLICK. It may fail if the dialog won't close due to validation errors.
CANCEL Simulates pressing ESC key. If a dialog is active this will be equivalent to clicking on Cancel button

COMMAND name help text Issues a program command (WM_COMMAND) by number or by name. It is equivalent to using a menu command or toolbar button. Searching by name is more intuitive; it finds the command from a menu or toolbar that corresponds to the (partial) name. For toolbar buttons without names use the tooltip (popup) name. If the active window is a dialog, it finds the named button and simulates a click. If the command is disabled (e.g. ghosted toolbar button), it fails. If successful, returns the explanation text of a the command issued (use MESSAGE $0 to see it).
CMENU name window number Simulate a context menu (right click) on the window last found, and find the menu command that corresponds to name. Returns the command identifier of the menu item found. Can be used for the shell context menu or any other background menu
WAITWND Wait till the active window changes, e.g. a new dialog window opens
WAITIDLE Wait till the active window finishes processing the last command.
WAIT period Wait a fixed amount of time in milliseconds (1000 = 1 sec). The argument may also be a window handle in a variable, where it behaves like WAITIDLE for that particular window.

ERRORSTOP 1/0 Turns the "resume on error" policy on/off (default is to stop on any error).
LABEL name This instruction doesn't do anything but marks the destination of a jump/goto instruction
GOTO label Unconditional jump to label name
JUMPOK label any Conditional jump to label name. Checks the result of last command and if it is failure/empty/0 then does nothing. So it only jumps if the last command was successful
EQUAL name any 0/1 Compares its argument with the last result. If the 2 values are compatible and equal, the result is 1, else 0
DECR $var $var-1 Decreases the variable ($1 - $9) by one and updates last result too. Used for loop control.
INCR $var $var+1 Adds 1 to a variable ($1 - $9) and updates last result too.
EXIT Stops execution; any instructions below this are ignored

MESSAGE name Pauses execution showing a message. Debugging aid mainly used to visualise the result of the last command as MESSAGE $0
ADDSTR name old old+ name Adds name to the old string result and then a newline. Intended for composing longer messages
REM any Comment line that doesn't do anything but explain something. For inline comments use #
INPUT prompt text Pops up an input dialog where you enter a string, which is then stored in the result. Prompt is used as the question to ask. Tip: use INPUT 0 to import the text from the clipboard.
STORE $var any Stores the last result in a variable $1 — $9 for future use
POP any =any Moves the constant or stored variable in the last result $0 register to be used in a subsequent command

Table 2. Macro instruction reference

Here's an example of a complex script that will show all the names in a listview control, demonstrating the use of some of the advanced instructions:

FINDWND "search results"
STORE $1 # listview (search result) window
GETCOUNT $2 # total items, process in reverse

LABEL loop
POP $1
SELECT $2
CMENU rename
WAIT 100 # for edit box to appear
FINDCLASS edit
GETTEXT $0
CANCEL
MESSAGE $0 
DECR $2
JUMPOK loop
To avoid the roundabout way to extract the item name through context menus, we could have used COMMAND 32798 which copies the entire path (ALT+C shortcut command). Or even more simply use the GETITEMTEXT instruction <g>

Licensing and registration

DeskRule is a "try before you buy" application. You can download and install it, then use it for free at full capacity for a limited time period. This way you can tell if it is the right tool for you before buying it. The longer you take to evaluate the more nags it will throw at you, including this nag dialog when you start it:

opening registration nag dialog
Figure 5. Registration prompt dialog

Click on Continue in trial mode to proceed. Eventually after a longish period of evaluation at full capacity, it will switch to restricted mode. After that the search engine will barely work: fast desktop search will be disabled and it will only show the first few search results. At this point really you should make up your mind, whether to purchase or uninstall.

DeskRule licensing is similar to xplorer², in that it is licensed per user. If you are the only user and have 2 computers, you only need one license key. But you must add a seat for each extra user. Your purchase will entitle you to free upgrades and support for one year (at minimum, perhaps longer). Click on the Secure online order button (see figure 5 above) to start the ordering process. All the usual payment methods are available.

Once you receive your key to your email address, click on I have an unlock key and start the license manager in full administrator mode. Copy/paste the long funny looking key (all of it) and you should be able to activate your DeskRule. From then on you can use the search engine at full speed without any nags whatsoever.


Miscellaneous

Software details
DeskRule runs on windows Vista or later (7/8/10 etc). The installer includes both 32 and 64 bit versions and installs the most suitable for your Windows system.

Customer support
If there is something that you cannot understand using this help file and the demo videos (there are a few under the HELP toolbar button), please contact email support. If you suspect any bugs (e.g. the program crashes) please use the Reliability command from the toolbar help drop-down menu, adding as much information as possible to help us reproduce the problem. You can also ask questions in the forum.

The demo videos play in any internet browser with an enabled shockwave flash (SWF) plugin. If your browser cannot play these demo videos, you either need to download the flash plugin or use the standalone flash player. Internet explorer and Edge browsers should already have this plugin installed, so if you are using some other browser, try IE for the demo videos.

Command line arguments
You can edit the shortcut icon properties (what you click to start the program) to add command line switches and arguments.

COMMAND LINE OPTIONS
/A disable assertion messages
/I use settings file (default=deskrule.ini)
/P run a new process
/F don't load filter used in last search
/G:name start a search with saved search filter name; if the saved search name doesn't exist, it performs a simple mode search for name
/J load all system properties without exclusions (1000+)
/C Print search results in a console window and exit (must be combined with /G)

A folder name can be passed to start the search where you want. Another way to pick the starting folder is to right click on it and pick Search with DeskRule command from the context menu.

Keyboard shortcuts
Many keyboard shortcuts appear next to the (context) menu commands, e.g. right click on some item or at the background of the file list view. Here are some other available commands (similar to xplorer²)

Key Function
Ctrl+A Select all
Alt+A Unselect all
Ctrl+C Copy
Ctrl+X Cut
Alt+Ret Properties
Ctrl+Ret Open selected item's container folder
Del Delete selection (real file delete)
Ctrl+Del Remove selection from pane (files not deleted)
Alt+C Copy selected path names
Ctrl+P Copy selected information (all columns and details)
Ctrl+Plus   Autosize columns
Ctrl+Q Toggle the preview pane on/off
F1 Displays this help file
F12 Program settings
F2 Rename
F3 View selected file as text
Ctrl+F (in the previewer pane) search for text; F3 to find next
F6 Move to next pane (Shift for previous)
F8 Clear search parameter fields
Tab Switch address/filter box (Shift for opposite direction)
also from rules to property control

Navigating around the window is achieved pressing <F6> key (or Shift+F6), that moves you to the four main areas: toolbar, search panel, search results and previewer pane. Within each area (e.g. search panel), pressing <TAB> key cycles in the locally available windows. Note that the property control is also very much keyboard happy.

To select multiple items use the middle mouse button. This toggles the selection status without affecting the selection of other items. Another solution is to hold down <Ctrl> key while selecting with the left mouse button.

While in the addressbar you can select folders previously searched typing part of their name then the <UP> arrow key.


© 2014-2017 ZabKat LTD, All Rights Reserved
zabkat.com