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.
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.
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.
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.
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.
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.
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.
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.