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:

- Description
- Usage
- Form definition file format
- User input acquisition mode form definition file example
- Computation mode form definition file example
- Another computation mode form definition file example, metric conversions
- A form that uses roo!™ as the supporting executable module
- Buttons
- Adding a TopHat!™ form to your startup menu
- TOPHAT_PROGRAM_TO_EXECUTE environment variable
- Changing button captions and tips -- for languages other than English
- Other remarks

## 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:

TopHat [/S] [formDefinitionFile]

## 1.4 Optional Arguments:

- /S .. enable scrollable window

  The /S option enables scrolling of the TopHat!™ window. This option is useful for small displays.

- formDefinitionFile .. a text file containing lines which define one or more forms. When the formDefinitionFile does not have a file extension, an implicit .TopHat is added.

  The contents of the form definition file are defined below.

### 1.4.1 Form definition file format

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

  Remark
When the first non-space character on the line is a semicolon, the line is ignored.

  Title
The title line is the first line of the form definition file, that does not begin with a semicolon, and is not empty. It is displayed as the caption of the TopHat!™ application. If the title begins with the word 'get' followed by a space, then TopHat!™ operates in user input acquisition mode. Otherwise, TopHat!™ operates in computation mode.

  Supporting executable module
When the first character on the line is an exclamation point (!), the remainder of the line identifies the executable module to invoke. For example:

! roo.exe The above line executes roo!™ The default module is: r4.exe

  Associated registry key base
When the first character on the line is a colon (:), the remainder of the line identifies the associated registry key base that is used to communicate with the executable module. For example:

: Software\Kilowatt Software\roo The above line indicates the registry key base is: HKEY_LOCAL_MACHINE\Software\Kilowatt Software\roo The default registry key base is: HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4

  Associated help file
When the first character on the line is a question mark (?), the remainder of the line identifies the help file associated with the TopHat!™ application. For example:

? KinematicEquations.htm The above line indicates the help file associated with the TopHat!™ application is: KinematicEquations.htm

Note: if a complete file name is not specified, the HTML file should be in the same directory as the TopHat!™ program. You can specify a full directory path of the HTML file, if it is in another directory, or on a different disk. You can also specify an internet URL for the HTML file.

  Form definition line
A line that does not have any leading spaces defines a form tab section. The form definition line is followed by one or more 'field definition' lines.

Note: there is only one form tab section when operating in user input acquisition mode.

The form definition line has three components, which are separated by commas. These are:

1. The name of the associated REXX program. Usually this will be unqualified, such as: LoanCalc.
   The program name is the last segment of the registry key, that is used to communicate with the REXX program.

2. The folder tab caption associated with this form definition.

3. A note to display at the top of the TopHat!™ application window, when the folder tab is activated.

The following is an example of a form definition line:

LoanCalc,LoanCalc,Loan calculator

In the above line, LoanCalc is the name of the associated REXX program and the folder tab caption. Loan calculator is the note that is displayed when the folder tab is activated.

  Field definition line
Lines with one or more leading spaces are field definition lines. Up to 32 fields can be defined per form.

The field definition line has four components, which are separated by commas. These are:

1. The field type, 'I' indicates an input field, 'O' indicates an output field.

2. The caption that appears to the left of the input or output field. The caption can include an ampersand ('&') before one of the characters. The associated character is displayed with an underline. The user can cause the cursor to jump to the associated input field by pressing the character while the Alt key is held down.

   Note: an empty caption is used to provide spacing, as used in the metric examples below. When the caption is empty, neither the caption field nor the associated text field are not displayed. Furthermore, the value of a skipped text field is not passed in request parameters. Likewise, the REXX program does not return a response for skipped output text fields. This simplifies the implementation of the REXX programs that interact with forms having skipped fields.

3. The default value associated with input fields. Optional values should use a single dash ('-').

4. A helpful tip that is displayed when the mouse passes over the field.

Note: If a component of a field definition line, or a form definition includes a comma, then the entire component should be enclosed in double-quotes. If it also includes a double-quote then the double-quote within the component value is specified twice. See the 'payment period' field definitions in the examples below.

The following is an example of a field definition line:

I,&Annual % rate,7,Enter annual interest rate of loan

In the above line, I indicates that this is an input field. The field's caption is '&Annual % rate'. The cursor will jump to the field when 'A' is typed while the Alt key is held down. 7 is the default value for the input field. Enter annual interest rate of loan is the tip that is displayed when the mouse passes over the input field.

