	    Tk "sticker" canvas item type (tkSticker)
		     (Version 1.0; August 1994)

			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.2-3/TK3.5-6 and dynamically loadable.


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 Tcl 7.3 and Tk 3.6 (or Tcl7.2/Tk3.5),
get a copy and follow the instructions to build the system.
tkSticker may not work with earlier versions of Tcl/Tk.

+) Unpack
	tar xfz tkSticker-1.0.tar.gz
or
	gzcat tkSticker-1.0.tar.gz | tar xf -
or
	cat tkSticker-1.0.tar.gz | gunzip | tar xf -
which creates a subdirectory tkSticker-1.0 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.
- Edit Makefile.in and append tkSticker.o to the CANVOBJS list.
- Run ./configure
- Run make
- Test e.g. ./wish -f ../tkSticker-1.0/demo.tcl
- Run make install


DEMO

demo.tcl is a simple script showing 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 (17) 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.

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
configures all items with tag "st" the same as
	.c itemconfigure st -orient vertical


TESTED

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)
HP700/HPUX - 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).


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. 
This is the cleanest possible interface, IMHO, avoiding patches to Tk itself,
so problems with other extensions are minimized. Sure Tk 4.0 might break it...
Besides routines documented in "the book" and X11, I use

tkCanvas.h:			tkInt.h:
TkCanvPsColor			TkDisplayChars
TkCanvPsFont			TkMeasureChars
TkCanvPsStipple
TkCanvPsY			nowhere:
TkGetCanvasCoord		(Shouldn't this be in tkCanvas.h, John?)
tkCanvasTagsOption		Tk_CreateItemType

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@att.com)!


CHANGES SINCE 1.0

will go here


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
