Using Tools

The tools menu provides easy access to external tools. It also has three predefined tools for programmers: an ASCII table, a grep tool and a calculator. The output of the external tools can be accessed through this menu as well.

The messages window

The output of the external utilities is redirected by the IDE and it will be displayed in the messages window. The messages window is displayed automatically, if an external tool was run. The messages window can also be displayed manually by selecting the menu item or by pressing the key. The messages window is shown in figure [fig:messages].

If the output of the tool contains filenames and line numbers, the messages window can be used to navigate the source as in a browse window:

1. Pressing or double clicking the output line will jump to the specified source line and close the messages window.

2. Pressing the space bar will jump to the specified source line, but will leave the messages window open, with the focus on it. This allows the quick selection of another message line with the arrow keys and jump to another location in the sources.

The algorithm which extracts the file names and line numbers from the tool output is quite sophisticated, but in some cases it may fail⁷.

Grep

One external tool in the Tools menu is already predefined: a menu item to call the grep utility ( or ). Grep searches for a given string in files and returns the lines which contain the string. The search string can even be a regular expression. For this menu item to work, the grep program must be installed, since it is not distributed with Free Pascal.

The messages window displayed in figure [fig:messages] in the previous section shows the output of a typical grep session. The messages window can be used in combination with grep to find special occurrences in the text.

Grep supports regular expressions. A regular expression is a string with special characters which describe a whole class of expressions. The command line in DOSor Linuxhas limited support for regular expressions: entering ls *.pas (or dir *.pas) to get a list of all Pascal files in a directory. *.pas is something similar to a regular expression. It uses a wildcard to describe a whole class of strings: those which end on ".pas". Regular expressions offer much more: for example [A-Z][0-9]+ describes all strings which begin with an upper case letter followed by one or more digits.

It is outside the scope of this manual to describe regular expressions in great detail. Users of a Linuxsystem can get more information on grep using man grep on the command line.

The ASCII table

The tools menu also provides an ASCII table (). The ASCII table can be used to look up ASCII codes as well as to insert characters into the window which was active when invoking the table.

To reveal the ASCII code of a character in the table, move the cursor onto this character or click it with the mouse. The decimal and hex values of the character are shown at the bottom on the ASCII table window.

To insert a character into an editor window either:

1. using the mouse, double click it, or,

2. using the keyboard, press while the cursor is on it.

This is especially useful for pasting graphical characters in a constant string.

The ASCII table remains active till another window is explicitly activated; thus multiple characters can be inserted at once. The ASCII table is shown in figure [fig:ascii].

The calculator

The calculator allows quick calculations without leaving the IDE. It is a simple calculator, since it does not take care of operator precedence, and bracketing of operations is not (yet) supported.

The result of the calculations can be pasted into the text using the keystroke. The calculator dialog is shown in figure [fig:calc].

The calculator supports all basic mathematical operations such as addition, subtraction, division and multiplication. They are summarised in table The IDE.

But also more sophisticated mathematical operations such as exponentiation and logarithms are supported. The advanced mathematical operations are shown in table The IDE.

Like many calculators, the calculator in the IDE also supports storing a single value in memory, and several operations can be done on this memory value. The available operations are listed in table The IDE

Adding new tools

The tools menu can be extended with any external program which is command line oriented. The output of such a program will be caught and displayed in the messages window.

Adding a tool to the tools menu can be done using the menu. This will display the tools dialog. The tools dialog is shown in figure [fig:otools].

In the tools dialog, the following actions are available:

New

Shows the tool properties dialog where the properties of a new tool can be entered.

Edit

Shows the tool properties dialog where the properties of the highlighted tool can be edited.

Delete

Removes the currently highlighted tool.

Cancel

Discards all changes and closes the dialog.

OK

Saves all changes and closes the dialog.

The definitions of the tools are written in the desktop configuration file. So unless auto-saving of the desktop file is enabled, the desktop file should be saved explicitly after the dialog is closed.

Meta parameters

When specifying the command line for the called tool, meta parameters can be used. Meta parameters are variables and they are replaced by their contents before passing the command line to the tool.

$CAP

Captures the output of the tool.

$CAP_MSG()

Captures the output of the tool and puts it in the messages window.

$CAP_EDIT()

Captures the output of the tool and puts it in a separate editor window.

$COL

Replaced by the column of the cursor in the active editor window. If there is no active window or the active window is a dialog, then it is replaced by 0.

$CONFIG

Replaced by the complete filename of the current configuration file.

$DIR()

Replaced by the full directory of the filename argument, including the trailing directory separator, e.g.

  $DIR('d:\data\myfile.pas')

would return d:\data\.

$DRIVE()

Replaced by the drive letter of the filename argument. e.g.

  $DRIVE('d:\data\myfile.pas')

would return d:.

$EDNAME

Replaced by the complete file name of the file in the active edit window. If there is no active edit window, this is an empty string.

$EXENAME

Replaced by the executable name that would be created if the make command was used. (i.e. from the ’Primary File’ setting or the active edit window).

$EXT()

Replaced by the extension of the filename argument. The extension includes the dot. e.g.

  $EXT('d:\data\myfile.pas')

would return .pas.

$LINE

Replaced by the line number of the cursor in the active edit window. If no edit window is present or active, this is 0.

$NAME()

Replaced by the name part (excluding extension and dot) of the filename argument. e.g.

  $NAME('d:\data\myfile.pas')

would return myfile.

$NAMEEXT()

Replaced by the name and extension part of the filename argument. e.g.

  $NAMEEXT('d:\data\myfile.pas')

