home *** CD-ROM | disk | FTP | other *** search
- 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: micke@slaka.sirius.se
- micke@slaka.UUCP
- {mcvax|seismo}!sunic!liuida!slaka!micke
-
- Phone: +46-13 50479
-