home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 531.lha / TurboText_Utils / SelectDoc_v1.9 / SelectDoc.doc < prev    next >
Encoding:
Text File  |  1991-07-04  |  7.4 KB  |  182 lines
  1.  
  2.                     SelectDoc v1.0, by Stan Ziel
  3.                     ----------------------------
  4.  
  5. OVERVIEW
  6. --------
  7.     SelectDoc is an add-on utility (tool) for TurboText, which presents
  8. you with a list of documents.  Using a GUI and  scrolling list, you can 
  9. choose a document, which  will be brought to the  front of the screen
  10. and made  active.  SelectDoc will only run under version 2.0 or greater
  11. of AmigaDOS.
  12.  
  13.     SelectDoc is freely redistributable.
  14.  
  15.     TurboText is Copyright © 1990,1991 by Martin Taillefer.
  16.  
  17.  
  18. INSTALLATION
  19. ------------
  20.     Simply copy SelectDoc to a suitable place on your system.  One
  21. likely place is wherever you have TurboText: assigned.  Once this is
  22. done, you will want to add a command to your TTX_Startup.dfn file that
  23. will run SelectDoc.  This will use the ExecTool command of TurboText to
  24. start SelectDoc.  Starting SelectDoc every time you start TurboText is
  25. left as an experiment to the reader.  :-)
  26.  
  27.     SelectDoc is not "pure" nor can it be made resident.  However, since
  28. you can only have one copy of TurboText, this should not be a problem.
  29. If SelectDoc sees that it is already running, it will just open the
  30. current SelectDoc window.  This allows you to use the same command that
  31. starts SelectDoc to also activate SelectDoc.
  32.  
  33.     SelectDoc does not "detach", and thus will not return control to
  34. TurboText once it is started.  This is useful if you want to use
  35. SelectDoc as a "one-shot" utility.  But if you want to start SelectDoc
  36. and then continue with TurboText, you can "run" SelectDoc to do this.
  37.  
  38.     An example menu item to start SelectDoc would be:
  39.  
  40.   ITEM "Select Doc..." "" ExecTool SCREEN
  41.             "run <nil: >nil: TurboText:SelectDoc BG"
  42.  
  43.     Note: The line is broken in half just so that it will fit here.
  44. This line would go in your TTX_Startup.dfn file, and would install a
  45. menu item that starts SelectDoc in background mode.  This allows it to
  46. hang around after the selection, and thus we use "run".  The SCREEN
  47. argument must be used after ExecTool!  SelectDoc will not run if this is
  48. missing.  This menu item will also activate SelectDoc if it is already
  49. running.
  50.  
  51.  
  52. COMMAND-LINE OPTIONS
  53. --------------------
  54.     SelectDoc uses a standard CLI-Template for the options passed to it.
  55. However, typing "SelectDoc ?" will not do anything, so you'll need to
  56. read about them here.  The SCREEN option is mandatory, and is passed
  57. from TurboText when you use "ExecTool SCREEN" to start SelectDoc.  The
  58. full Template is:
  59.  
  60.     BG=BACKGROUND/S,ICON=ICONIFIED/S,LEFT/N/K,TOP/N/K,SCREEN/A
  61.  
  62.     BG      - This option tells SelectDoc to hang around after you make
  63.               a selection.  SelectDoc will quit, though, if you use the
  64.               close gadget, or send an ARexx command telling it to quit.
  65.  
  66.     ICON    - This option is used to start SelectDoc in its iconified
  67.               mode.  This is a small window that is less obtrusive, so
  68.               is handy when you keep SelectDoc in background mode.
  69.  
  70.     LEFT n  - When you use the "LEFT" keyword along with a numeric
  71.               argument, you specify the starting left-edge for the
  72.               SelectDoc windows.  If you specify a value that would put
  73.               the windows off the screen, the windows are opened with
  74.               the maximum possible left-edge.
  75.  
  76.     TOP n   - Like the LEFT option, but this value specifies the
  77.               top-edge to use.  Again, this value will be adjusted if it
  78.               isn't valid for the screen dimensions.
  79.  
  80.     If SelectDoc is already running, all options are ignored.
  81.  
  82.  
  83. INTERFACE
  84. ---------
  85.     SelectDoc's interface is fairly straight-forward, and follows (for
  86. the most part) the 2.0 style.  You can drag the window around, and zoom
  87. between Iconified and Full-Sized windows.
  88.  
  89.     The close gadget will terminate SelectDoc regardless even if you
  90. specified "BG" on the command line.
  91.  
  92.     When SelectDoc is full-sized, you will see a list of documents, plus
  93. three buttons.  The list can be scrolled if there are more documents
  94. than will fit.  The buttons all have keyboard shortcuts, which are
  95. specified by the underline.  (You don't need to use any special keys
  96. with the keyboard shortcuts.)
  97.  
  98.     To choose a document, click and it once, and choose "OK", or just
  99. double-click on the name of the document.  If, for some reason, the
  100. document is not found, or you have not picked one yet, the screen will
  101. flash, and you can try again.
  102.  
  103.     Choosing Cancel will end the process without selecting a document.
  104. Note that OK and Cancel both respect the BackGround setting.  If you
  105. started SelectDoc with the BG option, they will iconify the window.
  106. Otherwise, SelectDoc will terminate.
  107.  
  108.     Update List is used for those times when SelectDoc's list doesn't
  109. keep up with the documents you really have in TurboText.  This can
  110. happen, for example, when the SelectDoc window is full-sized, and you
  111. open or close a document.  When this happens, you can update the list.
  112. The list is always updated when the SelectDoc window de-iconifies, and
  113. when you choose a non-existant document.
  114.  
  115.     Note: The list shows "<no name>" for documents that have not yet
  116. been named (or might be empty.)  This makes it easier to distinguish
  117. these documents from empty spots on the list.
  118.  
  119.  
  120. AREXX
  121. -----
  122.     SelectDoc also accepts some ARexx commands.  This allows you to have
  123. additional control from TurboText menus and keyboard commands.  (Or any
  124. place else that speaks ARexx.)
  125.  
  126.     SelectDoc's ARexx port is called "TTX_SD_PORT".  It is in upper-case
  127. to make it easier to deal with in ARexx.  One example of using the ARexx
  128. interface would be to add a keyboard command to toggle the Iconify-state
  129. of the window from within TurboText.  Thus:
  130.  
  131.     CTRL-D  ExecARexxString "address TTX_SD_PORT TOGGLE"
  132.  
  133.     You might want to be sure that the port exists first.  But if you
  134. don't, and the port isn't found, you'll just get an error message to
  135. that extent; no harm done.
  136.  
  137.     The ARexx commands understood by SelectDoc are:
  138.  
  139.     TOGGLE      - Toggle the window's Iconified state.
  140.  
  141.     QUIT        - Tells SelectDoc to terminate, regardless of BackGround
  142.                   mode.
  143.  
  144.     UPDATE      - Forces SelectDoc to update it's list of documents.
  145.  
  146.     CANCEL      - This Iconifies the window (if it isn't already.)  If
  147.                   SelectDoc is not running in BackGround mode, then the
  148.                   program will be terminated.  "CANCEL" was chosen since
  149.                   it is the same as the Cancel gadget.
  150.  
  151.     UNZOOMWINDOW - This will expand SelectDoc's window to full-sized,
  152.                   and update the list of documents.  As mentioned
  153.                   before, running SelectDoc a second time has the same
  154.                   effect.
  155.  
  156.  
  157. NOTES
  158. -----
  159.     SelectDoc was done because the GUI RexxArpLib version I first
  160. attempted was too awkward.  It was also done so that I could finally
  161. write a "real" 2.0 program.  As such, it uses many of the new 2.0
  162. enhancements, such as ReadArgs(), GadTools, public screens, and so on.
  163. I've also tried to keep close to the 2.0 and TurboText's look, as well
  164. as the new interface guidelines from Commodore.
  165.  
  166.     SelectDoc was written in SAS/C on a 3000, using the Ed text editor.
  167. (Just kidding... of course I used TurboText! :-)
  168.  
  169.     Thanks to:
  170. - Martin Taillefer for TurboText and answering my questions about it.
  171. - David Junod for helping me get the keys to "work" their gadgets.
  172.  
  173. - And, as always, Kate Bush for singing to me while I worked, and while
  174.   I didn't.
  175.  
  176.  
  177.     You can reach me via:
  178.  
  179. Phone: 914-639-5001 (voice), BIX: sizel, DevCon 91: I hope
  180.  
  181.  
  182.