Merge pull request #5 from csabella/8.6.8-tk

Import Tk 8.6.8

README

@@ -0,0 +1,41 @@
+README:  Tk
+    This is the Tk 8.6.8 source distribution.
+	http://sourceforge.net/projects/tcl/files/Tcl/
+    You can get any source release of Tk from the URL above.
+
+1. Introduction
+---------------
+
+This directory contains the sources and documentation for Tk, an X11
+toolkit implemented with the Tcl scripting language.
+
+For details on features, incompatibilities, and potential problems with
+this release, see the Tcl/Tk 8.6 Web page at
+
+	http://www.tcl.tk/software/tcltk/8.6.html
+
+or refer to the "changes" file in this directory, which contains a
+historical record of all changes to Tk.
+
+Tk is maintained, enhanced, and distributed freely by the Tcl community.
+Source code development and tracking of bug reports and feature requests
+takes place at:
+
+	http://core.tcl.tk/tk/
+
+with the Tcl Developer Xchange at:
+
+	http://www.tcl.tk/
+
+Tk is a freely available open source package.  You can do virtually
+anything you like with it, such as modifying it, redistributing it,
+and selling it either in whole or in part.  See the file
+"license.terms" for complete information.
+
+2. See Tcl README
+-----------------
+
+Please see the README file that comes with the associated Tcl release
+for more information.  There are pointers there to extensive
+documentation.  In addition, there are additional README files
+in the subdirectories of this distribution.

bitmaps/error.xbm

@@ -0,0 +1,8 @@
+#define error_width 17
+#define error_height 17
+static unsigned char error_bits[] = {
+   0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x16, 0x50, 0x00,
+   0x2b, 0xa0, 0x00, 0x55, 0x40, 0x01, 0xa3, 0xc0, 0x00, 0x45, 0x41, 0x01,
+   0x83, 0xc2, 0x00, 0x05, 0x45, 0x01, 0x03, 0xca, 0x00, 0x05, 0x74, 0x01,
+   0x0a, 0xa8, 0x00, 0x14, 0x58, 0x00, 0xe8, 0x2f, 0x00, 0x50, 0x15, 0x00,
+   0xa0, 0x0a, 0x00};

bitmaps/gray12.xbm

@@ -0,0 +1,6 @@
+#define gray12_width 16
+#define gray12_height 16
+static unsigned char gray12_bits[] = {
+   0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22,
+   0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88,
+   0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88};

bitmaps/gray25.xbm

@@ -0,0 +1,6 @@
+#define gray25_width 16
+#define gray25_height 16
+static unsigned char gray25_bits[] = {
+   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,
+   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,
+   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22};

bitmaps/gray50.xbm

@@ -0,0 +1,6 @@
+#define gray50_width 16
+#define gray50_height 16
+static unsigned char gray50_bits[] = {
+   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,
+   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,
+   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa};

bitmaps/gray75.xbm

@@ -0,0 +1,6 @@
+#define gray75_width 16
+#define gray75_height 16
+static unsigned char gray75_bits[] = {
+   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,
+   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,
+   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd};

bitmaps/hourglass.xbm

@@ -0,0 +1,9 @@
+#define hourglass_width 19
+#define hourglass_height 21
+static unsigned char hourglass_bits[] = {
+   0xff, 0xff, 0x07, 0x55, 0x55, 0x05, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,
+   0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xc2, 0x0a, 0x03, 0x46, 0x05, 0x01,
+   0x82, 0x0a, 0x03, 0x06, 0x05, 0x01, 0x02, 0x03, 0x03, 0x86, 0x05, 0x01,
+   0xc2, 0x0a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,
+   0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0xff, 0xff, 0x07,
+   0xab, 0xaa, 0x02};

bitmaps/info.xbm

@@ -0,0 +1,5 @@
+#define info_width 8
+#define info_height 21
+static unsigned char info_bits[] = {
+   0x3c, 0x2a, 0x16, 0x2a, 0x14, 0x00, 0x00, 0x3f, 0x15, 0x2e, 0x14, 0x2c,
+   0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0xd7, 0xab, 0x55};

bitmaps/questhead.xbm

@@ -0,0 +1,9 @@
+#define questhead_width 20
+#define questhead_height 22
+static unsigned char questhead_bits[] = {
+   0xf8, 0x1f, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0xeb, 0xaf, 0x00,
+   0xf5, 0x5f, 0x01, 0xfb, 0xbf, 0x00, 0x75, 0x5d, 0x01, 0xfb, 0xbe, 0x02,
+   0x75, 0x5d, 0x05, 0xab, 0xbe, 0x0a, 0x55, 0x5f, 0x07, 0xab, 0xaf, 0x00,
+   0xd6, 0x57, 0x01, 0xac, 0xab, 0x00, 0xd8, 0x57, 0x00, 0xb0, 0xaa, 0x00,
+   0x50, 0x55, 0x00, 0xb0, 0x0b, 0x00, 0xd0, 0x17, 0x00, 0xb0, 0x0b, 0x00,
+   0x58, 0x15, 0x00, 0xa8, 0x2a, 0x00};

bitmaps/question.xbm

@@ -0,0 +1,10 @@
+#define question_width 17
+#define question_height 27
+static unsigned char question_bits[] = {
+   0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00,
+   0x2b, 0xa8, 0x00, 0x15, 0x50, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01,
+   0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xb0, 0x00, 0x00, 0x58, 0x01,
+   0x00, 0xaf, 0x00, 0x80, 0x55, 0x00, 0xc0, 0x2a, 0x00, 0x40, 0x15, 0x00,
+   0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00,
+   0xc0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0xc0, 0x02, 0x00,
+   0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x01, 0x00};

bitmaps/warning.xbm

@@ -0,0 +1,5 @@
+#define warning_width 6
+#define warning_height 19
+static unsigned char warning_bits[] = {
+   0x0c, 0x16, 0x2b, 0x15, 0x2b, 0x15, 0x2b, 0x16, 0x0a, 0x16, 0x0a, 0x16,
+   0x0a, 0x00, 0x00, 0x1e, 0x0a, 0x16, 0x0a};

compat/license.terms

@@ -0,0 +1,40 @@
+This software is copyrighted by the Regents of the University of
+California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState
+Corporation, Apple Inc. and other parties.  The following terms apply to
+all files associated with the software unless explicitly disclaimed in
+individual files.
+
+The authors hereby grant permission to use, copy, modify, distribute,
+and license this software and its documentation for any purpose, provided
+that existing copyright notices are retained in all copies and that this
+notice is included verbatim in any distributions. No written agreement,
+license, or royalty fee is required for any of the authorized uses.
+Modifications to this software may be copyrighted by their authors
+and need not follow the licensing terms described here, provided that
+the new terms are clearly indicated on the first page of each file where
+they apply.
+
+IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
+DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
+IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
+NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
+MODIFICATIONS.
+
+GOVERNMENT USE: If you are acquiring this software on behalf of the
+U.S. government, the Government shall have only "Restricted Rights"
+in the software and related documentation as defined in the Federal
+Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
+are acquiring the software on behalf of the Department of Defense, the
+software shall be classified as "Commercial Computer Software" and the
+Government shall have only "Restricted Rights" as defined in Clause
+252.227-7013 (b) (3) of DFARs.  Notwithstanding the foregoing, the
+authors grant the U.S. Government and others acting in its behalf
+permission to use and distribute the software in accordance with the
+terms specified in this license.

compat/stdlib.h

@@ -0,0 +1,36 @@
+/*
+ * stdlib.h --
+ *
+ *	Declares facilities exported by the "stdlib" portion of the C library.
+ *	This file isn't complete in the ANSI-C sense; it only declares things
+ *	that are needed by Tcl. This file is needed even on many systems with
+ *	their own stdlib.h (e.g. SunOS) because not all stdlib.h files declare
+ *	all the procedures needed here (such as strtod).
+ *
+ * Copyright (c) 1991 The Regents of the University of California.
+ * Copyright (c) 1994-1998 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#ifndef _STDLIB
+#define _STDLIB
+
+extern void		abort(void);
+extern double		atof(const char *string);
+extern int		atoi(const char *string);
+extern long		atol(const char *string);
+extern char *		calloc(unsigned int numElements, unsigned int size);
+extern void		exit(int status);
+extern int		free(char *blockPtr);
+extern char *		getenv(const char *name);
+extern char *		malloc(unsigned int numBytes);
+extern void		qsort(void *base, int n, int size, int (*compar)(
+			    const void *element1, const void *element2));
+extern char *		realloc(char *ptr, unsigned int numBytes);
+extern double		strtod(const char *string, char **endPtr);
+extern long		strtol(const char *string, char **endPtr, int base);
+extern unsigned long	strtoul(const char *string, char **endPtr, int base);
+
+#endif /* _STDLIB */

compat/unistd.h

@@ -0,0 +1,76 @@
+/*
+ * unistd.h --
+ *
+ *      Macros, constants and prototypes for Posix conformance.
+ *
+ * Copyright 1989 Regents of the University of California Permission to use,
+ * copy, modify, and distribute this software and its documentation for any
+ * purpose and without fee is hereby granted, provided that the above
+ * copyright notice appear in all copies. The University of California makes
+ * no representations about the suitability of this software for any purpose.
+ * It is provided "as is" without express or implied warranty.
+ */
+
+#ifndef _UNISTD
+#define _UNISTD
+
+#include <sys/types.h>
+
+#ifndef NULL
+#define NULL    0
+#endif
+
+/*
+ * Strict POSIX stuff goes here. Extensions go down below, in the ifndef
+ * _POSIX_SOURCE section.
+ */
+
+extern void		_exit(int status);
+extern int		access(const char *path, int mode);
+extern int		chdir(const char *path);
+extern int		chown(const char *path, uid_t owner, gid_t group);
+extern int		close(int fd);
+extern int		dup(int oldfd);
+extern int		dup2(int oldfd, int newfd);
+extern int		execl(const char *path, ...);
+extern int		execle(const char *path, ...);
+extern int		execlp(const char *file, ...);
+extern int		execv(const char *path, char **argv);
+extern int		execve(const char *path, char **argv, char **envp);
+extern int		execvpw(const char *file, char **argv);
+extern pid_t		fork(void);
+extern char *		getcwd(char *buf, size_t size);
+extern gid_t		getegid(void);
+extern uid_t		geteuid(void);
+extern gid_t		getgid(void);
+extern int		getgroups(int bufSize, int *buffer);
+extern pid_t		getpid(void);
+extern uid_t		getuid(void);
+extern int		isatty(int fd);
+extern long		lseek(int fd, long offset, int whence);
+extern int		pipe(int *fildes);
+extern int		read(int fd, char *buf, size_t size);
+extern int		setgid(gid_t group);
+extern int		setuid(uid_t user);
+extern unsigned		sleep(unsigned seconds);
+extern char *		ttyname(int fd);
+extern int		unlink(const char *path);
+extern int		write(int fd, const char *buf, size_t size);
+
+#ifndef	_POSIX_SOURCE
+extern char *		crypt(const char *, const char *);
+extern int		fchown(int fd, uid_t owner, gid_t group);
+extern int		flock(int fd, int operation);
+extern int		ftruncate(int fd, unsigned long length);
+extern int		ioctl(int fd, int request, ...);
+extern int		readlink(const char *path, char *buf, int bufsize);
+extern int		setegid(gid_t group);
+extern int		seteuidw(uid_t user);
+extern int		setreuid(int ruid, int euid);
+extern int		symlink(const char *, const char *);
+extern int		ttyslot(void);
+extern int		truncate(const char *path, unsigned long length);
+extern int		vfork(void);
+#endif /* _POSIX_SOURCE */
+
+#endif /* _UNISTD */

doc/3DBorder.3

@@ -0,0 +1,294 @@
+'\"
+'\" Copyright (c) 1990-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_3DBorder
+\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_3DBorder
+\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
+.sp
+Tk_3DBorder
+\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+void
+\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
+.sp
+void
+\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
+.sp
+void
+\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
+.sp
+void
+\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
+.sp
+void
+\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR
+.sp
+void
+\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR
+.sp
+void
+\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
+.sp
+const char *
+\fBTk_NameOf3DBorder(\fIborder\fB)\fR
+.sp
+XColor *
+\fBTk_3DBorderColor(\fIborder\fB)\fR
+.sp
+GC *
+\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
+.sp
+\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+\fBTk_Free3DBorder(\fIborder\fB)\fR
+.SH ARGUMENTS
+.AS "Tk_3DBorder" borderWidth
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window (for all procedures except \fBTk_Get3DBorder\fR,
+must be the window for which the border was allocated).
+.AP Tcl_Obj *objPtr in
+Pointer to value whose value describes color corresponding to
+background (flat areas).  Illuminated edges will be brighter than
+this and shadowed edges will be darker than this.
+.AP char *colorName in
+Same as \fIobjPtr\fR except value is supplied as a string rather
+than a value.
+.AP Drawable drawable in
+X token for window or pixmap;  indicates where graphics are to be drawn.
+Must either be the X window for \fItkwin\fR or a pixmap with the
+same screen and depth as \fItkwin\fR.
+.AP Tk_3DBorder border in
+Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
+.AP int x in
+X-coordinate of upper-left corner of rectangle describing border
+or bevel, in pixels.
+.AP int y in
+Y-coordinate of upper-left corner of rectangle describing border or
+bevel, in pixels.
+.AP int width in
+Width of rectangle describing border or bevel, in pixels.
+.AP int height in
+Height of rectangle describing border or bevel, in pixels.
+.AP int borderWidth in
+Width of border in pixels. Positive means border is inside rectangle
+given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
+border is outside rectangle.
+.AP int relief in
+Indicates 3-D position of interior of value relative to exterior;
+should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR,
+\fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR
+for \fBTk_Fill3DRectangle\fR).
+.AP XPoint *pointPtr in
+Pointer to array of points describing the set of vertices in a polygon.
+The polygon need not be closed (it will be closed automatically if it
+is not).
+.AP int numPoints in
+Number of points at \fI*pointPtr\fR.
+.AP int polyBorderWidth in
+Width of border in pixels.  If positive, border is drawn to left of
+trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
+right of trajectory.  If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or
+\fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory.
+.AP int leftRelief in
+Height of left side of polygon's path relative to right.  \fBTK_RELIEF_RAISED\fR
+means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side
+should appear higher;
+\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things.
+For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to
+indicate no difference in height.
+.AP int leftBevel in
+Non-zero means this bevel forms the left side of the value;  zero means
+it forms the right side.
+.AP int leftIn in
+Non-zero means that the left edge of the horizontal bevel angles in,
+so that the bottom of the edge is farther to the right than
+the top.
+Zero means the edge angles out, so that the bottom is farther to the
+left than the top.
+.AP int rightIn in
+Non-zero means that the right edge of the horizontal bevel angles in,
+so that the bottom of the edge is farther to the left than the top.
+Zero means the edge angles out, so that the bottom is farther to the
+right than the top.
+.AP int topBevel in
+Non-zero means this bevel forms the top side of the value;  zero means
+it forms the bottom side.
+.AP int which in
+Specifies which of the border's graphics contexts is desired.
+Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures provide facilities for drawing window borders in a
+way that produces a three-dimensional appearance.
+\fBTk_Alloc3DBorderFromObj\fR
+allocates colors and Pixmaps needed to draw a border in the window
+given by the \fItkwin\fR argument.  The value of \fIobjPtr\fR
+is a standard Tk color name that determines the border colors.
+The color indicated by \fIobjPtr\fR will not actually be used in
+the border;  it indicates the background color for the window
+(i.e. a color for flat surfaces).
+The illuminated portions of the border will appear brighter than indicated
+by \fIobjPtr\fR, and the shadowed portions of the border will appear
+darker than \fIobjPtr\fR.
+.PP
+\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
+to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
+for the border (e.g. a bogus color name was given)
+then NULL is returned and an error message is left as the result of
+interpreter \fIinterp\fR.
+If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches
+information about the return value in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
+that the color is specified with a string instead of a value.  This
+prevents \fBTk_Get3DBorder\fR from caching the return value, so
+\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
+.PP
+\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
+the window and color name used to create the border.
+\fBTk_Get3DBorderFromObj\fR does not actually create the border; it must
+already have been created with a previous call to
+\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
+invoked to draw the border.
+The \fItkwin\fR argument specifies the
+window for which the border was allocated, and \fIdrawable\fR
+specifies a window or pixmap in which the border is to be drawn.
+\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it
+must refer to a compatible
+pixmap or window:  one associated with the same screen and with the
+same depth as \fItkwin\fR.
+The \fIx\fR, \fIy\fR, \fIwidth\fR, and
+\fIheight\fR arguments define the bounding box of the border region
+within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
+\fIwidth\fR and \fIheight\fR are the dimensions of the window), and
+\fIborderWidth\fR specifies the number of pixels actually
+occupied by the border.  The \fIrelief\fR argument indicates
+which of several three-dimensional effects is desired:
+\fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should
+appear raised relative to the exterior of the rectangle, and
+\fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed.
+\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be
+a groove or ridge around the exterior of the rectangle.
+.PP
+\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
+that it first fills the rectangular area with the background color
+(one corresponding
+to the color used to create \fIborder\fR).  Then it calls
+\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
+the rectangular area.  The argument \fIrelief\fR indicates the desired
+effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that
+happens is to fill the rectangle with the background color).
+.PP
+The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
+shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
+\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
+indicates how wide the border should be (and on which side of the
+trajectory to draw it), and \fIleftRelief\fR indicates which side
+of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
+draws a border around the given trajectory using the colors from
+\fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
+non-self-intersecting, the appearance will be a raised or sunken
+polygon shape.  The trajectory may be self-intersecting, although
+it's not clear how useful this is.
+.PP
+\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
+\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
+the polygonal area with the background color from \fIborder\fR,
+then calls \fBTk_Draw3DPolygon\fR to draw a border around the
+area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no
+border is drawn).
+.PP
+The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR
+provide lower-level drawing primitives that are used by
+procedures such as \fBTk_Draw3DRectangle\fR.
+These procedures are also useful in their own right for drawing
+rectilinear border shapes.
+\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the
+left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR
+draws a horizontal beveled edge, such as the top or bottom of a
+rectangle.
+Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
+arguments that describe the rectangular area of the beveled edge
+(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR).
+The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the
+position of the border relative to the
+.QW inside
+of the value, and
+\fIrelief\fR indicates the relief of the inside of the value relative
+to the outside.
+\fBTk_3DVerticalBevel\fR just draws a rectangular region.
+\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate
+mitered corners;  it should be called after \fBTk_3DVerticalBevel\fR
+(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in
+the corner).
+The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR
+describe the mitering at the corners;  a value of 1 means that the bottom
+edge of the trapezoid will be shorter than the top, 0 means it will
+be longer.
+For example, to draw a rectangular border the top bevel should be
+drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the
+bottom bevel should be drawn with 0 for both arguments.
+.PP
+The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
+pixel and/or pixmap of \fItkwin\fR to produce a result compatible
+with \fIborder\fR.  For color displays, the resulting background will
+just be the color specified when \fIborder\fR was created;  for monochrome
+displays, the resulting background
+will be a light stipple pattern, in order to distinguish the background from
+the illuminated portion of the border.
+.PP
+Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
+will return the color name that was used to create the border.
+.PP
+The procedure \fBTk_3DBorderColor\fR returns the XColor structure
+that will be used for flat surfaces drawn for its \fIborder\fR
+argument by procedures like \fBTk_Fill3DRectangle\fR.
+The return value corresponds to the color name that was used to
+create the border.
+The XColor, and its associated pixel value, will remain allocated
+as long as \fIborder\fR exists.
+.PP
+The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts
+that are used to draw the border.
+The argument \fIwhich\fR selects which one of the three possible GC's:
+\fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces,
+\fBTK_3D_LIGHT_GC\fR returns the context for light shadows,
+and \fBTK_3D_DARK_GC\fR returns the context for dark shadows.
+.PP
+When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR
+or \fBTk_Free3DBorder\fR should
+be called to release the resources associated with it.
+For \fBTk_Free3DBorderFromObj\fR the border to release is specified
+with the window and color name used to create the
+border; for \fBTk_Free3DBorder\fR the border to release is specified
+with the Tk_3DBorder token for the border.
+There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or
+\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR
+or \fBTk_Get3DBorder\fR.
+.SH KEYWORDS
+3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect

doc/AddOption.3

@@ -0,0 +1,50 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\"
+.TH Tk_AddOption 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_AddOption \- Add an option to the option database
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+void
+\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
+.SH ARGUMENTS
+.AP Tk_Window tkwin in
+Token for window.
+.AP "const char" *name in
+Multi-element name of option.
+.AP "const char" *value in
+Value of option.
+.AP int priority in
+Overall priority level to use for option.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure is invoked to add an option to the database
+associated with \fItkwin\fR's main window.  \fIName\fR
+contains the option being specified and consists of names and/or
+classes separated by asterisks or dots, in the usual X format.
+\fIValue\fR contains the text string to associate with \fIname\fR;
+this value will be returned in calls to \fBTk_GetOption\fR.
+\fIPriority\fR specifies the priority of the value; when options are
+queried using \fBTk_GetOption\fR, the value with the highest priority
+is returned.  \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR.  Some
+common priority values are:
+.IP 20
+Used for default values hard-coded into widgets.
+.IP 40
+Used for options specified in application-specific startup files.
+.IP 60
+Used for options specified in user-specific defaults files, such as
+\fB.Xdefaults\fR, resource databases loaded into the X server, or
+user-specific startup files.
+.IP 80
+Used for options specified interactively after the application starts
+running.
+.SH KEYWORDS
+class, name, option, add

doc/BindTable.3

@@ -0,0 +1,153 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_BindingTable
+\fBTk_CreateBindingTable(\fIinterp\fB)\fR
+.sp
+\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR
+.sp
+unsigned long
+\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR
+.sp
+int
+\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
+.sp
+const char *
+\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
+.sp
+\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR
+.sp
+\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR
+.sp
+\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR
+.SH ARGUMENTS
+.AS Tk_BindingTable bindingTable
+.AP Tcl_Interp *interp in
+Interpreter to use when invoking bindings in binding table.  Also
+used for returning results and errors from binding procedures.
+.AP Tk_BindingTable bindingTable in
+Token for binding table;  must have been returned by some previous
+call to \fBTk_CreateBindingTable\fR.
+.AP ClientData object in
+Identifies object with which binding is associated.
+.AP "const char" *eventString in
+String describing event sequence.
+.AP "const char" *script in
+Tcl script to invoke when binding triggers.
+.AP int append in
+Non-zero means append \fIscript\fR to existing script for binding,
+if any; zero means replace existing script with new one.
+.AP XEvent *eventPtr in
+X event to match against bindings in \fIbindingTable\fR.
+.AP Tk_Window tkwin in
+Identifier for any window on the display where the event occurred.
+Used to find display-related information such as key maps.
+.AP int numObjects in
+Number of object identifiers pointed to by \fIobjectPtr\fR.
+.AP ClientData *objectPtr in
+Points to an array of object identifiers:  bindings will be considered
+for each of these objects in order from first to last.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures provide a general-purpose mechanism for creating
+and invoking bindings.
+Bindings are organized in terms of \fIbinding tables\fR.
+A binding table consists of a collection of bindings plus a history
+of recent events.
+Within a binding table, bindings are associated with \fIobjects\fR.
+The meaning of an object is defined by clients of the binding package.
+For example, Tk keeps uses one binding table to hold all of the bindings
+created by the \fBbind\fR command.
+For this table, objects are pointers to strings such as window names, class
+names, or other binding tags such as \fBall\fR.
+Tk also keeps a separate binding table for each canvas widget, which manages
+bindings created by the canvas's \fBbind\fR widget command;  within
+this table, an object is either a pointer to the internal structure for a
+canvas item or a Tk_Uid identifying a tag.
+.PP
+The procedure \fBTk_CreateBindingTable\fR creates a new binding
+table and associates \fIinterp\fR with it (when bindings in the
+table are invoked, the scripts will be evaluated in \fIinterp\fR).
+\fBTk_CreateBindingTable\fR returns a token for the table, which
+must be used in calls to other procedures such as \fBTk_CreateBinding\fR
+or \fBTk_BindEvent\fR.
+.PP
+\fBTk_DeleteBindingTable\fR frees all of the state associated
+with a binding table.
+Once it returns the caller should not use the \fIbindingTable\fR
+token again.
+.PP
+\fBTk_CreateBinding\fR adds a new binding to an existing table.
+The \fIobject\fR argument identifies the object with which the
+binding is to be associated, and it may be any one-word value.
+Typically it is a pointer to a string or data structure.
+The \fIeventString\fR argument identifies the event or sequence
+of events for the binding;  see the documentation for the
+\fBbind\fR command for a description of its format.
+\fIscript\fR is the Tcl script to be evaluated when the binding
+triggers.
+\fIappend\fR indicates what to do if there already
+exists a binding for \fIobject\fR and \fIeventString\fR:  if \fIappend\fR
+is zero then \fIscript\fR replaces the old script;  if \fIappend\fR
+is non-zero then the new script is appended to the old one.
+\fBTk_CreateBinding\fR returns an X event mask for all the events
+associated with the bindings.
+This information may be useful to invoke \fBXSelectInput\fR to
+select relevant events, or to disallow the use of certain events
+in bindings.
+If an error occurred while creating the binding (e.g., \fIeventString\fR
+refers to a non-existent event), then 0 is returned and an error
+message is left as the result of interpreter \fIinterp\fR.
+.PP
+\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the
+binding given by \fIobject\fR and \fIeventString\fR, if
+such a binding exists.
+\fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR.
+In some cases it may reset the interpreter result to the default
+empty value.
+.PP
+\fBTk_GetBinding\fR returns a pointer to the script associated
+with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR.
+If no such binding exists then NULL is returned and an error
+message is left as the result of interpreter \fIinterp\fR.
+.PP
+\fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list
+of all the event strings for which there are bindings in
+\fIbindingTable\fR associated with \fIobject\fR.
+If there are no bindings for \fIobject\fR, the result will be an empty
+string.
+.PP
+\fBTk_DeleteAllBindings\fR deletes all of the bindings in
+\fIbindingTable\fR that are associated with \fIobject\fR.
+.PP
+\fBTk_BindEvent\fR is called to process an event.
+It makes a copy of the event in an internal history list associated
+with the binding table, then it checks for bindings that match
+the event.
+\fBTk_BindEvent\fR processes each of the objects pointed to
+by \fIobjectPtr\fR in turn.
+For each object, it finds all the bindings that match the current
+event history, selects the most specific binding using the priority
+mechanism described in the documentation for \fBbind\fR,
+and invokes the script for that binding.
+If there are no matching bindings for a particular object, then
+the object is skipped.
+\fBTk_BindEvent\fR continues through all of the objects, handling
+exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as
+described in the documentation for \fBbind\fR.
+.SH KEYWORDS
+binding, event, object, script

doc/CanvPsY.3

@@ -0,0 +1,121 @@
+'\"
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+double
+\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR)
+.sp
+int
+\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR)
+.sp
+int
+\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR)
+.sp
+int
+\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR)
+.sp
+\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR)
+.sp
+int
+\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR)
+.SH ARGUMENTS
+.AS "unsigned int" "numPoints"
+.AP Tk_Canvas canvas in
+A token that identifies a canvas widget for which Postscript is
+being generated.
+.AP double canvasY in
+Y-coordinate in the space of the canvas.
+.AP Tcl_Interp *interp in/out
+A Tcl interpreter;  Postscript is appended to its result, or the
+result may be replaced with an error message.
+.AP Pixmap bitmap in
+Bitmap to use for generating Postscript.
+.AP int x in
+X-coordinate within \fIbitmap\fR of left edge of region to output.
+.AP int y in
+Y-coordinate within \fIbitmap\fR of top edge of region to output.
+.AP "int" width in
+Width of region of bitmap to output, in pixels.
+.AP "int" height in
+Height of region of bitmap to output, in pixels.
+.AP XColor *colorPtr in
+Information about color value to set in Postscript.
+.AP Tk_Font tkFont in
+Font for which Postscript is to be generated.
+.AP double *coordPtr in
+Pointer to an array of coordinates for one or more
+points specified in canvas coordinates.
+The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3,
+and so on.
+.AP int numPoints in
+Number of points at \fIcoordPtr\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are called by canvas type managers to carry out
+common functions related to generating Postscript.
+Most of the procedures take a \fIcanvas\fR argument, which
+refers to a canvas widget for which Postscript is being
+generated.
+.PP
+\fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of
+a canvas and returns the value that should be used for that point
+in the Postscript currently being generated for \fIcanvas\fR.
+Y coordinates require transformation because Postscript uses an
+origin at the lower-left corner whereas X uses an origin at the
+upper-left corner.
+Canvas x coordinates can be used directly in Postscript without
+transformation.
+.PP
+\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region
+of a bitmap.
+The Postscript is generated in proper image data format for Postscript,
+i.e., as data between angle brackets, one bit per pixel.
+The Postscript is appended to the result of interpreter \fIinterp\fR
+and \fBTCL_OK\fR is returned unless an error occurs, in which case
+\fBTCL_ERROR\fR is returned and the interpreter result is overwritten
+with an error message.
+.PP
+\fBTk_CanvasPsColor\fR generates Postscript to set the current color
+to correspond to its \fIcolorPtr\fR argument, taking into account any
+color map specified in the \fBpostscript\fR command.
+It appends the Postscript to the interpreter \fIinterp\fR's result and returns
+\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is
+returned and the interpreter's result is overwritten with an error message.
+.PP
+\fBTk_CanvasPsFont\fR generates Postscript that sets the current font
+to match \fItkFont\fR as closely as possible.
+\fBTk_CanvasPsFont\fR takes into account any font map specified
+in the \fBpostscript\fR command, and it does
+the best it can at mapping X fonts to Postscript fonts.
+It appends the Postscript to interpreter \fIinterp\fR's result and
+returns \fBTCL_OK\fR unless an error occurs, in which case
+\fBTCL_ERROR\fR is returned and the interpreter's result is
+overwritten with an error message.
+.PP
+\fBTk_CanvasPsPath\fR generates Postscript to set the current path
+to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR.
+It appends the resulting Postscript to the result of interpreter \fIinterp\fR.
+.PP
+\fBTk_CanvasPsStipple\fR generates Postscript that will fill the
+current path in stippled fashion.
+It uses \fIbitmap\fR as the stipple pattern and the current Postscript
+color;  ones in the stipple bitmap are drawn in the current color, and
+zeroes are not drawn at all.
+The Postscript is appended to interpreter \fIinterp\fR's result and
+\fBTCL_OK\fR is returned, unless an error occurs, in which case
+\fBTCL_ERROR\fR is returned and the interpreter's result is
+overwritten with an error message.
+.SH KEYWORDS
+bitmap, canvas, color, font, path, Postscript, stipple

doc/CanvTkwin.3

@@ -0,0 +1,158 @@
+'\"
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_CanvasTkwin\fR(\fIcanvas\fR)
+.sp
+int
+\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR)
+.sp
+\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR)
+.sp
+\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR)
+.sp
+\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
+.sp
+\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
+.sp
+Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
+.sp
+Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;
+.SH ARGUMENTS
+.AS Tk_ItemType *drawableXPtr
+.AP Tk_Canvas canvas in
+A token that identifies a canvas widget.
+.AP Tcl_Interp *interp in/out
+Interpreter to use for error reporting.
+.AP "const char" *string in
+Textual description of a canvas coordinate.
+.AP double *doublePtr out
+Points to place to store a converted coordinate.
+.AP double x in
+An x coordinate in the space of the canvas.
+.AP double y in
+A y coordinate in the space of the canvas.
+.AP short *drawableXPtr out
+Pointer to a location in which to store an x coordinate in the space
+of the drawable currently being used to redisplay the canvas.
+.AP short *drawableYPtr out
+Pointer to a location in which to store a y coordinate in the space
+of the drawable currently being used to redisplay the canvas.
+.AP GC gc out
+Graphics context to modify.
+.AP short *screenXPtr out
+Points to a location in which to store the screen coordinate in the
+canvas window that corresponds to \fIx\fR.
+.AP short *screenYPtr out
+Points to a location in which to store the screen coordinate in the
+canvas window that corresponds to \fIy\fR.
+.AP int x1 in
+Left edge of the region that needs redisplay.  Only pixels at or to
+the right of this coordinate need to be redisplayed.
+.AP int y1 in
+Top edge of the region that needs redisplay.  Only pixels at or below
+this coordinate need to be redisplayed.
+.AP int x2 in
+Right edge of the region that needs redisplay.  Only pixels to
+the left of this coordinate need to be redisplayed.
+.AP int y2 in
+Bottom edge of the region that needs redisplay.  Only pixels above
+this coordinate need to be redisplayed.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are called by canvas type managers to perform various
+utility functions.
+.PP
+\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular
+canvas.
+.PP
+\fBTk_CanvasGetCoord\fR translates a string specification of a
+coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision
+canvas coordinate.
+If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR
+stores the corresponding canvas coordinate at *\fIdoublePtr\fR
+and returns \fBTCL_OK\fR.
+Otherwise it stores an error message in the interpreter result and
+returns \fBTCL_ERROR\fR.
+.PP
+\fBTk_CanvasDrawableCoords\fR is called by type managers during
+redisplay to compute where to draw things.
+Given \fIx\fR and \fIy\fR coordinates in the space of the
+canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding
+pixel in the drawable that is currently being used for redisplay;
+it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR.
+This procedure should not be invoked except during redisplay.
+.PP
+\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay.
+It sets the stipple origin in \fIgc\fR so that stipples drawn
+with \fIgc\fR in the current offscreen pixmap will line up
+with stipples drawn with origin (0,0) in the canvas's actual
+window.
+\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee
+that stipple patterns line up properly when the canvas is
+redisplayed in small pieces.
+Redisplays are carried out in double-buffered fashion where a
+piece of the canvas is redrawn in an offscreen pixmap and then
+copied back onto the screen.
+In this approach the stipple origins in graphics contexts need to
+be adjusted during each redisplay to compensate for the position
+of the off-screen pixmap relative to the window.
+If an item is being drawn with stipples, its type manager typically
+calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR
+to draw something;  after it is finished drawing, the type manager
+calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0)
+(the restore is needed because graphics contexts are shared, so
+they cannot be modified permanently).
+.PP
+\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR
+except that it returns coordinates in the canvas's window on the
+screen, instead of coordinates in an off-screen pixmap.
+.PP
+\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager
+to inform Tk that a portion of a canvas needs to be redrawn.
+The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments
+specify the region that needs to be redrawn, in canvas coordinates.
+Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR,
+since Tk can normally figure out when an item has changed and make
+the redisplay request on its behalf (this happens, for example
+whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR).
+The only time that a type manager needs to call
+\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own
+without being invoked through one of the procedures in its Tk_ItemType;
+this could happen, for example, in an image item if the image is
+modified using image commands.
+.PP
+\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are
+procedures that handle the \fB\-tags\fR option for canvas items.
+The code of a canvas type manager will not call these procedures
+directly, but will use their addresses to create a \fBTk_CustomOption\fR
+structure for the \fB\-tags\fR option.   The code typically looks
+like this:
+.PP
+.CS
+static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
+    Tk_CanvasTagsPrintProc, (ClientData) NULL
+};
+
+static const Tk_ConfigSpec configSpecs[] = {
+    ...
+    {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
+        NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
+    ...
+};
+.CE
+.SH KEYWORDS
+canvas, focus, item type, redisplay, selection, type manager

doc/CanvTxtInfo.3

@@ -0,0 +1,100 @@
+'\"
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CanvasTextInfo \- additional information for managing text items in canvases
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_CanvasTextInfo *
+\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR)
+.SH ARGUMENTS
+.AS Tk_Canvas canvas
+.AP Tk_Canvas canvas in
+A token that identifies a particular canvas widget.
+.BE
+.SH DESCRIPTION
+.PP
+Textual canvas items are somewhat more complicated to manage than
+other items, due to things like the selection and the input focus.
+\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager
+to obtain additional information needed for items that display text.
+The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to
+a structure that is shared between Tk and all the items that display
+text.
+The structure has the following form:
+.CS
+typedef struct Tk_CanvasTextInfo {
+    Tk_3DBorder \fIselBorder\fR;
+    int \fIselBorderWidth\fR;
+    XColor *\fIselFgColorPtr\fR;
+    Tk_Item *\fIselItemPtr\fR;
+    int \fIselectFirst\fR;
+    int \fIselectLast\fR;
+    Tk_Item *\fIanchorItemPtr\fR;
+    int \fIselectAnchor\fR;
+    Tk_3DBorder \fIinsertBorder\fR;
+    int \fIinsertWidth\fR;
+    int \fIinsertBorderWidth\fR;
+    Tk_Item *\fIfocusItemPtr\fR;
+    int \fIgotFocus\fR;
+    int \fIcursorOn\fR;
+} \fBTk_CanvasTextInfo\fR;
+.CE
+The \fBselBorder\fR field identifies a Tk_3DBorder that should be
+used for drawing the background under selected text.
+\fIselBorderWidth\fR gives the width of the raised border around
+selected text, in pixels.
+\fIselFgColorPtr\fR points to an XColor that describes the foreground
+color to be used when drawing selected text.
+\fIselItemPtr\fR points to the item that is currently selected, or
+NULL if there is no item selected or if the canvas does not have the
+selection.
+\fIselectFirst\fR and \fIselectLast\fR give the indices of the first
+and last selected characters in \fIselItemPtr\fR, as returned by the
+\fIindexProc\fR for that item.
+\fIanchorItemPtr\fR points to the item that currently has the selection
+anchor;  this is not necessarily the same as \fIselItemPtr\fR.
+\fIselectAnchor\fR is an index that identifies the anchor position
+within \fIanchorItemPtr\fR.
+\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the
+insertion cursor;  \fIinsertWidth\fR gives the total width of the
+insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the
+width of the raised  border around the insertion cursor.
+\fIfocusItemPtr\fR identifies the item that currently has the input
+focus, or NULL if there is no such item.
+\fIgotFocus\fR is 1 if the canvas widget has the input focus and
+0 otherwise.
+\fIcursorOn\fR is 1 if the insertion cursor should be drawn in
+\fIfocusItemPtr\fR and 0 if it should not be drawn;  this field
+is toggled on and off by Tk to make the cursor blink.
+.PP
+The structure returned by \fBTk_CanvasGetTextInfo\fR
+is shared between Tk and the type managers;  typically the type manager
+calls \fBTk_CanvasGetTextInfo\fR once when an item is created and
+then saves the pointer in the item's record.
+Tk will update information in the Tk_CanvasTextInfo;  for example,
+a \fBconfigure\fR widget command might change the \fIselBorder\fR
+field, or a \fBselect\fR widget command might change the \fIselectFirst\fR
+field, or Tk might change \fIcursorOn\fR in order to make the insertion
+cursor flash on and off during successive redisplays.
+.PP
+Type managers should treat all of the fields of the Tk_CanvasTextInfo
+structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR,
+\fIselectLast\fR, and \fIselectAnchor\fR.
+Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and
+\fIselectAnchor\fR to adjust for insertions and deletions in the
+item (but only if the item is the current owner of the selection or
+anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR).
+If all of the selected text in the item is deleted, the item should
+set \fIselItemPtr\fR to NULL to indicate that there is no longer a
+selection.
+.SH KEYWORDS
+canvas, focus, insertion cursor, selection, selection anchor, text

