Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/365.lha/VSnap/snap.doc

Text File | 1990-04-10 | 18KB | 457 lines

                     Snap 1.4
                     ========
               © Mikael Karlsson 1989
      Keymap inverting courtesy of Jim Mackraz
      IFF picture saving to clipboard by Stephen Vermeulen

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

  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).
  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 registred copy of the product.
  (How about including it with a '030 card?)

  Also read this message that Jim Mackraz sent to me regarding
  some code used in Snap:

  "You may use ikm.c in your product Snap.
   You may not distribute the source to ikm.c for profit,
   and any distribution of ikm.c must retain the original
   copyright message.

   You should also be warned that IKM() has not been
   substantially verified in either design or implementation,
   and that it will be made obsolete in version V1.4 by a
   new OS function call.

   There is no explicit or implied guarantee that ikm.c contains
   only supported algorithms.  It may have problems in a future
   release of the system.

      jimm

   Jim Mackraz
   Aug 18, 1989"

---------------------------------------------------------------------

New addition to make this 1.4:  by Stephen Vermeulen
                                   P.O. Box 3295, Station B
                                   Calgary, Alberta,
                                   CANADA, T2M 4L8

                                   [phone]

   I found that after playing with snap's cut out graphics feature
   that I wanted it to save those pictures to the clipboard as propper
   IFF FORM ILBMs so that I could use the "Open Clipboard" feature
   of Express Paint 3.0.60 and higher to paste these into drawings.
   To this end I looked through SNAP 1.3, found the routine which
   handled the picture snapping and added one line of code to SNAPGFX.C
   which is:

    if (goodsnap) save_bm(&MyBM, theScreen);  /* write it to clipboard */

   and then I added the file "IFFPIC.C" which contains the necessary
   code to save pictures to the clipboard.  This file contains some
   duplication of functionality when compared with the original snap
   code as I was too lazy to either modify the existing routines or
   change my routines to suit the requirements of snap...

   I also added one line "SetRast(&MyRP, 0L);" to SnapGfx.c to clear the
   raster that contains the snapped image before the image is put
   there to eliminate some crud on the right hand edge...

   To round out the changes I modified the make file to include the new
   C file and the dependencies on the pre-compiled includes, as well
   I wrote up a source file "SYMBOLS.Y" for the predefined include
   file.  And last I added a "CLEAN" entry to the makefile so now you
   can:

     make clean

   to nuke all the object modules except for "detach.o" which is suppied
   by Manx.

   Just about forgot, I added "packer.c" which comes with the IFF
   examples.

   From the user's point of view all that happens is each time that
   a graphic image is "snapped" a new snap window appears on the WorkBench
   screen (as before) and the contents of that window are posted to
   the clipboard as an IFF FORM ILBM (a standard IFF picture or brush)
   replacing the previous cut on the clipboard.

-----------------------  Now back to SNAP 1.3 docs ---------------------


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


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 and height<16.
   e. Snap supports accented characters (128-255).
   f. Snap supports keymaps, thanks to Jim Mackraz.
   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 does word oriented snapping.
   m. Snap has ants.
   n. Snap has a key combination to do insert.
   o. Snap supports Xerox style snapping with immediate insert.


Starting and Stopping

   Start Snap with 'snap'. That's it. Snap detaches itself
   from the CLI, making it possible to close the CLI.
   Make sure that you have 'clipboard.device' in devs:.
   To get rid of Snap, execute Snap again.
   Note that you can't remove Snap if you have any 'snapped'
   windows left.
   Snap accepts a couple of command line arguments.
   XX is hex. NN is decimal.
     -pNN    where NN is the priority to use when installing
             the input handler. Default is 51.
     -tXX    where XX is the text qualifier to use in text
             operations. Default is the left Amiga key.
     -gXX    where XX is the graphics qualifier to use in
             graphics operations. Default is the right Amiga key.
     -iXX    where XX is the raw key code for the key to be used
             together with the left Amiga key as insert key.
             Use 0 to disable. Default is 17 ("I").
     -cNN    where NN is the amount of time that Snap should
             wait after each character inserted into the input
             stream. Default is 0.
     -lNN    where NN is the amount of time that Snap should
             wait after each carriage return inserted into the
             input stream. Default is 0.
     -aXXXX  where XXXX is a 16 bit number that specifies the
             pattern for the crawling ants. Use FFFF to turn
             the crawling off. Default is 7777.
     -x      tells Snap to use Xerox style snapping instead.
             The snapped text is inserted immediately it has
             been snapped.
     -uN     tells Snap which unit to use when you start snapping.
             0 is rectangular snapping (FRAME).
             1 is character snapping (CHAR). Default is 0.
     -bXX    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.

QUALIFIERS (always entered in HEX)  (This list borrowed from Matt Dillon)

    0001    Left Shift
    0002    Right Shift
    0004    Caps Lock
    0008    Control
    0010    Left Alt
    0020    Right Alt
    0040    Left Amiga Key
    0080    Right Amiga Key
    0100    Numeric Key Pad Key (not useful)
    0200    Repeat              (not useful)
    0400    Interrupt           (not useful)
    0800    Multibroadcast      (not useful)
    1000    Middle Mouse Button (not normally implemented by intuition)
    2000    Right Mouse Button
    4000    Left Mouse Button

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

   Some useful raw key codes:
    17 I    seems to become the Amiga standard
    34 V    for you Macintosh freaks
    15 Y    good ol' Emacs

   Note that you can't change parameters while Snap is running.
   You have to remove and restart Snap to change anything.
   The character and line delay may be necessary with some
   programs that can't handle the amount of characters the Snap
   insert into the input stream. CygnusEd is known to have problems
   with this. TxED handles inserted characters very nicely.
   The delay is specified in ticks, 50 ticks per second.


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

   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.
   Another thing: 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.
   Trailing blanks are removed on each line when you're snapping
   characters, words or lines.
   Windows with graphic snaps are always opened on the Workbench
   screen.


Compiling

   A 'makefile' is provided for Manx-Aztec users. Note the
   use of a precompiled header file containing all amiga-specific
   include files.
   Conversion to Lattice shouldn't be to hard, I hope.


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.
   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.
   It seems like there is a problem with JRComm. Any spaces snapped
   using JRComm's internal font are interpreted as ascii 0. The
   problem doesn't occur when you use an external font.


Changes

  Björn Knutsson pointed out that it wasn't possible to Snap
  the rightmost characters in a borderless window. Now I look
  at the window flags for border and resize gadget, instead
  of just subtracting.
  Ants! I've always thought that the Macintosh's crawling ants
  were neat. Here it is. New option: -aXXXX  - Ants.
  You still can't shrink the selection down to one line. Sorry.
  Björn Knutsson also had some problems when trying to start
  snapping at the leftmost character in a window. A couple of
  small changes has been made to simplify this.
  Major: At last I got rid of the 8-point-wide limit. Thanks to
  Michel Denber for pushing me over the edge on that one.
  Lost and found accented chars 128-255. Watch out for signed tests.
  A key combination for insert is now available.
  Bold characters are now supported. Combinations (bold+inverted)
  are not supported. And Björn Knutsson keeps telling me that
  he wants underlined too. Sigh. Some people are never satisfied.
  Combinations are a potential problem. I'm afraid that implementing
  all combinations will make the character recognition too slow.
  Handler code cleaned up.
  Better gfx snapping, similar to rect snapping. Change corner,
  ants (crawling the other way :-), better edge checking.
  Xerox style snapping with immediate insert. Option -x.
  Stricter control in the input handler. Unused button events when
  snapping are IECLASS_NULLed without mercy.
  Made it possible to shrink the selection back to one line and char.
  Added the option to select char or frame snapping as startint unit.
  Option to select bit planes to draw selection frame into.


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.
   Another obvious improvement is to make Snap recognize proportional
   fonts. Don't hold your breath.
   The ability to save snapped graphics as an IFF-file? Tell me if you
   want it. It will cost some memory though. Perhaps if I could find
   a good iff.library?
   Built-in help? Naah...
   Converting to one loader and one handler.
   Prepending and appending characters.


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

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

Phone:  [phone]
        [phone] (in the summer)