* Merged 8.1 branch into the main trunk

1 files changed, 94 insertions, 41 deletions

diff --git a/doc/GetCursor.3 b/doc/GetCursor.3
index dca27ad..55b9c58 100644
--- a/doc/GetCursor.3
+++ b/doc/GetCursor.3
@@ -1,23 +1,31 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" 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.
 '\" 
-'\" RCS: @(#) $Id: GetCursor.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
+'\" RCS: @(#) $Id: GetCursor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetCursor 3 4.1 Tk "Tk Library Procedures"
+.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor \- maintain database of cursors
+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
+.VS 8.1
 Tk_Cursor
-\fBTk_GetCursor(\fIinterp, tkwin, nameId\fB)\fR
+\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
+.VE
 .sp
 Tk_Cursor
 \fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR
@@ -25,6 +33,10 @@ Tk_Cursor
 char *
 \fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR
 .sp
+.VS 8.1
+\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR
 .SH ARGUMENTS
 .AS "unsigned long" *pixelPtr
@@ -32,12 +44,18 @@ char *
 Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window in which the cursor will be used.
-.AP Tk_Uid nameId in
-Description of cursor;  see below for possible values.
+.VS 8.1 br
+.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 isn't cached.
+.VE
 .AP char *source in
-Data for cursor bitmap, in standard bitmap format.
+Data for cursor cursor, in standard cursor format.
 .AP char *mask in
-Data for mask bitmap, in standard bitmap format.
+Data for mask cursor, in standard cursor format.
 .AP "int" width in
 Width of \fIsource\fR and \fImask\fR.
 .AP "int" height in
@@ -53,7 +71,7 @@ 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
+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
@@ -63,18 +81,25 @@ have been returned by some previous call to \fBTk_GetCursor\fR or
 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 (actually Tk_Uids).
+allow cursors to be named with character strings.
 .PP
-\fBTk_GetCursor\fR takes as argument a Tk_Uid 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.  \fINameId\fR must be a standard Tcl
+.VS 8.1
+\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 isn't NULL.  \fIObjPtr\fR must contain a standard Tcl
 list with one of the following forms:
+.VE
 .TP
 \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]]
-\fIName\fR is the name of a cursor in the standard X cursor font,
-i.e., any of the names defined in \fBcursorfont.h\fR, without
+\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 ``The X Window System''
 by Scheifler & Gettys has illustrations showing what each of these
@@ -86,9 +111,10 @@ 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.
-
-The Macintosh version of Tk also supports all of the X cursors.
-Tk on the Mac will also accept any of the standard Mac cursors
+.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
@@ -96,11 +122,12 @@ name of the 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 bitmaps for the cursor's source bits and mask.
-Each file must be in standard X11 or X10 bitmap format.
+files describing cursors for the cursor's source bits and mask.
+Each file must be in standard X11 or X10 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
@@ -112,10 +139,27 @@ 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.
 .PP
+.VS 8.1
+\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 doesn't 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.
+.VE
+.PP
 \fBTk_GetCursorFromData\fR allows cursors to be created from
-in-memory descriptions of their source and mask bitmaps.  \fISource\fR
-points to standard bitmap data for the cursor's source bits, and
-\fImask\fR points to standard bitmap data describing
+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
@@ -135,24 +179,26 @@ cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
 	source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
 .CE
 .PP
-Under normal conditions, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR
+Under normal conditions \fBTk_GetCursorFromData\fR
 will return an identifier for the requested cursor.  If an error
-occurs in creating the cursor, such as when \fInameId\fR refers
-to a non-existent file, then \fBNone\fR is returned and an error
-message will be stored in \fIinterp->result\fR.
+occurs in creating the cursor then \fBNone\fR is returned and an error
+message will be stored in \fIinterp\fR's result.
 .PP
-\fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR maintain a
+\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_GetCursor\fR or \fBTk_GetCursorFromData\fR will
+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.
+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 \fInameId\fR
+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
@@ -162,17 +208,24 @@ 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_GetCursor\fR or \fBTk_GetCursorFromData\fR
-is no longer needed, \fBTk_FreeCursor\fR should be called to release it.
+.VS 8.1
+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_GetCursor\fR or \fBTk_GetCursorFromData\fR.
-When a cursor is no longer in use anywhere (i.e. it has been freed as
-many times as it has been gotten) \fBTk_FreeCursor\fR will release
-it to the X server and remove it from the database.
+each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+or \fBTk_GetCursorFromData\fR.
+.VE
 
 .SH BUGS
 In determining whether an existing cursor can be used to satisfy
-a new request, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR
+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