The CDPD Public Domain Collection for CDTV 3/CDPDIII.bin/fish/791-800/ff793/snap/snap.doc

Text File | 1993-01-10 | 27KB | 712 lines

                     Snap 1.63
                     =========
               © Mikael Karlsson 1991


Is it Public Domain?

  Snap is NOT Public Domain. Snap is 'Freely distributable
  copyrighted software with a shareware option'.

  "Permission is hereby granted to copy Snap provided that
   the copyright notice and this document is left intact.
   Copies may not be made for profit. Modified copies may
   not be distributed without the author's prior consent."

  I don't know if the above should hold in court but what
  I mean is: Copy Snap if you want to but don't make a
  business of it. It is of course free to include it on
  public domain disks or putting it on a BBS.
  If you find Snap useful, please feel free to send a
  donation ($10 is a nice round number) or a nice program (PD).
  Please don't send personal checks. It costs me $5 to
  cash them. Or you can buy me a beer or two when we meet.
  If you wish to include Snap with a commercial product,
  please contact me first. I just want to make sure that
  my ego can stand for it. Of course it would also be nice
  with a registered copy of the product.
  (How about including it with a '040 card? ;-)


What Is It?

  Snap is the perfect tool for the lazy typer. Isn't it
  irritating when you look at something on the screen
  and think: "That is what I'm going to type."?
  What if you could just point at it and get the computer to
  type it for you? That's where Snap comes to the rescue.
  Another thing that irritates me is that I'm sitting in
  front of THE computer and still I must have pen and
  paper available to scribble down something from the screen
  that I know I will need later. Snap provides a solution
  to that problem also. Just frame it and Snap creates a
  window with a copy of the screen contents. Perfect for
  snapping text from later on. This is another idea borrowed
  from the computer scientists at Xerox Palo Alto Research
  Center (you know, the ones who invented the mouse, windows,
  icons and stuff like that).


The First Time

  To try Snap, do the following:
   1. Double click the Snap icon.
   2. Move the mouse over a character.
   3. Press and hold the left Amiga key.
   4. Press the left mouse button. A frame should appear around
      character you pointed at. If no frame appears, release
      the mouse button and the Amiga key, and start again at 2.
   5. Extend the selection by moving the mouse.
   6. When you're satisfied with the selection, release first
      the mouse button and then the Amiga key.
   7. You can now insert the text by holding down the left
      Amiga key and clicking the right mouse button.


Why Use Snap Instead?

   a. Snap finds out the character coordinates automatically.
   b. Snap uses the RastPort's current font, not just Topaz 8.
   c. Snap was written by me.
   d. Snap supports all fixed width fonts with width<16.
   e. Snap supports accented characters (128-255).
   f. Snap supports keymaps.
   g. Snap does both column and text oriented snapping.
   h. Snap snaps graphics.
   i. Snap uses the clipboard, making it compatible with TxED (and NotePad).
   j. Snap understands inverted characters.
   k. Snap understands bold characters.
   l. Snap understands underlined characters
   m. Snap does word oriented snapping.
   n. Snap has ants.
   o. Snap has a key combination to do insert.
   p. Snap supports Xerox style snapping with immediate insert.
   q. Snap prepends and appends characters.
   r. Snap saves graphics.
   s. Snap caches the character offsets between windows.
   t. Snap joins long lines.
   u. Snap supports ARexx to read and set prepend and append strings.
   v. Snap handles an extra pixel line between character rows.
   w. Snap supports an alternate font for snapping.
   x. Snap supports fonts of any height, settable at compile time.
   y. Snap caches the fonts between windows.
   z. Snap clips graphics to the clipboard.
   w. Snap supports Workbench tooltype arguments


Starting and Stopping

 From CLI
   Start Snap with 'run >nil: snap'.
   To remove Snap, execute 'snap -Q' (or snap QUIT).

 From Workbench
   Double click on the Snap icon to install Snap. Double click
   a second time to remove Snap.

   Make sure that you have 'clipboard.device' in devs:.

   Note that you can't remove Snap if you have any 'snapped'
   windows left.


Command Line Arguments

   Snap accepts a number of command line arguments. You can
   use either unix or Amiga style arguments.

   Usage:
    snap -pNN -tQQ -gQQ -iXX -wXX -Pstr -Astr -cNN -lNN
      -aXXXX -x -X -e -E -r -R -j -J -s -S -uN -bXX -CNN
      -BNN -Ffont -Q
    or
    snap PRIORITY/k TEXTQUAL/k GFXQUAL/k INSERTKEY/k CWKEY/k
      PREPEND/k APPEND/k CHARDELAY/k LINEDELAY/k CRAWLPTRN/k
      XEROX/s NOXEROX/s EARLYPATCH/s NOEARLYPATCH/s STARTUNIT/k
      TRUEUNDERSCORE/s FAKEUNDERSCORE/s JOINLONG/s NOJOINLONG/s
      SIMPLEREFRESH/s SMARTREFRESH/s PLANEMASK/k CACHESIZE/k
      BADCHAR/s ALTFONT/k QUIT/s

   o XX is hex, specified as 0xXXXX.
     Example: 0xF3

   o NN is decimal.

   o str is a string.

   o QQ are keyboard qualifiers. Qualifiers can be specified
     either as a hex value combined from the following list:
       0001    Left Shift
       0002    Right Shift
       0008    Control
       0010    Left Alt
       0020    Right Alt
       0040    Left Amiga Key
       0080    Right Amiga Key
       1000    Middle Mouse Button

     Example: 0x18 gives Left Alt+Control

     Or as a combination of the following strings (separate the
     qualifiers with '+'):
       LSHIFT          Left Shift
       RSHIFT          Right Shift
       CONTROL         Control
       LALT            Left Alt
       RALT            Right Alt
       LCOMMAND        Left Amiga
       RCOMMAND        Right Amiga
       MIDBUTTON       Middle Mouse Button

     Example: LALT+CONTROL gives Left Alt+Control

     Note: Combinations are allowed, in which case ALL of the elected
           qualifiers at once along with the left or right mouse button
           will cause the appropriate action to occur.

   o font is the name of a font, specified as 'fontname/size'.
     Exampel: Topaz/8

    -pNN
    PRIORITY NN
            where NN is the priority to use when installing
            the input handler. Default is 52. Note that it's
            not possible to change the priority of the input
            handler while Snap is running.
    -tQQ
    TEXTQUAL QQ
            where QQ is the text qualifier to use in text
            operations. Default is the left Amiga key.
    -gQQ
    GFXQUAL QQ
            where QQ is the graphics qualifier to use in
            graphics operations. Default is the right Amiga key.
    -iXX
    INSERTKEY XX
            where XX is the raw key code for the key to be used
            together with the left Amiga key as insert key.
            Use together with Shift to get modidified inserts.
            Use 0 to disable. Default is hex 17 ("I").
    -wXX
    CWKEY XX
            where XX is the raw key code for the key to be used
            together with the left Amiga key to open the Snap
            control window. Default is hex 11 ("W").
    -Pstr
    PREPEND str
            where str is the string that will be inserted in
            front of every line in a modified insert. Max
            length of the string is 16. Default is "> ".
            If you use the Unix style argument and need to
            enclose the string in quotes, add a space between
            the 'P' and the quoted string.
    -Astr
    APPEND str
            where str is the string that will be inserted after
            every line in a modified insert. Max length of the
            string is 16. Default is "".
            If you use the Unix style argument and need to
            enclose the string in quotes, add a space between
            the 'A' and the quoted string.
    -cNN
    CHARDELAY NN
            where NN is the amount of time that Snap should
            wait after each character inserted into the input
            stream. Default is 0.
    -lNN
    LINEDELAY NN
            where NN is the amount of time that Snap should
            wait after each carriage return inserted into the
            input stream. Default is 0.
    -aXXXX
    CRAWLPTRN XXXX
            where XXXX is a 16 bit number that specifies the
            pattern for the crawling ants. Use FFFF to turn
            the crawling off. If you specify 0 as the crawl
            pattern, Snap will use different patterns for
            each snapping mode (box/char/word/line).
            Default is 7777.
    -x
    XEROX
            tells Snap to use Xerox style snapping instead.
            The snapped text is inserted immediately it has
            been snapped.
    -X
    NOXEROX
            turns off Xerox style snapping.
    -e
    EARLYPATCH
            tells Snap to patch dangerous functions as soon as
            the text qualifier goes down. This is done automatically
            when you use Xerox style snapping.
    -E
    NOEARLYPATCH
            turns off early patching. This is default.
    -j
    JOINLONG
            tells Snap to join long lines. This means that Snap
            joins (removes the line feed between) two lines if
            the first line has a non-blank in the last position.
            This is not done in rectangular snapping.
    -J
    NOJOINLONG
            disables the join-long-lines behavior. This is default.
    -s
    SMARTREFRESH
            tells Snap to use smart refresh for the graphics snap
            windows. This is faster but uses up precious chip
            memory. This is default.
    -S
    SIMPLEREFRESH
            tells Snap to use simple refresh for the graphics snap
            windows. This saves chip memory but the refreshing of
            Snap's windows might be a bit slower than the smart
            refresh approach.
    -uN
    STARTUNIT N
            tells Snap which unit to use when you start snapping.
            0 is rectangular snapping (FRAME).
            1 is character snapping (CHAR). Default is 0.
    -r
    TRUEUNDERSCORE
            tells Snap to do true checking of underscores when
            snapping characters.
    -R
    FAKEUNDERSCORE
            turns off true checking of underscores. Instead Snap
            just skips the underscore line and hopes that the rest
            of the character will provide correct matching. This
            option is provided since there is a bug in the rendering
            of underscored characters.
    -bXX
    PLANEMASK XX
            where XX is the bit plane mask used when drawing the
            selection frame for character snapping. This does not
            affect graphics snapping. Default is 1.
    -CNN
    CACHESIZE NN
            where NN is the number of windows that Snap will cache
            character offsets for. Specifying a new value while Snap
            is running means that you increase the cache size by N.
            Default size is 10, default increase is 0.
    -LNN
    LEADING NN
            specifies the number of extra pixels in the line spacing
            that Snap should check for. Default is 1.

    -BNN
    BADCHAR NN
            where NN is the ascii value of the character that will
            be used when Snap doesn't recognize a character.
            Default is 63, a '?'.
    -Ffont
    ALTFONT font
            where font specifies an alternate font that will be
            tried if Snap can't find any character in the font
            that is specified in the window's RastPort. Some
            programs (CygnusEd 2.0 is one example) doesn't use
            the RastPort's font to render text and this option
            makes it possible to snap text from those programs
            too. The font is specified as 'fontname/size',
            eg 'Topaz/8'.
    -Q
    QUIT
            removes Snap.


   Some useful raw key codes:
    17 I    seems to become the Amiga standard
    34 V    as in Workbench 2.0
    15 Y    good ol' Emacs


Workbench Usage

  Snap recognizes the following tooltypes:

    PRIORITY=NN         Input handler priority
    TEXTQUAL=QQ         Text qualifier
    GFXQUAL=QQ          Graphics qualifier
    INSERTKEY=XX        Insert key
    CWKEY=XX            Control window key
    PREPEND=str         Prepend string
    APPEND=str          Append string
    CHARDELAY=NN        Character delay
    LINEDELAY=NN        Line delay
    CRAWLPTRN=XXXX      Crawl pattern
    XEROX               Xerox mode on
    NOXEROX             Xerox mode off
    EARLYPATCH          Early patch on
    NOEARLYPATCH        Early patch off
    STARTUNIT=NN        Starting unit
    TRUEUNDERSCORE      True underscores
    FAKEUNDERSCORE      Fake underscores
    JOINLONG            Join long lines
    NOJOINLONG          Don't join long lines
    SIMPLEREFRESH       Simple refresh
    SMARTREFRESH        Smart refresh
    PLANEMASK=XX        Plane mask
    CACHESIZE=NN        Cache size
    BADCHAR=str         Bad character
    ALTFONT=font        Alternate font

   To change the Workbench tooltypes, select the Snap icon and
   choose 'Information' (for Workbench 2.0) or 'Info' (for
   Workbench 1.3).

   Workbench 1.2/1.3 users must include an '=' in a tooltype,
   eg 'JOINLONG' must be specified as 'JOINLONG='

Modified Inserts

   Modified insert means that extra characters are added in front of
   and after each line as it is inserted. The characters in front
   are set via the -P/PREPEND command line argument, the characters
   after via the -A/APPEND command line argument.
   These strings can also be set from ARexx using the commands
   'PREPEND newstring' and
   'APPEND newstring'.
   These commands should be addressed to Snap using the ARexx command
   'ADDRESS SNAP'.
   The old string is returned in the RESULT variable, provided that
   'OPTIONS RESULTS' is given.
   If no newstring is given then no change is made.
   A small example:

    /* Change PREPEND and APPEND strings for my mail answering program */

    PARSE ARG ReplyTo

    OPTIONS RESULTS

    ADDRESS SNAP 'prepend' ReplyTo'>'
    oldprepend = RESULT
    ADDRESS SNAP 'append' ""
    oldappend = RESULT


Delays

   The character and line delays may be necessary with some programs
   that can't handle the amount of characters that Snap inserts into
   the input stream. CygnusEd is known to have problems with this.
   TxED and UEdit handles inserted characters very nicely.
   The delay is specified in milliseconds, eg a value of 1000 gives
   a delay of 1 second. A delay of 20 milliseconds will be enough
   to solve the problem for most programs.


Watch Out For

   The Early Patch behavior may cause problems if you use the Left
   Amiga key as the text qualifier together with MachII. What
   happens is that MachII can't activate a new window when you do
   a Left Amiga-M.
   Underscored characters can give problems. Apart from the bug
   mentioned above there's another problem. In some fonts the
   underscore character (_) and an underscored space looks the
   same. Snap tries to be smart and usually gets it right. The
   algorithm used is the following:
   An underscore/underscored space is interpreted as an underscored
   space if the previous character was underscored, otherwise it's
   interpreted as a true underscore character.


Snapping

   Snapping comes in two flavors; characters and graphics.
   Snapping graphics simply means that you can frame an
   area on screen and that area is copied into a window.
   Character snapping can be made in four different ways:
   * rectangular snapping
   * character oriented snapping
   * word oriented snapping
   * line oriented snapping

   Rectangular snapping makes it possible to snap a column
   of text. A carriage return is inserted after each row,
   except the last one.

   Line oriented snapping is much the same as rectangular
   snapping, except that the width of the rectangle is the
   width of the window.

   Character oriented snapping is much harder to explain than
   to use. Character oriented snapping starts at one character,
   extends to the right edge of the window, goes on with
   complete lines, and ends at another character. The select box
   can look like this: ________________________
    __________________|                        |
   |                                           |
   |                 __________________________|
   |________________|

   or like this:                      _________
    _____                            |_________|
   |_____|

   and of course like this:    ________________
                              |________________|

   Word oriented snapping works the same way as character
   oriented, except that you can only extend the selection
   word by word. A word is defined as non-blanks surrounded
   by blanks.


   Let's define some actions used when controlling snap.

   CLICK
      1. Press the mouse button.
      2. Release the mouse button.

   MOVE
      1. Move the mouse.

   PREPARE_TEXT
      1. If you are using Xerox style snapping, make sure that your
         intended destination window is active.
      2. Press and hold the text qualifier (Default: Left Amiga key).
      3. MOVE to the first character you want to copy.

   PREPARE_GFX
      1. Press and hold the graphics qualifier (Default: Right Amiga key).
      2. MOVE to the upper left corner of the area you want to copy

   EXTEND
      1. MOVE
      2. (Press and) Release the mouse button.

   END
      1. Release the mouse button.
      2. Release the qualifier.

   CANCEL
      1. Release the qualifier.
      2. Release the mouse button.


   Ways to use these actions:
   This is with starting unit FRAME. Selecting starting unit CHAR will
   skip rectangular snapping and take you directly to character oriented
   snapping. To do rectangular snapping you have to click through char,
   word and line oriented back to rectangular snapping.

   To do rectangular snapping:
    1. PREPARE_TEXT.
    2. Press the left mouse button.
    3. MOVE.
    4. EXTEND until satisfied.
    5. END or CANCEL.

   To do character oriented snapping
    1. PREPARE_TEXT.
    2. CLICK the left mouse button.
    3. EXTEND until satisfied.
    4. END or CANCEL.

   To do word oriented snapping
    1. PREPARE_TEXT.
    2. Double-CLICK left mouse button.
    3. EXTEND until satisfied.
    4. END or CANCEL.

   To do line oriented snapping
    1. PREPARE_TEXT.
    2. Triple-CLICK left mouse button.
    3. EXTEND until satisfied.
    4. END or CANCEL.

   To insert snapped characters (BKSYSBUF "You know ;-)")
    1. PREPARE_TEXT.
    2. CLICK the right mouse button.
   or
    1. Press and hold the left amiga key.
    2. Type the insert key as specified with -i (Default "I").

   To insert snapped characters including prepend and append strings
    1. Press and hold the left amiga key and either shift key.
    2. Type the insert key as specified with -i (Default "I").

   To abort insertion
    1. CLICK the left mouse button.

   To snap graphics
    1. PREPARE_GFX.
    2. Press the left mouse button.
    3. MOVE.
    4. EXTEND until satisfied.
    5. END or CANCEL.

   To open the Snap Control Window
    1. Press and hold the left amiga key.
    2. Type the control window key as specified with -w (Default "W").

   When snapping text you can go directly from snapping to
   inserting by replacing "END or CANCEL" above with
   "Release left mouse button - CLICK right mouse button".
   If you are using Xerox style snapping, the snapped text
   will be inserted as soon as you END.
   When selecting snapping unit a fourth click takes you
   back to character oriented snapping. Each click steps
   one unit. Note that rectangular snapping only is available
   if you MOVE before you release the mouse button.


Snapping Characters, Character Coordinates and Caching

   You must always start snapping at a character, otherwise
   Snap won't get the coordinates right. This applies to all
   kinds of snapping including line snapping.
   Snap caches the character coordinates for the N last used
   windows, where N is specified by the -C/CACHESIZE parameter.
   When you start snapping in a window Snap checks it's cache
   to see whether you have snapped in this window before.
   If the window is in the cache then Snap first tries to find
   a character at the previous coordinates. If no character is
   found at the cached coordinates then Snap goes through the
   complete lookup process. Of course this is transparent to
   the user, so you don't have to worry about it. The size of
   the cache can be specified by the user and is managed on a
   Least Recently Used basis.
   The caching makes it possible for Snap to get the correct
   character coordinates even if you start snapping on a space,
   provided that you've snapped in that window before.

   Trailing blanks are removed on each line when you're snapping
   characters, words or lines, but not when doing rectangular
   snapping.


Snapping and Saving Graphics

   Windows with graphic snaps are always opened on the Workbench
   screen. If you've snapped graphics from a screen with different
   colors then you can switch to the graphic snap's original colors
   by holding down the left mouse button inside the snap window.
   Saving of graphics is done via the Snap Control Window (SCW).
   Below a Snap window's window-to-front and window-to-back gadgets
   is a small gadget that looks like a disk. Clicking this disk
   gadget has different effects according to a two conditions.

     SCW        Graphics Window
   not open      not selected     Opens the SCW, selects the Graphics Window
     open        not selected     Selects the Graphics Window.
     open          selected       Saves the contents of the Graphics Window

   The Snap Control Window looks something like this:
    _______________________________
   |x|Snap_Control_Window________|||
   | ____      __________________  |
   ||Save| as |Name gadget       | |
   | ~~~~      ~~~~~~~~~~~~~~~~~~  |
   | Transparent color |0~~|       |
   |                    ~~~        |
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   The Save gadget will be ghosted if no window is selected.
   Clicking the Save gadget will save the contents of the
   selected Graphics Window as an IFF file.
   The Transparent color gadget is used to specify which color
   will be transparent in the saved IFF file.
   The Name gadget is used to specify the name of the IFF file
   to save. The Name gadget is a string gadget if req.library
   isn't available. If req.library is available it will be a
   click-gadget that brings up a Req File Requester.
   Below the disk gadget is a scissors gadget. Clicking this
   gadget saves the snapped graphics in the clipboard.
   Asl.library is used instead of req.library in Workbench 2.0.


Compiling

   A 'makefile' is provided. Depending on which compiler you
   use, remove and insert '#'s.
   I seem to have some problem with the detaching when using
   Lattice. Everything works ok, except that you can't close
   the CLI-window. If anybody solves it, I'd be very grateful
   to know about it.
   The makefile gives you some options when compiling Snap.
   The first choice is whether or not you want graphics
   snapping. This gives a smaller executable better suited
   for floppy users. The second choice is ARexx support.
   The third chioce is whether or not you want to compile
   with suport for req.library.
   When you've made your choices, add and/or remove comment
   characters (#) in front of the appropriate lines, touch
   (setdate) all source files and compile (make).


Some Things to Remember

   a. The text is sent to the active window. Make sure that
      the correct window is active.
   b. Don't interfere when the text is being inserted. Any key
      pressed by you will be inserted in the middle of the text
      being inserted.
   c. Snap begins with an attempt to find the character coordinates.
      Therefore if you begin snapping on a space, Snap will almost
      certainly get the wrong coordinates, unless Snap has cached
      the character coordinates from a previous snap.
   d. To be able to do Xerox style snapping, Snap disables
      ActivateWindow when the text qualifier is held down.
      By doing this Snap makes sure that the destination window
      remains active when you move out of it, even if you are
      using DMouse or another Sun mouse utility.


Bugs

   Of course, what did you think. Well, as far as I know there
   are no explicit bugs. Oh yes, there is one that I don't know
   how to solve. The problem is that some font editors optimize
   the character image data. The result is that two characters
   with the same image (e.g. I and l in some fonts) uses the
   same image data, thereby making it impossible for Snap to
   determine which character was printed in the first place.
   This can be solved by editing the font so that each character
   is unique.
   Oh yes, there are also some problems in the input handler
   state machine. I'll rewrite that in the next version.


Acknowledgements

   Thanks to:

   o Amiga-Lorraine for the machine.
   o Radical Eye Software for "minrexx".
   o William Hawes for ARexx, WShell, ConMan, etc.
   o Marc Boucher for his invaluable help with making Snap
     compatible with 2.0. "Help"? Actually, he did most of the work.
   o Björn Knutsson, Dominic Giampaolo, Marc Boucher, Eddy Carroll,
     Ismo Suihko, Kent D. Polk, Jonas Petersson and Loren J Rittle
     for testing.
   o All of you who has sent or will send comments, contributions
     or questions.

Improvements

   I've been thinking about adding a way for programs to "register"
   their windows with Snap so that Snap can let the program handle
   the snapping by itself. As an example: Snapping an icon as text
   doesn't make much sense, so the program displaying the icon
   could take over and put the name of the file in the clipboard.
   A character-mapped window could also benefit from this.
   Proportional fonts. Sigh. Ok, I'll take a look at it.
   Intuitionized interface. It's coming, it's coming. Hold on.

   A version that takes advantage of all the nifty 2.0-stuff will
   be available as soon as I can get hold of some documentation.


s-mail: Mikael Karlsson
        Lövsättersvägen 10
        S-585 98  LINKÖPING
        SWEDEN

e-mail: [e-mail]
        [e-mail]
        {mcvax|seismo}!sunic!liuida!slaka!micke

Phone:  [phone]