doc/Clipboard.3

@@ -0,0 +1,77 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR)
+.sp
+int
+\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR)
+.SH ARGUMENTS
+.AS Tk_ClipboardClear tkwin
+.AP Tcl_Interp *interp in
+Interpreter to use for reporting errors.
+.AP Tk_Window tkwin in
+Window that determines which display's clipboard to manipulate.
+.AP Atom target in
+Conversion type for this clipboard item;  has same meaning as
+\fItarget\fR argument to \fBTk_CreateSelHandler\fR.
+.AP Atom format in
+Representation to use when data is retrieved;  has same meaning as
+\fIformat\fR argument to \fBTk_CreateSelHandler\fR.
+.AP "const char" *buffer in
+Null terminated string containing the data to be appended to the clipboard.
+.BE
+.SH DESCRIPTION
+.PP
+These two procedures manage the clipboard for Tk.
+The clipboard is typically managed by calling \fBTk_ClipboardClear\fR
+once, then calling \fBTk_ClipboardAppend\fR to add data for any
+number of targets.
+.PP
+\fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any
+data items previously stored on the clipboard in this application.
+It normally returns \fBTCL_OK\fR, but if an error occurs it returns
+\fBTCL_ERROR\fR and leaves an error message in interpreter
+\fIinterp\fR's result.
+\fBTk_ClipboardClear\fR must be called before a sequence of
+\fBTk_ClipboardAppend\fR calls can be issued.
+.PP
+\fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard.
+The first buffer for a given \fItarget\fR determines the \fIformat\fR
+for that \fItarget\fR.
+Any successive appends for that \fItarget\fR must have
+the same format or an error will be returned.
+\fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is
+successfully copied onto the clipboard.  If the clipboard is not
+currently owned by the application, either
+because \fBTk_ClipboardClear\fR has not been called or because
+ownership of the clipboard has changed since the last call to
+\fBTk_ClipboardClear\fR,
+\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error
+message in the result of interpreter \fIinterp\fR.
+.PP
+In order to guarantee atomicity, no event handling should occur
+between \fBTk_ClipboardClear\fR and the following
+\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve
+a partially completed clipboard or claim ownership away from
+this application).
+.PP
+\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary
+Tcl scripts, as a result of losing the CLIPBOARD selection, so
+any calling function should take care to be re-entrant at the point
+\fBTk_ClipboardClear\fR is invoked.
+.SH KEYWORDS
+append, clipboard, clear, format, type

doc/ClrSelect.3

@@ -0,0 +1,38 @@
+'\"
+'\" Copyright (c) 1992-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ClearSelection \- Deselect a selection
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_ClearSelection\fR(\fItkwin, selection\fR)
+.SH ARGUMENTS
+.AS Tk_Window tkwin
+.AP Tk_Window tkwin in
+The selection will be cleared from the display containing this
+window.
+.AP Atom selection in
+The name of selection to be cleared.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_ClearSelection\fR cancels the selection specified by the atom
+\fIselection\fR for the display containing \fItkwin\fR.
+The selection need not be in \fItkwin\fR itself or even in
+\fItkwin\fR's application.
+If there is a window anywhere on \fItkwin\fR's display that
+owns \fIselection\fR, the window will be notified and the
+selection will be cleared.
+If there is no owner for \fIselection\fR on the display, then the
+procedure has no effect.
+.SH KEYWORDS
+clear, selection

doc/ConfigWidg.3

@@ -0,0 +1,631 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
+.sp
+int
+\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
+.sp
+int
+\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
+.sp
+\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
+.SH ARGUMENTS
+.AS char *widgRec in/out
+.AP Tcl_Interp *interp in
+Interpreter to use for returning error messages.
+.AP Tk_Window tkwin in
+Window used to represent widget (needed to set up X resources).
+.AP "const Tk_ConfigSpec" *specs in
+Pointer to table specifying legal configuration options for this
+widget.
+.AP int argc in
+Number of arguments in \fIargv\fR.
+.AP "const char" **argv in
+Command-line options for configuring widget.
+.AP char *widgRec in/out
+Points to widget record structure.  Fields in this structure get
+modified by \fBTk_ConfigureWidget\fR to hold configuration information.
+.AP int flags in
+If non-zero, then it specifies an OR-ed combination of flags that
+control the processing of configuration information.
+\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be
+ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to
+selectively disable entries in \fIspecs\fR.
+.AP "type name" type in
+The name of the type of a widget record.
+.AP "field name" field in
+The name of a field in records of type \fItype\fR.
+.AP "const char" *argvName in
+The name used on Tcl command lines to refer to a particular option
+(e.g. when creating a widget or invoking the \fBconfigure\fR widget
+command).  If non-NULL, then information is returned only for this
+option.  If NULL, then information is returned for all available
+options.
+.AP Display *display in
+Display containing widget whose record is being freed;  needed in
+order to free up resources.
+.BE
+.SH DESCRIPTION
+.PP
+Note: \fBTk_ConfigureWidget\fR should be replaced with the new
+\fBTcl_Obj\fR based API \fBTk_SetOptions\fR.  The old interface is
+retained for backward compatibility.
+.PP
+\fBTk_ConfigureWidget\fR is called to configure various aspects of a
+widget, such as colors, fonts, border width, etc.
+It is intended as a convenience procedure to reduce the amount
+of code that must be written in individual widget managers to
+handle configuration information.
+It is typically
+invoked when widgets are created, and again when the \fBconfigure\fR
+command is invoked for a widget.
+Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
+can be used in other situations where \fIargc-argv\fR information
+is to be used to fill in a record structure, such as configuring
+graphical elements for a canvas widget or entries of a menu.
+.PP
+\fBTk_ConfigureWidget\fR processes
+a table specifying the configuration options that are supported
+(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
+\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
+It uses the option database and defaults specified in \fIspecs\fR
+to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
+\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
+case it does not modify \fIinterp\fR.
+If an error
+occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
+leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
+fashion.
+In the event of an error return, some of the fields of \fIwidgRec\fR
+could already have been set, if configuration information for them
+was successfully processed before the error occurred.
+The other fields will be set to reasonable initial values so that
+\fBTk_FreeOptions\fR can be called for cleanup.
+.PP
+The \fIspecs\fR array specifies the kinds of configuration options
+expected by the widget.  Each of its entries specifies one configuration
+option and has the following structure:
+.CS
+typedef struct {
+    int \fItype\fR;
+    const char *\fIargvName\fR;
+    const char *\fIdbName\fR;
+    const char *\fIdbClass\fR;
+    const char *\fIdefValue\fR;
+    int \fIoffset\fR;
+    int \fIspecFlags\fR;
+    const Tk_CustomOption *\fIcustomPtr\fR;
+} \fBTk_ConfigSpec\fR;
+.CE
+The \fItype\fR field indicates what type of configuration option this is
+(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
+an integer value).  The \fItype\fR field indicates how to use the
+value of the option (more on this below).
+The \fIargvName\fR field is a string such as
+.QW \-font
+or
+.QW \-bg ,
+which is compared with the values in \fIargv\fR (if \fIargvName\fR is
+NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
+\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
+for this option in the option database.  The \fIdefValue\fR field
+specifies a default value for this configuration option if no
+value is specified in either \fIargv\fR or the option database.
+\fIOffset\fR indicates where in \fIwidgRec\fR to store information
+about this option, and \fIspecFlags\fR contains additional information
+to control the processing of this configuration option (see FLAGS
+below).
+The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
+\fBTK_CONFIG_CUSTOM\fR;  see CUSTOM OPTION TYPES below.
+.PP
+\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
+(if any) configuration options are specified there.  \fIArgv\fR
+must contain an even number of fields;  the first of each pair
+of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
+(unique abbreviations are acceptable),
+and the second field of the pair contains the value for that
+configuration option.  If there are entries in \fIspec\fR for which
+there were no matching entries in \fIargv\fR,
+\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
+fields of the \fIspecs\fR entry to probe the option database;  if
+a value is found, then it is used as the value for the option.
+Finally, if no entry is found in the option database, the
+\fIdefValue\fR field of the \fIspecs\fR entry is used as the
+value for the configuration option.  If the \fIdefValue\fR is
+NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
+\fIflags\fR, then there is no default value and this \fIspecs\fR entry
+will be ignored if no value is specified in \fIargv\fR or the
+option database.
+.PP
+Once a string value has been determined for a configuration option,
+\fBTk_ConfigureWidget\fR translates the string value into a more useful
+form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
+if \fItype\fR is \fBTK_CONFIG_INT\fR.  This value is then stored in the
+record pointed to by \fIwidgRec\fR.  This record is assumed to
+contain information relevant to the manager of the widget;  its exact
+type is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR field
+of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
+the information about this configuration option.  You should use the
+\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
+a description of \fBTk_Offset\fR).  The location indicated by
+\fIwidgRec\fR and \fIoffset\fR will be referred to as the
+.QW target
+in the descriptions below.
+.PP
+The \fItype\fR field of each entry in \fIspecs\fR determines what
+to do with the string value of that configuration option.  The
+legal values for \fItype\fR, and the corresponding actions, are:
+.TP
+\fBTK_CONFIG_ACTIVE_CURSOR\fR
+The value
+must be an ASCII string identifying a cursor in a form
+suitable for passing to \fBTk_GetCursor\fR.
+The value is converted to a \fBTk_Cursor\fR by calling
+\fBTk_GetCursor\fR and the result is stored in the target.
+In addition, the resulting cursor is made the active cursor
+for \fItkwin\fR by calling \fBXDefineCursor\fR.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target and \fItkwin\fR's
+active cursor will be set to \fBNone\fR.
+If the previous value of the target
+was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
+.TP
+\fBTK_CONFIG_ANCHOR\fR
+The value must be an ASCII string identifying an anchor point in one of the ways
+accepted by \fBTk_GetAnchor\fR.
+The string is converted to a \fBTk_Anchor\fR by calling
+\fBTk_GetAnchor\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_BITMAP\fR
+The value must be an ASCII string identifying a bitmap in a form
+suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
+to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
+is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target is set to \fBNone\fR.
+If the previous value of the target
+was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
+.TP
+\fBTK_CONFIG_BOOLEAN\fR
+The value must be an ASCII string specifying a boolean value.  Any
+of the values
+.QW true ,
+.QW yes ,
+.QW on ,
+or
+.QW 1 ,
+or an abbreviation of one of these values, means true;
+any of the values
+.QW false ,
+.QW no ,
+.QW off ,
+or
+.QW 0 ,
+or an abbreviation of one of these values, means false.
+The target is expected to be an integer;  for true values it will
+be set to 1 and for false values it will be set to 0.
+.TP
+\fBTK_CONFIG_BORDER\fR
+The value must be an ASCII string identifying a border color in a form
+suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
+to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
+is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target
+was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
+.TP
+\fBTK_CONFIG_CAP_STYLE\fR
+The value must be
+an ASCII string identifying a cap style in one of the ways
+accepted by \fBTk_GetCapStyle\fR.
+The string is converted to an integer value corresponding
+to the cap style by calling
+\fBTk_GetCapStyle\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_COLOR\fR
+The value must be an ASCII string identifying a color in a form
+suitable for passing to \fBTk_GetColor\fR.  The value is converted
+to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
+is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to \fBNone\fR.
+If the previous value of the target
+was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
+.TP
+\fBTK_CONFIG_CURSOR\fR
+This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
+that the new cursor is not made the active one for \fItkwin\fR.
+.TP
+\fBTK_CONFIG_CUSTOM\fR
+This option allows applications to define new option types.
+The \fIcustomPtr\fR field of the entry points to a structure
+defining the new option type.
+See the section \fBCUSTOM OPTION TYPES\fR below for details.
+.TP
+\fBTK_CONFIG_DOUBLE\fR
+The value must be an ASCII floating-point number in
+the format accepted by \fBstrtol\fR.  The string is converted
+to a \fBdouble\fR value, and the value is stored in the
+target.
+.TP
+\fBTK_CONFIG_END\fR
+Marks the end of the table.  The last entry in \fIspecs\fR
+must have this type;  all of its other fields are ignored and it
+will never match any arguments.
+.TP
+\fBTK_CONFIG_FONT\fR
+The value must be an ASCII string identifying a font in a form
+suitable for passing to \fBTk_GetFont\fR.  The value is converted
+to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
+is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target
+was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
+.TP
+\fBTK_CONFIG_INT\fR
+The value must be an ASCII integer string
+in the format accepted by \fBstrtol\fR (e.g.
+.QW 0
+and
+.QW 0x
+prefixes may be used to specify octal or hexadecimal
+numbers, respectively).  The string is converted to an integer
+value and the integer is stored in the target.
+.TP
+\fBTK_CONFIG_JOIN_STYLE\fR
+The value must be
+an ASCII string identifying a join style in one of the ways
+accepted by \fBTk_GetJoinStyle\fR.
+The string is converted to an integer value corresponding
+to the join style by calling
+\fBTk_GetJoinStyle\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_JUSTIFY\fR
+The value must be
+an ASCII string identifying a justification method in one of the
+ways accepted by \fBTk_GetJustify\fR.
+The string is converted to a \fBTk_Justify\fR by calling
+\fBTk_GetJustify\fR and the result is stored in the target.
+.TP
+\fBTK_CONFIG_MM\fR
+The value must specify a screen distance in one of the forms acceptable
+to \fBTk_GetScreenMM\fR.
+The string is converted to double-precision floating-point distance
+in millimeters and the value is stored in the target.
+.TP
+\fBTK_CONFIG_PIXELS\fR
+The value must specify screen units in one of the forms acceptable
+to \fBTk_GetPixels\fR.
+The string is converted to an integer distance in pixels and the
+value is stored in the target.
+.TP
+\fBTK_CONFIG_RELIEF\fR
+The value must be an ASCII string identifying a relief in a form
+suitable for passing to \fBTk_GetRelief\fR.  The value is converted
+to an integer relief value by calling \fBTk_GetRelief\fR and the result
+is stored in the target.
+.TP
+\fBTK_CONFIG_STRING\fR
+A copy
+of the value is made by allocating memory space with
+\fBTcl_Alloc\fR and copying the value into the dynamically-allocated
+space.  A pointer to the new string is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
+may be an empty string, in which case the target will be set to NULL.
+If the previous value of the target was not NULL, then it is
+freed by passing it to \fBTcl_Free\fR.
+.TP
+\fBTK_CONFIG_SYNONYM\fR
+This \fItype\fR value identifies special entries in \fIspecs\fR that
+are synonyms for other entries.  If an \fIargv\fR value matches the
+\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
+directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
+for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
+field in the \fBTK_CONFIG_SYNONYM\fR entry;  this new entry is used just
+as if its \fIargvName\fR had matched the \fIargv\fR value.  The
+synonym mechanism allows multiple \fIargv\fR values to be used for
+a single configuration option, such as
+.QW \-background
+and
+.QW \-bg .
+.TP
+\fBTK_CONFIG_UID\fR
+The value is translated to a \fBTk_Uid\fR
+(by passing it to \fBTk_GetUid\fR).  The resulting value
+is stored in the target.
+If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
+is an empty string then the target will be set to NULL.
+.TP
+\fBTK_CONFIG_WINDOW\fR
+The value must be a window path name.  It is translated to a
+\fBTk_Window\fR token and the token is stored in the target.
+.SH "GROUPED ENTRIES"
+.PP
+In some cases it is useful to generate multiple resources from
+a single configuration value.  For example, a color name might
+be used both to generate the background color for a widget (using
+\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the
+widget (using \fBTK_CONFIG_BORDER\fR).  In cases like this it is possible
+to specify that several consecutive entries in \fIspecs\fR are to
+be treated as a group.  The first entry is used to determine a value
+(using its \fIargvName\fR, \fIdbName\fR,
+\fIdbClass\fR, and \fIdefValue\fR fields).  The value will be processed
+several times (one for each entry in the group), generating multiple
+different resources and modifying multiple targets within \fIwidgRec\fR.
+Each of the entries after the first must have a NULL value in its
+\fIargvName\fR field;  this indicates that the entry is to be grouped
+with the entry that precedes it.  Only the \fItype\fR and \fIoffset\fR
+fields are used from these follow-on entries.
+.SH "FLAGS"
+.PP
+The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
+in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
+to provide additional control over the processing of configuration
+options.  These values are used in three different ways as
+described below.
+.PP
+First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
+the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),
+then the option database and
+\fIdefValue\fR fields are not used.  In this case, if an entry in
+\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
+the corresponding target is not modified.  This feature is useful
+when the goal is to modify certain configuration options while
+leaving others in their current state, such as when a \fBconfigure\fR
+widget command is being processed.
+.PP
+Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
+to control the processing of that entry.  Each \fIspecFlags\fR
+field may consists of an OR-ed combination of the following values:
+.TP
+\fBTK_CONFIG_COLOR_ONLY\fR
+If this bit is set then the entry will only be considered if the
+display for \fItkwin\fR has more than one bit plane.  If the display
+is monochromatic then this \fIspecs\fR entry will be ignored.
+.TP
+\fBTK_CONFIG_MONO_ONLY\fR
+If this bit is set then the entry will only be considered if the
+display for \fItkwin\fR has exactly one bit plane.  If the display
+is not monochromatic then this \fIspecs\fR entry will be ignored.
+.TP
+\fBTK_CONFIG_NULL_OK\fR
+This bit is only relevant for some types of entries (see the
+descriptions of the various entry types above).
+If this bit is set, it indicates that an empty string value
+for the field is acceptable and if it occurs then the
+target should be set to NULL or \fBNone\fR, depending
+on the type of the target.
+This flag is typically used to allow a
+feature to be turned off entirely, e.g. set a cursor value to
+\fBNone\fR so that a window simply inherits its parent's cursor.
+If this bit is not set then empty strings are processed as strings,
+which generally results in an error.
+.TP
+\fBTK_CONFIG_DONT_SET_DEFAULT\fR
+If this bit is one, it means that the \fIdefValue\fR field of the
+entry should only be used for returning the default value in
+\fBTk_ConfigureInfo\fR.
+In calls to \fBTk_ConfigureWidget\fR no default will be supplied
+for entries with this flag set;  it is assumed that the
+caller has already supplied a default value in the target location.
+This flag provides a performance optimization where it is expensive
+to process the default string:  the client can compute the default
+once, save the value, and provide it before calling
+\fBTk_ConfigureWidget\fR.
+.TP
+\fBTK_CONFIG_OPTION_SPECIFIED\fR
+This bit is
+deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
+so that callers could detect what entries were specified in
+\fIargv\fR, but it was removed because it was inherently
+thread-unsafe. Code that wishes to detect what options were specified
+should use \fBTk_SetOptions\fR instead.
+.PP
+The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
+used to specify different default values for
+monochrome and color displays.  This is done by creating two
+entries in \fIspecs\fR that are identical except for their
+\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
+the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
+default value for monochrome displays in its \fIdefValue\fR;  the
+other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in
+its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
+color displays.
+.PP
+Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
+together to selectively disable some entries.  This feature is
+not needed very often.  It is useful in cases where several
+similar kinds of widgets are implemented in one place.  It allows
+a single \fIspecs\fR table to be created with all the configuration
+options for all the widget types.  When processing a particular
+widget type, only entries relevant to that type will be used.  This
+effect is achieved by setting the high-order bits (those in positions
+equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR
+values or in \fIflags\fR.  In order for a particular entry in
+\fIspecs\fR to be used, its high-order bits must match exactly
+the high-order bits of the \fIflags\fR value passed to
+\fBTk_ConfigureWidget\fR.  If a \fIspecs\fR table is being used
+for N different widget types, then N of the high-order bits will
+be used.  Each \fIspecs\fR entry will have one of more of those
+bits set in its \fIspecFlags\fR field to indicate the widget types
+for which this entry is valid.  When calling \fBTk_ConfigureWidget\fR,
+\fIflags\fR will have a single one of these bits set to select the
+entries for the desired widget type.  For a working example of
+this feature, see the code in tkButton.c.
+.SH TK_OFFSET
+.PP
+The \fBTk_Offset\fR macro is provided as a safe way of generating
+the \fIoffset\fR values for entries in Tk_ConfigSpec structures.
+It takes two arguments:  the name of a type of record, and the
+name of a field in that record.  It returns the byte offset of
+the named field in records of the given type.
+.SH TK_CONFIGUREINFO
+.PP
+The \fBTk_ConfigureInfo\fR procedure may be used to obtain
+information about one or all of the options for a given widget.
+Given a token for a window (\fItkwin\fR), a table describing the
+configuration options for a class of widgets (\fIspecs\fR), a
+pointer to a widget record containing the current information for
+a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
+\fBTk_ConfigureInfo\fR generates a string describing all of the
+configuration options for the window.  The string is placed
+in interpreter \fIinterp\fR's result.  Under normal circumstances
+it returns \fBTCL_OK\fR;  if an error occurs then it returns \fBTCL_ERROR\fR
+and the interpreter's result will contain an error message.
+.PP
+If \fIargvName\fR is NULL, then the value left in
+the interpreter's result by \fBTk_ConfigureInfo\fR
+consists of a list of one or more entries, each of which describes
+one configuration option (i.e. one entry in \fIspecs\fR).  Each
+entry in the list will contain either two or five values.  If the
+corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then
+the list will contain two values:  the \fIargvName\fR for the entry
+and the \fIdbName\fR (synonym name).  Otherwise the list will contain
+five values:  \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
+and current value.  The current value is computed from the appropriate
+field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
+.PP
+If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
+then it indicates a single option, and information is returned only
+for that option.  The string placed in the interpreter's result will be
+a list containing two or five values as described above;  this will
+be identical to the corresponding sublist that would have been returned
+if \fIargvName\fR had been NULL.
+.PP
+The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
+the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
+.SH TK_CONFIGUREVALUE
+.PP
+\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
+instead of returning a list of values, it just returns the current value
+of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
+The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is
+normally returned as the procedure's result.
+If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
+not a valid option name), \fBTCL_ERROR\fR is returned and an error message
+is left in the interpreter's result.
+This procedure is typically called to implement \fBcget\fR widget
+commands.
+.SH TK_FREEOPTIONS
+.PP
+The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
+to release all of the resources associated with configuration options.
+It scans through \fIspecs\fR and for each entry corresponding to a
+resource that must be explicitly freed (e.g. those with
+type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record.
+If the field in the widget record does not refer to a resource (e.g.
+it contains a null pointer) then no resource is freed for that
+entry.
+After freeing a resource, \fBTk_FreeOptions\fR sets the
+corresponding field of the widget record to null.
+.SH "CUSTOM OPTION TYPES"
+.PP
+Applications can extend the built-in configuration types with additional
+configuration types by writing procedures to parse and print options
+of the a type and creating a structure pointing to those procedures:
+.CS
+typedef struct Tk_CustomOption {
+    Tk_OptionParseProc *\fIparseProc\fR;
+    Tk_OptionPrintProc *\fIprintProc\fR;
+    ClientData \fIclientData\fR;
+} \fBTk_CustomOption\fR;
+
+typedef int \fBTk_OptionParseProc\fR(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Window \fItkwin\fR,
+        char *\fIvalue\fR,
+        char *\fIwidgRec\fR,
+        int \fIoffset\fR);
+
+typedef const char *\fBTk_OptionPrintProc\fR(
+        ClientData \fIclientData\fR,
+        Tk_Window \fItkwin\fR,
+        char *\fIwidgRec\fR,
+        int \fIoffset\fR,
+        Tcl_FreeProc **\fIfreeProcPtr\fR);
+.CE
+The Tk_CustomOption structure contains three fields, which are pointers
+to the two procedures and a \fIclientData\fR value to be passed to those
+procedures when they are invoked.  The \fIclientData\fR value typically
+points to a structure containing information that is needed by the
+procedures when they are parsing and printing options.
+.PP
+The \fIparseProc\fR procedure is invoked by
+\fBTk_ConfigureWidget\fR to parse a string and store the resulting
+value in the widget record.
+The \fIclientData\fR argument is a copy of the \fIclientData\fR
+field in the Tk_CustomOption structure.
+The \fIinterp\fR argument points to a Tcl interpreter used for
+error reporting.  \fITkwin\fR is a copy of the \fItkwin\fR argument
+to \fBTk_ConfigureWidget\fR.  The \fIvalue\fR argument is a string
+describing the value for the option;  it could have been specified
+explicitly in the call to \fBTk_ConfigureWidget\fR or it could
+come from the option database or a default.
+\fIValue\fR will never be a null pointer but it may point to
+an empty string.
+\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
+\fBTk_ConfigureWidget\fR;  it points to the start of the widget
+record to modify.
+The last argument, \fIoffset\fR, gives the offset in bytes from the start
+of the widget record to the location where the option value is to
+be placed.  The procedure should translate the string to whatever
+form is appropriate for the option and store the value in the widget
+record.  It should normally return \fBTCL_OK\fR, but if an error occurs
+in translating the string to a value then it should return \fBTCL_ERROR\fR
+and store an error message in interpreter \fIinterp\fR's result.
+.PP
+The \fIprintProc\fR procedure is called
+by \fBTk_ConfigureInfo\fR to produce a string value describing an
+existing option.
+Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
+arguments all have the same meaning as for Tk_OptionParseProc
+procedures.
+The \fIprintProc\fR procedure should examine the option whose value
+is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
+that option, and return a pointer to the string.
+If the string is stored in dynamically-allocated memory, then
+the procedure must set \fI*freeProcPtr\fR to the address of
+a procedure to call to free the string's memory;  \fBTk_ConfigureInfo\fR
+will call this procedure when it is finished with the string.
+If the result string is stored in static memory then \fIprintProc\fR
+need not do anything with the \fIfreeProcPtr\fR argument.
+.PP
+Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
+Tk_CustomOption structure has been created for them, options of this
+new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
+fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point
+to the Tk_CustomOption structure.
+.SH EXAMPLES
+.PP
+Although the explanation of \fBTk_ConfigureWidget\fR is fairly
+complicated, its actual use is pretty straightforward.
+The easiest way to get started is to copy the code
+from an existing widget.
+The library implementation of frames
+(tkFrame.c) has a simple configuration table, and the library
+implementation of buttons (tkButton.c) has a much more complex
+table that uses many of the fancy \fIspecFlags\fR mechanisms.
+.SH "SEE ALSO"
+Tk_SetOptions(3)
+.SH KEYWORDS
+anchor, bitmap, boolean, border, cap style, color, configuration options,
+cursor, custom, double, font, integer, join style, justify, millimeters,
+pixels, relief, synonym, uid

doc/ConfigWind.3

@@ -0,0 +1,147 @@
+'\"
+'\" Copyright (c) 1990-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR)
+.sp
+\fBTk_MoveWindow\fR(\fItkwin, x, y\fR)
+.sp
+\fBTk_ResizeWindow\fR(\fItkwin, width, height\fR)
+.sp
+\fBTk_MoveResizeWindow\fR(\fItkwin, x,  y, width, height\fR)
+.sp
+\fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR)
+.sp
+\fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR)
+.sp
+\fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR)
+.sp
+\fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR)
+.sp
+\fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR)
+.sp
+\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
+.sp
+\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
+.sp
+\fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
+.sp
+\fBTk_UndefineCursor\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS XSetWindowAttributes borderWidth
+.AP Tk_Window tkwin in
+Token for window.
+.AP "unsigned int" valueMask in
+OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
+indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.
+.AP XWindowChanges *valuePtr in
+Points to a structure containing new values for the configuration
+parameters selected by \fIvalueMask\fR.  Fields not selected
+by \fIvalueMask\fR are ignored.
+.AP int x in
+New x-coordinate for \fItkwin\fR's top left pixel (including
+border, if any) within tkwin's parent.
+.AP int y in
+New y-coordinate for \fItkwin\fR's top left pixel (including
+border, if any) within tkwin's parent.
+.AP "int" width in
+New width for \fItkwin\fR (interior, not including border).
+.AP "int" height in
+New height for \fItkwin\fR (interior, not including border).
+.AP "int" borderWidth in
+New width for \fItkwin\fR's border.
+.AP XSetWindowAttributes *attsPtr in
+Points to a structure containing new values for the attributes
+given by the \fIvalueMask\fR argument.  Attributes not selected
+by \fIvalueMask\fR are ignored.
+.AP "unsigned long" pixel in
+New background or border color for window.
+.AP Pixmap pixmap in
+New pixmap to use for background or border of \fItkwin\fR.  WARNING:
+cannot necessarily be deleted immediately, as for Xlib calls.  See
+note below.
+.AP Colormap colormap in
+New colormap to use for \fItkwin\fR.
+.AP Tk_Cursor cursor in
+New cursor to use for \fItkwin\fR.  If \fBNone\fR is specified, then
+\fItkwin\fR will not have its own cursor;  it will use the cursor
+of its parent.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are analogous to the X library procedures
+with similar names, such as \fBXConfigureWindow\fR.  Each
+one of the above procedures calls the corresponding X procedure
+and also saves the configuration information in Tk's local
+structure for the window.  This allows the information to
+be retrieved quickly by the application (using macros such
+as \fBTk_X\fR and \fBTk_Height\fR) without having to contact
+the X server.  In addition, if no X window has actually been
+created for \fItkwin\fR yet, these procedures do not issue
+X operations or cause event handlers to be invoked;  they save
+the information in Tk's local
+structure for the window;  when the window is created later,
+the saved information will be used to configure the window.
+.PP
+See the X library documentation for details on what these
+procedures do and how they use their arguments.
+.PP
+In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR,
+\fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and
+\fBTk_SetWindowBorderWidth\fR,
+if \fItkwin\fR is an internal window then event handlers interested
+in configure events are invoked immediately, before the procedure
+returns.  If \fItkwin\fR is a top-level window
+then the event handlers will be invoked later, after X has seen
+the request and returned an event for it.
+.PP
+Applications using Tk should never call procedures like
+\fBXConfigureWindow\fR directly;  they should always use the
+corresponding Tk procedures.
+.PP
+The size and location of a window should only be modified by the
+appropriate geometry manager for that window and never by a window
+itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level
+window).
+.PP
+You may not use \fBTk_ConfigureWindow\fR to change the
+stacking order of a window (\fIvalueMask\fR may not contain the
+\fBCWSibling\fR or \fBCWStackMode\fR bits).
+To change the stacking order, use the procedure \fBTk_RestackWindow\fR.
+.PP
+The procedure \fBTk_SetWindowColormap\fR will automatically add
+\fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its
+nearest top-level ancestor if the new colormap is different from
+that of \fItkwin\fR's parent and \fItkwin\fR is not already in
+the \fBTK_COLORMAP_WINDOWS\fR property.
+.SH BUGS
+.PP
+\fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR
+differ slightly from their Xlib counterparts in that the \fIpixmap\fR
+argument may not necessarily be deleted immediately after calling
+one of these procedures.  This is because \fItkwin\fR's window
+may not exist yet at the time of the call, in which case \fIpixmap\fR
+is merely saved and used later when \fItkwin\fR's window is actually
+created.  If you wish to delete \fIpixmap\fR, then call
+\fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists
+and \fIpixmap\fR has been passed to the X server.
+.PP
+A similar problem occurs for the \fIcursor\fR argument passed to
+\fBTk_DefineCursor\fR.  The solution is the same as for pixmaps above:
+call \fBTk_MakeWindowExist\fR before freeing the cursor.
+.SH "SEE ALSO"
+Tk_MoveToplevelWindow, Tk_RestackWindow
+.SH KEYWORDS
+attributes, border, color, configure, height, pixel, pixmap, width, window, x, y

doc/CoordToWin.3

@@ -0,0 +1,47 @@
+'\"
+'\" Copyright (c) 1990-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CoordsToWindow \- Find window containing a point
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR)
+.SH ARGUMENTS
+.AS Tk_Window tkwin
+.AP int rootX in
+X-coordinate (in root window coordinates).
+.AP int rootY in
+Y-coordinate (in root window coordinates).
+.AP Tk_Window tkwin in
+Token for window that identifies application.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CoordsToWindow\fR locates the window that contains a given point.
+The point is specified in root coordinates with \fIrootX\fR and
+\fIrootY\fR (if a virtual-root window manager is in use then
+\fIrootX\fR and \fIrootY\fR are in the coordinate system of the
+virtual root window).
+The return value from the procedure is a token for the window that
+contains the given point.
+If the point is not in any window, or if the containing window
+is not in the same application as \fItkwin\fR, then NULL is
+returned.
+.PP
+The containing window is decided using the same rules that determine
+which window contains the mouse cursor:  if a parent and a child both
+contain the point then the child gets preference, and if two siblings
+both contain the point then the highest one in the stacking order
+(i.e. the one that's visible on the screen) gets preference.
+.SH KEYWORDS
+containing, coordinates, root window

doc/CrtCmHdlr.3

@@ -0,0 +1,64 @@
+'\"
+'\" Copyright (c) 2000 Ajuba Solutions.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateClientMessageHandler\fR(\fIproc\fR)
+.sp
+\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR)
+.SH ARGUMENTS
+.AP Tk_ClientMessageProc *proc in
+Procedure to invoke whenever a ClientMessage X event occurs on any display.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked
+in the future whenever a ClientMessage X event occurs that is not handled by
+\fBWM_PROTOCOL\fR.  \fBTk_CreateClientMessageHandler\fR is intended for use
+by applications which need to watch X ClientMessage events, such as drag and
+drop applications.
+.PP
+The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
+this mechanism only works in programs that dispatch events
+through \fBTk_HandleEvent\fR (or through other Tk procedures that
+call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
+\fBTk_MainLoop\fR).
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTk_ClientMessageProc\fR:
+.CS
+typedef int \fBTk_ClientMessageProc\fR(
+        Tk_Window \fItkwin\fR,
+        XEvent *\fIeventPtr\fR);
+.CE
+The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is
+associated with this event.  \fIEventPtr\fR is a pointer to the X event.
+.PP
+Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR,
+the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR.
+The return value from \fIproc\fR is normally 0.
+A non-zero return value indicates that the event is not to be handled
+further; that is, \fIproc\fR has done all processing that is to be
+allowed for the event.
+.PP
+If there are multiple ClientMessage event handlers, each one is called
+for each event, in the order in which they were established.
+.PP
+\fBTk_DeleteClientMessageHandler\fR may be called to delete a
+previously-created ClientMessage event handler: it deletes each handler it
+finds that matches the \fIproc\fR argument.  If no such handler exists,
+then \fBTk_DeleteClientMessageHandler\fR returns without doing anything.
+Although Tk supports it, it's probably a bad idea to have more than one
+callback with the same \fIproc\fR argument.
+.SH KEYWORDS
+bind, callback, event, handler

doc/CrtConsoleChan.3

@@ -0,0 +1,44 @@
+'\"
+'\" Copyright (c) 2007 ActiveState Software Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_InitConsoleChannels \- Install the console channels as standard channels
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_InitConsoleChannels\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp in
+.AP Tcl_Interp *interp in
+Interpreter in which the console channels are created.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_InitConsoleChannels\fR is invoked to create a set of console
+channels and install them as the standard channels. All I/O on these
+channels will be discarded until \fBTk_CreateConsoleWindow\fR is
+called to attach the console to a text widget.
+.PP
+This function is for use by shell applications based on Tk, like
+\fBwish\fR, on platforms which have no standard channels in graphical
+mode, like Win32.
+.PP
+The \fIinterp\fR argument is the interpreter in which to create and
+install the console channels.
+.PP
+\fBNOTE:\fR If this function is used it has to be called before the
+first call to \fBTcl_RegisterChannel\fR, directly, or indirectly
+through other channel functions. Because otherwise the standard
+channels will be already initialized to the system defaults, which will
+be nonsensical for the case \fBTk_InitConsoleChannels\fR is for.
+.SH "SEE ALSO"
+console(n)
+.SH KEYWORDS
+standard channels, console

doc/CrtErrHdlr.3

