	    Tk "sticker" canvas item type (tkSticker)
		   (Version 1.2; September 1995)

			Heribert Dahms
		University of Karlsruhe, Germany
		(dahms@ifk20.mach.uni-karlsruhe.de)

This is a freely distributable extension to Tcl/Tk called tkSticker.

FROM THE FAQ

	A "sticker" is a rectangle with text inside but which truncates
	if it's too long e.g. after the canvas is scaled. The text can be
	drawn vertically and/or repeated. You can also draw a (filled) bar;
	we use it showing percentage of a job's completeness. You may use
	mouse enter/leave bindings to put the complete text in a status line.
	No hacks nor patches to Tcl7.4-5/Tk4.0-1 and dynamically loadable.
	Please use tkSticker-1.0 for Tcl7.2-3/Tk3.5-6!

INTRODUCTION

tkSticker has full support for Tk canvas Postscript generation.

There's no user callable C interface besides the initialization routine
since all is handled by the standard Tk canvas widget code.
No new Tcl/Tk commands are defined for the same reason.
The only extra you'll get is a global Tcl variable "tksticker_version".
However, a new canvas item type named "sticker" will be recognized.

Sorry, there's neither a Makefile nor a man page (yet).
See sections INSTALLATION and USAGE instead.


INSTALLATION

To compile tkSticker:

+) If you do not already have Tcl7.4 and Tk4.0 or a newer version,
get a copy and follow the instructions to build the system.
tkSticker may not work with earlier versions of Tcl/Tk.
tkSticker versions > 1.1 will not work with Tk3.x!
Again, please use tkSticker-1.0 for Tcl7.2-3/Tk3.5-6!
BTW, tkSticker-1.1 was never publically released.

+) Unpack
	tar xfz tkSticker-1.2.tar.gz
or
	gzcat tkSticker-1.2.tar.gz | tar xf -
or
	cat tkSticker-1.2.tar.gz | gunzip | tar xf -
or
	cat tkSticker-1.2.tar.gz | gzip -d | tar xf -
which creates a subdirectory tkSticker-1.2 to put things into.

+) I describe only the easiest method (assuming you have enough privilege):
- cd to the Tk source directory.
- Copy tkSticker.c into the Tk source directory.
- Edit tkAppInit.c to insert the initialization code (which you might read
  in from tkSticker.txt) right after Tk_Init in the Mod_Init section.
- Edit Makefile.in and append tkSticker.o to the CANVOBJS list.
- Run ./configure
- Run make
- Test e.g. ./wish ../tkSticker-1.2/demo.tcl
- Run make install


DEMO

demo.tcl is a simple script showing some of tkSticker's specific features.
The comments tell what should happen.


USAGE

Creation, given canvas .c
	.c create sticker x1 y1 x2 y2 ?option value ?option value ...
		x1 y1 x2 y2 - just like the canvas rectangle coordinates

Options (21) with their defaults
	-anchor		center
		Position as accepted by Tk_GetAnchor for the text.
		Subject to rotation via -orient vertical.
	-bar		black
		Color as accepted by Tk_GetColor for drawing a bar
		or empty string to suppress drawing.
	-color		black
		Color as accepted by Tk_GetColor for drawing the text
		or empty string to suppress drawing.
	-fill		{}
		Color as accepted by Tk_GetColor for filling the
		rectangle x1 y1 x2 y1 or empty string for transparency.
	-font		-Adobe-Helvetica-Bold-R-Normal--*-120-*-*-*-*-*-*
		Font as accepted by Tk_GetFontStruct for drawing text.
	-lefttrunc	0 
		Flag as accepted by Tk_GetBoolean. If true, forces that
		the rightmost part of too long text is drawn.
	-outline	black
		Color as accepted by Tk_GetColor for drawing the outline
		or empty string to suppress drawing.
	-relheight	0
	-relwidth	0
	-relx		0
	-rely		0
		The above four floating-point numbers define a rectangular
		bar (similar to the Tk placer geometry manager) relative to
		the remaining area inside of a possibly fat outline.
		Negative numbers or values greater than 1 are valid. Only
		the part of the bar inside the "sticker" is drawn, if any.
		The bar is not drawn if either -relwidth or -relheight or
		both are negative. -relx 0 -rely 0 is upper left. 
	-space		0
		Distance as accepted by Tk_GetPixel between repeatedly drawn
		text or 0 if text is to be drawn only once.
	-stipple	{} 
		Bitmap as accepted by Tk_GetBitmap for filling the rectangle
		with a stipple pattern or empty string for solid background.
		Without -fill there's no effect.
	-tags		{}
		List of tag names. May be empty.
	-text		{}
		String of characters to be displayed as text. May be empty.
		Text is always drawn solid regardless of -stipple.
	-width		0
		Width as accepted by Tk_GetPixel for drawing the outline.
	-orient		horizontal
		Specify text orientation as either "horizontal" or "vertical".
		May be abbreviated.
	-maxheight	32767
	-maxwidth	0
	-minheight	32767
	-minwidth	0
		The above four values as accepted by Tk_GetPixel suppress the
		drawing of the whole sticker if it is too small or too large.