#### 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:

; Contact.TopHat ; This defines the input fields associated with acquiring contact information ; The first line below begins with 'get' followed by a space, ; which indicates TopHat will operate in user input acquisition mode Get Contact Information ; the contact information tab -- the associated REXX program is: Contact Contact,Contact,Get Contact Information I,&Name,,Enter contact name I,&Address 1,,Enter 1st line of contact's address I,A&ddress 2,-,Enter 2nd line of contact's address I,&City,,Enter contact's city I,&State/Prov.,,Enter contact's state or province I,&Mail code,,Enter contact's zip code or mail code I,&Phone,,Enter contact's telephone number I,&E-mail,,Enter contact's e-mail address I,Alt. E-&mail,,Enter contact's alternate e-mail address I,&Date,,Enter date of last contact

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

HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4\Contact[Request]

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

HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4\Contact[Request]

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.

/* GetContact.rex this program obtains contact information via TopHat this program communicates with TopHat.EXE via the registry a tab delimited input value is acquired from registry value: HKLM\Software\Kilowatt Software\R4\Contact[Request] */ tab = d2c( 9 ) /* invoke TopHat with input file: Contact.TopHat */ revise = 1 /* 1 => revise provided input values */ request = '' /* => reset existing input values */ if revise then do /* provide input values */ name = 'John Doe' address1 = '11 Oak Street' address2 = '-' city = 'Pleasantville' state = 'ZW' country = 'USA' mailCode = '55555' phone = '999-555-1212' email = 'jdoe@bitbucket.com' emailAlt = 'johndoe@elsewhere.com' dateOfContact = '23 May 2001' /* prepare tab delimited TopHat input values request */ request = , name || tab , || address1 || tab , || address2 || tab , || city || tab , || state || tab , || country || tab , || mailCode || tab , || phone || tab , || email || tab , || emailAlt || tab , || dateOfContact end 'set R4REGISTRYWRITE=Y' /* enable registry writing */ call value "HKLM\Software\Kilowatt Software\R4\Contact[Request]", request, "Registry" trace off /* ignore error code when cancel is pressed */ 'TopHat Contact.TopHat' if rc <> 0 then /* cancel button was pressed */ exit 1 /* get TopHat input field values */ input = value( "HKLM\Software\Kilowatt Software\R4\Contact[Request]", , "Registry" ) /* parse tab delimited input field values */ parse var input , name (tab) , address1 (tab) , address2 (tab) , city (tab) , state (tab) , country (tab) , mailCode (tab) , phone (tab) , email (tab) , emailAlt (tab) , dateOfContact (tab) say 'Contact information:' say say left( 'Name', 20 ) name say left( 'Address1', 20 ) address1 say left( 'Address2', 20 ) copies( address2, address2 <> '-' ) say left( 'City', 20 ) city say left( 'State', 20 ) state say left( 'Country', 20 ) country say left( 'Zip/Mail code', 20 ) mailCode say left( 'Phone', 20 ) phone say left( 'E-mail', 20 ) email say left( 'Alternate e-mail', 20 ) emailAlt say left( 'Date of contact', 20 ) dateOfContact exit 0

#### 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:

; Bizzy.TopHat ; a set of business calculation forms ; The first line below DOES NOT BEGIN with 'get' followed by a space, ; which indicates TopHat will operate in computation mode Business calculations ; the loan calculation tab -- the associated REXX program is: LoanCalc LoanCalc,LoanCalc,Loan calculator I,&Down Payment,0,Enter down payment I,&Principal,0,Enter amount of loan I,&Annual % rate,7,Enter annual interest rate of loan I,"P&eriod (Mo, Yr)",Yr,Enter loan payment period; either Mo or Yr I,#Pe&riods,0,Enter number of payment periods O,Monthly payment,,Computed monthly payment O,Total payment,,Computed total payment over life of loan O,Total interest,,Total interest payed over life of loan O,Total expense,,Total expense including down payment ; the 'compound interest; calculation tab -- the associated REXX program is: CompVal CompVal,ComputeValue,Compute value of investment with interest compounded monthly I,&Principal,0,Enter amount of investment I,&Annual % rate,7,Enter annual interest rate of investment I,"P&eriod (Mo, Yr)",Yr,Enter payment period; either Mo or Yr I,#Pe&riods,0,Enter number of payment periods O,Present value,,Present value ; the 'present value' calculation tab -- the associated REXX program is: PresVal PresVal,PresentValue,Compute present value needed to have a future amount with interest compounded monthly I,&Future value,0,Enter future value desired I,&Annual % rate,7,Enter annual interest rate of investment I,"P&eriod (Mo, Yr)",Yr,Enter payment period; either Mo or Yr I,#Pe&riods,0,Enter number of payment periods O,Present value,,Present value needed ; the 'compounded annuity' calculation tab -- the associated REXX program is: AnnVal AnnVal,AnnuityValue,Compute final amount of an annuity with interest compounded monthly I,&Annual investment,0,Enter annual investment amount I,Annual % &rate,7,Enter annual interest rate of investment I,#&Years,0,Enter number of years O,Annuity value,,Final annuity value

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:

HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4\LoanCalc[Request]

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

HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4\LoanCalc[Response]

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.

/* LoanCalc.rex this program computes loan payment values this program communicates with TopHat.EXE via the registry a tab delimited request is received from registry value: HKLM\Software\Kilowatt Software\R4\LoanCalc[Request] a tab delimited response is returned in registry value: HKLM\Software\Kilowatt Software\R4\LoanCalc[Response] */ tab = d2c( 9 ) /* get TopHat request */ request = value( 'HKLM\Software\Kilowatt Software\R4\LoanCalc[Request]', , 'Registry' ) /* parse tab delimited request fields */ parse var request downPayment (tab) principal (tab) pctRate (tab) periodType (tab) nperiods /* compute loan payment values */ workingPrincipal = principal - downPayment interest = ( pctRate / 100 ) / 12 /* convert annual interest rate to monthly rate */ if translate( left( periodType, 1 ) ) = 'Y' then nperiods = nperiods * 12 /* #payments in a year */ x = ( 1 + interest ) ** nperiods monthly = ( workingPrincipal * x * interest ) / ( x - 1 ) monthlyPayment = trunc( monthly, 2 ) total = monthly * nperiods totalPayment = trunc( total, 2 ) totalInterest = trunc( total - principal, 2 ) totalExpense = trunc( total + downPayment, 2 ) /* prepare tab delimited TopHat response */ response = monthlyPayment || tab || totalPayment || tab || totalInterest || tab || totalExpense 'set R4REGISTRYWRITE=Y' /* enable registry writing */ call value 'HKLM\Software\Kilowatt Software\R4\LoanCalc[Response]', response, 'Registry'

#### 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:

; Conversions.TopHat ; a collection of conversion calculation forms ; The first line below DOES NOT BEGIN with 'get' followed by a space, ; which indicates TopHat will operate in computation mode Conversions ; the metric distance tab -- the associated REXX program is: MetricDistance MetricDistance,Distance,Distance metric conversions I,Inches,-, I,Feet,-, I,Yards,-, I,Miles,-, I,,-, I,Centimeters,-, I,Meters,-, I,Meters,-, I,Kilometers,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, O,Centimeters,-, O,Meters,-, O,Meters,-, O,Kilometers,-, O,,, O,Inches,-, O,Feet,-, O,Yards,-, O,Miles,-, O,,, O,,, O,,, O,,, O,,, O,,, O,,, ; the metric area tab -- the associated REXX program is: MetricArea MetricArea,Area,Area metric conversions I,Square inches,-, I,Square feet,-, I,Square yards,-, I,,-, I,Square centimeters,-, I,Square meters,-, I,Square meters,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, O,Square centimeters,-, O,Square meters,-, O,Square meters,-, O,,, O,Square inches,-, O,Square feet,-, O,Square yards,-, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, ; the metric volume tab -- the associated REXX program is: MetricVolumne MetricVolume,Volume,Volume metric conversions I,Cubic inches,-, I,Cubic feet,-, I,Cubic yards,-, I,,-, I,Fluid ounces,-, I,Quarts,-, I,Gallons,-, I,,-, I,Cubic centimeters,-, I,Cubic meters,-, I,Cubic meters,-, I,,-, I,Milliliters,-, I,Liters,-, I,Liters,-, I,,-, O,Cubic centimeters,-, O,Cubic meters,-, O,Cubic meters,-, O,,, O,Milliliters,-, O,Liters,-, O,Liters,-, O,,, O,Cubic inches,-, O,Cubic feet,-, O,Cubic yards,-, O,,, O,Fluid ounces,-, O,Quarts,-, O,Gallons,-, O,,, ; the metric weight tab -- the associated REXX program is: MetricWeight MetricWeight,Weight,Weight metric conversions I,Ounces,-, I,Pounds,-, I,,-, I,Grams,-, I,Kilograms,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, O,Grams,-, O,Kilograms,-, O,,, O,Ounces,-, O,Pounds,-, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, ; the metric temperature tab -- the associated REXX program is: MetricTemperature MetricTemperature,Temperature,Temperature metric conversions I,Fahrenheit,-, I,,-, I,Centigrade,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, I,,-, O,Centigrade,-, O,,, O,Fahrenheit,-, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,, O,,,

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

