This guide contains the following sections:
visual accessory, generic fill-in-the-blank form, user input acquisition, computation user interface
The TopHat!™ program is used in conjunction with r4™ and
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.
| TopHat [/S] [formDefinitionFile] |
The /S option enables scrolling of the TopHat!™ window. This option is useful for small displays.
The contents of the form definition file are defined below.
There are six different types of lines within the form definition file. Empty lines are ignored.
|
! roo.exe
The above line executes roo!™ The default module is: r4.exe |
|
: 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 |
|
? 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.
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:
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.
The field definition line has four components, which are separated by commas. These are:
| 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. |
|
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.
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 |
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' |
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 ) |
; 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
/* 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
The buttons that appear differ based on the operating mode.
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.
If you use the same forms every day, you can have TopHat forms automatically displayed when you start your computer as follows:
Now the forms will automatically be displayed when your computer starts!
|
TopHat Bizzy.TopHat [opens the business calculation example]
|
TopHat!™ can be used with both r4™ and
set TOPHAT_PROGRAM_TO_EXECUTE=roo |
Observe: even though
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
|
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:
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.