@@ -0,0 +1,140 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_ErrorHandler
+\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
+.sp
+\fBTk_DeleteErrorHandler\fR(\fIhandler\fR)
+.SH ARGUMENTS
+.AS "Tk_ErrorHandler" clientData
+.AP Display *display in
+Display whose errors are to be handled.
+.AP int error in
+Match only error events with this value in the \fIerror_code\fR
+field.  If \-1, then match any \fIerror_code\fR value.
+.AP int request in
+Match only error events with this value in the \fIrequest_code\fR
+field.  If \-1, then match any \fIrequest_code\fR value.
+.AP int minor in
+Match only error events with this value in the \fIminor_code\fR
+field.  If \-1, then match any \fIminor_code\fR value.
+.AP Tk_ErrorProc *proc in
+Procedure to invoke whenever an error event is received for
+\fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR.
+NULL means ignore any matching errors.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.AP Tk_ErrorHandler handler in
+Token for error handler to delete (return value from a previous
+call to \fBTk_CreateErrorHandler\fR).
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateErrorHandler\fR arranges for a particular procedure
+(\fIproc\fR) to be called whenever certain protocol errors occur on a
+particular display (\fIdisplay\fR).  Protocol errors occur when
+the X protocol is used incorrectly, such as attempting to map a window
+that does not exist.  See the Xlib documentation for \fBXSetErrorHandler\fR
+for more information on the kinds of errors that can occur.
+For \fIproc\fR to be invoked
+to handle a particular error, five things must occur:
+.IP [1]
+The error must pertain to \fIdisplay\fR.
+.IP [2]
+Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR
+must have been \-1, or the \fIerror\fR argument must match
+the \fIerror_code\fR field from the error event.
+.IP [3]
+Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR
+must have been \-1, or the \fIrequest\fR argument must match
+the \fIrequest_code\fR field from the error event.
+.IP [4]
+Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR
+must have been \-1, or the \fIminor\fR argument must match
+the \fIminor_code\fR field from the error event.
+.IP [5]
+The protocol request to which the error pertains must have been
+made when the handler was active (see below for more information).
+.PP
+\fIProc\fR should have arguments and result that match the
+following type:
+.CS
+typedef int \fBTk_ErrorProc\fR(
+        ClientData \fIclientData\fR,
+        XErrorEvent *\fIerrEventPtr\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
+argument given to \fBTcl_CreateErrorHandler\fR when the callback
+was created.  Typically, \fIclientData\fR points to a data
+structure containing application-specific information that is
+needed to deal with the error.  \fIErrEventPtr\fR is
+a pointer to the X error event.
+The procedure \fIproc\fR should return an integer value.  If it
+returns 0 it means that \fIproc\fR handled the error completely and there
+is no need to take any other action for the error.  If it returns
+non-zero it means \fIproc\fR was unable to handle the error.
+.PP
+If a value of NULL is specified for \fIproc\fR, all matching errors
+will be ignored:  this will produce the same result as if a procedure
+had been specified that always returns 0.
+.PP
+If more than more than one handler matches a particular error, then
+they are invoked in turn.  The handlers will be invoked in reverse
+order of creation:  most recently declared handler first.
+If any handler returns 0, then subsequent (older) handlers will
+not be invoked.  If no handler returns 0, then Tk invokes X's
+default error handler, which prints an error message and aborts the
+program.  If you wish to have a default handler that deals with errors
+that no other handler can deal with, then declare it first.
+.PP
+The X documentation states that
+.QW "the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events."
+This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR;
+disobey it at your own risk.
+.PP
+\fBTk_DeleteErrorHandler\fR may be called to delete a
+previously-created error handler.  The \fIhandler\fR argument
+identifies the error handler, and should be a value returned by
+a previous call to \fBTk_CreateEventHandler\fR.
+.PP
+A particular error handler applies to errors resulting
+from protocol requests generated between
+the call to \fBTk_CreateErrorHandler\fR and the call to
+\fBTk_DeleteErrorHandler\fR.  However, the actual callback
+to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR
+call, due to buffering in the client and server.
+If an error event pertains to
+a protocol request made just before calling \fBTk_DeleteErrorHandler\fR,
+then the error event may not have been processed
+before the \fBTk_DeleteErrorHandler\fR
+call.  When this situation arises, Tk will save information about
+the handler and
+invoke the handler's \fIproc\fR later when the error event
+finally arrives.
+If an application wishes to delete an error handler and know
+for certain that all relevant errors have been processed,
+it should first call \fBTk_DeleteErrorHandler\fR and then
+call \fBXSync\fR;  this will flush out any buffered requests and errors,
+but will result in a performance penalty because
+it requires communication to and from the X server.  After the
+\fBXSync\fR call Tk is guaranteed not to call any error
+handlers deleted before the \fBXSync\fR call.
+.PP
+For the Tk error handling mechanism to work properly, it is essential
+that application code never calls \fBXSetErrorHandler\fR directly;
+applications should use only \fBTk_CreateErrorHandler\fR.
+.SH KEYWORDS
+callback, error, event, handler

doc/CrtGenHdlr.3

@@ -0,0 +1,81 @@
+'\"
+'\" Copyright (c) 1992-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR)
+.sp
+\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR)
+.SH ARGUMENTS
+.AS "Tk_GenericProc" clientData
+.AP Tk_GenericProc *proc in
+Procedure to invoke whenever any X event occurs on any display.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be
+invoked in the future whenever any X event occurs.  This mechanism is
+\fInot\fR intended for dispatching X events on windows managed by Tk
+(you should use \fBTk_CreateEventHandler\fR for this purpose).
+\fBTk_CreateGenericHandler\fR is intended for other purposes, such
+as tracing X events, monitoring events on windows not owned by Tk,
+accessing X-related libraries that were not originally designed for
+use with Tk, and so on.
+.PP
+The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
+this mechanism only works in programs that dispatch events
+through \fBTk_HandleEvent\fR (or through other Tk procedures that
+call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
+\fBTk_MainLoop\fR).
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTk_GenericProc\fR:
+.CS
+typedef int \fBTk_GenericProc\fR(
+        ClientData \fIclientData\fR,
+        XEvent *\fIeventPtr\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
+argument given to \fBTk_CreateGenericHandler\fR when the callback
+was created.  Typically, \fIclientData\fR points to a data
+structure containing application-specific information about
+how to handle events.
+\fIEventPtr\fR is a pointer to the X event.
+.PP
+Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR
+is called.  The return value from \fIproc\fR is normally 0.
+A non-zero return value indicates that the event is not to be handled
+further; that is, \fIproc\fR has done all processing that is to be
+allowed for the event.
+.PP
+If there are multiple generic event handlers, each one is called
+for each event, in the order in which they were established.
+.PP
+\fBTk_DeleteGenericHandler\fR may be called to delete a
+previously-created generic event handler:  it deletes each handler
+it finds that matches the \fIproc\fR and \fIclientData\fR arguments.  If
+no such handler exists, then \fBTk_DeleteGenericHandler\fR returns
+without doing anything.  Although Tk supports it, it's probably
+a bad idea to have more than one callback with the same
+\fIproc\fR and \fIclientData\fR arguments.
+.PP
+Establishing a generic event handler does nothing to ensure that the
+process will actually receive the X events that the handler wants to
+process.
+For example, it is the caller's responsibility to invoke
+\fBXSelectInput\fR to select the desired events, if that is necessary.
+.SH KEYWORDS
+bind, callback, event, handler

doc/CrtImgType.3

@@ -0,0 +1,283 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateImageType\fR(\fItypePtr\fR)
+.sp
+ClientData
+\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR)
+.sp
+\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
+.SH ARGUMENTS
+.AS "const Tk_ImageType" *typePtrPtr
+.AP "const Tk_ImageType" *typePtr in
+Structure that defines the new type of image.
+For Tk 8.4 and earlier this must be static: a
+pointer to this structure is retained by the image code.
+In Tk 8.5, this limitation was relaxed.
+.AP Tcl_Interp *interp in
+Interpreter in which image was created.
+.AP "const char" *name in
+Name of existing image.
+.AP Tk_ImageType **typePtrPtr out
+Points to word in which to store a pointer to type information for
+the given image, if it exists.
+.AP int argc in
+Number of arguments
+.AP char ***argvPtr in/out
+Pointer to argument list
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateImageType\fR is invoked to define a new kind of image.
+An image type corresponds to a particular value of the \fItype\fR
+argument for the \fBimage create\fR command.  There may exist
+any number of different image types, and new types may be defined
+dynamically by calling \fBTk_CreateImageType\fR.
+For example, there might be one type for 2-color bitmaps,
+another for multi-color images, another for dithered images,
+another for video, and so on.
+.PP
+The code that implements a new image type is called an
+\fIimage manager\fR.
+It consists of a collection of procedures plus three different
+kinds of data structures.
+The first data structure is a Tk_ImageType structure, which contains
+the name of the image type and pointers to five procedures provided
+by the image manager to deal with images of this type:
+.CS
+typedef struct Tk_ImageType {
+    const char *\fIname\fR;
+    Tk_ImageCreateProc *\fIcreateProc\fR;
+    Tk_ImageGetProc *\fIgetProc\fR;
+    Tk_ImageDisplayProc *\fIdisplayProc\fR;
+    Tk_ImageFreeProc *\fIfreeProc\fR;
+    Tk_ImageDeleteProc *\fIdeleteProc\fR;
+} \fBTk_ImageType\fR;
+.CE
+The fields of this structure will be described in later subsections
+of this entry.
+.PP
+The second major data structure manipulated by an image manager
+is called an \fIimage master\fR;  it contains overall information
+about a particular image, such as the values of the configuration
+options specified in an \fBimage create\fR command.
+There will usually be one of these structures for each
+invocation of the \fBimage create\fR command.
+.PP
+The third data structure related to images is an \fIimage instance\fR.
+There will usually be one of these structures for each usage of an
+image in a particular widget.
+It is possible for a single image to appear simultaneously
+in multiple widgets, or even multiple times in the same widget.
+Furthermore, different instances may be on different screens
+or displays.
+The image instance data structure describes things that may
+vary from instance to instance, such as colors and graphics
+contexts for redisplay.
+There is usually one instance structure for each \fB\-image\fR
+option specified for a widget or canvas item.
+.PP
+The following subsections describe the fields of a Tk_ImageType
+in more detail.
+.SS NAME
+.PP
+\fItypePtr->name\fR provides a name for the image type.
+Once \fBTk_CreateImageType\fR returns, this name may be used
+in \fBimage create\fR commands to create images of the new
+type.
+If there already existed an image type by this name then
+the new image type replaces the old one.
+.SS CREATEPROC
+.PP
+\fItypePtr->createProc\fR provides the address of a procedure for
+Tk to call whenever \fBimage create\fR is invoked to create
+an image of the new type.
+\fItypePtr->createProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageCreateProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        const char *\fIname\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[],
+        const Tk_ImageType *\fItypePtr\fR,
+        Tk_ImageMaster \fImaster\fR,
+        ClientData *\fImasterDataPtr\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
+command was invoked, and \fIname\fR is the name for the new image,
+which was either specified explicitly in the \fBimage\fR command
+or generated automatically by the \fBimage\fR command.
+The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration
+options for the new image (everything after the name argument to
+\fBimage\fR).
+The \fImaster\fR argument is a token that refers to Tk's information
+about this image;  the image manager must return this token to
+Tk when invoking the \fBTk_ImageChanged\fR procedure.
+Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR
+and create an image master data structure for the new image.
+\fIcreateProc\fR may store an arbitrary one-word value at
+*\fImasterDataPtr\fR, which will be passed back to the
+image manager when other callbacks are invoked.
+Typically the value is a pointer to the master data
+structure for the image.
+.PP
+If \fIcreateProc\fR encounters an error, it should leave an error
+message in the interpreter result and return \fBTCL_ERROR\fR;  otherwise
+it should return \fBTCL_OK\fR.
+.PP
+\fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the
+size of the image and request an initial redisplay.
+.SS GETPROC
+.PP
+\fItypePtr->getProc\fR is invoked by Tk whenever a widget
+calls \fBTk_GetImage\fR to use a particular image.
+This procedure must match the following prototype:
+.CS
+typedef ClientData \fBTk_ImageGetProc\fR(
+        Tk_Window \fItkwin\fR,
+        ClientData \fImasterData\fR);
+.CE
+The \fItkwin\fR argument identifies the window in which the
+image will be used and \fImasterData\fR is the value
+returned by \fIcreateProc\fR when the image master was created.
+\fIgetProc\fR will usually create a data structure for the new
+instance, including such things as the resources needed to
+display the image in the given window.
+\fIgetProc\fR returns a one-word token for the instance, which
+is typically the address of the instance data structure.
+Tk will pass this value back to the image manager when invoking
+its \fIdisplayProc\fR and \fIfreeProc\fR procedures.
+.SS DISPLAYPROC
+.PP
+\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs
+to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR).
+\fIdisplayProc\fR must match the following prototype:
+.CS
+typedef void \fBTk_ImageDisplayProc\fR(
+        ClientData \fIinstanceData\fR,
+        Display *\fIdisplay\fR,
+        Drawable \fIdrawable\fR,
+        int \fIimageX\fR,
+        int \fIimageY\fR,
+        int \fIwidth\fR,
+        int \fIheight\fR,
+        int \fIdrawableX\fR,
+        int \fIdrawableY\fR);
+.CE
+The \fIinstanceData\fR will be the same as the value returned by
+\fIgetProc\fR when the instance was created.
+\fIdisplay\fR and \fIdrawable\fR indicate where to display the
+image;  \fIdrawable\fR may be a pixmap rather than
+the window specified to \fIgetProc\fR (this is usually the case,
+since most widgets double-buffer their redisplay to get smoother
+visual effects).
+\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR
+identify the region of the image that must be redisplayed.
+This region will always be within the size of the image
+as specified in the most recent call to \fBTk_ImageChanged\fR.
+\fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR
+the image should be displayed;  \fIdisplayProc\fR should display
+the given region of the image so that point (\fIimageX\fR, \fIimageY\fR)
+in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR.
+.SS FREEPROC
+.PP
+\fItypePtr->freeProc\fR contains the address of a procedure that
+Tk will invoke when an image instance is released (i.e., when
+\fBTk_FreeImage\fR is invoked).
+This can happen, for example, when a widget is deleted or a image item
+in a canvas is deleted, or when the image displayed in a widget or
+canvas item is changed.
+\fIfreeProc\fR must match the following prototype:
+.CS
+typedef void \fBTk_ImageFreeProc\fR(
+        ClientData \fIinstanceData\fR,
+        Display *\fIdisplay\fR);
+.CE
+The \fIinstanceData\fR will be the same as the value returned by
+\fIgetProc\fR when the instance was created, and \fIdisplay\fR
+is the display containing the window for the instance.
+\fIfreeProc\fR should release any resources associated with the
+image instance, since the instance will never be used again.
+.SS DELETEPROC
+.PP
+\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an
+image is being deleted (i.e. when the \fBimage delete\fR command
+is invoked).
+Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for
+each of the image's instances.
+\fIdeleteProc\fR must match the following prototype:
+.CS
+typedef void \fBTk_ImageDeleteProc\fR(
+        ClientData \fImasterData\fR);
+.CE
+The \fImasterData\fR argument will be the same as the value
+stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the
+image was created.
+\fIdeleteProc\fR should release any resources associated with
+the image.
+.SH TK_GETIMAGEMASTERDATA
+.PP
+The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve
+information about an image.  For example, an image manager can use this
+procedure to locate its image master data for an image.
+If there exists an image named \fIname\fR
+in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is
+filled in with type information for the image (the \fItypePtr\fR value
+passed to \fBTk_CreateImageType\fR when the image type was registered)
+and the return value is the ClientData value returned by the
+\fIcreateProc\fR when the image was created (this is typically a
+pointer to the image master data structure).  If no such image exists
+then NULL is returned and NULL is stored at \fI*typePtrPtr\fR.
+.SH "LEGACY INTERFACE SUPPORT"
+.PP
+In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR
+was incompatibly different, with the following prototype:
+.CS
+typedef int \fBTk_ImageCreateProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        char *\fIname\fR,
+        int \fIargc\fR,
+        char **\fIargv\fR,
+        Tk_ImageType *\fItypePtr\fR,
+        Tk_ImageMaster \fImaster\fR,
+        ClientData *\fImasterDataPtr\fR);
+.CE
+Legacy programs and libraries dating from those days may still
+contain code that defines extended Tk image types using the old
+interface.  The Tk header file will still support this legacy
+interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR
+defined.
+.PP
+When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may
+see the routine \fBTk_InitImageArgs\fR in use.  This was a migration
+tool used to create stub-enabled extensions that could be loaded
+into interps containing all versions of Tk 8.1 and later.  Tk 8.5 no longer
+provides this routine, but uses a macro to convert any attempted
+calls of this routine into an empty comment.  Any stub-enabled
+extension providing an extended image type via the legacy interface
+that is compiled against Tk 8.5 headers and linked against the
+Tk 8.5 stub library will produce a file that can be loaded only
+into interps with Tk 8.5 or later; that is, the normal stub-compatibility
+rules.  If a developer needs to generate from such code a file
+that is loadable into interps with Tk 8.4 or earlier, they must
+use Tk 8.4 headers and stub libraries to do so.
+.PP
+Any new code written today should not make use of the legacy
+interfaces.  Expect their support to go away in Tk 9.
+.SH "SEE ALSO"
+Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
+.SH KEYWORDS
+image manager, image type, instance, master

doc/CrtItemType.3

@@ -0,0 +1,695 @@
+'\"
+'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateItemType\fR(\fItypePtr\fR)
+.sp
+Tk_ItemType *
+\fBTk_GetItemTypes\fR()
+.SH ARGUMENTS
+.AS Tk_ItemType *typePtr
+.AP Tk_ItemType *typePtr in
+Structure that defines the new type of canvas item.
+.BE
+.SH INTRODUCTION
+.PP
+\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
+described by the \fItypePtr\fR argument.
+An item type corresponds to a particular value of the \fItype\fR
+argument to the \fBcreate\fR widget command for canvases, and
+the code that implements a canvas item type is called a \fItype manager\fR.
+Tk defines several built-in item types, such as \fBrectangle\fR
+and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
+allows additional item types to be defined.
+Once \fBTk_CreateItemType\fR returns, the new item type may be used
+in new or existing canvas widgets just like the built-in item
+types.
+.PP
+\fBTk_GetItemTypes\fR returns a pointer to the first in the list
+of all item types currently defined for canvases.
+The entries in the list are linked together through their
+\fInextPtr\fR fields, with the end of the list marked by a
+NULL \fInextPtr\fR.
+.PP
+You may find it easier to understand the rest of this manual entry
+by looking at the code for an existing canvas item type such as
+bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c).
+The easiest way to create a new type manager is to copy the code
+for an existing type and modify it for the new type.
+.PP
+Tk provides a number of utility procedures for the use of canvas
+type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
+these are described in separate manual entries.
+.SH "DATA STRUCTURES"
+.PP
+A type manager consists of a collection of procedures that provide a
+standard set of operations on items of that type.
+The type manager deals with three kinds of data
+structures.
+The first data structure is a Tk_ItemType; it contains
+information such as the name of the type and pointers to
+the standard procedures implemented by the type manager:
+.PP
+.CS
+typedef struct Tk_ItemType {
+    const char *\fIname\fR;
+    int \fIitemSize\fR;
+    Tk_ItemCreateProc *\fIcreateProc\fR;
+    const Tk_ConfigSpec *\fIconfigSpecs\fR;
+    Tk_ItemConfigureProc *\fIconfigProc\fR;
+    Tk_ItemCoordProc *\fIcoordProc\fR;
+    Tk_ItemDeleteProc *\fIdeleteProc\fR;
+    Tk_ItemDisplayProc *\fIdisplayProc\fR;
+    int \fIalwaysRedraw\fR;
+    Tk_ItemPointProc *\fIpointProc\fR;
+    Tk_ItemAreaProc *\fIareaProc\fR;
+    Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
+    Tk_ItemScaleProc *\fIscaleProc\fR;
+    Tk_ItemTranslateProc *\fItranslateProc\fR;
+    Tk_ItemIndexProc *\fIindexProc\fR;
+    Tk_ItemCursorProc *\fIicursorProc\fR;
+    Tk_ItemSelectionProc *\fIselectionProc\fR;
+    Tk_ItemInsertProc *\fIinsertProc\fR;
+    Tk_ItemDCharsProc *\fIdCharsProc\fR;
+    Tk_ItemType *\fInextPtr\fR;
+} \fBTk_ItemType\fR;
+.CE
+.PP
+The fields of a Tk_ItemType structure are described in more detail
+later in this manual entry.
+When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
+argument must point to a structure with all of the fields initialized
+except \fInextPtr\fR, which Tk sets to link all the types together
+into a list.
+The structure must be in permanent memory (either statically
+allocated or dynamically allocated but never freed); Tk retains
+a pointer to this structure.
+.PP
+The second data structure manipulated by a type manager is an
+\fIitem record\fR.
+For each item in a canvas there exists one item record.
+All of the items of a given type generally have item records with
+the same structure, but different types usually have different
+formats for their item records.
+The first part of each item record is a header with a standard structure
+defined by Tk via the type Tk_Item; the rest of the item
+record is defined by the type manager.
+A type manager must define its item records with a Tk_Item as
+the first field.
+For example, the item record for bitmap items is defined as follows:
+.PP
+.CS
+typedef struct BitmapItem {
+    Tk_Item \fIheader\fR;
+    double \fIx\fR, \fIy\fR;
+    Tk_Anchor \fIanchor\fR;
+    Pixmap \fIbitmap\fR;
+    XColor *\fIfgColor\fR;
+    XColor *\fIbgColor\fR;
+    GC \fIgc\fR;
+} \fBBitmapItem\fR;
+.CE
+.PP
+The \fIheader\fR substructure contains information used by Tk
+to manage the item, such as its identifier, its tags, its type,
+and its bounding box.
+The fields starting with \fIx\fR belong to the type manager:
+Tk will never read or write them.
+The type manager should not need to read or write any of the
+fields in the header except for four fields
+whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
+These fields give a bounding box for the items using integer
+canvas coordinates: the item should not cover any pixels
+with x-coordinate lower than \fIx1\fR or y-coordinate
+lower than \fIy1\fR, nor should it cover any pixels with
+x-coordinate greater than or equal to \fIx2\fR or y-coordinate
+greater than or equal to \fIy2\fR.
+It is up to the type manager to keep the bounding box up to
+date as the item is moved and reconfigured.
+.PP
+Whenever Tk calls a procedure in a type manager it passes in a pointer
+to an item record.
+The argument is always passed as a pointer to a Tk_Item; the type
+manager will typically cast this into a pointer to its own specific
+type, such as BitmapItem.
+.PP
+The third data structure used by type managers has type
+Tk_Canvas; it serves as an opaque handle for the canvas widget
+as a whole.
+Type managers need not know anything about the contents of this
+structure.
+A Tk_Canvas handle is typically passed in to the
+procedures of a type manager, and the type manager can pass the
+handle back to library procedures such as Tk_CanvasTkwin
+to fetch information about the canvas.
+.SH "TK_ITEMTYPE FIELDS"
+.SS NAME
+.PP
+This section and the ones that follow describe each of the fields
+in a Tk_ItemType structure in detail.
+The \fIname\fR field provides a string name for the item type.
+Once \fBTk_CreateImageType\fR returns, this name may be used
+in \fBcreate\fR widget commands to create items of the new
+type.
+If there already existed an item type by this name then
+the new item type replaces the old one.
+.SS "FLAGS (IN ALWAYSREDRAW)"
+.PP
+The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons)
+contains a collection of flag bits that modify how the canvas core interacts
+with the item. The following bits are defined:
+.TP
+\fB1\fR
+.
+Indicates that the item should always be redrawn when any part of the canvas
+is redrawn, rather than only when the bounding box of the item overlaps the
+area being redrawn. This is used by window items, for example, which need to
+unmap subwindows that are not on the screen.
+.TP
+\fBTK_CONFIG_OBJS\fR
+.
+Indicates that operations which would otherwise take a string (or array of
+strings) actually take a Tcl_Obj reference (or an array of such references).
+The operations to which this applies are the \fIconfigProc\fR, the
+\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the
+\fIinsertProc\fR.
+.TP
+\fBTK_MOVABLE_POINTS\fR
+.VS 8.6
+Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and
+\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon
+types, and that hence individual coordinate points can be moved. Must not be
+set if any of the above methods is NULL.
+.VE 8.6
+.SS ITEMSIZE
+.PP
+\fItypePtr\->itemSize\fR gives the size in bytes of item records
+of this type, including the Tk_Item header.
+Tk uses this size to allocate memory space for items of the type.
+All of the item records for a given type must have the same size.
+If variable length fields are needed for an item (such as a list
+of points for a polygon), the type manager can allocate a separate
+object of variable length and keep a pointer to it in the item record.
+.SS CREATEPROC
+.PP
+\fItypePtr\->createProc\fR points to a procedure for
+Tk to call whenever a new item of this type is created.
+\fItypePtr\->createProc\fR must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemCreateProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[]);
+.CE
+.PP
+The \fIinterp\fR argument is the interpreter in which the canvas's
+\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
+handle for the canvas widget.
+\fIitemPtr\fR is a pointer to a newly-allocated item of
+size \fItypePtr\->itemSize\fR.
+Tk has already initialized the item's header (the first
+\fBsizeof(Tk_ItemType)\fR bytes).
+The \fIobjc\fR and \fIobjv\fR arguments describe all of the
+arguments to the \fBcreate\fR command after the \fItype\fR
+argument.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
+For example, in the widget command:
+.PP
+.CS
+\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
+.CE
+.PP
+\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
+integer object \fB10\fR.
+.PP
+\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize
+the type-specific parts of the item record and set an initial value
+for the bounding box in the item's header.
+It should return a standard Tcl completion code and leave an
+error message in the interpreter result if an error occurs.
+If an error occurs Tk will free the item record, so \fIcreateProc\fR
+must be sure to leave the item record in a clean state if it returns an error
+(e.g., it must free any additional memory that it allocated for
+the item).
+.SS CONFIGSPECS
+.PP
+Each type manager must provide a standard table describing its
+configuration options, in a form suitable for use with
+\fBTk_ConfigureWidget\fR.
+This table will normally be used by \fItypePtr\->createProc\fR
+and \fItypePtr\->configProc\fR, but Tk also uses it directly
+to retrieve option information in the \fBitemcget\fR and
+\fBitemconfigure\fR widget commands.
+\fItypePtr\->configSpecs\fR must point to the configuration table
+for this type.
+Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
+for implementing the \fB\-tags\fR option; see an existing type
+manager for an example of how to use it in \fIconfigSpecs\fR.
+.SS CONFIGPROC
+.PP
+\fItypePtr\->configProc\fR is called by Tk whenever the
+\fBitemconfigure\fR widget command is invoked to change the
+configuration options for a canvas item.
+This procedure must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemConfigureProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[],
+        int \fIflags\fR);
+.CE
+.PP
+The \fIinterp\fR argument identifies the interpreter in which the
+widget command was invoked, \fIcanvas\fR is a handle for the canvas
+widget, and \fIitemPtr\fR is a pointer to the item being configured.
+\fIobjc\fR and \fIobjv\fR contain the configuration options.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
+For example, if the following command is invoked:
+.PP
+.CS
+\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
+.CE
+.PP
+\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR
+through \fBblack\fR.
+\fIobjc\fR will always be an even value.
+The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
+currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk
+invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR
+procedure will usually invoke \fIconfigProc\fR with different flag values.
+.PP
+\fItypePtr\->configProc\fR returns a standard Tcl completion code and
+leaves an error message in the interpreter result if an error occurs.
+It must update the item's bounding box to reflect the new configuration
+options.
+.SS COORDPROC
+.PP
+\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
+widget command for an item.
+It must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemCoordProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[]);
+.CE
+.PP
+The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
+all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
+describe the coordinate arguments.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
+For example, if the following widget command is invoked:
+.PP
+.CS
+\fB\&.c coords 2 30 90\fR
+.CE
+.PP
+\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
+\fB30\fR and \fB90\fR.
+.PP
+The \fIcoordProc\fR procedure should process the new coordinates,
+update the item appropriately (e.g., it must reset the bounding
+box in the item's header), and return a standard Tcl completion
+code.
+If an error occurs, \fIcoordProc\fR must leave an error message in
+the interpreter result.
+.SS DELETEPROC
+.PP
+\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item
+and free any resources allocated to it.
+It must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemDeleteProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        Display *\fIdisplay\fR);
+.CE
+.PP
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
+interpretations, and \fIdisplay\fR identifies the X display containing
+the canvas.
+\fIdeleteProc\fR must free up any resources allocated for the item,
+so that Tk can free the item record.
+\fIdeleteProc\fR should not actually free the item record; this will
+be done by Tk when \fIdeleteProc\fR returns.
+.SS "DISPLAYPROC"
+.PP
+\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item
+on the screen.
+It must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemDisplayProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        Display *\fIdisplay\fR,
+        Drawable \fIdst\fR,
+        int \fIx\fR,
+        int \fIy\fR,
+        int \fIwidth\fR,
+        int \fIheight\fR);
+.CE
+.PP
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
+\fIdisplay\fR identifies the display containing the canvas, and
+\fIdst\fR specifies a drawable in which the item should be rendered;
+typically this is an off-screen pixmap, which Tk will copy into
+the canvas's window once all relevant items have been drawn.
+\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular
+region in canvas coordinates, which is the area to be redrawn;
+only information that overlaps this area needs to be redrawn.
+Tk will not call \fIdisplayProc\fR unless the item's bounding box
+overlaps the redraw area, but the type manager may wish to use
+the redraw area to optimize the redisplay of the item.
+.PP
+Because of scrolling and the use of off-screen pixmaps for
+double-buffered redisplay, the item's coordinates in \fIdst\fR
+will not necessarily be the same as those in the canvas.
+\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
+to transform coordinates from those of the canvas to those
+of \fIdst\fR.
+.PP
+Normally an item's \fIdisplayProc\fR is only invoked if the item
+overlaps the area being displayed.
+However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1,
+(i.e.\|
+.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" )
+then \fIdisplayProc\fR is invoked during every redisplay operation,
+even if the item does not overlap the area of redisplay; this is useful for
+cases such as window items, where the subwindow needs to be unmapped when it
+is off the screen.
+.SS POINTPROC
+.PP
+\fItypePtr\->pointProc\fR is invoked by Tk to find out how close
+a given point is to a canvas item.
+Tk uses this procedure for purposes such as locating the item
+under the mouse or finding the closest item to a given point.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef double \fBTk_ItemPointProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        double *\fIpointPtr\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
+\fIpointPtr\fR points to an array of two numbers giving
+the x and y coordinates of a point.
+\fIpointProc\fR must return a real value giving the distance
+from the point to the item, or 0 if the point lies inside
+the item.
+.SS AREAPROC
+.PP
+\fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship
+between an item and a rectangular area.
+It must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemAreaProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        double *\fIrectPtr\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
+\fIrectPtr\fR points to an array of four real numbers;
+the first two give the x and y coordinates of the upper left
+corner of a rectangle, and the second two give the x and y
+coordinates of the lower right corner.
+\fIareaProc\fR must return \-1 if the item lies entirely outside
+the given area, 0 if it lies partially inside and partially
+outside the area, and 1 if it lies entirely inside the area.
+.SS POSTSCRIPTPROC
+.PP
+\fItypePtr\->postscriptProc\fR is invoked by Tk to generate
+Postscript for an item during the \fBpostscript\fR widget command.
+If the type manager is not capable of generating Postscript then
+\fItypePtr\->postscriptProc\fR should be NULL.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemPostscriptProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIprepass\fR);
+.CE
+.PP
+The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
+standard meanings; \fIprepass\fR will be described below.
+If \fIpostscriptProc\fR completes successfully, it should append
+Postscript for the item to the information in the interpreter result
+(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
+and return \fBTCL_OK\fR.
+If an error occurs, \fIpostscriptProc\fR should clear the result
+and replace its contents with an error message; then it should
+return \fBTCL_ERROR\fR.
+.PP
+Tk provides a collection of utility procedures to simplify
+\fIpostscriptProc\fR.
+For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
+the current color to a given Tk color and \fBTk_CanvasPsFont\fR will
+set up font information.
+When generating Postscript, the type manager is free to change the
+graphics state of the Postscript interpreter, since Tk places
+\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
+the item.
+The type manager can use canvas x coordinates directly in its Postscript,
+but it must call \fBTk_CanvasPsY\fR to convert y coordinates from
+the space of the canvas (where the origin is at the
+upper left) to the space of Postscript (where the origin is at the
+lower left).
+.PP
+In order to generate Postscript that complies with the Adobe Document
+Structuring Conventions, Tk actually generates Postscript in two passes.
+It calls each item's \fIpostscriptProc\fR in each pass.
+The only purpose of the first pass is to collect font information
+(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is
+discarded.
+Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
+during the first pass; the type manager can use \fIprepass\fR to skip
+all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
+During the second pass \fIprepass\fR will be 0, so the type manager
+must generate complete Postscript.
+.SS SCALEPROC
+.PP
+\fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item
+during the \fBscale\fR widget command.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemScaleProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        double \fIoriginX\fR,
+        double \fIoriginY\fR,
+        double \fIscaleX\fR,
+        double \fIscaleY\fR);
+.CE
+.PP
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
+\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
+the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the
+x and y scale factors.
+The item should adjust its coordinates so that a point in the item
+that used to have coordinates \fIx\fR and \fIy\fR will have new
+coordinates \fIx\(fm\fR and \fIy\(fm\fR, where
+.PP
+.CS
+\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR)
+\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR)
+.CE
+.PP
+\fIscaleProc\fR must also update the bounding box in the item's
+header.
+.SS TRANSLATEPROC
+.PP
+\fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item
+during the \fBmove\fR widget command.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemTranslateProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        double \fIdeltaX\fR,
+        double \fIdeltaY\fR);
+.CE
+.PP
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
+and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be
+added to each x and y coordinate within the item.
+The type manager should adjust the item's coordinates and
+update the bounding box in the item's header.
+.SS INDEXPROC
+.PP
+\fItypePtr\->indexProc\fR is invoked by Tk to translate a string
+index specification into a numerical index, for example during the
+\fBindex\fR widget command.
+It is only relevant for item types that support indexable text or coordinates;
+\fItypePtr\->indexProc\fR may be specified as NULL for non-textual
+item types if they do not support detailed coordinate addressing.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemIndexProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        Tcl_Obj *\fIindexObj\fR,
+        int *\fIindexPtr\fR);
+.CE
+.PP
+The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
+have the usual meaning.
+\fIindexObj\fR contains a textual description of an index,
+and \fIindexPtr\fR points to an integer value that should be
+filled in with a numerical index.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will
+actually contain a pointer to a constant string.
+It is up to the type manager to decide what forms of index
+are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR,
+\fBend\fR, etc.).
+\fIindexProc\fR should return a Tcl completion code and set
+the interpreter result in the event of an error.
+.SS ICURSORPROC
+.PP
+\fItypePtr\->icursorProc\fR is invoked by Tk during
+the \fBicursor\fR widget command to set the position of the
+insertion cursor in a textual item.
+It is only relevant for item types that support an insertion cursor;
+\fItypePtr\->icursorProc\fR may be specified as NULL for item types
+that do not support an insertion cursor.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemCursorProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIindex\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
+\fIindex\fR is an index into the item's text, as returned by a
+previous call to \fItypePtr\->insertProc\fR.
+The type manager should position the insertion cursor in the
+item just before the character given by \fIindex\fR.
+Whether or not to actually display the insertion cursor is
+determined by other information provided by \fBTk_CanvasGetTextInfo\fR.
+.SS SELECTIONPROC
+.PP
+\fItypePtr\->selectionProc\fR is invoked by Tk during selection
+retrievals; it must return part or all of the selected text in
+the item (if any).
+It is only relevant for item types that support text;
+\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual
+item types.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef int \fBTk_ItemSelectionProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIoffset\fR,
+        char *\fIbuffer\fR,
+        int \fImaxBytes\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIoffset\fR is an offset in bytes into the selection where 0 refers
+to the first byte of the selection; it identifies
+the first character that is to be returned in this call.
+\fIbuffer\fR points to an area of memory in which to store the
+requested bytes, and \fImaxBytes\fR specifies the maximum number
+of bytes to return.
+\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
+from the selection and copy them to \fImaxBytes\fR; it should
+return a count of the number of bytes actually copied, which may
+be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes
+in the selection.
+.SS INSERTPROC
+.PP
+\fItypePtr\->insertProc\fR is invoked by Tk during
+the \fBinsert\fR widget command to insert new text or coordinates into a
+canvas item.
+It is only relevant for item types that support the \fBinsert\fR method;
+\fItypePtr\->insertProc\fR may be specified as NULL for other
+item types.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemInsertProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIindex\fR,
+        Tcl_Obj *\fIobj\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIindex\fR is an index into the item's text, as returned by a
+previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR
+contains new text to insert just before the character given
+by \fIindex\fR.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will
+actually contain a pointer to a constant string to be inserted.
+If the item supports modification of the coordinates list by this
+.PP
+The type manager should insert the text and recompute the bounding
+box in the item's header.
+.SS DCHARSPROC
+.PP
+\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
+widget command to delete a range of text from a canvas item or a range of
+coordinates from a pathed item.
+It is only relevant for item types that support text;
+\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual
+item types that do not want to support coordinate deletion.
+The procedure must match the following prototype:
+.PP
+.CS
+typedef void \fBTk_ItemDCharsProc\fR(
+        Tk_Canvas \fIcanvas\fR,
+        Tk_Item *\fIitemPtr\fR,
+        int \fIfirst\fR,
+        int \fIlast\fR);
+.CE
+.PP
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
+to be deleted, as returned by previous calls to \fItypePtr\->indexProc\fR.
+The type manager should delete the specified characters and update
+the bounding box in the item's header.
+.SH "SEE ALSO"
+Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
+.SH KEYWORDS
+canvas, focus, item type, selection, type manager

doc/CrtPhImgFmt.3

