CanDo: An Interactive Authoring Tool, Part 7: Buttons, Sorting, Printing, and AmigaGuide Help

by Randy Finch

For this installment, I decided to write a complete application including help via AmigaGuide, Commodore's help system. The CanDo deck is named StarTrek_Videos. This program allows the user to input information about his or her Star Trek video collection. The information can be sorted and printed. I have used the program to input my collection of 29 video tapes containing 174 episodes of Star Trek and have found it to be a very useful tool. Of course, with a few changes, the program could be used for any type of video collection.

Star Trek: The Video Collection

The user interface for the CanDo deck is shown in Figure 1 and a print-out of the deck is shown in Listing 1. Please refer to these during the discussion below.

The interface consists of three image buttons, six text buttons, one area button, four text fields, and three integer fields. The position, properties, and limitations of these objects can be found in the Definition sections of the program listing. The text "The Video Collection" near the top of the card, the horizontal bar, and all the labels for the text and integer fields were generated in the RefreshWindow global routine which is called from the card's AfterAttachment script.

Text and Integer Fields

The text fields consist of the four input fields labeled Show, Title, Year, and Description. The integer fields consist of the three input fields labeled Episode #, Tape #, and Show #. Since I have discussed these type of objects in previous installments, I will only discuss what these fields are used for.

The Show field is used for a three-letter code representing the type of Star Trek show. At this time, only three types make sense: ORG (Original Star Trek), TNG (The Next Generation), and DS9 (Deep Space 9). The Year and Episode # fields are used to store the year the show aired and the sequence within the year. (I use the same year for the entire TV season. Thus, I designate all shows for the 1993-94 season as 1994.) Tape # and Show # refer to the number given to the tape and the position of the show on the tape. The Title and Description fields are self explanatory. The actual names used for these fields all begin with a period. This allows the information in the fields to be quickly moved to and from an array variable as discussed in an earlier installment (November 1993).

You may be wondering why the Year field is a text field rather than an integer field. Well, I had some recordings of re-runs and did not know the year they were originally shown. I wanted to use the word "Old" in this field to designate this fact. Thus, I made it a text field. One interesting aside. I originally made the Year field an integer field. It was only after having added about 50 records to the database that I decided to change it to a text field. After changing it and loading the database, I discovered that the year values displayed fine in the new text field even though they were originally saved as integers.

Image Buttons

The three image buttons are the big "Star Trek" button at the top of the card, and the left and right arrow buttons at the bottom of the card. The first image button uses a brush named StarTrek.br that I created in Deluxe Paint IV. When this button is pushed, the master index of the AmigaGuide help file is displayed. This will be discussed later. Be aware that the background color for an image button is transparent. Therefore, to press an image button, you must position the pointer over the non-transparent part of the image. If you do not, the button will not be activated.

The arrow buttons use brushes that were included with CanDo. They are used to step forward and backward one record in the database when in Edit mode (see Edit/Add Rollo Button section below).

While adding the "Star Trek" button to the deck, I discovered an interesting "feature" of CanDo. If you select a brush file to use for an image button, switch to your paint program, modify the brush, and re-save it, you cannot simply switch back to CanDo and select the same file name again. If you do, the original image is still used. If you select a totally different file and then revert back to the originally chosen file, the same thing occurs. The only way you can get CanDo to recognize the modified file saved from your paint program is to save the deck and then re-load it. Apparently, once a brush is selected for use as an image button, CanDo buffers the file and it cannot be replaced with a modified brush using the same filename.

The Del Button

This text button allows you to delete the currently displayed record when in Edit mode. When a record is deleted using the DeleteArray function, all of the indices of records after it are renumbered.

The Sort Button

This text button allows you to sort the database. When complete, the entire database will be sorted by tape number. The show number will be in sequence for each tape number. The database must be sorted for the printed output to look right (see The Print Button section below).