Text characters are always entirely drawn or omitted; there are no clipped
partially drawn characters. This works both for fixed and proportional fonts.

Note that the bar specified with -relx, -rely, -relwidth, -relheight does
*not* automatically rotate via -orient vertical unlike the text. If you
need this, you may compute the transformation in a Tcl procedure.

Hint: The -anchor option supersedes -justify of a canvas text item.

Not implemented: Splitting up long text into multiple lines. In case of a
newline either the first or last line will be drawn depending on -lefttrunc.

The following canvas widget commands (for text items) are not supported:
- dchars, focus, icursor, index, insert, select.

Special: If the canvas exists, you can get the RCS id with something like
	catch {.c create sticker -version} tksticker_rcsid
but you can't abbreviate -version (I invented this trick for the first
versions which didn't pass "interp" to the init routine).

Else, as usual, keywords can be abbreviated if still unique, e.g.
	.c it st -or v
no longer works because Tk4.0 introduced itemcget, so now
	.c itemco st -or v
configures all items with tag "st" the same as
	.c itemconfigure st -orient vertical


TESTED 1.2

486/Linux 0.99.13/Slackware 1.1.0 - Tcl7.4/Tk4.0p1
486/Linux 1.2.8/Slackware ? - Tcl7.4/Tk4.0 with BLT1.8
Alpha/OSF1 3.2 - Tcl7.5a1/Tk4.1a1 inclusive dynamic loading
HP9000/HP-UX 9.05 - Tcl7.4/Tk4.0 with BLT1.8
(It works with other extensions, but does not require them)

TESTED 1.0

486/Linux 0.99.13/Slackware 1.1.0 - Tcl7.2/Tk3.5 with BLT1.1 and Tcl-DP3.0
486/Linux 1.0.8/Slackware 2.0 - Tcl7.3/Tk3.6 with BLT1.7 and Tcl-DP3.2
Alpha/OSF1 1.3 - Tcl7.3/Tk3.6 with BLT up to 1.7 and Tcl-DP3.2
VAX/VMS 5.5-1 - Tcl7.3/Tk3.6 with BLT1.6 (no Tcl-DP port yet available [1994])
HP9000/HP-UX - Tcl7.3/Tk3.6 with BLT1.5 and Tcl-DP3.1 


I had no luck under Linux yet, but I made a dynamically loadable tkSticker
on VAX/VMS and Alpha/OSF1 (the latter using a slightly adapted shells-1.1).
With the new ELF shareable library support it should be easy under Linux, too.


FEEDBACK

To report bugs, bug fixes, descriptions of interesting tkSticker 
applications, and suggested improvements:

+) Send email to dahms@ifk20.mach.uni-karlsruhe.de

or

+) Post an article in the comp.lang.tcl newsgroup, which should have
"sticker" somewhere in the subject (lower/upper/mixed case letters).


UNDER THE HOOD

All the init code has to do is pass a structure describing the "sticker"
item to Tk_CreateItemType which hooks it onto an internal Tk pointered list. 
Thanks to John, all routines I need now have prototype declarations in Tk4.0,
except LineToPostscript, whose code I duplicated from tkCanvText.c because it
is declared static (with good reason, as it has no Tk prefix and is different
from the one in tkCanvLine.c).

I use the following "X" routines:
	XCreateGC	XDrawPoint	XDrawRectangle	XFillRectangle
	XFreeGC		XGContextFromGC	XGetImage	XSetFont
	XSetTSOrigin	Tk_FreeXId

I've heard that X11R6 can draw rotated text, but I do it the hard way much
like BLT (which inspired me, so thanks to george.howlett@fast.net)!


CHANGES IN 1.2

- Added wrapper routines Tksticker_Init and Tksticker_SafeInit as aliases
  for TkSticker_Init in order to support dynamic loading under tcl7.5


CHANGES IN 1.1

- Added -maxheight, -maxwidth, -minheight and -minwidth options.
  This was requested by Yves Mathys (mathys@geneve.sps.mot.com).


TO DO

- Figure out dynamic loading under Linux.
- Makefile with ./configure
- man page (I can easily convert this README to VMS HELP, but man page...)
- Maybe support of lists for -bar, -relx, -rely, -relwidth, -relheight.
- Maybe splitting up long text automatically or at newlines. 


[README of Tcl-DP stolen as a template]

Have fun with it!
Heribert
