home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 384.lha / Ctype_v2.0 / CType2.doc < prev    next >
Text File  |  1990-06-11  |  35KB  |  932 lines
  1.  
  2.    --------------------------------------------------------------------
  3.              Ctype 2.0    Bill Nelson - Midnight Logic Software
  4.    --------------------------------------------------------------------
  5.  
  6.                 THIS IS A FREELY REDISTRIBUTABLE PROGRAM
  7.  
  8.  
  9.              This means that it *IS* copyrighted, but it may be
  10.              distributed without charge other than for media. It
  11.              may be placed on BBS's, it may be kept in User Group
  12.              Libraries, and of course (a SPECIAL CASE) it may be
  13.              used by Fred Fish as he might decide!  Enjoy...
  14.  
  15.    ---------------------------------------------------------------------
  16.  
  17.    Any questions, suggestions, or neat stuff of your own may be sent to:
  18.  
  19.                               Bill Nelson
  20.                            8D-2310 Gaetz Ave
  21.                            Red Deer, Alberta
  22.                                 CANADA
  23.                                T4R  1C5
  24.  
  25.                              or to SYSOP at
  26.  
  27.                             Fly-By-Wire BBS
  28.                              403-346-9965
  29.  
  30.                           300/1200/2400 24 hrs
  31.  
  32.    (if you really feel like sending money - don't let anything stop you!
  33.     but I would rather have neat things that YOU programmed if possible.)
  34.  
  35.    ----------------------------------------------------------------------
  36.  
  37.    QUICK DOCS
  38.    ----------
  39.  
  40.  
  41.    Make sure that REQ.LIBRARY is copied into your systems currently
  42.    assigned LIBS: drawer before attempting to run this program.  If
  43.    you do NOT do this, you will get a message saying
  44.  
  45.   'You need V1+ of req.library'
  46.  
  47.    If you attempt to start it from the WorkBench, and the library is
  48.    not present, you get NOTHING as a result!
  49.  
  50.    Fire it up, and select a text file from the requester. OR use it
  51.    in any normal WorkBench way - multi-select and all.  Help that
  52.    MAY be sufficient is available for the price of a tap on the
  53.    HELP key!  If that isn't enough - more extensive docs follow ...
  54.  
  55.    
  56.  
  57.    QUICK CHANGES for V2.0:
  58.    ------------------------
  59.  
  60.  
  61. RESIDENT     1) Fully residentable - keep it handy in memory without
  62.                 tieing up a RAMdisk.  Also means multiple invocations
  63.                 of the program, running simultaneously, incur a memory
  64.                 cost of about 1300 bytes (plus the file!) after the
  65.                 first is running.
  66.  
  67. RESIZE       2) Related to above, you can now resize the window at any
  68.                 time, however you wish.  CType knows automatically that
  69.                 you have done so, and will display the file as sensibly
  70.                 as it can within the new window.  See also MODE.
  71.  
  72. TABS         3) Properly handles tabs now - you pick the size between
  73.                 2 and 10.  Defaults to AmigaDOS normal size of 8.
  74.  
  75. TITLEBAR     4) Now shows the current FileName in the titlebar.
  76.  
  77. SCROLLING    5) Scrolling in any direction is possible, depending on the
  78.                 MODE.  Program will exit only on specified EXIT keys.
  79.  
  80. MOUSE        6) The Left mouse button is equivalent to the Spacebar
  81.                 or any PgDn key.  Can be handy if you started the
  82.                 read with a mouse.
  83.  
  84. FORMATTING   7) Now does ALL its formatting "on the fly", according to
  85. MODE            your specifications.  The default mode is to run a long
  86.                 line "off the end" of the screen, and allow you to scroll
  87.                 over to the right to view the missing portion.
  88.  
  89.                 If you choose have it wordwrapped to your current size
  90.                 of window, no problem - and the program will automatically
  91.                 select the Format MODE on its own if any lines in the
  92.                 file exceed the buffer size (512 bytes).  The MODE
  93.                 setting is displayed in the PROMPT bar at the bottom of
  94.                 the screen (if the window is wide enough!), using an
  95.                 (N) for normal mode, and (F) for formatted text.
  96.  
  97. REQUESTERS   8) This program now makes use of the freely redistributable
  98.                 REQ.LIBRARY, which arrived on my doorstop with the new
  99.                 release of CygnusEdPro 2.0 (** WONDERFUL EDITOR **). This
  100.                 means you get the best FileRequester on the Amiga, along
  101.                 with simple requesters for any interaction with the
  102.                 program other than single command keystrokes.
  103.  
  104. WORKBENCH    9) FULL WorkBench support this time - works if you just
  105.                 double-click its icon - or if you SHIFT-click any number
  106.                 of other icons, then SHIFT-double-click it - or if you
  107.                 have the Default Tool of a file set to call it.
  108.  
  109. MULTI-ARGS  10) Another bonus from the REQ.LIBRARY, you get multiple
  110.                 file selection from the file requester, whether or not
  111.                 you start from the CLI.  Works in the most logical
  112.                 fashion possible - SHIFT-CLICK your choices in the
  113.                 file requester.
  114.  
  115.                 As mentioned above, multi-args selected from the WorkBench
  116.                 environment are also honoured.
  117.  
  118. ANY TEXT    11) As text files come to an Amiga from all sorts of differing
  119.                 sources ( BBS's, commercial networks, word processors,
  120.                 Unix and other operating systems, other personal computers)
  121.                 I have attempted to handle "durn near anything" that is
  122.                 covered by the term TEXT FILE.  This means that it does
  123.                 NOT MATTER whether the end of line character has a value
  124.                 of 10 (LineFeed), 13 (Carriage Return) or even BOTH (CR/LF)
  125.  
  126.                 Between that fact, and the formatting provisions, you
  127.                 should be able to read anything that comes your way
  128.                 in ASCII TEXT format.
  129.  
  130.  
  131.    ----------------------------------------------------------------------
  132.  
  133.    WHY I DID IT
  134.    ------------
  135.  
  136.       The Amiga is a wonderful machine, but it is NOT the most accessible to
  137.    those just trying to learn to program it (especially in Assembly!).  Most
  138.    of the source code out there is in C, and is thus mostly inscrutable- and
  139.    the machine is QUITE complicated enough (with its rich environment of
  140.    System routines) without one also needing a translator for the examples!
  141.  
  142.       So - as a result of that, I decided to attempt a small, useful program
  143.    in Assembly - figuring that by the time it was running as desired, I
  144.    would know a great deal more.  The next problem, of course, was WHAT to
  145.    write! The sheer volume of Freely Redistributable software (especially
  146.    utilities!) is almost overwhelming - and there aren't many gaping holes
  147.    anymore!  However, ONE thing I hadn't seen done in a way I liked was a
  148.    TEXT FILE READER.
  149.  
  150.    What?  ANOTHER Text Reader program?  What about MORE - LESS - VIEWER -
  151.    RD - READER - TEXTDISPLAY - MUCHMORE and others?   'Fraid so - another
  152.    one - and here are the reasons.
  153.  
  154.  
  155.    1) Many of these programs have insisted on a certain SIZE OF
  156.       FONT, or NUMBER OF LINES, or even on opening their OWN SCREEN.  As
  157.       I run with either an 11 or 14 point font, on a screen of 698 X 470
  158.       that "choosing for me" drives me NUTS!
  159.  
  160.    2) Many of them insist on SCROLLING through a file, rather than jumping
  161.       ahead a page at a time.  Many that DO jump a page, still SCROLL to
  162.       get there.  It is MUCH faster on a large screen to CLEAR THE SCREEN
  163.       (thus the name CType - for CLS_TYPE) first and get something readable
  164.       on it right away.  Of course, I allow scrolling in all 4 directions
  165.       as appropriate.
  166.  
  167.    3) Many of them make multiple invocations difficult or wasteful of memory
  168.       by not being RESIDENTable.
  169.  
  170.    4) None of the other ones I have seen will allow full RESIZING, for
  171.       shoving them out of the way - or lining up a few of them for
  172.       visual comparison purposes.
  173.  
  174.    5) Few of them did anything ELSE with the file except display it - and
  175.       those that did insisted on doing it only one way (or to the whole
  176.       thing!).  I like to PRINT interesting PARTS of files to another
  177.       file for later reference - NOT the whole thing!
  178.  
  179.    6) None of the others seem to be capable of making sense of FILES FROM
  180.       OTHER SYSTEMS, or even from the "capture buffer" of your terminal
  181.       program (without being run through a conversion program first). I
  182.       also wanted to be able to handle "WORD PROCESSING" files, which do
  183.       not have line-ending characters, only paragraph ends.
  184.  
  185.    7) Many of them are TOO BIG for what they do for you - though there are
  186.       some glorious exceptions to this (QView comes to mind).  I tried to
  187.       keep this under the size of the MORE program that comes with WorkBench
  188.       1.3, and sort of succeeded ( about 8.5K for the program itself)
  189.     
  190.    So - Presenting CTYPE (or CT, when installed in your C: directory?)
  191.  
  192.    ----------------------------------------------------------------------
  193.  
  194.     FEATURES:
  195.     ---------
  196.  
  197.    1) Opens a window on your WorkBench screen, using the current settings
  198.       from YOUR preferences (including any MoreRows'd additions).  This
  199.       INCLUDES any possible PAL or NTSC settings.  Might have trouble
  200.       with a display more than 999 pixels across though! :-) (Anyone want
  201.       to send me a monitor that I can test on?)
  202.  
  203.  
  204.    2) Does not disturb, and will USE the font YOU have chosen (for instance
  205.       with SetFont) [thanks Dave Haynie!]  Important for those running with
  206.       11 points as a default, for example.
  207.  
  208.  
  209.    3) Have you ever been annoyed at a file that was written to be a LITTLE
  210.       WIDER than YOUR screen defaults?  Optional word-wrap should lessen
  211.       that problem for you - at least you can have the whole WORD on the
  212.       next line! 
  213.  
  214.  
  215.    4) Because of the format routine mentioned above, it will also correctly
  216.       handle a "word processing" file, which has an "end of line" character
  217.       only at the end of each paragraph. 
  218.  
  219.  
  220.    5) Will correctly handle any common method for signalling an end of line,
  221.       or end of paragraph.  This includes the LineFeed character (Amiga
  222.       standard, Unix) the Carriage Return ( Terminals, Mac, C64 ) or the
  223.       combination of both CR and LF (IBM compatibles, CP/M).
  224.  
  225.  
  226.    6) Will allow progress through the file by PAGE or LINE in any direction.
  227.       When displaying by PAGE will clear the screen (leading to a consider-
  228.       able speed-up on LARGE screens).
  229.  
  230.  
  231.    7) Will facilitate moving through a file by allowing both CASE SenSitIve
  232.       and non sensitive searches.  A touch of the "N" key will repeat the
  233.       last search command (maintaining the state of case sensitivity).
  234.  
  235.  
  236.    8) Allows the reading of files to be broken up into convenient sessions,
  237.       by supporting a "goto this place" function - or more accurately, goto
  238.       a given percentage.
  239.  
  240.  
  241.    9) If you find something interesting, you can get hardcopy at any time,
  242.       either of the whole file, or of the currently displayed screen.  Of
  243.       course, YOU define WHERE the printing goes, any valid AmigaDOS file
  244.       or port will be accepted (with PRT: the default of course).
  245.  
  246.  
  247.   10) Will work from either the CLI or the WorkBench - because the Amiga 
  248.       has BOTH for a good reason :-)
  249.  
  250.  
  251.   11) Always has HELP available, and the basic prompts are always displayed.
  252.       Yes, and the help is actually selected by the HELP key!  
  253.  
  254.  
  255.   12) If all this is NOT enough - (and sometimes it isn't!) - just call up
  256.       your EDITOR.  If you have an entry in your environment by the name
  257.       of EDITOR, it will be called with a command line including the name
  258.       of the file you are currently viewing. If nothing is found in 
  259.       ENV:EDITOR, a requester will ask you for a choice at that time.
  260.  
  261.  
  262.   13) Fully "pure" code (I trust - WShell doesn't complain!) - so you can
  263.       keep it resident - and run more than one at one time from the same
  264.       memory image.
  265.  
  266.  
  267.   14) As a result of the above, I decided it needed the ability to handle
  268.       a resized window properly.  You can arrange it any way you want,
  269.       and the text will be displayed as sensibly as can be managed.  Of
  270.       course, if the window is not as wide as the length of a single word,
  271.       that word will be broken up across lines as needed.  Formatting of
  272.       the text will be determined by the MODE you have set.
  273.  
  274.  
  275.   15) Never thought to mention it before - but it fully supports the usual
  276.       colour changes, and other attributes that can be displayed on a
  277.       normal CLI window with the "TYPE" command - because it runs in a
  278.       normal CLI window  :-)
  279.  
  280.  
  281.   16) Major addition - REQ.LIBRARY.  All possible operations that could be
  282.       handled by a requester now do so.  You get the best filerequester
  283.       I've seen on the Amiga, along with mouse or key activation of nearly
  284.       every interactive action of the program.  See the Requester docs for
  285.       operation of the requesters.
  286.  
  287.  
  288.   17) Minor addition - you can use the Left mouse button as a substitute for
  289.       the SPACEBAR or PgDn keys.  Sometimes a nicer way to browse.  Anyone
  290.       know how to get the Mouse Position Report stuff from RAW: ?
  291.  
  292.  
  293.    -------------------------------------------------------------------------
  294.  
  295.  
  296.    USING THE PROGRAM
  297.    -----------------
  298.  
  299.    It certainly isn't terribly hard to start using - just start it up from
  300.    your choice of the WorkBench or the CLI.  IF starting from the CLI, you
  301.    can give it an optional Filename to start displaying - if from the
  302.    WorkBench, the usual CLICK on a file icon, followed by SHIFT-DOUBLE-CLICK
  303.    on the program icon will do the job as well (as many files as desired
  304.    from the WorkBench - up to 65536 anwyay!).
  305.  
  306.    If you haven't specified a name, a file requester will appear for you to
  307.    choose a file from - one or as many as desired.
  308.  
  309.    The program, after learning of a name, will load and run a quick check of
  310.    the contents of the file to make sure that it contains TEXT and not much
  311.    else.  If it finds anything dubious, it will pop up a requester warning
  312.    you that it found "NON-ASCII characters", and asking if it should try to
  313.    display it anyway.  If you say YES, it will continue checking for more
  314.    problem characters - which could lead to LOTS of requesters!  IF you get
  315.    more than a couple of them, better assume the file is NOT text!
  316.  
  317.    For those interested, the characters checked for are any with ASCII
  318.    values OVER 127 (hi bit set) and the CTRL-N (SHIFT-OUT).  A binary file
  319.    without some of these is a RARE beast indeed, and the SHIFT-OUT char is
  320.    capable of rendering your text a complete MESS!  Other than those, pretty
  321.    much anything goes - so ESCape sequences to change colours and so on will
  322.    all work just as they would with the TYPE command - with the possible
  323.    exception that CURSOR movement commands can confuse the programs sense of
  324.    where on the page it is!
  325.  
  326.  
  327.    Not much more to say here - it is NOT a fancy user interface, (one of the
  328.    MAIN goals was to keep this SMALL and HANDY!) but I like to think it IS
  329.    an effective one.  Rather than stick with one person's idea of the
  330.    "right" keys to use for a given result, I have attempted to allow the use
  331.    of ALL the keys that make ANY sense at all, or have been expected by
  332.    convention.  In particular this meant that the Page Down function
  333.    (for instance) can be called by ANY of the following:
  334.  
  335.    the SPACE bar      - by convention in countless MORE-type programs
  336.    shifted cursor key - by logic
  337.    PgDn Key (num pad) - so people who have to work on PC's can use it too!
  338.    Left Mouse Button  - why not?
  339.  
  340.    Most of the rest of the commands are implemented in a similar way, so
  341.    pretty much anything can be done the way you like it.  Those commands
  342.    (such as Search and Goto %) that require input from you will call up a
  343.    requester, with (hopefully) obvious conventions of operation.
  344.  
  345.    By the way, the number pad commands (PgDn, PgUp, Home etc) were
  346.    implemented the "cheap" way, so that the number that is on the top of the
  347.    key will work as an alternative input.  In particular that means that
  348.    A1000 users can also hit the "3" key, even though their keyboard doesn't
  349.    SAY it calls PageDown!  Of course, as an A1000 does not HAVE a PrtSc key
  350.    (based on the number pad's * key) - they will have to call that function
  351.    from the top row of the main keyboard, or perhaps from the F7 key if they
  352.    prefer.
  353.  
  354.    Due to the way in which I have used the REQ.LIBRARY in this program, and
  355.    the fact that it hasn't been around very long, it might be worth your
  356.    while to check out the features of the File Requester, - at least those
  357.    HIGHLIGHTED by ALL CAPS headings.  There are a few VERY nice features in
  358.    these requesters - especially if you are familiar with them (and even if
  359.    you DON'T generally read docs!)
  360.  
  361.    One final note on usage - I have this program in the C: directory as CT,
  362.    and hiding in the S: directory is a little script file (included in the
  363.    archive, but easily duplicated!) I call HT; which makes a RAM: copy of
  364.    the output of the TYPE OPT H command, and feeds THAT to CType.  This
  365.    enables this program to handle binary files too! :-)   Of course, under
  366.    1.3 you can have the script bit set, and make the file automatically
  367.    executable when you enter its name - without having to type "EXECUTE HT"
  368.    to make it run....  should do until I add a HexType mode as well ...
  369.  
  370.  
  371.    -------------------------------------------------------------------------
  372.  
  373.  
  374.    COMMANDS IN DETAIL
  375.    ------------------
  376.  
  377.  
  378.    Command        Numeric    Cursor key     Equivalents
  379.      Key            pad
  380.  
  381.  
  382.  
  383.    PageDown
  384.    --------
  385.  
  386.    KEYS:
  387.  
  388.    <SPACE BAR)    (PgDn)    (SHIFT-DOWN)     (3)     (MOUSE CLICK)
  389.  
  390.    If the display is not already at the bottom of the file, will cause the
  391.    screen to be cleared, and the next screenfull to be displayed.  This
  392.    programs defines a PAGE to be the size of the window it has at that
  393.    moment to work with.
  394.  
  395.  
  396.    PageUp
  397.    ------
  398.  
  399.    KEYS:
  400.  
  401.    (BACKSPACE)    (PgUp)    (SHIFT-UP)       (9)
  402.  
  403.    If the display is not already at the top of the page, will cause the
  404.    screen to be cleared, and the previous screenfull to be shown.  If this
  405.    movement would take you "past the beginning" of the file, one full page
  406.    will be shown from the beginning of the file.
  407.  
  408.  
  409.  
  410.    LineDown
  411.    --------
  412.  
  413.    KEYS:
  414.  
  415.    (RETURN)       (DOWN)    (DOWN)           (2)
  416.  
  417.    If the display is not at the bottom of the file, will cause the display
  418.    to be scrolled up, and the next line displayed.
  419.  
  420.  
  421.  
  422.    LineUp
  423.    ------
  424.  
  425.    KEYS:
  426.  
  427.    (DEL)          (UP)      (UP)             (8)
  428.  
  429.    If the display is not at the top of the file, will cause the display to
  430.    be scrolled down, and the previous line inserted at the top.
  431.  
  432.  
  433.  
  434.    ScrollRight
  435.    -----------
  436.  
  437.    KEYS:
  438.  
  439.    (R)            (RIGHT)   (RIGHT)
  440.  
  441.    This command will cause the screen to be redrawn 10 characters to the
  442.    right of its previous position - to allow the end of a long line to be
  443.    seen.  It jumps by 10 characters each time it is called, to a maximum of
  444.    120.
  445.  
  446.    NOTE:  If FORMAT mode is active, this command is disabled!
  447.           (as it would serve no purpose!)
  448.  
  449.  
  450.  
  451.    ScrollLeft
  452.    ----------
  453.  
  454.    KEYS:
  455.  
  456.    (L)            (LEFT)    (LEFT)
  457.  
  458.    This command will cause the screen to be redrawn 10 characters to the
  459.    left of its previous position - if you are not already displaying the
  460.    beginning of a line.
  461.  
  462.    NOTE:  If FORMAT mode is active, this command is disabled!
  463.           (as it would serve no purpose!)
  464.  
  465.  
  466.  
  467.    GotoTop
  468.    -------
  469.  
  470.    KEYS:
  471.  
  472.    (<)            (HOME)    (SHIFT-LEFT)
  473.  
  474.    This command will clear the screen and display the file again from the
  475.    beginning.
  476.  
  477.  
  478.  
  479.    GotoBottom
  480.    -------
  481.  
  482.    KEYS:
  483.  
  484.    (>)            (END)     (SHIFT-RIGHT)
  485.  
  486.    This command will clear the screen and display the file again from the
  487.    beginning.
  488.  
  489.  
  490.  
  491.    ESC/QUIT/NextFile
  492.    -----------------
  493.  
  494.    KEYS:
  495.  
  496.    (Q)                      (ESC)            (F10)
  497.  
  498.    This command will abort the display of the current file, and will then
  499.    display the next file that you have selected.  If no further files have
  500.    been selected, you will get a requester inquiring for your intentions
  501.    (Load another file, or EXIT)
  502.  
  503.  
  504.  
  505.    UNCONDITIONAL Exit
  506.    ------------------
  507.  
  508.    KEYS:
  509.  
  510.    (CTRL-C)
  511.  
  512.    This command will cause the program to be exited, regardless of any
  513.    remaining undisplayed files.
  514.  
  515.  
  516.  
  517.    TabSize
  518.    -------
  519.  
  520.    KEYS:
  521.  
  522.    (TAB)
  523.  
  524.    This command will cause a requester to appear, with the current setting
  525.    of the tab size in it.  Press (RETURN) to leave it unchanged, or change
  526.    it to any value between 2 and 10 as you wish. Much of the source code
  527.    out there was written with a tab size of 3 - so now you can view it as
  528.    the programmer wrote it...
  529.  
  530.  
  531.  
  532.    FormatMode
  533.    ----------
  534.  
  535.    KEYS:
  536.  
  537.    (F)
  538.  
  539.    This command allows a little flexibility in the way that the file is
  540.    displayed.  When in Normal mode (shown by a MODE = N in the prompt)
  541.    a long line will "disappear off the end" of the screen, and can be
  542.    retrieved by use of the ScrollRight and ScrollLeft commands.  Giving
  543.    this command will cause the line instead to be formatted with word
  544.    wrapping to the current size of your window.  This will be indicated
  545.    by a MODE = F  in the prompt.
  546.  
  547.    If a file contains lines longer than 512 characters, FORMAT mode will be
  548.    entered automatically, and you will NOT be able to change it on that
  549.    file.
  550.  
  551.  
  552.  
  553.    SearchString
  554.    ------------
  555.  
  556.    KEYS:
  557.  
  558.    (/)
  559.  
  560.    This command causes a requester to appear, in which you enter the exact
  561.    text you wish to find.  This version of the command is Case Sensitive,
  562.    meaning that 'TesT' is NOT EQUAL to 'test'.  If the text is found, the
  563.    screen will be redisplayed with it contained in the TOP line of the
  564.    screen.  No other highlighting is done.  It may be repeated with the
  565.    (N)ext command.
  566.  
  567.  
  568.    SearchString
  569.    ------------
  570.  
  571.    KEYS:
  572.    
  573.    (.)
  574.  
  575.    This command is equivalent to the above, except that the search is NOT
  576.    case sensitive.  If you enter 'TeSt' it will match with 'test', 'Test'
  577.    and any other permutations of upper and lower case.
  578.  
  579.  
  580.    
  581.    NextOccurence
  582.    -------------
  583.  
  584.    KEYS:
  585.  
  586.    (N)
  587.  
  588.    This command will repeat the previous search from the current location
  589.    in the file.  Retains any characteristics of the previous search,
  590.    including the state of case sensitivity.  If the string is not found,
  591.    the page from which it STARTED will be redisplayed. 
  592.  
  593.  
  594.  
  595.    GotoPercent
  596.    -----------
  597.  
  598.    KEYS:
  599.  
  600.    (%)
  601.  
  602.  
  603.    This command will pop up an empty numeric requester, that will accept
  604.    values between 0 and 100, and then attempt to display from approximately
  605.    that percentage of the file.
  606.  
  607.  
  608.  
  609.    CallEditor
  610.    ----------
  611.  
  612.    KEYS:
  613.  
  614.    (E)
  615.  
  616.    This command will attempt to call up your favourite editing program, and
  617.    pass it the name of the file you are currently viewing.  To determine
  618.    what that editor might be, it looks for an entry in your environment by
  619.    the name of EDITOR.  In practise at the moment, this means a file in
  620.    your currently ASSIGNED ENV: directory, by the name of EDITOR.  IF this
  621.    entry is not found, a requester will attempt to discover your choice.
  622.    Enter in the path and name of your editor, and we'll give it a try.
  623.    (eg: c:ed - as mine reads for CygnusEdPro)
  624.  
  625.  
  626.  
  627.    PrintFile
  628.    ---------
  629.  
  630.    KEYS:
  631.  
  632.    (P)                                       (SHIFT-F7)
  633.  
  634.    This command will cause the file requester to re-appear, and solicit
  635.    a destination for this copy of the file.  It will default to PRT: if
  636.    you just hit (RETURN), but you can enter ANY valid AmigaDOS file, and
  637.    the WHOLE FILE will be "printed" there.
  638.  
  639.    If the FILE exists already, another requester will appear to inquire
  640.    whether you want to APPEND to the existing file (add on the end) -
  641.    OVERWRITE the existing file (replace it) or CANCEL the whole operation.
  642.  
  643.  
  644.  
  645.    PrintScreen
  646.    -----------
  647.  
  648.    KEYS:
  649.  
  650.    (*)            (PrtSc)                    (F7)
  651.  
  652.    Use of this command operates similarly to PrintFile, but will result
  653.    only in the CURRENTLY DEFINED PAGE being printed to your chosen
  654.    destination.
  655.  
  656.    NOTE:
  657.  
  658.    The definition of the CURRENT PAGE will match what you see which leads
  659.    to an extra measure of flexibility - you can define fairly precisely
  660.    just what will be printed by scrolling and resizing the window as 
  661.    necessary to "frame" just what you want in the resulting file.  Of
  662.    course, if what you want to print exceeds 1 screen full, you can APPEND
  663.    other sections as required.
  664.  
  665.  
  666.    
  667.    Help
  668.    ----
  669.  
  670.    KEYS:
  671.  
  672.    (H)                      (HELP)           (?)     (F1)
  673.  
  674.    Touching any of the above keys will cause a requester to appear
  675.    with a reminder of all of the commands that this program recognizes,
  676.    and a question: (MORE HELP?)   Choosing YES will cause the second 
  677.    "page" of commands to appear, and NO will cause your return to the 
  678.    main program.
  679.  
  680.  
  681.  
  682.  
  683.    -----------------------------------------------------------------------
  684.  
  685.  
  686.  
  687.    THE FILE REQUESTER
  688.    ------------------
  689.  
  690.    This came attached to the files I received: should speak for itself!
  691.  
  692. =============================================================================
  693. Official release of version 1.22, Jan '90
  694.  
  695.  
  696. Req.library  is Copyright ©1989, 1990 by C.W.  Fox and Bruce Dawson.  It is
  697. freely  distributable.  No charge may be made for it's distribution, except
  698. for a nominal media fee.
  699.  
  700.      Feel free to distribute and use this library with your programs, along
  701. with a notice that the library is 'FreeWare'.
  702.  
  703. =============================================================================
  704.  
  705.  
  706.    This program was written with the aid of the above redistributable
  707.    Requester library.  This library was first released on the disk
  708.    with CygnusEdPro from ASDG. (a GREAT editor :-)
  709.  
  710.    Here is a USER GUIDE of sorts for you...
  711.  
  712.  
  713. BASIC REQUESTER USAGE
  714.  
  715.    You probably have some familiarity with file requesters, if you have used
  716.    your Amiga for any length of time - but this one has more flexibility
  717.    than most of the alternatives - and thus perhaps needs a bit of an
  718.    explanation.
  719.  
  720.    The requester will open up a LARGE window on your screen (I have it set
  721.    to display up to *40* files if your screen is big enough!), containing
  722.    several Boxes within it - all with specific purposes.
  723.  
  724.    At the very TOP of the requester is a Title bar, containing, from left to
  725.    right, a CLOSE GADGET (for cancelling it) a descriptive TITLE (which
  726.    should tell you what operation you are selecting files for) and the usual
  727.    system BACK and FRONT GADGETS.
  728.  
  729.    Next is a line describing the files it has found in the current directory,
  730.    and specifying how many it has shown, or hidden in the main area.
  731.  
  732.    Directly under this is a PARENT gadget, which will return you one level
  733.    up in the directory tree, if there IS a higher level.  This could
  734.    change, for example, the file list from those for RAM:Work to those
  735.    for RAM:
  736.  
  737.    Now there is the MAIN or FILE area.  In this are displayed all the files
  738.    in the current directory that match the conditions set elsewhere. They
  739.    will first appear in the order they are found, but a click in the
  740.    accompanying SCROLL GADGET will SORT them for you.  You will notice that
  741.    in this usage, the FILES and the DIRECTORIES are displayed in different
  742.    colours, for easing your recognition.  Files additionally have their
  743.    SIZE in BYTES displayed to the right of the box, while directories have
  744.    the word (dir) displayed to their right.
  745.  
  746.    To the right of the FILE area and its scroll bar is the DEVICE area.  In
  747.    it is a sorted list of all available DEVICES that could be located in
  748.    your system. This includes floppy drives, hard drive partitions, and even
  749.    assigned names that you have set up.  This area is also accompanied by a
  750.    scroll bar should not all entries fit in the "window" available.
  751.  
  752.    Under the FILES area are located two STRING GADGETS, labelled for
  753.    DRAWER and FILE respectively.  The contents of these two boxes reflect
  754.    the choices you have made.  You may type directly directly into them
  755.    to change their contents at any time.  If a COLOURED BLOCK shows up
  756.    in a block, then your typing will be directed into that box.
  757.  
  758.  
  759.    To the right of these are two more STRING GADGETS, labelled HIDE and
  760.    SHOW.  These may be used by those familiar with WILDCARDS to restrict
  761.    the display in the FILES area to those that match whatever criteria
  762.    you choose.
  763.  
  764.    The final lineon the bottom consists of three small gadgets, labelled
  765.    as OK     GET DIR  and CANCEL.
  766.  
  767.    Clicking on OK will cause the requester to leave, and the current contents
  768.    of the DRAWER and FILE boxes are taken as your choice.
  769.  
  770.    Clicking on GET DIR will cause the requester to rebuild its list of files
  771.    in the FILES area.  The requester remembers where you were last time, and
  772.    will reflect your previous choices.  It also remembers the contents of
  773.    the directory - and will NOT know of any changes you have made since the
  774.    time it last read it.  Use this whenever you doubt that it is displaying
  775.    the true state of affairs.
  776.  
  777.    Clicking on CANCEL will have the same effect as clicking on the close
  778.    gadget in the title bar - you will be assumed to have NOT made a choice.
  779.  
  780.  
  781.    Typical use of the File Requester will have you seeing the file you wish
  782.    in the FILE area, and clicking on it.  This will cause the name you choose
  783.    to show up in the FILE box, and a click on OK will return this to the
  784.    program as your choice.  Alternatively you can click QUICKLY twice on the
  785.    filename, with the same effect.  Clicking on a (dir) entry will cause
  786.    the requester to display the contents of the directory you chose
  787.    (if any), and between this, the DEVICE list, and the PARENT gadget you
  788.    can go ANYWHERE in your file system and display any file there is
  789.    available in your FILES area.
  790.  
  791.  
  792. KEYBOARD FEATURES
  793.  
  794.    When the requester first comes up, the CURSOR will be in the FILE
  795.    box, and any typing you do will appear there - so if the directory
  796.    is correct you can just enter the name you wish, and strike (RETURN).
  797.  
  798.    If you need to change the directory, you can use SHIFT-RETURN to
  799.    activate the DRAWER BOX, enter a directory name, and then striking
  800.    (RETURN) will return you to the FILE box.
  801.  
  802.    If you wish to change the contents of the HIDE or SHOW boxes, they
  803.    can be reached by using either ALT key with RETURN, and then you
  804.    can switch between them with the same SHIFT-RETURN.  Hitting RETURN
  805.    in either HIDE or SHOW will return to the FILE box.
  806.  
  807.    RIGHT-AMIGA-L will cause CANCEL to be selected for you.
  808.  
  809.  
  810. MULTI-SELECT
  811.  
  812.    Often it can be handy to select more than one file at a time, if you
  813.    know you have a few to work on.  This program allows it, and the
  814.    requester supports it in the most logical way.  In the same way
  815.    as you can select multiple icons from the WorkBench by clicking on
  816.    one, then holding SHIFT and clicking on others - you can do it to
  817.    the filenames shown in the FILES area.  Double clicking on the last
  818.    one, or choosing OK will cause the whole list to be passed on to the
  819.    program as your choices.
  820.  
  821.  
  822. HIDE and SHOW
  823.  
  824.  
  825.    Any single instance of the AmigaDOS wildcards (or the ARP ones :-) can
  826.    be used to restrict the files shown in the main part of the requester -
  827.    which can reduce confusion considerably.
  828.  
  829.    For example, if you are programming, your current directory is likely
  830.    to be cluttered up with .o files.  An entry of #?.o in the HIDE box
  831.    will prevent their display in the FILES area.  The top text line will
  832.    inform you of how many files are shown and how many are hidden.
  833.  
  834.    You can extend the checking by using the AmigaDOS convention of using
  835.    a vertical bar | as an OR operator - so to hide BOTH files ending
  836.    in .o and files ending in .i, then the entry should read like
  837.    #?.o | #?.i - and neither would show up in the FILES area.
  838.  
  839.    The SHOW gadget works similarly, but has priority over the HIDE gadget
  840.    should both contain specifications of this type.
  841.  
  842.    By the way - "nested" definitions are NOT decoded, for the previous
  843.    example the AmigaDOS legal  #?(.o|.i) specification will NOT work.
  844.  
  845.    Also - I have enabled a feature separate from the Hide and Show boxes
  846.    that keeps any file ending in .info from showing up in the requester.
  847.    You should NEVER have a reason to see those files in here, as you do
  848.    NOT generally READ a .info file! :-)
  849.  
  850.  
  851.  
  852. OTHER REQUESTERS
  853.  
  854.    Most of the other requesters operate in a similar manner where
  855.    similarity exists, but with a few additional conveniences.  In
  856.    particular, several keyboard shortcuts exist as equivalents of
  857.    selecting a particular gadget.
  858.  
  859.    (ESC) (Q) (B) (LEFT-AMIGA-B) (N) are all the same as selecting the
  860.    CANCEL gadget on any other requester that appears here.  The
  861.    CANCEL gadget will always be the one on the RIGHT BOTTOM corner
  862.    of that requester...
  863.  
  864.    (you will notice that means that (ESC)ape, and (Q)uit and (N)o are
  865.    understood, as well as the Intuition managed LEFT-AMIGA-B and its
  866.    no-shifted B - for similar behaviour as system requesters..)
  867.    
  868.  
  869.    (Y) (LEFT-AMIGA-V) are the same as selecting the POSITIVE gadget, which
  870.    will be the one on the LEFT BOTTOM of the requester.
  871.  
  872.    -you will notice these correspond to (Y)es and to the system-managed
  873.    LEFT-AMIGA-V and V keystrokes.-
  874.       
  875.  
  876.    If there is a middle gadget, the only shortcut for it is to use
  877.    the (M) key...
  878.  
  879.  
  880.    RIGHT-AMIGA-L should CANCEL any requester that appears...   
  881.  
  882.  
  883. ---------------------------------------------------------------------------
  884.  
  885.  
  886.    LAST THOUGHTS
  887.    -------------
  888.  
  889.    
  890.    I had a LOT of fun writing this program (and yes, I think I *DID* learn
  891.    something).  In hopes of making it easier for someone else just learning
  892.    Assembly on the Amiga, the source code is included.  Perhaps SOME of the
  893.    code (and comments) will make it easier to see how it all works.  PLEASE
  894.    feel free to use any of the code you wish in programs of your own that
  895.    are intended for free distribution - but include a reference in your docs
  896.    or source to the person who sweated it out first, OK?  I retain the
  897.    copyright to the code as whole, and do not wish any commercial use to be
  898.    made of the program (not that any of the code is that good, probably, 
  899.    anyway :-) unless I am contacted first...
  900.  
  901.    Thanks to David Choboter for creating an icon - that doesn't look as if
  902.    it came from someone who uses only the CLI (as it WOULD have otherwise!)
  903.  
  904.    Finally  - many thanks to the Beta testers (OK - entymologists!) who both
  905.    helped squash the bugs, and pestered me for improvements where they were
  906.    sorely needed!
  907.  
  908.                              Michael Velez
  909.                              Rob Zelt
  910.                              Brad Nelson
  911.                              Niel Ericson
  912.                              Doug McNeil
  913.  
  914.    and others from 
  915.  
  916.                         Amiga User's of Calgary
  917.                               (A.M.U.C.) 
  918.  
  919.    and the               
  920.  
  921.                    Central Alberta Amiga Owner's Society
  922.                              (C.A.A.O.S.)
  923.  
  924.  
  925.  
  926.    who also contributed.  Thank you one and all!!
  927.  
  928.  
  929.    Bill Nelson       00:00:01  3 May 1990
  930.  
  931.    -------------------------------------------------------------------------
  932.