@@ -0,0 +1,270 @@
+'\"
+'\" Copyright (c) 1994 The Australian National University
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
+'\"	    Department of Computer Science,
+'\"	    Australian National University.
+'\"
+.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreatePhotoImageFormat \- define new file format for photo images
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR)
+.SH ARGUMENTS
+.AS "const Tk_PhotoImageFormat" *formatPtr
+.AP "const Tk_PhotoImageFormat" *formatPtr in
+Structure that defines the new file format.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format
+for image data for use with photo images.  The code that implements an
+image file format is called an image file format handler, or
+handler for short.  The photo image code
+maintains a list of handlers that can be used to read and
+write data to or from a file.  Some handlers may also
+support reading image data from a string or converting image data to a
+string format.
+The user can specify which handler to use with the \fB\-format\fR
+image configuration option or the \fB\-format\fR option to the
+\fBread\fR and \fBwrite\fR photo image subcommands.
+.PP
+An image file format handler consists of a collection of procedures
+plus a Tk_PhotoImageFormat structure, which contains the name of the
+image file format and pointers to six procedures provided by the
+handler to deal with files and strings in this format.  The
+Tk_PhotoImageFormat structure contains the following fields:
+.CS
+typedef struct Tk_PhotoImageFormat {
+    const char *\fIname\fR;
+    Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
+    Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
+    Tk_ImageFileReadProc *\fIfileReadProc\fR;
+    Tk_ImageStringReadProc *\fIstringReadProc\fR;
+    Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
+    Tk_ImageStringWriteProc *\fIstringWriteProc\fR;
+} \fBTk_PhotoImageFormat\fR;
+.CE
+.PP
+The handler need not provide implementations of all six procedures.
+For example, the procedures that handle string data would not be
+provided for a format in which the image data are stored in binary,
+and could therefore contain null characters.  If any procedure is not
+implemented, the corresponding pointer in the Tk_PhotoImageFormat
+structure should be set to NULL.  The handler must provide the
+\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR
+procedure, and the \fIstringMatchProc\fR procedure if it provides the
+\fIstringReadProc\fR procedure.
+.SS NAME
+.PP
+\fIformatPtr->name\fR provides a name for the image type.
+Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used
+in the \fB\-format\fR photo image configuration and subcommand option.
+The manual page for the photo image (photo(n)) describes how image
+file formats are chosen based on their names and the value given to
+the \fB\-format\fR option. The first character of \fIformatPtr->name\fR
+must not be an uppercase character from the ASCII character set
+(that is, one of the characters \fBA\fR-\fBZ\fR).  Such names are used
+only for legacy interface support (see below).
+.SS FILEMATCHPROC
+.PP
+\fIformatPtr->fileMatchProc\fR provides the address of a procedure for
+Tk to call when it is searching for an image file format handler
+suitable for reading data in a given file.
+\fIformatPtr->fileMatchProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageFileMatchProc\fR(
+        Tcl_Channel \fIchan\fR,
+        const char *\fIfileName\fR,
+        Tcl_Obj *\fIformat\fR,
+        int *\fIwidthPtr\fR,
+        int *\fIheightPtr\fR,
+        Tcl_Interp *\fIinterp\fR);
+.CE
+The \fIfileName\fR argument is the name of the file containing the
+image data, which is open for reading as \fIchan\fR.  The
+\fIformat\fR argument contains the value given for the
+\fB\-format\fR option, or NULL if the option was not specified.
+If the data in the file appears to be in the format supported by this
+handler, the \fIformatPtr->fileMatchProc\fR procedure should store the
+width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR
+respectively, and return 1.  Otherwise it should return 0.
+.SS STRINGMATCHPROC
+.PP
+\fIformatPtr->stringMatchProc\fR provides the address of a procedure for
+Tk to call when it is searching for an image file format handler for
+suitable for reading data from a given string.
+\fIformatPtr->stringMatchProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageStringMatchProc\fR(
+        Tcl_Obj *\fIdata\fR,
+        Tcl_Obj *\fIformat\fR,
+        int *\fIwidthPtr\fR,
+        int *\fIheightPtr\fR,
+        Tcl_Interp *\fIinterp\fR);
+.CE
+The \fIdata\fR argument points to the object containing the image
+data.  The \fIformat\fR argument contains the value given for
+the \fB\-format\fR option, or NULL if the option was not specified.
+If the data in the string appears to be in the format supported by
+this handler, the \fIformatPtr->stringMatchProc\fR procedure should
+store the width and height of the image in *\fIwidthPtr\fR and
+*\fIheightPtr\fR respectively, and return 1.  Otherwise it should
+return 0.
+.SS FILEREADPROC
+.PP
+\fIformatPtr->fileReadProc\fR provides the address of a procedure for
+Tk to call to read data from an image file into a photo image.
+\fIformatPtr->fileReadProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageFileReadProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Channel \fIchan\fR,
+        const char *\fIfileName\fR,
+        Tcl_Obj *\fIformat\fR,
+        PhotoHandle \fIimageHandle\fR,
+        int \fIdestX\fR, int \fIdestY\fR,
+        int \fIwidth\fR, int \fIheight\fR,
+        int \fIsrcX\fR, int \fIsrcY\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the command was
+invoked to read the image; it should be used for reporting errors.
+The image data is in the file named \fIfileName\fR, which is open for
+reading as \fIchan\fR.  The \fIformat\fR argument contains the
+value given for the \fB\-format\fR option, or NULL if the option was
+not specified.  The image data in the file, or a subimage of it, is to
+be read into the photo image identified by the handle
+\fIimageHandle\fR.  The subimage of the data in the file is of
+dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
+coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
+image with its top-left corner at coordinates
+(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
+The return value is a standard Tcl return value.
+.SS STRINGREADPROC
+.PP
+\fIformatPtr->stringReadProc\fR provides the address of a procedure for
+Tk to call to read data from a string into a photo image.
+\fIformatPtr->stringReadProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageStringReadProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIdata\fR,
+        Tcl_Obj *\fIformat\fR,
+        PhotoHandle \fIimageHandle\fR,
+        int \fIdestX\fR, int \fIdestY\fR,
+        int \fIwidth\fR, int \fIheight\fR,
+        int \fIsrcX\fR, int \fIsrcY\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the command was
+invoked to read the image; it should be used for reporting errors.
+The \fIdata\fR argument points to the image data in object form.
+The \fIformat\fR argument contains the
+value given for the \fB\-format\fR option, or NULL if the option was
+not specified.  The image data in the string, or a subimage of it, is to
+be read into the photo image identified by the handle
+\fIimageHandle\fR.  The subimage of the data in the string is of
+dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
+coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
+image with its top-left corner at coordinates
+(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
+The return value is a standard Tcl return value.
+.SS FILEWRITEPROC
+.PP
+\fIformatPtr->fileWriteProc\fR provides the address of a procedure for
+Tk to call to write data from a photo image to a file.
+\fIformatPtr->fileWriteProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageFileWriteProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        const char *\fIfileName\fR,
+        Tcl_Obj *\fIformat\fR,
+        Tk_PhotoImageBlock *\fIblockPtr\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the command was
+invoked to write the image; it should be used for reporting errors.
+The image data to be written are in memory and are described by the
+Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
+manual page FindPhoto(3) for details.  The \fIfileName\fR argument
+points to the string giving the name of the file in which to write the
+image data.  The \fIformat\fR argument contains the
+value given for the \fB\-format\fR option, or NULL if the option was
+not specified.  The format string can contain extra characters
+after the name of the format.  If appropriate, the
+\fIformatPtr->fileWriteProc\fR procedure may interpret these
+characters to specify further details about the image file.
+The return value is a standard Tcl return value.
+.SS STRINGWRITEPROC
+.PP
+\fIformatPtr->stringWriteProc\fR provides the address of a procedure for
+Tk to call to translate image data from a photo image into a string.
+\fIformatPtr->stringWriteProc\fR must match the following prototype:
+.CS
+typedef int \fBTk_ImageStringWriteProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIformat\fR,
+        Tk_PhotoImageBlock *\fIblockPtr\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the command was
+invoked to convert the image; it should be used for reporting errors.
+The image data to be converted are in memory and are described by the
+Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
+manual page FindPhoto(3) for details.  The data for the string
+should be put in the interpreter \fIinterp\fR result.
+The \fIformat\fR argument contains the
+value given for the \fB\-format\fR option, or NULL if the option was
+not specified.  The format string can contain extra characters
+after the name of the format.  If appropriate, the
+\fIformatPtr->stringWriteProc\fR procedure may interpret these
+characters to specify further details about the image file.
+The return value is a standard Tcl return value.
+.SH "LEGACY INTERFACE SUPPORT"
+.PP
+In Tk 8.2 and earlier, the definition of all the function pointer
+types stored in fields of a \fBTk_PhotoImageFormat\fR struct were
+incompatibly different.  Legacy programs and libraries dating from
+those days may still contain code that defines extended Tk photo image
+formats using the old interface.  The Tk header file will still support
+this legacy interface if the code is compiled with the
+macro \fBUSE_OLD_IMAGE\fR defined.  Alternatively, the legacy interfaces
+are used if the first character of \fIformatPtr->name\fR is an
+uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts
+are used to forgive the type mismatch.  For example,
+.CS
+static Tk_PhotoImageFormat myFormat = {
+    "MyFormat",
+    (Tk_ImageFileMatchProc *) FileMatch,
+    NULL,
+    (Tk_ImageFileReadProc *) FileRead,
+    NULL,
+    NULL,
+    NULL
+};
+.CE
+would define a minimal \fBTk_PhotoImageFormat\fR that operates provide
+only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR
+are written according to the legacy interfaces of Tk 8.2 or earlier.
+.PP
+Any stub-enabled extension providing an extended photo image format
+via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro
+that is compiled against Tk 8.5 headers and linked against the
+Tk 8.5 stub library will produce a file that can be loaded only
+into interps with Tk 8.5 or later; that is, the normal stub-compatibility
+rules.  If a developer needs to generate from such code a file
+that is loadable into interps with Tk 8.4 or earlier, they must
+use Tk 8.4 headers and stub libraries to do so.
+.PP
+Any new code written today should not make use of the legacy
+interfaces.  Expect their support to go away in Tk 9.
+.SH "SEE ALSO"
+Tk_FindPhoto, Tk_PhotoPutBlock
+.SH KEYWORDS
+photo image, image file

doc/CrtSelHdlr.3

@@ -0,0 +1,116 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR)
+.sp
+\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR)
+.SH ARGUMENTS
+.AS Tk_SelectionProc clientData
+.AP Tk_Window tkwin in
+Window for which \fIproc\fR will provide selection information.
+.AP Atom selection in
+The name of the selection for which \fIproc\fR will provide
+selection information.
+.AP Atom target in
+Form in which \fIproc\fR can provide the selection (e.g. STRING
+or FILE_NAME).  Corresponds to \fItype\fR arguments in \fBselection\fR
+commands.
+.AP Tk_SelectionProc *proc in
+Procedure to invoke whenever the selection is owned by \fItkwin\fR
+and the selection contents are requested in the format given by
+\fItarget\fR.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.AP Atom format in
+If the selection requestor is not in this process, \fIformat\fR determines
+the representation used to transmit the selection to its
+requestor.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateSelHandler\fR arranges for a particular procedure
+(\fIproc\fR) to be called whenever \fIselection\fR is owned by
+\fItkwin\fR and the selection contents are requested in the
+form given by \fItarget\fR.
+\fITarget\fR should be one of
+the entries defined in the left column of Table 2 of the
+X Inter-Client Communication Conventions Manual (ICCCM) or
+any other form in which an application is willing to present
+the selection.  The most common form is STRING.
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTk_SelectionProc\fR:
+.CS
+typedef int \fBTk_SelectionProc\fR(
+        ClientData \fIclientData\fR,
+        int \fIoffset\fR,
+        char *\fIbuffer\fR,
+        int \fImaxBytes\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the
+\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR.
+Typically, \fIclientData\fR points to a data
+structure containing application-specific information that is
+needed to retrieve the selection.  \fIOffset\fR specifies an
+offset position into the selection, \fIbuffer\fR specifies a
+location at which to copy information about the selection, and
+\fImaxBytes\fR specifies the amount of space available at
+\fIbuffer\fR.  \fIProc\fR should place a NULL-terminated string
+at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters
+(not including the terminating NULL), and it should return a
+count of the number of non-NULL characters stored at
+\fIbuffer\fR.  If the selection no longer exists (e.g. it once
+existed but the user deleted the range of characters containing
+it), then \fIproc\fR should return \-1.
+.PP
+When transferring large selections, Tk will break them up into
+smaller pieces (typically a few thousand bytes each) for more
+efficient transmission.  It will do this by calling \fIproc\fR
+one or more times, using successively higher values of \fIoffset\fR
+to retrieve successive portions of the selection.  If \fIproc\fR
+returns a count less than \fImaxBytes\fR it means that the entire
+remainder of the selection has been returned.  If \fIproc\fR's return
+value is \fImaxBytes\fR it means there may be additional information
+in the selection, so Tk must make another call to \fIproc\fR to
+retrieve the next portion.
+.PP
+\fIProc\fR always returns selection information in the form of a
+character string.  However, the ICCCM allows for information to
+be transmitted from the selection owner to the selection requestor
+in any of several formats, such as a string, an array of atoms, an
+array of integers, etc.  The \fIformat\fR argument to
+\fBTk_CreateSelHandler\fR indicates what format should be used to
+transmit the selection to its requestor (see the middle column of
+Table 2 of the ICCCM for examples).  If \fIformat\fR is not
+STRING, then Tk will take the value returned by \fIproc\fR and divided
+it into fields separated by white space.  If \fIformat\fR is ATOM,
+then Tk will return the selection as an array of atoms, with each
+field in \fIproc\fR's result treated as the name of one atom.  For
+any other value of \fIformat\fR, Tk will return the selection as an
+array of 32-bit values where each field of \fIproc\fR's result is
+treated as a number and translated to a 32-bit value.  In any event,
+the \fIformat\fR atom is returned to the selection requestor along
+with the contents of the selection.
+.PP
+If \fBTk_CreateSelHandler\fR is called when there already exists a
+handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the
+existing handler is replaced with a new one.
+.PP
+\fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR,
+\fIselection\fR, and \fItarget\fR, if such a handler exists.
+If there is no such handler then it has no effect.
+.SH KEYWORDS
+format, handler, selection, target

doc/CrtWindow.3

@@ -0,0 +1,146 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR)
+.sp
+Tk_Window
+\fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR)
+.sp
+Tk_Window
+\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
+.sp
+\fBTk_DestroyWindow\fR(\fItkwin\fR)
+.sp
+\fBTk_MakeWindowExist\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *topLevScreen
+.AP Tcl_Interp *interp out
+Tcl interpreter to use for error reporting.  If no error occurs,
+then \fI*interp\fR is not modified.
+.AP Tk_Window parent in
+Token for the window that is to serve as the logical parent of
+the new window.
+.AP "const char" *name in
+Name to use for this window.  Must be unique among all children of
+the same \fIparent\fR.
+.AP "const char" *topLevScreen in
+Has same format as \fIscreenName\fR.  If NULL, then new window is
+created as an internal window.  If non-NULL, new window is created as
+a top-level window on screen \fItopLevScreen\fR.  If \fItopLevScreen\fR
+is an empty string
+.PQ ""
+then new window is created as top-level window of \fIparent\fR's screen.
+.AP Tk_Window tkwin in
+Token for window.
+.AP "const char" *pathName in
+Name of new window, specified as path name within application
+(e.g. \fB.a.b.c\fR).
+.BE
+.SH DESCRIPTION
+.PP
+The procedures \fBTk_CreateWindow\fR,
+\fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR
+are used to create new windows for
+use in Tk-based applications.  Each of the procedures returns a token
+that can be used to manipulate the window in other calls to the Tk
+library.  If the window could not be created successfully, then NULL
+is returned and the result of interpreter \fIinterp\fR is modified to
+hold an error message.
+.PP
+Tk supports two different kinds of windows:  internal
+windows and top-level windows.
+An internal window is an interior window of a Tk application, such as a
+scrollbar or menu bar or button.  A top-level window is one that is
+created as a child of a screen's root window, rather than as an
+interior window, but which is logically part of some existing main
+window.  Examples of top-level windows are pop-up menus and dialog boxes.
+.PP
+New windows may be created by calling
+\fBTk_CreateWindow\fR.  If the \fItopLevScreen\fR argument is
+NULL, then the new window will be an internal window.  If
+\fItopLevScreen\fR is non-NULL, then the new window will be a
+top-level window: \fItopLevScreen\fR indicates the name of
+a screen and the new window will be created as a child of the
+root window of \fItopLevScreen\fR.  In either case Tk will
+consider the new window to be the logical child of \fIparent\fR:
+the new window's path name will reflect this fact, options may
+be specified for the new window under this assumption, and so on.
+The only difference is that new X window for a top-level window
+will not be a child of \fIparent\fR's X window.  For example, a pull-down
+menu's \fIparent\fR would be the button-like window used to invoke it,
+which would in turn be a child of the menu bar window.  A dialog box might
+have the application's main window as its parent.
+.PP
+\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in
+that it creates an unnamed window.  This window will be manipulatable
+only using C interfaces, and will not be visible to Tcl scripts.  Both
+interior windows and top-level windows may be created with
+\fBTk_CreateAnonymousWindow\fR.
+.PP
+\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying
+new windows.  In \fBTk_CreateWindowFromPath\fR the new
+window is specified with a token for any window in the target
+application (\fItkwin\fR), plus a path name for the new window.
+It produces the same effect as \fBTk_CreateWindow\fR and allows
+both top-level and internal windows to be created, depending on
+the value of \fItopLevScreen\fR.  In calls to \fBTk_CreateWindowFromPath\fR,
+as in calls to \fBTk_CreateWindow\fR, the parent of the new window
+must exist at the time of the call, but the new window must not
+already exist.
+.PP
+The window creation procedures do not
+actually issue the command to X to create a window.
+Instead, they create a local data structure associated with
+the window and defer the creation of the X window.
+The window will actually be created by the first call to
+\fBTk_MapWindow\fR.  Deferred window creation allows various
+aspects of the window (such as its size, background color,
+etc.) to be modified after its creation without incurring
+any overhead in the X server.  When the window is finally
+mapped all of the window attributes can be set while creating
+the window.
+.PP
+The value returned by a window-creation procedure is not the
+X token for the window (it cannot be, since X has not been
+asked to create the window yet).  Instead, it is a token
+for Tk's local data structure for the window.  Most
+of the Tk library procedures take Tk_Window tokens, rather
+than X identifiers.  The actual
+X window identifier can be retrieved from the local
+data structure using the \fBTk_WindowId\fR macro;  see
+the manual entry for \fBTk_WindowId\fR for details.
+.PP
+\fBTk_DestroyWindow\fR deletes a window and all the data
+structures associated with it, including any event handlers
+created with \fBTk_CreateEventHandler\fR.  In addition,
+\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR
+recursively (where children are defined in the Tk sense, consisting
+of all windows that were created with the given window as \fIparent\fR).
+If \fItkwin\fR is an internal window, then event
+handlers interested in destroy events
+are invoked immediately.  If \fItkwin\fR is a top-level or main window,
+then the event handlers will be invoked later, after X has seen
+the request and returned an event for it.
+.PP
+If a window has been created
+but has not been mapped, so no X window exists, it is
+possible to force the creation of the X window by
+calling \fBTk_MakeWindowExist\fR.  This procedure issues
+the X commands to instantiate the window given by \fItkwin\fR.
+.SH KEYWORDS
+create, deferred creation, destroy, display, internal window,
+screen, top-level window, window

doc/DeleteImg.3

@@ -0,0 +1,31 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_DeleteImage \- Destroy an image.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_DeleteImage\fR(\fIinterp, name\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter for which the image was created.
+.AP "const char" *name in
+Name of the image.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR
+and \fIname\fR, if there is one.  All instances of that image
+will redisplay as empty regions.  If the given image does not
+exist then the procedure has no effect.
+.SH KEYWORDS
+delete image, image manager

doc/DrawFocHlt.3

@@ -0,0 +1,36 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *joinPtr
+.AP Tk_Window tkwin in
+Window for which the highlight is being drawn.  Used to retrieve
+the window's dimensions, among other things.
+.AP GC gc in
+Graphics context to use for drawing the highlight.
+.AP int width in
+Width of the highlight ring, in pixels.
+.AP Drawable drawable in
+Drawable in which to draw the highlight;  usually an offscreen
+pixmap for double buffering.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the
+traversal highlight ring for a widget.
+It is typically invoked by widgets during redisplay.
+.SH KEYWORDS
+focus, traversal highlight

doc/EventHndlr.3

@@ -0,0 +1,75 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
+.sp
+\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
+.SH ARGUMENTS
+.AS "unsigned long" clientData
+.AP Tk_Window tkwin in
+Token for window in which events may occur.
+.AP "unsigned long" mask in
+Bit-mask of events (such as \fBButtonPressMask\fR)
+for which \fIproc\fR should be called.
+.AP Tk_EventProc *proc in
+Procedure to invoke whenever an event in \fImask\fR occurs
+in the window given by \fItkwin\fR.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be
+invoked in the future whenever one of the event types specified
+by \fImask\fR occurs in the window specified by \fItkwin\fR.
+The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
+this mechanism only works in programs that dispatch events
+through \fBTk_HandleEvent\fR (or through other Tk procedures that
+call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
+\fBTk_MainLoop\fR).
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTk_EventProc\fR:
+.CS
+typedef void \fBTk_EventProc\fR(
+        ClientData \fIclientData\fR,
+        XEvent *\fIeventPtr\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
+argument given to \fBTk_CreateEventHandler\fR when the callback
+was created.  Typically, \fIclientData\fR points to a data
+structure containing application-specific information about
+the window in which the event occurred.  \fIEventPtr\fR is
+a pointer to the X event, which will be one of the ones
+specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR.
+.PP
+\fBTk_DeleteEventHandler\fR may be called to delete a
+previously-created event handler:  it deletes the first handler
+it finds that is associated with \fItkwin\fR and matches the
+\fImask\fR, \fIproc\fR, and \fIclientData\fR arguments.  If
+no such handler exists, then \fBTk_HandleEvent\fR returns
+without doing anything.  Although Tk supports it, it's probably
+a bad idea to have more than one callback with the same \fImask\fR,
+\fIproc\fR, and \fIclientData\fR arguments.
+When a window is deleted all of its handlers will be deleted
+automatically;  in this case there is no need to call
+\fBTk_DeleteEventHandler\fR.
+.PP
+If multiple handlers are declared for the same type of X event
+on the same window, then the handlers will be invoked in the
+order they were created.
+.SH KEYWORDS
+bind, callback, event, handler

doc/FindPhoto.3

@@ -0,0 +1,283 @@
+'\"
+'\" Copyright (c) 1994 The Australian National University
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
+'\"	    Department of Computer Science,
+'\"	    Australian National University.
+'\"
+.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_PhotoHandle
+\fBTk_FindPhoto\fR(\fIinterp, imageName\fR)
+.sp
+int
+\fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\
+compRule\fR)
+.sp
+int
+\fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\
+zoomX, zoomY, subsampleX, subsampleY, compRule\fR)
+.sp
+int
+\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
+.sp
+void
+\fBTk_PhotoBlank\fR(\fIhandle\fR)
+.sp
+int
+\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR)
+.sp
+void
+\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
+.sp
+int
+\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR)
+.SH ARGUMENTS
+.AS Tk_PhotoImageBlock window_path
+.AP Tcl_Interp *interp in
+Interpreter in which image was created and in which error reporting is
+to be done.
+.AP "const char" *imageName in
+Name of the photo image.
+.AP Tk_PhotoHandle handle in
+Opaque handle identifying the photo image to be affected.
+.AP Tk_PhotoImageBlock *blockPtr in
+Specifies the address and storage layout of image data.
+.AP int x in
+Specifies the X coordinate where the top-left corner of the block is
+to be placed within the image.
+.AP int y in
+Specifies the Y coordinate where the top-left corner of the block is
+to be placed within the image.
+.AP int width in
+Specifies the width of the image area to be affected (for
+\fBTk_PhotoPutBlock\fR) or the desired image width (for
+\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
+.AP int compRule in
+Specifies the compositing rule used when combining transparent pixels
+in a block of data with a photo image.  Must be one of
+\fBTK_PHOTO_COMPOSITE_OVERLAY\fR (which puts the block of data over the top
+of the existing photo image, with the previous contents showing
+through in the transparent bits) or \fBTK_PHOTO_COMPOSITE_SET\fR (which
+discards the existing photo image contents in the rectangle covered by
+the data block.)
+.AP int height in
+Specifies the height of the image area to be affected (for
+\fBTk_PhotoPutBlock\fR) or the desired image height (for
+\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
+.AP int *widthPtr out
+Pointer to location in which to store the image width.
+.AP int *heightPtr out
+Pointer to location in which to store the image height.
+.AP int subsampleX in
+Specifies the subsampling factor in the X direction for input
+image data.
+.AP int subsampleY in
+Specifies the subsampling factor in the Y direction for input
+image data.
+.AP int zoomX in
+Specifies the zoom factor to be applied in the X direction to pixels
+being written to the photo image.
+.AP int zoomY in
+Specifies the zoom factor to be applied in the Y direction to pixels
+being written to the photo image.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a
+particular photo image to the other procedures.  The parameter is the
+name of the image, that is, the name specified to the \fBimage create
+photo\fR command, or assigned by that command if no name was specified.
+If \fIimageName\fR does not exist or is not a photo image,
+\fBTk_FindPhoto\fR returns NULL.
+.PP
+\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be
+displayed.  The call affects an area of the image of size
+\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at
+coordinates (\fIx\fR,\fIy\fR).  All of \fIwidth\fR, \fIheight\fR,
+\fIx\fR, and \fIy\fR must be non-negative.
+If part of this area lies outside the
+current bounds of the image, the image will be expanded to include the
+area, unless the user has specified an explicit image size with the
+\fB\-width\fR and/or \fB\-height\fR widget configuration options
+(see photo(n)); in that
+case the area is silently clipped to the image boundaries.
+.PP
+The \fIblock\fR parameter is a pointer to a
+\fBTk_PhotoImageBlock\fR structure, defined as follows:
+.CS
+typedef struct {
+    unsigned char *\fIpixelPtr\fR;
+    int \fIwidth\fR;
+    int \fIheight\fR;
+    int \fIpitch\fR;
+    int \fIpixelSize\fR;
+    int \fIoffset\fR[4];
+} \fBTk_PhotoImageBlock\fR;
+.CE
+The \fIpixelPtr\fR field points to the first pixel, that is, the
+top-left pixel in the block.
+The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the
+block of pixels.  The \fIpixelSize\fR field specifies the address
+difference between two horizontally adjacent pixels.  It should be 4 for
+RGB and 2 for grayscale image data.  Other values are possible, if the
+offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for
+red, green and blue data stored in different planes).  Using such a
+layout is strongly discouraged, though. Due to a bug, it might not work
+correctly if an alpha channel is provided. (see the \fBBUGS\fR section
+below). The \fIpitch\fR field specifies the
+address difference between two vertically adjacent pixels.  The
+\fIoffset\fR array contains the offsets from the address of a pixel
+to the addresses of the bytes containing the red, green, blue and alpha
+(transparency) components.  If the offsets for red, green and blue are
+equal, the image is interpreted as grayscale. If they differ, RGB data
+is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data
+and 0, 0, 0, 1 for grayscale.  It is possible to provide image data
+without an alpha channel by setting the offset for alpha to a negative
+value and adjusting the \fIpixelSize\fR field accordingly. This use is
+discouraged, though (see the \fBBUGS\fR section below).
+.PP
+The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a
+compositing rule that says what to do with transparent pixels.  The
+value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of
+the photo image should show through, and the value
+\fBTK_PHOTO_COMPOSITE_SET\fR says that the previous contents of the photo
+image should be completely ignored, and the values from the block be
+copied directly across.  The behavior in Tk8.3 and earlier was
+equivalent to having \fBTK_PHOTO_COMPOSITE_OVERLAY\fR as a compositing rule.
+.PP
+The value given for the \fIwidth\fR and \fIheight\fR parameters to
+\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified
+in \fIblock\fR.  If they are smaller, \fBTk_PhotoPutBlock\fR extracts a
+sub-block from the image data supplied.  If they are larger, the data
+given are replicated (in a tiled fashion) to fill the specified area.
+These rules operate independently in the horizontal and vertical
+directions.
+.PP
+\fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot
+allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
+returned instead and, if the \fIinterp\fR argument is non-NULL, an
+error message is placed in the interpreter's result.
+.PP
+\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that
+the image can be reduced or enlarged for display.  The
+\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the
+image to be reduced by subsampling.
+\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image
+whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y
+coordinates are multiples of \fIsubsampleY\fR.  For example, an image
+of 512x512 pixels can be reduced to 256x256 by setting
+\fIsubsampleX\fR and \fIsubsampleY\fR to 2.
+.PP
+The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be
+enlarged by pixel replication.  Each pixel of the (possibly subsampled)
+input image will be written to a block \fIzoomX\fR pixels wide and
+\fIzoomY\fR pixels high of the displayed image.  Subsampling and
+zooming can be used together for special effects.
+.PP
+\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo
+image.  \fBTk_PhotoGetImage\fR fills
+in the structure pointed to by the \fIblockPtr\fR parameter with values
+that describe the address and layout of the image data that the
+photo image has stored internally.  The values are valid
+until the image is destroyed or its size is changed.
+.PP
+It is possible to modify an image by writing directly to the data
+the \fIpixelPtr\fR field points to. The size of the image cannot be
+changed this way, though.
+Also, changes made by writing directly to \fIpixelPtr\fR will not be
+immediately visible, but only after a call to
+\fBTk_ImageChanged\fR or after an event that causes the interested
+widgets to redraw themselves.
+For these reasons usually it is preferable to make changes to
+a copy of the image data and write it back with
+\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR.
+.PP
+\fBTk_PhotoGetImage\fR returns 1 for compatibility with the
+corresponding procedure in the old photo widget.
+.PP
+\fBTk_PhotoBlank\fR blanks the entire area of the
+photo image.  Blank areas of a photo image are transparent.
+.PP
+\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be
+at least \fIwidth\fR x \fIheight\fR pixels in size.  The width and/or
+height are unchanged if the user has specified an explicit image width
+or height with the \fB\-width\fR and/or \fB\-height\fR configuration
+options, respectively.
+If the image data
+are being supplied in many small blocks, it is more efficient to use
+\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than
+allowing the image to expand in many small increments as image blocks
+are supplied.
+.PP
+\fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot
+allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
+returned instead and, if the \fIinterp\fR argument is non-NULL, an
+error message is placed in the interpreter's result.
+.PP
+\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user
+had specified the given \fIwidth\fR and \fIheight\fR values to the
+\fB\-width\fR and \fB\-height\fR configuration options.  A value of
+zero for \fIwidth\fR or \fIheight\fR does not change the image's width
+or height, but allows the width or height to be changed by subsequent
+calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or
+\fBTk_PhotoExpand\fR.
+.PP
+\fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot
+allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
+returned instead and, if the \fIinterp\fR argument is non-NULL, an
+error message is placed in the interpreter's result.
+.PP
+\fBTk_PhotoGetSize\fR returns the dimensions of the image in
+*\fIwidthPtr\fR and *\fIheightPtr\fR.
+.SH PORTABILITY
+.PP
+In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and
+\fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to
+compile code that uses the old interface against 8.4 without updating
+your code, compile it with the flag
+-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK.  Code linked using Stubs against
+older versions of Tk will continue to work.
+.PP
+In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR,
+\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an
+\fIinterp\fR argument or return any result code.  If insufficient
+memory was available for an image, Tk would panic.  This behaviour is
+still supported if you compile your extension with the additional flag
+-DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE.  Code linked using Stubs against
+older versions of Tk will continue to work.
+.SH BUGS
+The \fBTk_PhotoImageBlock\fR structure used to provide image data to
+\fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the
+data (e.g. separate planes for the red, green, blue and alpha
+channels).  Unfortunately, the implementation fails to hold this
+promise.  The problem is that the \fIpixelSize\fR field is
+(incorrectly) used to determine whether the image has an alpha channel.
+Currently, if the offset for the alpha channel is greater or equal than
+\fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is
+present and makes the image fully opaque.  This means that for layouts
+where the channels are separate (or any other exotic layout where
+\fIpixelSize\fR has to be smaller than the alpha offset), the alpha
+channel will not be read correctly.  In order to be on the safe side
+if this issue will be corrected in a future release, it is strongly
+recommended you always provide alpha data - even if the image has no
+transparency - and only use the "standard" layout with a
+\fIpixelSize\fR of 2 for grayscale and 4 for RGB data with
+\fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively.
+.SH CREDITS
+.PP
+The code for the photo image type was developed by Paul Mackerras,
+based on his earlier photo widget code.
+.SH KEYWORDS
+photo, image

doc/FontId.3

@@ -0,0 +1,94 @@
+'\"
+'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for
+fonts
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Font
+\fBTk_FontId(\fItkfont\fB)\fR
+.sp
+\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR
+.sp
+int
+\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR
+.SH ARGUMENTS
+.AS Tk_FontMetrics *dsPtr
+.AP Tk_Font tkfont in
+Opaque font token being queried.  Must have been returned by a previous
+call to \fBTk_GetFont\fR.
+.AP Tk_FontMetrics *fmPtr out
+Pointer to structure in which the font metrics for \fItkfont\fR will
+be stored. See \fBDATA STRUCTURES\fR below for details.
+.AP Tcl_DString *dsPtr out
+Pointer to an initialized \fBTcl_DString\fR to which the name of the
+Postscript font that corresponds to \fItkfont\fR will be appended.
+.BE
+.SH DESCRIPTION
+.PP
+Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be
+selected into an XGCValues structure in order to construct a graphics
+context that can be used to draw text in the specified font.
+.PP
+\fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the
+\fItkfont\fR in pixels and stores those values in the structure pointer to by
+\fIfmPtr\fR.  These values can be used in computations such as to space
+multiple lines of text, to align the baselines of text in different
+fonts, and to vertically align text in a given region.  See the
+documentation for the \fBfont\fR command for definitions of the terms
+ascent, descent, and linespace, used in font metrics.
+.PP
+\fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding
+Postscript font name that should be used when printing.  The return value
+is the size in points of the \fItkfont\fR and the Postscript font name is
+appended to \fIdsPtr\fR.  \fIDsPtr\fR must refer to an initialized
+\fBTcl_DString\fR.  Given a
+.QW reasonable
+Postscript printer, the
+following screen font families should print correctly:
+.IP
+\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR,
+\fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR,
+\fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR,
+\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and
+\fBZapf Dingbats\fR.
+.PP
+Any other font families may not print correctly because the computed
+Postscript font name may be incorrect or not exist on the printer.
+.SH "DATA STRUCTURES"
+.PP
+The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to
+return information about a font and is defined as follows:
+.CS
+typedef struct Tk_FontMetrics {
+    int \fIascent\fR;
+    int \fIdescent\fR;
+    int \fIlinespace\fR;
+} \fBTk_FontMetrics\fR;
+.CE
+.PP
+The \fIascent\fR field is the amount in pixels that the tallest
+letter sticks up above the baseline, plus any extra blank space added
+by the designer of the font.
+.PP
+The \fIdescent\fR is the largest amount in pixels that any letter
+sticks below the baseline, plus any extra blank space added by the
+designer of the font.
+.PP
+The \fIlinespace\fR is the sum of the ascent and descent.  How far
+apart two lines of text in the same font should be placed so that none
+of the characters in one line overlap any of the characters in the
+other line.
+.SH "SEE ALSO"
+font(n), MeasureChar(3)
+.SH KEYWORDS
+font, measurement, Postscript

doc/FreeXId.3

@@ -0,0 +1,48 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_FreeXId \- make X resource identifier available for reuse
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_FreeXId(\fIdisplay, id\fB)\fR
+.SH ARGUMENTS
+.AS Display *display out
+.AP Display *display in
+Display for which \fIid\fR was allocated.
+.AP XID id in
+Identifier of X resource (window, font, pixmap, cursor, graphics
+context, or colormap) that is no longer in use.
+.BE
+.SH DESCRIPTION
+.PP
+The default allocator for resource identifiers provided by Xlib is very
+simple-minded and does not allow resource identifiers to be re-used.
+If a long-running application reaches the end of the resource id
+space, it will generate an X protocol error and crash.
+Tk replaces the default id allocator with its own allocator, which
+allows identifiers to be reused.
+In order for this to work, \fBTk_FreeXId\fR must be called to
+tell the allocator about resources that have been freed.
+Tk automatically calls \fBTk_FreeXId\fR whenever it frees a
+resource, so if you use procedures like \fBTk_GetFont\fR,
+\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call
+\fBTk_FreeXId\fR.
+However, if you allocate resources directly from Xlib, for example
+by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR
+when you call the corresponding Xlib free procedure, such as
+\fBXFreePixmap\fR.
+If you do not call \fBTk_FreeXId\fR then the resource identifier will
+be lost, which could cause problems if the application runs long enough
+to lose all of the available identifiers.
+.SH KEYWORDS
+resource identifier

doc/GeomReq.3

@@ -0,0 +1,92 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \- specify desired geometry or internal border for a window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR)
+.sp
+\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR)
+.sp
+\fBTk_SetInternalBorder\fR(\fItkwin, width\fR)
+.sp
+\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR)
+.SH ARGUMENTS
+.AS baseHeight clientData
+.AP Tk_Window tkwin in
+Window for which geometry is being requested.
+.AP int reqWidth in
+Desired width for \fItkwin\fR, in pixel units.
+.AP int reqHeight in
+Desired height for \fItkwin\fR, in pixel units.
+.AP int minWidth in
+Desired minimum requested width for \fItkwin\fR, in pixel units.
+.AP int minHeight in
+Desired minimum requested height for \fItkwin\fR, in pixel units.
+.AP int width in
+Space to leave for internal border for \fItkwin\fR, in pixel units.
+.AP int left in
+Space to leave for left side of internal border for \fItkwin\fR, in pixel units.
+.AP int right in
+Space to leave for right side of internal border for \fItkwin\fR, in pixel units.
+.AP int top in
+Space to leave for top side of internal border for \fItkwin\fR, in pixel units.
+.AP int bottom in
+Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GeometryRequest\fR is called by widget code to indicate its
+preference for the dimensions of a particular window.  The arguments
+to \fBTk_GeometryRequest\fR are made available to the geometry
+manager for the window, which then decides on the actual geometry
+for the window.  Although geometry managers generally try to satisfy
+requests made to \fBTk_GeometryRequest\fR, there is no guarantee that
+this will always be possible.  Widget code should not assume that
+a geometry request will be satisfied until it receives a
+\fBConfigureNotify\fR event indicating that the geometry change has
+occurred.  Widget code should never call procedures like
+\fBTk_ResizeWindow\fR directly.  Instead, it should invoke
+\fBTk_GeometryRequest\fR and leave the final geometry decisions to
+the geometry manager.
+.PP
+If \fItkwin\fR is a top-level window, then the geometry information
+will be passed to the window manager using the standard ICCCM protocol.
+.PP
+\fBTk_SetInternalBorder\fR is called by widget code to indicate that
+the widget has an internal border.  This means that the widget draws
+a decorative border inside the window instead of using the standard
+X borders, which are external to the window's area.  For example,
+internal borders are used to draw 3-D effects.  \fIWidth\fR
+specifies the width of the border in pixels.  Geometry managers will
+use this information to avoid placing any children of \fItkwin\fR
+overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area.
+.PP
+\fBTk_SetInternalBorderEx\fR works like \fBTk_SetInternalBorder\fR
+but lets you specify different widths for different sides of the window.
+.PP
+\fBTk_SetMinimumRequestSize\fR is called by widget code to indicate
+that a geometry manager should request at least this size for the
+widget.  This allows a widget to have some control over its size when
+a propagating geometry manager is used inside it.
+.PP
+The information specified in calls to \fBTk_GeometryRequest\fR,
+\fBTk_SetMinimumRequestSize\fR, \fBTk_SetInternalBorder\fR and
+\fBTk_SetInternalBorderEx\fR can be retrieved using the macros
+\fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, \fBTk_MinReqWidth\fR,
+\fBTk_MinReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_InternalBorderLeft\fR,
+\fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and
+\fBTk_InternalBorderBottom\fR.
+See the \fBTk_WindowId\fR manual entry for details.
+.SH KEYWORDS
+geometry, request

doc/GetAnchor.3

@@ -0,0 +1,89 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR
+.sp
+int
+\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfAnchor(\fIanchor\fB)\fR
+.SH ARGUMENTS
+.AS "Tk_Anchor" *anchorPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting, or NULL.
+.AP Tcl_Obj *objPtr in/out
+String value contains name of anchor point:
+.QW \fBn\fR  ,
+.QW \fBne\fR ,
+.QW \fBe\fR  ,
+.QW \fBse\fR ,
+.QW \fBs\fR  ,
+.QW \fBsw\fR ,
+.QW \fBw\fR  ,
+.QW \fBnw\fR ,
+or
+.QW \fBcenter\fR ;
+internal rep will be modified to cache corresponding Tk_Anchor. In the
+case of
+.QW \fBcenter\fR
+on input, a non-empty abbreviation of it may also be used on input.
+.AP "const char" *string in
+Same as \fIobjPtr\fR except description of anchor point is passed as
+a string.
+.AP int *anchorPtr out
+Pointer to location in which to store anchor position corresponding to
+\fIobjPtr\fR or \fIstring\fR.
+.AP Tk_Anchor anchor in
+Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position
+(enumerated type \fBTk_Anchor\fR)
+corresponding to \fIobjPtr\fR's value.  The result will be one of
+\fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR,
+\fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR,
+or \fBTK_ANCHOR_CENTER\fR.
+Anchor positions are typically used for indicating a point on an object
+that will be used to position the object, e.g. \fBTK_ANCHOR_N\fR means
+position the top center point of the object at a particular place.
+.PP
+Under normal circumstances the return value is \fBTCL_OK\fR and
+\fIinterp\fR is unused.
+If \fIstring\fR does not contain a valid anchor position
+or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,
+\fI*anchorPtr\fR is unmodified, and an error message is
+stored in \fIinterp\fR's result if \fIinterp\fR is not NULL.
+\fBTk_GetAnchorFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except
+that the description of the anchor is specified with a string instead
+of an object.  This prevents \fBTk_GetAnchor\fR from caching the
+return value, so \fBTk_GetAnchor\fR is less efficient than
+\fBTk_GetAnchorFromObj\fR.
+.PP
+\fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR.
+Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a
+statically-allocated string corresponding to \fIanchor\fR.
+If \fIanchor\fR is not a legal anchor value, then
+.QW "unknown anchor position"
+is returned.
+.SH KEYWORDS
+anchor position