would return myfile.pas.

$NOSWAP

Does nothing in the IDE; it is provided only for compatibility with Turbo Pascal.

$PROMPT()

Prompt displays a dialog box that allows editing of all arguments that come after it. Arguments that appear before the $PROMPT keyword are not presented for editing.

$PROMPT() can also take an optional filename argument. If present, $PROMPT() will load a dialog description from the filename argument. E.g.

$PROMPT(cvsco.tdf)

would parse the file cvsco.tdf, construct a dialog with it and display it. After the dialog closed, the information entered by the user is used to construct the tool command line.

See section The IDE for more information on how to create a dialog description.

$SAVE

Before executing the command, the active editor window is saved, even if it is not modified.

$SAVE_ALL

Before executing the command, all unsaved editor files are saved without prompting.

$SAVE_CUR

Before executing the command the contents of the active editor window are saved without prompting if they are modified.

$SAVE_PROMPT

Before executing the command, a dialog is displayed asking whether any unsaved files should be saved before executing the command.

$WRITEMSG()

Writes the parsed tool output information to a file with name as in the argument.

Building a command line dialog box

When defining a tool, it is possible to show a dialog to the user, asking for additional arguments, using the $PROMPT(filename) command-macro. The Free Pascaldistribution contains some ready-made dialogs, such as a ’grep’ dialog, a ’cvs checkout’ dialog and a ’cvs check in’ dialog. The files for these dialogs are in the binary directory and have an extension .tdf.

In this section, the file format for the dialog description file is explained. The format of this file resembles a windows .INI file, where each section in the file describes an element (or control) in the dialog. An OK and a Cancel button will be added to the bottom of the dialog, so these should not be specified in the dialog definition.

A special section is the Main section. It describes how the result of the dialog will be passed to the command line, and the total size of the dialog.

Title="Dialog title"

The Main section should contain the following keywords:

Title

The title of the dialog. This will appear in the frame title of the dialog. The string should be enclosed in quotes.

Size

The size of the dialog, this is formatted as (Cols,Rows), so

Size=(59,9)

means the dialog is 59 characters wide, and 9 lines high. This size does not include the border of the dialog.

CommandLine

specifies how the command line will be passed to the program, based on the entries made in the dialog. The text typed here will be passed on after replacing some control placeholders with their values.

A control placeholder is the name of some control in the dialog, enclosed in percent (%) characters. The name of the control will be replaced with the text associated with the control. Consider the following example:

CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"

Here the values associated with the controls named l, v, i, w and searchstr and filemask will be inserted in the command line string.

Default

The name of the control that is the default control, i.e. the control that is to have the focus when the dialog is opened.

The following is an example of a valid main section:

[Main]
Title="GNU Grep"
Size=(56,9)
CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"
Default="searchstr"

After the Main section, a section must be specified for each control that should appear on the dialog. Each section has the name of the control it describes, as in the following example:

[CaseSensitive]
Type=CheckBox
Name="~C~ase sensitive"
Origin=(2,6)
Size=(25,1)
Default=On
On="-i"

Each control section must have at least the following keywords associated with it:

Type

The type of control. Possible values are:

Label

A plain text label which will be shown on the dialog. A control can be linked to this label, so it will be focused when the user presses the highlighted letter in the label caption (if any).

InputLine

An edit field where a text can be entered.

CheckBox

A checkbox which can be in an on or off state.

Origin

Specifies where the control should be located in the dialog. The origin is specified as (left,top) and the top-left corner of the dialog has coordinate (1,1) (not counting the frame).

Size

Specifies the size of the control, which should be specified as (Cols,Rows).

Each control has some specific keywords associated with it; they will be described below.

A label (Type=Label) has the following extra keywords associated with it:

Text

the text displayed in the label. If one of the letters should be highlighted so it can be used as a shortcut, then it should be enclosed in tilde characters (~). E.g. in

Text="~T~ext to find"

the T will be highlighted.

Link

The name of a control in the dialog may be specified. If specified, pressing the label’s highlighted letter in combination with the key will put the focus on the control specified here.

A label does not contribute to the text of the command line; it is for informational and navigational purposes only. The following is an example of a label description section:

[label2]
Type=Label
Origin=(2,3)
Size=(22,1)
Text="File ~m~ask"
Link="filemask"

An edit control (Type=InputLine) allows entry of arbitrary text. The text of the edit control will be pasted in the command line if it is referenced there. The following keyword can be specified in a inputline control section:

Value

A standard value (text) for the edit control can be specified. This value will be filled in when the dialog appears.

The following is an example of an input line section:

[filemask]
Type=InputLine
Origin=(2,4)
Size=(22,1)
Value="*.pas *.pp *.inc"

A checkbox control (Type=CheckBox) presents a checkbox which can be in one of two states, on or off. With each of these states, a value can be associated which will be passed on to the command line. The following keywords can appear in a checkbox type section:

Name

The text that appears after the checkbox. If there is a highlighted letter in it, this letter can be used to set or unset the checkbox using the -letter combination.

Default

Specifies whether the checkbox is checked or not when the dialog appears (value on or off).

On

The text associated with this checkbox if it is in the checked state.

Off

The text associated with this checkbox if it is in the unchecked state.

The following is an example of a valid checkbox description:

[i]
Type=CheckBox
Name="~C~ase sensitive"
Origin=(2,6)
Size=(25,1)
Default=On
On="-i"

If the checkbox is checked, then the value -i will be added on the command line of the tool. If it is unchecked, no value will be added.