ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import Tk 8.5.15 (as of svn r89086)

Browse Source
This commit is contained in:
Zachary Ware
2017-09-04 14:25:47 -05:00
parent 4b29e0458f
commit 27e7dfc7da
883 changed files with 499023 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

295
doc/3DBorder.3 Normal file
View File

@@ -0,0 +1,295 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
.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 object 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 an object.
.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 object 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 object; 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 object; 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 in \fIinterp->result\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 an object. 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 object, and
\fIrelief\fR indicates the relief of the inside of the object 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, object, polygon, raised, shadow, three-dimensional effect

52
doc/AddOption.3 Normal file
View File

@@ -0,0 +1,52 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH Tk_AddOption 3 "" Tk "Tk Library Procedures"
.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

155
doc/BindTable.3 Normal file
View File

@@ -0,0 +1,155 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
.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 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 in \fIinterp->result\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 \fIinterp->result\fR 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 in \fIinterp->result\fR.
.PP
\fBTk_GetAllBindings\fR returns in \fIinterp->result\fR 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 then an empty
string is returned in \fIinterp->result\fR.
.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

120
doc/CanvPsY.3 Normal file
View File

@@ -0,0 +1,120 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures"
.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 \fIinterp->result\fR and \fBTCL_OK\fR is returned
unless an error occurs, in which case \fBTCL_ERROR\fR is returned and
\fIinterp->result\fR 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 \fIinterp->result\fR and returns
\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is returned and
\fIinterp->result\fR 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 \fIinterp->result\fR and returns \fBTCL_OK\fR
unless an error occurs, in which case \fBTCL_ERROR\fR is returned and
\fIinterp->result\fR 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 \fIinterp->result\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 \fIinterp->result\fR and \fBTCL_OK\fR is
returned, unless an error occurs, in which case \fBTCL_ERROR\fR is returned and
\fIinterp->result\fR is overwritten with an error message.
.SH KEYWORDS
bitmap, canvas, color, font, path, Postscript, stipple

159
doc/CanvTkwin.3 Normal file
View File

