The CanDo How To Book, Version 1.0: INOVAtronics, Inc. 8499 Greenville Ave. Suite 209B Dallas, TX 75231 USA Phone: (214) 340-4991 BBS: (214) 357-8511 Errata-On-Disk The following is a list of minor corrections to the CanDo documentation, listed in the order of the sections of the manual. Also included here is documentation for some commands and features which were added at the last minute (relatively speaking), plus documentation for a program that removes hung CanDo decks from a system. This is called ShutDownDeck and is found on the CanDoExtras disk. --------------- First of all... --------------- Our phone number on the back manual cover is incorrect. It should read 214-340-4991. --------------------------------- CanDo Installation --------------------------------- Floppy Disk Based Amiga's - The CanDoInstaller program does not copy the "Decks" drawer or other optional files to your WorkBench disk. Please use your working CanDo disk to run the sample Decks, Sounds, Images, etc. CanDoInstaller installs the following files: CanDo CanDo.info c/DeckRunner c/DeckRunnerNoLibrary c/DeckBinder libs/CanDo.library L/ApplicationIcon.info These files are essential for CanDo and it's Decks to operate correctly. Hard Disk Installation - The CanDoInstaller program installs CanDo in a drawer on the root directory. CanDo and all the support files on the CanDoExtras disk are copied to this directory. The following files are installed: C:DeckRunner C:DeckRunnerNoLibrary C:DeckBinder Libs:CanDo.library L:ApplicationIcon.info As above, the sample Decks, Sounds, Images, etc., on your CanDo disk are not copied on your Hard Disk. --------------------------------- Section 2:Tutorial (You CanDo It) --------------------------------- 2-8:Step 42 ----------- The step to be repeated is Number 39, not 38. Also, in this step, the user is encouraged to change button border styles. While we haven't used borders in this example, they are self-explanatory and fun to work with. 2-11:Step 19 and 22 ------------------- If you should study the deck on the Extras disk that corresponds to this tutorial, you may find that your pathnames differ from those in the deck on the disk. If you used the Dos Editor Tool, don't worry; it's foolproof. 2-13:Step 23 ------------ Disregard the third and final line of the script in this step (PrintText). The script is as follows: Setpen 1 PrintText "Sound Samples",35,48 ----------------- Section 4:Objects ----------------- 4-22:Menus --------------------------------------- Currently the Menus do not support extended print styles. 4-31:Document Editors and Lists --------------------------------------- Currently the Document Editors handle non-proportional fonts only. These fonts include topaz and Courier and are supplied by Commodore on your original system disks. 4-35:Animation Object ----------------------------- When creating an animation object, you must reference the brush animation with the exact path and filename you specified when loading and/or showing it. The animation object cannot refer to a brush animation that has been given another name with the LoadBrushAnim Command. ------------------ Section 6:Commands ------------------ 6:30-33:Graphics ------------------ The PrintText Command on page 6-33 is documented incorrectly. The x,y coordinates should be specified AFTER the "string". The syntax should be... PrintText "string",, The example should read as follows: PrintText "Hello World",50,50 ********************************************************************* The example for the SetPrintFont Command on page 6-33 is incorrect. SetPrintFont "topaz" Make sure that the capitalization for the font's name corresponds exactly with the real thing. ********************************************************************* The example for the DrawTo Command on page 6-30 is incorrect. It should read as follows: DrawLine 50,50,100,50 DrawTo 100,100 Notice the example uses the Command "DrawLine". There is not a "Line" Command. 6-31:GetRGB and 6-32:SetRGB ---------------------------- These Commands use color values ranging from 0 to 255 for each of the red, blue or green components that make up the color. This enables CanDo to take advantage of future Amiga hardware that can display more than the current 4096 colors. Currently, paint programs (Deluxe Paint) use values from 0 through 15. Their equivalents in CanDo may be obtained by multiplying them by 17. 6-40:Animation ---------------------- Sequence motion shows ALL frames of an animation before moving it. -------------------- Section 7:Appendices -------------------- 7-10:Error Messages/Syntax Errors "Conflicting switches Specified" should read: Conflicting KEYWORDS Specified ================================================== Additional Commands (not documented in the manual) ================================================== ----------------------------------------------------------------------- "string" = AskForFileName ("filespec" {,"WindowTitle" {,x {,y} } } ) This Function brings up CanDo's file requester. It allows your application to ask for a file name from the user. The "filespec" allows you to specify the default file specification shown in the file requester. The remaining parameters are optional. "WindowTitle" lets you specify the message appearing on the File Requester's Window Title. The x,y parameters allow you to specify the initial horizontal and vertical location. The returned "string" indicates the file specified by the user. It will be "" (NULL) if they selected CANCEL. ----------------------------------------------------------------------- AreaCopy , , , , , The AreaCopy Command copies an area of the window. The StartX and StartY specify the upper left corner of the area to copy. The Width and Height specify the size of the area in pixels. The DestinationX and DestinationY indicate the upper left corner of the area to copy to. ----------------------------------------------------------------------- AreaPolygon , , , , , {,, {,, {,, }}} The AreaPolygon allows you to draw a solid Polygon with 3 to 6 vertices. It uses the color in PenA. the parameters are the X,Y locations for the Polygon. The first six values, designating 3 verticies, are required. An additional 3 verticies can be specified. ----------------------------------------------------------------------- AreaScroll , , , , , The AreaScroll Command scrolls an area of the window. The StartX, StartY, Width, and Height define the area to be scrolled. The DeltaX and DeltaY indicate the number of Pixels to scroll. Example: Let Cnt = 100 ; Scroll 100 Times While Cnt > 0 Let Cnt = Cnt - 1 ; Decrement Cnt for Loop AreaScroll 0,0,320,200,4,2 ; Scroll entire window EndLoop ----------------------------------------------------------------------- Dispose VarName Dispose removes the specified variable. By removing the variable its current contents are lost and it will perform as though it had never been created. ----------------------------------------------------------------------- DisposeAll Disposes all variables. The contents of all variables are lost. ----------------------------------------------------------------------- DoOnError "RoutineName" {,Arg1,...,Arg10} The DoOnError Command performs the specified "RoutineName" if an error occurs in the script being performed. This will supersede the error handling done by CanDo. This means CanDo will not detect the error and it will not bring up the error script. ----------------------------------------------------------------------- DrawPolygon , , , , , {,, {,, {,X6, Y6}}} The AreaPolygon allows you to draw a Polygon with 3 to 6 verticies. The Polygon is drawn with lines using PenA. the parameters are the X,Y locations for the Polygon. The first six values, designating 3 verticies, are required. An additional 3 verticies can be specified. ----------------------------------------------------------------------- = ErrorLineNumber The ErrorLineNumber variable returns the line number, in the script, that caused an error. This number can be used by the "RoutineName" used in a DoOnError. ----------------------------------------------------------------------- "string" = ErrorScriptType It returns the script type where an error occurred. ----------------------------------------------------------------------- "string" = ErrorSourceLine It returns the source line of the line the error occurred on. ----------------------------------------------------------------------- "string" = ErrorSourceName It returns the Name of the Object, Routine, or the Card in the case of StartupScripts errors, where the error occurred. ----------------------------------------------------------------------- "string" = ErrorSourceType It returns "Object", "Routine", or the "Card" in the case of StartupScript errors, where the error occurred. ----------------------------------------------------------------------- "string" = ErrorText It returns the error message for the error that occurred. ----------------------------------------------------------------------- <> = Exists ("filename") It returns a TRUE if the specified filename exists. ----------------------------------------------------------------------- "string" = FileType ("FileName") This function returns specific information about the type of file. These include: Directory - The filespec is actually a directory. Program - This is a executable program. Deck - This is a CanDo Deck. Sound - This is an 8SVX IFF sampled sound file. Picture - This is a standard IFF picture. Brush - This is an IFF "GRAB" or clipped image. BrushAnim - This is an IFF Deluxe PaintIII Brush Animation Unknown - This file could not be positively identified. This could mean that it is a simple text file. ----------------------------------------------------------------------- GetDiskInfo "filespec" , NumberOfBlockVar {,NumberUsedVar {,BytesPerBlockVar}} This Command is used for getting information about a Disk Device. The "filespec" is the specification for the device or any file on the device. The remaining parameters must be valid variable names where the information is to be stored. NumberOfBlockVar will be set to the number of Blocks the device has. NumberUsedVar will be set to the number of Blocks currently in use on the device. BytesPerBlockVar will be set to the number of usable bytes per Block. Using these values you can calculate additional information that you may want to use. ----------------------------------------------------------------------- GetWindowLimits MinX, MinY, MaxX, MaxY The GetWindowLimits Command returns current window limits. The values will be put into the specified variable names. They can be changed using the SetWindowLimits Command. See the SetWindowLimits Command for a description of the values. ----------------------------------------------------------------------- IfError...{else}...endif The IfError Command is used to detect an error following a scripting Command. If the previous Command caused an error the IfError Commands will supersede CanDo's error handling done by CanDo and a DoOnError you might have in the script. This means CanDo will not know about the error and the "RoutineName" specified in a DoOnError will not be performed. ----------------------------------------------------------------------- "string" = LibraryVersion The LibraryVersion System Variable returns the string identifing the current CanDo.Library being used. ----------------------------------------------------------------------- = Nothing The Nothing System Variable is primarily used to determining if a variable has a value. Example: If TheVariable = Nothing . . . EndIf This comparison will only be TRUE if the variable has no value. ----------------------------------------------------------------------- = NumberOfWords ("String" {,Delimiters}) The NumberOfWords Function returns the number of seperate words in the specified string. You can optionally specify the character delimiters separating the words. ----------------------------------------------------------------------- "string" = ParentOf ("DirName") The ParentOf Function returns the directory specification of the specified "DirName" ----------------------------------------------------------------------- "string" = ScreenTitle It returns the current Screen Title message ----------------------------------------------------------------------- <> = SearchFound The SearchFound System Variable Returns TRUE if the most previous SearchFor or Replace Command found the specified search string. ----------------------------------------------------------------------- SetAutoFileRequester <> SetAutoFileRequester enables or disables the automatic file requester. When enabled, CanDo's file requester will appear whenever an error occurs when reading a file. While this can very useful for avoiding errors, you may want to provide your own error handling and not have the file requester appear. However, an error will still occur if the user selects CANCEL from the automatic file requester. ----------------------------------------------------------------------- SortDocument {SortSwitches {,} } The SortDocument allows you to sort the Current WorkWithDocument. The default sort is Non-Case sensitive in Ascending Order starting in Column 1. The optional SortSwitches allow you to specify NOCASE or CASE, and ASCENDING or DESCENDING. Finally, the optional StartingColumn allows you specify a column of 1 or more. Examples: SortDocument ; uses default settings SortDocument NOCASE ASCENDING, 1 ; uses default settings SortDocument CASE ; Case sensitive sort SortDocument DESCENDING ; Descending Order SortDocument NOCASE, 5 ; A switch is required ; to specify Column 5 ----------------------------------------------------------------------- = TimeLeftOnChannel ( ) The TimeLeftOnChannel Function returns the number of seconds remain for a sound playing on the specified channel. ----------------------------------------------------------------------- Additional utilities located on the CanDoExtras disk in the CLI-Utilities directory. SerialManager - AREXX microserver SerialManager is a standalone program to handle communications over the Amiga's serial port. This enables your CanDo application to communicate with external hardware such as a laserdisc player, video equipment, or anything that can send and receive text messages. You must run SerialManager from a CLI or Shell, or from CanDo's DOS command. SerialManager -l{port} -t{talkto} -u{unit} -d{devicename} -p{prefix} ARexx Commands Understood: (Not caps sensitive) Send {text} SetTalkTo {portname} SetPrefix {prefix} SetConfig {as in F8N1{baud}} SetCRMode {On,Off} -- this waits on CR to end else waits on NIL SetHandshaking {XON,DTR,NONE} Quit -- shut down the serialmanager Abort -- Use when SerialManager hangs on replying to a message from an ARexx message. Only works in that case. Must be sent by external program as your main program will be hung waiting on its reply. NOTE : DTR works by setting 7Wire mode and turning XON/XOFF off. ----------------------------------------------------------------------- AnimToBAnim - A utility to convert full screen Anims to Deluxe Paint III compatible brush animations. ANIM REV.5 TO BrushANIM REV.5 Converter -- Version 1.1 Copyright (c) 1989 by Silver Fox Software, All Rights Reserved Written by James Nelson Developed for INOVAtronics -- Creators of CanDo! Syntax: animtobanim {animname} {banimname} [{x} {y} {w} {h}] Required Arguments: {animname} - name of the source anim file {banimname} - name of the destination brush animation file Optional Arguments: {x} {y} - upperleft corner of the rectangle to clip {w} {h} - size of the rectangle to clip ----------------------------------------------------------------------- ShutDownDeck {DeckName} A file is included on the CanDoExtras disk called "ShutDownDeck." Its purpose is to shut down a running CanDo Deck. In the event that your Deck becomes caught in a loop and appears to be hung, you may execute this command and quit the application. For example if your Deck had a script as follows: Let count=0 ;initialize count to zero While count<10 ;loop until count becomes 10 or greater PlaySound "CanDo:Sounds/DogBark.snd" Let cnt=cnt+1 ;we misspelled our count variable EndLoop ;we'll never end NextCard ;go to the next card As you can see, this While...EndLoop will never end since the variable "count" does not get incremented. In order to remove this hung Deck from your system, the user would do the following. 1. Go to an active CLI or shell 2. Type: (pathname/)ShutDownDeck DeckName DeckName, in this case, is the name of the hung deck. It must mirror the deck name exactly, including case-sensitivity. If the deck is truly hung, it will be removed immediately, returning the user to the CLI, shell, or Workbench. If the specified deck is actually running correctly, it will be removed after its next event (such as clicking one of the deck's buttons).