/* MetricDistance.rex this program converts metric distances -- CRC Handbook, p3 this program communicates with TopHat.EXE via the registry the corresponding TopHat form definition is: Metric.TopHat a tab delimited request is received from registry value: HKLM\Software\Kilowatt Software\R4\MetricDistance[Request] a tab delimited response is returned in registry value: HKLM\Software\Kilowatt Software\R4\MetricDistance[Response] */ tab = d2c( 9 ) /* get TopHat request */ request = value( 'HKLM\Software\Kilowatt Software\R4\MetricDistance[Request]', , 'Registry' ) /* parse tab delimited request fields */ parse var request , inches (tab) , feet (tab) , yards (tab) , miles (tab) , /* . (tab) , */ , centimeters (tab) , metersToFeet (tab) , metersToYards (tab) , kilometers (tab) /* initialize all output values to empty strings */ parse value '' with , o_centimeters , o_metersFromFeet , o_metersFromYards , o_kilometers , o_inches , o_feet , o_yards , o_miles /* compute values */ if inches <> '-' then o_centimeters = Trim( inches * 2.54 ) if feet <> '-' then o_metersFromFeet = Trim( feet * .3048 ) if yards <> '-' then o_metersFromYards = Trim( yards * .9144 ) if miles <> '-' then o_kilometers = Trim( miles * 1.609344 ) if centimeters <> '-' then o_inches = Trim( centimeters * .3937007874 ) if metersToFeet <> '-' then o_feet = Trim( metersToFeet * 3.280839895 ) if metersToYards <> '-' then o_yards = Trim( metersToYards * 1.093613298 ) if kilometers <> '-' then o_miles = Trim( kilometers * .6213711922 ) /* prepare tab delimited TopHat response */ response = , o_centimeters || tab , || o_metersFromFeet || tab , || o_metersFromYards || tab , || o_kilometers || tab , /* || '' || tab , */ , || o_inches || tab , || o_feet || tab , || o_yards || tab , || o_miles || tab 'set R4REGISTRYWRITE=Y' /* enable registry writing */ call value 'HKLM\Software\Kilowatt Software\R4\MetricDistance[Response]', response, 'Registry' exit 0 Trim : procedure parse arg before '.' after if after = '' | after = '0' then return before return arg( 1 )

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

## 1.4.2.1 QuadraticFormulaRoo.tophat

    ; QuadraticFormulaRoo.TopHat

    ; calculates the roots of a quadratic equation
    ; such as: 5 x^2 + 15 x + 10 = 0

    ; The first line below DOES NOT BEGIN with 'get' followed by a space,
    ; which indicates TopHat will operate in computation mode

    Quadratic formula

    ; the supporting executable module is 'roo.exe'

    ! roo.exe

    ; the associated registry key base is: Software\Kilowatt Software\roo (in HKEY_LOCAL_MACHINE)

    : Software\Kilowatt Software\roo

    ; the quadratic formula tab -- the associated roo program is: QuadraticFormula.rooProgram

    QuadraticFormula,QuadraticFormula,Quadratic formula; such as: 5 x^2 + 15 x + 10 = 0
     I,&A,1,Enter coefficient A -- in a x^2 + b x + c = 0
     I,&B,-,Enter coefficient B -- in a x^2 + b x + c = 0
     I,&C,-,Enter coefficient C -- in a x^2 + b x + c = 0
     O,Root #1,,1st computed root
     O,Root #2,,2nd computed root

