Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / genapps / hp22dc.arj / REFGUIDE / COMMANDS.TXT < prev next >

Wrap

Text File | 1991-05-16 | 80KB | 2,473 lines

________________________________________________________________________ Chapter 11: Commands 99 ________________________________________________________________________ CHAPTER ELEVEN: COMMANDS This chapter provides an alphabetical listing of all the commands available in PADtalk. Each command is described in detail, its syntax is given and examples are offered. Command: Description: ----------------------------------------------------------------------- add Add to a container answer Ask a question with buttons as choices ask Ask a question, allowing user to type response close Close a file convert Convert date and time data to a different format delete Delete a chunk from a container dial Dial a number with a modem divide Divide a container by an amount do Execute an expression as a statement edit script Edit the script of a HyperPAD object find Find text somewhere in your pad flushCache Write changed pages from memory to disk fxShow Execute the Show Partner F/X runtime get Put an expression into the local variable "it" global Declare a global variable go Change to another page, background, or pad hide Hide an object hilite Highlights text in a field multiply Multiply a container by an amount noSound Turn the speaker off (from sound or play) play Play music in the background playBack Play back previously recorded keystrokes pop page Change to a previously saved page print Print information from a pad ________________________________________________________________________ Chapter 11: Commands 100 ________________________________________________________________________ Command: Description: ----------------------------------------------------------------------- push page Save a page for later recovery using pop put Copy information to a container query Create a subset of pages based on criteria read Read chunks from a file record Record keystrokes for later playback run Run another program send Send a message to another object set Modify object properties setDefaultPopupColors Sets the popup colors to the default SetPopupColors Sets the colors used to display popups show Make an object visible sort Sort the pad sound Turn the speaker on a a particular frequency subtract Subtract an expression from a container visual Set up an effect for the next page change wait Wait some number of miliseconds write Write text to a file ----------------------------------- ADD Syntax: add <expression> to <destination>; Purpose: The add command adds the value of the expression to the value of the destination and places the result into the destination. The <expression> must evaluate to a number or be a container holding a number. The <destination> must be a container. Note: You will receive a runtime error if either the <expression> or the <destination> is not a number. Examples: add 5 to page field 23; add 45.67 to word 2 of page field 1; ________________________________________________________________________ Chapter 11: Commands 101 ________________________________________________________________________ ----------------------------------- ANSWER Syntax: answer question [with <button1> [,<button2> [,<button3>]]]; Purpose: The answer command allows you to create dialog boxes that ask a question. The user responds by choosing one of the buttons supplied. The dialog box is similar to other HyperPAD dialog boxes and is always centered on the page. You can specify up to 3 buttons to choose from. The Answer dialog box looks like this: ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ **** The Printed Documentation has a picture or screen shot here **** │ │ │ └───────────────────────────────────────────────────────────────────────┘ The <question> is the text within the dialog box. The text can be many lines long, in which case it is word-wrapped. Use carriage returns to improve the readability of your messages. The user can choose one of up to three buttons you supply in <button1>, <button2>, <button3>. If you don't specify any buttons to choose from, HyperPAD uses the two default buttons: <<Ok>> and <Cancel>. When the user accesses the dialog box, it remains on-screen until a choice is selected. After the user responds, either by selecting a choice or pressing ESC, the dialog box is removed and the selected button text is placed into the local variable it. For example, if the user selects <<Ok>>, it will contain "Ok". If the user selects <Cancel>, it will contain "cancel". If the user presses ESC, then the variable it will be empty. ________________________________________________________________________ Chapter 11: Commands 102 ________________________________________________________________________ Examples: answer "Ok to quit?"; answer "Continue printing?" with "Yes","No"; answer "What color?" with "red","blue","green"; answer "Error printing!" with "Ok"; The following handler asks the user if it is Ok to quit: handler cancel; begin "Ok to quit?" with "Yes","No"; if it is "Yes" then quit; end; See Also: ask ----------------------------------- ASK Syntax: ask question [with <default response>]; Purpose: The ask command allows you to gather information from the pad's user by creating a dialog box in which the user types a response. The Ask dialog box presents a question as a prompt, a text box in which to type a response, and <<Ok>> and <Cancel> buttons. ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ **** The Printed Documentation has a picture or screen shot here **** │ │ │ └───────────────────────────────────────────────────────────────────────┘ When the user presses the <<Ok>> button, the response is put in the local variable it. If there is no response, or <Cancel> is selected, the local variable it will be empty. ________________________________________________________________________ Chapter 11: Commands 103 ________________________________________________________________________ If you supply a default answer, it is presented in the text box as the default response. Then, when the user begins typing in a different response, the proposed answer is replaced by the typed one. Note: You cannot change the proposed buttons in the Ask dialog box. They will always be Ok and Cancel. Examples: ask "What is your name?"; The following uses ask to go to the page that the user specifies. If the user cancels the dialog box, the process stops: handler select; begin while true do begin ask "Go to which page?" with currentPage + 1; if it is empty then exit; go to page it; end; end; See Also: answer ----------------------------------- CLOSE Syntax: close <file number>; Purpose: The close command closes a previously opened file. All files must be closed after you are finished with them. (You can open a file using the create and open functions.) Examples: close fh; The following example writes the contents of field 1 to a file: put create("data.dat") into fh; write field 1 to fh; close fh; Note: This command sends the close message. See Also: create, open, read, write ________________________________________________________________________ Chapter 11: Commands 104 ________________________________________________________________________ ----------------------------------- CONVERT Syntax: convert container to <format> [and <format>]; convert var1 to seconds; convert var1 to dateItems; convert var1 to [long | short | abbreviated] date; convert var1 to [long | short] time; convert var1 to [long | short | abbreviated] date and [long | short] time; Purpose: This command converts dates to different formats. The range of dates HyperPAD understands starts from Saturday, January 1, 1583 -- the starting date of the Gregorian Calendar. Using convert, you can input a numerical date, like "5/8/90", and translate it to written form, like "Tuesday, May 8, 1990". The following are explanations of target formats using January 1, 1990 at 5:00:00 PM as an example. Date Format: Example: ----------------------------------------------------------------- date (same as short date) 1-1-90 The dash (-) is the only date separator output by convert long date Monday, January 1, 1990 abbreviated date Mon, Jan 1, 1990 seconds 12843766800 The number of seconds since 1-1-1583 time 5:00 PM long time 5:00:00 dateItems 1990,1,1,17,0,0,2 (year, month, day, hour, minute, second, day of week) ________________________________________________________________________ Chapter 11: Commands 105 ________________________________________________________________________ Container formats: The power of convert is derived from the flexible representation of the container being converted. The following are allowed: 1. Both the dash and slash (-,/) can be used as date separators. 2. Date item lists can be modified creating an invalid date and then normalized by converting it to another format. The following example modifies the dateItems list to figure out the date 40 days from today: get the seconds; --get today's date and time convert it to dateItems; --convert to date item list add 40 to item 3 of it; --add 40 days convert it to longDate; --normalize answer "40 days from now is" && it; The next example modifies the dateItems list to figure out what the date and time will be 18 hours from now: get the seconds; --get today's date in seconds convert it to dateItems; --convert to date item list add 18 to item 4 of it; --add 18 hours convert it to longDate and time; --normalize answer "18 hours from now is" && it; 3. The formats that you can convert from are loose. The following are suitable formats for convert: Example: Format: ----------------------------------------------------- Jan 1, 1990 date January 1, 1990 date Jan 1, 90 date Jan 1, 1990 11:20 date and time Mon, Jan 1, 90 11:20 AM date and time 11:20 time 11:20 PM time 11:20 Jan 1, 1990 time and date 11:20 Mon, Jan 1, 1190 time and date 65 seconds 1990,1,1,17,00,2 dateItems ________________________________________________________________________ Chapter 11: Commands 106 ________________________________________________________________________ Examples: This function returns the day of the week of the first day of the current month: function firstDay; begin get the date; convert it to dateItems; --represent as date items put 1 into item 3 of it; -- put 1 as day of the month convert it to long date; -- convert to string return word 1 of it; -- return day of week end; This handler computes tomorrows date: handler tomorrow; begin get the seconds; add 60 * 60 * 24 to it; convert it to long date; answer "Tomorrows date is" && it; end; Comments: The following months and days of the week and their abbreviations are recognized by HyperPAD: Keyword: Abbreviation: ------------------------------------------ january jan february feb march mar april apr may may june jun july jul august aug september sep october oct november nov december dec ________________________________________________________________________ Chapter 11: Commands 107 ________________________________________________________________________ Keyword: Abbreviation: ------------------------------------------ sunday sun monday mon tuesday tue wednesday wed thursday thu friday fri saturday sat See Also: time, longTime(), seconds(), date(), longDate() ----------------------------------- DELETE Syntax: delete <chunk> from <container>; delete <container;> Purpose: The delete command can be used to remove a chunk of information, or all the information from a container. The number of characters removed from the container is specified by using a chunking expression involving items, words, lines or characters (see the section on Chunking). If you do not specify a chunk to be deleted, HyperPAD will delete all of the characters in the container. For example: delete page field 1; delete salesTax; Chunks are defined by the characters that are around them. When you delete items and lines from a container, you also remove the delimiter (either a comma or carriage return) that defines it. For example, deleting a line from a field would delete the carriage return at the end of the line (if there is one). The following example deletes items from a field. Suppose field 1 contains "Jim, John, Sally, Lisa". The following statement: delete item 2 to 3 of field 1; results in field 1 containing "Jim, Lisa". Note that "John, Sally," was deleted, including the commas. ________________________________________________________________________ Chapter 11: Commands 108 ________________________________________________________________________ When to use it: When you want to remove a specific part of a container's value while keeping the rest intact. Examples: delete myvar; delete page field 5; -- removes all chars in page field 5 The following example deletes the current line from page field 1: get the currentLine of page field 1; delete line it from page field 1; The next example deletes all of the lines that contain the word "BAD". Care is taken to make sure that the loop is performed the correct number of times because the number of lines change as we delete lines: put the number of lines of page field 1 into numlines; put 1 into i; while i numlines do begin if line i of page field 1 contains "BAD" then begin delete line i of page field 1; subtract 1 from numlines; end else add 1 to i; end; ----------------------------------- DIAL Syntax: dial [pulse | tone | noHayes] <number> [with <modem commands>]; Purpose: With dial, you can call any telephone number (using a modem) for voice communication. Specify pulse or tone dialing, depending on your phone service (the default is pulse). While dialing, you are presented with a message, indicating that dialing is in progress If the dial is successful, a dialog box will be displayed requesting that you pick up the phone. The modem will remain connected until this dialog box is removed (by selecting the <<Ok>> button). The dial command performs the following steps when dialing the phone: 1. The modem port is initialized using the current settings of the global properties modem, dataBits, stopBits, parity, and baud. ________________________________________________________________________ Chapter 11: Commands 109 ________________________________________________________________________ 2. The modem is initialized using the Hayes modem command "ATV1E0", causing the modem to echo responses to HyperPAD. HyperPAD waits for the modem to respond "Ok". 3. The <expression> is prefixed with "ATDP" or "ATDT" depending on if you specified tone or pulse. Specifying <modem commands> replaces this default prefix with your own. For example, the following dial commands are the same: dial "5551212" with "ATDT"; dial tone "5551212"; 4. The <expression> is ended with a semi-colon and a carriage return. 5. The Progress box is displayed and the new expression is sent to the modem. 6. When the number has completed dialing, a dialog box is displayed indicating that it is Ok to pick up the phone. 7. After you select the <<Ok>> button from this dialog box, the text "ATH0" is sent to the modem and HyperPAD waits for the modem to respond "Ok". If dial is unsuccessful, you will receive an error message . This error is not a normal runtime error, however, and will not stop execution of your script. You can determine if an error occurred by using the result() function. The result() will be the text "not dialed" if there was an error, or empty if the dial was successful. If you have a Hayes incompatible modem, you can use the noHayes option to dial the phone. In this case, HyperPAD will not send any modem commands to your modem. The dial command performs the following steps: 1. The modem port is initialized using the current settings of the global properties modem, dataBits, stopBits, parity, and baud. 2. If you specified <modem commands>, HyperPAD will prefix it to <expression>. 3. HyperPAD sends the new expression to the serial port. HyperPAD will not wait for a response; it will return immediately. For example: dial nohayes "5551212"; dial nohayes "D 5551212;" & return; The nohayes option is also useful to initialize your serial port. ________________________________________________________________________ Chapter 11: Commands 110 ________________________________________________________________________ The following example uses dial to initialize the COM1 port to 1200,N,8,1: set the modem to "com1"; set the baud to 1200; set the parity to "none"; set the stopBits to 8; set the dataBits to 1; dial nohayes empty; Examples: dial "315-463-1234"; dial "315-463-1234" with "ATZ"; dial pulse "9,18002341624"; if result() is "not dialed" then answer "Can't dial the phone"; The following example prompts for a number, then dials it. Special care is taken to check for an area code enclosed in parenthesis. This means that the number is long distance and should be preceded by a 1. ask "Number to dial:"; if char 1 of it is "(" then begin -- get rid of parenthesis get substitute(it,"(",""); get substitute(it,")",""); -- long distance put 1 before it; end; get substitute(it," ",""); dial it; if the result is not empty then answer "Error dialing the phone!"; Note: The serial port is not initialized until you issue the dial command. See Also: baud, parity, stopBits, dataBits, modem ________________________________________________________________________ Chapter 11: Commands 111 ________________________________________________________________________ ----------------------------------- DIVIDE Syntax: divide <destination> by <expression> Purpose: The divide command divides <destination> by <expression> and places the result back into <destination>. The <expression> must be a number or a container holding a number. The <destination> must be a container. Note: You will receive a runtime error if either the <destination> or the <expression> is not a number. Examples: divide page field 23 by 4; divide salesTax by 0.07; ----------------------------------- DO Syntax: do <expression> Purpose: The do command compiles and executes the <expression>. This command provides a mechanism for executing statements from within a handler that haven't been compiled. The do command executes statements the same way as the message box. Thus, you can use the do command to evaluate expressions, putting the result into the message box. The following example puts the result of a calculation into the message box: do "3 + 4 - " && page field 1; You can only execute one command at a time. Thus, the <expression> can contain many statements. The do command must compile the specified statement, which may cause a slight delay in your script execution. The compiler must be located in the disk file "HPAD2.OVL", which must be accessible for this command to work. ________________________________________________________________________ Chapter 11: Commands 112 ________________________________________________________________________ Examples: do "go to the next page"; answer "Go where" with "next","previous"; do "go to" && it && "page"; The following statements execute the contents of field 1: do page field 1; ----------------------------------- EDIT SCRIPT Syntax: edit [the] script of <object>; Purpose: This command is used to edit the script of different objects. This is the same as selecting the object's Info dialog box and selecting the <Script...> button. Examples: edit the script of page "Preferences"; edit the script of page button 3; edit the script of background "Template"; edit the script of pad; ----------------------------------- FIND Syntax: find [part | whole] <expression> [in <field>]; Purpose: The find command locates text anywhere in your pad. If you restrict the search to a single background field, only text on any page in that field will be locate. If you don't restrict the search to a particular background field, find will locate text in any field in your pad. (The find command will not locate text on the painting layer of the page or background.) HyperPAD searches differently for a part than it does for a whole. The whole option tells HyperPAD to locate only whole words; that is, only occurrences that are enclosed by word delimiters (such as spaces, end of ________________________________________________________________________ Chapter 11: Commands 113 ________________________________________________________________________ lines, and punctuation) will be found. The part option tells HyperPAD to locate the text anywhere, even if it occurs within another word. For example, consider a field containing "John is a lawyer". The following statement will not find a match: find whole "law"; The next statement, however, will find a match: find whole "is"; Using find part, HyperPAD will find occurrences anywhere within the target text, even if the expression occurs within a word. For example, consider the same text "John is a lawyer". The following statement will find a match: find part "law"; Up to 10 strings can be specified. If more than one is given, find will locate any of the expressions in the destination. For example: find whole "john","joe","jack" After finding an occurrence, the user can press ENTER to search for the next instance of the string. If the user presses ENTER, the search begins on the current page where the previous find left off. If the user presses any other key, the search is terminated. If find locates a match within a locked field, you are taken to the page containing the match and the focus is set to the default object (because a locked field cannot receive the focus). If the user presses ENTER to locate the next match, the search begins on the next field after the locked one. If you use find from the message box, the Find in Progress box is displayed while HyperPAD searches; two beeps will sound if no matches are found. If you execute find from a script, the Find in Progress box and beeps won't occur. Determine the result of the find command using the result() function. If the find is successful, result will return "found". Otherwise, result will return "not found". Examples: To find John anywhere in the pad: find "John"; ________________________________________________________________________ Chapter 11: Commands 114 ________________________________________________________________________ To find John in the "first name" field: find "John" in field "First Name"; The following button handler locates the next occurrence of the highlighted text. If the user hasn't highlighted any text, the Ask dialog box will appear and ask for something to find: handler select; begin get the selectedText; if it is empty then ask "Find What?"; if it is empty then exit; find it; if the result is "not found" then answer "Can't find" && it with "Ok"; end; ----------------------------------- FLUSHCACHE Syntax: flushCache; Purpose: This command writes to disk all of the pages in memory that have been changed and empties the cache. Internally, HyperPAD keeps recently accessed pages in an area of the memory called the cache. When the cache becomes too large to fit in the memory, a page that hasn't been used in a long time is removed from the cache and written to disk. When to use it: Anytime you need more free memory for a particular operation, use this command. Also, use flushCache to prevent thrashing. (Thrashing is the constant disk access that occurs when the cache is full. For each new page read from the disk, a page must be written out.) Examples: flushCache; The following example frees up the maximum amount of memory before cycling through all of the pages in a pad: flushCache; for i = 1 to the number of pages do go to page i; Note: This command sends the flushCache message. The cache is flushed when the message is received by HyperPAD. See Also: maxDirtyPages, autoSave ________________________________________________________________________ Chapter 11: Commands 115 ________________________________________________________________________ ----------------------------------- FXSHOW Syntax: fxshow <fileName>; Purpose: This command is used to display images or screen shows from within HyperPAD. The fxshow command requires an external file called FXSHOW.EXE. The <fileName> parameter is the DOS filename of the .PRO, .PR2, .SLD, or .GX2 file you want to view. When HyperPAD loads for the first time, HyperPAD looks for the file FXSHOW.EXE in the same directory as HPAD.EXE. If the file is found, you will see an additional credit message displayed at the bottom of the screen informing you that fxshow is available. You cannot use the fxshow command if FXSHOW.EXE is not located in this directory. The fxshow command causes HyperPAD to shrink down to 3K and run the program FXSHOW.EXE, passing it information about what files to load. Refer to Appendix 4, "Support for Show Partner F/X" for more information. When running the show, HyperPAD does the following: 1. Switches to the directory containing <fileName>. 2. If no extension is specified, searches for files in this order: *.PRO, *.PR2, *.SLD, *.GX2. 3. Issues the suspend message to run FXSHOW.EXE. 4. Runs the show. 5. Returns control to HyperPAD. This is very similar to running a program with the run command, except that HyperPAD first changes to the directory containing the files you run. Examples: fxshow "sample"; fxshow "C:\FX\SAMPLE\SAMPLE"; fxshow "d:\pics\*.gx2"; Note: This command sends the fxshow message. The handler for this message is implemented in HyperPAD. ________________________________________________________________________ Chapter 11: Commands 116 ________________________________________________________________________ ----------------------------------- GET Syntax: get <expression>; Purpose: Use get to retrieve a value and put it into the local variable it. The <expression> can be a constant, a literal, a function, or a container (the value of a variable, a field's contents, or the contents of the message box). Examples: get 1 + 2 * 3; get field 1 of page 25; get word 1 to 5 of line 6 of field id 2 of page 88; Using the local variable it will enhance script readability and execution speed, as shown in the following example: get the selectedText; if it is empty then ask "What do you want to find?"; if it is empty then exit; find it; See Also: put ----------------------------------- GLOBAL Syntax: global <var1> [<var2>,...]; Purpose: The global statement allows you to declare a global variable. A Global variable is accessible to all handlers, not just the handler in which it is defined. Global variables remain until you exit HyperPAD or run another program. Note: The global command cannot be used in a do command or in the message box. When to use it: If you want a particular variable to maintain its value between handlers or pads, you must define it as a global variable. Examples: global taxAmount,salesAmount,userName; ________________________________________________________________________ Chapter 11: Commands 117 ________________________________________________________________________ ----------------------------------- GO Syntax: go [to] [pad] <padName> [with diskChange <expression>]; go [to] <background> [of [pad] <padName> [with diskChange <expression>]]; go [to] <page> [of <background>] [of [pad] <padName> [with diskChange <expression>]]; go back; go help; go home; Purpose: The go command changes to another page, background or pad. The destination indicates which page (and if necessary, which pad) will be displayed. If the destination specifies only a pad, HyperPAD goes to the default page (the page which was last accessed) of that pad. You can alter the destination by supplying a container as the destination. The diskChange option allows you to specify that the destination pad may be on a different disk. In this case, the user will be asked to switch disks using the <expression> that you supply as a prompt. For example: go to pad "a:phone" with diskChange "Insert Disk 2"; When you supply the diskChange parameter: 1. The current pad is closed. 2. HyperPAD displays a dialog box with the message the you supplied. 3. The user can then remove a disk and insert the disk containing the desired pad. If the user selects <<Ok>>, HyperPAD will attempt to load the pad from the new disk. If the user is unable to insert the correct disk and presses <Cancel> at the dialog box, HyperPAD will attempt to load the original pad. If unable to do so, HyperPAD will ask the user to insert the original disk...and will continue to do so until the original disk has been inserted. The go home and go help statements are special because they use HyperPAD's special file searching method to locate the pad. ________________________________________________________________________ Chapter 11: Commands 118 ________________________________________________________________________ The statement go to pad "HOME"; may not be unable to locate the Home pad because it may not be in the current directory or path. Thus, if you want to access either the Home or Help pads you should use go home and go help. go back - is the same as selecting Back from the Go menu. go recent - goes to the most recently accessed page (the one that you just came from). You can also use ordinal types with the go command. The allowed ordinal types are: first, second, third,...,tenth next previous any middle this recent If you attempt to go to a page beyond the end of the pad, the result() function will return "no such page"; otherwise, it will return empty. Examples: go to page 1; go to page 1 of background 2; go to background "template"; go "phone"; go to pad "phone"; go to pad "phone" with diskChange "Insert Disk 2"; go to page 2 of pad "Phone"; go to page 1 of background 2 of pad "Phone" with diskChange "Insert Disk 2"; go to the next page; go to page (currentPage() + 10); go to page ("taxNumber" && i); ________________________________________________________________________ Chapter 11: Commands 119 ________________________________________________________________________ go to any page; go to the recent page; go to the first page of pad "Phone" ask "Go to what pad?"; -- ask for a name go to pad it; ask "Go to what page?"; -- ask for name or number go to page it; Note: Remember, pads are only referenced by name. Thus, the only way to go to a pad is to supply the DOS name of the pad: go to pad "phone"; Pages and backgrounds, however, can be referenced by either their number within the pad, their ID, or their name. For example: go to page 10; -- by page number go to page id 56; -- by page ID go to page "status"; -- by page name When going to backgrounds, HyperPAD really goes to pages on the specified background. The following list summarizes what happens with different go statements involving backgrounds: The following statement goes to the first page on the first background that you created. go to background 1; The next statement goes to the first page after the current page that is on a different background. go to the next background; The next statement goes to the fifth page that uses background 2. go to page 5 of background 2; The next statement goes to the next page after the current page that uses the same background. go to the next page of this background; ________________________________________________________________________ Chapter 11: Commands 120 ________________________________________________________________________ ----------------------------------- HIDE Syntax: hide <object>; Purpose: The hide command allows you to make the specified button or field invisible. This command actually modifies the visible property of the target object. In fact, the following two statements are equivalent: hide page button 1; set the visible of page button 1 to false; When to use it: If you want a button or field to become visible only when certain criteria are met, you can use hide and show to toggle the object's visibility. Examples: hide page field 1; hide background button 3; See Also: show, visible ----------------------------------- HILITE Syntax: hilite [<chunk>]; hilite <field>; hilite the message box; Purpose: This command highlights text within a field or the message box. The text that gets highlighted is copied into the selectedText. When highlighting text, the text becomes highlighted on the screen. ________________________________________________________________________ Chapter 11: Commands 121 ________________________________________________________________________ Examples: hilite char 1 to 5 of page field 1; hilite line 1 of page field 1; hilite the last line of me; hilite field "Last Name"; hilite the message box; hilite word 2 of msg; The following example locates the word "lawyer" in a field and highlights it. get offset("lawyer",field "occupation"); if it is 0 then exit; hilite char it to (it + 5) of field "occupation"; See Also: selectedText ----------------------------------- MULTIPLY Syntax: multiply <destination> by <expression>; Purpose: This command multiplies the value of the <destination> by the value of the <expression> and places the result into the <destination>. The expression must be a number or a container holding a number. The destination must be a container. Note: You will receive a runtime error if the <destination> or the <expression> are not both numbers. Examples: multiply page field 1 by 6; multiply totalAmount by salesTax; multiply the message box by 10; See Also: add, subtract, divide ________________________________________________________________________ Chapter 11: Commands 122 ________________________________________________________________________ ----------------------------------- NOSOUND Syntax: noSound; Purpose: This command stops any music or tones that are currently being played. Examples: sound 2000; -- start a sound wait 200; -- 200 milliseconds noSound; -- turn it off The following example plays notes for 5 seconds. play "abcdefg"; wait 5000; noSound; Note: This command sends the noSound message which is implemented in HyperPAD. ----------------------------------- PLAY Syntax: play <expression>; Purpose: The play command allows you to play music in the background while other HyperPAD tasks are taking place. ________________________________________________________________________ Chapter 11: Commands 123 ________________________________________________________________________ The <expression> is a string containing note and music commands: Command: Description: ----------------------------------------------------------------- A-G Play this note. +,# Make the preceding note sharp. - Make the preceding note flat. Ln Set the length of each note to n. L1= full note, L2 = 1/2 note, L3= 1/4 note (default). The range of n is 1 to 64. MN Play normal. Each not will play 7/8 of the time given by L. ML Music legato. Each note will play the full time given by L. MS Music staccato. Each note will play 3/4 of the time given by L. On Sets the current octave to n. The default is 2, the range of octaves is 0 to 6. Middle C is at the beginning of octave 3. Pn Pause = n. The range of n is 1 to 64. Tn Tempo = n. This sets the number of L4 quarter notes in one minute. The range of n is 32-255. The default is 120. >n Increases the octave of the next note by 1. <n Decreases the octave of the next note by 1. . Increases the playing time of the note (L*T) by 50%. Multiple periods can appear after a note (multiples the playing time by 3/2). Periods may also appear after a pause. Note: Any spaces in your play string are ignored. Music continues to play in the background until there are no more notes to play. You can stop the music by issuing a noSound command. You can determine if music is playing using the isSound() function. Examples: play "cdefgabc"; play "O1 L16 T12O A O2 P4.. B."; Notes: This command sends the play message. When the message is received by HyperPAD, the music will begin playing in the background. See Also: noSound, isSound() ________________________________________________________________________ Chapter 11: Commands 124 ________________________________________________________________________ ----------------------------------- PLAYBACK Syntax: playBack; Purpose: The playBack command starts the replay of keys that have previously been recorded using the record command. HyperPAD begins executing a playBack command on the next idle message. If keys are played back within HyperPAD, the first key will be pressed at the beginning at the next idle (when HyperPAD checks for key presses). The real power, however, is in HyperPAD's ability to play back keys while other programs are running, like in the following example: record "/frHOUSE.WK1{enter}"; playback; run "C:\LOTUS\123.EXE" with programDirectory; Note: This command sends the playBack message. The playBack command is executed when this message is received by HyperPAD. See Also: record ----------------------------------- POP PAGE Syntax: pop page [into <container>]; Purpose: The pop page command removes the last pushed page from the page stack and either goes to it or places it into a container. The push page command allows you to remember where you are in your pad as if you had placed a bookmark on that page. Then, when you want to return there, you use the pop page command. You can place a series of these bookmarks, in which case pop page will take you to those pages in the reverse order in which you placed them. ________________________________________________________________________ Chapter 11: Commands 125 ________________________________________________________________________ If you use the form pop page; you will actually be taken there (you will change pages and possibly the pad). You can also put the references to that page into a variable: pop page into pageRef; pageRef will contain a page reference similar to the following: page id 2 of pad "C:\HOME.PAD"; Examples: The following statements show several different uses of the page stack. The first example remembers the current page, fetches the user's name from the Home pad, and returns. push this page; go home; go to page "preferences"; put page field "User Name" into userName; pop page; push recent; pop page into pageRef; get the last word of pageRef; go to the first page of pad it; See Also: push page ----------------------------------- PRINT Syntax: print <expression> [at <x>,<y>]; print <page reference>; print <number> pages; Purpose: The print command prints either a page, a group of pages, or an expression at an optional X,Y location. Printing pages within HyperPAD is controlled by the current settings in the Print Page dialog box, the Page Setup dialog box, and the Printer Setup dialog box. Printing pages with the print command is exactly the same as choosing Print from the File menu and selecting the Pages option. ________________________________________________________________________ Chapter 11: Commands 126 ________________________________________________________________________ For example: print page 1; print page "status"; print the next page; print 10 pages; Printing text, on the other hand, is not controlled by the current print settings. You must turn the printer on and off manually (using the printer property) and eject pages by sending formfeeds from your script. The following steps are taken: 1. Turn the printer on. 2. Do your printing. 3. Turn the printer off. The print command keeps track of the printhead position internally. When you first turn the printer on, the print head is positioned at 1,1 on the page. As you print characters across the page, the print head X position changes to different coordinates, such as 10,1. As you print carriage returns, the X position is reset to 1 and the Y position is incremented, like 1,10. When you print an end of page (formfeed) the print head position is reset to 1,1. You can directly locate the print head using the print at syntax. For example: print "hello world" at 10,10; When using this syntax, you can only move the print head to the right on the current line or down on the page. The printhead cannot backtrack over already printed text. Examples: print page field 1; print page field 1 & return & page field 2; print formfeed; print page field "First Name" at 10,10; ________________________________________________________________________ Chapter 11: Commands 127 ________________________________________________________________________ The following example prints the AUTOEXEC.BAT file: set the printer to on; put open ("C:\AUTOEXEC.BAT") into fh; if the result is not empty then exit; while the result is not "eof" do begin read 1 line from fh; print it & return; end; set the printer to off; close fh; The following handler prints all the page fields in a pad: handler select; begin ask "Which pad?" with currentPad(); if it is empty then exit; go to pad it; for i = 1 to the number of pages do begin go to page i; for j = 1 to the number of pg flds do print page field j & return; end; end; ----------------------------------- PUSH Syntax: push <page description>; push recent; Purpose: The push page command saves a page identifier on the page stack. The push page command remembers a page and pad so that you can later return there with the pop page command. You can think of this command as placing a bookmark at a location within a pad. ________________________________________________________________________ Chapter 11: Commands 128 ________________________________________________________________________ The push recent syntax saves the page that you just came from on the page stack. This is particularly useful for returning back there later, like in the following example: This handler belongs in a pad script. handler openPad; begin push recent; pass; end; When you want to return from where you came: handler select; begin pop page; end; When to use it: Use the push page command when you want to remember a particular location within a pad so that you can later return there. Examples: The following script visits every page of a background, sending a message to one of its fields and then returns to the page it started from. handler select; begin put 0 into total; push this page; for i=1 to the number of pages of bkgnd 2 do begin go to page i of bkgnd 2; send "reCalc" to field "Item Cost"; add pg fld "Item Cost" to total; end; pop page; answer "The total was" && total; end; Some other examples: push this page; push recent; push previous page; push next page; ________________________________________________________________________ Chapter 11: Commands 129 ________________________________________________________________________ push first page; push page 2 of bkgnd 4; See Also: pop page ----------------------------------- PUT Syntax: put <expression> [into <destination>]; Purpose: The put command places information into a container: either a field, a variable, or the message box. The <expression> can be text, numeric, a numeric expression, or a container. The <destination> must be a container. Expressions are evaluated before they are stored in the destination. So, if you put an arithmetic equation, its result is placed into the destination. If no destination is specified the result is placed into the message box. The put command is probably the most often used command in PADtalk. It provides the only mechanism for copying data from one location to another. Examples: put 10 into page field 1; put longDate() into the message box; put "Wowee" after word 7 of pg fld id 8; put page field "subTotal" into page field "total"; put 10 into field 1 of page 6 of background 2; put empty into me; The following two statements are the same: put "hello"; put "hello" into the message box; The next two statements are also the same: put "hello" into it; get "hello"; See also: get ________________________________________________________________________ Chapter 11: Commands 130 ________________________________________________________________________ ----------------------------------- QUERY Syntax: query <expression>; query clear; Purpose: The query command creates a subset of pages based on some criteria. The query command goes to each page of a particular background and evaluates a boolean (true or false) expression. If the expression is true, then the page is included in the query. If the expression is false, then the page is excluded from the query. A subset of the pages that meet the criteria is formed. The following example will include only pages that contain "John" in the "name" field. query field "Name" contains "John"; If you want to query on a numeric field: query field "Total" > 10; The following statement shows the versatility of the query command. It results in a random set of about half of the pages of any background being included in the query. query random(2) = 1; Once the query has been established, the pad user can view only those pages included in the subset. Using the built-in navigation tools (including PGUP and PGDN), the user can move between the pages in the group. While a query is active, the user can also print and sort those pages. Although you can use PADtalk commands to access other pages in the pad, in order to restore the pad to its pre-query state, you must clear the query with the query clear command. The query will also be cleared if you perform another query, exit to DOS, or run another program. For larger queries, HyperPAD may be required to create a temporary file to hold some query information. The file will reside in the program directory (where HPAD.EXE is located) and will have the same name as your current pad but with an ".IDX" file extension. The result of the query can be determined using the result() function. The result() will return "found" if the query found at least one page; otherwise the result() will return "not found". ________________________________________________________________________ Chapter 11: Commands 131 ________________________________________________________________________ Examples: query field 1 contains "Smith"; if the result is "not found" then answer "No pages in query."; query field 1 = 3 and field 2 10; query field 1 = 3 and field 2 10 or state = "NY"; See Also: find, sort ----------------------------------- READ Syntax: read from <fileNumber> until end; read from <fileNumber> until <character>; read <expression> characters | items | words | lines from <fileNumber>; Purpose: The read command reads data from a file into the local variable it. You can only read from files that have been opened using the open() function. The syntax read from <fileNumber> until end is used to read all the characters that remain in the file starting at the current position in the file. put open("data.dat") into fh; read from fh until end; close fh; put it into field 1; The syntax read from <fileNumber> until <character> is used to read all of the characters up to the next occurrence of character starting at the current position. For example: put open("data.dat") into fh; read from fh until "A"; close fh; put it into field 1; The syntax read <expression> characters | items | words | lines from <fileNumber> is used to read a number of characters, words, items, of lines from the file into the variable it. ________________________________________________________________________ Chapter 11: Commands 132 ________________________________________________________________________ For example: put open("data.dat") int fh; read 1 character from fh; put it; read 6 words from fh; put it; read 5 items from fh; put it; read 2 lines from it; put it; Words are surrounded by either spaces or carriage returns, items are determined by commas, and lines are defined by carriage returns. When reading from files, HyperPAD translates carriage return/line-feed pairs to single carriage returns. You can determine if you have reached the end of file using the result() function. If you have reached the end of file, the result() returns "eof". Otherwise, the result() will be empty. The end of file is determined by either an end of file marker (Hex 1A) or by reading the number of characters determined by the file size. For example: Examples: read from file_number until end; read from file_number until "@"; read n+1 words from file_number; read 1 line from file_number; This example reads the AUTOEXEC.BAT file into page field 1: put the open of "C:\AUTOEXEC.BAT" into fh; read from fh until end; close fh; put it into page field 1; The next handler reads a text file of names and addresses into the PHONE pad. Each record in the text file is separated by a blank line. The format of the phone record in the text file is as follows: Name Phone Number Address Name Phone Number Address ________________________________________________________________________ Chapter 11: Commands 133 ________________________________________________________________________ The address field can take up as many lines as necessary, as long as a blank line is understood as separating the records: handler readPhoneRecords; begin put open ("PHONE.TXT") into fh; repeat doMenu "new page"; read 1 line from fh; put it into field "Name"; read 1 line from fh; put it into field "Phone Number"; read 1 line from fh; put empty into "Address"; repeat read 1 line from fh; if it is not empty then put it after the last line of address; until it is empty; put address into field "Address"; until the result is "eof"; close fh; end; Note: The <fileNumber> parameter is a number returned by the open() function. See Also: write, create(), append(), open() ----------------------------------- RECORD Syntax: record <expression>; Purpose: This command records keystrokes for later playback using the playBack command. The number of keystrokes you can record is 100. Recorded keystrokes remain in memory when you run other programs. If there are any keys in the buffer when another program is launched, they are immediately played back when the running program is started. The <expression> contains the keystrokes that you want played back. Letters and punctuation are types in as normal, like: record "hello"; Special keys and key combinations are placed inside brackets, like: record "{alt+f}Njunk.pad{enter}"; ________________________________________________________________________ Chapter 11: Commands 134 ________________________________________________________________________ A complete list of all of the special keys and key combinations is located in Appendix 2, "Key Codes". The record command will translate all of the keys in the <expression> to numbers. In addition to keystrokes, there is a special command that you can place within brackets called pause. For example: record "{escape}{enter}{pause:5000}"; The pause command waits a specified number of milliseconds before continuing keystroke playback. Thus, {pause:500} waits for half a second. When to use it: When combined with the run command, the record and playback commands are particularly useful because you can pump keystrokes into other programs. Examples: record "this is a test"; record "{alt+f}ophone{enter}"; The following runs BASICA, loading a program called DEMO and running it: handler select; begin record "load ^"DEMO.BAS^"{enter}run{enter}"; playBack; run "BASICA.EXE"; end; Notes: This command sends the record message. HyperPAD handles the record message. See Also: playBack ----------------------------------- RUN Syntax: run <program>; run <program> with programDirectory; run <program> with pause; run <program> with programDirectory,pause; Purpose: The run command executes other programs you use on your computer. While the external program is running, HyperPAD shrinks to 3K, ________________________________________________________________________ Chapter 11: Commands 135 ________________________________________________________________________ giving the program as much memory as possible. When you exit the external program, HyperPAD resumes where it left off. The pause parameter causes HyperPAD to display the message Press any key to return to HyperPAD before returning to HyperPAD. HyperPAD will resume after any keystroke or mouse button press. The programDirectory option controls which directory the program will be executed from. If specified, the current directory will be changed to the directory containing the program. If it is not specified, the current directory will remain unchanged. This parameter is used mainly with programs that require you run them from their own directory. When running another program, HyperPAD performs the following steps: 1. If the extension is not supplied, HyperPAD looks for .EXE, .COM, and .BAT files. 2. If a directory is specified with the filename, HyperPAD looks only in that directory for the program. 3. If no directory is specified, HyperPAD searches the following areas (in this order) for the program: a. The current directory. b. The directory specified by the environment variable HPADNET. c. The program directory (where HPAD.EXE is located). d. The startup directory (where HPAD.EXE was started from). e. Every directory specified in the path. You can determine the return code of the a program using the result() function. Normally, you can determine the return code of a program in a batch file using the DOS errorlevel batch command. In HyperPAD, this number is returned by the result() function. Examples: To return temporarily to the MS-DOS prompt: run environment("COMSPEC"); To run a standard program: run "C:\123\123.EXE" with programDirectory; To run a batch file called C:\BATS\TEST.BAT: run "C:\COMMAND.COM /c C:\BATS\TEST.BAT"; ________________________________________________________________________ Chapter 11: Commands 136 ________________________________________________________________________ To run a batch file leaving room for a larger environment: run "C:\COMMAND.COM /e:2048 /c C:\BATS\TEST.BAT"; To run a program and pause before it returns: run "FORMAT.COM A:" with pause; Abbreviations: programDir, progDir ----------------------------------- SEND Syntax: send <message> <parameter list> to <object> Purpose: The send command sends a message, along with its parameters, to a specific object. It allows you to redirect a message's normal travel up the hierarchy to another object. When to use it: Use the send command when you want some action to be performed that is handled by some other object or handler. It can also be used to bypass a message handler in the hierarchy. Parameters: The <message> parameter is any message for which a handler has been defined in the hierarchy of the receiving object. The characters of the message must be enclosed in double quotes, like "select". The optional <parameter list> is a list of values separated by commas that will be used by the receiving message handler. Examples: send "select" to page button "Quit"; send "keyPress" 7181 to me; -- simulate ENTER send "changeTemp" "up",5 to fld "Thermostat"; The following statement avoids the other objects in the hierarchy by sending a message directly to HyperPAD: send "doMenu" "new page" to hyperpad; The send message will travel up the hierarchy of the receiving object. ________________________________________________________________________ Chapter 11: Commands 137 ________________________________________________________________________ The following example sends a message to one of two routines. It either adds or multiplies two numbers, depending on which option the user wants: handler _add(n1, n2); begin put n1 + n2; end; handler _multiply (n1,n2); begin put n1 * n2; end; handler select; begin answer "add or multiply" with "add", "multiply"; if it is not empty then send "_" & it 10,12 to me; end; Note: The send command changes the value of the me object, but does not change the value of target or currentObject. You can only send messages to objects within the current pad. If you send a message to another page, that page does not become the current page (i.e. it will not receive the openPage message). Parameter expressions are evaluated before the message is sent. ----------------------------------- SET Syntax: set [the] <property> [of <object>] to <value>; Purpose: The set command establishes property values of the objects in your pads. With set, you can modify properties affecting buttons, fields, pages, backgrounds, pads, the message box, the menu bar, the status bar and the tool box. The properties that you can set for the different objects are described in Chapter Twelve, "Properties". Examples: set hilite of page button 1 to true; set lockScreen to false; set the color of page field 4 to black on white; ________________________________________________________________________ Chapter 11: Commands 138 ________________________________________________________________________ ----------------------------------- SETDEFAULTPOPUPCOLOR Syntax: setDefaultPopupColor; Purpose: This handler resets the colors of the popup menus to the same values that HyperPAD uses to display the pull down menus. These colors are modified depending on your computer's graphics card and the command line parameters /mono, /lcd, /B&W, and /color. See Also: popup(), setPopupColors ----------------------------------- SETPOPUPCOLORS Syntax: setPopupColors <menu color>,<highlight color>, <letter color>,<dimmed color>; Purpose: This handler sets the display colors for future popup menus. The colors are used as follows: Color: Description: ---------------------------------------------------- Menu color The color of the menu, including the border Highlight color The color of a highlighted choice Letter color The color of the accelerator characters of the choices (specified with the & within the choice) Dimmed color The color of dimmed choices (specified with the @ character within the choice) Examples: setPopupColors 31,112,27,123; setPopupColors light green,black on grey,red,light grey; See Also: popup(), setDefaultPopupColors ________________________________________________________________________ Chapter 11: Commands 139 ________________________________________________________________________ ----------------------------------- SHOW Syntax: show <object>; Purpose: The show command makes the specified button or field visible; this is the same as setting the visible property of the object to true. When to use it: If you want a button or field to become visible only if certain criteria are met. Examples: show page button 3; show page field 7; The following two statements are equivalent: show button 1; set the visible of button 1 to true; See Also: hide, visible ----------------------------------- SORT Syntax: sort [ascending | descending] [text | numeric | date] by <expression>; Purpose: The sort command reorders the pages belonging to a background according to a specified condition. The sort command works by cycling though all the pages of a particular background and evaluating an expression. The result of the expression is saved and used as a sort key. Once all of the sort information has been gathered, the pages are sorted in the specified order. For example, the following statement sorts a pad by the first background field: sort by field 1; For each page in the current background, the expression field 1 is evaluated and used as sort criteria. Suppose that there are 5 pages in this pad, each using the same background. ________________________________________________________________________ Chapter 11: Commands 140 ________________________________________________________________________ After sort has cycled through all of the pages and evaluated the expression, the situation is as follows: at page 1, field 1 = "Sue" at page 2, field 1 = "John" at page 3, field 1 = "Zev" at page 4, field 1 = "Lisa" at page 5, field 1 = "Jim" After sorting, the pages will be reordered as follows: page 5 will become page 1 ("Jim") page 2 will become page 2 ("John") page 4 will become page 3 ("Lisa") page 1 will become page 4 ("Sue") page 3 will become page 5 ("Zev") When there are multiple backgrounds in the pad, sort may appear to give incorrect results because pages in the pad that use different backgrounds will remain in their same positions. For example, suppose we have 7 pages, 5 pages using background 1 and 2 pages using background 2. We perform the same sort on the first page of background 1: page 1, background 1, field 1 = "Sue" page 2, background 2 page 3, background 1, field 1 = "John" page 4, background 1, field 1 = "Zev" page 5, background 2 page 6, background 1, field 1 = "Lisa" page 7, background 1, field 1 = "Jim" After sorting, the pad will be organized as follows (notice that the pages of background 2 remained in their relative positions in the pad): page 7, background 1 ("Jim") page 2, background 2 page 3, background 1 ("John") page 6, background 1 ("Lisa") page 5, background 2 page 1, background 1 ("Sue") page 4, background 1 ("Zev") The sort command treats the data differently if you specify text, numeric, or date. For text data, HyperPAD alphabetizes the data. For numeric data, HyperPAD compares numeric quantities. For dates, HyperPAD compares the data as dates (dates can be represented using any format the convert command recognizes). ________________________________________________________________________ Chapter 11: Commands 141 ________________________________________________________________________ The optional parameter ascending (the default) specifies that you want the data sorted with the lowest values near the front; descending specifies the opposite. For larger sorts, a disk file may be required to hold temporary sorting data. In such a case, HyperPAD creates a temporary file in either the directory specified by the TMP environment variable, or if TMP is not specified, in the directory from which you launched HyperPAD. To make sorting faster, therefore, you can have TMP specify a directory on a RAM disk, as in the following DOS command: SET TMP=D:\ Examples: sort descending by field "name"; sort by the last word of field "name"; sort numeric by field "age"; sort ascending date by field "birthday"; See Also: query, find ----------------------------------- SOUND Syntax: sound <frequency>; Purpose: The sound command turns the speaker on at a given frequency. The sound will remain on until you turn it off using the noSound command. Examples: sound 2000; wait 500; -- half a second noSound; Notes: This command sends the sound message. When the handler reaches HyperPAD, the sound handler is executed. ________________________________________________________________________ Chapter 11: Commands 142 ________________________________________________________________________ ----------------------------------- SUBTRACT Syntax: subtract <expression> from <destination>; Purpose: The subtract command subtracts the value of the expression from the value of the destination and places the result into the destination. The <expression> must be a number or a container holding a number. The <destination> must be a container. Note: You will receive a runtime error if the <expression> and <destination> are not both numbers. Examples: subtract 5 from page field 23; ----------------------------------- VISUAL Syntax: visual [effect] <effectName> [<direction>] [with delay <expression>]; Purpose: The visual command sets up an effect to be used during the next page or pad change. Instead of simply replacing one page with another (which is the default) you can select an effect which alters the manner in which a page is placed on-screen. Once the effect has been executed, it is reset to the replace effect (the default). So, you must specify an effect each time you want it to occur. The following list includes all the effects and their usable directions: Effect: Direction: ---------------------------------------------------------- box in, out drip none fade none hsplit in, out peel upperleft, lowerleft, upperright, lowerright quad none replace none ________________________________________________________________________ Chapter 11: Commands 143 ________________________________________________________________________ When to use it: Visual effects are useful if you want to capture your audience's attention without distracting them from the information you're relating. Examples: The following example goes to the next or previous page depending on whether the SHIFT key is depressed when the button was selected. It uses an appropriate visual direction as a user feedback device. handler select; begin if the shiftKey is "down" then begin visual effect scroll down; go to the previous page; end else begin visual effect scroll up; go to the next page; end end; Comments: The visual effect is set to replace when the next idle message is sent (upon completion of all pending handlers). ----------------------------------- WAIT Syntax: wait <milliseconds>; Purpose: This command waits a specified number of milliseconds. Pressing CTRL+BREAK will terminate the wait command and stop execution of the script. The delay is the same for all computers. HyperPAD uses either the real time clock (on AT style computers) or the system clock (interrupt 8) so that it ticks 1000 times per second. Examples: wait 5000; -- 5 seconds wait i * 1000; -- if i = seconds ________________________________________________________________________ Chapter 11: Commands 144 ________________________________________________________________________ ----------------------------------- WRITE Syntax: write <expression> to <fileNumber>; Purpose: The write command adds data to an open file. Only files opened with the append() or create() function can be used with this command. Examples: To write a field to a file: put create("data.dat") into fh; write page field 1 to fh; close fh; Use the return constant to end a line: write page field "name" & return to fh; write page field "address" & return to fh; write page field "phone number" & return & return to fh; Note: Single carriage returns are translated to carriage return/line- feed pairs. All files are automatically closed when the user exits or runs another application using the run command.