Typically, the way to accomplish a double sort as described above is to first sort by the secondary variable (Show #) and then to sort by the primary variable (Tape #). However, this only works if the sort algorithm used for the second sort maintains the ordering of the first sort. Apparently, the SortArray command does not do this. It uses an algorithm that is faster but destroys the ordering of the database. Therefore, instead of using two SortArray commands in sequence to accomplish the double sort, I used one SortArray command to sort by Show # and then used a routine I wrote entitled SortTapeNum to do the second sort. SortTapeNum uses a simple bubble sort. It is slower than other algorithms, but it does maintain the order of the first sort. On my 28 MHz 68030 Amiga 2000, 174 records were sorted in 1.5 minutes.

The Print Button

This text button allows you to print out a formatted report for the database on a Hewlett-Packard LaserJet 4 printer. It will probably work for other model LaserJets and compatibles. A sample print out is shown in Table 1. The output is grouped by tape number and ordered by show number for each tape.

Following through the OnRelease event script for the Print button, you will see that several printer escape sequences are defined for formatting text and positioning the cursor. A file is then opened to the PAR: device, and the formatted output is sent to the printer using FileWriteChars and FileWriteLine commands. The former command sends the text without attaching a line feed (LF) to the end of the text while the latter does attach a line feed. Since I am printing directly to the parallel port rather than going through a printer driver (PRT:), a line feed does not get converted into a carriage return / line feed (CR/LF) combination. Therefore, a CR must be added to the end of any text written with a FileWriteLine command. The output shows the contents of eight video tapes on each page. This is controlled by a loop that looks for the variable NumTapes to become a multiple of eight.

If you want to modify the script to work with your printer, you will need to replace the escape codes with those for your printer. If an equivalent code is not available for your printer, then additional code may have to be written. Another way to modify the script is to use the standard Amiga printer escape sequences that are recognized by the Amiga printer drivers. If you do this, the file should be opened to PRT: rather than PAR:. When you print to the PRT: device, the current Preferences printer driver will intercept all the standard codes and convert them to the equivalent codes for the printer. Since a LF will be converted to a CR/LF, the CRs must be removed from the FileWriteLine commands.

The Load and Save Buttons

These two text buttons each bring up the standard Amiga file requester allowing you to select the path and the file to load or save. The AskForFileName function is used. Notice that in each case the FN variable is passed to this function as the file specification. This variable is initially NULL but will be set equal to whatever path and filename is chosen. By using this file spec, the file requester will always display the last selected directory rather than the current directory. The default filename will be the previously selected filename. Since the AskForFileName function returns a NULL when the Cancel button on the file requester is selected, the current value of FN is stored in FNold before the file requester is displayed and, if the Cancel button is selected, equated back to FN. This prevents losing the previous path and filename when the user cancels a load or save operation.

The ? Button

This text button is used to obtain help about other objects on the screen. It is a toggle button. This means that when the button is pressed it will toggle to an ON state, remaining highlighted. When it is pressed again, it will toggle to an OFF state and the highlighting will disappear. When this button is ON, selecting other objects on the card will bring up an AmigaGuide help file with information about the selected object. When this button is OFF, selecting other objects cause them to operate in the normal way. This will be discussed more in the AmigaGuide Help section.

The Edit/Add Rollo Button

The area button in the lower left corner of the card has a rollo border type. A rollo border has a curving arrow on the left side of the button. This is not a special type of button that allows you to specify a list of text strings to cycle through when selected. Rather it is just a plain old area button with a different appearance. To simulate a real rollo button, a script must be used to do all the work.

There are only two states that the rollo button can be in: Edit or Add. The current state of the button is stored in the variable Mode. This variable is set to "Edit" in the RefreshWindow global routine which is called when the card first appears. Also, the word "Edit" is printed on top of the button. When the button is pushed, the OnRelease event script executes. This script checks the current state of the button via the Mode variable. If Mode is equal to "Edit", then it is changed to "Add", the word on top of the button is overwritten with "Add" to reflect the change, four buttons are disabled, the window title is changed, the Title and Description fields are cleared, and the Show field is activated. You are now ready to add new records to the database. The DisableObject command is used to disable the left arrow, right arrow, Del, and Sort buttons. When disabled, the buttons will have a ghosted look to them, giving visual feedback that they cannot be selected.

If Mode is equal to "Add" when the rollo button is pushed, then the four previously disabled buttons are enabled. However, there is a problem. The ghosted look goes away for image buttons but not for text buttons. This is true even though the buttons are actually enabled. The way to clear the ghosted look from the buttons is to execute the ClearWindow command. But this creates another problem. All of the text and graphics that were drawn on the screen after the card was attached disappear. Thus, the RefreshWindow routine must be called to re-display everything that disappeared. This is a rather roundabout way of removing the ghosted look of a disabled button, but it is the only way I could find to accomplish the task.

AmigaGuide Help

As I mentioned in the fourth installment of this series (December 1993), CanDo 2.51 supports AmigaGuide help files. The AskForHelp function accomplishes this task. The Star Trek Video Collection program makes use of a help file. It is named StarTrek.guide and is shown in Listing 2. I modeled the help file after one of the CanDo help files. A print-out of the AmigaGuide help window is shown in Figure 2.

Basically, an AmigaGuide help file is an ASCII file with embedded commands. There are three kinds of commands: label commands, node label commands, and action commands. The first two types of commands begin with the @ symbol. Table 2 shows some of the common commands. They provide AmigaGuide with information about how text should appear and how the various pieces of information link together. Since AmigaGuide help files are in ASCII format, they can be created easily with a text editor or word processor. This is unlike creating help files for the Windows platform where exotic codes have to be inserted, the file stored in Rich Text Format, and then compiled.

All label and node label commands, except for textual link points, must have the @ symbol in the first column of a line. The first line of an AmigaGuide help file must be a @database command. This command specifies the name of the AmigaGuide file.

I do not know if the @author, @(c), and @$VER: commands serve any purpose other than to provide information. I was unable to find them documented anywhere. It seems obvious what the @wordwrap and @font label commands should do, but neither worked as expected. I believe these commands are new to the AmigaGuide system for AmigaDOS 3.0, but I was not able to test it with that version of the operating system.

The @index command specifies which node in the help file will be displayed when the Index button is pressed at the top of the AmigaGuide help window.

The rest of the StarTrek.guide file consists of nodes. These are sections of text surrounded with the @node and @endnode commands. Nodes contain the actual text that will be displayed in a help window. Node label commands can be inside an @node section. These are documented in Table 2.

The first node in StarTrek.guide is Main. By default, this is the name of the node that will be displayed when the Contents button at the top of the help window is pressed. This can be overridden within individual nodes with the @toc node label command.

The only thing that appears within the nodes of StarTrek.guide is the text to be displayed and textual link points. Notice that the first line of text in each node is the same as the window title as specified in the @node label command. The reason for doing this is to be kind to people who want to print the contents of the help window. Since the window title is not printed, it is nice to have the window title text in the printed text so it is easy to see the subject of the help file.

Textual link points appear in nodes StarTrek_MasterIndex and StarTrek_EditAdd. The latter demonstrates how a textual link point does not have to be in the first column of a line. A textual link point has the following syntax:

	@{<label> <command>}

The <label> is the text string that appears within the button that AmigaGuide creates for the link point. You can see how it appears in Figure 2. The <command> can be any of the action commands listed in Table 2. The most common one is the link command. It tells AmigaGuide to display another node. This is the essence of hypertext. The other available commands allow new windows to be opened and closed, ARexx macros and strings to be executed, system commands to be executed, and the database to be shut down. Node StarTrek_MasterIndex is a good example of how link points can be used for an index into the entire help file.

I have only touched the high points of AmigaGuide help files. If you would like more details, I recommend either DevWare's DevDisk 92 or Fred Fish 870. They contain Commodore's information on AmigaGuide.

Getting Star Trek Help

The Star Trek Video Collection program uses a global routine for accessing the StarTrek.guide help file. This routine accepts one argument, the ending of the node name. This ending is appended to the string "StarTrek_", which is common to all node names except for Main. Once the argument is appended, the complete node name is available. The AmigaGuide help filename and the complete node name are used as arguments for the AskForHelp function.

There are several ways you can get help while running the program. First, you can press the Help key while no fields are selected. The KeyInput object named "Help" will have its OnUp script activated. This script calls GetHelp, asking it to display the master index. Second, you can press the big "Star Trek" image button at the top of the screen. This will display the master index as the Help key does. Third, you can toggle the ? button to ON and select a field or button. Each field has an OnClick event script that checks to see if the ? button is ON. If it is, an appropriate node within the help file is displayed. Each button checks the state of the ? button in its OnRelease script. If the state is ON, then the normal function of the button is suspended and an appropriate node in the help file is displayed.

There are several anomalies you should be aware of when using AmigaGuide help files. First, if you use the AskForHelp function with a non-existent help file, you will receive no error message. In fact, nothing will happen. Make sure the help filename is correct or put in a check for the file's existence before using AskForHelp. Second, if you do not press Enter after the last @endnode when creating the help file, the text of that node will not be displayed in the help window. The title appears, but the text is missing. Third, when you use the Help key while browsing a CanDo deck, CanDo's internal help display overrides any help that the deck itself displays. This does not happen when in SuperBrowse mode or when executing the deck as a stand alone application created by TheBinder or TheMultiBinder.

Winding Down

That's it for this time.


Back to list of articles
Back to Randy Finch's Home Page
Last modified on April 1, 1996
Randy Finch at webmaster@rcfinch.com