home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
345.lha
/
snap_v1.4
/
snap.doc
< prev
next >
Wrap
Text File
|
1990-02-13
|
22KB
|
603 lines
Snap 1.4
========
(c) Mikael Karlsson 1989
Keymap inverting courtesy of Jim Mackraz
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"
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 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.
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 -Q' (or snap QUIT).
Note that you can't remove Snap if you have any 'snapped'
windows left.
Command line arguments
Snap accepts a couple of command line arguments. You can
use either unix or Amiga style arguments.
XX is hex. NN is decimal. str is a string.
Usage:
snap -pNN -tXX -gXX -iXX -wXX -Pstr -Astr -cNN -lNN -aXXXX
-x -X -e -E -r -R -j -J -uN -bXX -oNN -CNN -BNN -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/k FAKEUNDERSCORE/s JOINLONG/s NOJOINLONG/s
PLANEMASK/k GADOFFSET/k CACHESIZE/k BADCHAR/s QUIT/s
-pNN
PRIORITY NN
where NN is the priority to use when installing
the input handler. Default is 51. Note that it's
not possible to change the priority of the input
handler while Snap is running.
-tXX
TEXTQUAL XX
where XX is the text qualifier to use in text
operations. Default is the left Amiga key.
-gXX
GFXQUAL XX
where XX 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 "> ".
-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 "".
-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.
-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.
-oNN
GADOFFSET NN
where NN is the offset for the save gadget. This may
be necessary to use if you use some kind of iconifier
program that puts a gadget where Snap usually puts the
save gadget. Default is 52.
-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.
-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 '?'.
-Q
QUIT
removes Snap.
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
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 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 and UEdit handles inserted characters very nicely.
The delay is specified in milliseconds, eg a value of 1000 gives
a delay of 1 second.
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
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 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. Trailing blanks are only removed in line mode if
you're snapping a single line.
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).
To the left of 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 arp.library
isn't available. If arp.library is available it will be a
click-gadget that brings up an Arp File Requester.
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.
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.
Acknowledgements
Thanks to:
o Amiga-Lorraine for the machine.
o Jim Mackraz for the keymap inverting code.
o Radical Eye Software for "minrexx".
o William Hawes for ARexx, WShell, ConMan, etc.
o Bjorn Knutsson, Dominic Giampal, Marc Boucher, Eddy Carroll
and Jonas Petersson 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.
s-mail: Mikael Karlsson
Lovsattersvagen 10
S-585 98 LINKOPING
SWEDEN
e-mail: micke@slaka.sirius.se
micke@slaka.UUCP
{mcvax|munnari|seismo}!sunic!liuida!slaka!micke
Phone: +46-13 50479
+46-431 50623 (in the summer)