doc/GetBitmap.3

@@ -0,0 +1,296 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Pixmap
+\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+int
+\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
+.sp
+const char *
+\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
+.sp
+\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
+.sp
+\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
+.SH ARGUMENTS
+.AS "unsigned long" *pixelPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting; if NULL then no error message
+is left after errors.
+.AP Tk_Window tkwin in
+Token for window in which the bitmap will be used.
+.AP Tcl_Obj *objPtr in/out
+String value describes desired bitmap; internal rep will be
+modified to cache pointer to corresponding Pixmap.
+.AP "const char" *info in
+Same as \fIobjPtr\fR except description of bitmap is passed as a string and
+resulting Pixmap is not cached.
+.AP "const char" *name in
+Name for new bitmap to be defined.
+.AP "const void" *source in
+Data for bitmap, in standard bitmap format.
+Must be stored in static memory whose value will never change.
+.AP "int" width in
+Width of bitmap.
+.AP "int" height in
+Height of bitmap.
+.AP "int" *widthPtr out
+Pointer to word to fill in with \fIbitmap\fR's width.
+.AP "int" *heightPtr out
+Pointer to word to fill in with \fIbitmap\fR's height.
+.AP Display *display in
+Display for which \fIbitmap\fR was allocated.
+.AP Pixmap bitmap in
+Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures manage a collection of bitmaps (one-plane pixmaps)
+being used by an application.  The procedures allow bitmaps to be
+re-used efficiently, thereby avoiding server overhead, and also
+allow bitmaps to be named with character strings.
+.PP
+\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
+that matches the description in \fIobjPtr\fR and is suitable for use
+in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
+creates a new one otherwise.  \fIObjPtr\fR's value must have one
+of the following forms:
+.TP 20
+\fB@\fIfileName\fR
+\fIFileName\fR must be the name of a file containing a bitmap
+description in the standard X11 format.
+.TP 20
+\fIname\fR
+\fIName\fR must be the name of a bitmap defined previously with
+a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
+by Tk:
+.RS
+.TP 12
+\fBerror\fR
+The international
+.QW don't
+symbol:  a circle with a diagonal line across it.
+.TP 12
+\fBgray75\fR
+75% gray: a checkerboard pattern where three out of four bits are on.
+.TP 12
+\fBgray50\fR
+50% gray: a checkerboard pattern where every other bit is on.
+.TP 12
+\fBgray25\fR
+25% gray: a checkerboard pattern where one out of every four bits is on.
+.TP 12
+\fBgray12\fR
+12.5% gray: a pattern where one-eighth of the bits are on, consisting of
+every fourth pixel in every other row.
+.TP 12
+\fBhourglass\fR
+An hourglass symbol.
+.TP 12
+\fBinfo\fR
+A large letter
+.QW i .
+.TP 12
+\fBquesthead\fR
+The silhouette of a human head, with a question mark in it.
+.TP 12
+\fBquestion\fR
+A large question-mark.
+.TP 12
+\fBwarning\fR
+A large exclamation point.
+.PP
+In addition, the following pre-defined names are available only on the
+\fBMacintosh\fR platform:
+.TP 12
+\fBdocument\fR
+A generic document.
+.TP 12
+\fBstationery\fR
+Document stationery.
+.TP 12
+\fBedition\fR
+The \fIedition\fR symbol.
+.TP 12
+\fBapplication\fR
+Generic application icon.
+.TP 12
+\fBaccessory\fR
+A desk accessory.
+.TP 12
+\fBfolder\fR
+Generic folder icon.
+.TP 12
+\fBpfolder\fR
+A locked folder.
+.TP 12
+\fBtrash\fR
+A trash can.
+.TP 12
+\fBfloppy\fR
+A floppy disk.
+.TP 12
+\fBramdisk\fR
+A floppy disk with chip.
+.TP 12
+\fBcdrom\fR
+A cd disk icon.
+.TP 12
+\fBpreferences\fR
+A folder with prefs symbol.
+.TP 12
+\fBquerydoc\fR
+A database document icon.
+.TP 12
+\fBstop\fR
+A stop sign.
+.TP 12
+\fBnote\fR
+A face with balloon words.
+.TP 12
+\fBcaution\fR
+A triangle with an exclamation point.
+.RE
+.LP
+Under normal conditions, \fBTk_AllocBitmapFromObj\fR
+returns an identifier for the requested bitmap.  If an error
+occurs in creating the bitmap, such as when \fIobjPtr\fR refers
+to a non-existent file, then \fBNone\fR is returned and an error
+message is left in \fIinterp\fR's result if \fIinterp\fR is not
+NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
+that the description of the bitmap is specified with a string instead
+of an object.  This prevents \fBTk_GetBitmap\fR from caching the
+return value, so \fBTk_GetBitmap\fR is less efficient than
+\fBTk_AllocBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given
+the window and description used to create the bitmap.
+\fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap
+must already have been created with a previous call to
+\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_DefineBitmap\fR associates a name with
+in-memory bitmap data so that the name can be used in later
+calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The \fInameId\fR
+argument gives a name for the bitmap;  it must not previously
+have been used in a call to \fBTk_DefineBitmap\fR.
+The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
+describe the bitmap.
+\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs
+(e.g. a bitmap named \fInameId\fR has already been defined) then
+\fBTCL_ERROR\fR is returned and an error message is left in
+interpreter \fIinterp\fR's result.
+Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
+\fIsource\fR to be static:  \fBTk_DefineBitmap\fR does not make
+a private copy of this memory, but uses the bytes pointed to
+by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.PP
+Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
+bitmap file directly into a C program and then referencing
+the variables defined by the file.
+For example, suppose there exists a file \fBstip.bitmap\fR,
+which was created by the \fBbitmap\fR program and contains
+a stipple pattern.
+The following code uses \fBTk_DefineBitmap\fR to define a
+new bitmap named \fBfoo\fR:
+.CS
+Pixmap bitmap;
+#include "stip.bitmap"
+Tk_DefineBitmap(interp, "foo", stip_bits,
+    stip_width, stip_height);
+\&...
+bitmap = Tk_GetBitmap(interp, tkwin, "foo");
+.CE
+This code causes the bitmap file to be read
+at compile-time and incorporates the bitmap information into
+the program's executable image.  The same bitmap file could be
+read at run-time using \fBTk_GetBitmap\fR:
+.CS
+Pixmap bitmap;
+bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
+.CE
+The second form is a bit more flexible (the file could be modified
+after the program has been compiled, or a different string could be
+provided to read a different file), but it is a little slower and
+requires the bitmap file to exist separately from the program.
+.PP
+Tk maintains a database of all the bitmaps that are currently in use.
+Whenever possible, it will return an existing bitmap rather
+than creating a new one.
+When a bitmap is no longer used, Tk will release it automatically.
+This approach can substantially reduce server overhead, so
+\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
+be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
+.PP
+The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
+are shared, so callers should never modify them.
+If a bitmap must be modified dynamically, then it should be
+created by calling Xlib procedures such as \fBXReadBitmapFile\fR
+or \fBXCreatePixmap\fR directly.
+.PP
+The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
+\fBTk_GetBitmap\fR.
+Given an X Pixmap argument, it returns the textual description that was
+passed to \fBTk_GetBitmap\fR when the bitmap was created.
+\fIBitmap\fR must have been the return value from a previous
+call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
+.PP
+\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
+argument in the words pointed to by the \fIwidthPtr\fR and
+\fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
+\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.PP
+When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or
+\fBTk_FreeBitmap\fR should be called to release it.
+For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified
+with the same information used to create it; for
+\fBTk_FreeBitmap\fR the bitmap to release is specified
+with its Pixmap token.
+There should be exactly one call to \fBTk_FreeBitmapFromObj\fR
+or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.SH BUGS
+.PP
+In determining whether an existing bitmap can be used to satisfy
+a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
+consider only the immediate value of the string description.  For
+example, when a file name is passed to \fBTk_GetBitmap\fR,
+\fBTk_GetBitmap\fR will assume it is safe to re-use an existing
+bitmap created from the same file name:  it will not check to
+see whether the file itself has changed, or whether the current
+directory has changed, thereby causing the name to refer to
+a different file.
+.SH KEYWORDS
+bitmap, pixmap

doc/GetCapStyl.3

@@ -0,0 +1,64 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfCapStyle(\fIcap\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *capPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP "const char" *string in
+String containing name of cap style \- one of
+.QW \fBbutt\fR ,
+.QW \fBprojecting\fR ,
+or
+.QW \fBround\fR
+\- or a unique abbreviation of one.
+.AP int *capPtr out
+Pointer to location in which to store X cap style corresponding to
+\fIstring\fR.
+.AP int cap in
+Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style
+corresponding to \fIstring\fR.
+This will be one of the values
+\fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR.
+Cap styles are typically used in X graphics contexts to indicate
+how the end-points of lines should be capped.
+See the X documentation for information on what each style
+implies.
+.PP
+Under normal circumstances the return value is \fBTCL_OK\fR and
+\fIinterp\fR is unused.
+If \fIstring\fR does not contain a valid cap style
+or an abbreviation of one of these names, then an error message is
+stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and
+\fI*capPtr\fR is unmodified.
+.PP
+\fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR.
+Given a cap style such as \fBCapButt\fR it returns a
+statically-allocated string corresponding to \fIcap\fR.
+If \fIcap\fR is not a legal cap style, then
+.QW "unknown cap style"
+is returned.
+.SH KEYWORDS
+butt, cap style, projecting, round

doc/GetClrmap.3

@@ -0,0 +1,77 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Colormap
+\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR
+.sp
+\fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR
+.sp
+\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR
+.SH ARGUMENTS
+.AS "Colormap" colormap
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window in which colormap will be used.
+.AP "const char" *string in
+Selects a colormap:  either \fBnew\fR or the name of a window
+with the same screen and visual as \fItkwin\fR.
+.AP Display *display in
+Display for which \fIcolormap\fR was allocated.
+.AP Colormap colormap in
+Colormap to free or preserve;  must have been returned by a previous
+call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are used to manage colormaps.
+\fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR.
+If its \fIstring\fR argument is \fBnew\fR then a new colormap is
+created;  otherwise \fIstring\fR must be the name of another window
+with the same screen and visual as \fItkwin\fR, and the colormap from that
+window is returned.
+If \fIstring\fR does not make sense, or if it refers to a window on
+a different screen from \fItkwin\fR or with
+a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns
+\fBNone\fR and leaves an error message in \fIinterp\fR's result.
+.PP
+\fBTk_PreserveColormap\fR increases the internal reference count for a
+colormap previously returned by \fBTk_GetColormap\fR, which allows the
+colormap to be stored in several locations without knowing which order
+they will be released.
+.PP
+\fBTk_FreeColormap\fR should be called when a colormap returned by
+\fBTk_GetColormap\fR is no longer needed.
+Tk maintains a reference count for each colormap returned by
+\fBTk_GetColormap\fR, so there should eventually be one call to
+\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each
+call to \fBTk_PreserveColormap\fR.
+When a colormap's reference count becomes zero, Tk releases the
+X colormap.
+.PP
+\fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that
+a new colormap created by \fBTk_GetVisual\fR may later be returned
+by \fBTk_GetColormap\fR.
+The reference counting mechanism for colormaps includes both procedures,
+so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR
+to release the colormap.
+If \fBTk_GetColormap\fR is called with a \fIstring\fR value of
+\fBnew\fR then the resulting colormap will never
+be returned by \fBTk_GetVisual\fR;  however, it can be used in other
+windows by calling \fBTk_GetColormap\fR with the original window's
+name as \fIstring\fR.
+.SH KEYWORDS
+colormap, visual

doc/GetColor.3

@@ -0,0 +1,176 @@
+'\"
+'\" Copyright (c) 1990-1991 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+XColor *
+\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+XColor *
+\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR
+.sp
+XColor *
+\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+XColor *
+\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfColor(\fIcolorPtr\fB)\fR
+.sp
+GC
+\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR
+.sp
+\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+\fBTk_FreeColor(\fIcolorPtr\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *colorPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window in which color will be used.
+.AP Tcl_Obj *objPtr in/out
+String value describes desired color; internal rep will be
+modified to cache pointer to corresponding (XColor *).
+.AP char *name in
+Same as \fIobjPtr\fR except description of color is passed as a string and
+resulting (XColor *) is not cached.
+.AP XColor *prefPtr in
+Indicates red, green, and blue intensities of desired
+color.
+.AP XColor *colorPtr in
+Pointer to X color information.  Must have been allocated by previous
+call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or
+\fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR.
+.AP Drawable drawable in
+Drawable in which the result graphics context will be used.  Must have
+same screen and depth as the window for which the color was allocated.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures manage the colors being used by a Tk application.
+They allow colors to be shared whenever possible, so that colormap
+space is preserved, and they pick closest available colors when
+colormap space is exhausted.
+.PP
+Given a textual description of a color, \fBTk_AllocColorFromObj\fR
+locates a pixel value that may be used to render the color
+in a particular window.  The desired color is specified with a
+value whose string value must have one of the following forms:
+.TP 20
+\fIcolorname\fR
+Any of the valid textual names for a color defined in the
+server's color database file, such as \fBred\fR or \fBPeachPuff\fR.
+.TP 20
+\fB#\fIRGB\fR
+.TP 20
+\fB#\fIRRGGBB\fR
+.TP 20
+\fB#\fIRRRGGGBBB\fR
+.TP 20
+\fB#\fIRRRRGGGGBBBB\fR
+A numeric specification of the red, green, and blue intensities
+to use to display the color.  Each \fIR\fR, \fIG\fR, or \fIB\fR
+represents a single hexadecimal digit.  The four forms permit
+colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values.
+When fewer than 16 bits are provided for each color, they represent
+the most significant bits of the color, while the lower unfilled
+bits will be repeatedly replicated from the available higher bits.
+For example, #3a7 is the same as #3333aaaa7777.
+.PP
+\fBTk_AllocColorFromObj\fR returns a pointer to
+an XColor structure;  the structure indicates the exact intensities of
+the allocated color (which may differ slightly from those requested,
+depending on the limitations of the screen) and a pixel value
+that may be used to draw with the color in \fItkwin\fR.
+If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown
+color name) then NULL is returned and an error message is stored in
+\fIinterp\fR's result if \fIinterp\fR is not NULL.
+If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR
+will use the closest existing color in the colormap.
+\fBTk_AllocColorFromObj\fR caches information about
+the return value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR.
+.PP
+\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except
+that the description of the color is specified with a string instead
+of a value.  This prevents \fBTk_GetColor\fR from caching the
+return value, so \fBTk_GetColor\fR is less efficient than
+\fBTk_AllocColorFromObj\fR.
+.PP
+\fBTk_GetColorFromObj\fR returns the token for an existing color, given
+the window and description used to create the color.
+\fBTk_GetColorFromObj\fR does not actually create the color; the color
+must already have been created with a previous call to
+\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that
+the desired color is indicated with the \fIred\fR, \fIgreen\fR, and
+\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR.
+.PP
+This package maintains a database
+of all the colors currently in use.
+If the same color is requested multiple times from
+\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different
+windows), or if the
+same intensities are requested multiple times from
+\fBTk_GetColorByValue\fR, then existing pixel values will
+be re-used.  Re-using an existing pixel avoids any interaction
+with the window server, which makes the allocation much more
+efficient.  These procedures also provide a portable interface that
+works across all platforms.  For this reason, you should generally use
+\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR
+instead of lower level procedures like \fBXAllocColor\fR.
+.PP
+Since different calls to this package
+may return the same shared
+pixel value, callers should never change the color of a pixel
+returned by the procedures.
+If you need to change a color value dynamically, you should use
+\fBXAllocColorCells\fR to allocate the pixel value for the color.
+.PP
+The procedure \fBTk_NameOfColor\fR is roughly the inverse of
+\fBTk_GetColor\fR.  If its \fIcolorPtr\fR argument was created
+by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value
+is the string that was used to create the
+color.  If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR,
+or by any other mechanism, then the return value is a string
+that could be passed to \fBTk_GetColor\fR to return the same
+color.  Note:  the string returned by \fBTk_NameOfColor\fR is
+only guaranteed to persist until the next call to
+\fBTk_NameOfColor\fR.
+.PP
+\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR
+field is the pixel allocated for \fIcolorPtr\fR and whose other fields
+all have default values.
+This provides an easy way to do basic drawing with a color.
+The graphics context is cached with the color and will exist only as
+long as \fIcolorPtr\fR exists;  it is freed when the last reference
+to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR.
+.PP
+When a color is no longer needed \fBTk_FreeColorFromObj\fR or
+\fBTk_FreeColor\fR should be called to release it.
+For \fBTk_FreeColorFromObj\fR the color to release is specified
+with the same information used to create it; for
+\fBTk_FreeColor\fR the color to release is specified
+with a pointer to its XColor structure.
+There should be exactly one call to \fBTk_FreeColorFromObj\fR
+or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR,
+\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR.
+.SH KEYWORDS
+color, intensity, value, pixel value

doc/GetCursor.3

@@ -0,0 +1,231 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Cursor
+\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_Cursor
+\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR
+.sp
+Tk_Cursor
+\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+Tk_Cursor
+\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR
+.sp
+const char *
+\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR
+.sp
+\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR
+.SH ARGUMENTS
+.AS "unsigned long" *pixelPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window in which the cursor will be used.
+.AP Tcl_Obj *objPtr in/out
+Description of cursor;  see below for possible values.  Internal rep will be
+modified to cache pointer to corresponding Tk_Cursor.
+.AP char *name in
+Same as \fIobjPtr\fR except description of cursor is passed as a string and
+resulting Tk_Cursor is not cached.
+.AP "const char" *source in
+Data for cursor cursor, in standard cursor format.
+.AP "const char" *mask in
+Data for mask cursor, in standard cursor format.
+.AP "int" width in
+Width of \fIsource\fR and \fImask\fR.
+.AP "int" height in
+Height of \fIsource\fR and \fImask\fR.
+.AP "int" xHot in
+X-location of cursor hot-spot.
+.AP "int" yHot in
+Y-location of cursor hot-spot.
+.AP Tk_Uid fg in
+Textual description of foreground color for cursor.
+.AP Tk_Uid bg in
+Textual description of background color for cursor.
+.AP Display *display in
+Display for which \fIcursor\fR was allocated.
+.AP Tk_Cursor cursor in
+Opaque Tk identifier for cursor.  If passed to \fBTk_FreeCursor\fR, must
+have been returned by some previous call to \fBTk_GetCursor\fR or
+\fBTk_GetCursorFromData\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures manage a collection of cursors
+being used by an application.  The procedures allow cursors to be
+re-used efficiently, thereby avoiding server overhead, and also
+allow cursors to be named with character strings.
+.PP
+\fBTk_AllocCursorFromObj\fR takes as argument an object describing a
+cursor, and returns an opaque Tk identifier for a cursor corresponding
+to the description.  It re-uses an existing cursor if possible and
+creates a new one otherwise.  \fBTk_AllocCursorFromObj\fR caches
+information about the return value in \fIobjPtr\fR, which speeds up
+future calls to procedures such as \fBTk_AllocCursorFromObj\fR and
+\fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor,
+such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR
+is returned and an error message will be stored in \fIinterp\fR's result
+if \fIinterp\fR is not NULL.  \fIObjPtr\fR must contain a standard Tcl
+list with one of the following forms:
+.TP
+\fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]]
+\fIName\fR is the name of a cursor in the standard X cursor cursor,
+i.e., any of the names defined in \fBcursorcursor.h\fR, without
+the \fBXC_\fR.  Some example values are \fBX_cursor\fR, \fBhand2\fR,
+or \fBleft_ptr\fR.  Appendix B of
+.QW "The X Window System"
+by Scheifler & Gettys has illustrations showing what each of these
+cursors looks like.  If \fIfgColor\fR and \fIbgColor\fR are both
+specified, they give the foreground and background colors to use
+for the cursor (any of the forms acceptable to \fBTk_GetColor\fR
+may be used).  If only \fIfgColor\fR is specified, then there
+will be no background color:  the background will be transparent.
+If no colors are specified, then the cursor
+will use black for its foreground color and white for its background
+color.
+.RS
+.PP
+The Macintosh version of Tk supports all of the X cursors and
+will also accept any of the standard Mac cursors
+including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and
+\fBarrow\fR.  In addition, Tk will load Macintosh cursor resources of
+the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the
+name of the resource.  The application and all its open
+dynamic library's resource files will be searched for the named
+cursor.  If there are conflicts color cursors will always be loaded
+in preference to black and white cursors.
+.RE
+.TP
+\fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR
+In this form, \fIsourceName\fR and \fImaskName\fR are the names of
+files describing cursors for the cursor's source bits and mask.
+Each file must be in standard X11 cursor format.
+\fIFgColor\fR and \fIbgColor\fR
+indicate the colors to use for the
+cursor, in any of the forms acceptable to \fBTk_GetColor\fR.  This
+form of the command will not work on Macintosh or Windows computers.
+.TP
+\fB@\fIsourceName\0fgColor\fR
+This form is similar to the one above, except that the source is
+used as mask also.  This means that the cursor's background is
+transparent.  This form of the command will not work on Macintosh
+or Windows computers.
+.TP
+\fB@\fIsourceName\fR
+This form only works on Windows, and will load a Windows system
+cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in
+\fIsourceName\fR.
+.PP
+\fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except
+that the description of the cursor is specified with a string instead
+of an object.  This prevents \fBTk_GetCursor\fR from caching the
+return value, so \fBTk_GetCursor\fR is less efficient than
+\fBTk_AllocCursorFromObj\fR.
+.PP
+\fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given
+the window and description used to create the cursor.
+\fBTk_GetCursorFromObj\fR does not actually create the cursor; the cursor
+must already have been created with a previous call to
+\fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_GetCursorFromData\fR allows cursors to be created from
+in-memory descriptions of their source and mask cursors.  \fISource\fR
+points to standard cursor data for the cursor's source bits, and
+\fImask\fR points to standard cursor data describing
+which pixels of \fIsource\fR are to be drawn and which are to be
+considered transparent.  \fIWidth\fR and \fIheight\fR give the
+dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the
+location of the cursor's hot-spot (the point that is reported when
+an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's
+foreground and background colors textually (any of the forms
+suitable for \fBTk_GetColor\fR may be used).  Typically, the
+arguments to \fBTk_GetCursorFromData\fR are created by including
+a cursor file directly into the source code for a program, as in
+the following example:
+.CS
+Tk_Cursor cursor;
+#include "source.cursor"
+#include "mask.cursor"
+cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
+    mask_bits, source_width, source_height, source_x_hot,
+    source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
+.CE
+.PP
+Under normal conditions \fBTk_GetCursorFromData\fR
+will return an identifier for the requested cursor.  If an error
+occurs in creating the cursor then \fBNone\fR is returned and an error
+message will be stored in \fIinterp\fR's result.
+.PP
+\fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and
+\fBTk_GetCursorFromData\fR maintain a
+database of all the cursors they have created.  Whenever possible,
+a call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or
+\fBTk_GetCursorFromData\fR will
+return an existing cursor rather than creating a new one.  This
+approach can substantially reduce server overhead, so the Tk
+procedures should generally be used in preference to Xlib procedures
+like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which
+create a new cursor on each call.  The Tk procedures are also more
+portable than the lower-level X procedures.
+.PP
+The procedure \fBTk_NameOfCursor\fR is roughly the inverse of
+\fBTk_GetCursor\fR.  If its \fIcursor\fR argument was created
+by \fBTk_GetCursor\fR, then the return value is the \fIname\fR
+argument that was passed to \fBTk_GetCursor\fR to create the
+cursor.  If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR,
+or by any other mechanism, then the return value is a hexadecimal string
+giving the X identifier for the cursor.
+Note:  the string returned by \fBTk_NameOfCursor\fR is
+only guaranteed to persist until the next call to
+\fBTk_NameOfCursor\fR.  Also, this call is not portable except for
+cursors returned by \fBTk_GetCursor\fR.
+.PP
+When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+or \fBTk_GetCursorFromData\fR
+is no longer needed, \fBTk_FreeCursorFromObj\fR or
+\fBTk_FreeCursor\fR should be called to release it.
+For \fBTk_FreeCursorFromObj\fR the cursor to release is specified
+with the same information used to create it; for
+\fBTk_FreeCursor\fR the cursor to release is specified
+with its Tk_Cursor token.
+There should be exactly one call to \fBTk_FreeCursor\fR for
+each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+or \fBTk_GetCursorFromData\fR.
+.SH BUGS
+.PP
+In determining whether an existing cursor can be used to satisfy
+a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+and \fBTk_GetCursorFromData\fR
+consider only the immediate values of their arguments.  For
+example, when a file name is passed to \fBTk_GetCursor\fR,
+\fBTk_GetCursor\fR will assume it is safe to re-use an existing
+cursor created from the same file name:  it will not check to
+see whether the file itself has changed, or whether the current
+directory has changed, thereby causing the name to refer to
+a different file.  Similarly, \fBTk_GetCursorFromData\fR assumes
+that if the same \fIsource\fR pointer is used in two different calls,
+then the pointers refer to the same data;  it does not check to
+see if the actual data values have changed.
+.SH KEYWORDS
+cursor

doc/GetDash.3

@@ -0,0 +1,82 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetDash \- convert from string to valid dash structure.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+
+int
+\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR)
+.fi
+.SH ARGUMENTS
+.AS Tk_Dash *dashPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP "const char" *string in
+Textual value to be converted.
+.AP Tk_Dash *dashPtr out
+Points to place to store the dash pattern
+value converted from \fIstring\fR. Must not be NULL.
+.BE
+.SH DESCRIPTION
+.PP
+These procedure parses the string and fills in the result in the
+Tk_Dash structure. The string can be a list of integers or a
+character string containing only
+.QW \fB.,-_\fR
+and spaces. If all
+goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored
+in the variable pointed to by \fIdashPtr\fR.
+If \fIstring\fR does not have the
+proper syntax then \fBTCL_ERROR\fR is returned, an error message is left
+in the interpreter's result, and nothing is stored at *\fIdashPtr\fR.
+.PP
+The first possible syntax is a list of integers. Each element
+represents the number of pixels of a line segment. Only the odd
+segments are drawn using the
+.QW outline
+color. The other segments are drawn transparent.
+.PP
+The second possible syntax is a character list containing only
+5 possible characters
+.QW "\fB.,-_ \fR" .
+The space can be used
+to enlarge the space between other line elements, and can not
+occur in the first position of the string. Some examples:
+.PP
+.CS
+    \-dash .     = \-dash {2 4}
+    \-dash -     = \-dash {6 4}
+    \-dash -.    = \-dash {6 4 2 4}
+    \-dash -..   = \-dash {6 4 2 4 2 4}
+    \-dash {. }  = \-dash {2 8}
+    \-dash ,     = \-dash {4 4}
+.CE
+.PP
+The main difference between this syntax and the numeric is that it
+is shape-conserving. This means that all values in the dash
+list will be multiplied by the line width before display. This
+ensures that
+.QW .
+will always be displayed as a dot and
+.QW -
+always as a dash regardless of the line width.
+.PP
+On systems where only a limited set of dash patterns, the dash
+pattern will be displayed as the most close dash pattern that
+is available. For example, on Windows only the first 4 of the
+above examples are available; the last 2 examples will be
+displayed identically to the first one.
+.SH "SEE ALSO"
+canvas(n), Tk_CreateItemType(3)
+.SH KEYWORDS
+dash, conversion

doc/GetFont.3

@@ -0,0 +1,110 @@
+'\"
+'\" Copyright (c) 1990-1992 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Font
+\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_Font
+\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
+.sp
+Tk_Font
+\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfFont(\fItkfont\fB)\fR
+.sp
+Tk_Font
+\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR
+.sp
+void
+\fBTk_FreeFont(\fItkfont\fB)\fR
+.SH ARGUMENTS
+.AS "const char" *tkfont
+.AP "Tcl_Interp" *interp in
+Interpreter to use for error reporting.  If \fBNULL\fR, then no error
+messages are left after errors.
+.AP Tk_Window tkwin in
+Token for window in which font will be used.
+.AP Tcl_Obj *objPtr in/out
+Gives name or description of font.  See documentation
+for the \fBfont\fR command for details on acceptable formats.
+Internal rep will be modified to cache corresponding Tk_Font.
+.AP "const char" *string in
+Same as \fIobjPtr\fR except description of font is passed as a string and
+resulting Tk_Font is not cached.
+.AP Tk_Font tkfont in
+Opaque font token.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and
+returns a token that represents the font.  The return value can be used
+in subsequent calls to procedures such as \fBTk_GetFontMetrics\fR,
+\fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR.  The Tk_Font token
+will remain valid until
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it.
+\fIObjPtr\fR can contain either a symbolic name or a font description; see
+the documentation for the \fBfont\fR command for a description of the
+valid formats.  If \fBTk_AllocFontFromObj\fR is unsuccessful (because,
+for example, \fIobjPtr\fR did not contain a valid font specification) then it
+returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result
+if \fIinterp\fR is not \fBNULL\fR.  \fBTk_AllocFontFromObj\fR caches
+information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR.
+.PP
+\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except
+that the description of the font is specified with a string instead
+of an object.  This prevents \fBTk_GetFont\fR from caching the
+matching Tk_Font, so \fBTk_GetFont\fR is less efficient than
+\fBTk_AllocFontFromObj\fR.
+.PP
+\fBTk_GetFontFromObj\fR returns the token for an existing font, given
+the window and description used to create the font.
+\fBTk_GetFontFromObj\fR does not actually create the font; the font
+must already have been created with a previous call to
+\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain
+a database of all fonts they have allocated.  If
+the same font is requested multiple times (e.g. by different
+windows or for different purposes), then a single Tk_Font will be
+shared for all uses.  The underlying resources will be freed automatically
+when no-one is using the font anymore.
+.PP
+The procedure \fBTk_NameOfFont\fR is roughly the inverse of
+\fBTk_GetFont\fR.  Given a \fItkfont\fR that was created by
+\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is
+the \fIstring\fR argument that was
+passed to \fBTk_GetFont\fR to create the font.  The string returned by
+\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR
+is deleted.  The caller must not modify this string.
+.PP
+When a font is no longer needed,
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to
+release it.  For \fBTk_FreeFontFromObj\fR the font to release is specified
+with the same information used to create it; for
+\fBTk_FreeFont\fR the font to release is specified
+with its Tk_Font token.  There should be
+exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR
+for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.
+.SH "SEE ALSO"
+Tk_FontId(3)
+.SH KEYWORDS
+font

doc/GetGC.3

@@ -0,0 +1,70 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetGC 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+GC
+\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
+.sp
+\fBTk_FreeGC(\fIdisplay, gc\fR)
+.SH ARGUMENTS
+.AS "unsigned long" valueMask
+.AP Tk_Window tkwin in
+Token for window in which the graphics context will be used.
+.AP "unsigned long" valueMask in
+Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR)
+indicating which fields of \fI*valuePtr\fR are valid.
+.AP XGCValues *valuePtr in
+Pointer to structure describing the desired values for the
+graphics context.
+.AP Display *display in
+Display for which \fIgc\fR was allocated.
+.AP GC gc in
+X identifier for graphics context that is no longer needed.
+Must have been allocated by \fBTk_GetGC\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts
+being used by an application.  The procedures allow graphics contexts to be
+shared, thereby avoiding the server overhead that would be incurred
+if a separate GC were created for each use.  \fBTk_GetGC\fR takes arguments
+describing the desired graphics context and returns an X identifier
+for a GC that fits the description.  The graphics context that is returned
+will have default values in all of the fields not specified explicitly
+by \fIvalueMask\fR and \fIvaluePtr\fR.
+.PP
+\fBTk_GetGC\fR maintains a
+database of all the graphics contexts it has created.  Whenever possible,
+a call to \fBTk_GetGC\fR will
+return an existing graphics context rather than creating a new one.  This
+approach can substantially reduce server overhead, so \fBTk_GetGC\fR
+should generally be used in preference to the Xlib procedure
+\fBXCreateGC\fR, which creates a new graphics context on each call.
+.PP
+Since the return values of \fBTk_GetGC\fR
+are shared, callers should never modify the graphics contexts
+returned by \fBTk_GetGC\fR.
+If a graphics context must be modified dynamically, then it should be
+created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR.
+.PP
+When a graphics context
+is no longer needed, \fBTk_FreeGC\fR should be called to release it.
+There should be exactly one call to \fBTk_FreeGC\fR for
+each call to \fBTk_GetGC\fR.
+When a graphics context is no longer in use anywhere (i.e. it has
+been freed as many times as it has been gotten) \fBTk_FreeGC\fR
+will release it to the X server and delete it from the database.
+.SH KEYWORDS
+graphics context

doc/GetHINSTANCE.3

@@ -0,0 +1,22 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetHINSTANCE \- retrieve the global application instance handle
+.SH SYNOPSIS
+.nf
+\fB#include <tkPlatDecls.h>\fR
+.sp
+HINSTANCE
+\fBTk_GetHINSTANCE\fR()
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetHINSTANCE\fR returns the Windows application instance handle
+for the Tk application.  This function is only available on Windows platforms.
+.SH KEYWORDS
+identifier, instance

doc/GetHWND.3

@@ -0,0 +1,36 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.TH HWND 3 8.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetHWND, Tk_AttachHWND \- manage interactions between the Windows handle and an X window
+.SH SYNOPSIS
+.nf
+\fB#include <tkPlatDecls.h>\fR
+.sp
+HWND
+\fBTk_GetHWND\fR(\fIwindow\fR)
+.sp
+Window
+\fBTk_AttachHWND\fR(\fItkwin, hwnd\fR)
+.SH ARGUMENTS
+.AP Window window in
+X token for window.
+.AP Tk_Window tkwin in
+Tk window for window.
+.AP HWND hwnd in
+Windows HWND for window.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetHWND\fR returns the Windows HWND identifier for X Windows
+window given by \fIwindow\fR.
+.PP
+\fBTk_AttachHWND\fR binds the Windows HWND identifier to the
+specified Tk_Window given by \fItkwin\fR. It returns an X Windows
+window that encapsulates the HWND.
+.SH KEYWORDS
+identifier, window

doc/GetImage.3

@@ -0,0 +1,130 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Image
+\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
+.sp
+\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
+.sp
+\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
+.sp
+\fBTk_FreeImage\fR(\fIimage\fR)
+.SH ARGUMENTS
+.AS Tk_ImageChangedProc *changeProc
+.AP Tcl_Interp *interp in
+Place to leave error message.
+.AP Tk_Window tkwin in
+Window in which image will be used.
+.AP "const char" *name in
+Name of image.
+.AP Tk_ImageChangedProc *changeProc in
+Procedure for Tk to invoke whenever image content or size changes.
+.AP ClientData clientData in
+One-word value for Tk to pass to \fIchangeProc\fR.
+.AP Tk_Image image in
+Token for image instance;  must have been returned by a previous
+call to \fBTk_GetImage\fR.
+.AP int imageX in
+X-coordinate of upper-left corner of region of image to redisplay
+(measured in pixels from the image's upper-left corner).
+.AP int imageY in
+Y-coordinate of upper-left corner of region of image to redisplay
+(measured in pixels from the image's upper-left corner).
+.AP "int" width (in)
+Width of region of image to redisplay.
+.AP "int" height (in)
+Height of region of image to redisplay.
+.AP Drawable drawable in
+Where to display image.  Must either be window specified to
+\fBTk_GetImage\fR or a pixmap compatible with that window.
+.AP int drawableX in
+Where to display image in \fIdrawable\fR: this is the x-coordinate
+in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image
+should be displayed.
+.AP int drawableY in
+Where to display image in \fIdrawable\fR: this is the y-coordinate
+in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image
+should be displayed.
+.AP "int" widthPtr out
+Store width of \fIimage\fR (in pixels) here.
+.AP "int" heightPtr out
+Store height of \fIimage\fR (in pixels) here.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are invoked by widgets that wish to display images.
+\fBTk_GetImage\fR is invoked by a widget when it first decides to
+display an image.
+\fIname\fR gives the name of the desired image and \fItkwin\fR
+identifies the window where the image will be displayed.
+\fBTk_GetImage\fR looks up the image in the table of existing
+images and returns a token for a new instance of the image.
+If the image does not exist then \fBTk_GetImage\fR returns NULL
+and leaves an error message in interpreter \fIinterp\fR's result.
+.PP
+When a widget wishes to actually display an image it must
+call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR),
+a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR,
+\fIwidth\fR, and \fIheight\fR), and a place to display the
+image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR).
+Tk will then invoke the appropriate image manager, which will
+display the requested portion of the image before returning.
+.PP
+A widget can find out the dimensions of an image by calling
+\fBTk_SizeOfImage\fR:  the width and height will be stored
+in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR,
+respectively.
+.PP
+When a widget is finished with an image (e.g., the widget is
+being deleted or it is going to use a different image instead
+of the current one), it must call \fBTk_FreeImage\fR to
+release the image instance.
+The widget should never again use the image token after passing
+it to \fBTk_FreeImage\fR.
+There must be exactly one call to \fBTk_FreeImage\fR for each
+call to \fBTk_GetImage\fR.
+.PP
+If the contents or size of an image changes, then any widgets
+using the image will need to find out about the changes so that
+they can redisplay themselves.
+The \fIchangeProc\fR and \fIclientData\fR arguments to
+\fBTk_GetImage\fR are used for this purpose.
+\fIchangeProc\fR will be called by Tk whenever a change occurs
+in the image;  it must match the following prototype:
+.CS
+typedef void \fBTk_ImageChangedProc\fR(
+        ClientData \fIclientData\fR,
+        int \fIx\fR,
+        int \fIy\fR,
+        int \fIwidth\fR,
+        int \fIheight\fR,
+        int \fIimageWidth\fR,
+        int \fIimageHeight\fR);
+.CE
+The \fIclientData\fR argument to \fIchangeProc\fR is the same as the
+\fIclientData\fR argument to \fBTk_GetImage\fR.
+It is usually a pointer to the widget record for the widget or
+some other data structure managed by the widget.
+The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
+identify a region within the image that must be redisplayed;
+they are specified in pixels measured from the upper-left
+corner of the image.
+The arguments \fIimageWidth\fR and \fIimageHeight\fR give
+the image's (new) size.
+.SH "SEE ALSO"
+Tk_CreateImageType
+.SH KEYWORDS
+images, redisplay

