Configure User Tools

Contents  Previous  Next


Menu: Configure > User Tools


Default Shortcut Key: none


Macro function: ConfigureUserTools()


The Configure User Tools command is used to define and configure up to 24 external programs which can be run from the User Tools submenu on the Tools menu.  A variety of Tools Macros is available which makes it possible to control the information which is passed to the program being run.


A common use for a User Tool would be to send the name of the current file to an external program which processes the file in some way.   Examples of such programs are assemblers, compilers, grammar checkers, parsers, etc.




Use of the Configure User Tools dialog box is described below:



Name of this tool

Use this edit box to supply the name for the User Tool being defined.  The name supplied will appear in the User Tools submenu when definition is complete.  Up to 20 characters can be used.



Use this edit box to supply an optional description for the tool being defined.  This description will appear as a menu hint for the Tools | User Tools menu entry that corresponds to this tool.


Program, document, folder or URL

Use this edit box to supply the full filepath of the program which is to be run.  The button with the ellipsis (...) can be used to browse for and select the desired program.  If the program selected has an associated icon, it will be displayed to the right of the Name edit box.


Tools Macros can be placed into the Program field by clicking on the '$' button.  For example, you might use the $SelWord directive to pass the word at the cursor--or a short text selection--to a web-based resource that performs a search for that term.  The URL:$SelWord


would cause the word at the cursor to be sent to Google for search results.


bm2The $Sel and $SelWord directives are processed specially when used in a URL: any embedded spaces that might result from expansion are automatically converted to plus signs (+) to create a web-friendly URL.


Working Directory

Use this edit box to supply the working directory for the program being defined.  The working directory will become the current directory for the program being run.  The button with the ellipsis (...) can be used to browse for and select the working directory.


bm1The $Path Tools Macro (among others) can also be used in the Working Directory field as a means of specifying the working directory.


Command Line Parameters

The Command Line Parameters edit box is used to supply command line parameters to the program being defined.  These parameters might be option flags required by the program or any other such information.


Boxer will recognize several different Tools Macros in the Command Line Parameters edit box to pass information to the defined program.  When a macro appears in the Command Line Parameters field, it will be expanded to its equivalent text at the time the User Tool is run.


Clicking the ellipsis (...) button to the right of the edit box presents the Tools Macros list:




Macros are available to pass the current filepath, filename, extension and other portions of the filename.  The line and column number can also be passed, as can the word beneath the text cursor.  Selected text (or the first line of a multi-line selection) can also be passed.  If needed, two or more macros can be placed in the Command Line Parameters edit box.


bm2If it is anticipated that the file and/or path being passed to the User Tool might contain an embedded space, be sure to enclose the $Filepath directive in double quotes to ensure proper handling.


Before running this program...

Save current file

Use this option to save any changes in the current file before running the defined User Tool.  Be sure to use this option when defining a User Tool which will operate on the current file, so the program has access to the most recent changes you've made.


Save all modified files

Use this option to save any changes within all edited files before running the defined User Tool.


Minimize Boxer

Use this option to request that Boxer be minimized to the task bar while the User Tool is running.


Prompt for parameters

Use this option to request that Boxer prompt for parameters before running the defined program.  This option is useful when running a program whose command line parameter(s) must be determined according to other conditions and cannot be specified programmatically.


Convert '\'s in Parameters to '/'s

Use this option to request that any backslashes (\) within the Command Line Parameters edit box be converted to forward slashes (/) before running the defined program.


Pass short filename to program

Use this option to request that any Tools Macros used in the Command Line Parameters edit box be converted to short filenames before running the defined program.  This option is needed when defining a User Tool which passes a filename to a DOS program, or to a 16-bit Windows program, since these programs are typically unable to process long filenames.



Save Tool button

Use the Save Tool button to save the current tool definition.  Note that the current tool will also be saved automatically when moving to a new tool in the Tools list.


Clear Tool button

Use the Clear Tool button to clear the definition for the current tool.  No confirmation is required before the tool is erased.


Test Tool Button

Use the Test Tool button to simulate running the current tool, without actually executing the defined program or resource.  A dialog will appear showing the various fields, after the expansion of any Tools Macros and other requested conversions have been made.


Move up in list / Move down in list

Use these buttons to change the order in which tools appear in the User Tools submenu on the Tools menu.  Clicking on a button moves the currently selected User Tool up or down in the list.  Moving a User Tool up or down in the list does not cause a change in the shortcut key assignments, if any are in use.  For example: a shortcut key assigned to User Tool 2 remains assigned to the second tool in the list and does not travel with a tool which is moved through that position.


Tips and Notes

bm1The method by which Boxer runs a User Tool program makes it possible to define User Tools which are mapped to documents, rather than programs.  For example, if the 'program' to be run is defined to be an HTML document, then your Internet browser will be launched to display that file.  If a .DOC file is defined as the 'program' to be run, then Microsoft Word will be launched to display the document.  The browse button will present a file selection dialog box which defaults to showing .EXE and .COM files, so in order to locate documents it will need to be changed to show files of all types.


bm1The method described in the above Tip can also be used to create User Tools which map to your favorite directories. If a directory name is defined as the 'program' to be run, then Explorer will be launched with that directory in its view.  The browse button cannot be used to select a directory name, so in order to define a User Tool in this way, the directory name will need to be typed manually into the Program edit box.


bm1Some DOS programs issue an on-screen report but do not pause for user interaction or confirmation before terminating.  When such programs are run as User Tools, they will execute and terminate so quickly that their results cannot be studied.  You can remedy this behavior by making a change to the Properties of the program being executed.  Locate the program in Explorer, right-click on its icon, and select Properties.  Click the Program tab and uncheck the option titled Close on exit.  Click OK to save the change.  Thereafter, when the program is run, its window will not close until its close button is clicked.


bm2By default, Boxer is configured to present a warning message when a file it is editing is changed by another program or process.  This capability is especially useful when running User Tools since it confirms that a change was made and provides the opportunity to Reload the file from disk to get the latest copy.  If you will be running a User Tool which operates on the current file, this option should be kept in force.  The option is located on the Configure | Preferences | Messages option page, and is titled Warn when an edited file is changed by another program.


bm2If you are a user of one of the JP Software command processors and wish to specify a .BTM file as a User Tool, you may need to make a system configuration change before doing so.  To see if a change is required, create a .BTM file which performs some passive operation (such as DIR), and try to execute it by double clicking from within Explorer.  If the file executes properly, then the Windows shell is aware that .BTM files can be executed, and no changes are needed.  If the file does not run, then a change will be needed before a .BTM file can be run as a program in one of Boxer's User Tools.  JP Software has documented this configuration procedure in an information file on their website.  At the time of writing, this file could be found at: If the file is not found there, look in the Support section at


bm1Here's a tip for users of JP Software's 4DOS and/or 4NT command processors: If you would like to direct the error output from a DOS program to the Windows clipboard, you can make use of the clip: logical device to achieve this.  At the end of any Command Line Parameters which might be defined for a given User Tool, add the following: >&>! clip: This directive causes the  standard error stream to be placed on the Windows clipboard, overwriting the current clipboard content.  The clipboard can later be reviewed in Boxer or manipulated as required.