Kilowatt Software L.L.C.'s
TopHat!™
A generic fill-in-the-blank form accessory for use with r4™ programs

1 Index

This guide contains the following sections:

1.1 Categories:

visual accessory, generic fill-in-the-blank form, user input acquisition, computation user interface

1.2 Description:

The TopHat!™ program is used in conjunction with r4™ and roo!™ programs. There are two modes of operation: user input acquisition mode and computation mode. In user input acquisition mode, a REXX program is acquiring a series of input values from the user; such as, information for contacting other individuals. In computation mode, the user prepares a set of input values, and then performs a REXX program which prepares a set of output values. The computation of loan payment information is an example of a computation mode form.

In user input acquisition mode, TopHat!™ is started by a REXX program, and returns information to the program in the system registry.

In computation mode, TopHat!™ is started as an application as described in the usage section below. In this mode, T!opHat™ starts the associated REXX program when the perform button is pressed. Information is passed to the REXX program in the system registry, and the associated response is returned in the system registry.

TopHat!™ determines the mode of operation by analyzing the form definition's title line.

1.3 Usage:

1.4 Optional Arguments:

1.4.1 Form definition file format

There are six different types of lines within the form definition file. Empty lines are ignored.

1.4.1.1 User input acquisition mode form definition file example

The following is a complete example of a user input acquisition mode form definition file.

The form appears as follows:

The associated form definition file is:

When TopHat!™ is started to acquire contact information, initial values are received from the REXX program as registry values within the following registry key:

When the OK button is pressed input values are returned to the REXX program as registry values within the following registry key:

Note: you may have observed that the same registry value is used to receive information from the REXX program, and return it to the REXX program. This is correct for user input acquisition.

The following is the example REXX program that starts the contact information acquisition form.

1.4.1.2 Computation mode form definition file example

The following is a complete example of a computation mode form definition file. Four tabs are defined. Each tab performs a business calculation.

The form appears as follows:

The associated form definition file is:

When the perform button is pressed while the LoanCalc folder tab is activated, TopHat!™ communicates with the LoanCalc REXX program as follows:

Requests are passed to the REXX program as registry values within the following registry key:

Responses are received from the REXX program as registry values within the following registry key:

Note: you may have observed that different values are used to send information to the REXX program, and receive information from the REXX program. This is correct for computation mode.

The following is the example REXX program that performs the loan computations associated with the first form tab above.

1.4.1.3 Another computation mode form definition file example, metric conversions

The following is another example of a computation mode form definition file. The tabs provide a collection of metric to english measurement conversions.

This example shows two helpful concepts. First, some fields do not have captions. This introduces spacing between fields, which helps the user distinguish groups of conversions. Second, the output values are presented on the right side of the form area. This is accomplished by providing the appropriate number of empty input field captions after the last visible field. The total number of input fields in the left column is 16. For consistency, empty output fields are also defined, so the total number of output fields in the right column is also 16.

The example REXX programs that perform metric conversions have comment lines at the hidden input and output fields positions. You may find that this technique is helpful in your programs also.

The form appears as follows:

The associated form definition file is:

The following is the example REXX program that performs the MetricDistance computations associated with the first form tab above.

1.4.2 A TopHat form that uses roo!™ as the supporting executable module


1.4.2.1 QuadraticFormulaRoo.tophat


1.4.2.2 QuadraticFormula.rooProgram

1.5 Buttons

The buttons that appear differ based on the operating mode.

1.5.1 Buttons, user input acquisition mode:

1.5.2 Buttons, computation mode:

1.6 Adding a TopHat form to your startup menu

If you use the same forms every day, you can have TopHat forms automatically displayed when you start your computer as follows:

  1. Select `Settings` under the Microsoft `Start` button options.

  2. Select `Taskbar & Start menu...`

  3. Click the `Start menu` tab.

  4. Click the `Advanced...` button.

  5. Click `+` character in front of the `Programs` folder.

  6. Click the `Startup` folder.

  7. Right click in an empty area of the startup folder, and select `New`, move the mouse to select `Shortcut`.

  8. Click the browse button.

  9. Locate the TopHat.EXE program in your Kilowatt Software L.L.C. folder, then click the `Next` and `Finish` buttons.

  10. Right click the new shortcut, and select `Rename`. Then, give the shortcut the name of your list.

  11. Right click the new shortcut, and select `Properties`.

  12. Alter the `Start in:` value to be the folder that contains your form definition file.

  13. Edit the `Target:` line.

  14. Add the name of your form definition file after TopHat.EXE with an intervening space too.

Now the forms will automatically be displayed when your computer starts!

1.7 Examples:

1.8 TOPHAT_PROGRAM_TO_EXECUTE environment variable

TopHat!™ can be used with both r4™ and roo!™. Normally, the associated REXX program of a TopHat form is processed by r4™. The TOPHAT_PROGRAM_TO_EXECUTE environment variable can be assigned an alternate program to use. For example:

The above environment variable setting will use roo!™ to execute the program, instead of r4™.

Observe: even though roo!™ is used to execute the program, TopHat!™ will use registry keys that begin with:

1.9 Changing button captions and tips -- for languages other than English

Alternative TopHat!™ button captions can be specified. At the bottom of the form definition file, you can can provide a series of lines similar to the following:

Button caption definitions start in column 1. The word buttonCaption must be completely spelled that way, but character case is not significant. Each line must have at least two commas. The character case of the button name (i.e. perform) is not significant. The third value is shown on the button in the character case specified.

The new captions can have ampersands (&) to establish hot-key characters that are used with the Alt key.

To have a real ampersand appear put two in a row -- &&

Alternative button tips can also be specified. See the perform button definition above. The tip text follows the last comma on the line. For the perform button the tip text is:


Commas are not allowed in the tip text. If these are present the tip text is truncated where the comma appears.

1.10 Other remarks:

In computation mode you can add a little excitement to a form if it is used repeeatedly. After the perform button is pressed, the note at the top of the form can be updated with a random quip. The quip is displayed if a file named quips.dat is in the same directory as TOPHAT.EXE. An example quips file is distributed with the product. You can replace this with a file containing other quips. If the quips file is absent, the form tab's note remains displayed.


TopHat!™
Version 1.1
Copyright © 2001-2014
All Rights Reserved.
Web: http://www.kilowattsoftware.com/
E-Mail: support@kilowattsoftware.com

Last updated on: 4 Mar 2011