189 lines
8.1 KiB
Groff
189 lines
8.1 KiB
Groff
'\"
|
|
'\" 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.
|
|
'\"
|
|
'\" SCCS: @(#) GetCursor.3 1.23 96/08/27 13:21:26
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_GetCursor 3 4.1 Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor \- maintain database of cursors
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
Tk_Cursor
|
|
\fBTk_GetCursor(\fIinterp, tkwin, nameId\fB)\fR
|
|
.sp
|
|
Tk_Cursor
|
|
\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR
|
|
.sp
|
|
char *
|
|
\fBTk_NameOfCursor(\fIdisplay, cursor\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 Tk_Uid nameId in
|
|
Description of cursor; see below for possible values.
|
|
.AP char *source in
|
|
Data for cursor bitmap, in standard bitmap format.
|
|
.AP char *mask in
|
|
Data for mask bitmap, in standard bitmap 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 (actually Tk_Uids).
|
|
.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
|
|
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 font,
|
|
i.e., any of the names defined in \fBcursorfont.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
|
|
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.
|
|
|
|
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
|
|
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 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.
|
|
.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.
|
|
\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.
|
|
.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
|
|
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_GetCursor\fR and \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.
|
|
.PP
|
|
\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
|
|
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.
|
|
.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
|
|
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_GetCursor\fR or \fBTk_GetCursorFromData\fR
|
|
is no longer needed, \fBTk_FreeCursor\fR should be called to release it.
|
|
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.
|
|
|
|
.SH BUGS
|
|
In determining whether an existing cursor can be used to satisfy
|
|
a new request, \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
|