Difference between revisions of "Configure tools"

Latest revision as of 13:03, 2 August 2021

A user tool is a way for you to interact with other applications or programs on your system by executing a DOS or Windows command. You can configure up to 50 user tools - 25 standard tools and 25 Project tools. You can access and execute user tools in the Advanced tab in the User tools drop down. You can also add your tools to the ribbon or toolbars and map keyboard shortcuts to your tools. You can also use user tools in macros or scripts.

Clicking Configure tools opens the "Tool configuration" dialog, where you can create and delete tools. Here you can also configure tools, including defining the command line, setting parameters, configuring output handling, and setting options for interacting with the active file.

You can modify existing tools by selecting them from the list at the bottom of the dialog. The dialog also includes the following global buttons for adding / removing tools.

Insert
Creates a new tool and makes it active.

Copy
Creates a copy of the active / selected tool and makes it active.

Delete
Deletes the active / selected tool.

Your changes to tools are not saved until you click either the OK or Apply button in the "Tool configuration" dialog.

You can configure tools in the Command, Options, and Output tabs in the "Tool configuration" dialog. The settings for each tab are described below.

Command tab

Menu item name
This is the name of the tool and is shown in the user / project tool drop down as well as the tool list in the "Tool configuration" dialog.

Command line
This is the actual command line to be executed when the tool is run. The command line uses the same syntax as a DOS command prompt, however this field also supports a special placeholder syntax (described below) which allows variables, such as the active file's path and name, to be passed to the command line. You can use the Browse button to browse to and select an existing batch or cmd file.

Working directory
This is the active directory the tool and ensuing process will be launched in. You can use the Browse button to browse to and select an existing folder on your system.

For both the command line and working directory fields, the following placeholders are available.

All examples provided below are based upon a hypothetical file path D:\work\Dev Projects\Cycle One\some file.c.

Toolbar bitmap/icon (file path)
This field allows you to set the path to a bitmap, png, or icon file to be used in the ribbon, context menu, or toolbar for the tool. Use the Browse button to browse to and select the image file you'd like to use. The image will be scaled to fit in the ribbon or toolbar. If this isn't set, the default tool icon (with associated number) is displayed with the tool.

Options tab

Program type
You must define the program type as one of the following two options:

• DOS program (default)
  The "Command" field is launched in console mode, just as you would run a command in a DOS command prompt window. Most user tools will use this setting.
• Windows program
  The "Command" field is launched as a Windows executable program, just as if you were to double-click its icon in Windows explorer.

Save active file first
If checked, the active file is saved before the tool is run.

Save all files first
If checked, all open files are saved before the tool is run.

Output tab

Command output (DOS commands)
You can optionally capture the output from your DOS command user tool to a file. The four options for DOS command output are:

1. Append to existing
   Appends the tool output to the existing "Command Output" tool output file, or create the "Command Output" file if it does not yet exist.
2. Replace existing
   Replaces existing text with tool output in the "Command Output" tool output file, or create the "Command Output" file if it does not yet exist.
3. Create new file
   Always creates a new "Command Output" file for the tool output regardless of whether one already exists.
4. Output to list box
   Sends tool output to the output window.

Show DOS box
If checked, a DOS command prompt window is shown as tool's command is running, otherwise the DOS window will be hidden.

Capture output
If checked, output from the tool's command is captured and handled as configured elsewhere in this window, otherwise all output including standard, error, etc. is discarded.

Clear output before run
If checked, any data in the output window is cleared prior to the tool's command being executed.

Replace selected text with
You can choose what to do with the selection in the active file after the user tool is run. This is especially useful if you want to send a selection of text (a code procedure, a forumala, etc.) to an external process and have it reformatted or recalculated in some way. The three options are:

1. No replace
   The selection is left unaltered.
2. Captured output
   The selection is replaced with all output from the user tool.
3. Clipboard
   The selection is replaced with the clipboard contents after the tool completes execution.

Handle output as
This allows you to specify the encoding to use when displaying the output returned from the DOS command. These options don't actually convert the output, but allow you to configure which encoding UltraEdit / UEStudio uses to display the output. The three options are:

1. ANSI (Default, recommended for most cases)
   The user tool output is displayed as ANSI with your system's default code page.
2. UTF-8
   The user tool output is displayed as though it were UTF-8. This option is not recommended unless your external process specifically creates output as UTF-8. Otherwise, the output may look garbled or incorrect.
3. UTF-16
   The user tool output is displayed as though it were UTF-16. Additionally, this will cause the command prompt to be internally invoked with the "/u" flag, creating a Unicode (UTF-16) DOS command prompt before the command is run. This option is not recommended unless your external process specifically creates output as UTF-16. Otherwise, the output may look garbled or incorrect.