## 1.4.2.2 QuadraticFormula.rooProgram

    /* QuadraticFormula.rooProgram
     this program computes roots of a quadratic equation

     this program communicates with TopHat.EXE via the registry

     a tab delimited request is received from registry value:
      HKLM\Software\Kilowatt Software\roo\QuadraticFormula[Request]

     a tab delimited response is returned in registry value:
      HKLM\Software\Kilowatt Software\roo\QuadraticFormula[Response]
    */

    tab = d2c( 9 )

    -- get TopHat request

    request = value( "HKLM\Software\Kilowatt Software\roo\QuadraticFormula[Request]", , "Registry" )

    response = '?' || tab || '?'

    'set ROOREGISTRYWRITE=Y'   /* enable registry writing */

    call value "HKLM\Software\Kilowatt Software\roo\QuadraticFormula[Response]", response, "Registry"

    -- parse tab delimited request fields

    parse var request a (tab) b (tab) c

    if \ datatype( a, 'Number' ) then
      call usage1 'a' a

    if \ datatype( a, 'Number' ) then
      call usage2 'b' b

    if \ datatype( a, 'Number' ) then
      call usage3 'c' c

    call quadraticRoots a b c

    -- prepare tab delimited TopHat response

    response = root1 || tab || root2

    call value "HKLM\Software\Kilowatt Software\roo\QuadraticFormula[Response]", response, "Registry"

    return 0

    -- 'quadraticRoots' procedure
    -- find the roots of a quadratic equation

    quadraticRoots  :  procedure expose root1 root2
      parse arg a b c

      if a = 0 then
        call usage2 'The first coefficient of a quadratic equation is 0 (invalid).'

      twoA = a * 2

      subterm = ( b * b ) - ( 4 * a * c )

      subtermSign = sign( subterm )

      subterm = abs( subterm )

      subroot = squareroot( subterm )

      if subtermSign <> -1 then
        root1 = ( subroot - b ) / twoA
      else
        root1 = ( 0 - b ) / twoA '+' ( subroot / twoA ) 'i'

      if subtermSign <> -1 then
        root2 = ( 0 - ( subroot + b ) ) / twoA
      else
        root2 = ( 0 - b ) / twoA '-' ( subroot / twoA ) 'i'

      return

    usage1  :  procedure
      parse arg which v
      'msgbox' 'Value' which 'is non-numeric. It''s' v
      exit 99

    usage2  :  procedure
      'msgbox' arg(1)
      exit 99

## 1.5 Buttons

The buttons that appear differ based on the operating mode.

### 1.5.1 Buttons, user input acquisition mode:

  OK
Conclude and return input field values to the REXX program.

  Print
Prints item values.

  Reset
Resets all input fields to default values.

  Close
Concludes program operation, without returning input field values to the REXX program

### 1.5.2 Buttons, computation mode:

  Perform
Performs a REXX computation, and optionally displays results in the corresponding output fields. When the form contains input fields, the Perform button is disabled until all fields have a value. The Perform button is always enabled when there are no input fields.

  Print
Prints item values.

  Reset
Resets all input fields to default values.

  Close
Concludes program operation.

  Interactive (option check box)
When checked, the REXX program can interact with the user. When unchecked, the REXX program is executed invisibly, and user interactions are not supported.

Normally the computations performed by the REXX program are based on the input field values only, and no user interaction is necessary. When developing a REXX program you may need to activate the interactive trace facility, in which case the 'Interactive' option must be checked.

  Stay on top (option check box)
When checked, the TopHat form will remain visible when other applications are activated.

## 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:

TopHat Bizzy.TopHat [opens the business calculation example] TopHat Metric.TopHat [opens the metric conversion example] TopHat [uses a file search dialog to find the form definition file] r4 GetContact [performs contact information acquisition with Contact.TopHat form]

## 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:

      set TOPHAT_PROGRAM_TO_EXECUTE=roo

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:

HKEY_LOCAL_MACHINE\Software\Kilowatt Software\R4

## 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:

buttonCaption,ok,Done buttonCaption,perform,Do it!,Press this button to prepare output values. buttonCaption,print,List buttonCaption,reset,Clear buttonCaption,close,Adios buttonCaption,interactive,Dynamic buttonCaption,stayontop,&Stay buttonCaption,help,Help?

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:

Press this button to prepare output values.

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-2007
All Rights Reserved.
Web: http://www.kilowattsoftware.com/
E-Mail: support@kilowattsoftware.com

Last updated on: 27 Sep 2006