@@ -0,0 +1,159 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
.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 \fIinterp->result\fR 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:
.CS
static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
Tk_CanvasTagsPrintProc, (ClientData) NULL
};
static Tk_ConfigSpec configSpecs[] = {
...
{TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL,
(char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
...
};
.CE
.SH KEYWORDS
canvas, focus, item type, redisplay, selection, type manager

102
doc/CanvTxtInfo.3 Normal file
View File

@@ -0,0 +1,102 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures"
.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;
} Tk_CanvasTextInfo;
.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

78
doc/Clipboard.3 Normal file
View File

@@ -0,0 +1,78 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures"
.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 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 \fIinterp->result\fR.
\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
\fIinterp->result\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 reentrant at the point
\fBTk_ClipboardClear\fR is invoked.
.SH KEYWORDS
append, clipboard, clear, format, type

40
doc/ClrSelect.3 Normal file
View File

@@ -0,0 +1,40 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures"
.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

643
doc/ConfigWidg.3 Normal file
View File

@@ -0,0 +1,643 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
.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 Tk_ConfigSpec *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 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 \fIinterp->result\fR 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;
char *\fIargvName\fR;
char *\fIdbName\fR;
char *\fIdbClass\fR;
char *\fIdefValue\fR;
int \fIoffset\fR;
int \fIspecFlags\fR;
Tk_CustomOption *\fIcustomPtr\fR;
} Tk_ConfigSpec;
.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
.VS 8.5
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.
.VE 8.5
.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 \fIinterp->result\fR. Under normal circumstances
it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR
and \fIinterp->result\fR contains an error message.
.PP
If \fIargvName\fR is NULL, then the value left in
\fIinterp->result\fR 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 \fIinterp->result\fR 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 \fIinterp->result\fR 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 \fIinterp->result\fR.
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;
} Tk_CustomOption;
typedef int Tk_OptionParseProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
Tk_Window \fItkwin\fR,
char *\fIvalue\fR,
char *\fIwidgRec\fR,
int \fIoffset\fR);
typedef char *Tk_OptionPrintProc(
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 \fIinterp->result\fR.
.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

147
doc/ConfigWind.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures"
.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

49
doc/CoordToWin.3 Normal file
View File

@@ -0,0 +1,49 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures"
.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

67
doc/CrtCmHdlr.3 Normal file
View File

@@ -0,0 +1,67 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures"
.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 Tk_ClientMessageProc(
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

44
doc/CrtConsoleChan.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures"
.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

141
doc/CrtErrHdlr.3 Normal file
View File

@@ -0,0 +1,141 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures"
.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 Tk_ErrorProc(
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

82
doc/CrtGenHdlr.3 Normal file
View File

@@ -0,0 +1,82 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures"
.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 Tk_GenericProc(
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

291
doc/CrtImgType.3 Normal file
View File

@@ -0,0 +1,291 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
.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 Tk_ImageType *typePtrPtr
.AP Tk_ImageType *typePtr in
Structure that defines the new type of image.
Must be static: a
pointer to this structure is retained by the image code.
.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 {
char *\fIname\fR;
Tk_ImageCreateProc *\fIcreateProc\fR;
Tk_ImageGetProc *\fIgetProc\fR;
Tk_ImageDisplayProc *\fIdisplayProc\fR;
Tk_ImageFreeProc *\fIfreeProc\fR;
Tk_ImageDeleteProc *\fIdeleteProc\fR;
} Tk_ImageType;
.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
\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 Tk_ImageCreateProc(
Tcl_Interp *\fIinterp\fR,
char *\fIname\fR,
int \fIobjc\fR,
Tcl_Obj *const \fIobjv\fR[],
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 Tk_ImageGetProc(
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 Tk_ImageDisplayProc(
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 Tk_ImageFreeProc(
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 Tk_ImageDeleteProc(
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"
In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR
was incompatibly different, with the following prototype:
.CS
typedef int Tk_ImageCreateProc(
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

602
doc/CrtItemType.3 Normal file
View File

@@ -0,0 +1,602 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
.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 (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:
.CS
typedef struct Tk_ItemType {
char *\fIname\fR;
int \fIitemSize\fR;
Tk_ItemCreateProc *\fIcreateProc\fR;
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;
} Tk_ItemType;
.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:
.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;
} BitmapItem;
.CE
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.
.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 ITEMSIZE
\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:
.CS
typedef int Tk_ItemCreateProc(
Tcl_Interp *\fIinterp\fR,
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIobjc\fR,
Tcl_Obj* const \fIobjv\fR[]);
.CE
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.
For example, in the widget command
.CS
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
.CE
\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 \fIinterp->result\fR 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:
.CS
typedef int Tk_ItemConfigureProc(
Tcl_Interp *\fIinterp\fR,
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIobjc\fR,
Tcl_Obj* const \fIobjv\fR[],
int \fIflags\fR);
.CE
The \fIinterp\fR objument 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. For
example, if the following command is invoked:
.CS
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
.CE
\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 \fIinterp->result\fR 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:
.CS
typedef int Tk_ItemCoordProc(
Tcl_Interp *\fIinterp\fR,
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIobjc\fR,
Tcl_Obj* const \fIobjv\fR[]);
.CE
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
describe the coordinate arguments.
For example, if the following widget command is invoked:
.CS
\fB\&.c coords 2 30 90\fR
.CE
\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
\fIinterp->result\fR.
.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:
.CS
typedef void Tk_ItemDeleteProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
Display *\fIdisplay\fR);
.CE
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 AND ALWAYSREDRAW"
.PP
\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
on the screen.
It must match the following prototype:
.CS
typedef void Tk_ItemDisplayProc(
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
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 \fItypePtr->alwaysRedraw\fR has a non-zero value, then
\fIdisplayProc\fR is invoked during every redisplay operation,
even if the item does not overlap the area of redisplay.
\fIalwaysRedraw\fR should normally be set to 0; it is only
set to 1 in special cases such as window items that need to be
unmapped when they are off-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:
.CS
typedef double Tk_ItemPointProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
double *\fIpointPtr\fR);
.CE
\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:
.CS
typedef int Tk_ItemAreaProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
double *\fIrectPtr\fR);
.CE
\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:
.CS
typedef int Tk_ItemPostscriptProc(
Tcl_Interp *\fIinterp\fR,
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIprepass\fR);
.CE
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 \fIinterp->result\fR
(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
\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:
.CS
typedef void Tk_ItemScaleProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
double \fIoriginX\fR,
double \fIoriginY\fR,
double \fIscaleX\fR,
double \fIscaleY\fR);
.CE
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
.CS
\fIx\(fm = originX + scaleX*(x-originX)
y\(fm = originY + scaleY*(y-originY)\fR
.CE
\fIscaleProc\fR must also update the bounding box in the item's
header.
.SS TRANSLATEPROC
\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:
.CS
typedef void Tk_ItemTranslateProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
double \fIdeltaX\fR,
double \fIdeltaY\fR);
.CE
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
\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;
\fItypePtr->indexProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemIndexProc(
Tcl_Interp *\fIinterp\fR,
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
char \fIindexString\fR,
int *\fIindexPtr\fR);
.CE
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
have the usual meaning.
\fIindexString\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.
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
\fIinterp->result\fR 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:
.CS
typedef void Tk_ItemCursorProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIindex\fR);
.CE
\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:
.CS
typedef int Tk_ItemSelectionProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIoffset\fR,
char *\fIbuffer\fR,
int \fImaxBytes\fR);
.CE
\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 into a
canvas item.
It is only relevant for item types that support text;
\fItypePtr->insertProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemInsertProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIindex\fR,
char *\fIstring\fR);
.CE
\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 \fIstring\fR
contains new text to insert just before the character given
by \fIindex\fR.
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.
It is only relevant for item types that support text;
\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemDCharsProc(
Tk_Canvas \fIcanvas\fR,
Tk_Item *\fIitemPtr\fR,
int \fIfirst\fR,
int \fIlast\fR);
.CE
\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

274
doc/CrtPhImgFmt.3 Normal file
View File

@@ -0,0 +1,274 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures"
.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 Tk_PhotoImageFormat *formatPtr
.AP 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 {
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;
} Tk_PhotoImageFormat;
.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.
.SH 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).
.SH FILEMATCHPROC
\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 Tk_ImageFileMatchProc(
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.
.SH STRINGMATCHPROC
\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 Tk_ImageStringMatchProc(
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.
.SH FILEREADPROC
\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 Tk_ImageFileReadProc(
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.
.SH STRINGREADPROC
\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 Tk_ImageStringReadProc(
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.
.SH FILEWRITEPROC
\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 Tk_ImageFileWriteProc(
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.
.SH STRINGWRITEPROC
\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 Tk_ImageStringWriteProc(
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"
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

117
doc/CrtSelHdlr.3 Normal file
View File

@@ -0,0 +1,117 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures"
.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 Tk_SelectionProc(
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

147
doc/CrtWindow.3 Normal file
View File

@@ -0,0 +1,147 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures"
.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 \fIinterp->result\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 manipulable
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

33
doc/DeleteImg.3 Normal file
View File

@@ -0,0 +1,33 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures"
.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

38
doc/DrawFocHlt.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures"
.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

77
doc/EventHndlr.3 Normal file
View File

@@ -0,0 +1,77 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures"
.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 Tk_EventProc(
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

260
doc/FindPhoto.3 Normal file
View File

@@ -0,0 +1,260 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
.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
.VS 8.5
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)
.VE 8.5
.sp
int
\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
.sp
void
\fBTk_PhotoBlank\fR(\fIhandle\fR)
.sp
.VS 8.5
int
\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR)
.VE 8.5
.sp
void
\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
.sp
.VS 8.5
int
\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR)
.VE 8.5
.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.
.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[4]\fR;
} Tk_PhotoImageBlock;
.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. Often it is 3
or 4, but it can have any value. 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. These are normally 0, 1, 2 and 3, but can
have other values, e.g., for images that are stored as separate red,
green and blue planes.
.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
.VS 8.5
\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.
.VE 8.5
.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.
\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
.VS 8.5
\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.
.VE 8.5
.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
.VS 8.5
\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.
.VE 8.5
.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
.VS 8.5
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.
.VE 8.5
.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

93
doc/FontId.3 Normal file
View File

@@ -0,0 +1,93 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures"
.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"
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;
} Tk_FontMetrics;
.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

48
doc/FreeXId.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures"
.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

94
doc/GeomReq.3 Normal file
View File

@@ -0,0 +1,94 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures"
.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

86
doc/GetAnchor.3 Normal file
View File

@@ -0,0 +1,86 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures"
.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 n ,
.QW ne ,
.QW e ,
.QW se ,
.QW s ,
.QW sw ,
.QW w ,
.QW nw ,
or
.QW center ;
internal rep will be modified to cache corresponding Tk_Anchor.
.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

298
doc/GetBitmap.3 Normal file
View File

@@ -0,0 +1,298 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
.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 char" *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 or X10 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
\fIinterp->result\fR.
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
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

65
doc/GetCapStyl.3 Normal file
View File

@@ -0,0 +1,65 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures"
.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 butt ,
.QW projecting ,
or
.QW round .
.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 \fIinterp->result\fR, \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

77
doc/GetClrmap.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures"
.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

177
doc/GetColor.3 Normal file
View File

@@ -0,0 +1,177 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
.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 an
object 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 an object. 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, object, pixel value

233
doc/GetCursor.3 Normal file
View File

@@ -0,0 +1,233 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures"
.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 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
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
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

78
doc/GetDash.3 Normal file
View File

@@ -0,0 +1,78 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetDash \- convert from string to valid dash structure.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR)
.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.
.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
or spaces. If all
goes well, \fBTCL_OK\fR is returned. 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 as the first position in the string. Some examples:
.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 of this syntax with the previous 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
assures 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 as the first one.
.SH KEYWORDS
dash, conversion

112
doc/GetFont.3 Normal file
View File

@@ -0,0 +1,112 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures"
.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

72
doc/GetGC.3 Normal file
View File

@@ -0,0 +1,72 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetGC 3 "" Tk "Tk Library Procedures"
.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

22
doc/GetHINSTANCE.3 Normal file
View File

@@ -0,0 +1,22 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures"
.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

37
doc/GetHWND.3 Normal file
View File

@@ -0,0 +1,37 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH HWND 3 8.0 Tk "Tk Library Procedures"
.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

133
doc/GetImage.3 Normal file
View File

@@ -0,0 +1,133 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
.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 \fIinterp->result\fR.
.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 Tk_ImageChangedProc(
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

64
doc/GetJoinStl.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures"
.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 bevel ,
.QW miter ,
or
.QW round .
.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 \fIinterp->result\fR, \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

87
doc/GetJustify.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures"
.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 left ,
.QW right ,
or
.QW center .
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

44
doc/GetOption.3 Normal file
View File

@@ -0,0 +1,44 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetOption 3 "" Tk "Tk Library Procedures"
.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

97
doc/GetPixels.3 Normal file
View File

@@ -0,0 +1,97 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures"
.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_GetAnchor\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

54
doc/GetPixmap.3 Normal file
View File

@@ -0,0 +1,54 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures"
.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

81
doc/GetRelief.3 Normal file
View File

@@ -0,0 +1,81 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures"
.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 flat ,
.QW groove ,
.QW raised ,
.QW ridge ,
.QW solid ,
or
.QW sunken ;
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

39
doc/GetRootCrd.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures"
.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

76
doc/GetScroll.3 Normal file
View File

@@ -0,0 +1,76 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetScrollInfo, Tk_GetScrollInfoObj \- parse arguments for scrolling commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR
.sp
int
\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR
.SH ARGUMENTS
.AS "Tcl_Interp" *dblPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.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 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 double *dblPtr out
Filled in with fraction from \fBmoveto\fR option, if any.
.AP int *intPtr out
Filled in with line or page count from \fBscroll\fR option, if any.
The value may be negative.
.BE
.SH DESCRIPTION
.PP
\fBTk_GetScrollInfo\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 \fIargv\fR[2].
The words starting with \fIargv\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 \fIargv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR
is returned as result and \fI*dblPtr\fR is filled in with the
\fIfraction\fR argument to the command, which must be a proper real
value.
If \fIargv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR
or \fBTK_SCROLL_PAGES\fR is returned and \fI*intPtr\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 \fIinterp->result\fR.
.PP
\fBTk_GetScrollInfoObj\fR is identical in function to
\fBTk_GetScrollInfo\fR. However, \fBTk_GetScrollInfoObj\fR accepts
Tcl_Obj style arguments, making it more appropriate for use with new
development.
.SH KEYWORDS
parse, scrollbar, scrolling command, xview, yview

77
doc/GetSelect.3 Normal file
View File

@@ -0,0 +1,77 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures"
.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:
.CS
typedef int Tk_GetSelProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
char *\fIportion\fR);
.CE
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 \fIinterp->result\fR. \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 \fIinterp->result\fR
and return \fBTCL_ERROR\fR; this will abort the selection retrieval.
.SH KEYWORDS
format, get, selection retrieval

47
doc/GetUid.3 Normal file
View File

@@ -0,0 +1,47 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_GetUid 3 "" Tk "Tk Library Procedures"
.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

48
doc/GetVRoot.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures"
.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

100
doc/GetVisual.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures"
.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 \fIinterp->result\fR.
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

63
doc/Grab.3 Normal file
View File

@@ -0,0 +1,63 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH Tk_Grab 3 "" Tk "Tk Library Procedures"
.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
\fBTcl_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

28
doc/HWNDToWindow.3 Normal file
View File

@@ -0,0 +1,28 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures"
.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

48
doc/HandleEvent.3 Normal file
View File

@@ -0,0 +1,48 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures"
.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
\fBTcl_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

34
doc/IdToWindow.3 Normal file
View File

@@ -0,0 +1,34 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures"
.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

67
doc/ImgChanged.3 Normal file
View File

@@ -0,0 +1,67 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures"
.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

36
doc/Inactive.3 Normal file
View File

@@ -0,0 +1,36 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures"
.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

57
doc/InternAtom.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures"
.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

30
doc/MainLoop.3 Normal file
View File

@@ -0,0 +1,30 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures"
.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

44
doc/MainWin.3 Normal file
View File

@@ -0,0 +1,44 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures"
.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 \fIinterp->result\fR.
.PP
\fBTk_GetNumMainWindows\fR returns a count of the number of main
windows currently open in the process.
.SH KEYWORDS
application, main window

100
doc/MaintGeom.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures"
.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

91
doc/ManageGeom.3 Normal file
View File

@@ -0,0 +1,91 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures"
.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;
} Tk_GeomMgr;
.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 Tk_GeomRequestProc(
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 Tk_GeomLostSlaveProc(
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

51
doc/MapWindow.3 Normal file
View File

@@ -0,0 +1,51 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures"
.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

127
doc/MeasureChar.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
.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

53
doc/MoveToplev.3 Normal file
View File

@@ -0,0 +1,53 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures"
.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

88
doc/Name.3 Normal file
View File

@@ -0,0 +1,88 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_Name 3 "" Tk "Tk Library Procedures"
.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 \fIinterp->result\fR
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

32
doc/NameOfImg.3 Normal file
View File

@@ -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.
'\"
.so man.macros
.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures"
.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

50
doc/OwnSelect.3 Normal file
View File

@@ -0,0 +1,50 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures"
.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 Tk_LostSelProc(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

358
doc/ParseArgv.3 Normal file
View File

@@ -0,0 +1,358 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
.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 \fIinterp->result\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 {
char *\fIkey\fR;
int \fItype\fR;
char *\fIsrc\fR;
char *\fIdst\fR;
char *\fIhelp\fR;
} Tk_ArgvInfo;
.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 \fIinterp->result\fR
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 \fIinterp->result\fR,
in the usual Tcl fashion, and return \-1; when this happens
\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
.RE
.SH "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", interp->result);
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

52
doc/QWinEvent.3 Normal file
View File

@@ -0,0 +1,52 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures"
.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

47
doc/Restack.3 Normal file
View File

@@ -0,0 +1,47 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures"
.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

80
doc/RestrictEv.3 Normal file
View File

@@ -0,0 +1,80 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures"
.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, clientData, prevClientDataPtr\fR)
.SH ARGUMENTS
.AS Tk_RestrictProc **prevClientDataPtr
.AP Tk_RestrictProc *proc in
Predicate procedure to call to filter incoming X events.
NULL means do not restrict events at all.
.AP ClientData clientData in
Arbitrary argument to pass to \fIproc\fR.
.AP ClientData *prevClientDataPtr 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 Tk_RestrictProc(
ClientData \fIclientData\fR,
XEvent *\fIeventPtr\fR);
.CE
The \fIclientData\fR argument is a copy of the \fIclientData\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 \fIprevClientDataPtr\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

64
doc/SetAppName.3 Normal file
View File

@@ -0,0 +1,64 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures"
.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

38
doc/SetCaret.3 Normal file
View File

@@ -0,0 +1,38 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures"
.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

59
doc/SetClass.3 Normal file
View File

@@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetClass 3 "" Tk "Tk Library Procedures"
.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

89
doc/SetClassProcs.3 Normal file
View File

@@ -0,0 +1,89 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures"
.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 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;
} Tk_ClassProcs;
.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 Tk_ClassWorldChangedProc(
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 Tk_ClassCreateProc(
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 Tk_ClassModalProc(
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

65
doc/SetGrid.3 Normal file
View File

@@ -0,0 +1,65 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures"
.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

646
doc/SetOptions.3 Normal file
View File

@@ -0,0 +1,646 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
.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.
\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, 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;
ClientData \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. At
present only a single flag is supported: \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.
.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

52
doc/SetVisual.3 Normal file
View File

@@ -0,0 +1,52 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures"
.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

40
doc/StrictMotif.3 Normal file
View File

@@ -0,0 +1,40 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures"
.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

275
doc/TextLayout.3 Normal file
View File

@@ -0,0 +1,275 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures"
.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
\fIinterp->result\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. 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 \fIinterp->result\fR.
.SH "DISPLAY MODEL"
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

75
doc/TkInitStubs.3 Normal file
View File

@@ -0,0 +1,75 @@
'\"
'\" Copyright (c) 1999 Scriptics Corporation
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
.TH Tk_InitStubs 3 8.4 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_InitStubs \- initialize the Tk stubs mechanism
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_InitStubs\fR(\fIinterp, version, exact\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp in
.AP Tcl_Interp *interp in
Tcl interpreter handle.
.AP char *version in
A version string consisting of one or more decimal numbers
separated by dots.
.AP int exact in
Non-zero means that only the particular Tk version specified by
\fIversion\fR is acceptable.
Zero means that versions newer than \fIversion\fR are also
acceptable as long as they have the same major version number
as \fIversion\fR.
.BE
.SH INTRODUCTION
.PP
The Tcl stubs mechanism defines a way to dynamically bind
extensions to a particular Tcl implementation at run time.
the stubs mechanism requires no changes to applications
incoporating Tcl/Tk interpreters. Only developers creating
C-based Tcl/Tk extensions need to take steps to use the
stubs mechanism with their extensions.
See the \fBTcl_InitStubs\fR page for more information.
.PP
Enabling the stubs mechanism for a Tcl/Tk extension requires the following
steps:
.IP 1) 5
Call \fBTcl_InitStubs\fR in the extension before calling any other
Tcl functions.
.IP 2) 5
Call \fBTk_InitStubs\fR if the extension before calling any other
Tk functions.
.IP 2) 5
Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the
\fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
.IP 3) 5
Link the extension with the Tcl and Tk stubs libraries instead of
the standard Tcl and Tk libraries. On Unix platforms, the library
names are \fIlibtclstub8.4.a\fR and \fIlibtkstub8.4.a\fR; on Windows
platforms, the library names are \fItclstub84.lib\fR and \fItkstub84.lib\fR
(adjust names with appropriate version number).
.SH DESCRIPTION
\fBTk_InitStubs\fR attempts to initialize the Tk stub table pointers
and ensure that the correct version of Tk is loaded. In addition
to an interpreter handle, it accepts as arguments a version number
and a Boolean flag indicating whether the extension requires
an exact version match or not. If \fIexact\fR is 0, then the
extension is indicating that newer versions of Tk are acceptable
as long as they have the same major version number as \fIversion\fR;
non-zero means that only the specified \fIversion\fR is acceptable.
\fBTcl_InitStubs\fR returns a string containing the actual version
of Tk satisfying the request, or NULL if the Tk version is not
acceptable, does not support the stubs mechanism, or any other
error condition occurred.
.SH "SEE ALSO"
\fBTcl_InitStubs\fR
.SH KEYWORDS
stubs

87
doc/Tk_Init.3 Normal file
View File

@@ -0,0 +1,87 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_Init 3 8.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Init, Tk_SafeInit \- add Tk to an interpreter and make a new Tk application.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_Init\fR(\fIinterp\fR)
.sp
int
\fBTk_SafeInit\fR(\fIinterp\fR)
.SH ARGUMENTS
.AP Tcl_Interp *interp in
Interpreter in which to load Tk. Tk should not already be loaded
in this interpreter.
.BE
.SH DESCRIPTION
.PP
\fBTk_Init\fR is the package initialization procedure for Tk.
It is normally invoked by the \fBTcl_AppInit\fR procedure
for an application or by the \fBload\fR command.
\fBTk_Init\fR adds all of Tk's commands to \fIinterp\fR
and creates a new Tk application, including its main window.
If the initialization is successful \fBTk_Init\fR returns
\fBTCL_OK\fR; if there is an error it returns \fBTCL_ERROR\fR.
\fBTk_Init\fR also leaves a result or error message
in \fIinterp->result\fR.
.PP
If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR
treats the contents of this variable as a list of options for the
new Tk application.
The options may have any of the forms documented for the
\fBwish\fR application (in fact, \fBwish\fR uses Tk_Init to process
its command-line arguments).
.PP
\fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes
all Tk commands that are considered unsafe. Those commands and the
reasons for their exclusion are:
.TP
\fBbell\fR
Continuous ringing of the bell is a nuisance.
.TP
\fBclipboard\fR
A malicious script could replace the contents of the clipboard with
the string
.QW "\fBrm \-r *\fR"
and lead to surprises when the contents of the clipboard are pasted.
.TP
\fBgrab\fR
Grab can be used to block the user from using any other applications.
.TP
\fBmenu\fR
Menus can be used to cover the entire screen and to steal input from
the user.
.TP
\fBselection\fR
See clipboard.
.TP
\fBsend\fR
Send can be used to cause unsafe interpreters to execute commands.
.TP
\fBtk\fR
The tk command recreates the send command, which is unsafe.
.TP
\fBtkwait\fR
Tkwait can block the containing process forever
.TP
\fBtoplevel\fR
Toplevels can be used to cover the entire screen and to steal input
from the user.
.TP
\fBwm\fR
If toplevels are ever allowed, wm can be used to remove decorations,
move windows around, etc.
.SH KEYWORDS
safe, application, initialization, load, main window

60
doc/Tk_Main.3 Normal file
View File

@@ -0,0 +1,60 @@
'\"
'\" 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.
'\"
.so man.macros
.TH Tk_Main 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Main \- main program for Tk-based applications
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_Main\fR(\fIargc, argv, appInitProc\fR)
.SH ARGUMENTS
.AS Tcl_AppInitProc *appInitProc
.AP int argc in
Number of elements in \fIargv\fR.
.AP char *argv[] in
Array of strings containing command-line arguments.
.AP Tcl_AppInitProc *appInitProc in
Address of an application-specific initialization procedure.
The value for this argument is usually \fBTcl_AppInit\fR.
.BE
.SH DESCRIPTION
.PP
\fBTk_Main\fR acts as the main program for most Tk-based applications.
Starting with Tk 4.0 it is not called \fBmain\fR anymore because it
is part of the Tk library and having a function \fBmain\fR
in a library (particularly a shared library) causes problems on many
systems.
Having \fBmain\fR in the Tk library would also make it hard to use
Tk in C++ programs, since C++ programs must have special C++
\fBmain\fR functions.
.PP
Normally each application contains a small \fBmain\fR function that does
nothing but invoke \fBTk_Main\fR.
\fBTk_Main\fR then does all the work of creating and running a
\fBwish\fR-like application.
.PP
When it is has finished its own initialization, but before
it processes commands, \fBTk_Main\fR calls the procedure given by
the \fIappInitProc\fR argument. This procedure provides a
.QW hook
for the application to perform its own initialization, such as defining
application-specific commands. The procedure must have an interface
that matches the type \fBTcl_AppInitProc\fR:
.CS
typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
.CE
\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR;
for more details on this procedure, see the documentation
for \fBTcl_AppInit\fR.
.SH KEYWORDS
application-specific initialization, command-line arguments, main program

190
doc/WindowId.3 Normal file
View File

@@ -0,0 +1,190 @@
'\"
'\" Copyright (c) 1990-1993 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.
'\"
.so man.macros
.TH Tk_WindowId 3 "8.4" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap, Tk_Interp \- retrieve information from Tk's local data structure
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Window
\fBTk_WindowId\fR(\fItkwin\fR)
.sp
Tk_Window
\fBTk_Parent\fR(\fItkwin\fR)
.sp
Display *
\fBTk_Display\fR(\fItkwin\fR)
.sp
const char *
\fBTk_DisplayName\fR(\fItkwin\fR)
.sp
int
\fBTk_ScreenNumber\fR(\fItkwin\fR)
.sp
Screen *
\fBTk_Screen\fR(\fItkwin\fR)
.sp
int
\fBTk_X\fR(\fItkwin\fR)
.sp
int
\fBTk_Y\fR(\fItkwin\fR)
.sp
int
\fBTk_Width\fR(\fItkwin\fR)
.sp
int
\fBTk_Height\fR(\fItkwin\fR)
.sp
XWindowChanges *
\fBTk_Changes\fR(\fItkwin\fR)
.sp
XSetWindowAttributes *
\fBTk_Attributes\fR(\fItkwin\fR)
.sp
int
\fBTk_IsContainer\fR(\fItkwin\fR)
.sp
int
\fBTk_IsEmbedded\fR(\fItkwin\fR)
.sp
int
\fBTk_IsMapped\fR(\fItkwin\fR)
.sp
int
\fBTk_IsTopLevel\fR(\fItkwin\fR)
.sp
int
\fBTk_ReqWidth\fR(\fItkwin\fR)
.sp
int
\fBTk_ReqHeight\fR(\fItkwin\fR)
.sp
int
\fBTk_MinReqWidth\fR(\fItkwin\fR)
.sp
int
\fBTk_MinReqHeight\fR(\fItkwin\fR)
.sp
int
\fBTk_InternalBorderLeft\fR(\fItkwin\fR)
.sp
int
\fBTk_InternalBorderRight\fR(\fItkwin\fR)
.sp
int
\fBTk_InternalBorderTop\fR(\fItkwin\fR)
.sp
int
\fBTk_InternalBorderBottom\fR(\fItkwin\fR)
.sp
Visual *
\fBTk_Visual\fR(\fItkwin\fR)
.sp
int
\fBTk_Depth\fR(\fItkwin\fR)
.sp
Colormap
\fBTk_Colormap\fR(\fItkwin\fR)
.sp
Tcl_Interp *
\fBTk_Interp\fR(\fItkwin\fR)
.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP
\fBTk_WindowId\fR and the other names listed above are
all macros that return fields from Tk's local data structure
for \fItkwin\fR. None of these macros requires any
interaction with the server; it is safe to assume that
all are fast.
.PP
\fBTk_WindowId\fR returns the X identifier for \fItkwin\fR,
or \fBNULL\fR if no X window has been created for \fItkwin\fR
yet.
.PP
\fBTk_Parent\fR returns Tk's token for the logical parent of
\fItkwin\fR. The parent is the token that was specified when
\fItkwin\fR was created, or NULL for main windows.
.PP
\fBTk_Interp\fR returns the Tcl interpreter associated with a
\fItkwin\fR or NULL if there is an error.
.PP
\fBTk_Display\fR returns a pointer to the Xlib display structure
corresponding to \fItkwin\fR. \fBTk_DisplayName\fR returns an
ASCII string identifying \fItkwin\fR's display. \fBTk_ScreenNumber\fR
returns the index of \fItkwin\fR's screen among all the screens
of \fItkwin\fR's display. \fBTk_Screen\fR returns a pointer to
the Xlib structure corresponding to \fItkwin\fR's screen.
.PP
\fBTk_X\fR, \fBTk_Y\fR, \fBTk_Width\fR, and \fBTk_Height\fR
return information about \fItkwin's\fR location within its
parent and its size. The location information refers to the
upper-left pixel in the window, or its border if there is one.
The width and height information refers to the interior size
of the window, not including any border. \fBTk_Changes\fR
returns a pointer to a structure containing all of the above
information plus a few other fields. \fBTk_Attributes\fR
returns a pointer to an XSetWindowAttributes structure describing
all of the attributes of the \fItkwin\fR's window, such as background
pixmap, event mask, and so on (Tk keeps track of all this information
as it is changed by the application). Note: it is essential that
applications use Tk procedures like \fBTk_ResizeWindow\fR instead
of X procedures like \fBXResizeWindow\fR, so that Tk can keep its
data structures up-to-date.
.PP
\fBTk_IsContainer\fR returns a non-zero value if \fItkwin\fR
is a container, and that some other application may be embedding
itself inside \fItkwin\fR.
.PP
\fBTk_IsEmbedded\fR returns a non-zero value if \fItkwin\fR
is not a free-standing window, but rather is embedded in some
other application.
.PP
\fBTk_IsMapped\fR returns a non-zero value if \fItkwin\fR
is mapped and zero if \fItkwin\fR is not mapped.
.PP
\fBTk_IsTopLevel\fR returns a non-zero value if \fItkwin\fR
is a top-level window (its X parent is the root window of the
screen) and zero if \fItkwin\fR is not a top-level window.
.PP
\fBTk_ReqWidth\fR and \fBTk_ReqHeight\fR return information about
the window's requested size. These values correspond to the last
call to \fBTk_GeometryRequest\fR for \fItkwin\fR.
.PP
\fBTk_MinReqWidth\fR and \fBTk_MinReqHeight\fR return information about
the window's minimum requested size. These values correspond to the last
call to \fBTk_SetMinimumRequestSize\fR for \fItkwin\fR.
.PP
\fBTk_InternalBorderLeft\fR, \fBTk_InternalBorderRight\fR,
\fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR
return the width of one side of the internal border
that has been requested for \fItkwin\fR, or 0 if no internal border was
requested. The return value is simply the last value passed to
\fBTk_SetInternalBorder\fR or \fBTk_SetInternalBorderEx\fR for \fItkwin\fR.
.PP
\fBTk_Visual\fR, \fBTk_Depth\fR, and \fBTk_Colormap\fR return
information about the visual characteristics of a window.
\fBTk_Visual\fR returns the visual type for
the window, \fBTk_Depth\fR returns the number of bits per pixel,
and \fBTk_Colormap\fR returns the current
colormap for the window. The visual characteristics are
normally set from the defaults for the window's screen, but
they may be overridden by calling \fBTk_SetWindowVisual\fR.
.SH KEYWORDS
attributes, colormap, depth, display, height, geometry manager,
identifier, mapped, requested size, screen, top-level,
visual, width, window, x, y

33
doc/bell.n Normal file
View File

@@ -0,0 +1,33 @@
'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" 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.
'\"
.so man.macros
.TH bell n 8.4 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
bell \- Ring a display's bell
.SH SYNOPSIS
\fBbell \fR?\fB\-displayof \fIwindow\fR? ?\fB\-nice\fR?
.BE
.SH DESCRIPTION
.PP
This command rings the bell on the display for \fIwindow\fR and
returns an empty string.
If the \fB\-displayof\fR option is omitted, the display of the
application's main window is used by default.
The command uses the current bell-related settings for the display, which
may be modified with programs such as \fBxset\fR.
.PP
If \fB\-nice\fR is not specified, this command also resets the screen saver
for the screen. Some screen savers will ignore this, but others will reset
so that the screen becomes visible again.
.SH KEYWORDS
beep, bell, ring

724
doc/bind.n Normal file
View File

@@ -0,0 +1,724 @@
'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 1998 by Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
.TH bind n 8.0 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
bind \- Arrange for X events to invoke Tcl scripts
.SH SYNOPSIS
\fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR?
.BE
.SH "INTRODUCTION"
.PP
The \fBbind\fR command associates Tcl scripts with X events.
If all three arguments are specified, \fBbind\fR will
arrange for \fIscript\fR (a Tcl script) to be evaluated whenever
the event(s) given by \fIsequence\fR occur in the window(s)
identified by \fItag\fR.
If \fIscript\fR is prefixed with a
.QW + ,
then it is appended to
any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces
any existing binding.
If \fIscript\fR is an empty string then the current binding for
\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound.
In all of the cases where a \fIscript\fR argument is provided,
\fBbind\fR returns an empty string.
.PP
If \fIsequence\fR is specified without a \fIscript\fR, then the
script currently bound to \fIsequence\fR is returned, or
an empty string is returned if there is no binding for \fIsequence\fR.
If neither \fIsequence\fR nor \fIscript\fR is specified, then the
return value is a list whose elements are all the sequences
for which there exist bindings for \fItag\fR.
.PP
The \fItag\fR argument determines which window(s) the binding applies to.
If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must
be the path name for a window; otherwise it may be an arbitrary
string.
Each window has an associated list of tags, and a binding applies
to a particular window if its tag is among those specified for
the window.
Although the \fBbindtags\fR command may be used to assign an
arbitrary set of binding tags to a window, the default binding
tags provide the following behavior:
.IP \(bu 3
If a tag is the name of an internal window the binding applies
to that window.
.IP \(bu 3
If the tag is the name of a toplevel window the binding applies
to the toplevel window and all its internal windows.
.IP \(bu 3
If the tag is the name of a class of widgets, such as \fBButton\fR,
the binding applies to all widgets in that class;
.IP \(bu 3
If \fItag\fR has the value \fBall\fR,
the binding applies to all windows in the application.
.SH "EVENT PATTERNS"
.PP
The \fIsequence\fR argument specifies a sequence of one or more
event patterns, with optional white space between the patterns. Each
event pattern may
take one of three forms. In the simplest case it is a single
printing ASCII character, such as \fBa\fR or \fB[\fR. The character
may not be a space character or the character \fB<\fR. This form of
pattern matches a \fBKeyPress\fR event for the particular
character. The second form of pattern is longer but more general.
It has the following syntax:
.CS
\fB<\fImodifier\-modifier\-type\-detail\fB>\fR
.CE
The entire event pattern is surrounded by angle brackets.
Inside the angle brackets are zero or more modifiers, an event
type, and an extra piece of information (\fIdetail\fR) identifying
a particular button or keysym. Any of the fields may be omitted,
as long as at least one of \fItype\fR and \fIdetail\fR is present.
The fields must be separated by white space or dashes.
.PP
The third form of pattern is used to specify a user-defined, named virtual
event. It has the following syntax:
.CS
\fB<<\fIname\fB>>\fR
.CE
The entire virtual event pattern is surrounded by double angle brackets.
Inside the angle brackets is the user-defined name of the virtual event.
Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a
virtual event to modify it. Bindings on a virtual event may be created
before the virtual event is defined, and if the definition of a virtual
event changes dynamically, all windows bound to that virtual event will
respond immediately to the new definition.
.PP
Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events
when their internal state is updated in some ways. Please see the
manual page for each widget for details.
.SS "MODIFIERS"
.PP
Modifiers consist of any of the following values:
.DS
.ta 6c
\fBControl\fR \fBMod1\fR, \fBM1\fR, \fBCommand\fR
\fBAlt\fR \fBMod2\fR, \fBM2\fR, \fBOption\fR
\fBShift\fR \fBMod3\fR, \fBM3\fR
\fBLock\fR \fBMod4\fR, \fBM4\fR
\fBExtended\fR \fBMod5\fR, \fBM5\fR
\fBButton1\fR, \fBB1\fR \fBMeta\fR, \fBM\fR
\fBButton2\fR, \fBB2\fR \fBDouble\fR
\fBButton3\fR, \fBB3\fR \fBTriple\fR
\fBButton4\fR, \fBB4\fR \fBQuadruple\fR
\fBButton5\fR, \fBB5\fR
.DE
Where more than one value is listed, separated by commas, the values
are equivalent.
Most of the modifiers have the obvious X meanings.
For example, \fBButton1\fR requires that
button 1 be depressed when the event occurs.
For a binding to match a given event, the modifiers in the event
must include all of those specified in the event pattern.
An event may also contain additional modifiers not specified in
the binding.
For example, if button 1 is pressed while the shift and control keys
are down, the pattern \fB<Control\-Button\-1>\fR will match
the event, but \fB<Mod1\-Button\-1>\fR will not.
If no modifiers are specified, then any combination of modifiers may
be present in the event.
.PP
\fBMeta\fR and \fBM\fR refer to whichever of the
\fBM1\fR through \fBM5\fR modifiers is associated with the Meta
key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR).
If there are no Meta keys, or if they are not associated with any
modifiers, then \fBMeta\fR and \fBM\fR will not match any events.
Similarly, the \fBAlt\fR modifier refers to whichever modifier
is associated with the alt key(s) on the keyboard (keysyms
\fBAlt_L\fR and \fBAlt_R\fR).
.PP
The \fBDouble\fR, \fBTriple\fR and \fBQuadruple\fR modifiers are a
convenience for specifying double mouse clicks and other repeated
events. They cause a particular event pattern to be repeated 2, 3 or 4
times, and also place a time and space requirement on the sequence: for a
sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR
pattern, all of the events must occur close together in time and without
substantial mouse motion in between. For example, \fB<Double\-Button\-1>\fR
is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space
requirement.
.PP
The \fBCommand\fR and \fBOption\fR modifiers are equivalents of \fBMod1\fR
resp. \fBMod2\fR, they correspond to Macintosh-specific modifier keys.
.PP
.VS 8.5
The \fBExtended\fR modifier is, at present, specific to Windows. It
appears on events that are associated with the keys on the
.QW "extended keyboard" .
On a US keyboard, the extended keys include the \fBAlt\fR
and \fBControl\fR keys at the right of the keyboard, the cursor keys
in the cluster to the left of the numeric pad, the \fBNumLock\fR key,
the \fBBreak\fR key, the \fBPrintScreen\fR key, and the \fB/\fR and
\fBEnter\fR keys in the numeric keypad.
.VE 8.5
.SS "EVENT TYPES"
.PP
The \fItype\fR field may be any of the standard X event types, with a
few extra abbreviations. The \fItype\fR field will also accept a
couple non-standard X event types that were added to better support
the Macintosh and Windows platforms. Below is a list of all the valid
types; where two names appear together, they are synonyms.
.DS
.ta \w'\fBButtonPress, Button\0\0\0\fR'u +\w'\fBKeyPress, Key\0\0\0\fR'u
\fBActivate\fR \fBDestroy\fR \fBMap\fR
\fBButtonPress\fR, \fBButton\fR \fBEnter\fR \fBMapRequest\fR
\fBButtonRelease\fR \fBExpose\fR \fBMotion\fR
\fBCirculate\fR \fBFocusIn\fR \fBMouseWheel\fR
\fBCirculateRequest\fR \fBFocusOut\fR \fBProperty\fR
\fBColormap\fR \fBGravity\fR \fBReparent\fR
\fBConfigure\fR \fBKeyPress\fR, \fBKey\fR \fBResizeRequest\fR
\fBConfigureRequest\fR \fBKeyRelease\fR \fBUnmap\fR
\fBCreate\fR \fBLeave\fR \fBVisibility\fR
\fBDeactivate\fR
.DE
Most of the above events have the same fields and behaviors as events
in the X Windowing system. You can find more detailed descriptions of
these events in any X window programming book. A couple of the events
are extensions to the X event system to support features unique to the
Macintosh and Windows platforms. We provide a little more detail on
these events here. These include:
.IP "\fBActivate\fR, \fBDeactivate\fR" 5
These two events are sent to every sub-window of a toplevel when they
change state. In addition to the focus Window, the Macintosh platform
and Windows platforms have a notion of an active window (which often
has but is not required to have the focus). On the Macintosh, widgets
in the active window have a different appearance than widgets in
deactive windows. The \fBActivate\fR event is sent to all the
sub-windows in a toplevel when it changes from being deactive to
active. Likewise, the \fBDeactive\fR event is sent when the window's
state changes from active to deactive. There are no useful percent
substitutions you would make when binding to these events.
.IP \fBMouseWheel\fR 5
Many contemporary mice support a mouse wheel, which is used
for scrolling documents without using the scrollbars. By rolling the
wheel, the system will generate \fBMouseWheel\fR events that the
application can use to scroll. Like \fBKey\fR events the event is
always routed to the window that currently has focus. When the event
is received you can use the \fB%D\fR substitution to get the
\fIdelta\fR field for the event, which is a integer value describing how
the mouse wheel has moved. The smallest value for which the
system will report is defined by the OS. On Windows 95 & 98 machines
this value is at least 120 before it is reported. However, higher
resolution devices may be available in the future. The sign of the
value determines which direction your widget should scroll. Positive
values should scroll up and negative values should scroll down.
.IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5
The \fBKeyPress\fR and \fBKeyRelease\fR events are generated
whenever a key is pressed or released. \fBKeyPress\fR and \fBKeyRelease\fR
events are sent to the window which currently has the keyboard focus.
.IP "\fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR" 5
The \fBButtonPress\fR and \fBButtonRelease\fR events
are generated when the user presses or releases a mouse button.
\fBMotion\fR events are generated whenever the pointer is moved.
\fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR events are
normally sent to the window containing the pointer.
.RS
.PP
When a mouse button is pressed, the window containing the pointer
automatically obtains a temporary pointer grab.
Subsequent \fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR
events will be sent to that window,
regardless of which window contains the pointer,
until all buttons have been released.
.RE
.IP \fBConfigure\fR 5
A \fBConfigure\fR event is sent to a window whenever its
size, position, or border width changes, and sometimes
when it has changed position in the stacking order.
.IP "\fBMap\fR, \fBUnmap\fR" 5
The \fBMap\fR and \fBUnmap\fR events are generated whenever the mapping
state of a window changes.
.RS
.PP
Windows are created in the unmapped state.
Top-level windows become mapped when they transition to the
\fBnormal\fR state, and are unmapped in the \fBwithdrawn\fR
and \fBiconic\fR states.
Other windows become mapped when they are placed under control
of a geometry manager (for example \fBpack\fR or \fBgrid\fR).
.PP
A window is \fIviewable\fR only if it and all of its ancestors are mapped.
Note that geometry managers typically do not map their children until
they have been mapped themselves, and unmap all children
when they become unmapped; hence in Tk \fBMap\fR and \fBUnmap\fR
events indicate whether or not a window is viewable.
.RE
.IP \fBVisibility\fR 5
A window is said to be \fIobscured\fR when another window
above it in the stacking order fully or partially overlaps it.
\fBVisibility\fR events are generated whenever a window's
obscurity state changes; the \fIstate\fR field (\fB%s\fR)
specifies the new state.
.IP \fBExpose\fR 5
An \fBExpose\fR event is generated whenever all or part of a
window should be redrawn (for example, when a window is
first mapped or if it becomes unobscured).
It is normally not necessary for client applications to
handle \fBExpose\fR events, since Tk handles them internally.
.IP \fBDestroy\fR 5
A \fBDestroy\fR event is delivered to a window when
it is destroyed.
.RS
.PP
When the \fBDestroy\fR event is delivered
to a widget, it is in a
.QW half-dead
state: the widget still exists, but most operations on it will fail.
.RE
.IP "\fBFocusIn\fR, \fBFocusOut\fR" 5
The \fBFocusIn\fR and \fBFocusOut\fR events are generated
whenever the keyboard focus changes.
A \fBFocusOut\fR event is sent to the old focus window,
and a \fBFocusIn\fR event is sent to the new one.
.RS
.PP
In addition,
if the old and new focus windows do not share a common parent,
.QW "virtual crossing"
focus events are sent to the intermediate windows in the hierarchy.
Thus a \fBFocusIn\fR event indicates
that the target window or one of its descendants has acquired the focus,
and a \fBFocusOut\fR event indicates that the focus
has been changed to a window outside the target window's hierarchy.
.PP
The keyboard focus may be changed explicitly by a call to \fBfocus\fR,
or implicitly by the window manager.
.RE
.IP "\fBEnter\fR, \fBLeave\fR" 5
An \fBEnter\fR event is sent to a window when the pointer
enters that window, and a \fBLeave\fR event is sent when
the pointer leaves it.
.RS
.PP
If there is a pointer grab in effect, \fBEnter\fR and \fBLeave\fR
events are only delivered to the window owning the grab.
.PP
In addition, when the pointer moves
between two windows, \fBEnter\fR and \fBLeave\fR
.QW "virtual crossing"
events are sent to intermediate windows
in the hierarchy in the same manner as for \fBFocusIn\fR and
\fBFocusOut\fR events.
.RE
.IP \fBProperty\fR
A \fBProperty\fR event is sent to a window whenever an X property
belonging to that window is changed or deleted.
\fBProperty\fR events are not normally delivered to Tk applications as
they are handled by the Tk core.
.IP \fBColormap\fR
A \fBColormap\fR event is generated whenever the colormap
associated with a window has been changed, installed, or uninstalled.
.RS
.PP
Widgets may be assigned a private colormap by
specifying a \fB\-colormap\fR option; the window manager
is responsible for installing and uninstalling colormaps
as necessary.
.PP
Note that Tk provides no useful details for this event type.
.RE
'\" The following events were added in TIP#47
.IP "\fBMapRequest\fR, \fBCirculateRequest\fR, \fBResizeRequest\fR, \fBConfigureRequest\fR, \fBCreate\fR" 5
These events are not normally delivered to Tk applications.
They are included for completeness, to make it possible to
write X11 window managers in Tk.
(These events are only delivered when a client has
selected \fBSubstructureRedirectMask\fR on a window;
the Tk core does not use this mask.)
.IP "\fBGravity\fR, \fBReparent\fR, \fBCirculate\fR" 5
The events \fBGravity\fR and \fBReparent\fR
are not normally delivered to Tk applications.
They are included for completeness.
.RS
.PP
A \fBCirculate\fR event indicates that the window has moved
to the top or to the bottom of the stacking order as
a result of an \fBXCirculateSubwindows\fR protocol request.
Note that the stacking order may be changed for other reasons
which do not generate a \fBCirculate\fR event, and that
Tk does not use \fBXCirculateSubwindows()\fR internally.
This event type is included only for completeness;
there is no reliable way to track changes to a window's
position in the stacking order.
.RE
.SS "EVENT DETAILS"
.PP
The last part of a long event specification is \fIdetail\fR. In the
case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
number of a button (1\-5). If a button number is given, then only an
event on that particular button will match; if no button number is
given, then an event on any button will match. Note: giving a
specific button number is different than specifying a button modifier;
in the first case, it refers to a button being pressed or released,
while in the second it refers to some other button that is already
depressed when the matching event occurs. If a button
number is given then \fItype\fR may be omitted: if will default
to \fBButtonPress\fR. For example, the specifier \fB<1>\fR
is equivalent to \fB<ButtonPress\-1>\fR.
.PP
If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then
\fIdetail\fR may be specified in the form of an X keysym. Keysyms
are textual specifications for particular keys on the keyboard;
they include all the alphanumeric ASCII characters (e.g.
.QW a
is the keysym for the ASCII character
.QW a ),
plus descriptions for non-alphanumeric characters
.PQ comma "is the keysym for the comma character" ,
plus descriptions for all the non-ASCII keys on the keyboard (e.g.
.QW Shift_L
is the keysym for the left shift key, and
.QW F1
is the keysym for the F1 function key, if it exists). The
complete list of keysyms is not presented here; it is
available in other X documentation and may vary from system to
system.
If necessary, you can use the \fB%K\fR notation described below
to print out the keysym name for a particular key.
If a keysym \fIdetail\fR is given, then the
\fItype\fR field may be omitted; it will default to \fBKeyPress\fR.
For example, \fB<Control\-comma>\fR is equivalent to
\fB<Control\-KeyPress\-comma>\fR.
.SH "BINDING SCRIPTS AND SUBSTITUTIONS"
.PP
The \fIscript\fR argument to \fBbind\fR is a Tcl script,
which will be executed whenever the given event sequence occurs.
\fICommand\fR will be executed in the same interpreter that the
\fBbind\fR command was executed in, and it will run at global
level (only global variables will be accessible).
If \fIscript\fR contains
any \fB%\fR characters, then the script will not be
executed directly. Instead, a new script will be
generated by replacing each \fB%\fR, and the character following
it, with information from the current event. The replacement
depends on the character following the \fB%\fR, as defined in the
list below. Unless otherwise indicated, the
replacement string is the decimal value of the given field from
the current event.
Some of the substitutions are only valid for
certain types of events; if they are used for other types of events
the value substituted is undefined.
.IP \fB%%\fR 5
Replaced with a single percent.
.IP \fB%#\fR 5
The number of the last client request processed by the server
(the \fIserial\fR field from the event). Valid for all event
types.
.IP \fB%a\fR 5
The \fIabove\fR field from the event,
formatted as a hexadecimal number.
Valid only for \fBConfigure\fR events.
Indicates the sibling window immediately below the receiving window
in the stacking order, or \fB0\fR if the receiving window is at the
bottom.
.IP \fB%b\fR 5
The number of the button that was pressed or released. Valid only
for \fBButtonPress\fR and \fBButtonRelease\fR events.
.IP \fB%c\fR 5
The \fIcount\fR field from the event. Valid only for \fBExpose\fR events.
Indicates that there are \fIcount\fR pending \fBExpose\fR events which have not
yet been delivered to the window.
.IP \fB%d\fR 5
The \fIdetail\fR
.VS 8.5
or \fIuser_data\fR
.VE 8.5
field from the event. The \fB%d\fR is replaced by
a string identifying the detail. For \fBEnter\fR,
\fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events,
the string will be one of the following:
.RS
.DS
.ta 6c
\fBNotifyAncestor\fR \fBNotifyNonlinearVirtual\fR
\fBNotifyDetailNone\fR \fBNotifyPointer\fR
\fBNotifyInferior\fR \fBNotifyPointerRoot\fR
\fBNotifyNonlinear\fR \fBNotifyVirtual\fR
.DE
For \fBConfigureRequest\fR events, the string will be one of:
.DS
.ta 6c
\fBAbove\fR \fBOpposite\fR
\fBBelow\fR \fBNone\fR
\fBBottomIf\fR \fBTopIf\fR
.DE
.VS 8.5
For virtual events, the string will be whatever value is stored in the
\fIuser_data\fR field when the event was created (typically with
\fBevent generate\fR), or the empty string if the field is NULL.
Virtual events corresponding to key sequence presses (see \fBevent
add\fR for details) set the \fIuser_data\fR to NULL.
.VE 8.5
For events other than these, the substituted string is undefined.
.RE
.IP \fB%f\fR 5
The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only
for \fBEnter\fR and \fBLeave\fR events. \fB1\fR if the receiving
window is the focus window or a descendant of the focus window,
\fB0\fR otherwise.
.IP \fB%h\fR 5
The \fIheight\fR field from the event. Valid for the \fBConfigure\fR,
\fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and
\fBExpose\fR events.
Indicates the new or requested height of the window.
.IP \fB%i\fR 5
The \fIwindow\fR field from the event, represented as a hexadecimal
integer. Valid for all event types.
.IP \fB%k\fR 5
The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR
and \fBKeyRelease\fR events.
.IP \fB%m\fR 5
The \fImode\fR field from the event. The substituted string is one of
\fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or
\fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR,
\fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events.
.IP \fB%o\fR 5
The \fIoverride_redirect\fR field from the event. Valid only for
\fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events.
.IP \fB%p\fR 5
The \fIplace\fR field from the event, substituted as one of the
strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only
for \fBCirculate\fR and \fBCirculateRequest\fR events.
.IP \fB%s\fR 5
The \fIstate\fR field from the event. For \fBButtonPress\fR,
\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
\fBLeave\fR, and \fBMotion\fR events, a decimal string
is substituted. For \fBVisibility\fR, one of the strings
\fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR,
and \fBVisibilityFullyObscured\fR is substituted.
For \fBProperty\fR events, substituted with
either the string \fBNewValue\fR (indicating that the property
has been created or modified) or \fBDelete\fR (indicating that
the property has been removed).
.IP \fB%t\fR 5
The \fItime\fR field from the event.
This is the X server timestamp (typically the time since
the last server reset) in milliseconds, when the event occurred.
Valid for most events.
.IP \fB%w\fR 5
The \fIwidth\fR field from the event.
Indicates the new or requested width of the window.
Valid only for
\fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR,
\fBResizeRequest\fR, and \fBExpose\fR events.
.IP "\fB%x\fR, \fB%y\fR" 5
The \fIx\fR and \fIy\fR fields from the event.
For \fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR,
\fBKeyPress\fR, \fBKeyRelease\fR, and \fBMouseWheel\fR events,
\fB%x\fR and \fB%y\fR indicate the position of the mouse pointer
relative to the receiving window.
For \fBEnter\fR and \fBLeave\fR events, the position where the
mouse pointer crossed the window, relative to the receiving window.
For \fBConfigure\fR and \fBCreate\fR requests, the \fIx\fR and \fIy\fR
coordinates of the window relative to its parent window.
.IP \fB%A\fR 5
Substitutes the UNICODE character corresponding to the event, or
the empty string if the event does not correspond to a UNICODE character
(e.g. the shift key was pressed). \fBXmbLookupString\fR (or
\fBXLookupString\fR when input method support is turned off) does all
the work of translating from the event to a UNICODE character.
Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
.IP \fB%B\fR 5
The \fIborder_width\fR field from the event. Valid only for
\fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events.
.IP \fB%D\fR 5
This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The
\fIdelta\fR value represents the rotation units the mouse wheel has
been moved. On Windows 95 & 98 systems the smallest value for the
delta is 120. Future systems may support higher resolution values for
the delta. The sign of the value represents the direction the mouse
wheel was scrolled.
.IP \fB%E\fR 5
The \fIsend_event\fR field from the event. Valid for all event types.
\fB0\fR indicates that this is a
.QW normal
event, \fB1\fR indicates that it is a
.QW synthetic
event generated by \fBSendEvent\fR.
.IP \fB%K\fR 5
The keysym corresponding to the event, substituted as a textual
string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
.IP \fB%N\fR 5
The keysym corresponding to the event, substituted as a decimal
number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
.IP \fB%P\fR 5
The name of the property being updated or deleted (which
may be converted to an XAtom using \fBwinfo atom\fR.) Valid
only for \fBProperty\fR events.
.IP \fB%R\fR 5
The \fIroot\fR window identifier from the event. Valid only for
events containing a \fIroot\fR field.
.IP \fB%S\fR 5
The \fIsubwindow\fR window identifier from the event,
formatted as a hexadecimal number.
Valid only for events containing a \fIsubwindow\fR field.
.IP \fB%T\fR 5
The \fItype\fR field from the event. Valid for all event types.
.IP \fB%W\fR 5
The path name of the window to which the event was reported (the
\fIwindow\fR field from the event). Valid for all event types.
.IP "\fB%X\fR, \fB%Y\fR" 5
The \fIx_root\fR and \fIy_root\fR fields from the event.
If a virtual-root window manager is being used then the substituted
values are the corresponding x-coordinate and y-coordinate in the virtual root.
Valid only for
\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
and \fBMotion\fR events.
Same meaning as \fB%x\fR and \fB%y\fR, except relative to the (virtual) root
window.
.LP
The replacement string for a %-replacement is formatted as a proper
Tcl list element.
This means that spaces or special characters such as \fB$\fR and
\fB{\fR may be preceded by backslashes.
This guarantees that the string will be passed through the Tcl
parser when the binding script is evaluated.
Most replacements are numbers or well-defined strings such
as \fBAbove\fR; for these replacements no special formatting
is ever necessary.
The most common case where reformatting occurs is for the \fB%A\fR
substitution. For example, if \fIscript\fR is
.CS
\fBinsert\0%A\fR
.CE
and the character typed is an open square bracket, then the script
actually executed will be
.CS
\fBinsert\0\e[\fR
.CE
This will cause the \fBinsert\fR to receive the original replacement
string (open square bracket) as its first argument.
If the extra backslash had not been added, Tcl would not have been
able to parse the script correctly.
.SH "MULTIPLE MATCHES"
.PP
It is possible for several bindings to match a given X event.
If the bindings are associated with different \fItag\fR's,
then each of the bindings will be executed, in order.
By default, a binding for the widget will be executed first, followed
by a class binding, a binding for its toplevel, and
an \fBall\fR binding.
The \fBbindtags\fR command may be used to change this order for
a particular window or to associate additional binding tags with
the window.
.PP
The \fBcontinue\fR and \fBbreak\fR commands may be used inside a
binding script to control the processing of matching scripts.
If \fBcontinue\fR is invoked, then the current binding script
is terminated but Tk will continue processing binding scripts
associated with other \fItag\fR's.
If the \fBbreak\fR command is invoked within a binding script,
then that script terminates and no other scripts will be invoked
for the event.
.PP
If more than one binding matches a particular event and they
have the same \fItag\fR, then the most specific binding
is chosen and its script is evaluated.
The following tests are applied, in order, to determine which of
several matching sequences is more specific:
.RS
.IP (a)
an event pattern that specifies a specific button or key is more specific
than one that does not;
.IP (b)
a longer sequence (in terms of number
of events matched) is more specific than a shorter sequence;
.IP (c)
if the modifiers specified in one pattern are a subset of the
modifiers in another pattern, then the pattern with more modifiers
is more specific.
.IP (d)
a virtual event whose physical pattern matches the sequence is less
specific than the same physical pattern that is not associated with a
virtual event.
.IP (e)
given a sequence that matches two or more virtual events, one
of the virtual events will be chosen, but the order is undefined.
.RE
.PP
If the matching sequences contain more than one event, then tests
(c)\-(e) are applied in order from the most recent event to the least recent
event in the sequences. If these tests fail to determine a winner, then the
most recently registered sequence is the winner.
.PP
If there are two (or more) virtual events that are both triggered by the
same sequence, and both of those virtual events are bound to the same window
tag, then only one of the virtual events will be triggered, and it will
be picked at random:
.CS
event add <<Paste>> <Control\-y>
event add <<Paste>> <Button\-2>
event add <<Scroll>> <Button\-2>
\fBbind\fR Entry <<Paste>> {puts Paste}
\fBbind\fR Entry <<Scroll>> {puts Scroll}
.CE
If the user types Control\-y, the \fB<<Paste>>\fR binding
will be invoked, but if the user presses button 2 then one of
either the \fB<<Paste>>\fR or the \fB<<Scroll>>\fR bindings will
be invoked, but exactly which one gets invoked is undefined.
.PP
If an X event does not match any of the existing bindings, then the
event is ignored.
An unbound event is not considered to be an error.
.SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS"
.PP
When a \fIsequence\fR specified in a \fBbind\fR command contains
more than one event pattern, then its script is executed whenever
the recent events (leading up to and including the current event)
match the given sequence. This means, for example, that if button 1 is
clicked repeatedly the sequence \fB<Double\-ButtonPress\-1>\fR will match
each button press but the first.
If extraneous events that would prevent a match occur in the middle
of an event sequence then the extraneous events are
ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events.
For example, \fB<Double\-ButtonPress\-1>\fR will match a sequence of
presses of button 1, even though there will be \fBButtonRelease\fR
events (and possibly \fBMotion\fR events) between the
\fBButtonPress\fR events.
Furthermore, a \fBKeyPress\fR event may be preceded by any number
of other \fBKeyPress\fR events for modifier keys without the
modifier keys preventing a match.
For example, the event sequence \fBaB\fR will match a press of the
\fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR
key, and a press of the \fBb\fR key: the press of \fBShift\fR is
ignored because it is a modifier key.
Finally, if several \fBMotion\fR events occur in a row, only
the last one is used for purposes of matching binding sequences.
.SH "ERRORS"
.PP
If an error occurs in executing the script for a binding then the
\fBbgerror\fR mechanism is used to report the error.
The \fBbgerror\fR command will be executed at global level
(outside the context of any Tcl procedure).
.SH "EXAMPLES"
Arrange for a string describing the motion of the mouse to be printed
out when the mouse is double-clicked:
.CS
\fBbind\fR . <Double\-1> {
puts "hi from (%x,%y)"
}
.CE
.PP
A little GUI that displays what the keysym name of the last key
pressed is:
.CS
set keysym "Press any key"
pack [label .l \-textvariable keysym \-padx 2m \-pady 1m]
\fBbind\fR . <Key> {
set keysym "You pressed %K"
}
.CE
.SH "SEE ALSO"
bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
.SH KEYWORDS
binding, event

101
doc/bindtags.n Normal file
View File

@@ -0,0 +1,101 @@
'\"
'\" 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.
'\"
.so man.macros
.TH bindtags n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
bindtags \- Determine which bindings apply to a window, and order of evaluation
.SH SYNOPSIS
\fBbindtags \fIwindow \fR?\fItagList\fR?
.BE
.SH DESCRIPTION
.PP
When a binding is created with the \fBbind\fR command, it is
associated either with a particular window such as \fB.a.b.c\fR,
a class name such as \fBButton\fR, the keyword \fBall\fR, or any
other string.
All of these forms are called \fIbinding tags\fR.
Each window contains a list of binding tags that determine how
events are processed for the window.
When an event occurs in a window, it is applied to each of the
window's tags in order: for each tag, the most specific binding
that matches the given tag and event is executed.
See the \fBbind\fR command for more information on the matching
process.
.PP
By default, each window has four binding tags consisting of the
name of the window, the window's class name, the name of the window's
nearest toplevel ancestor, and \fBall\fR, in that order.
Toplevel windows have only three tags by default, since the toplevel
name is the same as that of the window.
The \fBbindtags\fR command allows the binding tags for a window to be
read and modified.
.PP
If \fBbindtags\fR is invoked with only one argument, then the
current set of binding tags for \fIwindow\fR is returned as a list.
If the \fItagList\fR argument is specified to \fBbindtags\fR,
then it must be a proper list; the tags for \fIwindow\fR are changed
to the elements of the list.
The elements of \fItagList\fR may be arbitrary strings; however,
any tag starting with a dot is treated as the name of a window; if
no window by that name exists at the time an event is processed,
then the tag is ignored for that event.
The order of the elements in \fItagList\fR determines the order in
which binding scripts are executed in response to events.
For example, the command
.CS
\fBbindtags .b {all . Button .b}\fR
.CE
reverses the order in which binding scripts will be evaluated for
a button named \fB.b\fR so that \fBall\fR bindings are invoked
first, following by bindings for \fB.b\fR's toplevel
.PQ . "" ,
followed by class bindings, followed by bindings for \fB.b\fR.
If \fItagList\fR is an empty list then the binding tags for \fIwindow\fR
are returned to the default state described above.
.PP
The \fBbindtags\fR command may be used to introduce arbitrary
additional binding tags for a window, or to remove standard tags.
For example, the command
.CS
\fBbindtags .b {.b TrickyButton . all}\fR
.CE
replaces the \fBButton\fR tag for \fB.b\fR with \fBTrickyButton\fR.
This means that the default widget bindings for buttons, which are
associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR,
but any bindings associated with \fBTrickyButton\fR (perhaps some
new button behavior) will apply.
.SH EXAMPLE
If you have a set of nested \fBframe\fR widgets and you want events
sent to a \fBbutton\fR widget to also be delivered to all the widgets
up to the current \fBtoplevel\fR (in contrast to Tk's default
behavior, where events are not delivered to those intermediate
windows) to make it easier to have accelerators that are only active
for part of a window, you could use a helper procedure like this to
help set things up:
.CS
proc setupBindtagsForTreeDelivery {widget} {
set tags [list $widget [winfo class $widget]]
set w $widget
set t [winfo toplevel $w]
while {$w ne $t} {
set w [winfo parent $w]
lappend tags $w
}
lappend tags all
\fBbindtags\fR $widget $tags
}
.CE
.SH "SEE ALSO"
bind(n)
.SH KEYWORDS
binding, event, tag

112
doc/bitmap.n Normal file
View File

@@ -0,0 +1,112 @@
'\"
'\" 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.
'\"
.so man.macros
.TH bitmap n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
bitmap \- Images that display two colors
.SH SYNOPSIS
\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR?
.BE
.SH DESCRIPTION
.PP
A bitmap is an image whose pixels can display either of two colors
or be transparent.
A bitmap image is defined by four things: a background color,
a foreground color, and two bitmaps, called the \fIsource\fR
and the \fImask\fR.
Each of the bitmaps specifies 0/1 values for a rectangular
array of pixels, and the two bitmaps must have the same
dimensions.
For pixels where the mask is zero, the image displays nothing,
producing a transparent effect.
For other pixels, the image displays the foreground color if
the source data is one and the background color if the source
data is zero.
.SH "CREATING BITMAPS"
.PP
Like all images, bitmaps are created using the \fBimage create\fR
command.
Bitmaps support the following \fIoptions\fR:
.TP
\fB\-background \fIcolor\fR
Specifies a background color for the image in any of the standard
ways accepted by Tk. If this option is set to an empty string
then the background pixels will be transparent. This effect
is achieved by using the source bitmap as the mask bitmap, ignoring
any \fB\-maskdata\fR or \fB\-maskfile\fR options.
.TP
\fB\-data \fIstring\fR
Specifies the contents of the source bitmap as a string.
The string must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
If both the \fB\-data\fR and \fB\-file\fR options are specified,
the \fB\-data\fR option takes precedence.
.TP
\fB\-file \fIname\fR
\fIname\fR gives the name of a file whose contents define the
source bitmap.
The file must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
.TP
\fB\-foreground \fIcolor\fR
Specifies a foreground color for the image in any of the standard
ways accepted by Tk.
.TP
\fB\-maskdata \fIstring\fR
Specifies the contents of the mask as a string.
The string must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified,
the \fB\-maskdata\fR option takes precedence.
.TP
\fB\-maskfile \fIname\fR
\fIname\fR gives the name of a file whose contents define the
mask.
The file must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
.SH "IMAGE COMMAND"
.PP
When a bitmap image is created, Tk also creates a new command
whose name is the same as the image.
This command may be used to invoke various operations
on the image.
It has the following general form:
.CS
\fIimageName option \fR?\fIarg arg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command. The following
commands are possible for bitmap images:
.TP
\fIimageName \fBcget\fR \fIoption\fR
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the
\fBimage create bitmap\fR command.
.TP
\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
Query or modify the configuration options for the image.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list). If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified). If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given option(s) to have the given value(s); in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the
\fBimage create bitmap\fR command.
.SH KEYWORDS
bitmap, image

202
doc/button.n Normal file
View File

@@ -0,0 +1,202 @@
'\"
'\" 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.
'\"
.so man.macros
.TH button n 4.4 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
button \- Create and manipulate button widgets
.SH SYNOPSIS
\fBbutton\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-activebackground \-font \-relief
\-activeforeground \-foreground \-repeatdelay
\-anchor \-highlightbackground \-repeatinterval
\-background \-highlightcolor \-takefocus
\-bitmap \-highlightthickness \-text
\-borderwidth \-image \-textvariable
\-compound \-justify \-underline
\-cursor \-padx \-wraplength
\-disabledforeground \-pady
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
.OP \-command command Command
Specifies a Tcl command to associate with the button. This command
is typically invoked when mouse button 1 is released over the button
window.
.OP \-default default Default
Specifies one of three states for the default ring: \fBnormal\fR,
\fBactive\fR, or \fBdisabled\fR. In active state, the button is drawn
with the platform specific appearance for a default button. In normal
state, the button is drawn with the platform specific appearance for a
non-default button, leaving enough space to draw the default button
appearance. The normal and active states will result in buttons of
the same size. In disabled state, the button is drawn with the
non-default button appearance without leaving space for the default
appearance. The disabled state may result in a smaller button than
the active state.
.OP \-height height Height
Specifies a desired height for the button.
If an image or bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
for text it is in lines of text.
If this option is not specified, the button's desired height is computed
from the size of the image or bitmap or text being displayed in it.
.OP \-overrelief overRelief OverRelief
Specifies an alternative relief for the button, to be used when the
mouse cursor is over the widget. This option can be used to make
toolbar buttons, by configuring \fB\-relief flat \-overrelief
raised\fR. If the value of this option is the empty string, then no
alternative relief is used when the mouse cursor is over the button.
The empty string is the default value.
.OP \-state state State
Specifies one of three states for the button: \fBnormal\fR, \fBactive\fR,
or \fBdisabled\fR. In normal state the button is displayed using the
\fBforeground\fR and \fBbackground\fR options. The active state is
typically used when the pointer is over the button. In active state
the button is displayed using the \fBactiveForeground\fR and
\fBactiveBackground\fR options. Disabled state means that the button
should be insensitive: the default bindings will refuse to activate
the widget and will ignore mouse button presses.
In this state the \fBdisabledForeground\fR and
\fBbackground\fR options determine how the button is displayed.
.OP \-width width Width
Specifies a desired width for the button.
If an image or bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
For a text button (no image or with \fB\-compound none\fR) then the width
specifies how much space in characters to allocate for the text label.
If the width is negative then this specifies a minimum width.
If this option is not specified, the button's desired width is computed
from the size of the image or bitmap or text being displayed in it.
.BE
.SH DESCRIPTION
.PP
The \fBbutton\fR command creates a new window (given by the
\fIpathName\fR argument) and makes it into a button widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the button such as its colors, font,
text, and initial relief. The \fBbutton\fR command returns its
\fIpathName\fR argument. At the time this command is invoked,
there must not exist a window named \fIpathName\fR, but
\fIpathName\fR's parent must exist.
.PP
A button is a widget that displays a textual string, bitmap or image.
If text is displayed, it must all be in a single font, but it
can occupy multiple lines on the screen (if it contains newlines
or if wrapping occurs because of the \fBwrapLength\fR option) and
one of the characters may optionally be underlined using the
\fBunderline\fR option.
It can display itself in either of three different ways, according
to
the \fBstate\fR option;
it can be made to appear raised, sunken, or flat;
and it can be made to flash. When a user invokes the
button (by pressing mouse button 1 with the cursor over the
button), then the Tcl command specified in the \fB\-command\fR
option is invoked.
.SH "WIDGET COMMAND"
.PP
The \fBbutton\fR command creates a new Tcl command whose
name is \fIpathName\fR. This
command may be used to invoke various
operations on the widget. It has the following general form:
.CS
\fIpathName option \fR?\fIarg arg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command. The following
commands are possible for button widgets:
.TP
\fIpathName \fBcget\fR \fIoption\fR
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the \fBbutton\fR
command.
.TP
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list). If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified). If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the \fBbutton\fR
command.
.TP
\fIpathName \fBflash\fR
Flash the button. This is accomplished by redisplaying the button
several times, alternating between active and normal colors. At
the end of the flash the button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the button's state is \fBdisabled\fR.
.TP
\fIpathName \fBinvoke\fR
Invoke the Tcl command associated with the button, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the button.
This command is ignored if the button's state is \fBdisabled\fR.
.SH "DEFAULT BINDINGS"
.PP
Tk automatically creates class bindings for buttons that give them
default behavior:
.IP [1]
A button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the button.
Under Windows, this binding is only active when mouse button 1 has
been pressed over the button.
.IP [2]
A button's relief is changed to sunken whenever mouse button 1 is
pressed over the button, and the relief is restored to its original
value when button 1 is later released.
.IP [3]
If mouse button 1 is pressed over a button and later released over
the button, the button is invoked. However, if the mouse is not
over the button when button 1 is released, then no invocation occurs.
.IP [4]
When a button has the input focus, the space key causes the button
to be invoked.
.PP
If the button's state is \fBdisabled\fR then none of the above
actions occur: the button is completely non-responsive.
.PP
The behavior of buttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
.SH EXAMPLES
This is the classic Tk
.QW "Hello, World!"
demonstration:
.PP
.CS
\fBbutton\fR .b \-text "Hello, World!" \-command exit
pack .b
.CE
.PP
This example demonstrates how to handle button accelerators:
.PP
.CS
\fBbutton\fR .b1 \-text Hello \-underline 0
\fBbutton\fR .b2 \-text World \-underline 0
bind . <Key\-h> {.b1 flash; .b1 invoke}
bind . <Key\-w> {.b2 flash; .b2 invoke}
pack .b1 .b2
.CE
.SH "SEE ALSO"
ttk::button(n)
.SH KEYWORDS
button, widget

1851
doc/canvas.n Normal file
View File

File diff suppressed because it is too large Load Diff

294
doc/checkbutton.n Normal file
View File

@@ -0,0 +1,294 @@
'\"
'\" 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.
'\"
.so man.macros
.TH checkbutton n 4.4 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
checkbutton \- Create and manipulate checkbutton widgets
.SH SYNOPSIS
\fBcheckbutton\fI pathName \fR?\fIoptions\fR?
.SO
\-activebackground \-disabledforeground \-padx
\-activeforeground \-font \-pady
\-anchor \-foreground \-relief
\-background \-highlightbackground \-takefocus
\-bitmap \-highlightcolor \-text
\-borderwidth \-highlightthickness \-textvariable
\-compound \-image \-underline
\-cursor \-justify \-wraplength
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
.OP \-command command Command
Specifies a Tcl command to associate with the button. This command
is typically invoked when mouse button 1 is released over the button
window. The button's global variable (\fB\-variable\fR option) will
be updated before the command is invoked.
.OP \-height height Height
Specifies a desired height for the button.
If an image or bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
for text it is in lines of text.
If this option is not specified, the button's desired height is computed
from the size of the image or bitmap or text being displayed in it.
.OP \-indicatoron indicatorOn IndicatorOn
Specifies whether or not the indicator should be drawn. Must be a
proper boolean value. If false, the \fBrelief\fR option is
ignored and the widget's relief is always sunken if the widget is
selected and raised otherwise.
.OP \-offrelief offRelief OffRelief
Specifies the relief for the checkbutton when the indicator is not drawn and
the checkbutton is off. The default value is
.QW raised .
By setting this option to
.QW flat
and setting \fB\-indicatoron\fR to false and \fB\-overrelief\fR to
.QW raised ,
the effect is achieved
of having a flat button that raises on mouse-over and which is
depressed when activated. This is the behavior typically exhibited by
the Bold, Italic, and Underline checkbuttons on the toolbar of a
word-processor, for example.
.OP \-offvalue offValue Value
Specifies value to store in the button's associated variable whenever
this button is deselected. Defaults to
.QW 0 .
.OP \-onvalue onValue Value
Specifies value to store in the button's associated variable whenever
this button is selected. Defaults to
.QW 1 .
.OP \-overrelief overRelief OverRelief
Specifies an alternative relief for the checkbutton, to be used when the
mouse cursor is over the widget. This option can be used to make
toolbar buttons, by configuring \fB\-relief flat \-overrelief
raised\fR. If the value of this option is the empty string, then no
alternative relief is used when the mouse cursor is over the checkbutton.
The empty string is the default value.
.OP \-selectcolor selectColor Background
Specifies a background color to use when the button is selected.
If \fBindicatorOn\fR is true then the color is used as the background for
the indicator regardless of the select state.
If \fBindicatorOn\fR is false, this color is used as the background
for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR,
whenever the widget is selected.
If specified as an empty string then no special color is used for
displaying when the widget is selected.
.OP \-selectimage selectImage SelectImage
Specifies an image to display (in place of the \fBimage\fR option)
when the checkbutton is selected.
This option is ignored unless the \fBimage\fR option has been
specified.
.OP \-state state State
Specifies one of three states for the checkbutton: \fBnormal\fR, \fBactive\fR,
or \fBdisabled\fR. In normal state the checkbutton is displayed using the
\fBforeground\fR and \fBbackground\fR options. The active state is
typically used when the pointer is over the checkbutton. In active state
the checkbutton is displayed using the \fBactiveForeground\fR and
\fBactiveBackground\fR options. Disabled state means that the checkbutton
should be insensitive: the default bindings will refuse to activate
the widget and will ignore mouse button presses.
In this state the \fBdisabledForeground\fR and
\fBbackground\fR options determine how the checkbutton is displayed.
.OP \-tristateimage tristateImage TristateImage
.VS 8.5
Specifies an image to display (in place of the \fBimage\fR option)
when the checkbutton is in tri-state mode.
This option is ignored unless the \fBimage\fR option has been
specified.
.VE 8.5
.OP \-tristatevalue tristateValue Value
.VS 8.5
Specifies the value that causes the checkbutton to display the multi-value
selection, also known as the tri-state mode. Defaults to
.QW "" .
.VE 8.5
.OP \-variable variable Variable
Specifies the name of a global variable to set to indicate whether
or not this button is selected. Defaults to the name of the
button within its parent (i.e. the last element of the button
window's path name).
.OP \-width width Width
Specifies a desired width for the button.
If an image or bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
for text it is in characters.
If this option is not specified, the button's desired width is computed
from the size of the image or bitmap or text being displayed in it.
.BE
.SH DESCRIPTION
.PP
The \fBcheckbutton\fR command creates a new window (given by the
\fIpathName\fR argument) and makes it into a checkbutton widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the checkbutton such as its colors, font,
text, and initial relief. The \fBcheckbutton\fR command returns its
\fIpathName\fR argument. At the time this command is invoked,
there must not exist a window named \fIpathName\fR, but
\fIpathName\fR's parent must exist.
.PP
A checkbutton is a widget
that displays a textual string, bitmap or image
and a square called an \fIindicator\fR.
If text is displayed, it must all be in a single font, but it
can occupy multiple lines on the screen (if it contains newlines
or if wrapping occurs because of the \fBwrapLength\fR option) and
one of the characters may optionally be underlined using the
\fBunderline\fR option.
A checkbutton has
all of the behavior of a simple button, including the
following: it can display itself in either of three different
ways, according to the \fBstate\fR option;
it can be made to appear
raised, sunken, or flat; it can be made to flash; and it invokes
a Tcl command whenever mouse button 1 is clicked over the
checkbutton.
.PP
In addition, checkbuttons can be \fIselected\fR.
If a checkbutton is selected then the indicator is normally
drawn with a selected appearance, and
a Tcl variable associated with the checkbutton is set to a particular
value (normally 1).
.VS 8.5
The indicator is drawn with a check mark inside.
If the checkbutton is not selected, then the indicator is drawn with a
deselected appearance, and the associated variable is
set to a different value (typically 0).
The indicator is drawn without a check mark inside. In the special case
where the variable (if specified) has a value that matches the tristatevalue,
the indicator is drawn with a tri-state appearance and is in the tri-state
mode indicating mixed or multiple values. (This is used when the check
box represents the state of multiple items.)
The indicator is drawn in a platform dependent manner. Under Unix and
Windows, the background interior of the box is
.QW grayed .
Under Mac, the indicator is drawn with a dash mark inside.
By default, the name of the variable associated with a checkbutton is the
same as the \fIname\fR used to create the checkbutton.
The variable name, and the
.QW on ,
.QW off
and
.QW tristate
values stored in it, may be modified with options on the command line
or in the option database.
Configuration options may also be used to modify the way the
indicator is displayed (or whether it is displayed at all).
By default a checkbutton is configured to select and deselect
itself on alternate button clicks.
In addition, each checkbutton monitors its associated variable and
automatically selects and deselects itself when the variables value
changes to and from the button's
.QW on ,
.QW off
and
.QW tristate
values.
.VE 8.5
.SH "WIDGET COMMAND"
.PP
The \fBcheckbutton\fR command creates a new Tcl command whose
name is \fIpathName\fR. This
command may be used to invoke various
operations on the widget. It has the following general form:
.CS
\fIpathName option \fR?\fIarg arg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command. The following
commands are possible for checkbutton widgets:
.TP
\fIpathName \fBcget\fR \fIoption\fR
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
command.
.TP
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list). If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified). If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
command.
.TP
\fIpathName \fBdeselect\fR
Deselects the checkbutton and sets the associated variable to its
.QW off
value.
.TP
\fIpathName \fBflash\fR
Flashes the checkbutton. This is accomplished by redisplaying the checkbutton
several times, alternating between active and normal colors. At
the end of the flash the checkbutton is left in the same normal/active
state as when the command was invoked.
This command is ignored if the checkbutton's state is \fBdisabled\fR.
.TP
\fIpathName \fBinvoke\fR
Does just what would have happened if the user invoked the checkbutton
with the mouse: toggle the selection state of the button and invoke
the Tcl command associated with the checkbutton, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the checkbutton.
This command is ignored if the checkbutton's state is \fBdisabled\fR.
.TP
\fIpathName \fBselect\fR
Selects the checkbutton and sets the associated variable to its
.QW on
value.
.TP
\fIpathName \fBtoggle\fR
Toggles the selection state of the button, redisplaying it and
modifying its associated variable to reflect the new state.
.SH BINDINGS
.PP
Tk automatically creates class bindings for checkbuttons that give them
the following default behavior:
.IP [1]
On Unix systems, a checkbutton activates whenever the mouse passes
over it and deactivates whenever the mouse leaves the checkbutton. On
Mac and Windows systems, when mouse button 1 is pressed over a
checkbutton, the button activates whenever the mouse pointer is inside
the button, and deactivates whenever the mouse pointer leaves the
button.
.IP [2]
When mouse button 1 is pressed over a checkbutton, it is invoked (its
selection state toggles and the command associated with the button is
invoked, if there is one).
.IP [3]
When a checkbutton has the input focus, the space key causes the checkbutton
to be invoked. Under Windows, there are additional key bindings; plus
(+) and equal (=) select the button, and minus (\-) deselects the button.
.PP
If the checkbutton's state is \fBdisabled\fR then none of the above
actions occur: the checkbutton is completely non-responsive.
.PP
The behavior of checkbuttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
.SH EXAMPLE
This example shows a group of uncoupled checkbuttons.
.PP
.CS
labelframe .lbl \-text "Steps:"
\fBcheckbutton\fR .c1 \-text Lights \-variable lights
\fBcheckbutton\fR .c2 \-text Cameras \-variable cameras
\fBcheckbutton\fR .c3 \-text Action! \-variable action
pack .c1 .c2 .c3 \-in .lbl
pack .lbl
.CE
.SH "SEE ALSO"
button(n), options(n), radiobutton(n), ttk::checkbutton(n)
.SH KEYWORDS
checkbutton, widget

46
doc/chooseColor.n Normal file
View File

@@ -0,0 +1,46 @@
'\"
'\" 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.
'\"
.so man.macros
.TH tk_chooseColor n 4.2 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
tk_chooseColor \- pops up a dialog box for the user to select a color.
.SH SYNOPSIS
\fBtk_chooseColor \fR?\fIoption value ...\fR?
.BE
.SH DESCRIPTION
.PP
The procedure \fBtk_chooseColor\fR pops up a dialog box for the
user to select a color. The following \fIoption\-value\fR pairs are
possible as command line arguments:
.TP
\fB\-initialcolor\fR \fIcolor\fR
Specifies the color to display in the color dialog when it pops
up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR
function.
.TP
\fB\-parent\fR \fIwindow\fR
Makes \fIwindow\fR the logical parent of the color dialog. The color
dialog is displayed on top of its parent window.
.TP
\fB\-title\fR \fItitleString\fR
Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title will be displayed.
.LP
If the user selects a color, \fBtk_chooseColor\fR will return the
name of the color in a form acceptable to \fBTk_GetColor\fR. If the
user cancels the operation, both commands will return the empty
string.
.SH EXAMPLE
.CS
button .b \-bg [tk_chooseColor \-initialcolor gray \-title "Choose color"]
.CE
.SH KEYWORDS
color selection dialog

54
doc/chooseDirectory.n Normal file
View File

@@ -0,0 +1,54 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
.so man.macros
.TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
tk_chooseDirectory \- pops up a dialog box for the user to select a directory.
.SH SYNOPSIS
\fBtk_chooseDirectory \fR?\fIoption value ...\fR?
.BE
.SH DESCRIPTION
.PP
The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the
user to select a directory. The following \fIoption\-value\fR pairs are
possible as command line arguments:
.TP
\fB\-initialdir\fR \fIdirname\fR
Specifies that the directories in \fIdirectory\fR should be displayed
when the dialog pops up. If this parameter is not specified, then
the directories in the current working directory are displayed. If the
parameter specifies a relative path, the return value will convert the
relative path to an absolute path.
.TP
\fB\-mustexist\fR \fIboolean\fR
Specifies whether the user may specify non-existent directories. If
this parameter is true, then the user may only select directories that
already exist. The default value is \fIfalse\fR.
.TP
\fB\-parent\fR \fIwindow\fR
Makes \fIwindow\fR the logical parent of the dialog. The dialog
is displayed on top of its parent window. On Mac OS X, this
turns the file dialog into a sheet attached to the parent window.
.TP
\fB\-title\fR \fItitleString\fR
Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title will be displayed.
.SH EXAMPLE
.CS
set dir [\fBtk_chooseDirectory\fR \e
\-initialdir ~ \-title "Choose a directory"]
if {$dir eq ""} {
label .l \-text "No directory selected"
} else {
label .l \-text "Selected $dir"
}
.CE
.SH "SEE ALSO"
tk_getOpenFile(n), tk_getSaveFile(n)
.SH KEYWORDS
directory, selection, dialog, platform-specific

154
doc/clipboard.n Normal file
View File

@@ -0,0 +1,154 @@
'\"
'\" 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.
'\"
.so man.macros
.TH clipboard n 8.4 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
clipboard \- Manipulate Tk clipboard
.SH SYNOPSIS
\fBclipboard \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
This command provides a Tcl interface to the Tk clipboard,
which stores data for later retrieval using the selection mechanism
(via the \fB\-selection CLIPBOARD\fR option).
In order to copy data into the clipboard, \fBclipboard clear\fR must
be called, followed by a sequence of one or more calls to \fBclipboard
append\fR. To ensure that the clipboard is updated atomically, all
appends should be completed before returning to the event loop.
.PP
The first argument to \fBclipboard\fR determines the format of the
rest of the arguments and the behavior of the command. The following
forms are currently supported:
.PP
.TP
\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR?
Claims ownership of the clipboard on \fIwindow\fR's display and removes
any previous contents. \fIWindow\fR defaults to
.QW . .
Returns an empty string.
.TP
\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR
Appends \fIdata\fR to the clipboard on \fIwindow\fR's
display in the form given by \fItype\fR with the representation given
by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's
display.
.RS
.PP
\fIType\fR specifies the form in which the selection is to be returned
(the desired
.QW target
for conversion, in ICCCM terminology), and
should be an atom name such as STRING or FILE_NAME; see the
Inter-Client Communication Conventions Manual for complete details.
\fIType\fR defaults to STRING.
.PP
The \fIformat\fR argument specifies the representation that should be
used to transmit the selection to the requester (the second column of
Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is
STRING, the selection is transmitted as 8-bit ASCII characters. If
\fIformat\fR is ATOM, then the \fIdata\fR is
divided into fields separated by white space; each field is converted
to its atom value, and the 32-bit atom value is transmitted instead of
the atom name. For any other \fIformat\fR, \fIdata\fR is divided
into fields separated by white space and each
field is converted to a 32-bit integer; an array of integers is
transmitted to the selection requester. Note that strings passed to
\fBclipboard append\fR are concatenated before conversion, so the
caller must take care to ensure appropriate spacing across string
boundaries. All items appended to the clipboard with the same
\fItype\fR must have the same \fIformat\fR.
.PP
The \fIformat\fR argument is needed only for compatibility with
clipboard requesters that do not use Tk. If the Tk toolkit is being
used to retrieve the CLIPBOARD selection then the value is converted back to
a string at the requesting end, so \fIformat\fR is
irrelevant.
.PP
A \fB\-\|\-\fR argument may be specified to mark the end of options: the
next argument will always be used as \fIdata\fR.
This feature may be convenient if, for example, \fIdata\fR starts
with a \fB\-\fR.
.RE
.TP
\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR?
Retrieve data from the clipboard on \fIwindow\fR's display.
\fIWindow\fR defaults to
.QW . .
\fIType\fR specifies the form in which
the data is to be returned and should be an atom name such as STRING
or FILE_NAME. \fIType\fR defaults to STRING. This command is
equivalent to
.QW "\fBselection get \-selection CLIPBOARD\fR" .
.RS
.PP
Note that on modern X11 systems, the most useful type to retrieve for
transferred strings is not \fBSTRING\fR, but rather \fBUTF8_STRING\fR.
.RE
.SH EXAMPLES
Get the current contents of the clipboard.
.CS
if {[catch {\fBclipboard get\fR} contents]} {
# There were no clipboard contents at all
}
.CE
.PP
Set the clipboard to contain a fixed string.
.CS
\fBclipboard clear\fR
\fBclipboard append\fR "some fixed string"
.CE
.PP
You can put custom data into the clipboard by using a custom \fB\-type\fR
option. This is not necessarily portable, but can be very useful. The
method of passing Tcl scripts this way is effective, but should be mixed
with safe interpreters in production code.
.CS
# This is a very simple canvas serializer;
# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
set script {}
foreach item [$canvas find withtag $tag] {
append script {$canvas create } [$canvas type $item]
append script { } [$canvas coords $item] { }
foreach config [$canvas itemconf $item] {
lassign $config name \- \- \- value
append script [list $name $value] { }
}
append script \en
}
return [string trim $script]
}
# Set up a binding on a canvas to cut and paste an item
set c [canvas .c]
pack $c
$c create text 150 30 \-text "cut and paste me"
bind $c <<Cut>> {
\fBclipboard clear\fR
\fBclipboard append \-type\fR TkCanvasItem \e
[getItemConfig %W current]
# Delete because this is cut, not copy.
%W delete current
}
bind $c <<Paste>> {
catch {
set canvas %W
eval [\fBclipboard get \-type\fR TkCanvasItem]
}
}
.CE
.SH "SEE ALSO"
interp(n), selection(n)
.SH KEYWORDS
clear, format, clipboard, append, selection, type

946
doc/colors.n Normal file
View File

@@ -0,0 +1,946 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" Copyright (c) 2003 ActiveState Corporation.
'\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net>
'\" Copyright (c) 2008 Donal K. Fellows
'\"
.so man.macros
.TH colors n 8.3 Tk "Tk Built-In Commands"
.BS
.\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
colors \- symbolic color names recognized by Tk
.BE
.SH DESCRIPTION
.PP
Tk recognizes many symbolic color names (e.g., \fBred\fR) when
specifying colors. The symbolic names recognized by Tk and their
8-bit-per-channel RGB values are:
.DS
.ta 7.2cR 9.5cR 11cR
\fBName\fR \fBRed\fR \fBGreen\fR \fBBlue\fR
alice blue 240 248 255
AliceBlue 240 248 255
antique white 250 235 215
AntiqueWhite 250 235 215
AntiqueWhite1 255 239 219
AntiqueWhite2 238 223 204
AntiqueWhite3 205 192 176
AntiqueWhite4 139 131 120
aquamarine 127 255 212
aquamarine1 127 255 212
aquamarine2 118 238 198
aquamarine3 102 205 170
aquamarine4 69 139 116
azure 240 255 255
azure1 240 255 255
azure2 224 238 238
azure3 193 205 205
azure4 131 139 139
beige 245 245 220
bisque 255 228 196
bisque1 255 228 196
bisque2 238 213 183
bisque3 205 183 158
bisque4 139 125 107
black 0 0 0
blanched almond 255 235 205
BlanchedAlmond 255 235 205
blue 0 0 255
blue violet 138 43 226
blue1 0 0 255
blue2 0 0 238
blue3 0 0 205
blue4 0 0 139
BlueViolet 138 43 226
brown 165 42 42
brown1 255 64 64
brown2 238 59 59
brown3 205 51 51
brown4 139 35 35
burlywood 222 184 135
burlywood1 255 211 155
burlywood2 238 197 145
burlywood3 205 170 125
burlywood4 139 115 85
cadet blue 95 158 160
CadetBlue 95 158 160
CadetBlue1 152 245 255
CadetBlue2 142 229 238
CadetBlue3 122 197 205
CadetBlue4 83 134 139
chartreuse 127 255 0
chartreuse1 127 255 0
chartreuse2 118 238 0
chartreuse3 102 205 0
chartreuse4 69 139 0
chocolate 210 105 30
chocolate1 255 127 36
chocolate2 238 118 33
chocolate3 205 102 29
chocolate4 139 69 19
coral 255 127 80
coral1 255 114 86
coral2 238 106 80
coral3 205 91 69
coral4 139 62 47
cornflower blue 100 149 237
CornflowerBlue 100 149 237
cornsilk 255 248 220
cornsilk1 255 248 220
cornsilk2 238 232 205
cornsilk3 205 200 177
cornsilk4 139 136 120
cyan 0 255 255
cyan1 0 255 255
cyan2 0 238 238
cyan3 0 205 205
cyan4 0 139 139
dark blue 0 0 139
dark cyan 0 139 139
dark goldenrod 184 134 11
dark gray 169 169 169
dark green 0 100 0
dark grey 169 169 169
dark khaki 189 183 107
dark magenta 139 0 139
dark olive green 85 107 47
dark orange 255 140 0
dark orchid 153 50 204
dark red 139 0 0
dark salmon 233 150 122
dark sea green 143 188 143
dark slate blue 72 61 139
dark slate gray 47 79 79
dark slate grey 47 79 79
dark turquoise 0 206 209
dark violet 148 0 211
DarkBlue 0 0 139
DarkCyan 0 139 139
DarkGoldenrod 184 134 11
DarkGoldenrod1 255 185 15
DarkGoldenrod2 238 173 14
DarkGoldenrod3 205 149 12
DarkGoldenrod4 139 101 8
DarkGray 169 169 169
DarkGreen 0 100 0
DarkGrey 169 169 169
DarkKhaki 189 183 107
DarkMagenta 139 0 139
DarkOliveGreen 85 107 47
DarkOliveGreen1 202 255 112
DarkOliveGreen2 188 238 104
DarkOliveGreen3 162 205 90
DarkOliveGreen4 110 139 61
DarkOrange 255 140 0
DarkOrange1 255 127 0
DarkOrange2 238 118 0
DarkOrange3 205 102 0
DarkOrange4 139 69 0
DarkOrchid 153 50 204
DarkOrchid1 191 62 255
DarkOrchid2 178 58 238
DarkOrchid3 154 50 205
DarkOrchid4 104 34 139
DarkRed 139 0 0
DarkSalmon 233 150 122
DarkSeaGreen 143 188 143
DarkSeaGreen1 193 255 193
DarkSeaGreen2 180 238 180
DarkSeaGreen3 155 205 155
DarkSeaGreen4 105 139 105
DarkSlateBlue 72 61 139
DarkSlateGray 47 79 79
DarkSlateGray1 151 255 255
DarkSlateGray2 141 238 238
DarkSlateGray3 121 205 205
DarkSlateGray4 82 139 139
DarkSlateGrey 47 79 79
DarkTurquoise 0 206 209
DarkViolet 148 0 211
deep pink 255 20 147
deep sky blue 0 191 255
DeepPink 255 20 147
DeepPink1 255 20 147
DeepPink2 238 18 137
DeepPink3 205 16 118
DeepPink4 139 10 80
DeepSkyBlue 0 191 255
DeepSkyBlue1 0 191 255
DeepSkyBlue2 0 178 238
DeepSkyBlue3 0 154 205
DeepSkyBlue4 0 104 139
dim gray 105 105 105
dim grey 105 105 105
DimGray 105 105 105
DimGrey 105 105 105
dodger blue 30 144 255
DodgerBlue 30 144 255
DodgerBlue1 30 144 255
DodgerBlue2 28 134 238
DodgerBlue3 24 116 205
DodgerBlue4 16 78 139
firebrick 178 34 34
firebrick1 255 48 48
firebrick2 238 44 44
firebrick3 205 38 38
firebrick4 139 26 26
floral white 255 250 240
FloralWhite 255 250 240
forest green 34 139 34
ForestGreen 34 139 34
gainsboro 220 220 220
ghost white 248 248 255
GhostWhite 248 248 255
gold 255 215 0
gold1 255 215 0
gold2 238 201 0
gold3 205 173 0
gold4 139 117 0
goldenrod 218 165 32
goldenrod1 255 193 37
goldenrod2 238 180 34
goldenrod3 205 155 29
goldenrod4 139 105 20
gray 190 190 190
gray0 0 0 0
gray1 3 3 3
gray2 5 5 5
gray3 8 8 8
gray4 10 10 10
gray5 13 13 13
gray6 15 15 15
gray7 18 18 18
gray8 20 20 20
gray9 23 23 23
gray10 26 26 26
gray11 28 28 28
gray12 31 31 31
gray13 33 33 33
gray14 36 36 36
gray15 38 38 38
gray16 41 41 41
gray17 43 43 43
gray18 46 46 46
gray19 48 48 48
gray20 51 51 51
gray21 54 54 54
gray22 56 56 56
gray23 59 59 59
gray24 61 61 61
gray25 64 64 64
gray26 66 66 66
gray27 69 69 69
gray28 71 71 71
gray29 74 74 74
gray30 77 77 77
gray31 79 79 79
gray32 82 82 82
gray33 84 84 84
gray34 87 87 87
gray35 89 89 89
gray36 92 92 92
gray37 94 94 94
gray38 97 97 97
gray39 99 99 99
gray40 102 102 102
gray41 105 105 105
gray42 107 107 107
gray43 110 110 110
gray44 112 112 112
gray45 115 115 115
gray46 117 117 117
gray47 120 120 120
gray48 122 122 122
gray49 125 125 125
gray50 127 127 127
gray51 130 130 130
gray52 133 133 133
gray53 135 135 135
gray54 138 138 138
gray55 140 140 140
gray56 143 143 143
gray57 145 145 145
gray58 148 148 148
gray59 150 150 150
gray60 153 153 153
gray61 156 156 156
gray62 158 158 158
gray63 161 161 161
gray64 163 163 163
gray65 166 166 166
gray66 168 168 168
gray67 171 171 171
gray68 173 173 173
gray69 176 176 176
gray70 179 179 179
gray71 181 181 181
gray72 184 184 184
gray73 186 186 186
gray74 189 189 189
gray75 191 191 191
gray76 194 194 194
gray77 196 196 196
gray78 199 199 199
gray79 201 201 201
gray80 204 204 204
gray81 207 207 207
gray82 209 209 209
gray83 212 212 212
gray84 214 214 214
gray85 217 217 217
gray86 219 219 219
gray87 222 222 222
gray88 224 224 224
gray89 227 227 227
gray90 229 229 229
gray91 232 232 232
gray92 235 235 235
gray93 237 237 237
gray94 240 240 240
gray95 242 242 242
gray96 245 245 245
gray97 247 247 247
gray98 250 250 250
gray99 252 252 252
gray100 255 255 255
green 0 255 0
green yellow 173 255 47
green1 0 255 0
green2 0 238 0
green3 0 205 0
green4 0 139 0
GreenYellow 173 255 47
grey 190 190 190
grey0 0 0 0
grey1 3 3 3
grey2 5 5 5
grey3 8 8 8
grey4 10 10 10
grey5 13 13 13
grey6 15 15 15
grey7 18 18 18
grey8 20 20 20
grey9 23 23 23
grey10 26 26 26
grey11 28 28 28
grey12 31 31 31
grey13 33 33 33
grey14 36 36 36
grey15 38 38 38
grey16 41 41 41
grey17 43 43 43
grey18 46 46 46
grey19 48 48 48
grey20 51 51 51
grey21 54 54 54
grey22 56 56 56
grey23 59 59 59
grey24 61 61 61
grey25 64 64 64
grey26 66 66 66
grey27 69 69 69
grey28 71 71 71
grey29 74 74 74
grey30 77 77 77
grey31 79 79 79
grey32 82 82 82
grey33 84 84 84
grey34 87 87 87
grey35 89 89 89
grey36 92 92 92
grey37 94 94 94
grey38 97 97 97
grey39 99 99 99
grey40 102 102 102
grey41 105 105 105
grey42 107 107 107
grey43 110 110 110
grey44 112 112 112
grey45 115 115 115
grey46 117 117 117
grey47 120 120 120
grey48 122 122 122
grey49 125 125 125
grey50 127 127 127
grey51 130 130 130
grey52 133 133 133
grey53 135 135 135
grey54 138 138 138
grey55 140 140 140
grey56 143 143 143
grey57 145 145 145
grey58 148 148 148
grey59 150 150 150
grey60 153 153 153
grey61 156 156 156
grey62 158 158 158
grey63 161 161 161
grey64 163 163 163
grey65 166 166 166
grey66 168 168 168
grey67 171 171 171
grey68 173 173 173
grey69 176 176 176
grey70 179 179 179
grey71 181 181 181
grey72 184 184 184
grey73 186 186 186
grey74 189 189 189
grey75 191 191 191
grey76 194 194 194
grey77 196 196 196
grey78 199 199 199
grey79 201 201 201
grey80 204 204 204
grey81 207 207 207
grey82 209 209 209
grey83 212 212 212
grey84 214 214 214
grey85 217 217 217
grey86 219 219 219
grey87 222 222 222
grey88 224 224 224
grey89 227 227 227
grey90 229 229 229
grey91 232 232 232
grey92 235 235 235
grey93 237 237 237
grey94 240 240 240
grey95 242 242 242
grey96 245 245 245
grey97 247 247 247
grey98 250 250 250
grey99 252 252 252
grey100 255 255 255
honeydew 240 255 240
honeydew1 240 255 240
honeydew2 224 238 224
honeydew3 193 205 193
honeydew4 131 139 131
hot pink 255 105 180
HotPink 255 105 180
HotPink1 255 110 180
HotPink2 238 106 167
HotPink3 205 96 144
HotPink4 139 58 98
indian red 205 92 92
IndianRed 205 92 92
IndianRed1 255 106 106
IndianRed2 238 99 99
IndianRed3 205 85 85
IndianRed4 139 58 58
ivory 255 255 240
ivory1 255 255 240
ivory2 238 238 224
ivory3 205 205 193
ivory4 139 139 131
khaki 240 230 140
khaki1 255 246 143
khaki2 238 230 133
khaki3 205 198 115
khaki4 139 134 78
lavender 230 230 250
lavender blush 255 240 245
LavenderBlush 255 240 245
LavenderBlush1 255 240 245
LavenderBlush2 238 224 229
LavenderBlush3 205 193 197
LavenderBlush4 139 131 134
lawn green 124 252 0
LawnGreen 124 252 0
lemon chiffon 255 250 205
LemonChiffon 255 250 205
LemonChiffon1 255 250 205
LemonChiffon2 238 233 191
LemonChiffon3 205 201 165
LemonChiffon4 139 137 112
light blue 173 216 230
light coral 240 128 128
light cyan 224 255 255
light goldenrod 238 221 130
light goldenrod yellow 250 250 210
light gray 211 211 211
light green 144 238 144
light grey 211 211 211
light pink 255 182 193
light salmon 255 160 122
light sea green 32 178 170
light sky blue 135 206 250
light slate blue 132 112 255
light slate gray 119 136 153
light slate grey 119 136 153
light steel blue 176 196 222
light yellow 255 255 224
LightBlue 173 216 230
LightBlue1 191 239 255
LightBlue2 178 223 238
LightBlue3 154 192 205
LightBlue4 104 131 139
LightCoral 240 128 128
LightCyan 224 255 255
LightCyan1 224 255 255
LightCyan2 209 238 238
LightCyan3 180 205 205
LightCyan4 122 139 139
LightGoldenrod 238 221 130
LightGoldenrod1 255 236 139
LightGoldenrod2 238 220 130
LightGoldenrod3 205 190 112
LightGoldenrod4 139 129 76
LightGoldenrodYellow 250 250 210
LightGray 211 211 211
LightGreen 144 238 144
LightGrey 211 211 211
LightPink 255 182 193
LightPink1 255 174 185
LightPink2 238 162 173
LightPink3 205 140 149
LightPink4 139 95 101
LightSalmon 255 160 122
LightSalmon1 255 160 122
LightSalmon2 238 149 114
LightSalmon3 205 129 98
LightSalmon4 139 87 66
LightSeaGreen 32 178 170
LightSkyBlue 135 206 250
LightSkyBlue1 176 226 255
LightSkyBlue2 164 211 238
LightSkyBlue3 141 182 205
LightSkyBlue4 96 123 139
LightSlateBlue 132 112 255
LightSlateGray 119 136 153
LightSlateGrey 119 136 153
LightSteelBlue 176 196 222
LightSteelBlue1 202 225 255
LightSteelBlue2 188 210 238
LightSteelBlue3 162 181 205
LightSteelBlue4 110 123 139
LightYellow 255 255 224
LightYellow1 255 255 224
LightYellow2 238 238 209
LightYellow3 205 205 180
LightYellow4 139 139 122
lime green 50 205 50
LimeGreen 50 205 50
linen 250 240 230
magenta 255 0 255
magenta1 255 0 255
magenta2 238 0 238
magenta3 205 0 205
magenta4 139 0 139
maroon 176 48 96
maroon1 255 52 179
maroon2 238 48 167
maroon3 205 41 144
maroon4 139 28 98
medium aquamarine 102 205 170
medium blue 0 0 205
medium orchid 186 85 211
medium purple 147 112 219
medium sea green 60 179 113
medium slate blue 123 104 238
medium spring green 0 250 154
medium turquoise 72 209 204
medium violet red 199 21 133
MediumAquamarine 102 205 170
MediumBlue 0 0 205
MediumOrchid 186 85 211
MediumOrchid1 224 102 255
MediumOrchid2 209 95 238
MediumOrchid3 180 82 205
MediumOrchid4 122 55 139
MediumPurple 147 112 219
MediumPurple1 171 130 255
MediumPurple2 159 121 238
MediumPurple3 137 104 205
MediumPurple4 93 71 139
MediumSeaGreen 60 179 113
MediumSlateBlue 123 104 238
MediumSpringGreen 0 250 154
MediumTurquoise 72 209 204
MediumVioletRed 199 21 133
midnight blue 25 25 112
MidnightBlue 25 25 112
mint cream 245 255 250
MintCream 245 255 250
misty rose 255 228 225
MistyRose 255 228 225
MistyRose1 255 228 225
MistyRose2 238 213 210
MistyRose3 205 183 181
MistyRose4 139 125 123
moccasin 255 228 181
navajo white 255 222 173
NavajoWhite 255 222 173
NavajoWhite1 255 222 173
NavajoWhite2 238 207 161
NavajoWhite3 205 179 139
NavajoWhite4 139 121 94
navy 0 0 128
navy blue 0 0 128
NavyBlue 0 0 128
old lace 253 245 230
OldLace 253 245 230
olive drab 107 142 35
OliveDrab 107 142 35
OliveDrab1 192 255 62
OliveDrab2 179 238 58
OliveDrab3 154 205 50
OliveDrab4 105 139 34
orange 255 165 0
orange red 255 69 0
orange1 255 165 0
orange2 238 154 0
orange3 205 133 0
orange4 139 90 0
OrangeRed 255 69 0
OrangeRed1 255 69 0
OrangeRed2 238 64 0
OrangeRed3 205 55 0
OrangeRed4 139 37 0
orchid 218 112 214
orchid1 255 131 250
orchid2 238 122 233
orchid3 205 105 201
orchid4 139 71 137
pale goldenrod 238 232 170
pale green 152 251 152
pale turquoise 175 238 238
pale violet red 219 112 147
PaleGoldenrod 238 232 170
PaleGreen 152 251 152
PaleGreen1 154 255 154
PaleGreen2 144 238 144
PaleGreen3 124 205 124
PaleGreen4 84 139 84
PaleTurquoise 175 238 238
PaleTurquoise1 187 255 255
PaleTurquoise2 174 238 238
PaleTurquoise3 150 205 205
PaleTurquoise4 102 139 139
PaleVioletRed 219 112 147
PaleVioletRed1 255 130 171
PaleVioletRed2 238 121 159
PaleVioletRed3 205 104 127
PaleVioletRed4 139 71 93
papaya whip 255 239 213
PapayaWhip 255 239 213
peach puff 255 218 185
PeachPuff 255 218 185
PeachPuff1 255 218 185
PeachPuff2 238 203 173
PeachPuff3 205 175 149
PeachPuff4 139 119 101
peru 205 133 63
pink 255 192 203
pink1 255 181 197
pink2 238 169 184
pink3 205 145 158
pink4 139 99 108
plum 221 160 221
plum1 255 187 255
plum2 238 174 238
plum3 205 150 205
plum4 139 102 139
powder blue 176 224 230
PowderBlue 176 224 230
purple 160 32 240
purple1 155 48 255
purple2 145 44 238
purple3 125 38 205
purple4 85 26 139
red 255 0 0
red1 255 0 0
red2 238 0 0
red3 205 0 0
red4 139 0 0
rosy brown 188 143 143
RosyBrown 188 143 143
RosyBrown1 255 193 193
RosyBrown2 238 180 180
RosyBrown3 205 155 155
RosyBrown4 139 105 105
royal blue 65 105 225
RoyalBlue 65 105 225
RoyalBlue1 72 118 255
RoyalBlue2 67 110 238
RoyalBlue3 58 95 205
RoyalBlue4 39 64 139
saddle brown 139 69 19
SaddleBrown 139 69 19
salmon 250 128 114
salmon1 255 140 105
salmon2 238 130 98
salmon3 205 112 84
salmon4 139 76 57
sandy brown 244 164 96
SandyBrown 244 164 96
sea green 46 139 87
SeaGreen 46 139 87
SeaGreen1 84 255 159
SeaGreen2 78 238 148
SeaGreen3 67 205 128
SeaGreen4 46 139 87
seashell 255 245 238
seashell1 255 245 238
seashell2 238 229 222
seashell3 205 197 191
seashell4 139 134 130
sienna 160 82 45
sienna1 255 130 71
sienna2 238 121 66
sienna3 205 104 57
sienna4 139 71 38
sky blue 135 206 235
SkyBlue 135 206 235
SkyBlue1 135 206 255
SkyBlue2 126 192 238
SkyBlue3 108 166 205
SkyBlue4 74 112 139
slate blue 106 90 205
slate gray 112 128 144
slate grey 112 128 144
SlateBlue 106 90 205
SlateBlue1 131 111 255
SlateBlue2 122 103 238
SlateBlue3 105 89 205
SlateBlue4 71 60 139
SlateGray 112 128 144
SlateGray1 198 226 255
SlateGray2 185 211 238
SlateGray3 159 182 205
SlateGray4 108 123 139
SlateGrey 112 128 144
snow 255 250 250
snow1 255 250 250
snow2 238 233 233
snow3 205 201 201
snow4 139 137 137
spring green 0 255 127
SpringGreen 0 255 127
SpringGreen1 0 255 127
SpringGreen2 0 238 118
SpringGreen3 0 205 102
SpringGreen4 0 139 69
steel blue 70 130 180
SteelBlue 70 130 180
SteelBlue1 99 184 255
SteelBlue2 92 172 238
SteelBlue3 79 148 205
SteelBlue4 54 100 139
tan 210 180 140
tan1 255 165 79
tan2 238 154 73
tan3 205 133 63
tan4 139 90 43
thistle 216 191 216
thistle1 255 225 255
thistle2 238 210 238
thistle3 205 181 205
thistle4 139 123 139
tomato 255 99 71
tomato1 255 99 71
tomato2 238 92 66
tomato3 205 79 57
tomato4 139 54 38
turquoise 64 224 208
turquoise1 0 245 255
turquoise2 0 229 238
turquoise3 0 197 205
turquoise4 0 134 139
violet 238 130 238
violet red 208 32 144
VioletRed 208 32 144
VioletRed1 255 62 150
VioletRed2 238 58 140
VioletRed3 205 50 120
VioletRed4 139 34 82
wheat 245 222 179
wheat1 255 231 186
wheat2 238 216 174
wheat3 205 186 150
wheat4 139 126 102
white 255 255 255
white smoke 245 245 245
WhiteSmoke 245 245 245
yellow 255 255 0
yellow green 154 205 50
yellow1 255 255 0
yellow2 238 238 0
yellow3 205 205 0
yellow4 139 139 0
YellowGreen 154 205 50
.DE
.SH "PORTABILITY ISSUES"
.TP
\fBMac OS X\fR
.
On Mac OS X, the following additional system colors are available
(note that the actual color values depend on the currently active OS theme,
and typically many of these will in fact be patterns rather than pure colors):
.RS
.DS
systemActiveAreaFill
systemAlertActiveText
systemAlertBackgroundActive
systemAlertBackgroundInactive
systemAlertInactiveText
systemAlternatePrimaryHighlightColor
systemAppleGuideCoachmark
systemBevelActiveDark
systemBevelActiveLight
systemBevelButtonActiveText
systemBevelButtonInactiveText
systemBevelButtonPressedText
systemBevelButtonStickyActiveText
systemBevelButtonStickyInactiveText
systemBevelInactiveDark
systemBevelInactiveLight
systemBlack
systemBlackText
systemButtonActiveDarkHighlight
systemButtonActiveDarkShadow
systemButtonActiveLightHighlight
systemButtonActiveLightShadow
systemButtonFace
systemButtonFaceActive
systemButtonFaceInactive
systemButtonFacePressed
systemButtonFrame
systemButtonFrameActive
systemButtonFrameInactive
systemButtonInactiveDarkHighlight
systemButtonInactiveDarkShadow
systemButtonInactiveLightHighlight
systemButtonInactiveLightShadow
systemButtonPressedDarkHighlight
systemButtonPressedDarkShadow
systemButtonPressedLightHighlight
systemButtonPressedLightShadow
systemButtonText
systemChasingArrows
systemDialogActiveText
systemDialogBackgroundActive
systemDialogBackgroundInactive
systemDialogInactiveText
systemDocumentWindowBackground
systemDocumentWindowTitleActiveText
systemDocumentWindowTitleInactiveText
systemDragHilite
systemDrawerBackground
systemFinderWindowBackground
systemFocusHighlight
systemHighlight
systemHighlightAlternate
systemHighlightSecondary
systemHighlightText
systemIconLabelBackground
systemIconLabelBackgroundSelected
systemIconLabelSelectedText
systemIconLabelText
systemListViewBackground
systemListViewColumnDivider
systemListViewEvenRowBackground
systemListViewOddRowBackground
systemListViewSeparator
systemListViewSortColumnBackground
systemListViewText
systemListViewWindowHeaderBackground
systemMenu
systemMenuActive
systemMenuActiveText
systemMenuBackground
systemMenuBackgroundSelected
systemMenuDisabled
systemMenuItemActiveText
systemMenuItemDisabledText
systemMenuItemSelectedText
systemMenuText
systemMetalBackground
systemModelessDialogActiveText
systemModelessDialogBackgroundActive
systemModelessDialogBackgroundInactive
systemModelessDialogInactiveText
systemMovableModalBackground
systemMovableModalWindowTitleActiveText
systemMovableModalWindowTitleInactiveText
systemNotificationText
systemNotificationWindowBackground
systemPlacardActiveText
systemPlacardBackground
systemPlacardInactiveText
systemPlacardPressedText
systemPopupArrowActive
systemPopupArrowInactive
systemPopupArrowPressed
systemPopupButtonActiveText
systemPopupButtonInactiveText
systemPopupButtonPressedText
systemPopupLabelActiveText
systemPopupLabelInactiveText
systemPopupWindowTitleActiveText
systemPopupWindowTitleInactiveText
systemPrimaryHighlightColor
systemPushButtonActiveText
systemPushButtonInactiveText
systemPushButtonPressedText
systemRootMenuActiveText
systemRootMenuDisabledText
systemRootMenuSelectedText
systemScrollBarDelimiterActive
systemScrollBarDelimiterInactive
systemSecondaryGroupBoxBackground
systemSecondaryHighlightColor
systemSheetBackground
systemSheetBackgroundOpaque
systemSheetBackgroundTransparent
systemStaticAreaFill
systemSystemDetailText
systemTabFrontActiveText
systemTabFrontInactiveText
systemTabNonFrontActiveText
systemTabNonFrontInactiveText
systemTabNonFrontPressedText
systemTabPaneBackground
systemToolbarBackground
systemTransparent
systemUtilityWindowBackgroundActive
systemUtilityWindowBackgroundInactive
systemUtilityWindowTitleActiveText
systemUtilityWindowTitleInactiveText
systemWhite
systemWhiteText
systemWindowBody
systemWindowHeaderActiveText
systemWindowHeaderBackground
systemWindowHeaderInactiveText
.DE
.RE
.TP
\fBWindows\fR
.
On Windows, the following additional system colors are available
(note that the actual color values depend on the currently active OS theme):
.RS
.DS
.ta 6c
3dDarkShadow Highlight
3dLight HighlightText
ActiveBorder InactiveBorder
ActiveCaption InactiveCaption
AppWorkspace InactiveCaptionText
Background InfoBackground
ButtonFace InfoText
ButtonHighlight Menu
ButtonShadow MenuText
ButtonText Scrollbar
CaptionText Window
DisabledText WindowFrame
GrayText WindowText
.DE
.RE
.SH "SEE ALSO"
options(n), Tk_GetColor(3)
.SH KEYWORDS
color, option

141
doc/console.n Normal file
View File

@@ -0,0 +1,141 @@
'\"
'\" Copyright (c) 2001 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
.TH console n 8.4 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
console \- Control the console on systems without a real console
.SH SYNOPSIS
\fBconsole\fR \fIsubcommand\fR ?\fIarg ...\fR?
.BE
.SH DESCRIPTION
.PP
The console window is a replacement for a real console to allow input
and output on the standard I/O channels on platforms that do not have
a real console. It is implemented as a separate interpreter with the
Tk toolkit loaded, and control over this interpreter is given through
the \fBconsole\fR command. The behaviour of the console window is
defined mainly through the contents of the \fIconsole.tcl\fR file in
the Tk library. Except for TkAqua, this command is not available when
Tk is loaded into a tclsh interpreter with
.QW "\fBpackage require Tk\fR" ,
as a conventional terminal is expected to be present in that case.
In TkAqua, this command is ony available when stdin is \fB/dev/null\fR
(as is the case e.g. when the application embedding Tk is started
from the Mac OS X Finder).
.PP
.TP
\fBconsole eval \fIscript\fR
Evaluate the \fIscript\fR argument as a Tcl script in the console
interpreter. The normal interpreter is accessed through the
\fBconsoleinterp\fR command in the console interpreter.
.TP
\fBconsole hide\fR
Hide the console window from view. Precisely equivalent to
withdrawing the \fB.\fR window in the console interpreter.
.TP
\fBconsole show\fR
Display the console window. Precisely equivalent to deiconifying the
\fB.\fR window in the console interpreter.
.TP
\fBconsole title \fR?\fIstring\fR?
Query or modify the title of the console window. If \fIstring\fR is
not specified, queries the title of the console window, and sets the
title of the console window to \fIstring\fR otherwise. Precisely
equivalent to using the \fBwm title\fR command in the console
interpreter.
.SH "ACCESS TO THE MAIN INTERPRETER"
.PP
The \fBconsoleinterp\fR command in the console interpreter allows
scripts to be evaluated in the main interpreter. It supports two
subcommands: \fBeval\fR and \fBrecord\fR.
.PP
.TP
\fBconsoleinterp eval \fIscript\fR
Evaluates \fIscript\fR as a Tcl script at the global level in the main
interpreter.
.TP
\fBconsoleinterp record \fIscript\fR
Records and evaluates \fIscript\fR as a Tcl script at the global level
in the main interpreter as if \fIscript\fR had been typed in at the
console.
.SH "ADDITIONAL TRAP CALLS"
.PP
There are several additional commands in the console interpreter that
are called in response to activity in the main interpreter.
\fIThese are documented here for completeness only; they form part of
the internal implementation of the console and are likely to change or
be modified without warning.\fR
.PP
Output to the console from the main interpreter via the stdout and
stderr channels is handled by invoking the \fBtk::ConsoleOutput\fR
command in the console interpreter with two arguments. The first
argument is the name of the channel being written to, and the second
argument is the string being written to the channel (after encoding
and end-of-line translation processing has been performed.)
.PP
When the \fB.\fR window of the main interpreter is destroyed, the
\fBtk::ConsoleExit\fR command in the console interpreter is called
(assuming the console interpreter has not already been deleted itself,
that is.)
.SH "DEFAULT BINDINGS"
.PP
The default script creates a console window (implemented using a text
widget) that has the following behaviour:
.IP [1]
Pressing the tab key inserts a TAB character (as defined by the Tcl
\et escape.)
.IP [2]
Pressing the return key causes the current line (if complete by the
rules of \fBinfo complete\fR) to be passed to the main interpreter for
evaluation.
.IP [3]
Pressing the delete key deletes the selected text (if any text is
selected) or the character to the right of the cursor (if not at the
end of the line.)
.IP [4]
Pressing the backspace key deletes the selected text (if any text is
selected) or the character to the left of the cursor (of not at the
start of the line.)
.IP [5]
Pressing either Control+A or the home key causes the cursor to go to
the start of the line (but after the prompt, if a prompt is present on
the line.)
.IP [6]
Pressing either Control+E or the end key causes the cursor to go to
the end of the line.
.IP [7]
Pressing either Control+P or the up key causes the previous entry in
the command history to be selected.
.IP [8]
Pressing either Control+N or the down key causes the next entry in the
command history to be selected.
.IP [9]
Pressing either Control+B or the left key causes the cursor to move
one character backward as long as the cursor is not at the prompt.
.IP [10]
Pressing either Control+F or the right key causes the cursor to move
one character forward.
.IP [11]
Pressing F9 rebuilds the console window by destroying all its children
and reloading the Tcl script that defined the console's behaviour.
.PP
Most other behaviour is the same as a conventional text widget except
for the way that the \fI<<Cut>>\fR event is handled identically to the
\fI<<Copy>>\fR event.
.SH EXAMPLE
Not all platforms have the \fBconsole\fR command, so debugging code
often has the following code fragment in it so output produced by
\fBputs\fR can be seen while during development:
.CS
catch {\fBconsole show\fR}
.CE
.SH "SEE ALSO"
destroy(n), fconfigure(n), history(n), interp(n), puts(n), text(n), wm(n)
.SH KEYWORDS
console, interpreter, window, interactive, output channels

171
doc/cursors.n Normal file
View File

@@ -0,0 +1,171 @@
'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\"
'\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net>
'\"
.so man.macros
.TH cursors n 8.3 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
cursors \- mouse cursors available in Tk
.BE
.SH DESCRIPTION
.PP
The \fB\-cursor\fR widget option allows a Tk programmer to change the
mouse cursor for a particular widget. The cursor names recognized by
Tk on all platforms are:
.CS
X_cursor
arrow
based_arrow_down
based_arrow_up
boat
bogosity
bottom_left_corner
bottom_right_corner
bottom_side
bottom_tee
box_spiral
center_ptr
circle
clock
coffee_mug
cross
cross_reverse
crosshair
diamond_cross
dot
dotbox
double_arrow
draft_large
draft_small
draped_box
exchange
fleur
gobbler
gumby
hand1
hand2
heart
icon
iron_cross
left_ptr
left_side
left_tee
leftbutton
ll_angle
lr_angle
man
middlebutton
mouse
none
pencil
pirate
plus
question_arrow
right_ptr
right_side
right_tee
rightbutton
rtl_logo
sailboat
sb_down_arrow
sb_h_double_arrow
sb_left_arrow
sb_right_arrow
sb_up_arrow
sb_v_double_arrow
shuttle
sizing
spider
spraycan
star
target
tcross
top_left_arrow
top_left_corner
top_right_corner
top_side
top_tee
trek
ul_angle
umbrella
ur_angle
watch
xterm
.CE
.PP
The \fBnone\fR cursor can be specified to eliminate the cursor.
.SH "PORTABILITY ISSUES"
.TP
\fBWindows\fR
On Windows systems, the following cursors are mapped to native cursors:
.RS
.CS
arrow
center_ptr
crosshair
fleur
ibeam
icon
none
sb_h_double_arrow
sb_v_double_arrow
watch
xterm
.CE
And the following additional cursors are available:
.CS
no
starting
size
size_ne_sw
size_ns
size_nw_se
size_we
uparrow
wait
.CE
.RE
.TP
\fBMac OS X\fR
On Mac OS X systems, the following cursors are mapped to native cursors:
.RS
.CS
arrow
cross
crosshair
ibeam
none
plus
watch
xterm
.CE
And the following additional native cursors are available:
.CS
copyarrow
aliasarrow
contextualmenuarrow
text
cross-hair
closedhand
openhand
pointinghand
resizeleft
resizeright
resizeleftright
resizeup
resizedown
resizeupdown
notallowed
poof
countinguphand
countingdownhand
countingupanddownhand
spinning
.CE
.RE
.SH KEYWORDS
cursor, option

42
doc/destroy.n Normal file
View File

@@ -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.
'\"
.so man.macros
.TH destroy n "" Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
destroy \- Destroy one or more windows
.SH SYNOPSIS
\fBdestroy \fR?\fIwindow window ...\fR?
.BE
.SH DESCRIPTION
.PP
This command deletes the windows given by the
\fIwindow\fR arguments, plus all of their descendants.
If a \fIwindow\fR
.QW .
is deleted then all windows will be destroyed and the application will
(normally) exit.
The \fIwindow\fRs are destroyed in order, and if an error occurs
in destroying a window the command aborts without destroying the
remaining windows.
No error is returned if \fIwindow\fR does not exist.
.SH EXAMPLE
Destroy all checkbuttons that are direct children of the given widget:
.CS
proc killCheckbuttonChildren {parent} {
foreach w [winfo children $parent] {
if {[winfo class $w] eq "Checkbutton"} {
\fBdestroy\fR $w
}
}
}
.CE
.SH KEYWORDS
application, destroy, window

71
doc/dialog.n Normal file
View File

@@ -0,0 +1,71 @@
'\"
'\" 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.
'\"
.so man.macros
.TH tk_dialog n 4.1 Tk "Tk Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
tk_dialog \- Create modal dialog and wait for response
.SH SYNOPSIS
\fBtk_dialog \fIwindow title text bitmap default string string ...\fR
.BE
.SH DESCRIPTION
.PP
This procedure is part of the Tk script library.
Its arguments describe a dialog box:
.TP
\fIwindow\fR
Name of top-level window to use for dialog. Any existing window
by this name is destroyed.
.TP
\fItitle\fR
Text to appear in the window manager's title bar for the dialog.
.TP
\fItext\fR
Message to appear in the top portion of the dialog box.
.TP
\fIbitmap\fR
If non-empty, specifies a bitmap to display in the top portion of
the dialog, to the left of the text.
If this is an empty string then no bitmap is displayed in the dialog.
.TP
\fIdefault\fR
If this is an integer greater than or equal to zero, then it gives
the index of the button that is to be the default button for the dialog
(0 for the leftmost button, and so on).
If less than zero or an empty string then there will not be any default
button.
.TP
\fIstring\fR
There will be one button for each of these arguments.
Each \fIstring\fR specifies text to display in a button,
in order from left to right.
.PP
After creating a dialog box, \fBtk_dialog\fR waits for the user to
select one of the buttons either by clicking on the button with the
mouse or by typing return to invoke the default button (if any).
Then it returns the index of the selected button: 0 for the leftmost
button, 1 for the button next to it, and so on.
If the dialog's window is destroyed before the user selects one
of the buttons, then \-1 is returned.
.PP
While waiting for the user to respond, \fBtk_dialog\fR sets a local
grab. This prevents the user from interacting with the application
in any way except to invoke the dialog box.
.SH EXAMPLE
.CS
set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \e
questhead 0 Yes No "I'm not sure"]
.CE
.SH "SEE ALSO"
tk_messageBox(n)
.SH KEYWORDS
bitmap, dialog, modal

Some files were not shown because too many files have changed in this diff Show More