doc/GetJoinStl.3

@@ -0,0 +1,63 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *joinPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP "const char" *string in
+String containing name of join style \- one of
+.QW \fBbevel\fR ,
+.QW \fBmiter\fR ,
+or
+.QW \fBround\fR
+\- or a unique abbreviation of one.
+.AP int *joinPtr out
+Pointer to location in which to store X join style corresponding to
+\fIstring\fR.
+.AP int join in
+Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style
+corresponding to \fIstring\fR, which will be one of
+\fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR.
+Join styles are typically used in X graphics contexts to indicate
+how adjacent line segments should be joined together.
+See the X documentation for information on what each style
+implies.
+.PP
+Under normal circumstances the return value is \fBTCL_OK\fR and
+\fIinterp\fR is unused.
+If \fIstring\fR does not contain a valid join style
+or an abbreviation of one of these names, then an error message is
+stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and
+\fI*joinPtr\fR is unmodified.
+.PP
+\fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR.
+Given a join style such as \fBJoinBevel\fR it returns a
+statically-allocated string corresponding to \fIjoin\fR.
+If \fIjoin\fR is not a legal join style, then
+.QW "unknown join style"
+is returned.
+.SH KEYWORDS
+bevel, join style, miter, round

doc/GetJustify.3

@@ -0,0 +1,87 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR
+.sp
+int
+\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfJustify(\fIjustify\fB)\fR
+.SH ARGUMENTS
+.AS "Tk_Justify" *justifyPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting, or NULL.
+.AP Tcl_Obj *objPtr in/out
+String value contains name of justification style \- one of
+.QW \fBleft\fR ,
+.QW \fBright\fR ,
+or
+.QW \fBcenter\fR
+\- or a unique abbreviation of one.
+The internal rep will be modified to cache corresponding justify value.
+.AP "const char" *string in
+Same as \fIobjPtr\fR except description of justification style is passed as
+a string.
+.AP int *justifyPtr out
+Pointer to location in which to store justify value corresponding to
+\fIobjPtr\fR or \fIstring\fR.
+.AP Tk_Justify justify in
+Justification style (one of the values listed below).
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value
+corresponding to \fIobjPtr\fR's value.
+This value will be one of the following:
+.TP
+\fBTK_JUSTIFY_LEFT\fR
+Means that the text on each line should start at the left edge of
+the line;  as a result, the right edges of lines may be ragged.
+.TP
+\fBTK_JUSTIFY_RIGHT\fR
+Means that the text on each line should end at the right edge of
+the line;  as a result, the left edges of lines may be ragged.
+.TP
+\fBTK_JUSTIFY_CENTER\fR
+Means that the text on each line should be centered;  as a result,
+both the left and right edges of lines may be ragged.
+.PP
+Under normal circumstances the return value is \fBTCL_OK\fR and
+\fIinterp\fR is unused.
+If \fIobjPtr\fR does not contain a valid justification style
+or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,
+\fI*justifyPtr\fR is unmodified, and an error message is
+stored in \fIinterp\fR's result if \fIinterp\fR is not NULL.
+\fBTk_GetJustifyFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except
+that the description of the justification is specified with a string instead
+of an object.  This prevents \fBTk_GetJustify\fR from caching the
+return value, so \fBTk_GetJustify\fR is less efficient than
+\fBTk_GetJustifyFromObj\fR.
+.PP
+\fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR.
+Given a justify value it returns a statically-allocated string
+corresponding to \fIjustify\fR.
+If \fIjustify\fR is not a legal justify value, then
+.QW "unknown justification style"
+is returned.
+.SH KEYWORDS
+center, fill, justification, string

doc/GetOption.3

@@ -0,0 +1,42 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetOption 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetOption \- retrieve an option from the option database
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Uid
+\fBTk_GetOption\fR(\fItkwin, name, class\fR)
+.SH ARGUMENTS
+.AS Tk_Window *class
+.AP Tk_Window tkwin in
+Token for window.
+.AP "const char" *name in
+Name of desired option.
+.AP "const char" *class in
+Class of desired option.  Null means there is no class for
+this option;  do lookup based on name only.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure is invoked to retrieve an option from the database
+associated with \fItkwin\fR's main window.  If there is an option
+for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR,
+then it is returned in the form of a Tk_Uid.  If multiple options
+match \fIname\fR and \fIclass\fR, then the highest-priority one
+is returned.  If no option matches, then NULL is returned.
+.PP
+\fBTk_GetOption\fR caches options related to \fItkwin\fR so that
+successive calls for the same \fItkwin\fR will execute much more
+quickly than successive calls for different windows.
+.SH KEYWORDS
+class, name, option, retrieve

doc/GetPixels.3

@@ -0,0 +1,95 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR
+.sp
+int
+\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR
+.sp
+int
+\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
+.sp
+int
+\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *joinPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Window whose screen geometry determines the conversion between absolute
+units and pixels.
+.AP Tcl_Obj *objPtr in/out
+String value specifies a distance on the screen;
+internal rep will be modified to cache converted distance.
+.AP "const char" *string in
+Same as \fIobjPtr\fR except specification of distance is passed as
+a string.
+.AP int *intPtr out
+Pointer to location in which to store converted distance in pixels.
+.AP double *doublePtr out
+Pointer to location in which to store converted distance in millimeters.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures take as argument a specification of distance on
+the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
+corresponding distance either in integer pixels or floating-point millimeters.
+In either case,
+\fIobjPtr\fR or \fIstring\fR
+specifies a screen distance as a
+floating-point number followed by one of the following characters
+that indicates units:
+.TP
+<none>
+The number specifies a distance in pixels.
+.TP
+\fBc\fR
+The number specifies a distance in centimeters on the screen.
+.TP
+\fBi\fR
+The number specifies a distance in inches on the screen.
+.TP
+\fBm\fR
+The number specifies a distance in millimeters on the screen.
+.TP
+\fBp\fR
+The number specifies a distance in printer's points (1/72 inch)
+on the screen.
+.PP
+\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
+nearest even number of pixels and stores that value at \fI*intPtr\fR.
+It returns \fBTCL_OK\fR under normal circumstances.
+If an error occurs (e.g. \fIobjPtr\fR contains a number followed
+by a character that is not one of the ones above) then
+\fBTCL_ERROR\fR is returned and an error message is left
+in \fIinterp\fR's result if \fIinterp\fR is not NULL.
+\fBTk_GetPixelsFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except
+that the screen distance is specified with a string instead
+of an object.  This prevents \fBTk_GetPixels\fR from caching the
+return value, so \fBTk_GetPixels\fR is less efficient than
+\fBTk_GetPixelsFromObj\fR.
+.PP
+\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to
+\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except
+that they convert the screen distance to millimeters and
+store a double-precision floating-point result at \fI*doublePtr\fR.
+.SH KEYWORDS
+centimeters, convert, inches, millimeters, pixels, points, screen units

doc/GetPixmap.3

@@ -0,0 +1,52 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Pixmap
+\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR
+.sp
+\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR
+.SH ARGUMENTS
+.AS "Drawable" *pixelPtr
+.AP Display *display in
+X display for the pixmap.
+.AP Drawable d in
+Pixmap or window where the new pixmap will be used for drawing.
+.AP "int" width in
+Width of pixmap.
+.AP "int" height in
+Height of pixmap.
+.AP "int" depth in
+Number of bits per pixel in pixmap.
+.AP Pixmap pixmap in
+Pixmap to destroy.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR
+and \fBXFreePixmap\fR, except that they have extra code to manage X
+resource identifiers so that identifiers for deleted pixmaps can be
+reused in the future.
+It is important for Tk applications to use these procedures rather
+than \fBXCreatePixmap\fR and \fBXFreePixmap\fR;  otherwise long-running
+applications may run out of resource identifiers.
+.PP
+\fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR,
+with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR,
+and returns its identifier.
+\fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes
+its resource identifier available for reuse.
+.SH KEYWORDS
+pixmap, resource identifier

doc/GetRelief.3

@@ -0,0 +1,82 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR
+.sp
+int
+\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR
+.sp
+const char *
+\fBTk_NameOfRelief(\fIrelief\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *reliefPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tcl_Obj *objPtr in/out
+String value contains name of relief, one of
+.QW \fBflat\fR ,
+.QW \fBgroove\fR ,
+.QW \fBraised\fR ,
+.QW \fBridge\fR ,
+.QW \fBsolid\fR ,
+or
+.QW \fBsunken\fR
+(or any unique abbreviation thereof on input);
+the internal rep will be modified to cache corresponding relief value.
+.AP char *string in
+Same as \fIobjPtr\fR except description of relief is passed as
+a string.
+.AP int *reliefPtr out
+Pointer to location in which to store relief value corresponding to
+\fIobjPtr\fR or \fIname\fR.
+.AP "const char" *name
+Name of the relief.
+.AP int relief in
+Relief value (one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR,
+\fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR,
+or \fBTK_RELIEF_RIDGE\fR).
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value
+corresponding to the value of \fIobjPtr\fR.  This value will be one of
+\fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR,
+\fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR.
+Under normal circumstances the return value is \fBTCL_OK\fR and
+\fIinterp\fR is unused.
+If \fIobjPtr\fR does not contain one of the valid relief names
+or an abbreviation of one of them, then \fBTCL_ERROR\fR is returned,
+\fI*reliefPtr\fR is unmodified, and an error message
+is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL.
+\fBTk_GetReliefFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except
+that the description of the relief is specified with a string instead
+of an object.  This prevents \fBTk_GetRelief\fR from caching the
+return value, so \fBTk_GetRelief\fR is less efficient than
+\fBTk_GetReliefFromObj\fR.
+.PP
+\fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR.
+Given a relief value it returns the corresponding string (\fBflat\fR,
+\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR).
+If \fIrelief\fR is not a legal relief value, then
+.QW "unknown relief"
+is returned.
+.SH KEYWORDS
+name, relief, string

doc/GetRootCrd.3

@@ -0,0 +1,39 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetRootCoords \- Compute root-window coordinates of window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR)
+.SH ARGUMENTS
+.AS Tk_Window tkwin
+.AP Tk_Window tkwin in
+Token for window.
+.AP int *xPtr out
+Pointer to location in which to store root-window x-coordinate
+corresponding to left edge of \fItkwin\fR's border.
+.AP int *yPtr out
+Pointer to location in which to store root-window y-coordinate
+corresponding to top edge of \fItkwin\fR's border.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure scans through the structural information maintained
+by Tk to compute the root-window coordinates corresponding to
+the upper-left corner of \fItkwin\fR's border.  If \fItkwin\fR has
+no border, then \fBTk_GetRootCoords\fR returns the root-window
+coordinates corresponding to location (0,0) in \fItkwin\fR.
+\fBTk_GetRootCoords\fR is relatively efficient, since it does not have to
+communicate with the X server.
+.SH KEYWORDS
+coordinates, root window

doc/GetScroll.3

@@ -0,0 +1,75 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR
+.sp
+int
+\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *fractionPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP int objc in
+Number of Tcl_Obj's in \fIobjv\fR array.
+.AP "Tcl_Obj *const" objv[] in
+Argument objects.  These represent the entire widget command, of
+which the first word is typically the widget name and the second
+word is typically \fBxview\fR or \fByview\fR.
+.AP int argc in
+Number of strings in \fIargv\fR array.
+.AP "const char" *argv[] in
+Argument strings.  These represent the entire widget command, of
+which the first word is typically the widget name and the second
+word is typically \fBxview\fR or \fByview\fR.
+.AP double *fractionPtr out
+Filled in with fraction from \fBmoveto\fR option, if any.
+.AP int *stepsPtr out
+Filled in with line or page count from \fBscroll\fR option, if any.
+The value may be negative.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetScrollInfoObj\fR parses the arguments expected by widget
+scrolling commands such as \fBxview\fR and \fByview\fR.
+It receives the entire list of words that make up a widget command
+and parses the words starting with \fIobjv\fR[2].
+The words starting with \fIobjv\fR[2] must have one of the following forms:
+.CS
+\fBmoveto \fIfraction\fR
+\fBscroll \fInumber\fB units\fR
+\fBscroll \fInumber\fB pages\fR
+.CE
+.LP
+Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR
+keywords may be abbreviated.
+If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR
+is returned as result and \fI*fractionPtr\fR is filled in with the
+\fIfraction\fR argument to the command, which must be a proper real
+value.
+If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR
+or \fBTK_SCROLL_PAGES\fR is returned and \fI*stepsPtr\fR is filled
+in with the \fInumber\fR value, which must be a proper integer.
+If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR
+is returned and an error message is left in interpreter
+\fIinterp\fR's result.
+.PP
+\fBTk_GetScrollInfo\fR is identical in function to
+\fBTk_GetScrollInfoObj\fR.  However, \fBTk_GetScrollInfo\fR accepts
+string arguments, making it more appropriate for use with legacy
+widgets.
+.SH KEYWORDS
+parse, scrollbar, scrolling command, xview, yview

doc/GetSelect.3

@@ -0,0 +1,78 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetSelection \- retrieve the contents of a selection
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR)
+.SH ARGUMENTS
+.AS Tk_GetSelProc clientData
+.AP Tcl_Interp *interp in
+Interpreter to use for reporting errors.
+.AP Tk_Window tkwin in
+Window on whose behalf to retrieve the selection (determines
+display from which to retrieve).
+.AP Atom selection in
+The name of the selection to be retrieved.
+.AP Atom target in
+Form in which to retrieve selection.
+.AP Tk_GetSelProc *proc in
+Procedure to invoke to process pieces of the selection as they
+are retrieved.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetSelection\fR retrieves the selection specified by the atom
+\fIselection\fR in the format specified by \fItarget\fR.  The
+selection may actually be retrieved in several pieces; as each piece
+is retrieved, \fIproc\fR is called to process the piece.  \fIProc\fR
+should have arguments and result that match the type
+\fBTk_GetSelProc\fR:
+.PP
+.CS
+typedef int \fBTk_GetSelProc\fR(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        char *\fIportion\fR);
+.CE
+.PP
+The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR
+will be copies of the corresponding arguments to
+\fBTk_GetSelection\fR.  \fIPortion\fR will be a pointer to
+a string containing part or all of the selection.  For large
+selections, \fIproc\fR will be called several times with successive
+portions of the selection.  The X Inter-Client Communication
+Conventions Manual allows a selection to be returned in formats
+other than strings, e.g. as an array of atoms or integers.  If
+this happens, Tk converts the selection back into a string
+before calling \fIproc\fR.  If a selection is returned as an
+array of atoms, Tk converts it to a string containing the atom names
+separated by white space.  For any other format besides string,
+Tk converts a selection to a string containing hexadecimal
+values separated by white space.
+.PP
+\fBTk_GetSelection\fR returns to its caller when the selection has
+been completely retrieved and processed by \fIproc\fR, or when a
+fatal error has occurred (e.g. the selection owner did not respond
+promptly).  \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR;  if
+an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message
+in interpreter \fIinterp\fR's result.  \fIProc\fR should also return either
+\fBTCL_OK\fR or \fBTCL_ERROR\fR.  If \fIproc\fR encounters an error in
+dealing with the selection, it should leave an error message in the
+interpreter result and return \fBTCL_ERROR\fR;  this will abort the
+selection retrieval.
+.SH KEYWORDS
+format, get, selection retrieval

doc/GetUid.3

@@ -0,0 +1,45 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetUid 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetUid, Tk_Uid \- convert from string to unique identifier
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Uid
+\fBTk_GetUid\fR(\fIstring\fR)
+.SH ARGUMENTS
+.AP char *string in
+String for which the corresponding unique identifier is
+desired.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetUid\fR returns the unique identifier corresponding
+to \fIstring\fR.
+Unique identifiers are similar to atoms in Lisp, and are used
+in Tk to speed up comparisons and
+searches.  A unique identifier (type Tk_Uid) is a string pointer
+and may be used anywhere that a variable of type
+.QW "char *"
+could be used.  However, there is guaranteed to be exactly
+one unique identifier for any given string value.  If \fBTk_GetUid\fR
+is called twice, once with string \fIa\fR and once with string
+\fIb\fR, and if \fIa\fR and \fIb\fR have the same string value
+(strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly
+the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)).
+This means that variables of type
+Tk_Uid may be compared directly (x == y) without having to call
+\fBstrcmp\fR.
+In addition, the return value from \fBTk_GetUid\fR will have the
+same string value as its argument (strcmp(Tk_GetUid(a), a) == 0).
+.SH KEYWORDS
+atom, unique identifier

doc/GetVRoot.3

@@ -0,0 +1,46 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetVRootGeometry \- Get location and size of virtual root for window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
+.SH ARGUMENTS
+.AS Tk_Window heightPtr
+.AP Tk_Window tkwin in
+Token for window whose virtual root is to be queried.
+.AP int xPtr out
+Points to word in which to store x-offset of virtual root.
+.AP int yPtr out
+Points to word in which to store y-offset of virtual root.
+.AP "int" widthPtr out
+Points to word in which to store width of virtual root.
+.AP "int" heightPtr out
+Points to word in which to store height of virtual root.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetVRootGeometry\fR returns geometry information about the virtual
+root window associated with \fItkwin\fR.  The
+.QW associated
+virtual root is the one in which \fItkwin\fR's nearest top-level ancestor (or
+\fItkwin\fR itself if it is a top-level window) has
+been reparented by the window manager.  This window is identified by
+a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level
+window by the window manager.
+If \fItkwin\fR is not associated with a virtual root (e.g.
+because the window manager does not use virtual roots) then *\fIxPtr\fR and
+*\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR
+will be set to the dimensions of the screen containing \fItkwin\fR.
+.SH KEYWORDS
+geometry, height, location, virtual root, width, window manager

doc/GetVisual.3

@@ -0,0 +1,100 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetVisual \- translate from string to visual
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Visual *
+\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *colormapPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window in which the visual will be used.
+.AP "const char" *string in
+String that identifies the desired visual.  See below for
+valid formats.
+.AP int *depthPtr out
+Depth of returned visual gets stored here.
+.AP Colormap *colormapPtr out
+If non-NULL then a suitable colormap for visual is found and its
+identifier is stored here.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetVisual\fR takes a string description of a visual and
+finds a suitable X Visual for use in \fItkwin\fR, if there is one.
+It returns a pointer to the X Visual structure for the visual
+and stores the number of bits per pixel for it at \fI*depthPtr\fR.
+If \fIstring\fR is unrecognizable or if no suitable visual could
+be found, then NULL is returned and \fBTk_GetVisual\fR leaves
+an error message in interpreter \fIinterp\fR's result.
+If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR
+also locates an appropriate colormap for use with the result visual
+and stores its X identifier at \fI*colormapPtr\fR.
+.PP
+The \fIstring\fR argument specifies the desired visual in one
+of the following ways:
+.TP 15
+\fIclass depth\fR
+The string consists of a class name followed by an integer depth,
+with any amount of white space (including none) in between.
+\fIclass\fR selects what sort of visual is desired and must be one of
+\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR,
+\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or
+\fBtruecolor\fR, or a unique abbreviation.
+\fIdepth\fR specifies how many bits per pixel are needed for the
+visual.
+If possible, \fBTk_GetVisual\fR will return a visual with this depth;
+if there is no visual of the desired depth then \fBTk_GetVisual\fR
+looks first for a visual with greater depth, then one with less
+depth.
+.TP 15
+\fBdefault\fR
+Use the default visual for \fItkwin\fR's screen.
+.TP 15
+\fIpathName\fR
+Use the visual for the window given by \fIpathName\fR.
+\fIpathName\fR must be the name of a window on the same screen
+as \fItkwin\fR.
+.TP 15
+\fInumber\fR
+Use the visual whose X identifier is \fInumber\fR.
+.TP 15
+\fBbest\fR ?\fIdepth\fR?
+Choose the
+.QW "best possible"
+visual, using the following rules, in decreasing order of priority:
+.RS
+.IP (a)
+a visual that has exactly the desired depth is best, followed
+by a visual with greater depth than requested (but as little extra
+as possible), followed by a visual with less depth than requested
+(but as great a depth as possible);
+.IP (b)
+if no \fIdepth\fR is specified, then the deepest available visual
+is chosen;
+.IP (c)
+\fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR,
+which are better than \fBstaticcolor\fR, which is better than
+\fBstaticgray\fR or \fBgrayscale\fR;
+.IP (d)
+the default visual for the screen is better than any other visual.
+.RE
+.SH CREDITS
+.PP
+The idea for \fBTk_GetVisual\fR, and the first implementation, came
+from Paul Mackerras.
+.SH KEYWORDS
+colormap, screen, visual

doc/Grab.3

@@ -0,0 +1,58 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.TH Tk_Grab 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_Grab, Tk_Ungrab \- manipulate grab state in an application
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR)
+.sp
+void
+\fBTk_Ungrab\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting
+.AP Tk_Window tkwin in
+Window on whose behalf the pointer is to be grabbed or released
+.AP int grabGlobal in
+Boolean indicating whether the grab is global or application local
+.BE
+.SH DESCRIPTION
+.PP
+These functions are used to set or release a global or
+application local grab.  When a grab is set on a particular window
+in a Tk application, mouse and keyboard events can only be received by
+that window and its descendants.  Mouse and keyboard events for
+windows outside the tree rooted at \fItkwin\fR will be redirected to
+\fItkwin\fR.  If the grab is global, then all mouse and keyboard
+events for windows outside the tree rooted at \fItkwin\fR (even those
+intended for windows in other applications) will be redirected to
+\fItkwin\fR.  If the grab is application local, only mouse and
+keyboard events intended for a windows within the same application
+(but outside the tree rooted at \fItkwin\fR) will be redirected.
+.PP
+\fBTk_Grab\fR sets a grab on a particular window.  \fITkwin\fR
+specifies the window on whose behalf the pointer is to be grabbed.
+\fIGrabGlobal\fR indicates whether the grab should be global or
+application local; if it is non-zero, it means the grab should be
+global.  Normally, \fBTk_Grab\fR returns \fBTCL_OK\fR; if an error occurs
+and the grab cannot be set, \fBTCL_ERROR\fR is returned and an error message
+is left if \fIinterp\fR's result.  Once this call completes
+successfully, no window outside the tree rooted at \fItkwin\fR will
+receive pointer- or keyboard-related events until the next call to
+Tk_Ungrab.  If a previous grab was in effect within the application,
+then it is replaced with a new one.
+.PP
+\fBTk_Ungrab\fR releases a grab on the mouse pointer and keyboard, if
+there is one set on the window given by \fItkwin\fR.  Once a grab is
+released, pointer and keyboard events will start being delivered to
+other windows again.
+.SH KEYWORDS
+grab, window

doc/HWNDToWindow.3

@@ -0,0 +1,26 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_HWNDToWindow \- Find Tk's window information for a Windows window
+.SH SYNOPSIS
+.nf
+\fB#include <tkPlatDecls.h>\fR
+.sp
+Tk_Window
+\fBTk_HWNDToWindow\fR(\fIhwnd\fR)
+.SH ARGUMENTS
+.AP HWND hwnd in
+Windows handle for the window.
+.BE
+.SH DESCRIPTION
+.PP
+Given a Windows HWND window identifier, this procedure returns the
+corresponding Tk_Window handle. If there is no Tk_Window corresponding
+to \fIhwnd\fR then NULL is returned.
+.SH KEYWORDS
+Windows window id

doc/HandleEvent.3

@@ -0,0 +1,46 @@
+'\"
+'\" Copyright (c) 1990-1992 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_HandleEvent \- invoke event handlers for window system events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_HandleEvent\fR(\fIeventPtr\fR)
+.SH ARGUMENTS
+.AS XEvent *eventPtr
+.AP XEvent *eventPtr in
+Pointer to X event to dispatch to relevant handler(s). It is important
+that all unused fields of the structure be set to zero.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_HandleEvent\fR is a lower-level procedure that deals with window
+events.  It is called by \fBTcl_ServiceEvent\fR (and indirectly by
+\fBTk_DoOneEvent\fR), and in a few other cases within Tk.
+It makes callbacks to any window event
+handlers (created by calls to \fBTk_CreateEventHandler\fR)
+that match \fIeventPtr\fR and then returns.  In some cases
+it may be useful for an application to bypass the Tk event
+queue and call \fBTk_HandleEvent\fR directly instead of
+calling \fBTcl_QueueEvent\fR followed by
+\fBTcl_ServiceEvent\fR.
+.PP
+This procedure may be invoked recursively.  For example,
+it is possible to invoke \fBTk_HandleEvent\fR recursively
+from a handler called by \fBTk_HandleEvent\fR.  This sort
+of operation is useful in some modal situations, such
+as when a
+notifier has been popped up and an application wishes to
+wait for the user to click a button in the notifier before
+doing anything else.
+.SH KEYWORDS
+callback, event, handler, window

doc/IdToWindow.3

@@ -0,0 +1,32 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_IdToWindow \- Find Tk's window information for an X window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_IdToWindow\fR(\fIdisplay, window\fR)
+.SH ARGUMENTS
+.AS Tk_Window display
+.AP Display *display in
+X display containing the window.
+.AP Window window in
+X id for window.
+.BE
+.SH DESCRIPTION
+.PP
+Given an X window identifier and the X display it corresponds to,
+this procedure returns the corresponding Tk_Window handle.
+If there is no Tk_Window corresponding to \fIwindow\fR then
+NULL is returned.
+.SH KEYWORDS
+X window id

doc/ImgChanged.3

@@ -0,0 +1,64 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ImageChanged \- notify widgets that image needs to be redrawn
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_ImageChanged\fR(\fIimageMaster, x, y, width, height, imageWidth, imageHeight\fR)
+.SH ARGUMENTS
+.AS Tk_ImageMaster imageHeight
+.AP Tk_ImageMaster imageMaster in
+Token for image, which was passed to image's \fIcreateProc\fR when
+the image was created.
+.AP int x in
+X-coordinate of upper-left corner of region that needs redisplay (measured
+from upper-left corner of image).
+.AP int y in
+Y-coordinate of upper-left corner of region that needs redisplay (measured
+from upper-left corner of image).
+.AP "int" width in
+Width of region that needs to be redrawn, in pixels.
+.AP "int" height in
+Height of region that needs to be redrawn, in pixels.
+.AP "int" imageWidth in
+Current width of image, in pixels.
+.AP "int" imageHeight in
+Current height of image, in pixels.
+.BE
+.SH DESCRIPTION
+.PP
+An image manager calls \fBTk_ImageChanged\fR for an image
+whenever anything happens that requires the image to be redrawn.
+As a result of calling \fBTk_ImageChanged\fR, any widgets using
+the image are notified so that they can redisplay themselves
+appropriately.
+The \fIimageMaster\fR argument identifies the image, and
+\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
+specify a rectangular region within the image that needs to
+be redrawn.
+\fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size.
+.PP
+An image manager should call \fBTk_ImageChanged\fR during
+its \fIcreateProc\fR to specify the image's initial size and to
+force redisplay if there are existing instances for the image.
+If any of the pixel values in the image should change later on,
+\fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR,
+\fIwidth\fR, and \fIheight\fR values that cover all the pixels
+that changed.
+If the size of the image should change, then \fBTk_ImageChanged\fR
+must be called to indicate the new size, even if no pixels
+need to be redisplayed.
+.SH "SEE ALSO"
+Tk_CreateImageType
+.SH KEYWORDS
+images, redisplay, image size changes

doc/Inactive.3

@@ -0,0 +1,34 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+long
+\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR
+.sp
+\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR
+.SH ARGUMENTS
+.AS Display *display
+.AP Display *display in
+The display on which the user inactivity timer is to be queried or
+reset.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_GetUserInactiveTime\fR returns the number of milliseconds that
+have passed since the last user interaction (usually via keyboard or
+mouse) with the respective display. On systems and displays that do not
+support querying the user inactiviy time, \fB\-1\fR is returned.
+\fBTk_GetUserInactiveTime\fR resets the user inactivity timer of the
+given display to zero.  On windowing systems that do not support
+multiple displays \fIdisplay\fR can be passed as \fBNULL\fR.
+.SH KEYWORDS
+idle, inactive

doc/InternAtom.3

@@ -0,0 +1,55 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Atom
+\fBTk_InternAtom(\fItkwin, name\fR)
+.sp
+const char *
+\fBTk_GetAtomName(\fItkwin, atom\fR)
+.SH ARGUMENTS
+.AS Tk_Window parent
+.AP Tk_Window tkwin in
+Token for window.  Used to map atom or name relative to a particular display.
+.AP "const char" *name in
+String name for which atom is desired.
+.AP Atom atom in
+Atom for which corresponding string name is desired.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures are similar to the Xlib procedures
+\fBXInternAtom\fR and \fBXGetAtomName\fR.  \fBTk_InternAtom\fR
+returns the atom identifier associated with string given by
+\fIname\fR;  the atom identifier is only valid for the display
+associated with \fItkwin\fR.
+\fBTk_GetAtomName\fR returns the string associated
+with \fIatom\fR on \fItkwin\fR's display.  The string returned
+by \fBTk_GetAtomName\fR is in Tk's storage:  the caller need
+not free this space when finished with the string, and the caller
+should not modify the contents of the returned string.
+If there is no atom \fIatom\fR on \fItkwin\fR's display,
+then \fBTk_GetAtomName\fR returns the string
+.QW "?bad atom?" .
+.PP
+Tk caches
+the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR
+so that future calls
+for the same information can be serviced from the cache without
+contacting the server.  Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR
+are generally much faster than their Xlib counterparts, and they
+should be used in place of the Xlib procedures.
+.SH KEYWORDS
+atom, cache, display

doc/MainLoop.3

@@ -0,0 +1,28 @@
+'\"
+'\" Copyright (c) 1990-1992 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MainLoop \- loop for events until all windows are deleted
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_MainLoop\fR()
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_MainLoop\fR is a procedure that loops repeatedly calling
+\fBTcl_DoOneEvent\fR.  It returns only when there are no applications
+left in this process (i.e. no main windows exist anymore).  Most
+windowing applications will call \fBTk_MainLoop\fR after
+initialization; the main execution of the application will consist
+entirely of callbacks invoked via \fBTcl_DoOneEvent\fR.
+.SH KEYWORDS
+application, event, main loop

doc/MainWin.3

@@ -0,0 +1,40 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window information
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_MainWindow\fR(\fIinterp\fR)
+.sp
+int
+\fBTk_GetNumMainWindows\fR()
+.SH ARGUMENTS
+.AS Tcl_Interp *pathName
+.AP Tcl_Interp *interp in/out
+Interpreter associated with the application.
+.BE
+.SH DESCRIPTION
+.PP
+A main window is a special kind of toplevel window used as the
+outermost window in an application.
+.PP
+If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR
+returns the application's main window. If there is no Tk application
+associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and
+leaves an error message in interpreter \fIinterp\fR's result.
+.PP
+\fBTk_GetNumMainWindows\fR returns a count of the number of main
+windows currently open in the current thread.
+.SH KEYWORDS
+application, main window

doc/MaintGeom.3

@@ -0,0 +1,99 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_MaintainGeometry\fR(\fIslave, master, x, y, width, height\fR)
+.sp
+\fBTk_UnmaintainGeometry\fR(\fIslave, master\fR)
+.SH ARGUMENTS
+.AS Tk_Window master
+.AP Tk_Window slave in
+Window whose geometry is to be controlled.
+.AP Tk_Window master in
+Window relative to which \fIslave\fR's geometry will be controlled.
+.AP int x in
+Desired x-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels
+from the inside of \fImaster\fR's left border to the outside of
+\fIslave\fR's left border.
+.AP int y in
+Desired y-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels
+from the inside of \fImaster\fR's top border to the outside of
+\fIslave\fR's top border.
+.AP int width in
+Desired width for \fIslave\fR, in pixels.
+.AP int height in
+Desired height for \fIslave\fR, in pixels.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it
+easier for geometry managers to deal with slaves whose masters are not
+their parents.
+Three problems arise if the master for a slave is not its parent:
+.IP [1]
+The x- and y-position of the slave must be translated from the
+coordinate system of the master to that of the parent before
+positioning the slave.
+.IP [2]
+If the master window, or any of its ancestors up to the slave's
+parent, is moved, then the slave must be repositioned within its
+parent in order to maintain the correct position relative to the
+master.
+.IP [3]
+If the master or one of its ancestors is mapped or unmapped, then
+the slave must be mapped or unmapped to correspond.
+.LP
+None of these problems is an issue if the parent and master are
+the same.  For example, if the master or one of its ancestors
+is unmapped, the slave is automatically removed by the screen
+by X.
+.PP
+\fBTk_MaintainGeometry\fR deals with these problems for slaves
+whose masters are not their parents, as well as handling the simpler
+case of slaves whose masters are their parents.
+\fBTk_MaintainGeometry\fR is typically called by a window manager
+once it has decided where a slave should be positioned relative
+to its master.
+\fBTk_MaintainGeometry\fR translates the coordinates to the
+coordinate system of \fIslave\fR's parent and then moves and
+resizes the slave appropriately.
+Furthermore, it remembers the desired position and creates event
+handlers to monitor the master and all of its ancestors up
+to (but not including) the slave's parent.
+If any of these windows is moved, mapped, or unmapped,
+the slave will be adjusted so that it is mapped only when the
+master is mapped and its geometry relative to the master
+remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and
+\fIheight\fR.
+.PP
+When a window manager relinquishes control over a window, or
+if it decides that it does not want the window to appear on the
+screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR.
+\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any
+previous calls to \fBTk_MaintainGeometry\fR for the
+\fImaster\fR\-\fIslave\fR pair, so that the slave's
+geometry and mapped state are no longer maintained
+automatically.
+\fBTk_UnmaintainGeometry\fR need not be called by a geometry
+manager if the slave, the master, or any of the master's ancestors
+is destroyed:  Tk will call it automatically.
+.PP
+If \fBTk_MaintainGeometry\fR is called repeatedly for the same
+\fImaster\fR\-\fIslave\fR pair, the information from the most
+recent call supersedes any older information.
+If \fBTk_UnmaintainGeometry\fR is called for a \fImaster\fR\-\fIslave\fR
+pair that is is not currently managed, the call has no effect.
+.SH KEYWORDS
+geometry manager, map, master, parent, position, slave, unmap

doc/ManageGeom.3

@@ -0,0 +1,90 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ManageGeometry \- arrange to handle geometry requests for a window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR)
+.SH ARGUMENTS
+.AS Tk_GeometryProc clientData
+.AP Tk_Window tkwin in
+Token for window to be managed.
+.AP "const Tk_GeomMgr" *mgrPtr in
+Pointer to data structure containing information about the
+geometry manager, or NULL to indicate that \fItkwin\fR's geometry
+should not be managed anymore.
+The data structure pointed to by \fImgrPtr\fR must be static:
+Tk keeps a reference to it as long as the window is managed.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to geometry manager callbacks.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_ManageGeometry\fR arranges for a particular geometry manager,
+described by the \fImgrPtr\fR argument, to control the geometry
+of a particular slave window, given by \fItkwin\fR.
+If \fItkwin\fR was previously managed by some other geometry manager,
+the previous manager loses control in favor of the new one.
+If \fImgrPtr\fR is NULL, geometry management is cancelled for
+\fItkwin\fR.
+.PP
+The structure pointed to by \fImgrPtr\fR contains information about
+the geometry manager:
+.CS
+typedef struct {
+    const char *\fIname\fR;
+    Tk_GeomRequestProc *\fIrequestProc\fR;
+    Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR;
+} \fBTk_GeomMgr\fR;
+.CE
+The \fIname\fR field is the textual name for the geometry manager,
+such as \fBpack\fR or \fBplace\fR;  this value will be returned
+by the command \fBwinfo manager\fR.
+.PP
+\fIrequestProc\fR is a procedure in the geometry manager that
+will be invoked whenever \fBTk_GeometryRequest\fR is called by the
+slave to change its desired geometry.
+\fIrequestProc\fR should have arguments and results that match the
+type \fBTk_GeomRequestProc\fR:
+.CS
+typedef void \fBTk_GeomRequestProc\fR(
+        ClientData \fIclientData\fR,
+        Tk_Window \fItkwin\fR);
+.CE
+The parameters to \fIrequestProc\fR will be identical to the
+corresponding parameters passed to \fBTk_ManageGeometry\fR.
+\fIclientData\fR usually points to a data
+structure containing application-specific information about
+how to manage \fItkwin\fR's geometry.
+.PP
+The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another
+procedure in the geometry manager.
+Tk will invoke \fIlostSlaveProc\fR if some other manager
+calls \fBTk_ManageGeometry\fR to claim
+\fItkwin\fR away from the current geometry manager.
+\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is
+called with a NULL value for \fImgrPtr\fR (presumably the current
+geometry manager has made this call, so it already knows that the
+window is no longer managed), nor is it called if \fImgrPtr\fR
+is the same as the window's current geometry manager.
+\fIlostSlaveProc\fR should have
+arguments and results that match the following prototype:
+.CS
+typedef void \fBTk_GeomLostSlaveProc\fR(
+        ClientData \fIclientData\fR,
+        Tk_Window \fItkwin\fR);
+.CE
+The parameters to \fIlostSlaveProc\fR will be identical to the
+corresponding parameters passed to \fBTk_ManageGeometry\fR.
+.SH KEYWORDS
+callback, geometry, managed, request, unmanaged

doc/MapWindow.3

@@ -0,0 +1,49 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_MapWindow\fR(\fItkwin\fR)
+.sp
+\fBTk_UnmapWindow\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS Tk_Window parent
+.AP Tk_Window tkwin in
+Token for window.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures may be used to map and unmap windows
+managed by Tk.  \fBTk_MapWindow\fR maps the window given
+by \fItkwin\fR, and also creates an X window corresponding
+to \fItkwin\fR if it does not already exist.  See the
+\fBTk_CreateWindow\fR manual entry for information on
+deferred window creation.
+\fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window
+from the screen.
+.PP
+If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was
+used to create a child window), then event handlers interested in map
+and unmap events are invoked immediately.  If \fItkwin\fR is not an
+internal window, then the event handlers will be invoked later, after
+X has seen the request and returned an event for it.
+.PP
+These procedures should be used in place of the X procedures
+\fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update
+Tk's local data structure for \fItkwin\fR.  Applications
+using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR
+directly.
+.SH KEYWORDS
+map, unmap, window

doc/MeasureChar.3

