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