@@ -0,0 +1,127 @@
+'\"
+'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
+.sp
+int
+\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
+.sp
+\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
+.sp
+\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
+.sp
+.SH ARGUMENTS
+.AS "const char" firstChar
+.AP Tk_Font tkfont in
+Token for font in which text is to be drawn or measured.  Must have been
+returned by a previous call to \fBTk_GetFont\fR.
+.AP "const char" *string in
+Text to be measured or displayed.  Need not be null terminated.  Any
+non-printing meta-characters in the string (such as tabs, newlines, and
+other control characters) will be measured or displayed in a
+platform-dependent manner.
+.AP int numBytes in
+The maximum number of bytes to consider when measuring or drawing
+\fIstring\fR.  Must be greater than or equal to 0.
+.AP int maxPixels in
+If \fImaxPixels\fR is >= 0, it specifies the longest permissible
+line length in pixels.  Characters from \fIstring\fR are processed only
+until this many pixels have been covered.  If \fImaxPixels\fR is < 0, then
+the line length is unbounded and the \fIflags\fR argument is ignored.
+.AP int flags in
+Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character
+as long as any part of it fits in the length given by \fImaxPixels\fR;
+otherwise, a character must fit completely to be considered.
+\fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible.  If
+\fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no
+characters could fit in the length given by \fImaxPixels\fR.  If
+\fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if
+not even one word fits on the line, return the first few letters of the
+word that did fit; if not even one letter of the word fit, then the first
+letter will still be returned.
+.AP int *lengthPtr out
+Filled with the number of pixels occupied by the number of characters
+returned as the result of \fBTk_MeasureChars\fR.
+.AP Display *display in
+Display on which to draw.
+.AP Drawable drawable in
+Window or pixmap in which to draw.
+.AP GC gc in
+Graphics context for drawing characters.  The font selected into this GC
+must be the same as the \fItkfont\fR.
+.AP int "x, y" in
+Coordinates at which to place the left edge of the baseline when displaying
+\fIstring\fR.
+.AP int firstByte in
+The index of the first byte of the first character to underline in the
+\fIstring\fR.  Underlining begins at the left edge of this character.
+.AP int lastByte in
+The index of the first byte of the last character up to which the
+underline will be drawn.  The character specified by \fIlastByte\fR
+will not itself be underlined.
+.BE
+.SH DESCRIPTION
+.PP
+These routines are for measuring and displaying simple single-font,
+single-line strings.  To measure and display single-font, multi-line,
+justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR.
+There is no programming interface in the core of Tk that supports
+multi-font, multi-line text; support for that behavior must be built on
+top of simpler layers.
+Note that the interfaces described here are
+byte-oriented not character-oriented, so index values coming from Tcl
+scripts need to be converted to byte offsets using the
+\fBTcl_UtfAtIndex\fR and related routines.
+.PP
+A glyph is the displayable picture of a letter, number, or some other
+symbol.  Not all character codes in a given font have a glyph.
+Characters such as tabs, newlines/returns, and control characters that
+have no glyph are measured and displayed by these procedures in a
+platform-dependent manner; under X, they are replaced with backslashed
+escape sequences, while under Windows and Macintosh hollow or solid boxes
+may be substituted.  Refer to the documentation for
+\fBTk_ComputeTextLayout\fR for a programming interface that supports the
+platform-independent expansion of tab characters into columns and
+newlines/returns into multi-line text.
+.PP
+\fBTk_MeasureChars\fR is used both to compute the length of a given
+string and to compute how many characters from a string fit in a given
+amount of space.  The return value is the number of bytes from
+\fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to
+the conditions described by \fIflags\fR.  If all characters fit, the return
+value will be \fInumBytes\fR.  \fI*lengthPtr\fR is filled with the computed
+width, in pixels, of the portion of the string that was measured.  For
+example, if the return value is 5, then \fI*lengthPtr\fR is filled with the
+distance between the left edge of \fIstring\fR[0] and the right edge of
+\fIstring\fR[4].
+.PP
+\fBTk_TextWidth\fR is a wrapper function that provides a simpler interface
+to the \fBTk_MeasureChars\fR function.  The return value is how much
+space in pixels the given \fIstring\fR needs.
+.PP
+\fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the
+given \fIdrawable\fR.
+.PP
+\fBTk_UnderlineChars\fR underlines the given range of characters in the
+given \fIstring\fR.  It does not draw the characters (which are assumed to
+have been displayed previously by \fBTk_DrawChars\fR); it just draws the
+underline.  This procedure is used to underline a few characters without
+having to construct an underlined font.  To produce natively underlined
+text, the appropriate underlined font should be constructed and used.
+.SH "SEE ALSO"
+font(n), FontId(3)
+.SH KEYWORDS
+font, measurement

doc/MoveToplev.3

@@ -0,0 +1,51 @@
+'\"
+'\" Copyright (c) 1990-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_MoveToplevelWindow \- Adjust the position of a top-level window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR
+.SH ARGUMENTS
+.AS Tk_Window tkwin
+.AP Tk_Window tkwin in
+Token for top-level window to move.
+.AP int x in
+New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the
+top-left pixel of the decorative border supplied for \fItkwin\fR by the
+window manager, if there is one.
+.AP int y in
+New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the
+top-left pixel of the decorative border supplied for \fItkwin\fR by the
+window manager, if there is one.
+.BE
+.SH DESCRIPTION
+.PP
+In general, a window should never set its own position;  this should be
+done only by the geometry manger that is responsible for the window.
+For top-level windows the window manager is effectively the geometry
+manager;  Tk provides interface code between the application and the
+window manager to convey the application's desires to the geometry
+manager.  The desired size for a top-level window is conveyed using
+the usual \fBTk_GeometryRequest\fR mechanism.  The procedure
+\fBTk_MoveToplevelWindow\fR may be used by an application to request
+a particular position for a top-level window;  this procedure is
+similar in function to the \fBwm geometry\fR Tcl command except that
+negative offsets cannot be specified.  It is invoked by widgets such as
+menus that want to appear at a particular place on the screen.
+.PP
+When \fBTk_MoveToplevelWindow\fR is called it does not immediately
+pass on the new desired location to the window manager;  it defers
+this action until all other outstanding work has been completed,
+using the \fBTk_DoWhenIdle\fR mechanism.
+.SH KEYWORDS
+position, top-level window, window manager

doc/Name.3

@@ -0,0 +1,86 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_Name 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Uid
+\fBTk_Name\fR(\fItkwin\fR)
+.sp
+char *
+\fBTk_PathName\fR(\fItkwin\fR)
+.sp
+Tk_Window
+\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *pathName
+.AP Tk_Window tkwin in
+Token for window.
+.AP Tcl_Interp *interp out
+Interpreter to use for error reporting.
+.AP "const char" *pathName in
+Character string containing path name of window.
+.BE
+.SH DESCRIPTION
+.PP
+Each window managed by Tk has two names, a short name that identifies
+a window among children of the same parent, and a path name that
+identifies the window uniquely among all the windows belonging to the
+same main window.  The path name is used more often in Tk than the
+short name;  many commands, like \fBbind\fR, expect path names as
+arguments.
+.PP
+The \fBTk_Name\fR macro returns a window's
+short name, which is the same as the \fIname\fR argument
+passed to \fBTk_CreateWindow\fR when
+the window was created.  The value is returned
+as a Tk_Uid, which may be used just like a string pointer but also has
+the properties of a unique identifier (see the manual entry for
+\fBTk_GetUid\fR for details).
+.PP
+The \fBTk_PathName\fR macro returns a hierarchical name for \fItkwin\fR.
+Path names have a structure similar to file names in Unix but with
+dots between elements instead of slashes:  the main window for
+an application has the path name
+.QW . ;
+its children have names like
+.QW .a
+and
+.QW .b ;
+their children have names like
+.QW .a.aa
+and
+.QW .b.bb ;
+and so on.  A window is considered to be a child of
+another window for naming purposes if the second window was named
+as the first window's \fIparent\fR when the first window was created.
+This is not always the same as the X window hierarchy.  For
+example, a pop-up
+is created as a child of the root window, but its logical parent will
+usually be a window within the application.
+.PP
+The procedure \fBTk_NameToWindow\fR returns the token for a window
+given its path name (the \fIpathName\fR argument) and another window
+belonging to the same main window (\fItkwin\fR).  It normally
+returns a token for the named window, but if no such window exists
+\fBTk_NameToWindow\fR leaves an error message in interpreter
+\fIinterp\fR's result
+and returns NULL.  The \fItkwin\fR argument to \fBTk_NameToWindow\fR
+is needed because path names are only unique within a single
+application hierarchy.  If, for example, a single process has opened
+two main windows, each will have a separate naming hierarchy and the
+same path name might appear in each of the hierarchies.  Normally
+\fItkwin\fR is the main window of the desired hierarchy, but this
+need not be the case:  any window in the desired hierarchy may be used.
+.SH KEYWORDS
+name, path name, token, window

doc/NameOfImg.3

@@ -0,0 +1,30 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_NameOfImage \- Return name of image.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+const char *
+\fBTk_NameOfImage\fR(\fItypePtr\fR)
+.SH ARGUMENTS
+.AS Tk_ImageMaster *masterPtr
+.AP Tk_ImageMaster *masterPtr in
+Token for image, which was passed to image manager's \fIcreateProc\fR when
+the image was created.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure is invoked by image managers to find out the name
+of an image.  Given the token for the image, it returns the
+string name for the image.
+.SH KEYWORDS
+image manager, image name

doc/OwnSelect.3

@@ -0,0 +1,49 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_OwnSelection \- make a window the owner of the primary selection
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR)
+.SH ARGUMENTS
+.AS Tk_LostSelProc clientData
+.AP Tk_Window tkwin in
+Window that is to become new selection owner.
+.AP Atom selection in
+The name of the selection to be owned, such as XA_PRIMARY.
+.AP Tk_LostSelProc *proc in
+Procedure to invoke when \fItkwin\fR loses selection ownership later.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the
+new owner of the selection specified by the atom
+\fIselection\fR.  After this call completes, future requests
+for the selection will be directed to handlers created for
+\fItkwin\fR using \fBTk_CreateSelHandler\fR.  When \fItkwin\fR
+eventually loses the selection ownership, \fIproc\fR will be
+invoked so that the window can clean itself up (e.g. by
+unhighlighting the selection).  \fIProc\fR should have arguments and
+result that match the type \fBTk_LostSelProc\fR:
+.CS
+typedef void \fBTk_LostSelProc\fR(
+        ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the
+\fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is
+usually a pointer to a data structure containing application-specific
+information about \fItkwin\fR.
+.SH KEYWORDS
+own, selection owner

doc/ParseArgv.3

@@ -0,0 +1,360 @@
+'\"
+'\" Copyright (c) 1990-1992 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ParseArgv \- process command-line options
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR)
+.SH ARGUMENTS
+.AS Tk_ArgvInfo *argTable
+.AP Tcl_Interp *interp in
+Interpreter to use for returning error messages.
+.AP Tk_Window tkwin in
+Window to use when arguments specify Tk options.  If NULL, then
+no Tk options will be processed.
+.AP int argcPtr in/out
+Pointer to number of arguments in argv;  gets modified to hold
+number of unprocessed arguments that remain after the call.
+.AP "const char" **argv in/out
+Command line arguments passed to main program.  Modified to
+hold unprocessed arguments that remain after the call.
+.AP Tk_ArgvInfo *argTable in
+Array of argument descriptors, terminated by element with
+type \fBTK_ARGV_END\fR.
+.AP int flags in
+If non-zero, then it specifies one or more flags that control the
+parsing of arguments.  Different flags may be OR'ed together.
+The flags currently defined are \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR,
+\fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and
+\fBTK_ARGV_NO_DEFAULTS\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_ParseArgv\fR processes an array of command-line arguments according
+to a table describing the kinds of arguments that are expected.
+Each of the arguments in \fIargv\fR is processed in turn:  if it matches
+one of the entries in \fIargTable\fR, the argument is processed
+according to that entry and discarded.  The arguments that do not
+match anything in \fIargTable\fR are copied down to the beginning
+of \fIargv\fR (retaining their original order) and returned to
+the caller.  At the end of the call
+\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of
+arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR
+will hold the value NULL.  Normally, \fBTk_ParseArgv\fR
+assumes that \fIargv[0]\fR is a command name, so it is treated like
+an argument that does not match \fIargTable\fR and returned to the
+caller;  however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR bit is set in
+\fIflags\fR then \fIargv[0]\fR will be processed just like the other
+elements of \fIargv\fR.
+.PP
+\fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR.  If an error
+occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and
+\fBTk_ParseArgv\fR will leave an error message in the result of
+interpreter \fIinterp\fR in the standard Tcl fashion.  In
+the event of an error return, \fI*argvPtr\fR will not have been
+modified, but \fIargv\fR could have been partially modified.  The
+possible causes of errors are explained below.
+.PP
+The \fIargTable\fR array specifies the kinds of arguments that are
+expected;  each of its entries has the following structure:
+.CS
+typedef struct {
+    const char *\fIkey\fR;
+    int \fItype\fR;
+    char *\fIsrc\fR;
+    char *\fIdst\fR;
+    const char *\fIhelp\fR;
+} \fBTk_ArgvInfo\fR;
+.CE
+The \fIkey\fR field is a string such as
+.QW \-display
+or
+.QW \-bg
+that is compared with the values in \fIargv\fR.  \fIType\fR
+indicates how to process an argument that matches \fIkey\fR
+(more on this below).  \fISrc\fR and \fIdst\fR are additional
+values used in processing the argument.  Their exact usage
+depends on \fItype\fR, but typically \fIsrc\fR indicates
+a value and \fIdst\fR indicates where to store the
+value.  The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR
+are placeholders:  the actual types may be different.  Lastly,
+\fIhelp\fR is a string giving a brief description
+of this option;  this string is printed when users ask for help
+about command-line options.
+.PP
+When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR
+compares the argument to each of the \fIkey\fR's in \fIargTable\fR.
+\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches
+the argument exactly, if such a specifier exists.  Otherwise
+\fBTk_ParseArgv\fR selects a specifier for which the argument
+is a unique abbreviation.  If the argument is a unique abbreviation
+for more than one specifier, then an error is returned.  If there
+is no matching entry in \fIargTable\fR, then the argument is
+skipped and returned to the caller.
+.PP
+Once a matching argument specifier is found, \fBTk_ParseArgv\fR
+processes the argument according to the \fItype\fR field of the
+specifier.  The argument that matched \fIkey\fR is called
+.QW "the matching argument"
+in the descriptions below.  As part of the processing,
+\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
+after the matching argument, which is called
+.QW "the following argument" .
+The legal values for \fItype\fR, and the processing
+that they cause, are as follows:
+.TP
+\fBTK_ARGV_END\fR
+Marks the end of the table.  The last entry in \fIargTable\fR
+must have this type;  all of its other fields are ignored and it
+will never match any arguments.
+.TP
+\fBTK_ARGV_CONSTANT\fR
+\fISrc\fR is treated as an integer and \fIdst\fR is treated
+as a pointer to an integer.  \fISrc\fR is stored at \fI*dst\fR.
+The matching argument is discarded.
+.TP
+\fBTK_ARGV_INT\fR
+The following argument must contain an
+integer string in the format accepted by \fBstrtol\fR (e.g.
+.QW 0
+and
+.QW 0x
+prefixes may be used to specify octal or hexadecimal
+numbers, respectively).  \fIDst\fR is treated as a pointer to an
+integer;  the following argument is converted to an integer value
+and stored at \fI*dst\fR.  \fISrc\fR is ignored.  The matching
+and following arguments are discarded from \fIargv\fR.
+.TP
+\fBTK_ARGV_FLOAT\fR
+The following argument must contain a floating-point number in
+the format accepted by \fBstrtol\fR.
+\fIDst\fR is treated as the address of a double-precision
+floating point value;  the following argument is converted to a
+double-precision value and stored at \fI*dst\fR.  The matching
+and following arguments are discarded from \fIargv\fR.
+.TP
+\fBTK_ARGV_STRING\fR
+In this form, \fIdst\fR is treated as a pointer to a (char *);
+\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following
+argument, and discards the matching and following arguments from
+\fIargv\fR.  \fISrc\fR is ignored.
+.TP
+\fBTK_ARGV_UID\fR
+This form is similar to \fBTK_ARGV_STRING\fR, except that the argument
+is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
+\fIDst\fR is treated as a pointer to a
+Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
+corresponding to the following
+argument, and discards the matching and following arguments from
+\fIargv\fR.  \fISrc\fR is ignored.
+.TP
+\fBTK_ARGV_CONST_OPTION\fR
+This form causes a Tk option to be set (as if the \fBoption\fR
+command had been invoked).  The \fIsrc\fR field is treated as a
+pointer to a string giving the value of an option, and \fIdst\fR
+is treated as a pointer to the name of the option.  The matching
+argument is discarded.  If \fItkwin\fR is NULL, then argument
+specifiers of this type are ignored (as if they did not exist).
+.TP
+\fBTK_ARGV_OPTION_VALUE\fR
+This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the
+value of the option is taken from the following argument instead
+of from \fIsrc\fR.  \fIDst\fR is used as the name of the option.
+\fISrc\fR is ignored.  The matching and following arguments
+are discarded.  If \fItkwin\fR is NULL, then argument
+specifiers of this type are ignored (as if they did not exist).
+.TP
+\fBTK_ARGV_OPTION_NAME_VALUE\fR
+In this case the following argument is taken as the name of a Tk
+option and the argument after that is taken as the value for that
+option.  Both \fIsrc\fR and \fIdst\fR are ignored.  All three
+arguments are discarded from \fIargv\fR.  If \fItkwin\fR is NULL,
+then argument
+specifiers of this type are ignored (as if they did not exist).
+.TP
+\fBTK_ARGV_HELP\fR
+When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
+\fIhelp\fR fields of \fIargTable\fR to format a message describing
+all the valid arguments.  The message is placed in interpreter
+\fIinterp\fR's result
+and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR.  When this happens, the
+caller normally prints the help message and aborts.  If the \fIkey\fR
+field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will
+never match any arguments;  in this case the specifier simply provides
+extra documentation, which will be included when some other
+\fBTK_ARGV_HELP\fR entry causes help information to be returned.
+.TP
+\fBTK_ARGV_REST\fR
+This option is used by programs or commands that allow the last
+several of their options to be the name and/or options for some
+other program.  If a \fBTK_ARGV_REST\fR argument is found, then
+\fBTk_ParseArgv\fR does not process any
+of the remaining arguments;  it returns them all at
+the beginning of \fIargv\fR (along with any other unprocessed arguments).
+In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
+integer value, and stores at \fI*dst\fR the index of the first of the
+\fBTK_ARGV_REST\fR options in the returned \fIargv\fR.  This allows the
+program to distinguish the \fBTK_ARGV_REST\fR options from other
+unprocessed options that preceded the \fBTK_ARGV_REST\fR.
+.TP
+\fBTK_ARGV_FUNC\fR
+For this kind of argument, \fIsrc\fR is treated as the address of
+a procedure, which is invoked to process the following argument.
+The procedure should have the following structure:
+.RS
+.CS
+int
+\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR)
+    char *\fIdst\fR;
+    char *\fIkey\fR;
+    char *\fInextArg\fR;
+{
+}
+.CE
+The \fIdst\fR and \fIkey\fR parameters will contain the
+corresponding fields from the \fIargTable\fR entry, and
+\fInextArg\fR will point to the following argument from \fIargv\fR
+(or NULL if there are not any more arguments left in \fIargv\fR).
+If \fIfunc\fR uses \fInextArg\fR (so that
+\fBTk_ParseArgv\fR should discard it), then it should return 1.  Otherwise it
+should return 0 and \fBTkParseArgv\fR will process the following
+argument in the normal fashion.  In either event the matching argument
+is discarded.
+.RE
+.TP
+\fBTK_ARGV_GENFUNC\fR
+This form provides a more general procedural escape.  It treats
+\fIsrc\fR as the address of a procedure, and passes that procedure
+all of the remaining arguments.  The procedure should have the following
+form:
+.RS
+.CS
+int
+\fIgenfunc\fR(dst, interp, key, argc, argv)
+    char *\fIdst\fR;
+    Tcl_Interp *\fIinterp\fR;
+    char *\fIkey\fR;
+    int \fIargc\fR;
+    char **\fIargv\fR;
+{
+}
+.CE
+The \fIdst\fR and \fIkey\fR parameters will contain the
+corresponding fields from the \fIargTable\fR entry.  \fIInterp\fR
+will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR.
+\fIArgc\fR and \fIargv\fR refer to all of the options after the
+matching one.  \fIGenfunc\fR should behave in a fashion similar
+to \fBTk_ParseArgv\fR:  parse as many of the remaining arguments as it can,
+then return any that are left by compacting them to the beginning of
+\fIargv\fR (starting at \fIargv\fR[0]).  \fIGenfunc\fR
+should return a count of how many arguments are left in \fIargv\fR;
+\fBTk_ParseArgv\fR will process them.  If \fIgenfunc\fR encounters
+an error then it should leave an error message in interpreter
+\fIinterp\fR's result,
+in the usual Tcl fashion, and return \-1;  when this happens
+\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
+.RE
+.SS "FLAGS"
+.TP
+\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
+\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
+or command name, and returns it to the caller just as if it
+had not matched \fIargTable\fR.  If this flag is given, then
+\fIargv[0]\fR is not given special treatment.
+.TP
+\fBTK_ARGV_NO_ABBREV\fR
+Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for
+\fIkey\fR values in \fIargTable\fR.  If this flag is given then
+only exact matches will be acceptable.
+.TP
+\fBTK_ARGV_NO_LEFTOVERS\fR
+Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
+caller.  If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
+will return an error if it encounters any argument that does not
+match \fIargTable\fR.  The only exception to this rule is \fIargv[0]\fR,
+which will be returned to the caller with no errors as
+long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified.
+.TP
+\fBTK_ARGV_NO_DEFAULTS\fR
+Normally, \fBTk_ParseArgv\fR searches an internal table of
+standard argument specifiers in addition to \fIargTable\fR.  If
+this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
+use only \fIargTable\fR and not its default table.
+.SH EXAMPLE
+.PP
+Here is an example definition of an \fIargTable\fR and
+some sample command lines that use the options.  Note the effect
+on \fIargc\fR and \fIargv\fR;  arguments processed by \fBTk_ParseArgv\fR
+are eliminated from \fIargv\fR, and \fIargc\fR
+is updated to reflect reduced number of arguments.
+.CS
+/*
+ * Define and set default values for globals.
+ */
+int debugFlag = 0;
+int numReps = 100;
+char defaultFileName[] = "out";
+char *fileName = defaultFileName;
+Boolean exec = FALSE;
+
+/*
+ * Define option descriptions.
+ */
+Tk_ArgvInfo argTable[] = {
+    {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
+        "Turn on debugging printfs"},
+    {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
+        "Number of repetitions"},
+    {"\-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
+        "Name of file for output"},
+    {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
+        "File to exec, followed by any arguments (must be last argument)."},
+    {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
+        (char *) NULL}
+};
+
+main(argc, argv)
+    int argc;
+    char *argv[];
+{
+    \&...
+
+    if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
+        fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp)));
+        exit(1);
+    }
+
+    /*
+     * Remainder of the program.
+     */
+}
+.CE
+.PP
+Note that default values can be assigned to variables named in
+\fIargTable\fR:  the variables will only be overwritten if the
+particular arguments are present in \fIargv\fR.
+Here are some example command lines and their effects.
+.CS
+prog \-N 200 infile        # just sets the numReps variable to 200
+prog \-of out200 infile    # sets fileName to reference "out200"
+prog \-XN 10 infile        # sets the debug flag, also sets numReps
+.CE
+In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2,
+\fIargv\fR[0] will be
+.QW prog ,
+\fIargv\fR[1] will be
+.QW infile ,
+and \fIargv\fR[2] will be NULL.
+.SH KEYWORDS
+arguments, command line, options

doc/QWinEvent.3

@@ -0,0 +1,50 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CollapseMotionEvents, Tk_QueueWindowEvent \- Add a window event to the Tcl event queue
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR)
+.sp
+\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR)
+.SH ARGUMENTS
+.AS Tcl_QueuePosition position
+.AP Display *display  in
+Display for which to control motion event collapsing.
+.AP int collapse in
+Indicates whether motion events should be collapsed or not.
+.AP XEvent *eventPtr  in
+An event to add to the event queue. It is important
+that all unused fields of the structure be set to zero.
+.AP Tcl_QueuePosition position in
+Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
+\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event
+queue for eventual servicing.  It creates a Tcl_Event structure, copies the
+event into that structure, and calls \fBTcl_QueueEvent\fR to add the event
+to the queue.  When the event is eventually removed from the queue it is
+processed just like all window events.
+.PP
+When multiple motion events are received for the same window in rapid
+succession, they are collapsed by default.  This behavior can be controlled
+with \fBTk_CollapseMotionEvents\fR.  \fBTk_CollapseMotionEvents\fR always
+returns the previous value for collapse behavior on the \fIdisplay\fR.
+.PP
+The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has
+the same significance as for \fBTcl_QueueEvent\fR;  see the
+documentation for \fBTcl_QueueEvent\fR for details.
+.SH KEYWORDS
+callback, clock, handler, modal timeout, events

doc/Restack.3

@@ -0,0 +1,45 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_RestackWindow \- Change a window's position in the stacking order
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR)
+.SH ARGUMENTS
+.AS Tk_Window aboveBelow
+.AP Tk_Window tkwin in
+Token for window to restack.
+.AP int aboveBelow in
+Indicates new position of \fItkwin\fR relative to \fIother\fR;
+must be \fBAbove\fR or \fBBelow\fR.
+.AP Tk_Window other in
+\fITkwin\fR will be repositioned just above or below this window.
+Must be a sibling of \fItkwin\fR or a descendant of a sibling.
+If NULL then \fItkwin\fR is restacked above or below all siblings.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative
+to its siblings.
+If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned
+at the top or bottom of its stacking order, depending on whether
+\fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR.
+If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned
+just above or below \fIother\fR.
+.PP
+The \fIaboveBelow\fR argument must have one of the symbolic values
+\fBAbove\fR or \fBBelow\fR.
+Both of these values are defined by the include file <X11/Xlib.h>.
+.SH KEYWORDS
+above, below, obscure, stacking order

doc/RestrictEv.3

@@ -0,0 +1,79 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_RestrictEvents \- filter and selectively delay X events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_RestrictProc *
+\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR)
+.SH ARGUMENTS
+.AS Tk_RestrictProc **prevArgPtr
+.AP Tk_RestrictProc *proc in
+Predicate procedure to call to filter incoming X events.
+NULL means do not restrict events at all.
+.AP ClientData arg in
+Arbitrary argument to pass to \fIproc\fR.
+.AP ClientData *prevArgPtr out
+Pointer to place to save argument to previous restrict procedure.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure is useful in certain situations where applications
+are only prepared to receive certain X events.  After
+\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and
+hence \fBTk_MainLoop\fR) will filter X input events through
+\fIproc\fR.  \fIProc\fR indicates whether a
+given event is to be processed immediately, deferred until some
+later time (e.g. when the event restriction is lifted), or discarded.
+\fIProc\fR
+is a procedure with arguments and result that match
+the type \fBTk_RestrictProc\fR:
+.CS
+typedef Tk_RestrictAction \fBTk_RestrictProc\fR(
+        ClientData \fIarg\fR,
+        XEvent *\fIeventPtr\fR);
+.CE
+The \fIarg\fR argument is a copy of the \fIarg\fR passed
+to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with
+information it needs to filter events.  The \fIeventPtr\fR points to
+an event under consideration.  \fIProc\fR returns a restrict action
+(enumerated type \fBTk_RestrictAction\fR) that indicates what
+\fBTk_DoOneEvent\fR should do with the event.  If the return value is
+\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately.
+If the return value is \fBTK_DEFER_EVENT\fR, then the event will be
+left on the event queue for later processing.  If the return value is
+\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event
+queue and discarded without being processed.
+.PP
+\fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR
+to return information about the current event restriction procedure
+(a NULL return value means there are currently no restrictions).
+These values may be used to restore the previous restriction state
+when there is no longer any need for the current restriction.
+.PP
+There are very few places where \fBTk_RestrictEvents\fR is needed.
+In most cases, the best way to restrict events is by changing the
+bindings with the \fBbind\fR Tcl command or by calling
+\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C.
+The main place where \fBTk_RestrictEvents\fR must be used is when
+performing synchronous actions (for example, if you need to wait
+for a particular event to occur on a particular window but you do not
+want to invoke any handlers for any other events).  The
+.QW obvious
+solution in these situations is to call \fBXNextEvent\fR or
+\fBXWindowEvent\fR, but these procedures cannot be used because
+Tk keeps its own event queue that is separate from the X event
+queue.  Instead, call \fBTk_RestrictEvents\fR to set up a filter,
+then call \fBTk_DoOneEvent\fR to retrieve the desired event(s).
+.SH KEYWORDS
+delay, event, filter, restriction

doc/SetAppName.3

@@ -0,0 +1,62 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetAppName \- Set the name of an application for 'send' commands
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+const char *
+\fBTk_SetAppName\fR(\fItkwin, name\fR)
+.SH ARGUMENTS
+.AS Tk_Window parent
+.AP Tk_Window tkwin in
+Token for window in application.  Used only to select a particular
+application.
+.AP "const char" *name in
+Name under which to register the application.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_SetAppName\fR associates a name with a given application and
+records that association on the display containing with the application's
+main window.
+After this procedure has been invoked, other applications on the
+display will be able to use the \fBsend\fR command to invoke operations
+in the application.
+If \fIname\fR is already in use by some other application on the
+display, then a new name will be generated by appending
+.QW "\fB #2\fR"
+to \fIname\fR;  if this name is also in use,
+the number will be incremented until an unused name is found.
+The return value from the procedure is a pointer to the name actually
+used.
+.PP
+If the application already has a name when \fBTk_SetAppName\fR is
+called, then the new name replaces the old name.
+.PP
+\fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's
+interpreter, which can be used to send commands from this application
+to others on any of the displays where the application has windows.
+.PP
+The application's name registration persists until the interpreter is
+deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which
+point the name is automatically unregistered and the application
+becomes inaccessible via \fBsend\fR.
+The application can be made accessible again by calling \fBTk_SetAppName\fR.
+.PP
+\fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR,
+so applications do not normally need to call it explicitly.
+.PP
+The command \fBtk appname\fR provides Tcl-level access to the
+functionality of \fBTk_SetAppName\fR.
+.SH KEYWORDS
+application, name, register, send command

doc/SetCaret.3

@@ -0,0 +1,36 @@
+'\"
+'\" Copyright (c) 2002 ActiveState Corporation.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetCaretPos \- set the display caret location
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR)
+.SH ARGUMENTS
+.AP Tk_Window tkwin in
+Token for window.
+.AP int x in
+Window-relative x coordinate.
+.AP int y in
+Window-relative y coordinate.
+.AP int h in
+Height of the caret in the window.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_SetCaretPos\fR sets the caret location for the display of the
+specified Tk_Window \fItkwin\fR.  The caret is the per-display cursor
+location used for indicating global focus (e.g. to comply with Microsoft
+Accessibility guidelines), as well as for location of the over-the-spot XIM
+(X Input Methods) or Windows IME windows.
+.SH KEYWORDS
+caret, cursor

doc/SetClass.3

@@ -0,0 +1,57 @@
+'\"
+'\" Copyright (c) 1990 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetClass 3 "" Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetClass, Tk_Class \- set or retrieve a window's class
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_SetClass\fR(\fItkwin, class\fR)
+.sp
+Tk_Uid
+\fBTk_Class\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS Tk_Window parent
+.AP Tk_Window tkwin in
+Token for window.
+.AP char *class in
+New class name for window.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_SetClass\fR is called to associate a class with a particular
+window.  The \fIclass\fR string identifies the type of the
+window;  all windows with the same general class of behavior
+(button, menu, etc.) should have the same class.  By
+convention all class names start with a capital letter, and
+there exists a Tcl command with the same name as
+each class (except all in lower-case) which can be used to
+create and manipulate windows of that class.
+A window's class string is initialized to NULL
+when the window is created.
+.PP
+For main windows, Tk automatically propagates the name and class
+to the WM_CLASS property used by window managers.  This happens
+either when a main window is actually created (e.g. in
+\fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR
+is called, whichever occurs later.  If a main window has not been
+assigned a class then Tk will not set the WM_CLASS property for
+the window.
+.PP
+\fBTk_Class\fR is a macro that returns the
+current value of \fItkwin\fR's class.  The value is returned
+as a Tk_Uid, which may be used just like a string pointer but also has
+the properties of a unique identifier (see the manual entry for
+\fBTk_GetUid\fR for details).
+If \fItkwin\fR has not yet been given a class, then
+\fBTk_Class\fR will return NULL.
+.SH KEYWORDS
+class, unique identifier, window, window manager

doc/SetClassProcs.3

@@ -0,0 +1,87 @@
+'\"
+'\" Copyright (c) 2000 Ajuba Solutions.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetClassProcs \- register widget specific procedures
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR)
+.SH ARGUMENTS
+.AS Tk_ClassProc instanceData
+.AP Tk_Window tkwin in
+Token for window to modify.
+.AP "const Tk_ClassProcs" *procs in
+Pointer to data structure containing widget specific procedures.
+The data structure pointed to by \fIprocs\fR must be static:
+Tk keeps a reference to it as long as the window exists.
+.AP ClientData instanceData in
+Arbitrary one-word value to pass to widget callbacks.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_SetClassProcs\fR is called to register a set of procedures that
+are used as callbacks in different places.
+.PP
+The structure pointed to by \fIprocs\fR contains the following:
+.CS
+typedef struct Tk_ClassProcs {
+    unsigned int \fIsize\fR;
+    Tk_ClassWorldChangedProc *\fIworldChangedProc\fR;
+    Tk_ClassCreateProc *\fIcreateProc\fR;
+    Tk_ClassModalProc *\fImodalProc\fR;
+} \fBTk_ClassProcs\fR;
+.CE
+The \fIsize\fR field is used to simplify future expansion of the
+structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR.
+.PP
+\fIworldChangedProc\fR is invoked when the system has altered
+in some way that requires some reaction from the widget.  For example,
+when a font alias (see the \fBfont\fR manual entry) is reconfigured,
+widgets configured to use that font alias must update their display
+accordingly.  \fIworldChangedProc\fR should have arguments and results
+that match the type \fBTk_ClassWorldChangedProc\fR:
+.CS
+typedef void \fBTk_ClassWorldChangedProc\fR(
+        ClientData \fIinstanceData\fR);
+.CE
+The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR
+will be identical to the \fIinstanceData\fR parameter passed to
+\fBTk_SetClassProcs\fR.
+.PP
+\fIcreateProc\fR is used to create platform-dependant windows.  It is
+invoked by \fBTk_MakeWindowExist\fR.  \fIcreateProc\fR should have
+arguments and results that match the type \fBTk_ClassCreateProc\fR:
+.CS
+typedef Window \fBTk_ClassCreateProc\fR(
+        Tk_Window \fItkwin\fR,
+        Window \fIparent\fR,
+        ClientData \fIinstanceData\fR);
+.CE
+The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to
+the \fItkwin\fR and \fIinstanceData\fR parameters passed to
+\fBTk_SetClassProcs\fR.  The \fIparent\fR parameter will be the parent
+of the window to be created.  The \fIcreateProc\fR should return the
+created window.
+.PP
+\fImodalProc\fR is invoked after all bindings on a widget have been
+triggered in order to handle a modal loop.  \fImodalProc\fR should
+have arguments and results that match the type \fBTk_ClassModalProc\fR:
+.CS
+typedef void \fBTk_ClassModalProc\fR(
+        Tk_Window \fItkwin\fR,
+        XEvent *\fIeventPtr\fR);
+.CE
+The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the
+\fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR.  The
+\fIeventPtr\fR parameter will be a pointer to an XEvent structure
+describing the event being processed.
+.SH KEYWORDS
+callback, class

doc/SetGrid.3

@@ -0,0 +1,63 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR)
+.sp
+\fBTk_UnsetGrid\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS Tk_Window heightInc
+.AP Tk_Window tkwin in
+Token for window.
+.AP int reqWidth in
+Width in grid units that corresponds to the pixel dimension \fItkwin\fR
+has requested via \fBTk_GeometryRequest\fR.
+.AP int reqHeight in
+Height in grid units that corresponds to the pixel dimension \fItkwin\fR
+has requested via \fBTk_GeometryRequest\fR.
+.AP int widthInc in
+Width of one grid unit, in pixels.
+.AP int heightInc in
+Height of one grid unit, in pixels.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's
+toplevel window and specifies the geometry of the grid.
+\fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR
+option is true.
+It restricts interactive resizing of \fItkwin\fR's toplevel window so
+that the space allocated to the toplevel is equal to its requested
+size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR.
+Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are
+passed to the window manager so that it can report the window's
+size in grid units during interactive resizes.
+If \fItkwin\fR's configuration changes (e.g., the size of a grid unit
+changes) then the widget should invoke \fBTk_SetGrid\fR again with the new
+information.
+.PP
+\fBTk_UnsetGrid\fR cancels gridded geometry management for
+\fItkwin\fR's toplevel window.
+.PP
+For each toplevel window there can be at most one internal window
+with gridding enabled.
+If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some
+other window is already controlling gridding for \fItkwin\fR's
+toplevel, the calls for the new window have no effect.
+.PP
+See the \fBwm\fR manual entry for additional information on gridded geometry
+management.
+.SH KEYWORDS
+grid, window, window manager

doc/SetOptions.3

@@ -0,0 +1,656 @@
+'\"
+'\" Copyright (c) 1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,  Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_OptionTable
+\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
+.sp
+\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
+.sp
+int
+\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
+.sp
+int
+\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
+.sp
+\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
+.sp
+\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
+.sp
+Tcl_Obj *
+\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+.sp
+Tcl_Obj *
+\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+.sp
+\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
+.sp
+int
+\fBTk_Offset(\fItype, field\fB)\fR
+.SH ARGUMENTS
+.AS Tk_SavedOptions "*const objv[]" in/out
+.AP Tcl_Interp *interp in
+A Tcl interpreter.  Most procedures use this only for returning error
+messages; if it is NULL then no error messages are returned.  For
+\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the
+interpreter in which the option table will be used.
+.AP "const Tk_OptionSpec" *templatePtr in
+Points to an array of static information that describes the configuration
+options that are supported.  Used to build a Tk_OptionTable.  The information
+pointed to by this argument must exist for the lifetime of the Tk_OptionTable.
+.AP Tk_OptionTable optionTable in
+Token for an option table.  Must have been returned by a previous call
+to \fBTk_CreateOptionTable\fR.
+.AP char *recordPtr in/out
+Points to structure in which values of configuration options are stored;
+fields of this record are modified by procedures such as \fBTk_SetOptions\fR
+and read by procedures such as \fBTk_GetOptionValue\fR.
+.AP Tk_Window tkwin in
+For options such as \fBTK_OPTION_COLOR\fR, this argument indicates
+the window in which the option will be used.  If \fIoptionTable\fR uses
+no window-dependent options, then a NULL value may be supplied for
+this argument.
+.AP int objc in
+Number of values in \fIobjv\fR.
+.AP Tcl_Obj "*const objv[]" in
+Command-line arguments for setting configuring options.
+.AP Tk_SavedOptions *savePtr out
+If not NULL, the structure pointed to by this argument is filled
+in with the old values of any options that were modified and old
+values are restored automatically if an error occurs in \fBTk_SetOptions\fR.
+.AP int *maskPtr out
+If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the
+bit-wise OR of the \fItypeMask\fR fields for the options that
+were modified.
+.AP Tk_SavedOptions *savedPtr in/out
+Points to a structure previously filled in by \fBTk_SetOptions\fR with
+old values of modified options.
+.AP Tcl_Obj *namePtr in
+The value of this object is the name of a particular option.  If NULL
+is passed to \fBTk_GetOptionInfo\fR then information is returned for
+all options.  Must not be NULL when \fBTk_GetOptionValue\fR is called.
+.AP "type name" type in
+The name of the type of a record.
+.AP "field name" field in
+The name of a field in records of type \fItype\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures handle most of the details of parsing configuration
+options such as those for Tk widgets.  Given a description of what
+options are supported, these procedures handle all the details of
+parsing options and storing their values into a C structure associated
+with the widget or object. The procedures were designed primarily for
+widgets in Tk, but they can also be used for other kinds of objects that
+have configuration options.  In the rest of this manual page
+.QW widget
+will be used to refer to the object whose options are being managed; in
+practice the object may not actually be a widget.  The term
+.QW "widget record"
+is used to refer to the C-level structure in
+which information about a particular widget or object is stored.
+.PP
+Note: the easiest way to learn how to use these procedures is to
+look at a working example.  In Tk, the simplest example is the code
+that implements the button family of widgets, which is in \fBtkButton.c\fR.
+Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
+.PP
+In order to use these procedures, the code that implements the widget
+must contain a static array of Tk_OptionSpec structures. This is a
+template that describes the various options supported by that class of
+widget; there is a separate template for each kind of widget.  The
+template contains information such as the name of each option, its type,
+its default value, and where the value of the option is stored in the
+widget record.  See TEMPLATES below for more detail.
+.PP
+In order to process configuration options efficiently, the static
+template must be augmented with additional information that is available
+only at runtime.  The procedure \fBTk_CreateOptionTable\fR creates this
+dynamic information from the template and returns a Tk_OptionTable token
+that describes both the static and dynamic information.  All of the
+other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable
+token as argument.  Typically, \fBTk_CreateOptionTable\fR is called the
+first time that a widget of a particular class is created and the
+resulting Tk_OptionTable is used in the future for all widgets of that
+class.  A Tk_OptionTable may be used only in a single interpreter, given
+by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR.  When an
+option table is no longer needed \fBTk_DeleteOptionTable\fR should be
+called to free all of its resources.  All of the option tables
+for a Tcl interpreter are freed automatically if the interpreter is deleted.
+.PP
+\fBTk_InitOptions\fR is invoked when a new widget is created to set the
+default values for all of the widget's configuration options that do not
+have \fBTK_OPTION_DONT_SET_DEFAULT\fR set in their \fIflags\fR field.
+\fBTk_InitOptions\fR is passed a token for an option table
+(\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR),
+which is the C structure that holds information about this widget.
+\fBTk_InitOptions\fR uses the information in the option table to choose an
+appropriate default for each option, except those having
+\fBTK_OPTION_DONT_SET_DEFAULT\fR set, then it stores the default value
+directly into the widget record, overwriting any information that was
+already present in the widget record.  \fBTk_InitOptions\fR normally
+returns \fBTCL_OK\fR.  If an error occurred while setting the default
+values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR
+is returned and an error message is left in \fIinterp\fR's result if
+\fIinterp\fR is not NULL.
+.PP
+\fBTk_SetOptions\fR is invoked to modify configuration options based
+on information specified in a Tcl command.  The command might be one that
+creates a new widget, or a command that modifies options on an existing
+widget.  The \fIobjc\fR and \fIobjv\fR arguments describe the
+values of the arguments from the Tcl command.  \fIObjv\fR must contain
+an even number of objects: the first object of each pair gives the name of
+an option and the second object gives the new value for that option.
+\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that
+the new value of the option conforms to the type in \fIoptionTable\fR,
+and stores the value of the option into the widget record given by
+\fIrecordPtr\fR.  \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR.  If
+an error occurred (such as an unknown option name or an illegal option
+value) then \fBTCL_ERROR\fR is returned and an error message is left in
+\fIinterp\fR's result if \fIinterp\fR is not NULL.
+.PP
+\fBTk_SetOptions\fR has two additional features.  First, if the
+\fImaskPtr\fR argument is not NULL then it points to an integer
+value that is filled in with information about the options that were
+modified.  For each option in the template passed to
+\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field.  The
+bits of this field are defined by the code that implements the widget;
+for example, each bit might correspond to a particular configuration option.
+Alternatively, bits might be used functionally.  For example, one bit might
+be used for redisplay: all options that affect the widget's display, such
+that changing the option requires the widget to be redisplayed, might have
+that bit set.  Another bit might indicate that the geometry of the widget
+must be recomputed, and so on.  \fBTk_SetOptions\fR OR's together the
+\fItypeMask\fR fields from all the options that were modified and returns
+this value at *\fImaskPtr\fR; the caller can then use this information
+to optimize itself so that, for example, it does not redisplay the widget
+if the modified options do not affect the widget's appearance.
+.PP
+The second additional feature of \fBTk_SetOptions\fR has to do with error
+recovery.  If an error occurs while processing configuration options, this
+feature makes it possible to restore all the configuration options to their
+previous values.  Errors can occur either while processing options in
+\fBTk_SetOptions\fR or later in the caller.  In many cases the caller does
+additional processing after \fBTk_SetOptions\fR returns; for example, it
+might use an option value to set a trace on a variable and may detect
+an error if the variable is an array instead of a scalar.  Error recovery
+is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument
+to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized
+Tk_SavedOptions structure on the caller's stack.  \fBTk_SetOptions\fR
+overwrites the structure pointed to by \fIsavePtr\fR with information
+about the old values of any options modified by the procedure.
+If \fBTk_SetOptions\fR returns successfully, the
+caller uses the structure in one of two ways.  If the caller completes
+its processing of the new options without any errors, then it must pass
+the structure to \fBTk_FreeSavedOptions\fR so that the old values can be
+freed.  If the caller detects an error in its processing of the new
+options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR,
+which will copy the old values back into the widget record and free
+the new values.
+If \fBTk_SetOptions\fR detects an error then it automatically restores
+any options that had already been modified and leaves *\fIsavePtr\fR in
+an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or
+\fBTk_RestoreSavedOptions\fR.
+If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then
+\fBTk_SetOptions\fR frees each old option value immediately when it sets a new
+value for the option.  In this case, if an error occurs in the third
+option, the old values for the first two options cannot be restored.
+.PP
+\fBTk_GetOptionValue\fR returns the current value of a configuration option
+for a particular widget.  The \fInamePtr\fR argument contains the name of
+an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR
+to lookup the option and extract its value from the widget record
+pointed to by \fIrecordPtr\fR, then it returns an object containing
+that value.  If an error occurs (e.g., because \fInamePtr\fR contains an
+unknown option name) then NULL is returned and an error message is left
+in \fIinterp\fR's result unless \fIinterp\fR is NULL.
+.PP
+\fBTk_GetOptionInfo\fR returns information about configuration options in
+a form suitable for \fBconfigure\fR widget commands.  If the \fInamePtr\fR
+argument is not NULL, it points to an object that gives the name of a
+configuration option; \fBTk_GetOptionInfo\fR returns an object containing
+a list with five elements, which are the name of the option, the name and
+class used for the option in the option database, the default value for
+the option, and the current value for the option.  If the \fInamePtr\fR
+argument is NULL, then \fBTk_GetOptionInfo\fR returns information about
+all options in the form of a list of lists; each sublist describes one
+option.  Synonym options are handled differently depending on whether
+\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for
+each synonym option has only two elements, which are the name of the
+option and the name of the other option that it refers to; if \fInamePtr\fR
+is non-NULL and names a synonym option then the object returned
+is the five-element list
+for the other option that the synonym refers to.  If an error occurs
+(e.g., because \fInamePtr\fR contains an unknown option name) then NULL
+is returned and an error message is left in \fIinterp\fR's result unless
+\fIinterp\fR is NULL.
+.PP
+\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted.
+It frees all of the resources associated with any of the configuration
+options defined in \fIrecordPtr\fR by \fIoptionTable\fR.
+.PP
+The \fBTk_Offset\fR macro is provided as a safe way of generating the
+\fIobjOffset\fR and \fIinternalOffset\fR values for entries in
+Tk_OptionSpec structures.  It takes two arguments: the name of a type
+of record, and the name of a field in that record. It returns the byte
+offset of the named field in records of the given type.
+.SH "TEMPLATES"
+.PP
+The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR
+via its \fItemplatePtr\fR argument describes the configuration options
+supported by a particular class of widgets.  Each structure specifies
+one configuration option and has the following fields:
+.CS
+typedef struct {
+    Tk_OptionType \fItype\fR;
+    const char *\fIoptionName\fR;
+    const char *\fIdbName\fR;
+    const char *\fIdbClass\fR;
+    const char *\fIdefValue\fR;
+    int \fIobjOffset\fR;
+    int \fIinternalOffset\fR;
+    int \fIflags\fR;
+    const void *\fIclientData\fR;
+    int \fItypeMask\fR;
+} \fBTk_OptionSpec\fR;
+.CE
+The \fItype\fR field indicates what kind of configuration option this is
+(e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for
+an integer value).  \fIType\fR determines how the
+value of the option is parsed (more on this below).
+The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR;
+it is the name used for the option in Tcl commands and passed to
+procedures via the \fIobjc\fR or \fInamePtr\fR arguments.
+The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR
+to look up a default value for this option in the option database; if
+\fIdbName\fR is NULL then the option database is not used by
+\fBTk_InitOptions\fR for this option.  The \fIdefValue\fR field
+specifies a default value for this configuration option if no
+value is specified in the option database.  The \fIobjOffset\fR and
+\fIinternalOffset\fR fields indicate where to store the value of this
+option in widget records (more on this below); values for the \fIobjOffset\fR
+and \fIinternalOffset\fR fields should always be generated with the
+\fBTk_Offset\fR macro.
+The \fIflags\fR field contains additional information
+to control the processing of this configuration option (see below
+for details).
+\fIClientData\fR provides additional type-specific data needed
+by certain types.  For instance, for \fBTK_OPTION_COLOR\fR types,
+\fIclientData\fR is a string giving the default value to use on
+monochrome displays.  See the descriptions of the different types
+below for details.
+The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to
+return information about which options were modified; see the description
+of \fBTk_SetOptions\fR above for details.
+.PP
+When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an
+option into the widget record, they can do it in either of two ways.
+If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than
+or equal to zero, then the value of the option is stored as a
+(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR.
+If the \fIinternalOffset\fR field of the Tk_OptionSpec is
+greater than or equal to zero, then the value of the option is stored
+in a type-specific internal form at the location in the widget record
+given by \fIinternalOffset\fR.  For example, if the option's type is
+\fBTK_OPTION_INT\fR then the internal form is an integer.  If the
+\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the
+value is not stored in that form.  At least one of the offsets must be
+greater than or equal to zero.
+.PP
+The \fIflags\fR field consists of one or more bits ORed together. The
+following flags are supported:
+.TP
+\fBTK_OPTION_NULL_OK\fR
+If this bit is set for an option then an empty string will be accepted as
+the value for the option and the resulting internal form will be a NULL
+pointer, a zero value, or \fBNone\fR, depending on the type of the option.
+If the flag is not set then empty strings will result in errors.
+\fBTK_OPTION_NULL_OK\fR is typically used to allow a
+feature to be turned off entirely, e.g. set a cursor value to
+\fBNone\fR so that a window simply inherits its parent's cursor.
+Not all option types support the \fBTK_OPTION_NULL_OK\fR
+flag; for those that do, there is an explicit indication of that fact
+in the descriptions below.
+.TP
+\fBTK_OPTION_DONT_SET_DEFAULT\fR
+If this bit is set for an option then no default value will be set in
+\fBTk_InitOptions\fR for this option. Neither the option database, nor any
+system default value, nor \fIoptionTable\fR are used to give a default
+value to this option. Instead it is assumed that the caller has already
+supplied a default value in the widget code.
+.PP
+The \fItype\fR field of each Tk_OptionSpec structure determines
+how to parse the value of that configuration option. The
+legal value for \fItype\fR, and the corresponding actions, are
+described below.  If the type requires a \fItkwin\fR value to be
+passed into procedures like \fBTk_SetOptions\fR, or if it uses
+the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated
+explicitly; if not mentioned, the type requires neither \fItkwin\fR
+nor \fIclientData\fR.
+.TP
+\fBTK_OPTION_ANCHOR\fR
+The value must be a standard anchor position such as \fBne\fR or
+\fBcenter\fR.  The internal form is a Tk_Anchor value like the ones
+returned by \fBTk_GetAnchorFromObj\fR.
+.TP
+\fBTK_OPTION_BITMAP\fR
+The value must be a standard Tk bitmap name. The internal form is a
+Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_BOOLEAN\fR
+The value must be a standard boolean value such as \fBtrue\fR or
+\fBno\fR.  The internal form is an integer with value 0 or 1.
+.TP
+\fBTK_OPTION_BORDER\fR
+The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
+The internal form is a Tk_3DBorder token like the ones returned
+by \fBTk_Alloc3DBorderFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_COLOR\fR
+The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
+The internal form is an (XColor *) token like the ones returned by
+\fBTk_AllocColorFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_CURSOR\fR
+The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR.
+The internal form is a Tk_Cursor token like the ones returned by
+\fBTk_AllocCursorFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and when the option is set the cursor
+for the window is changed by calling \fBXDefineCursor\fR.  This
+option type also supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_CUSTOM\fR
+This option allows applications to define new option types.  The
+clientData field of the entry points to a structure defining the new
+option type.  See the section \fBCUSTOM OPTION TYPES\fR below for details.
+.TP
+\fBTK_OPTION_DOUBLE\fR
+The string value must be a floating-point number in
+the format accepted by \fBstrtol\fR.  The internal form is a C
+\fBdouble\fR value.  This option type supports the \fBTK_OPTION_NULL_OK\fR
+flag; if a NULL value is set, the internal representation is set to zero.
+.TP
+\fBTK_OPTION_END\fR
+Marks the end of the template.  There must be a Tk_OptionSpec structure
+with \fItype\fR \fBTK_OPTION_END\fR at the end of each template.  If the
+\fIclientData\fR field of this structure is not NULL, then it points to
+an additional array of Tk_OptionSpec's, which is itself terminated by
+another \fBTK_OPTION_END\fR entry.  Templates may be chained arbitrarily
+deeply.  This feature allows common options to be shared by several
+widget classes.
+.TP
+\fBTK_OPTION_FONT\fR
+The value must be a standard font name such as \fBTimes 16\fR.
+The internal form is a Tk_Font handle like the ones returned by
+\fBTk_AllocFontFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_INT\fR
+The string value must be an integer in the format accepted by
+\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to
+specify octal or hexadecimal numbers, respectively).  The internal
+form is a C \fBint\fR value.
+.TP
+\fBTK_OPTION_JUSTIFY\fR
+The value must be a standard justification value such as \fBleft\fR.
+The internal form is a Tk_Justify like the values returned by
+\fBTk_GetJustifyFromObj\fR.
+.TP
+\fBTK_OPTION_PIXELS\fR
+The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR.
+The internal form is an integer value giving a
+distance in pixels, like the values returned by
+\fBTk_GetPixelsFromObj\fR.  Note: if the \fIobjOffset\fR field is not
+used then information about the original value of this option will be lost.
+See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.  This option
+type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the
+internal representation is set to zero.
+.TP
+\fBTK_OPTION_RELIEF\fR
+The value must be standard relief such as \fBraised\fR.
+The internal form is an integer relief value such as
+\fBTK_RELIEF_RAISED\fR.  This option type supports the \fBTK_OPTION_NULL_OK\fR
+flag; if the empty string is specified as the value for the option,
+the integer relief value is set to \fBTK_RELIEF_NULL\fR.
+.TP
+\fBTK_OPTION_STRING\fR
+The value may be any string.  The internal form is a (char *) pointer
+that points to a dynamically allocated copy of the value.
+This option type supports the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fBTK_OPTION_STRING_TABLE\fR
+For this type, \fIclientData\fR is a pointer to an array of strings
+suitable for passing to \fBTcl_GetIndexFromObj\fR.  The value must
+be one of the strings in the table, or a unique abbreviation of
+one of the strings.  The internal form is an integer giving the index
+into the table of the matching string, like the return value
+from \fBTcl_GetStringFromObj\fR.
+.TP
+\fBTK_OPTION_SYNONYM\fR
+This type is used to provide alternative names for an option (for
+example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR).
+The \fBclientData\fR field is a string that gives the name of another
+option in the same table.  Whenever the synonym option is used, the
+information from the other option will be used instead.
+.TP
+\fBTK_OPTION_WINDOW\fR
+The value must be a window path name.  The internal form is a
+\fBTk_Window\fR token for the window.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR (in order to identify the application),
+and it supports the \fBTK_OPTION_NULL_OK\fR flag.
+.SH "STORAGE MANAGEMENT ISSUES"
+.PP
+If a field of a widget record has its offset stored in the \fIobjOffset\fR
+or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the
+procedures described here will handle all of the storage allocation and
+resource management issues associated with the field.  When the value
+of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR)
+will automatically free any resources associated with the old value, such as
+Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for
+\fBTK_OPTION_STRING\fR options.  For an option stored as an object using the
+\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the
+object pointed to by the \fIobjv\fR value from the call to
+\fBTk_SetOptions\fR.  The reference count for this object is incremented
+when a pointer to it is stored in the widget record and decremented when
+the option is modified.  When the widget is deleted
+\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources
+associated with all options and decrement reference counts for any
+objects.
+.PP
+However, the widget code is responsible for storing NULL or \fBNone\fR in
+all pointer and token fields before invoking \fBTk_InitOptions\fR.
+This is needed to allow proper cleanup in the rare case where
+an error occurs in \fBTk_InitOptions\fR.
+.SH "OBJOFFSET VS. INTERNALOFFSET"
+.PP
+In most cases it is simplest to use the \fIinternalOffset\fR field of
+a Tk_OptionSpec structure and not the \fIobjOffset\fR field.  This
+makes the internal form of the value immediately available to the
+widget code so the value does not have to be extracted from an object
+each time it is used.  However, there are two cases where the
+\fIobjOffset\fR field is useful.  The first case is for
+\fBTK_OPTION_PIXELS\fR options.  In this case, the internal form is
+an integer pixel value that is valid only for a particular screen.
+If the value of the option is retrieved, it will be returned as a simple
+number.  For example, after the command \fB.b configure \-borderwidth 2m\fR,
+the command \fB.b configure \-borderwidth\fR might return 7, which is the
+integer pixel value corresponding to \fB2m\fR.  Unfortunately, this loses
+the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options
+it is better to use the \fIobjOffset\fR field.  In this case the original
+value of the option is retained in the object and can be returned when
+the option is retrieved.  In most cases it is convenient to use the
+\fIinternalOffset\fR field as well, so that the integer value is
+immediately available for use in the widget code (alternatively,
+\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from
+the object whenever it is needed).  Note: the problem of losing information
+on retrievals exists only for \fBTK_OPTION_PIXELS\fR options.
+.PP
+The second reason to use the \fIobjOffset\fR field is in order to
+implement new types of options not supported by these procedures.
+To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as
+the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field
+but not the \fIinternalOffset\fR field.  Then, after calling
+\fBTk_SetOptions\fR, convert the object to internal form yourself.
+.SH "CUSTOM OPTION TYPES"
+.PP
+Applications can extend the built-in configuration types with
+additional configuration types by writing procedures to parse, print,
+free, and restore saved copies of the type and creating a structure
+pointing to those procedures:
+.CS
+typedef struct Tk_ObjCustomOption {
+    char *name;
+    Tk_CustomOptionSetProc *\fIsetProc\fR;
+    Tk_CustomOptionGetProc *\fIgetProc\fR;
+    Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
+    Tk_CustomOptionFreeProc *\fIfreeProc\fR;
+    ClientData \fIclientData\fR;
+} \fBTk_ObjCustomOption\fR;
+
+typedef int \fBTk_CustomOptionSetProc\fR(
+    ClientData \fIclientData\fR,
+    Tcl_Interp *\fIinterp\fR,
+    Tk_Window \fItkwin\fR,
+    Tcl_Obj **\fIvaluePtr\fR,
+    char *\fIrecordPtr\fR,
+    int \fIinternalOffset\fR,
+    char *\fIsaveInternalPtr\fR,
+    int \fIflags\fR);
+
+typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR(
+    ClientData \fIclientData\fR,
+    Tk_Window \fItkwin\fR,
+    char *\fIrecordPtr\fR,
+    int \fIinternalOffset\fR);
+
+typedef void \fBTk_CustomOptionRestoreProc\fR(
+    ClientData \fIclientData\fR,
+    Tk_Window \fItkwin\fR,
+    char *\fIinternalPtr\fR,
+    char *\fIsaveInternalPtr\fR);
+
+typedef void \fBTk_CustomOptionFreeProc\fR(
+    ClientData \fIclientData\fR,
+    Tk_Window \fItkwin\fR,
+    char *\fIinternalPtr\fR);
+.CE
+.PP
+The Tk_ObjCustomOption structure contains six fields: a name
+for the custom option type; pointers to the four procedures; and a
+\fIclientData\fR value to be passed to those procedures when they are
+invoked.  The \fIclientData\fR value typically points to a structure
+containing information that is needed by the procedures when they are
+parsing and printing options.  \fIRestoreProc\fR and \fIfreeProc\fR
+may be NULL, indicating that no function should be called for those
+operations.
+.PP
+The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to
+convert a Tcl_Obj into an internal representation and store the
+resulting value in the widget record.  The arguments are:
+.RS
+.TP
+\fIclientData\fR
+A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure.
+.TP
+\fIinterp\fR
+A pointer to a Tcl interpreter, used for error reporting.
+.TP
+\fITkwin\fR
+A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
+.TP
+\fIvaluePtr\fR
+A pointer to a reference to a Tcl_Obj describing the new value for the
+option; it could have been specified explicitly in the call to
+\fBTk_SetOptions\fR or it could come from the option database or a
+default.  If the objOffset for the option is non-negative (the option
+value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj
+pointer referenced by \fIvaluePtr\fR is the pointer that will be
+stored at the objOffset for the option.  \fISetProc\fR may modify the
+value if necessary; for example, \fIsetProc\fR may change the value to
+NULL to support the \fBTK_OPTION_NULL_OK\fR flag.
+.TP
+\fIrecordPtr\fR
+A pointer to the start of the widget record to modify.
+.TP
+\fIinternalOffset\fR
+Offset in bytes from the start of the widget record to the location
+where the internal representation of the option value is to be placed.
+.TP
+\fIsaveInternalPtr\fR
+A pointer to storage allocated in a Tk_SavedOptions structure for the
+internal representation of the original option value.  Before setting
+the option to its new value, \fIsetProc\fR should set the value
+referenced by \fIsaveInternalPtr\fR to the original value of the
+option in order to support \fBTk_RestoreSavedOptions\fR.
+.TP
+\fIflags\fR
+A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the
+option
+.RE
+.PP
+\fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful
+processing, or \fBTCL_ERROR\fR to indicate a failure of any kind.  An error
+message may be left in the Tcl interpreter given by \fIinterp\fR in
+the case of an error.
+.PP
+The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and
+\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the
+internal representation of an option.  The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure.  \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR.  \fIRecordPtr\fR
+is a pointer to the beginning of the widget record to query.
+\fIInternalOffset\fR is the offset in bytes from the beginning of the
+widget record to the location where the internal representation of the
+option value is stored.  \fIGetProc\fR must return a pointer to a
+Tcl_Obj representing the value of the option.
+.PP
+The \fIrestoreProc\fR procedure is invoked by
+\fBTk_RestoreSavedOptions\fR to restore a previously saved internal
+representation of a custom option value.  The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure.  \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR.  \fIInternalPtr\fR
+is a pointer to the location where internal representation of the
+option value is stored.
+\fISaveInternalPtr\fR is a pointer to the saved value.
+\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to
+\fIinternalPtr\fR to restore the value.  \fIRestoreProc\fR need not
+free any memory associated with either \fIinternalPtr\fR or
+\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that
+memory if necessary.  \fIRestoreProc\fR has no return value.
+.PP
+The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and
+\fBTk_FreeSavedOptions\fR to free any storage allocated for the
+internal representation of a custom option.  The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure.  \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR.  \fIInternalPtr\fR
+is a pointer to the location where the internal representation of the
+option value is stored.  The \fIfreeProc\fR must free any storage
+associated with the option.  \fIFreeProc\fR has no return value.
+.SH KEYWORDS
+anchor, bitmap, boolean, border, color, configuration option,
+cursor, double, font, integer, justify,
+pixels, relief, screen distance, synonym

doc/SetVisual.3

@@ -0,0 +1,50 @@
+'\"
+'\" Copyright (c) 1992 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_SetWindowVisual \- change visual characteristics of window
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR)
+.SH ARGUMENTS
+.AS "Tk_Window int" colormap
+.AP Tk_Window tkwin in
+Token for window.
+.AP Visual *visual in
+New visual type to use for \fItkwin\fR.
+.AP "int" depth in
+Number of bits per pixel desired for \fItkwin\fR.
+.AP Colormap colormap in
+New colormap for \fItkwin\fR, which must be compatible with
+\fIvisual\fR and \fIdepth\fR.
+.BE
+.SH DESCRIPTION
+.PP
+When Tk creates a new window it assigns it the default visual
+characteristics (visual, depth, and colormap) for its screen.
+\fBTk_SetWindowVisual\fR may be called to change them.
+\fBTk_SetWindowVisual\fR must be called before the window has
+actually been created in X (e.g. before \fBTk_MapWindow\fR or
+\fBTk_MakeWindowExist\fR has been invoked for the window).
+The safest thing is to call \fBTk_SetWindowVisual\fR immediately
+after calling \fBTk_CreateWindow\fR.
+If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR
+is called then it returns 0 and does not make any changes;  otherwise
+it returns 1 to signify that the operation
+completed successfully.
+.PP
+Note:  \fBTk_SetWindowVisual\fR should not be called if you just want
+to change a window's colormap without changing its visual or depth;
+call \fBTk_SetWindowColormap\fR instead.
+.SH KEYWORDS
+colormap, depth, visual

doc/StrictMotif.3

@@ -0,0 +1,38 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_StrictMotif \- Return value of tk_strictMotif variable
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_StrictMotif\fR(\fItkwin\fR)
+.SH ARGUMENTS
+.AS Tk_Window tkwin
+.AP Tk_Window tkwin in
+Token for window.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure returns the current value of the \fBtk_strictMotif\fR
+variable in the interpreter associated with \fItkwin\fR's application.
+The value is returned as an integer that is either 0 or 1.
+1 means that strict Motif compliance has been requested, so anything
+that is not part of the Motif specification should be avoided.
+0 means that
+.QW Motif-like
+is good enough, and extra features are welcome.
+.PP
+This procedure uses a link to the Tcl variable to provide much
+faster access to the variable's value than could be had by calling
+\fBTcl_GetVar\fR.
+.SH KEYWORDS
+Motif compliance, tk_strictMotif variable

doc/TextLayout.3

@@ -0,0 +1,276 @@
+'\"
+'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_TextLayout
+\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR
+.sp
+void
+\fBTk_FreeTextLayout(\fIlayout\fB)\fR
+.sp
+void
+\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR
+.sp
+void
+\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR
+.sp
+int
+\fBTk_PointToChar(\fIlayout, x, y\fB)\fR
+.sp
+int
+\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
+.sp
+int
+\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR
+.sp
+int
+\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR
+.sp
+void
+\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR
+.SH ARGUMENTS
+.AS Tk_TextLayout "*xPtr, *yPtr"
+.AP Tk_Font tkfont in
+Font to use when constructing and displaying a text layout.  The
+\fItkfont\fR must remain valid for the lifetime of the text layout.  Must
+have been returned by a previous call to \fBTk_GetFont\fR.
+.AP "const char" *string in
+Potentially multi-line string whose dimensions are to be computed and
+stored in the text layout.  The \fIstring\fR must remain valid for the
+lifetime of the text layout.
+.AP int numChars in
+The number of characters to consider from \fIstring\fR.  If
+\fInumChars\fR is less than 0, then assumes \fIstring\fR is null
+terminated and uses \fBTcl_NumUtfChars\fR to determine the length of
+\fIstring\fR.
+.AP int wrapLength in
+Longest permissible line length, in pixels.  Lines in \fIstring\fR will
+automatically be broken at word boundaries and wrapped when they reach
+this length.  If \fIwrapLength\fR is too small for even a single
+character to fit on a line, it will be expanded to allow one character to
+fit on each line.  If \fIwrapLength\fR is <= 0, there is no automatic
+wrapping; lines will get as long as they need to be and only wrap if a
+newline/return character is encountered.
+.AP Tk_Justify justify in
+How to justify the lines in a multi-line text layout.  Possible values
+are \fBTK_JUSTIFY_LEFT\fR, \fBTK_JUSTIFY_CENTER\fR, or
+\fBTK_JUSTIFY_RIGHT\fR. If the text layout only occupies a single
+line, then \fIjustify\fR is irrelevant.
+.AP int flags in
+Various flag bits OR-ed together. \fBTK_IGNORE_TABS\fR means that tab
+characters should not be expanded to the next tab stop.
+\fBTK_IGNORE_NEWLINES\fR means that newline/return characters should
+not cause a line break.  If either tabs or newlines/returns are
+ignored, then they will be treated as regular characters, being
+measured and displayed in a platform-dependent manner as described in
+\fBTk_MeasureChars\fR, and will not have any special behaviors.
+.AP int *widthPtr out
+If non-NULL, filled with either the width, in pixels, of the widest
+line in the text layout, or the width, in pixels, of the bounding box for the
+character specified by \fIindex\fR.
+.AP int *heightPtr out
+If non-NULL, filled with either the total height, in pixels, of all
+the lines in the text layout, or the height, in pixels, of the bounding
+box for the character specified by \fIindex\fR.
+.AP Tk_TextLayout layout in
+A token that represents the cached layout information about the single-font,
+multi-line, justified piece of text.  This token is returned by
+\fBTk_ComputeTextLayout\fR.
+.AP Display *display in
+Display on which to draw.
+.AP Drawable drawable in
+Window or pixmap in which to draw.
+.AP GC gc in
+Graphics context to use for drawing text layout.  The font selected in
+this GC must correspond to the \fItkfont\fR used when constructing the
+text layout.
+.AP int "x, y" in
+Point, in pixels, at which to place the upper-left hand corner of the
+text layout when it is being drawn, or the coordinates of a point (with
+respect to the upper-left hand corner of the text layout) to check
+against the text layout.
+.AP int firstChar in
+The index of the first character to draw from the given text layout.
+The number 0 means to draw from the beginning.
+.AP int lastChar in
+The index of the last character up to which to draw.  The character
+specified by \fIlastChar\fR itself will not be drawn.  A number less
+than 0 means to draw all characters in the text layout.
+.AP int underline in
+Index of the single character to underline in the text layout, or a number
+less than 0 for no underline.
+.AP int index in
+The index of the character whose bounding box is desired.  The bounding
+box is computed with respect to the upper-left hand corner of the text layout.
+.AP int "*xPtr, *yPtr" out
+Filled with the upper-left hand corner, in pixels, of the bounding box
+for the character specified by \fIindex\fR.  Either or both \fIxPtr\fR
+and \fIyPtr\fR may be NULL, in which case the corresponding value
+is not calculated.
+.AP int "width, height" in
+Specifies the width and height, in pixels, of the rectangular area to
+compare for intersection against the text layout.
+.AP Tcl_Interp *interp out
+Postscript code that will print the text layout is appended to
+the result of interpreter \fIinterp\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These routines are for measuring and displaying single-font, multi-line,
+justified text.  To measure and display simple single-font, single-line
+strings, refer to the documentation for \fBTk_MeasureChars\fR.  There is
+no programming interface in the core of Tk that supports multi-font,
+multi-line text; support for that behavior must be built on top of
+simpler layers.
+Note that unlike the lower level text display routines, the functions
+described here all operate on character-oriented lengths and indices
+rather than byte-oriented values.  See the description of
+\fBTcl_UtfAtIndex\fR for more details on converting between character
+and byte offsets.
+.PP
+The routines described here are built on top of the programming interface
+described in the \fBTk_MeasureChars\fR documentation.  Tab characters and
+newline/return characters may be treated specially by these procedures,
+but all other characters are passed through to the lower level.
+.PP
+\fBTk_ComputeTextLayout\fR computes the layout information needed to
+display a single-font, multi-line, justified \fIstring\fR of text and
+returns a Tk_TextLayout token that holds this information.  This token is
+used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR,
+\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR.  The
+\fIstring\fR and \fItkfont\fR used when computing the layout must remain
+valid for the lifetime of this token.
+.PP
+\fBTk_FreeTextLayout\fR is called to release the storage associated with
+\fIlayout\fR when it is no longer needed.  A \fIlayout\fR should not be used
+in any other text layout procedures once it has been released.
+.PP
+\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a
+single-font, multi-line, justified string of text at the specified location.
+.PP
+\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to
+display an underline below an individual character.  This procedure does
+not draw the text, just the underline.  To produce natively underlined
+text, an underlined font should be constructed and used.  All characters,
+including tabs, newline/return characters, and spaces at the ends of
+lines, can be underlined using this method.  However, the underline will
+never be drawn outside of the computed width of \fIlayout\fR; the
+underline will stop at the edge for any character that would extend
+partially outside of \fIlayout\fR, and the underline will not be visible
+at all for any character that would be located completely outside of the
+layout.
+.PP
+\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the
+character closest to the given point.  The point is specified with respect
+to the upper-left hand corner of the \fIlayout\fR, which is considered to be
+located at (0, 0).  Any point whose \fIy\fR-value is less that 0 will be
+considered closest to the first character in the text layout; any point
+whose \fIy\fR-value is greater than the height of the text layout will be
+considered closest to the last character in the text layout.  Any point
+whose \fIx\fR-value is less than 0 will be considered closest to the first
+character on that line; any point whose \fIx\fR-value is greater than the
+width of the text layout will be considered closest to the last character on
+that line.  The return value is the index of the character that was closest
+to the point, or one more than the index of any character (to indicate that
+the point was after the end of the string and that the corresponding caret
+would be at the end of the string).  Given a \fIlayout\fR with no characters,
+the value 0 will always be returned, referring to a hypothetical zero-width
+placeholder character.
+.PP
+\fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the
+bounding box for the character specified by \fIindex\fR.  The width of the
+bounding box is the advance width of the character, and does not include any
+left or right bearing.  Any character that extends partially outside of
+\fIlayout\fR is considered to be truncated at the edge.  Any character
+that would be located completely outside of \fIlayout\fR is considered to
+be zero-width and pegged against the edge.  The height of the bounding
+box is the line height for this font, extending from the top of the
+ascent to the bottom of the descent; information about the actual height
+of individual letters is not available.  For measurement purposes, a
+\fIlayout\fR that contains no characters is considered to contain a
+single zero-width placeholder character at index 0.  If \fIindex\fR was
+not a valid character index, the return value is 0 and \fI*xPtr\fR,
+\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified.
+Otherwise, if \fIindex\fR did specify a valid, the return value is
+non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and
+\fI*heightPtr\fR are filled with the bounding box information for the
+character.  If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or
+\fIheightPtr\fR are NULL, the corresponding value is not calculated or
+stored.
+.PP
+\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from
+the given point (\fIx, y\fR) to the characters in \fIlayout\fR.
+Newline/return characters and non-displaying space characters that occur at
+the end of individual lines in the text layout are ignored for hit detection
+purposes, but tab characters are not.  The return value is 0 if the point
+actually hits the \fIlayout\fR.  If the point did not hit the \fIlayout\fR
+then the return value is the distance in pixels from the point to the
+\fIlayout\fR.
+.PP
+\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies
+entirely inside, entirely outside, or overlaps a given rectangle.
+Newline/return characters and non-displaying space characters that occur
+at the end of individual lines in the \fIlayout\fR are ignored for
+intersection calculations.  The return value is \-1 if the \fIlayout\fR is
+entirely outside of the rectangle, 0 if it overlaps, and 1 if it is
+entirely inside of the rectangle.
+.PP
+\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript
+array of strings that represent the individual lines in \fIlayout\fR.  It
+is the responsibility of the caller to take the Postscript array of
+strings and add some Postscript function operate on the array to render
+each of the lines.  The code that represents the Postscript array of
+strings is appended to interpreter \fIinterp\fR's result.
+.SH "DISPLAY MODEL"
+.PP
+When measuring a text layout, space characters that occur at the end of a
+line are ignored.  The space characters still exist and the insertion point
+can be positioned amongst them, but their additional width is ignored when
+justifying lines or returning the total width of a text layout.  All
+end-of-line space characters are considered to be attached to the right edge
+of the line; this behavior is logical for left-justified text and reasonable
+for center-justified text, but not very useful when editing right-justified
+text.  Spaces are considered variable width characters; the first space that
+extends past the edge of the text layout is clipped to the edge, and any
+subsequent spaces on the line are considered zero width and pegged against
+the edge.  Space characters that occur in the middle of a line of text are
+not suppressed and occupy their normal space width.
+.PP
+Tab characters are not ignored for measurement calculations.  If wrapping
+is turned on and there are enough tabs on a line, the next tab will wrap
+to the beginning of the next line.  There are some possible strange
+interactions between tabs and justification; tab positions are calculated
+and the line length computed in a left-justified world, and then the
+whole resulting line is shifted so it is centered or right-justified,
+causing the tab columns not to align any more.
+.PP
+When wrapping is turned on, lines may wrap at word breaks (space or tab
+characters) or newline/returns.  A dash or hyphen character in the middle
+of a word is not considered a word break.  \fBTk_ComputeTextLayout\fR
+always attempts to place at least one word on each line.  If it cannot
+because the \fIwrapLength\fR is too small, the word will be broken and as
+much as fits placed on the line and the rest on subsequent line(s).  If
+\fIwrapLength\fR is so small that not even one character can fit on a
+given line, the \fIwrapLength\fR is ignored for that line and one
+character will be placed on the line anyhow.  When wrapping is turned
+off, only newline/return characters may cause a line break.
+.PP
+When a text layout has been created using an underlined \fItkfont\fR,
+then any space characters that occur at the end of individual lines,
+newlines/returns, and tabs will not be displayed underlined when
+\fBTk_DrawTextLayout\fR is called, because those characters are never
+actually drawn \- they are merely placeholders maintained in the
+\fIlayout\fR.
+.SH KEYWORDS
+font