diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:55:50 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:55:50 (GMT) |
commit | ff51550ee89b473c63df78de6b2a413f21105687 (patch) | |
tree | bcdca927ed2a7b05c647b9a6bfdfd4a7ca5c730e /tk8.6/doc | |
parent | 01cbf5b15ea760408c24288ccb5cf8e0af9aa299 (diff) | |
download | blt-ff51550ee89b473c63df78de6b2a413f21105687.zip blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.gz blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.bz2 |
update tcl/tk
Diffstat (limited to 'tk8.6/doc')
177 files changed, 0 insertions, 34391 deletions
diff --git a/tk8.6/doc/3DBorder.3 b/tk8.6/doc/3DBorder.3 deleted file mode 100644 index f2f0eb8..0000000 --- a/tk8.6/doc/3DBorder.3 +++ /dev/null @@ -1,294 +0,0 @@ -'\" -'\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_3DBorder -\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -Tk_3DBorder -\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR -.sp -Tk_3DBorder -\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.sp -void -\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR -.sp -void -\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR -.sp -void -\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR -.sp -void -\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR -.sp -void -\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR -.sp -void -\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR -.sp -void -\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR -.sp -const char * -\fBTk_NameOf3DBorder(\fIborder\fB)\fR -.sp -XColor * -\fBTk_3DBorderColor(\fIborder\fB)\fR -.sp -GC * -\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR -.sp -\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.sp -\fBTk_Free3DBorder(\fIborder\fB)\fR -.SH ARGUMENTS -.AS "Tk_3DBorder" borderWidth -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window (for all procedures except \fBTk_Get3DBorder\fR, -must be the window for which the border was allocated). -.AP Tcl_Obj *objPtr in -Pointer to value whose value describes color corresponding to -background (flat areas). Illuminated edges will be brighter than -this and shadowed edges will be darker than this. -.AP char *colorName in -Same as \fIobjPtr\fR except value is supplied as a string rather -than a value. -.AP Drawable drawable in -X token for window or pixmap; indicates where graphics are to be drawn. -Must either be the X window for \fItkwin\fR or a pixmap with the -same screen and depth as \fItkwin\fR. -.AP Tk_3DBorder border in -Token for border previously allocated in call to \fBTk_Get3DBorder\fR. -.AP int x in -X-coordinate of upper-left corner of rectangle describing border -or bevel, in pixels. -.AP int y in -Y-coordinate of upper-left corner of rectangle describing border or -bevel, in pixels. -.AP int width in -Width of rectangle describing border or bevel, in pixels. -.AP int height in -Height of rectangle describing border or bevel, in pixels. -.AP int borderWidth in -Width of border in pixels. Positive means border is inside rectangle -given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means -border is outside rectangle. -.AP int relief in -Indicates 3-D position of interior of value relative to exterior; -should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, -\fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR -for \fBTk_Fill3DRectangle\fR). -.AP XPoint *pointPtr in -Pointer to array of points describing the set of vertices in a polygon. -The polygon need not be closed (it will be closed automatically if it -is not). -.AP int numPoints in -Number of points at \fI*pointPtr\fR. -.AP int polyBorderWidth in -Width of border in pixels. If positive, border is drawn to left of -trajectory given by \fIpointPtr\fR; if negative, border is drawn to -right of trajectory. If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or -\fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory. -.AP int leftRelief in -Height of left side of polygon's path relative to right. \fBTK_RELIEF_RAISED\fR -means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side -should appear higher; -\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things. -For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to -indicate no difference in height. -.AP int leftBevel in -Non-zero means this bevel forms the left side of the value; zero means -it forms the right side. -.AP int leftIn in -Non-zero means that the left edge of the horizontal bevel angles in, -so that the bottom of the edge is farther to the right than -the top. -Zero means the edge angles out, so that the bottom is farther to the -left than the top. -.AP int rightIn in -Non-zero means that the right edge of the horizontal bevel angles in, -so that the bottom of the edge is farther to the left than the top. -Zero means the edge angles out, so that the bottom is farther to the -right than the top. -.AP int topBevel in -Non-zero means this bevel forms the top side of the value; zero means -it forms the bottom side. -.AP int which in -Specifies which of the border's graphics contexts is desired. -Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. -.BE -.SH DESCRIPTION -.PP -These procedures provide facilities for drawing window borders in a -way that produces a three-dimensional appearance. -\fBTk_Alloc3DBorderFromObj\fR -allocates colors and Pixmaps needed to draw a border in the window -given by the \fItkwin\fR argument. The value of \fIobjPtr\fR -is a standard Tk color name that determines the border colors. -The color indicated by \fIobjPtr\fR will not actually be used in -the border; it indicates the background color for the window -(i.e. a color for flat surfaces). -The illuminated portions of the border will appear brighter than indicated -by \fIobjPtr\fR, and the shadowed portions of the border will appear -darker than \fIobjPtr\fR. -.PP -\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls -to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information -for the border (e.g. a bogus color name was given) -then NULL is returned and an error message is left as the result of -interpreter \fIinterp\fR. -If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches -information about the return value in \fIobjPtr\fR, which speeds up -future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except -that the color is specified with a string instead of a value. This -prevents \fBTk_Get3DBorder\fR from caching the return value, so -\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. -.PP -\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given -the window and color name used to create the border. -\fBTk_Get3DBorderFromObj\fR does not actually create the border; it must -already have been created with a previous call to -\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be -invoked to draw the border. -The \fItkwin\fR argument specifies the -window for which the border was allocated, and \fIdrawable\fR -specifies a window or pixmap in which the border is to be drawn. -\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it -must refer to a compatible -pixmap or window: one associated with the same screen and with the -same depth as \fItkwin\fR. -The \fIx\fR, \fIy\fR, \fIwidth\fR, and -\fIheight\fR arguments define the bounding box of the border region -within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and -\fIwidth\fR and \fIheight\fR are the dimensions of the window), and -\fIborderWidth\fR specifies the number of pixels actually -occupied by the border. The \fIrelief\fR argument indicates -which of several three-dimensional effects is desired: -\fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should -appear raised relative to the exterior of the rectangle, and -\fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. -\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be -a groove or ridge around the exterior of the rectangle. -.PP -\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except -that it first fills the rectangular area with the background color -(one corresponding -to the color used to create \fIborder\fR). Then it calls -\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of -the rectangular area. The argument \fIrelief\fR indicates the desired -effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that -happens is to fill the rectangle with the background color). -.PP -The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex -shapes with a three-dimensional appearance. The \fIpointPtr\fR and -\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR -indicates how wide the border should be (and on which side of the -trajectory to draw it), and \fIleftRelief\fR indicates which side -of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR -draws a border around the given trajectory using the colors from -\fIborder\fR to produce a three-dimensional appearance. If the trajectory is -non-self-intersecting, the appearance will be a raised or sunken -polygon shape. The trajectory may be self-intersecting, although -it's not clear how useful this is. -.PP -\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what -\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills -the polygonal area with the background color from \fIborder\fR, -then calls \fBTk_Draw3DPolygon\fR to draw a border around the -area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no -border is drawn). -.PP -The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR -provide lower-level drawing primitives that are used by -procedures such as \fBTk_Draw3DRectangle\fR. -These procedures are also useful in their own right for drawing -rectilinear border shapes. -\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the -left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR -draws a horizontal beveled edge, such as the top or bottom of a -rectangle. -Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -arguments that describe the rectangular area of the beveled edge -(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). -The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the -position of the border relative to the -.QW inside -of the value, and -\fIrelief\fR indicates the relief of the inside of the value relative -to the outside. -\fBTk_3DVerticalBevel\fR just draws a rectangular region. -\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate -mitered corners; it should be called after \fBTk_3DVerticalBevel\fR -(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in -the corner). -The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR -describe the mitering at the corners; a value of 1 means that the bottom -edge of the trapezoid will be shorter than the top, 0 means it will -be longer. -For example, to draw a rectangular border the top bevel should be -drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the -bottom bevel should be drawn with 0 for both arguments. -.PP -The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background -pixel and/or pixmap of \fItkwin\fR to produce a result compatible -with \fIborder\fR. For color displays, the resulting background will -just be the color specified when \fIborder\fR was created; for monochrome -displays, the resulting background -will be a light stipple pattern, in order to distinguish the background from -the illuminated portion of the border. -.PP -Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR -will return the color name that was used to create the border. -.PP -The procedure \fBTk_3DBorderColor\fR returns the XColor structure -that will be used for flat surfaces drawn for its \fIborder\fR -argument by procedures like \fBTk_Fill3DRectangle\fR. -The return value corresponds to the color name that was used to -create the border. -The XColor, and its associated pixel value, will remain allocated -as long as \fIborder\fR exists. -.PP -The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts -that are used to draw the border. -The argument \fIwhich\fR selects which one of the three possible GC's: -\fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces, -\fBTK_3D_LIGHT_GC\fR returns the context for light shadows, -and \fBTK_3D_DARK_GC\fR returns the context for dark shadows. -.PP -When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR -or \fBTk_Free3DBorder\fR should -be called to release the resources associated with it. -For \fBTk_Free3DBorderFromObj\fR the border to release is specified -with the window and color name used to create the -border; for \fBTk_Free3DBorder\fR the border to release is specified -with the Tk_3DBorder token for the border. -There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or -\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR -or \fBTk_Get3DBorder\fR. -.SH KEYWORDS -3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect diff --git a/tk8.6/doc/AddOption.3 b/tk8.6/doc/AddOption.3 deleted file mode 100644 index 2368f09..0000000 --- a/tk8.6/doc/AddOption.3 +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH Tk_AddOption 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_AddOption \- Add an option to the option database -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -void -\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR) -.SH ARGUMENTS -.AP Tk_Window tkwin in -Token for window. -.AP "const char" *name in -Multi-element name of option. -.AP "const char" *value in -Value of option. -.AP int priority in -Overall priority level to use for option. -.BE -.SH DESCRIPTION -.PP -This procedure is invoked to add an option to the database -associated with \fItkwin\fR's main window. \fIName\fR -contains the option being specified and consists of names and/or -classes separated by asterisks or dots, in the usual X format. -\fIValue\fR contains the text string to associate with \fIname\fR; -this value will be returned in calls to \fBTk_GetOption\fR. -\fIPriority\fR specifies the priority of the value; when options are -queried using \fBTk_GetOption\fR, the value with the highest priority -is returned. \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR. Some -common priority values are: -.IP 20 -Used for default values hard-coded into widgets. -.IP 40 -Used for options specified in application-specific startup files. -.IP 60 -Used for options specified in user-specific defaults files, such as -\fB.Xdefaults\fR, resource databases loaded into the X server, or -user-specific startup files. -.IP 80 -Used for options specified interactively after the application starts -running. -.SH KEYWORDS -class, name, option, add diff --git a/tk8.6/doc/BindTable.3 b/tk8.6/doc/BindTable.3 deleted file mode 100644 index 5130bfc..0000000 --- a/tk8.6/doc/BindTable.3 +++ /dev/null @@ -1,153 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_BindingTable -\fBTk_CreateBindingTable(\fIinterp\fB)\fR -.sp -\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR -.sp -unsigned long -\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR -.sp -int -\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR -.sp -const char * -\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR -.sp -\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR -.sp -\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR -.sp -\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR -.SH ARGUMENTS -.AS Tk_BindingTable bindingTable -.AP Tcl_Interp *interp in -Interpreter to use when invoking bindings in binding table. Also -used for returning results and errors from binding procedures. -.AP Tk_BindingTable bindingTable in -Token for binding table; must have been returned by some previous -call to \fBTk_CreateBindingTable\fR. -.AP ClientData object in -Identifies object with which binding is associated. -.AP "const char" *eventString in -String describing event sequence. -.AP "const char" *script in -Tcl script to invoke when binding triggers. -.AP int append in -Non-zero means append \fIscript\fR to existing script for binding, -if any; zero means replace existing script with new one. -.AP XEvent *eventPtr in -X event to match against bindings in \fIbindingTable\fR. -.AP Tk_Window tkwin in -Identifier for any window on the display where the event occurred. -Used to find display-related information such as key maps. -.AP int numObjects in -Number of object identifiers pointed to by \fIobjectPtr\fR. -.AP ClientData *objectPtr in -Points to an array of object identifiers: bindings will be considered -for each of these objects in order from first to last. -.BE -.SH DESCRIPTION -.PP -These procedures provide a general-purpose mechanism for creating -and invoking bindings. -Bindings are organized in terms of \fIbinding tables\fR. -A binding table consists of a collection of bindings plus a history -of recent events. -Within a binding table, bindings are associated with \fIobjects\fR. -The meaning of an object is defined by clients of the binding package. -For example, Tk keeps uses one binding table to hold all of the bindings -created by the \fBbind\fR command. -For this table, objects are pointers to strings such as window names, class -names, or other binding tags such as \fBall\fR. -Tk also keeps a separate binding table for each canvas widget, which manages -bindings created by the canvas's \fBbind\fR widget command; within -this table, an object is either a pointer to the internal structure for a -canvas item or a Tk_Uid identifying a tag. -.PP -The procedure \fBTk_CreateBindingTable\fR creates a new binding -table and associates \fIinterp\fR with it (when bindings in the -table are invoked, the scripts will be evaluated in \fIinterp\fR). -\fBTk_CreateBindingTable\fR returns a token for the table, which -must be used in calls to other procedures such as \fBTk_CreateBinding\fR -or \fBTk_BindEvent\fR. -.PP -\fBTk_DeleteBindingTable\fR frees all of the state associated -with a binding table. -Once it returns the caller should not use the \fIbindingTable\fR -token again. -.PP -\fBTk_CreateBinding\fR adds a new binding to an existing table. -The \fIobject\fR argument identifies the object with which the -binding is to be associated, and it may be any one-word value. -Typically it is a pointer to a string or data structure. -The \fIeventString\fR argument identifies the event or sequence -of events for the binding; see the documentation for the -\fBbind\fR command for a description of its format. -\fIscript\fR is the Tcl script to be evaluated when the binding -triggers. -\fIappend\fR indicates what to do if there already -exists a binding for \fIobject\fR and \fIeventString\fR: if \fIappend\fR -is zero then \fIscript\fR replaces the old script; if \fIappend\fR -is non-zero then the new script is appended to the old one. -\fBTk_CreateBinding\fR returns an X event mask for all the events -associated with the bindings. -This information may be useful to invoke \fBXSelectInput\fR to -select relevant events, or to disallow the use of certain events -in bindings. -If an error occurred while creating the binding (e.g., \fIeventString\fR -refers to a non-existent event), then 0 is returned and an error -message is left as the result of interpreter \fIinterp\fR. -.PP -\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the -binding given by \fIobject\fR and \fIeventString\fR, if -such a binding exists. -\fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR. -In some cases it may reset the interpreter result to the default -empty value. -.PP -\fBTk_GetBinding\fR returns a pointer to the script associated -with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR. -If no such binding exists then NULL is returned and an error -message is left as the result of interpreter \fIinterp\fR. -.PP -\fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list -of all the event strings for which there are bindings in -\fIbindingTable\fR associated with \fIobject\fR. -If there are no bindings for \fIobject\fR, the result will be an empty -string. -.PP -\fBTk_DeleteAllBindings\fR deletes all of the bindings in -\fIbindingTable\fR that are associated with \fIobject\fR. -.PP -\fBTk_BindEvent\fR is called to process an event. -It makes a copy of the event in an internal history list associated -with the binding table, then it checks for bindings that match -the event. -\fBTk_BindEvent\fR processes each of the objects pointed to -by \fIobjectPtr\fR in turn. -For each object, it finds all the bindings that match the current -event history, selects the most specific binding using the priority -mechanism described in the documentation for \fBbind\fR, -and invokes the script for that binding. -If there are no matching bindings for a particular object, then -the object is skipped. -\fBTk_BindEvent\fR continues through all of the objects, handling -exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as -described in the documentation for \fBbind\fR. -.SH KEYWORDS -binding, event, object, script diff --git a/tk8.6/doc/CanvPsY.3 b/tk8.6/doc/CanvPsY.3 deleted file mode 100644 index 5e104ce..0000000 --- a/tk8.6/doc/CanvPsY.3 +++ /dev/null @@ -1,121 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -double -\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR) -.sp -int -\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR) -.sp -int -\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR) -.sp -int -\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR) -.sp -\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) -.sp -int -\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) -.SH ARGUMENTS -.AS "unsigned int" "numPoints" -.AP Tk_Canvas canvas in -A token that identifies a canvas widget for which Postscript is -being generated. -.AP double canvasY in -Y-coordinate in the space of the canvas. -.AP Tcl_Interp *interp in/out -A Tcl interpreter; Postscript is appended to its result, or the -result may be replaced with an error message. -.AP Pixmap bitmap in -Bitmap to use for generating Postscript. -.AP int x in -X-coordinate within \fIbitmap\fR of left edge of region to output. -.AP int y in -Y-coordinate within \fIbitmap\fR of top edge of region to output. -.AP "int" width in -Width of region of bitmap to output, in pixels. -.AP "int" height in -Height of region of bitmap to output, in pixels. -.AP XColor *colorPtr in -Information about color value to set in Postscript. -.AP Tk_Font tkFont in -Font for which Postscript is to be generated. -.AP double *coordPtr in -Pointer to an array of coordinates for one or more -points specified in canvas coordinates. -The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3, -and so on. -.AP int numPoints in -Number of points at \fIcoordPtr\fR. -.BE -.SH DESCRIPTION -.PP -These procedures are called by canvas type managers to carry out -common functions related to generating Postscript. -Most of the procedures take a \fIcanvas\fR argument, which -refers to a canvas widget for which Postscript is being -generated. -.PP -\fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of -a canvas and returns the value that should be used for that point -in the Postscript currently being generated for \fIcanvas\fR. -Y coordinates require transformation because Postscript uses an -origin at the lower-left corner whereas X uses an origin at the -upper-left corner. -Canvas x coordinates can be used directly in Postscript without -transformation. -.PP -\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region -of a bitmap. -The Postscript is generated in proper image data format for Postscript, -i.e., as data between angle brackets, one bit per pixel. -The Postscript is appended to the result of interpreter \fIinterp\fR -and \fBTCL_OK\fR is returned unless an error occurs, in which case -\fBTCL_ERROR\fR is returned and the interpreter result is overwritten -with an error message. -.PP -\fBTk_CanvasPsColor\fR generates Postscript to set the current color -to correspond to its \fIcolorPtr\fR argument, taking into account any -color map specified in the \fBpostscript\fR command. -It appends the Postscript to the interpreter \fIinterp\fR's result and returns -\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is -returned and the interpreter's result is overwritten with an error message. -.PP -\fBTk_CanvasPsFont\fR generates Postscript that sets the current font -to match \fItkFont\fR as closely as possible. -\fBTk_CanvasPsFont\fR takes into account any font map specified -in the \fBpostscript\fR command, and it does -the best it can at mapping X fonts to Postscript fonts. -It appends the Postscript to interpreter \fIinterp\fR's result and -returns \fBTCL_OK\fR unless an error occurs, in which case -\fBTCL_ERROR\fR is returned and the interpreter's result is -overwritten with an error message. -.PP -\fBTk_CanvasPsPath\fR generates Postscript to set the current path -to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR. -It appends the resulting Postscript to the result of interpreter \fIinterp\fR. -.PP -\fBTk_CanvasPsStipple\fR generates Postscript that will fill the -current path in stippled fashion. -It uses \fIbitmap\fR as the stipple pattern and the current Postscript -color; ones in the stipple bitmap are drawn in the current color, and -zeroes are not drawn at all. -The Postscript is appended to interpreter \fIinterp\fR's result and -\fBTCL_OK\fR is returned, unless an error occurs, in which case -\fBTCL_ERROR\fR is returned and the interpreter's result is -overwritten with an error message. -.SH KEYWORDS -bitmap, canvas, color, font, path, Postscript, stipple diff --git a/tk8.6/doc/CanvTkwin.3 b/tk8.6/doc/CanvTkwin.3 deleted file mode 100644 index d53c5b1..0000000 --- a/tk8.6/doc/CanvTkwin.3 +++ /dev/null @@ -1,158 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_CanvasTkwin\fR(\fIcanvas\fR) -.sp -int -\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR) -.sp -\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR) -.sp -\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR) -.sp -\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) -.sp -\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) -.sp -Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; -.sp -Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; -.SH ARGUMENTS -.AS Tk_ItemType *drawableXPtr -.AP Tk_Canvas canvas in -A token that identifies a canvas widget. -.AP Tcl_Interp *interp in/out -Interpreter to use for error reporting. -.AP "const char" *string in -Textual description of a canvas coordinate. -.AP double *doublePtr out -Points to place to store a converted coordinate. -.AP double x in -An x coordinate in the space of the canvas. -.AP double y in -A y coordinate in the space of the canvas. -.AP short *drawableXPtr out -Pointer to a location in which to store an x coordinate in the space -of the drawable currently being used to redisplay the canvas. -.AP short *drawableYPtr out -Pointer to a location in which to store a y coordinate in the space -of the drawable currently being used to redisplay the canvas. -.AP GC gc out -Graphics context to modify. -.AP short *screenXPtr out -Points to a location in which to store the screen coordinate in the -canvas window that corresponds to \fIx\fR. -.AP short *screenYPtr out -Points to a location in which to store the screen coordinate in the -canvas window that corresponds to \fIy\fR. -.AP int x1 in -Left edge of the region that needs redisplay. Only pixels at or to -the right of this coordinate need to be redisplayed. -.AP int y1 in -Top edge of the region that needs redisplay. Only pixels at or below -this coordinate need to be redisplayed. -.AP int x2 in -Right edge of the region that needs redisplay. Only pixels to -the left of this coordinate need to be redisplayed. -.AP int y2 in -Bottom edge of the region that needs redisplay. Only pixels above -this coordinate need to be redisplayed. -.BE -.SH DESCRIPTION -.PP -These procedures are called by canvas type managers to perform various -utility functions. -.PP -\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular -canvas. -.PP -\fBTk_CanvasGetCoord\fR translates a string specification of a -coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision -canvas coordinate. -If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR -stores the corresponding canvas coordinate at *\fIdoublePtr\fR -and returns \fBTCL_OK\fR. -Otherwise it stores an error message in the interpreter result and -returns \fBTCL_ERROR\fR. -.PP -\fBTk_CanvasDrawableCoords\fR is called by type managers during -redisplay to compute where to draw things. -Given \fIx\fR and \fIy\fR coordinates in the space of the -canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding -pixel in the drawable that is currently being used for redisplay; -it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR. -This procedure should not be invoked except during redisplay. -.PP -\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay. -It sets the stipple origin in \fIgc\fR so that stipples drawn -with \fIgc\fR in the current offscreen pixmap will line up -with stipples drawn with origin (0,0) in the canvas's actual -window. -\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee -that stipple patterns line up properly when the canvas is -redisplayed in small pieces. -Redisplays are carried out in double-buffered fashion where a -piece of the canvas is redrawn in an offscreen pixmap and then -copied back onto the screen. -In this approach the stipple origins in graphics contexts need to -be adjusted during each redisplay to compensate for the position -of the off-screen pixmap relative to the window. -If an item is being drawn with stipples, its type manager typically -calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR -to draw something; after it is finished drawing, the type manager -calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0) -(the restore is needed because graphics contexts are shared, so -they cannot be modified permanently). -.PP -\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR -except that it returns coordinates in the canvas's window on the -screen, instead of coordinates in an off-screen pixmap. -.PP -\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager -to inform Tk that a portion of a canvas needs to be redrawn. -The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments -specify the region that needs to be redrawn, in canvas coordinates. -Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR, -since Tk can normally figure out when an item has changed and make -the redisplay request on its behalf (this happens, for example -whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR). -The only time that a type manager needs to call -\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own -without being invoked through one of the procedures in its Tk_ItemType; -this could happen, for example, in an image item if the image is -modified using image commands. -.PP -\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are -procedures that handle the \fB\-tags\fR option for canvas items. -The code of a canvas type manager will not call these procedures -directly, but will use their addresses to create a \fBTk_CustomOption\fR -structure for the \fB\-tags\fR option. The code typically looks -like this: -.PP -.CS -static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, - Tk_CanvasTagsPrintProc, (ClientData) NULL -}; - -static const Tk_ConfigSpec configSpecs[] = { - ... - {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL, - NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, - ... -}; -.CE -.SH KEYWORDS -canvas, focus, item type, redisplay, selection, type manager diff --git a/tk8.6/doc/CanvTxtInfo.3 b/tk8.6/doc/CanvTxtInfo.3 deleted file mode 100644 index 92a2bc3..0000000 --- a/tk8.6/doc/CanvTxtInfo.3 +++ /dev/null @@ -1,100 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CanvasTextInfo \- additional information for managing text items in canvases -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_CanvasTextInfo * -\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) -.SH ARGUMENTS -.AS Tk_Canvas canvas -.AP Tk_Canvas canvas in -A token that identifies a particular canvas widget. -.BE -.SH DESCRIPTION -.PP -Textual canvas items are somewhat more complicated to manage than -other items, due to things like the selection and the input focus. -\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager -to obtain additional information needed for items that display text. -The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to -a structure that is shared between Tk and all the items that display -text. -The structure has the following form: -.CS -typedef struct Tk_CanvasTextInfo { - Tk_3DBorder \fIselBorder\fR; - int \fIselBorderWidth\fR; - XColor *\fIselFgColorPtr\fR; - Tk_Item *\fIselItemPtr\fR; - int \fIselectFirst\fR; - int \fIselectLast\fR; - Tk_Item *\fIanchorItemPtr\fR; - int \fIselectAnchor\fR; - Tk_3DBorder \fIinsertBorder\fR; - int \fIinsertWidth\fR; - int \fIinsertBorderWidth\fR; - Tk_Item *\fIfocusItemPtr\fR; - int \fIgotFocus\fR; - int \fIcursorOn\fR; -} \fBTk_CanvasTextInfo\fR; -.CE -The \fBselBorder\fR field identifies a Tk_3DBorder that should be -used for drawing the background under selected text. -\fIselBorderWidth\fR gives the width of the raised border around -selected text, in pixels. -\fIselFgColorPtr\fR points to an XColor that describes the foreground -color to be used when drawing selected text. -\fIselItemPtr\fR points to the item that is currently selected, or -NULL if there is no item selected or if the canvas does not have the -selection. -\fIselectFirst\fR and \fIselectLast\fR give the indices of the first -and last selected characters in \fIselItemPtr\fR, as returned by the -\fIindexProc\fR for that item. -\fIanchorItemPtr\fR points to the item that currently has the selection -anchor; this is not necessarily the same as \fIselItemPtr\fR. -\fIselectAnchor\fR is an index that identifies the anchor position -within \fIanchorItemPtr\fR. -\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the -insertion cursor; \fIinsertWidth\fR gives the total width of the -insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the -width of the raised border around the insertion cursor. -\fIfocusItemPtr\fR identifies the item that currently has the input -focus, or NULL if there is no such item. -\fIgotFocus\fR is 1 if the canvas widget has the input focus and -0 otherwise. -\fIcursorOn\fR is 1 if the insertion cursor should be drawn in -\fIfocusItemPtr\fR and 0 if it should not be drawn; this field -is toggled on and off by Tk to make the cursor blink. -.PP -The structure returned by \fBTk_CanvasGetTextInfo\fR -is shared between Tk and the type managers; typically the type manager -calls \fBTk_CanvasGetTextInfo\fR once when an item is created and -then saves the pointer in the item's record. -Tk will update information in the Tk_CanvasTextInfo; for example, -a \fBconfigure\fR widget command might change the \fIselBorder\fR -field, or a \fBselect\fR widget command might change the \fIselectFirst\fR -field, or Tk might change \fIcursorOn\fR in order to make the insertion -cursor flash on and off during successive redisplays. -.PP -Type managers should treat all of the fields of the Tk_CanvasTextInfo -structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR, -\fIselectLast\fR, and \fIselectAnchor\fR. -Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and -\fIselectAnchor\fR to adjust for insertions and deletions in the -item (but only if the item is the current owner of the selection or -anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR). -If all of the selected text in the item is deleted, the item should -set \fIselItemPtr\fR to NULL to indicate that there is no longer a -selection. -.SH KEYWORDS -canvas, focus, insertion cursor, selection, selection anchor, text diff --git a/tk8.6/doc/Clipboard.3 b/tk8.6/doc/Clipboard.3 deleted file mode 100644 index 3087777..0000000 --- a/tk8.6/doc/Clipboard.3 +++ /dev/null @@ -1,77 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) -.sp -int -\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) -.SH ARGUMENTS -.AS Tk_ClipboardClear tkwin -.AP Tcl_Interp *interp in -Interpreter to use for reporting errors. -.AP Tk_Window tkwin in -Window that determines which display's clipboard to manipulate. -.AP Atom target in -Conversion type for this clipboard item; has same meaning as -\fItarget\fR argument to \fBTk_CreateSelHandler\fR. -.AP Atom format in -Representation to use when data is retrieved; has same meaning as -\fIformat\fR argument to \fBTk_CreateSelHandler\fR. -.AP "const char" *buffer in -Null terminated string containing the data to be appended to the clipboard. -.BE -.SH DESCRIPTION -.PP -These two procedures manage the clipboard for Tk. -The clipboard is typically managed by calling \fBTk_ClipboardClear\fR -once, then calling \fBTk_ClipboardAppend\fR to add data for any -number of targets. -.PP -\fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any -data items previously stored on the clipboard in this application. -It normally returns \fBTCL_OK\fR, but if an error occurs it returns -\fBTCL_ERROR\fR and leaves an error message in interpreter -\fIinterp\fR's result. -\fBTk_ClipboardClear\fR must be called before a sequence of -\fBTk_ClipboardAppend\fR calls can be issued. -.PP -\fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard. -The first buffer for a given \fItarget\fR determines the \fIformat\fR -for that \fItarget\fR. -Any successive appends for that \fItarget\fR must have -the same format or an error will be returned. -\fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is -successfully copied onto the clipboard. If the clipboard is not -currently owned by the application, either -because \fBTk_ClipboardClear\fR has not been called or because -ownership of the clipboard has changed since the last call to -\fBTk_ClipboardClear\fR, -\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error -message in the result of interpreter \fIinterp\fR. -.PP -In order to guarantee atomicity, no event handling should occur -between \fBTk_ClipboardClear\fR and the following -\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve -a partially completed clipboard or claim ownership away from -this application). -.PP -\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary -Tcl scripts, as a result of losing the CLIPBOARD selection, so -any calling function should take care to be re-entrant at the point -\fBTk_ClipboardClear\fR is invoked. -.SH KEYWORDS -append, clipboard, clear, format, type diff --git a/tk8.6/doc/ClrSelect.3 b/tk8.6/doc/ClrSelect.3 deleted file mode 100644 index c56f63c..0000000 --- a/tk8.6/doc/ClrSelect.3 +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" Copyright (c) 1992-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ClearSelection \- Deselect a selection -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_ClearSelection\fR(\fItkwin, selection\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -The selection will be cleared from the display containing this -window. -.AP Atom selection in -The name of selection to be cleared. -.BE -.SH DESCRIPTION -.PP -\fBTk_ClearSelection\fR cancels the selection specified by the atom -\fIselection\fR for the display containing \fItkwin\fR. -The selection need not be in \fItkwin\fR itself or even in -\fItkwin\fR's application. -If there is a window anywhere on \fItkwin\fR's display that -owns \fIselection\fR, the window will be notified and the -selection will be cleared. -If there is no owner for \fIselection\fR on the display, then the -procedure has no effect. -.SH KEYWORDS -clear, selection diff --git a/tk8.6/doc/ConfigWidg.3 b/tk8.6/doc/ConfigWidg.3 deleted file mode 100644 index 92be073..0000000 --- a/tk8.6/doc/ConfigWidg.3 +++ /dev/null @@ -1,631 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR -.sp -int -\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR -.sp -int -\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR -.sp -\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR -.SH ARGUMENTS -.AS char *widgRec in/out -.AP Tcl_Interp *interp in -Interpreter to use for returning error messages. -.AP Tk_Window tkwin in -Window used to represent widget (needed to set up X resources). -.AP "const Tk_ConfigSpec" *specs in -Pointer to table specifying legal configuration options for this -widget. -.AP int argc in -Number of arguments in \fIargv\fR. -.AP "const char" **argv in -Command-line options for configuring widget. -.AP char *widgRec in/out -Points to widget record structure. Fields in this structure get -modified by \fBTk_ConfigureWidget\fR to hold configuration information. -.AP int flags in -If non-zero, then it specifies an OR-ed combination of flags that -control the processing of configuration information. -\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be -ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to -selectively disable entries in \fIspecs\fR. -.AP "type name" type in -The name of the type of a widget record. -.AP "field name" field in -The name of a field in records of type \fItype\fR. -.AP "const char" *argvName in -The name used on Tcl command lines to refer to a particular option -(e.g. when creating a widget or invoking the \fBconfigure\fR widget -command). If non-NULL, then information is returned only for this -option. If NULL, then information is returned for all available -options. -.AP Display *display in -Display containing widget whose record is being freed; needed in -order to free up resources. -.BE -.SH DESCRIPTION -.PP -Note: \fBTk_ConfigureWidget\fR should be replaced with the new -\fBTcl_Obj\fR based API \fBTk_SetOptions\fR. The old interface is -retained for backward compatibility. -.PP -\fBTk_ConfigureWidget\fR is called to configure various aspects of a -widget, such as colors, fonts, border width, etc. -It is intended as a convenience procedure to reduce the amount -of code that must be written in individual widget managers to -handle configuration information. -It is typically -invoked when widgets are created, and again when the \fBconfigure\fR -command is invoked for a widget. -Although intended primarily for widgets, \fBTk_ConfigureWidget\fR -can be used in other situations where \fIargc-argv\fR information -is to be used to fill in a record structure, such as configuring -graphical elements for a canvas widget or entries of a menu. -.PP -\fBTk_ConfigureWidget\fR processes -a table specifying the configuration options that are supported -(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and -\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR). -It uses the option database and defaults specified in \fIspecs\fR -to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. -\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this -case it does not modify \fIinterp\fR. -If an error -occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will -leave an error message in interpreter \fIinterp\fR's result in the standard Tcl -fashion. -In the event of an error return, some of the fields of \fIwidgRec\fR -could already have been set, if configuration information for them -was successfully processed before the error occurred. -The other fields will be set to reasonable initial values so that -\fBTk_FreeOptions\fR can be called for cleanup. -.PP -The \fIspecs\fR array specifies the kinds of configuration options -expected by the widget. Each of its entries specifies one configuration -option and has the following structure: -.CS -typedef struct { - int \fItype\fR; - const char *\fIargvName\fR; - const char *\fIdbName\fR; - const char *\fIdbClass\fR; - const char *\fIdefValue\fR; - int \fIoffset\fR; - int \fIspecFlags\fR; - const Tk_CustomOption *\fIcustomPtr\fR; -} \fBTk_ConfigSpec\fR; -.CE -The \fItype\fR field indicates what type of configuration option this is -(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for -an integer value). The \fItype\fR field indicates how to use the -value of the option (more on this below). -The \fIargvName\fR field is a string such as -.QW \-font -or -.QW \-bg , -which is compared with the values in \fIargv\fR (if \fIargvName\fR is -NULL it means this is a grouped entry; see \fBGROUPED ENTRIES\fR below). The -\fIdbName\fR and \fIdbClass\fR fields are used to look up a value -for this option in the option database. The \fIdefValue\fR field -specifies a default value for this configuration option if no -value is specified in either \fIargv\fR or the option database. -\fIOffset\fR indicates where in \fIwidgRec\fR to store information -about this option, and \fIspecFlags\fR contains additional information -to control the processing of this configuration option (see FLAGS -below). -The last field, \fIcustomPtr\fR, is only used if \fItype\fR is -\fBTK_CONFIG_CUSTOM\fR; see CUSTOM OPTION TYPES below. -.PP -\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which -(if any) configuration options are specified there. \fIArgv\fR -must contain an even number of fields; the first of each pair -of fields must match the \fIargvName\fR of some entry in \fIspecs\fR -(unique abbreviations are acceptable), -and the second field of the pair contains the value for that -configuration option. If there are entries in \fIspec\fR for which -there were no matching entries in \fIargv\fR, -\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR -fields of the \fIspecs\fR entry to probe the option database; if -a value is found, then it is used as the value for the option. -Finally, if no entry is found in the option database, the -\fIdefValue\fR field of the \fIspecs\fR entry is used as the -value for the configuration option. If the \fIdefValue\fR is -NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in -\fIflags\fR, then there is no default value and this \fIspecs\fR entry -will be ignored if no value is specified in \fIargv\fR or the -option database. -.PP -Once a string value has been determined for a configuration option, -\fBTk_ConfigureWidget\fR translates the string value into a more useful -form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer -if \fItype\fR is \fBTK_CONFIG_INT\fR. This value is then stored in the -record pointed to by \fIwidgRec\fR. This record is assumed to -contain information relevant to the manager of the widget; its exact -type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field -of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store -the information about this configuration option. You should use the -\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for -a description of \fBTk_Offset\fR). The location indicated by -\fIwidgRec\fR and \fIoffset\fR will be referred to as the -.QW target -in the descriptions below. -.PP -The \fItype\fR field of each entry in \fIspecs\fR determines what -to do with the string value of that configuration option. The -legal values for \fItype\fR, and the corresponding actions, are: -.TP -\fBTK_CONFIG_ACTIVE_CURSOR\fR -The value -must be an ASCII string identifying a cursor in a form -suitable for passing to \fBTk_GetCursor\fR. -The value is converted to a \fBTk_Cursor\fR by calling -\fBTk_GetCursor\fR and the result is stored in the target. -In addition, the resulting cursor is made the active cursor -for \fItkwin\fR by calling \fBXDefineCursor\fR. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target and \fItkwin\fR's -active cursor will be set to \fBNone\fR. -If the previous value of the target -was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. -.TP -\fBTK_CONFIG_ANCHOR\fR -The value must be an ASCII string identifying an anchor point in one of the ways -accepted by \fBTk_GetAnchor\fR. -The string is converted to a \fBTk_Anchor\fR by calling -\fBTk_GetAnchor\fR and the result is stored in the target. -.TP -\fBTK_CONFIG_BITMAP\fR -The value must be an ASCII string identifying a bitmap in a form -suitable for passing to \fBTk_GetBitmap\fR. The value is converted -to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result -is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target is set to \fBNone\fR. -If the previous value of the target -was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. -.TP -\fBTK_CONFIG_BOOLEAN\fR -The value must be an ASCII string specifying a boolean value. Any -of the values -.QW true , -.QW yes , -.QW on , -or -.QW 1 , -or an abbreviation of one of these values, means true; -any of the values -.QW false , -.QW no , -.QW off , -or -.QW 0 , -or an abbreviation of one of these values, means false. -The target is expected to be an integer; for true values it will -be set to 1 and for false values it will be set to 0. -.TP -\fBTK_CONFIG_BORDER\fR -The value must be an ASCII string identifying a border color in a form -suitable for passing to \fBTk_Get3DBorder\fR. The value is converted -to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result -is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target will be set to NULL. -If the previous value of the target -was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. -.TP -\fBTK_CONFIG_CAP_STYLE\fR -The value must be -an ASCII string identifying a cap style in one of the ways -accepted by \fBTk_GetCapStyle\fR. -The string is converted to an integer value corresponding -to the cap style by calling -\fBTk_GetCapStyle\fR and the result is stored in the target. -.TP -\fBTK_CONFIG_COLOR\fR -The value must be an ASCII string identifying a color in a form -suitable for passing to \fBTk_GetColor\fR. The value is converted -to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result -is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target will be set to \fBNone\fR. -If the previous value of the target -was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR. -.TP -\fBTK_CONFIG_CURSOR\fR -This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except -that the new cursor is not made the active one for \fItkwin\fR. -.TP -\fBTK_CONFIG_CUSTOM\fR -This option allows applications to define new option types. -The \fIcustomPtr\fR field of the entry points to a structure -defining the new option type. -See the section \fBCUSTOM OPTION TYPES\fR below for details. -.TP -\fBTK_CONFIG_DOUBLE\fR -The value must be an ASCII floating-point number in -the format accepted by \fBstrtol\fR. The string is converted -to a \fBdouble\fR value, and the value is stored in the -target. -.TP -\fBTK_CONFIG_END\fR -Marks the end of the table. The last entry in \fIspecs\fR -must have this type; all of its other fields are ignored and it -will never match any arguments. -.TP -\fBTK_CONFIG_FONT\fR -The value must be an ASCII string identifying a font in a form -suitable for passing to \fBTk_GetFont\fR. The value is converted -to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result -is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target will be set to NULL. -If the previous value of the target -was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR. -.TP -\fBTK_CONFIG_INT\fR -The value must be an ASCII integer string -in the format accepted by \fBstrtol\fR (e.g. -.QW 0 -and -.QW 0x -prefixes may be used to specify octal or hexadecimal -numbers, respectively). The string is converted to an integer -value and the integer is stored in the target. -.TP -\fBTK_CONFIG_JOIN_STYLE\fR -The value must be -an ASCII string identifying a join style in one of the ways -accepted by \fBTk_GetJoinStyle\fR. -The string is converted to an integer value corresponding -to the join style by calling -\fBTk_GetJoinStyle\fR and the result is stored in the target. -.TP -\fBTK_CONFIG_JUSTIFY\fR -The value must be -an ASCII string identifying a justification method in one of the -ways accepted by \fBTk_GetJustify\fR. -The string is converted to a \fBTk_Justify\fR by calling -\fBTk_GetJustify\fR and the result is stored in the target. -.TP -\fBTK_CONFIG_MM\fR -The value must specify a screen distance in one of the forms acceptable -to \fBTk_GetScreenMM\fR. -The string is converted to double-precision floating-point distance -in millimeters and the value is stored in the target. -.TP -\fBTK_CONFIG_PIXELS\fR -The value must specify screen units in one of the forms acceptable -to \fBTk_GetPixels\fR. -The string is converted to an integer distance in pixels and the -value is stored in the target. -.TP -\fBTK_CONFIG_RELIEF\fR -The value must be an ASCII string identifying a relief in a form -suitable for passing to \fBTk_GetRelief\fR. The value is converted -to an integer relief value by calling \fBTk_GetRelief\fR and the result -is stored in the target. -.TP -\fBTK_CONFIG_STRING\fR -A copy -of the value is made by allocating memory space with -\fBTcl_Alloc\fR and copying the value into the dynamically-allocated -space. A pointer to the new string is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value -may be an empty string, in which case the target will be set to NULL. -If the previous value of the target was not NULL, then it is -freed by passing it to \fBTcl_Free\fR. -.TP -\fBTK_CONFIG_SYNONYM\fR -This \fItype\fR value identifies special entries in \fIspecs\fR that -are synonyms for other entries. If an \fIargv\fR value matches the -\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used -directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR -for another entry whose \fIargvName\fR is the same as the \fIdbName\fR -field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just -as if its \fIargvName\fR had matched the \fIargv\fR value. The -synonym mechanism allows multiple \fIargv\fR values to be used for -a single configuration option, such as -.QW \-background -and -.QW \-bg . -.TP -\fBTK_CONFIG_UID\fR -The value is translated to a \fBTk_Uid\fR -(by passing it to \fBTk_GetUid\fR). The resulting value -is stored in the target. -If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value -is an empty string then the target will be set to NULL. -.TP -\fBTK_CONFIG_WINDOW\fR -The value must be a window path name. It is translated to a -\fBTk_Window\fR token and the token is stored in the target. -.SH "GROUPED ENTRIES" -.PP -In some cases it is useful to generate multiple resources from -a single configuration value. For example, a color name might -be used both to generate the background color for a widget (using -\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the -widget (using \fBTK_CONFIG_BORDER\fR). In cases like this it is possible -to specify that several consecutive entries in \fIspecs\fR are to -be treated as a group. The first entry is used to determine a value -(using its \fIargvName\fR, \fIdbName\fR, -\fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed -several times (one for each entry in the group), generating multiple -different resources and modifying multiple targets within \fIwidgRec\fR. -Each of the entries after the first must have a NULL value in its -\fIargvName\fR field; this indicates that the entry is to be grouped -with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR -fields are used from these follow-on entries. -.SH "FLAGS" -.PP -The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used -in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR -to provide additional control over the processing of configuration -options. These values are used in three different ways as -described below. -.PP -First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has -the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0), -then the option database and -\fIdefValue\fR fields are not used. In this case, if an entry in -\fIspecs\fR does not match a field in \fIargv\fR then nothing happens: -the corresponding target is not modified. This feature is useful -when the goal is to modify certain configuration options while -leaving others in their current state, such as when a \fBconfigure\fR -widget command is being processed. -.PP -Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used -to control the processing of that entry. Each \fIspecFlags\fR -field may consists of an OR-ed combination of the following values: -.TP -\fBTK_CONFIG_COLOR_ONLY\fR -If this bit is set then the entry will only be considered if the -display for \fItkwin\fR has more than one bit plane. If the display -is monochromatic then this \fIspecs\fR entry will be ignored. -.TP -\fBTK_CONFIG_MONO_ONLY\fR -If this bit is set then the entry will only be considered if the -display for \fItkwin\fR has exactly one bit plane. If the display -is not monochromatic then this \fIspecs\fR entry will be ignored. -.TP -\fBTK_CONFIG_NULL_OK\fR -This bit is only relevant for some types of entries (see the -descriptions of the various entry types above). -If this bit is set, it indicates that an empty string value -for the field is acceptable and if it occurs then the -target should be set to NULL or \fBNone\fR, depending -on the type of the target. -This flag is typically used to allow a -feature to be turned off entirely, e.g. set a cursor value to -\fBNone\fR so that a window simply inherits its parent's cursor. -If this bit is not set then empty strings are processed as strings, -which generally results in an error. -.TP -\fBTK_CONFIG_DONT_SET_DEFAULT\fR -If this bit is one, it means that the \fIdefValue\fR field of the -entry should only be used for returning the default value in -\fBTk_ConfigureInfo\fR. -In calls to \fBTk_ConfigureWidget\fR no default will be supplied -for entries with this flag set; it is assumed that the -caller has already supplied a default value in the target location. -This flag provides a performance optimization where it is expensive -to process the default string: the client can compute the default -once, save the value, and provide it before calling -\fBTk_ConfigureWidget\fR. -.TP -\fBTK_CONFIG_OPTION_SPECIFIED\fR -This bit is -deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR -so that callers could detect what entries were specified in -\fIargv\fR, but it was removed because it was inherently -thread-unsafe. Code that wishes to detect what options were specified -should use \fBTk_SetOptions\fR instead. -.PP -The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically -used to specify different default values for -monochrome and color displays. This is done by creating two -entries in \fIspecs\fR that are identical except for their -\fIdefValue\fR and \fIspecFlags\fR fields. One entry should have -the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the -default value for monochrome displays in its \fIdefValue\fR; the -other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in -its \fIspecFlags\fR and the appropriate \fIdefValue\fR for -color displays. -.PP -Third, it is possible to use \fIflags\fR and \fIspecFlags\fR -together to selectively disable some entries. This feature is -not needed very often. It is useful in cases where several -similar kinds of widgets are implemented in one place. It allows -a single \fIspecs\fR table to be created with all the configuration -options for all the widget types. When processing a particular -widget type, only entries relevant to that type will be used. This -effect is achieved by setting the high-order bits (those in positions -equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR -values or in \fIflags\fR. In order for a particular entry in -\fIspecs\fR to be used, its high-order bits must match exactly -the high-order bits of the \fIflags\fR value passed to -\fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used -for N different widget types, then N of the high-order bits will -be used. Each \fIspecs\fR entry will have one of more of those -bits set in its \fIspecFlags\fR field to indicate the widget types -for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, -\fIflags\fR will have a single one of these bits set to select the -entries for the desired widget type. For a working example of -this feature, see the code in tkButton.c. -.SH TK_OFFSET -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating -the \fIoffset\fR values for entries in Tk_ConfigSpec structures. -It takes two arguments: the name of a type of record, and the -name of a field in that record. It returns the byte offset of -the named field in records of the given type. -.SH TK_CONFIGUREINFO -.PP -The \fBTk_ConfigureInfo\fR procedure may be used to obtain -information about one or all of the options for a given widget. -Given a token for a window (\fItkwin\fR), a table describing the -configuration options for a class of widgets (\fIspecs\fR), a -pointer to a widget record containing the current information for -a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, -\fBTk_ConfigureInfo\fR generates a string describing all of the -configuration options for the window. The string is placed -in interpreter \fIinterp\fR's result. Under normal circumstances -it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR -and the interpreter's result will contain an error message. -.PP -If \fIargvName\fR is NULL, then the value left in -the interpreter's result by \fBTk_ConfigureInfo\fR -consists of a list of one or more entries, each of which describes -one configuration option (i.e. one entry in \fIspecs\fR). Each -entry in the list will contain either two or five values. If the -corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then -the list will contain two values: the \fIargvName\fR for the entry -and the \fIdbName\fR (synonym name). Otherwise the list will contain -five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, -and current value. The current value is computed from the appropriate -field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. -.PP -If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, -then it indicates a single option, and information is returned only -for that option. The string placed in the interpreter's result will be -a list containing two or five values as described above; this will -be identical to the corresponding sublist that would have been returned -if \fIargvName\fR had been NULL. -.PP -The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict -the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. -.SH TK_CONFIGUREVALUE -.PP -\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; -instead of returning a list of values, it just returns the current value -of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). -The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is -normally returned as the procedure's result. -If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is -not a valid option name), \fBTCL_ERROR\fR is returned and an error message -is left in the interpreter's result. -This procedure is typically called to implement \fBcget\fR widget -commands. -.SH TK_FREEOPTIONS -.PP -The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup -to release all of the resources associated with configuration options. -It scans through \fIspecs\fR and for each entry corresponding to a -resource that must be explicitly freed (e.g. those with -type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record. -If the field in the widget record does not refer to a resource (e.g. -it contains a null pointer) then no resource is freed for that -entry. -After freeing a resource, \fBTk_FreeOptions\fR sets the -corresponding field of the widget record to null. -.SH "CUSTOM OPTION TYPES" -.PP -Applications can extend the built-in configuration types with additional -configuration types by writing procedures to parse and print options -of the a type and creating a structure pointing to those procedures: -.CS -typedef struct Tk_CustomOption { - Tk_OptionParseProc *\fIparseProc\fR; - Tk_OptionPrintProc *\fIprintProc\fR; - ClientData \fIclientData\fR; -} \fBTk_CustomOption\fR; - -typedef int \fBTk_OptionParseProc\fR( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tk_Window \fItkwin\fR, - char *\fIvalue\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR); - -typedef const char *\fBTk_OptionPrintProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR, - Tcl_FreeProc **\fIfreeProcPtr\fR); -.CE -The Tk_CustomOption structure contains three fields, which are pointers -to the two procedures and a \fIclientData\fR value to be passed to those -procedures when they are invoked. The \fIclientData\fR value typically -points to a structure containing information that is needed by the -procedures when they are parsing and printing options. -.PP -The \fIparseProc\fR procedure is invoked by -\fBTk_ConfigureWidget\fR to parse a string and store the resulting -value in the widget record. -The \fIclientData\fR argument is a copy of the \fIclientData\fR -field in the Tk_CustomOption structure. -The \fIinterp\fR argument points to a Tcl interpreter used for -error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument -to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string -describing the value for the option; it could have been specified -explicitly in the call to \fBTk_ConfigureWidget\fR or it could -come from the option database or a default. -\fIValue\fR will never be a null pointer but it may point to -an empty string. -\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to -\fBTk_ConfigureWidget\fR; it points to the start of the widget -record to modify. -The last argument, \fIoffset\fR, gives the offset in bytes from the start -of the widget record to the location where the option value is to -be placed. The procedure should translate the string to whatever -form is appropriate for the option and store the value in the widget -record. It should normally return \fBTCL_OK\fR, but if an error occurs -in translating the string to a value then it should return \fBTCL_ERROR\fR -and store an error message in interpreter \fIinterp\fR's result. -.PP -The \fIprintProc\fR procedure is called -by \fBTk_ConfigureInfo\fR to produce a string value describing an -existing option. -Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR -arguments all have the same meaning as for Tk_OptionParseProc -procedures. -The \fIprintProc\fR procedure should examine the option whose value -is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing -that option, and return a pointer to the string. -If the string is stored in dynamically-allocated memory, then -the procedure must set \fI*freeProcPtr\fR to the address of -a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR -will call this procedure when it is finished with the string. -If the result string is stored in static memory then \fIprintProc\fR -need not do anything with the \fIfreeProcPtr\fR argument. -.PP -Once \fIparseProc\fR and \fIprintProc\fR have been defined and a -Tk_CustomOption structure has been created for them, options of this -new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR -fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point -to the Tk_CustomOption structure. -.SH EXAMPLES -.PP -Although the explanation of \fBTk_ConfigureWidget\fR is fairly -complicated, its actual use is pretty straightforward. -The easiest way to get started is to copy the code -from an existing widget. -The library implementation of frames -(tkFrame.c) has a simple configuration table, and the library -implementation of buttons (tkButton.c) has a much more complex -table that uses many of the fancy \fIspecFlags\fR mechanisms. -.SH "SEE ALSO" -Tk_SetOptions(3) -.SH KEYWORDS -anchor, bitmap, boolean, border, cap style, color, configuration options, -cursor, custom, double, font, integer, join style, justify, millimeters, -pixels, relief, synonym, uid diff --git a/tk8.6/doc/ConfigWind.3 b/tk8.6/doc/ConfigWind.3 deleted file mode 100644 index 7c7adab..0000000 --- a/tk8.6/doc/ConfigWind.3 +++ /dev/null @@ -1,147 +0,0 @@ -'\" -'\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR) -.sp -\fBTk_MoveWindow\fR(\fItkwin, x, y\fR) -.sp -\fBTk_ResizeWindow\fR(\fItkwin, width, height\fR) -.sp -\fBTk_MoveResizeWindow\fR(\fItkwin, x, y, width, height\fR) -.sp -\fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR) -.sp -\fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR) -.sp -\fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR) -.sp -\fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR) -.sp -\fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR) -.sp -\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) -.sp -\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) -.sp -\fBTk_DefineCursor\fR(\fItkwin, cursor\fR) -.sp -\fBTk_UndefineCursor\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS XSetWindowAttributes borderWidth -.AP Tk_Window tkwin in -Token for window. -.AP "unsigned int" valueMask in -OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, -indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. -.AP XWindowChanges *valuePtr in -Points to a structure containing new values for the configuration -parameters selected by \fIvalueMask\fR. Fields not selected -by \fIvalueMask\fR are ignored. -.AP int x in -New x-coordinate for \fItkwin\fR's top left pixel (including -border, if any) within tkwin's parent. -.AP int y in -New y-coordinate for \fItkwin\fR's top left pixel (including -border, if any) within tkwin's parent. -.AP "int" width in -New width for \fItkwin\fR (interior, not including border). -.AP "int" height in -New height for \fItkwin\fR (interior, not including border). -.AP "int" borderWidth in -New width for \fItkwin\fR's border. -.AP XSetWindowAttributes *attsPtr in -Points to a structure containing new values for the attributes -given by the \fIvalueMask\fR argument. Attributes not selected -by \fIvalueMask\fR are ignored. -.AP "unsigned long" pixel in -New background or border color for window. -.AP Pixmap pixmap in -New pixmap to use for background or border of \fItkwin\fR. WARNING: -cannot necessarily be deleted immediately, as for Xlib calls. See -note below. -.AP Colormap colormap in -New colormap to use for \fItkwin\fR. -.AP Tk_Cursor cursor in -New cursor to use for \fItkwin\fR. If \fBNone\fR is specified, then -\fItkwin\fR will not have its own cursor; it will use the cursor -of its parent. -.BE -.SH DESCRIPTION -.PP -These procedures are analogous to the X library procedures -with similar names, such as \fBXConfigureWindow\fR. Each -one of the above procedures calls the corresponding X procedure -and also saves the configuration information in Tk's local -structure for the window. This allows the information to -be retrieved quickly by the application (using macros such -as \fBTk_X\fR and \fBTk_Height\fR) without having to contact -the X server. In addition, if no X window has actually been -created for \fItkwin\fR yet, these procedures do not issue -X operations or cause event handlers to be invoked; they save -the information in Tk's local -structure for the window; when the window is created later, -the saved information will be used to configure the window. -.PP -See the X library documentation for details on what these -procedures do and how they use their arguments. -.PP -In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR, -\fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and -\fBTk_SetWindowBorderWidth\fR, -if \fItkwin\fR is an internal window then event handlers interested -in configure events are invoked immediately, before the procedure -returns. If \fItkwin\fR is a top-level window -then the event handlers will be invoked later, after X has seen -the request and returned an event for it. -.PP -Applications using Tk should never call procedures like -\fBXConfigureWindow\fR directly; they should always use the -corresponding Tk procedures. -.PP -The size and location of a window should only be modified by the -appropriate geometry manager for that window and never by a window -itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level -window). -.PP -You may not use \fBTk_ConfigureWindow\fR to change the -stacking order of a window (\fIvalueMask\fR may not contain the -\fBCWSibling\fR or \fBCWStackMode\fR bits). -To change the stacking order, use the procedure \fBTk_RestackWindow\fR. -.PP -The procedure \fBTk_SetWindowColormap\fR will automatically add -\fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its -nearest top-level ancestor if the new colormap is different from -that of \fItkwin\fR's parent and \fItkwin\fR is not already in -the \fBTK_COLORMAP_WINDOWS\fR property. -.SH BUGS -.PP -\fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR -differ slightly from their Xlib counterparts in that the \fIpixmap\fR -argument may not necessarily be deleted immediately after calling -one of these procedures. This is because \fItkwin\fR's window -may not exist yet at the time of the call, in which case \fIpixmap\fR -is merely saved and used later when \fItkwin\fR's window is actually -created. If you wish to delete \fIpixmap\fR, then call -\fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists -and \fIpixmap\fR has been passed to the X server. -.PP -A similar problem occurs for the \fIcursor\fR argument passed to -\fBTk_DefineCursor\fR. The solution is the same as for pixmaps above: -call \fBTk_MakeWindowExist\fR before freeing the cursor. -.SH "SEE ALSO" -Tk_MoveToplevelWindow, Tk_RestackWindow -.SH KEYWORDS -attributes, border, color, configure, height, pixel, pixmap, width, window, x, y diff --git a/tk8.6/doc/CoordToWin.3 b/tk8.6/doc/CoordToWin.3 deleted file mode 100644 index 5fe96a6..0000000 --- a/tk8.6/doc/CoordToWin.3 +++ /dev/null @@ -1,47 +0,0 @@ -'\" -'\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CoordsToWindow \- Find window containing a point -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP int rootX in -X-coordinate (in root window coordinates). -.AP int rootY in -Y-coordinate (in root window coordinates). -.AP Tk_Window tkwin in -Token for window that identifies application. -.BE -.SH DESCRIPTION -.PP -\fBTk_CoordsToWindow\fR locates the window that contains a given point. -The point is specified in root coordinates with \fIrootX\fR and -\fIrootY\fR (if a virtual-root window manager is in use then -\fIrootX\fR and \fIrootY\fR are in the coordinate system of the -virtual root window). -The return value from the procedure is a token for the window that -contains the given point. -If the point is not in any window, or if the containing window -is not in the same application as \fItkwin\fR, then NULL is -returned. -.PP -The containing window is decided using the same rules that determine -which window contains the mouse cursor: if a parent and a child both -contain the point then the child gets preference, and if two siblings -both contain the point then the highest one in the stacking order -(i.e. the one that's visible on the screen) gets preference. -.SH KEYWORDS -containing, coordinates, root window diff --git a/tk8.6/doc/CrtCmHdlr.3 b/tk8.6/doc/CrtCmHdlr.3 deleted file mode 100644 index 98b93f7..0000000 --- a/tk8.6/doc/CrtCmHdlr.3 +++ /dev/null @@ -1,64 +0,0 @@ -'\" -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateClientMessageHandler\fR(\fIproc\fR) -.sp -\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR) -.SH ARGUMENTS -.AP Tk_ClientMessageProc *proc in -Procedure to invoke whenever a ClientMessage X event occurs on any display. -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked -in the future whenever a ClientMessage X event occurs that is not handled by -\fBWM_PROTOCOL\fR. \fBTk_CreateClientMessageHandler\fR is intended for use -by applications which need to watch X ClientMessage events, such as drag and -drop applications. -.PP -The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; -this mechanism only works in programs that dispatch events -through \fBTk_HandleEvent\fR (or through other Tk procedures that -call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or -\fBTk_MainLoop\fR). -.PP -\fIProc\fR should have arguments and result that match the -type \fBTk_ClientMessageProc\fR: -.CS -typedef int \fBTk_ClientMessageProc\fR( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is -associated with this event. \fIEventPtr\fR is a pointer to the X event. -.PP -Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR, -the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR. -The return value from \fIproc\fR is normally 0. -A non-zero return value indicates that the event is not to be handled -further; that is, \fIproc\fR has done all processing that is to be -allowed for the event. -.PP -If there are multiple ClientMessage event handlers, each one is called -for each event, in the order in which they were established. -.PP -\fBTk_DeleteClientMessageHandler\fR may be called to delete a -previously-created ClientMessage event handler: it deletes each handler it -finds that matches the \fIproc\fR argument. If no such handler exists, -then \fBTk_DeleteClientMessageHandler\fR returns without doing anything. -Although Tk supports it, it's probably a bad idea to have more than one -callback with the same \fIproc\fR argument. -.SH KEYWORDS -bind, callback, event, handler diff --git a/tk8.6/doc/CrtConsoleChan.3 b/tk8.6/doc/CrtConsoleChan.3 deleted file mode 100644 index 7fd8a6a..0000000 --- a/tk8.6/doc/CrtConsoleChan.3 +++ /dev/null @@ -1,44 +0,0 @@ -'\" -'\" Copyright (c) 2007 ActiveState Software Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_InitConsoleChannels \- Install the console channels as standard channels -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_InitConsoleChannels\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp in -.AP Tcl_Interp *interp in -Interpreter in which the console channels are created. -.BE -.SH DESCRIPTION -.PP -\fBTk_InitConsoleChannels\fR is invoked to create a set of console -channels and install them as the standard channels. All I/O on these -channels will be discarded until \fBTk_CreateConsoleWindow\fR is -called to attach the console to a text widget. -.PP -This function is for use by shell applications based on Tk, like -\fBwish\fR, on platforms which have no standard channels in graphical -mode, like Win32. -.PP -The \fIinterp\fR argument is the interpreter in which to create and -install the console channels. -.PP -\fBNOTE:\fR If this function is used it has to be called before the -first call to \fBTcl_RegisterChannel\fR, directly, or indirectly -through other channel functions. Because otherwise the standard -channels will be already initialized to the system defaults, which will -be nonsensical for the case \fBTk_InitConsoleChannels\fR is for. -.SH "SEE ALSO" -console(n) -.SH KEYWORDS -standard channels, console diff --git a/tk8.6/doc/CrtErrHdlr.3 b/tk8.6/doc/CrtErrHdlr.3 deleted file mode 100644 index e506220..0000000 --- a/tk8.6/doc/CrtErrHdlr.3 +++ /dev/null @@ -1,140 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_ErrorHandler -\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) -.sp -\fBTk_DeleteErrorHandler\fR(\fIhandler\fR) -.SH ARGUMENTS -.AS "Tk_ErrorHandler" clientData -.AP Display *display in -Display whose errors are to be handled. -.AP int error in -Match only error events with this value in the \fIerror_code\fR -field. If \-1, then match any \fIerror_code\fR value. -.AP int request in -Match only error events with this value in the \fIrequest_code\fR -field. If \-1, then match any \fIrequest_code\fR value. -.AP int minor in -Match only error events with this value in the \fIminor_code\fR -field. If \-1, then match any \fIminor_code\fR value. -.AP Tk_ErrorProc *proc in -Procedure to invoke whenever an error event is received for -\fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR. -NULL means ignore any matching errors. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP Tk_ErrorHandler handler in -Token for error handler to delete (return value from a previous -call to \fBTk_CreateErrorHandler\fR). -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateErrorHandler\fR arranges for a particular procedure -(\fIproc\fR) to be called whenever certain protocol errors occur on a -particular display (\fIdisplay\fR). Protocol errors occur when -the X protocol is used incorrectly, such as attempting to map a window -that does not exist. See the Xlib documentation for \fBXSetErrorHandler\fR -for more information on the kinds of errors that can occur. -For \fIproc\fR to be invoked -to handle a particular error, five things must occur: -.IP [1] -The error must pertain to \fIdisplay\fR. -.IP [2] -Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR -must have been \-1, or the \fIerror\fR argument must match -the \fIerror_code\fR field from the error event. -.IP [3] -Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR -must have been \-1, or the \fIrequest\fR argument must match -the \fIrequest_code\fR field from the error event. -.IP [4] -Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR -must have been \-1, or the \fIminor\fR argument must match -the \fIminor_code\fR field from the error event. -.IP [5] -The protocol request to which the error pertains must have been -made when the handler was active (see below for more information). -.PP -\fIProc\fR should have arguments and result that match the -following type: -.CS -typedef int \fBTk_ErrorProc\fR( - ClientData \fIclientData\fR, - XErrorEvent *\fIerrEventPtr\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTcl_CreateErrorHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information that is -needed to deal with the error. \fIErrEventPtr\fR is -a pointer to the X error event. -The procedure \fIproc\fR should return an integer value. If it -returns 0 it means that \fIproc\fR handled the error completely and there -is no need to take any other action for the error. If it returns -non-zero it means \fIproc\fR was unable to handle the error. -.PP -If a value of NULL is specified for \fIproc\fR, all matching errors -will be ignored: this will produce the same result as if a procedure -had been specified that always returns 0. -.PP -If more than more than one handler matches a particular error, then -they are invoked in turn. The handlers will be invoked in reverse -order of creation: most recently declared handler first. -If any handler returns 0, then subsequent (older) handlers will -not be invoked. If no handler returns 0, then Tk invokes X's -default error handler, which prints an error message and aborts the -program. If you wish to have a default handler that deals with errors -that no other handler can deal with, then declare it first. -.PP -The X documentation states that -.QW "the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events." -This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR; -disobey it at your own risk. -.PP -\fBTk_DeleteErrorHandler\fR may be called to delete a -previously-created error handler. The \fIhandler\fR argument -identifies the error handler, and should be a value returned by -a previous call to \fBTk_CreateEventHandler\fR. -.PP -A particular error handler applies to errors resulting -from protocol requests generated between -the call to \fBTk_CreateErrorHandler\fR and the call to -\fBTk_DeleteErrorHandler\fR. However, the actual callback -to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR -call, due to buffering in the client and server. -If an error event pertains to -a protocol request made just before calling \fBTk_DeleteErrorHandler\fR, -then the error event may not have been processed -before the \fBTk_DeleteErrorHandler\fR -call. When this situation arises, Tk will save information about -the handler and -invoke the handler's \fIproc\fR later when the error event -finally arrives. -If an application wishes to delete an error handler and know -for certain that all relevant errors have been processed, -it should first call \fBTk_DeleteErrorHandler\fR and then -call \fBXSync\fR; this will flush out any buffered requests and errors, -but will result in a performance penalty because -it requires communication to and from the X server. After the -\fBXSync\fR call Tk is guaranteed not to call any error -handlers deleted before the \fBXSync\fR call. -.PP -For the Tk error handling mechanism to work properly, it is essential -that application code never calls \fBXSetErrorHandler\fR directly; -applications should use only \fBTk_CreateErrorHandler\fR. -.SH KEYWORDS -callback, error, event, handler diff --git a/tk8.6/doc/CrtGenHdlr.3 b/tk8.6/doc/CrtGenHdlr.3 deleted file mode 100644 index c2161d1..0000000 --- a/tk8.6/doc/CrtGenHdlr.3 +++ /dev/null @@ -1,81 +0,0 @@ -'\" -'\" Copyright (c) 1992-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) -.sp -\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) -.SH ARGUMENTS -.AS "Tk_GenericProc" clientData -.AP Tk_GenericProc *proc in -Procedure to invoke whenever any X event occurs on any display. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be -invoked in the future whenever any X event occurs. This mechanism is -\fInot\fR intended for dispatching X events on windows managed by Tk -(you should use \fBTk_CreateEventHandler\fR for this purpose). -\fBTk_CreateGenericHandler\fR is intended for other purposes, such -as tracing X events, monitoring events on windows not owned by Tk, -accessing X-related libraries that were not originally designed for -use with Tk, and so on. -.PP -The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; -this mechanism only works in programs that dispatch events -through \fBTk_HandleEvent\fR (or through other Tk procedures that -call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or -\fBTk_MainLoop\fR). -.PP -\fIProc\fR should have arguments and result that match the -type \fBTk_GenericProc\fR: -.CS -typedef int \fBTk_GenericProc\fR( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTk_CreateGenericHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -how to handle events. -\fIEventPtr\fR is a pointer to the X event. -.PP -Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR -is called. The return value from \fIproc\fR is normally 0. -A non-zero return value indicates that the event is not to be handled -further; that is, \fIproc\fR has done all processing that is to be -allowed for the event. -.PP -If there are multiple generic event handlers, each one is called -for each event, in the order in which they were established. -.PP -\fBTk_DeleteGenericHandler\fR may be called to delete a -previously-created generic event handler: it deletes each handler -it finds that matches the \fIproc\fR and \fIclientData\fR arguments. If -no such handler exists, then \fBTk_DeleteGenericHandler\fR returns -without doing anything. Although Tk supports it, it's probably -a bad idea to have more than one callback with the same -\fIproc\fR and \fIclientData\fR arguments. -.PP -Establishing a generic event handler does nothing to ensure that the -process will actually receive the X events that the handler wants to -process. -For example, it is the caller's responsibility to invoke -\fBXSelectInput\fR to select the desired events, if that is necessary. -.SH KEYWORDS -bind, callback, event, handler diff --git a/tk8.6/doc/CrtImgType.3 b/tk8.6/doc/CrtImgType.3 deleted file mode 100644 index cbbc11e..0000000 --- a/tk8.6/doc/CrtImgType.3 +++ /dev/null @@ -1,283 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateImageType\fR(\fItypePtr\fR) -.sp -ClientData -\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) -.sp -\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR) -.SH ARGUMENTS -.AS "const Tk_ImageType" *typePtrPtr -.AP "const Tk_ImageType" *typePtr in -Structure that defines the new type of image. -For Tk 8.4 and earlier this must be static: a -pointer to this structure is retained by the image code. -In Tk 8.5, this limitation was relaxed. -.AP Tcl_Interp *interp in -Interpreter in which image was created. -.AP "const char" *name in -Name of existing image. -.AP Tk_ImageType **typePtrPtr out -Points to word in which to store a pointer to type information for -the given image, if it exists. -.AP int argc in -Number of arguments -.AP char ***argvPtr in/out -Pointer to argument list -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateImageType\fR is invoked to define a new kind of image. -An image type corresponds to a particular value of the \fItype\fR -argument for the \fBimage create\fR command. There may exist -any number of different image types, and new types may be defined -dynamically by calling \fBTk_CreateImageType\fR. -For example, there might be one type for 2-color bitmaps, -another for multi-color images, another for dithered images, -another for video, and so on. -.PP -The code that implements a new image type is called an -\fIimage manager\fR. -It consists of a collection of procedures plus three different -kinds of data structures. -The first data structure is a Tk_ImageType structure, which contains -the name of the image type and pointers to five procedures provided -by the image manager to deal with images of this type: -.CS -typedef struct Tk_ImageType { - const char *\fIname\fR; - Tk_ImageCreateProc *\fIcreateProc\fR; - Tk_ImageGetProc *\fIgetProc\fR; - Tk_ImageDisplayProc *\fIdisplayProc\fR; - Tk_ImageFreeProc *\fIfreeProc\fR; - Tk_ImageDeleteProc *\fIdeleteProc\fR; -} \fBTk_ImageType\fR; -.CE -The fields of this structure will be described in later subsections -of this entry. -.PP -The second major data structure manipulated by an image manager -is called an \fIimage master\fR; it contains overall information -about a particular image, such as the values of the configuration -options specified in an \fBimage create\fR command. -There will usually be one of these structures for each -invocation of the \fBimage create\fR command. -.PP -The third data structure related to images is an \fIimage instance\fR. -There will usually be one of these structures for each usage of an -image in a particular widget. -It is possible for a single image to appear simultaneously -in multiple widgets, or even multiple times in the same widget. -Furthermore, different instances may be on different screens -or displays. -The image instance data structure describes things that may -vary from instance to instance, such as colors and graphics -contexts for redisplay. -There is usually one instance structure for each \fB\-image\fR -option specified for a widget or canvas item. -.PP -The following subsections describe the fields of a Tk_ImageType -in more detail. -.SS NAME -.PP -\fItypePtr->name\fR provides a name for the image type. -Once \fBTk_CreateImageType\fR returns, this name may be used -in \fBimage create\fR commands to create images of the new -type. -If there already existed an image type by this name then -the new image type replaces the old one. -.SS CREATEPROC -.PP -\fItypePtr->createProc\fR provides the address of a procedure for -Tk to call whenever \fBimage create\fR is invoked to create -an image of the new type. -\fItypePtr->createProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageCreateProc\fR( - Tcl_Interp *\fIinterp\fR, - const char *\fIname\fR, - int \fIobjc\fR, - Tcl_Obj *const \fIobjv\fR[], - const Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImaster\fR, - ClientData *\fImasterDataPtr\fR); -.CE -The \fIinterp\fR argument is the interpreter in which the \fBimage\fR -command was invoked, and \fIname\fR is the name for the new image, -which was either specified explicitly in the \fBimage\fR command -or generated automatically by the \fBimage\fR command. -The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration -options for the new image (everything after the name argument to -\fBimage\fR). -The \fImaster\fR argument is a token that refers to Tk's information -about this image; the image manager must return this token to -Tk when invoking the \fBTk_ImageChanged\fR procedure. -Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR -and create an image master data structure for the new image. -\fIcreateProc\fR may store an arbitrary one-word value at -*\fImasterDataPtr\fR, which will be passed back to the -image manager when other callbacks are invoked. -Typically the value is a pointer to the master data -structure for the image. -.PP -If \fIcreateProc\fR encounters an error, it should leave an error -message in the interpreter result and return \fBTCL_ERROR\fR; otherwise -it should return \fBTCL_OK\fR. -.PP -\fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the -size of the image and request an initial redisplay. -.SS GETPROC -.PP -\fItypePtr->getProc\fR is invoked by Tk whenever a widget -calls \fBTk_GetImage\fR to use a particular image. -This procedure must match the following prototype: -.CS -typedef ClientData \fBTk_ImageGetProc\fR( - Tk_Window \fItkwin\fR, - ClientData \fImasterData\fR); -.CE -The \fItkwin\fR argument identifies the window in which the -image will be used and \fImasterData\fR is the value -returned by \fIcreateProc\fR when the image master was created. -\fIgetProc\fR will usually create a data structure for the new -instance, including such things as the resources needed to -display the image in the given window. -\fIgetProc\fR returns a one-word token for the instance, which -is typically the address of the instance data structure. -Tk will pass this value back to the image manager when invoking -its \fIdisplayProc\fR and \fIfreeProc\fR procedures. -.SS DISPLAYPROC -.PP -\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs -to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). -\fIdisplayProc\fR must match the following prototype: -.CS -typedef void \fBTk_ImageDisplayProc\fR( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR, - Drawable \fIdrawable\fR, - int \fIimageX\fR, - int \fIimageY\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIdrawableX\fR, - int \fIdrawableY\fR); -.CE -The \fIinstanceData\fR will be the same as the value returned by -\fIgetProc\fR when the instance was created. -\fIdisplay\fR and \fIdrawable\fR indicate where to display the -image; \fIdrawable\fR may be a pixmap rather than -the window specified to \fIgetProc\fR (this is usually the case, -since most widgets double-buffer their redisplay to get smoother -visual effects). -\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR -identify the region of the image that must be redisplayed. -This region will always be within the size of the image -as specified in the most recent call to \fBTk_ImageChanged\fR. -\fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR -the image should be displayed; \fIdisplayProc\fR should display -the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) -in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. -.SS FREEPROC -.PP -\fItypePtr->freeProc\fR contains the address of a procedure that -Tk will invoke when an image instance is released (i.e., when -\fBTk_FreeImage\fR is invoked). -This can happen, for example, when a widget is deleted or a image item -in a canvas is deleted, or when the image displayed in a widget or -canvas item is changed. -\fIfreeProc\fR must match the following prototype: -.CS -typedef void \fBTk_ImageFreeProc\fR( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR); -.CE -The \fIinstanceData\fR will be the same as the value returned by -\fIgetProc\fR when the instance was created, and \fIdisplay\fR -is the display containing the window for the instance. -\fIfreeProc\fR should release any resources associated with the -image instance, since the instance will never be used again. -.SS DELETEPROC -.PP -\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an -image is being deleted (i.e. when the \fBimage delete\fR command -is invoked). -Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for -each of the image's instances. -\fIdeleteProc\fR must match the following prototype: -.CS -typedef void \fBTk_ImageDeleteProc\fR( - ClientData \fImasterData\fR); -.CE -The \fImasterData\fR argument will be the same as the value -stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the -image was created. -\fIdeleteProc\fR should release any resources associated with -the image. -.SH TK_GETIMAGEMASTERDATA -.PP -The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve -information about an image. For example, an image manager can use this -procedure to locate its image master data for an image. -If there exists an image named \fIname\fR -in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is -filled in with type information for the image (the \fItypePtr\fR value -passed to \fBTk_CreateImageType\fR when the image type was registered) -and the return value is the ClientData value returned by the -\fIcreateProc\fR when the image was created (this is typically a -pointer to the image master data structure). If no such image exists -then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. -.SH "LEGACY INTERFACE SUPPORT" -.PP -In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR -was incompatibly different, with the following prototype: -.CS -typedef int \fBTk_ImageCreateProc\fR( - Tcl_Interp *\fIinterp\fR, - char *\fIname\fR, - int \fIargc\fR, - char **\fIargv\fR, - Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImaster\fR, - ClientData *\fImasterDataPtr\fR); -.CE -Legacy programs and libraries dating from those days may still -contain code that defines extended Tk image types using the old -interface. The Tk header file will still support this legacy -interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR -defined. -.PP -When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may -see the routine \fBTk_InitImageArgs\fR in use. This was a migration -tool used to create stub-enabled extensions that could be loaded -into interps containing all versions of Tk 8.1 and later. Tk 8.5 no longer -provides this routine, but uses a macro to convert any attempted -calls of this routine into an empty comment. Any stub-enabled -extension providing an extended image type via the legacy interface -that is compiled against Tk 8.5 headers and linked against the -Tk 8.5 stub library will produce a file that can be loaded only -into interps with Tk 8.5 or later; that is, the normal stub-compatibility -rules. If a developer needs to generate from such code a file -that is loadable into interps with Tk 8.4 or earlier, they must -use Tk 8.4 headers and stub libraries to do so. -.PP -Any new code written today should not make use of the legacy -interfaces. Expect their support to go away in Tk 9. -.SH "SEE ALSO" -Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage -.SH KEYWORDS -image manager, image type, instance, master diff --git a/tk8.6/doc/CrtItemType.3 b/tk8.6/doc/CrtItemType.3 deleted file mode 100644 index 005d2e2..0000000 --- a/tk8.6/doc/CrtItemType.3 +++ /dev/null @@ -1,695 +0,0 @@ -'\" -'\" Copyright (c) 1994-1995 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateItemType\fR(\fItypePtr\fR) -.sp -Tk_ItemType * -\fBTk_GetItemTypes\fR() -.SH ARGUMENTS -.AS Tk_ItemType *typePtr -.AP Tk_ItemType *typePtr in -Structure that defines the new type of canvas item. -.BE -.SH INTRODUCTION -.PP -\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item -described by the \fItypePtr\fR argument. -An item type corresponds to a particular value of the \fItype\fR -argument to the \fBcreate\fR widget command for canvases, and -the code that implements a canvas item type is called a \fItype manager\fR. -Tk defines several built-in item types, such as \fBrectangle\fR -and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR -allows additional item types to be defined. -Once \fBTk_CreateItemType\fR returns, the new item type may be used -in new or existing canvas widgets just like the built-in item -types. -.PP -\fBTk_GetItemTypes\fR returns a pointer to the first in the list -of all item types currently defined for canvases. -The entries in the list are linked together through their -\fInextPtr\fR fields, with the end of the list marked by a -NULL \fInextPtr\fR. -.PP -You may find it easier to understand the rest of this manual entry -by looking at the code for an existing canvas item type such as -bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c). -The easiest way to create a new type manager is to copy the code -for an existing type and modify it for the new type. -.PP -Tk provides a number of utility procedures for the use of canvas -type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; -these are described in separate manual entries. -.SH "DATA STRUCTURES" -.PP -A type manager consists of a collection of procedures that provide a -standard set of operations on items of that type. -The type manager deals with three kinds of data -structures. -The first data structure is a Tk_ItemType; it contains -information such as the name of the type and pointers to -the standard procedures implemented by the type manager: -.PP -.CS -typedef struct Tk_ItemType { - const char *\fIname\fR; - int \fIitemSize\fR; - Tk_ItemCreateProc *\fIcreateProc\fR; - const Tk_ConfigSpec *\fIconfigSpecs\fR; - Tk_ItemConfigureProc *\fIconfigProc\fR; - Tk_ItemCoordProc *\fIcoordProc\fR; - Tk_ItemDeleteProc *\fIdeleteProc\fR; - Tk_ItemDisplayProc *\fIdisplayProc\fR; - int \fIalwaysRedraw\fR; - Tk_ItemPointProc *\fIpointProc\fR; - Tk_ItemAreaProc *\fIareaProc\fR; - Tk_ItemPostscriptProc *\fIpostscriptProc\fR; - Tk_ItemScaleProc *\fIscaleProc\fR; - Tk_ItemTranslateProc *\fItranslateProc\fR; - Tk_ItemIndexProc *\fIindexProc\fR; - Tk_ItemCursorProc *\fIicursorProc\fR; - Tk_ItemSelectionProc *\fIselectionProc\fR; - Tk_ItemInsertProc *\fIinsertProc\fR; - Tk_ItemDCharsProc *\fIdCharsProc\fR; - Tk_ItemType *\fInextPtr\fR; -} \fBTk_ItemType\fR; -.CE -.PP -The fields of a Tk_ItemType structure are described in more detail -later in this manual entry. -When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR -argument must point to a structure with all of the fields initialized -except \fInextPtr\fR, which Tk sets to link all the types together -into a list. -The structure must be in permanent memory (either statically -allocated or dynamically allocated but never freed); Tk retains -a pointer to this structure. -.PP -The second data structure manipulated by a type manager is an -\fIitem record\fR. -For each item in a canvas there exists one item record. -All of the items of a given type generally have item records with -the same structure, but different types usually have different -formats for their item records. -The first part of each item record is a header with a standard structure -defined by Tk via the type Tk_Item; the rest of the item -record is defined by the type manager. -A type manager must define its item records with a Tk_Item as -the first field. -For example, the item record for bitmap items is defined as follows: -.PP -.CS -typedef struct BitmapItem { - Tk_Item \fIheader\fR; - double \fIx\fR, \fIy\fR; - Tk_Anchor \fIanchor\fR; - Pixmap \fIbitmap\fR; - XColor *\fIfgColor\fR; - XColor *\fIbgColor\fR; - GC \fIgc\fR; -} \fBBitmapItem\fR; -.CE -.PP -The \fIheader\fR substructure contains information used by Tk -to manage the item, such as its identifier, its tags, its type, -and its bounding box. -The fields starting with \fIx\fR belong to the type manager: -Tk will never read or write them. -The type manager should not need to read or write any of the -fields in the header except for four fields -whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -These fields give a bounding box for the items using integer -canvas coordinates: the item should not cover any pixels -with x-coordinate lower than \fIx1\fR or y-coordinate -lower than \fIy1\fR, nor should it cover any pixels with -x-coordinate greater than or equal to \fIx2\fR or y-coordinate -greater than or equal to \fIy2\fR. -It is up to the type manager to keep the bounding box up to -date as the item is moved and reconfigured. -.PP -Whenever Tk calls a procedure in a type manager it passes in a pointer -to an item record. -The argument is always passed as a pointer to a Tk_Item; the type -manager will typically cast this into a pointer to its own specific -type, such as BitmapItem. -.PP -The third data structure used by type managers has type -Tk_Canvas; it serves as an opaque handle for the canvas widget -as a whole. -Type managers need not know anything about the contents of this -structure. -A Tk_Canvas handle is typically passed in to the -procedures of a type manager, and the type manager can pass the -handle back to library procedures such as Tk_CanvasTkwin -to fetch information about the canvas. -.SH "TK_ITEMTYPE FIELDS" -.SS NAME -.PP -This section and the ones that follow describe each of the fields -in a Tk_ItemType structure in detail. -The \fIname\fR field provides a string name for the item type. -Once \fBTk_CreateImageType\fR returns, this name may be used -in \fBcreate\fR widget commands to create items of the new -type. -If there already existed an item type by this name then -the new item type replaces the old one. -.SS "FLAGS (IN ALWAYSREDRAW)" -.PP -The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons) -contains a collection of flag bits that modify how the canvas core interacts -with the item. The following bits are defined: -.TP -\fB1\fR -. -Indicates that the item should always be redrawn when any part of the canvas -is redrawn, rather than only when the bounding box of the item overlaps the -area being redrawn. This is used by window items, for example, which need to -unmap subwindows that are not on the screen. -.TP -\fBTK_CONFIG_OBJS\fR -. -Indicates that operations which would otherwise take a string (or array of -strings) actually take a Tcl_Obj reference (or an array of such references). -The operations to which this applies are the \fIconfigProc\fR, the -\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the -\fIinsertProc\fR. -.TP -\fBTK_MOVABLE_POINTS\fR -.VS 8.6 -Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and -\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon -types, and that hence individual coordinate points can be moved. Must not be -set if any of the above methods is NULL. -.VE 8.6 -.SS ITEMSIZE -.PP -\fItypePtr\->itemSize\fR gives the size in bytes of item records -of this type, including the Tk_Item header. -Tk uses this size to allocate memory space for items of the type. -All of the item records for a given type must have the same size. -If variable length fields are needed for an item (such as a list -of points for a polygon), the type manager can allocate a separate -object of variable length and keep a pointer to it in the item record. -.SS CREATEPROC -.PP -\fItypePtr\->createProc\fR points to a procedure for -Tk to call whenever a new item of this type is created. -\fItypePtr\->createProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemCreateProc\fR( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj *const \fIobjv\fR[]); -.CE -.PP -The \fIinterp\fR argument is the interpreter in which the canvas's -\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a -handle for the canvas widget. -\fIitemPtr\fR is a pointer to a newly-allocated item of -size \fItypePtr\->itemSize\fR. -Tk has already initialized the item's header (the first -\fBsizeof(Tk_ItemType)\fR bytes). -The \fIobjc\fR and \fIobjv\fR arguments describe all of the -arguments to the \fBcreate\fR command after the \fItype\fR -argument. -Note that if \fBTK_CONFIG_OBJS\fR is not set in the -\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually -contain a pointer to an array of constant strings. -For example, in the widget command: -.PP -.CS -\fB\&.c create rectangle 10 20 50 50 \-fill black\fR -.CE -.PP -\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the -integer object \fB10\fR. -.PP -\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize -the type-specific parts of the item record and set an initial value -for the bounding box in the item's header. -It should return a standard Tcl completion code and leave an -error message in the interpreter result if an error occurs. -If an error occurs Tk will free the item record, so \fIcreateProc\fR -must be sure to leave the item record in a clean state if it returns an error -(e.g., it must free any additional memory that it allocated for -the item). -.SS CONFIGSPECS -.PP -Each type manager must provide a standard table describing its -configuration options, in a form suitable for use with -\fBTk_ConfigureWidget\fR. -This table will normally be used by \fItypePtr\->createProc\fR -and \fItypePtr\->configProc\fR, but Tk also uses it directly -to retrieve option information in the \fBitemcget\fR and -\fBitemconfigure\fR widget commands. -\fItypePtr\->configSpecs\fR must point to the configuration table -for this type. -Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR -for implementing the \fB\-tags\fR option; see an existing type -manager for an example of how to use it in \fIconfigSpecs\fR. -.SS CONFIGPROC -.PP -\fItypePtr\->configProc\fR is called by Tk whenever the -\fBitemconfigure\fR widget command is invoked to change the -configuration options for a canvas item. -This procedure must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemConfigureProc\fR( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj *const \fIobjv\fR[], - int \fIflags\fR); -.CE -.PP -The \fIinterp\fR argument identifies the interpreter in which the -widget command was invoked, \fIcanvas\fR is a handle for the canvas -widget, and \fIitemPtr\fR is a pointer to the item being configured. -\fIobjc\fR and \fIobjv\fR contain the configuration options. -Note that if \fBTK_CONFIG_OBJS\fR is not set in the -\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually -contain a pointer to an array of constant strings. -For example, if the following command is invoked: -.PP -.CS -\fB\&.c itemconfigure 2 \-fill red \-outline black\fR -.CE -.PP -\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR -through \fBblack\fR. -\fIobjc\fR will always be an even value. -The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; -currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk -invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR -procedure will usually invoke \fIconfigProc\fR with different flag values. -.PP -\fItypePtr\->configProc\fR returns a standard Tcl completion code and -leaves an error message in the interpreter result if an error occurs. -It must update the item's bounding box to reflect the new configuration -options. -.SS COORDPROC -.PP -\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR -widget command for an item. -It must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemCoordProc\fR( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj *const \fIobjv\fR[]); -.CE -.PP -The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR -all have the standard meanings, and \fIobjc\fR and \fIobjv\fR -describe the coordinate arguments. -Note that if \fBTK_CONFIG_OBJS\fR is not set in the -\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually -contain a pointer to an array of constant strings. -For example, if the following widget command is invoked: -.PP -.CS -\fB\&.c coords 2 30 90\fR -.CE -.PP -\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects -\fB30\fR and \fB90\fR. -.PP -The \fIcoordProc\fR procedure should process the new coordinates, -update the item appropriately (e.g., it must reset the bounding -box in the item's header), and return a standard Tcl completion -code. -If an error occurs, \fIcoordProc\fR must leave an error message in -the interpreter result. -.SS DELETEPROC -.PP -\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item -and free any resources allocated to it. -It must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemDeleteProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Display *\fIdisplay\fR); -.CE -.PP -The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual -interpretations, and \fIdisplay\fR identifies the X display containing -the canvas. -\fIdeleteProc\fR must free up any resources allocated for the item, -so that Tk can free the item record. -\fIdeleteProc\fR should not actually free the item record; this will -be done by Tk when \fIdeleteProc\fR returns. -.SS "DISPLAYPROC" -.PP -\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item -on the screen. -It must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemDisplayProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Display *\fIdisplay\fR, - Drawable \fIdst\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR); -.CE -.PP -The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. -\fIdisplay\fR identifies the display containing the canvas, and -\fIdst\fR specifies a drawable in which the item should be rendered; -typically this is an off-screen pixmap, which Tk will copy into -the canvas's window once all relevant items have been drawn. -\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular -region in canvas coordinates, which is the area to be redrawn; -only information that overlaps this area needs to be redrawn. -Tk will not call \fIdisplayProc\fR unless the item's bounding box -overlaps the redraw area, but the type manager may wish to use -the redraw area to optimize the redisplay of the item. -.PP -Because of scrolling and the use of off-screen pixmaps for -double-buffered redisplay, the item's coordinates in \fIdst\fR -will not necessarily be the same as those in the canvas. -\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR -to transform coordinates from those of the canvas to those -of \fIdst\fR. -.PP -Normally an item's \fIdisplayProc\fR is only invoked if the item -overlaps the area being displayed. -However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1, -(i.e.\| -.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" ) -then \fIdisplayProc\fR is invoked during every redisplay operation, -even if the item does not overlap the area of redisplay; this is useful for -cases such as window items, where the subwindow needs to be unmapped when it -is off the screen. -.SS POINTPROC -.PP -\fItypePtr\->pointProc\fR is invoked by Tk to find out how close -a given point is to a canvas item. -Tk uses this procedure for purposes such as locating the item -under the mouse or finding the closest item to a given point. -The procedure must match the following prototype: -.PP -.CS -typedef double \fBTk_ItemPointProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIpointPtr\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. -\fIpointPtr\fR points to an array of two numbers giving -the x and y coordinates of a point. -\fIpointProc\fR must return a real value giving the distance -from the point to the item, or 0 if the point lies inside -the item. -.SS AREAPROC -.PP -\fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship -between an item and a rectangular area. -It must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemAreaProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIrectPtr\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. -\fIrectPtr\fR points to an array of four real numbers; -the first two give the x and y coordinates of the upper left -corner of a rectangle, and the second two give the x and y -coordinates of the lower right corner. -\fIareaProc\fR must return \-1 if the item lies entirely outside -the given area, 0 if it lies partially inside and partially -outside the area, and 1 if it lies entirely inside the area. -.SS POSTSCRIPTPROC -.PP -\fItypePtr\->postscriptProc\fR is invoked by Tk to generate -Postscript for an item during the \fBpostscript\fR widget command. -If the type manager is not capable of generating Postscript then -\fItypePtr\->postscriptProc\fR should be NULL. -The procedure must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemPostscriptProc\fR( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIprepass\fR); -.CE -.PP -The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have -standard meanings; \fIprepass\fR will be described below. -If \fIpostscriptProc\fR completes successfully, it should append -Postscript for the item to the information in the interpreter result -(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) -and return \fBTCL_OK\fR. -If an error occurs, \fIpostscriptProc\fR should clear the result -and replace its contents with an error message; then it should -return \fBTCL_ERROR\fR. -.PP -Tk provides a collection of utility procedures to simplify -\fIpostscriptProc\fR. -For example, \fBTk_CanvasPsColor\fR will generate Postscript to set -the current color to a given Tk color and \fBTk_CanvasPsFont\fR will -set up font information. -When generating Postscript, the type manager is free to change the -graphics state of the Postscript interpreter, since Tk places -\fBgsave\fR and \fBgrestore\fR commands around the Postscript for -the item. -The type manager can use canvas x coordinates directly in its Postscript, -but it must call \fBTk_CanvasPsY\fR to convert y coordinates from -the space of the canvas (where the origin is at the -upper left) to the space of Postscript (where the origin is at the -lower left). -.PP -In order to generate Postscript that complies with the Adobe Document -Structuring Conventions, Tk actually generates Postscript in two passes. -It calls each item's \fIpostscriptProc\fR in each pass. -The only purpose of the first pass is to collect font information -(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is -discarded. -Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 -during the first pass; the type manager can use \fIprepass\fR to skip -all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. -During the second pass \fIprepass\fR will be 0, so the type manager -must generate complete Postscript. -.SS SCALEPROC -.PP -\fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item -during the \fBscale\fR widget command. -The procedure must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemScaleProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIoriginX\fR, - double \fIoriginY\fR, - double \fIscaleX\fR, - double \fIscaleY\fR); -.CE -.PP -The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. -\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which -the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the -x and y scale factors. -The item should adjust its coordinates so that a point in the item -that used to have coordinates \fIx\fR and \fIy\fR will have new -coordinates \fIx\(fm\fR and \fIy\(fm\fR, where -.PP -.CS -\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR) -\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR) -.CE -.PP -\fIscaleProc\fR must also update the bounding box in the item's -header. -.SS TRANSLATEPROC -.PP -\fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item -during the \fBmove\fR widget command. -The procedure must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemTranslateProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIdeltaX\fR, - double \fIdeltaY\fR); -.CE -.PP -The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, -and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be -added to each x and y coordinate within the item. -The type manager should adjust the item's coordinates and -update the bounding box in the item's header. -.SS INDEXPROC -.PP -\fItypePtr\->indexProc\fR is invoked by Tk to translate a string -index specification into a numerical index, for example during the -\fBindex\fR widget command. -It is only relevant for item types that support indexable text or coordinates; -\fItypePtr\->indexProc\fR may be specified as NULL for non-textual -item types if they do not support detailed coordinate addressing. -The procedure must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemIndexProc\fR( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Tcl_Obj *\fIindexObj\fR, - int *\fIindexPtr\fR); -.CE -.PP -The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all -have the usual meaning. -\fIindexObj\fR contains a textual description of an index, -and \fIindexPtr\fR points to an integer value that should be -filled in with a numerical index. -Note that if \fBTK_CONFIG_OBJS\fR is not set in the -\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will -actually contain a pointer to a constant string. -It is up to the type manager to decide what forms of index -are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, -\fBend\fR, etc.). -\fIindexProc\fR should return a Tcl completion code and set -the interpreter result in the event of an error. -.SS ICURSORPROC -.PP -\fItypePtr\->icursorProc\fR is invoked by Tk during -the \fBicursor\fR widget command to set the position of the -insertion cursor in a textual item. -It is only relevant for item types that support an insertion cursor; -\fItypePtr\->icursorProc\fR may be specified as NULL for item types -that do not support an insertion cursor. -The procedure must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemCursorProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and -\fIindex\fR is an index into the item's text, as returned by a -previous call to \fItypePtr\->insertProc\fR. -The type manager should position the insertion cursor in the -item just before the character given by \fIindex\fR. -Whether or not to actually display the insertion cursor is -determined by other information provided by \fBTk_CanvasGetTextInfo\fR. -.SS SELECTIONPROC -.PP -\fItypePtr\->selectionProc\fR is invoked by Tk during selection -retrievals; it must return part or all of the selected text in -the item (if any). -It is only relevant for item types that support text; -\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual -item types. -The procedure must match the following prototype: -.PP -.CS -typedef int \fBTk_ItemSelectionProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. -\fIoffset\fR is an offset in bytes into the selection where 0 refers -to the first byte of the selection; it identifies -the first character that is to be returned in this call. -\fIbuffer\fR points to an area of memory in which to store the -requested bytes, and \fImaxBytes\fR specifies the maximum number -of bytes to return. -\fIselectionProc\fR should extract up to \fImaxBytes\fR characters -from the selection and copy them to \fImaxBytes\fR; it should -return a count of the number of bytes actually copied, which may -be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes -in the selection. -.SS INSERTPROC -.PP -\fItypePtr\->insertProc\fR is invoked by Tk during -the \fBinsert\fR widget command to insert new text or coordinates into a -canvas item. -It is only relevant for item types that support the \fBinsert\fR method; -\fItypePtr\->insertProc\fR may be specified as NULL for other -item types. -The procedure must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemInsertProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR, - Tcl_Obj *\fIobj\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. -\fIindex\fR is an index into the item's text, as returned by a -previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR -contains new text to insert just before the character given -by \fIindex\fR. -Note that if \fBTK_CONFIG_OBJS\fR is not set in the -\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will -actually contain a pointer to a constant string to be inserted. -If the item supports modification of the coordinates list by this -.PP -The type manager should insert the text and recompute the bounding -box in the item's header. -.SS DCHARSPROC -.PP -\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR -widget command to delete a range of text from a canvas item or a range of -coordinates from a pathed item. -It is only relevant for item types that support text; -\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual -item types that do not want to support coordinate deletion. -The procedure must match the following prototype: -.PP -.CS -typedef void \fBTk_ItemDCharsProc\fR( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIfirst\fR, - int \fIlast\fR); -.CE -.PP -\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. -\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes -to be deleted, as returned by previous calls to \fItypePtr\->indexProc\fR. -The type manager should delete the specified characters and update -the bounding box in the item's header. -.SH "SEE ALSO" -Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin -.SH KEYWORDS -canvas, focus, item type, selection, type manager diff --git a/tk8.6/doc/CrtPhImgFmt.3 b/tk8.6/doc/CrtPhImgFmt.3 deleted file mode 100644 index c7e792a..0000000 --- a/tk8.6/doc/CrtPhImgFmt.3 +++ /dev/null @@ -1,270 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Australian National University -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), -'\" Department of Computer Science, -'\" Australian National University. -'\" -.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreatePhotoImageFormat \- define new file format for photo images -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) -.SH ARGUMENTS -.AS "const Tk_PhotoImageFormat" *formatPtr -.AP "const Tk_PhotoImageFormat" *formatPtr in -Structure that defines the new file format. -.BE -.SH DESCRIPTION -.PP -\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format -for image data for use with photo images. The code that implements an -image file format is called an image file format handler, or -handler for short. The photo image code -maintains a list of handlers that can be used to read and -write data to or from a file. Some handlers may also -support reading image data from a string or converting image data to a -string format. -The user can specify which handler to use with the \fB\-format\fR -image configuration option or the \fB\-format\fR option to the -\fBread\fR and \fBwrite\fR photo image subcommands. -.PP -An image file format handler consists of a collection of procedures -plus a Tk_PhotoImageFormat structure, which contains the name of the -image file format and pointers to six procedures provided by the -handler to deal with files and strings in this format. The -Tk_PhotoImageFormat structure contains the following fields: -.CS -typedef struct Tk_PhotoImageFormat { - const char *\fIname\fR; - Tk_ImageFileMatchProc *\fIfileMatchProc\fR; - Tk_ImageStringMatchProc *\fIstringMatchProc\fR; - Tk_ImageFileReadProc *\fIfileReadProc\fR; - Tk_ImageStringReadProc *\fIstringReadProc\fR; - Tk_ImageFileWriteProc *\fIfileWriteProc\fR; - Tk_ImageStringWriteProc *\fIstringWriteProc\fR; -} \fBTk_PhotoImageFormat\fR; -.CE -.PP -The handler need not provide implementations of all six procedures. -For example, the procedures that handle string data would not be -provided for a format in which the image data are stored in binary, -and could therefore contain null characters. If any procedure is not -implemented, the corresponding pointer in the Tk_PhotoImageFormat -structure should be set to NULL. The handler must provide the -\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR -procedure, and the \fIstringMatchProc\fR procedure if it provides the -\fIstringReadProc\fR procedure. -.SS NAME -.PP -\fIformatPtr->name\fR provides a name for the image type. -Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used -in the \fB\-format\fR photo image configuration and subcommand option. -The manual page for the photo image (photo(n)) describes how image -file formats are chosen based on their names and the value given to -the \fB\-format\fR option. The first character of \fIformatPtr->name\fR -must not be an uppercase character from the ASCII character set -(that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used -only for legacy interface support (see below). -.SS FILEMATCHPROC -.PP -\fIformatPtr->fileMatchProc\fR provides the address of a procedure for -Tk to call when it is searching for an image file format handler -suitable for reading data in a given file. -\fIformatPtr->fileMatchProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageFileMatchProc\fR( - Tcl_Channel \fIchan\fR, - const char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); -.CE -The \fIfileName\fR argument is the name of the file containing the -image data, which is open for reading as \fIchan\fR. The -\fIformat\fR argument contains the value given for the -\fB\-format\fR option, or NULL if the option was not specified. -If the data in the file appears to be in the format supported by this -handler, the \fIformatPtr->fileMatchProc\fR procedure should store the -width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR -respectively, and return 1. Otherwise it should return 0. -.SS STRINGMATCHPROC -.PP -\fIformatPtr->stringMatchProc\fR provides the address of a procedure for -Tk to call when it is searching for an image file format handler for -suitable for reading data from a given string. -\fIformatPtr->stringMatchProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageStringMatchProc\fR( - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); -.CE -The \fIdata\fR argument points to the object containing the image -data. The \fIformat\fR argument contains the value given for -the \fB\-format\fR option, or NULL if the option was not specified. -If the data in the string appears to be in the format supported by -this handler, the \fIformatPtr->stringMatchProc\fR procedure should -store the width and height of the image in *\fIwidthPtr\fR and -*\fIheightPtr\fR respectively, and return 1. Otherwise it should -return 0. -.SS FILEREADPROC -.PP -\fIformatPtr->fileReadProc\fR provides the address of a procedure for -Tk to call to read data from an image file into a photo image. -\fIformatPtr->fileReadProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageFileReadProc\fR( - Tcl_Interp *\fIinterp\fR, - Tcl_Channel \fIchan\fR, - const char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); -.CE -The \fIinterp\fR argument is the interpreter in which the command was -invoked to read the image; it should be used for reporting errors. -The image data is in the file named \fIfileName\fR, which is open for -reading as \fIchan\fR. The \fIformat\fR argument contains the -value given for the \fB\-format\fR option, or NULL if the option was -not specified. The image data in the file, or a subimage of it, is to -be read into the photo image identified by the handle -\fIimageHandle\fR. The subimage of the data in the file is of -dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at -coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo -image with its top-left corner at coordinates -(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. -The return value is a standard Tcl return value. -.SS STRINGREADPROC -.PP -\fIformatPtr->stringReadProc\fR provides the address of a procedure for -Tk to call to read data from a string into a photo image. -\fIformatPtr->stringReadProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageStringReadProc\fR( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); -.CE -The \fIinterp\fR argument is the interpreter in which the command was -invoked to read the image; it should be used for reporting errors. -The \fIdata\fR argument points to the image data in object form. -The \fIformat\fR argument contains the -value given for the \fB\-format\fR option, or NULL if the option was -not specified. The image data in the string, or a subimage of it, is to -be read into the photo image identified by the handle -\fIimageHandle\fR. The subimage of the data in the string is of -dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at -coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo -image with its top-left corner at coordinates -(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. -The return value is a standard Tcl return value. -.SS FILEWRITEPROC -.PP -\fIformatPtr->fileWriteProc\fR provides the address of a procedure for -Tk to call to write data from a photo image to a file. -\fIformatPtr->fileWriteProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageFileWriteProc\fR( - Tcl_Interp *\fIinterp\fR, - const char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); -.CE -The \fIinterp\fR argument is the interpreter in which the command was -invoked to write the image; it should be used for reporting errors. -The image data to be written are in memory and are described by the -Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the -manual page FindPhoto(3) for details. The \fIfileName\fR argument -points to the string giving the name of the file in which to write the -image data. The \fIformat\fR argument contains the -value given for the \fB\-format\fR option, or NULL if the option was -not specified. The format string can contain extra characters -after the name of the format. If appropriate, the -\fIformatPtr->fileWriteProc\fR procedure may interpret these -characters to specify further details about the image file. -The return value is a standard Tcl return value. -.SS STRINGWRITEPROC -.PP -\fIformatPtr->stringWriteProc\fR provides the address of a procedure for -Tk to call to translate image data from a photo image into a string. -\fIformatPtr->stringWriteProc\fR must match the following prototype: -.CS -typedef int \fBTk_ImageStringWriteProc\fR( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); -.CE -The \fIinterp\fR argument is the interpreter in which the command was -invoked to convert the image; it should be used for reporting errors. -The image data to be converted are in memory and are described by the -Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the -manual page FindPhoto(3) for details. The data for the string -should be put in the interpreter \fIinterp\fR result. -The \fIformat\fR argument contains the -value given for the \fB\-format\fR option, or NULL if the option was -not specified. The format string can contain extra characters -after the name of the format. If appropriate, the -\fIformatPtr->stringWriteProc\fR procedure may interpret these -characters to specify further details about the image file. -The return value is a standard Tcl return value. -.SH "LEGACY INTERFACE SUPPORT" -.PP -In Tk 8.2 and earlier, the definition of all the function pointer -types stored in fields of a \fBTk_PhotoImageFormat\fR struct were -incompatibly different. Legacy programs and libraries dating from -those days may still contain code that defines extended Tk photo image -formats using the old interface. The Tk header file will still support -this legacy interface if the code is compiled with the -macro \fBUSE_OLD_IMAGE\fR defined. Alternatively, the legacy interfaces -are used if the first character of \fIformatPtr->name\fR is an -uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts -are used to forgive the type mismatch. For example, -.CS -static Tk_PhotoImageFormat myFormat = { - "MyFormat", - (Tk_ImageFileMatchProc *) FileMatch, - NULL, - (Tk_ImageFileReadProc *) FileRead, - NULL, - NULL, - NULL -}; -.CE -would define a minimal \fBTk_PhotoImageFormat\fR that operates provide -only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR -are written according to the legacy interfaces of Tk 8.2 or earlier. -.PP -Any stub-enabled extension providing an extended photo image format -via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro -that is compiled against Tk 8.5 headers and linked against the -Tk 8.5 stub library will produce a file that can be loaded only -into interps with Tk 8.5 or later; that is, the normal stub-compatibility -rules. If a developer needs to generate from such code a file -that is loadable into interps with Tk 8.4 or earlier, they must -use Tk 8.4 headers and stub libraries to do so. -.PP -Any new code written today should not make use of the legacy -interfaces. Expect their support to go away in Tk 9. -.SH "SEE ALSO" -Tk_FindPhoto, Tk_PhotoPutBlock -.SH KEYWORDS -photo image, image file diff --git a/tk8.6/doc/CrtSelHdlr.3 b/tk8.6/doc/CrtSelHdlr.3 deleted file mode 100644 index 2292ccc..0000000 --- a/tk8.6/doc/CrtSelHdlr.3 +++ /dev/null @@ -1,116 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) -.sp -\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) -.SH ARGUMENTS -.AS Tk_SelectionProc clientData -.AP Tk_Window tkwin in -Window for which \fIproc\fR will provide selection information. -.AP Atom selection in -The name of the selection for which \fIproc\fR will provide -selection information. -.AP Atom target in -Form in which \fIproc\fR can provide the selection (e.g. STRING -or FILE_NAME). Corresponds to \fItype\fR arguments in \fBselection\fR -commands. -.AP Tk_SelectionProc *proc in -Procedure to invoke whenever the selection is owned by \fItkwin\fR -and the selection contents are requested in the format given by -\fItarget\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP Atom format in -If the selection requestor is not in this process, \fIformat\fR determines -the representation used to transmit the selection to its -requestor. -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateSelHandler\fR arranges for a particular procedure -(\fIproc\fR) to be called whenever \fIselection\fR is owned by -\fItkwin\fR and the selection contents are requested in the -form given by \fItarget\fR. -\fITarget\fR should be one of -the entries defined in the left column of Table 2 of the -X Inter-Client Communication Conventions Manual (ICCCM) or -any other form in which an application is willing to present -the selection. The most common form is STRING. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTk_SelectionProc\fR: -.CS -typedef int \fBTk_SelectionProc\fR( - ClientData \fIclientData\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the -\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR. -Typically, \fIclientData\fR points to a data -structure containing application-specific information that is -needed to retrieve the selection. \fIOffset\fR specifies an -offset position into the selection, \fIbuffer\fR specifies a -location at which to copy information about the selection, and -\fImaxBytes\fR specifies the amount of space available at -\fIbuffer\fR. \fIProc\fR should place a NULL-terminated string -at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters -(not including the terminating NULL), and it should return a -count of the number of non-NULL characters stored at -\fIbuffer\fR. If the selection no longer exists (e.g. it once -existed but the user deleted the range of characters containing -it), then \fIproc\fR should return \-1. -.PP -When transferring large selections, Tk will break them up into -smaller pieces (typically a few thousand bytes each) for more -efficient transmission. It will do this by calling \fIproc\fR -one or more times, using successively higher values of \fIoffset\fR -to retrieve successive portions of the selection. If \fIproc\fR -returns a count less than \fImaxBytes\fR it means that the entire -remainder of the selection has been returned. If \fIproc\fR's return -value is \fImaxBytes\fR it means there may be additional information -in the selection, so Tk must make another call to \fIproc\fR to -retrieve the next portion. -.PP -\fIProc\fR always returns selection information in the form of a -character string. However, the ICCCM allows for information to -be transmitted from the selection owner to the selection requestor -in any of several formats, such as a string, an array of atoms, an -array of integers, etc. The \fIformat\fR argument to -\fBTk_CreateSelHandler\fR indicates what format should be used to -transmit the selection to its requestor (see the middle column of -Table 2 of the ICCCM for examples). If \fIformat\fR is not -STRING, then Tk will take the value returned by \fIproc\fR and divided -it into fields separated by white space. If \fIformat\fR is ATOM, -then Tk will return the selection as an array of atoms, with each -field in \fIproc\fR's result treated as the name of one atom. For -any other value of \fIformat\fR, Tk will return the selection as an -array of 32-bit values where each field of \fIproc\fR's result is -treated as a number and translated to a 32-bit value. In any event, -the \fIformat\fR atom is returned to the selection requestor along -with the contents of the selection. -.PP -If \fBTk_CreateSelHandler\fR is called when there already exists a -handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the -existing handler is replaced with a new one. -.PP -\fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR, -\fIselection\fR, and \fItarget\fR, if such a handler exists. -If there is no such handler then it has no effect. -.SH KEYWORDS -format, handler, selection, target diff --git a/tk8.6/doc/CrtWindow.3 b/tk8.6/doc/CrtWindow.3 deleted file mode 100644 index b254460..0000000 --- a/tk8.6/doc/CrtWindow.3 +++ /dev/null @@ -1,146 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR) -.sp -Tk_Window -\fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR) -.sp -Tk_Window -\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) -.sp -\fBTk_DestroyWindow\fR(\fItkwin\fR) -.sp -\fBTk_MakeWindowExist\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tcl_Interp *topLevScreen -.AP Tcl_Interp *interp out -Tcl interpreter to use for error reporting. If no error occurs, -then \fI*interp\fR is not modified. -.AP Tk_Window parent in -Token for the window that is to serve as the logical parent of -the new window. -.AP "const char" *name in -Name to use for this window. Must be unique among all children of -the same \fIparent\fR. -.AP "const char" *topLevScreen in -Has same format as \fIscreenName\fR. If NULL, then new window is -created as an internal window. If non-NULL, new window is created as -a top-level window on screen \fItopLevScreen\fR. If \fItopLevScreen\fR -is an empty string -.PQ "" -then new window is created as top-level window of \fIparent\fR's screen. -.AP Tk_Window tkwin in -Token for window. -.AP "const char" *pathName in -Name of new window, specified as path name within application -(e.g. \fB.a.b.c\fR). -.BE -.SH DESCRIPTION -.PP -The procedures \fBTk_CreateWindow\fR, -\fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR -are used to create new windows for -use in Tk-based applications. Each of the procedures returns a token -that can be used to manipulate the window in other calls to the Tk -library. If the window could not be created successfully, then NULL -is returned and the result of interpreter \fIinterp\fR is modified to -hold an error message. -.PP -Tk supports two different kinds of windows: internal -windows and top-level windows. -An internal window is an interior window of a Tk application, such as a -scrollbar or menu bar or button. A top-level window is one that is -created as a child of a screen's root window, rather than as an -interior window, but which is logically part of some existing main -window. Examples of top-level windows are pop-up menus and dialog boxes. -.PP -New windows may be created by calling -\fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is -NULL, then the new window will be an internal window. If -\fItopLevScreen\fR is non-NULL, then the new window will be a -top-level window: \fItopLevScreen\fR indicates the name of -a screen and the new window will be created as a child of the -root window of \fItopLevScreen\fR. In either case Tk will -consider the new window to be the logical child of \fIparent\fR: -the new window's path name will reflect this fact, options may -be specified for the new window under this assumption, and so on. -The only difference is that new X window for a top-level window -will not be a child of \fIparent\fR's X window. For example, a pull-down -menu's \fIparent\fR would be the button-like window used to invoke it, -which would in turn be a child of the menu bar window. A dialog box might -have the application's main window as its parent. -.PP -\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in -that it creates an unnamed window. This window will be manipulatable -only using C interfaces, and will not be visible to Tcl scripts. Both -interior windows and top-level windows may be created with -\fBTk_CreateAnonymousWindow\fR. -.PP -\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying -new windows. In \fBTk_CreateWindowFromPath\fR the new -window is specified with a token for any window in the target -application (\fItkwin\fR), plus a path name for the new window. -It produces the same effect as \fBTk_CreateWindow\fR and allows -both top-level and internal windows to be created, depending on -the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR, -as in calls to \fBTk_CreateWindow\fR, the parent of the new window -must exist at the time of the call, but the new window must not -already exist. -.PP -The window creation procedures do not -actually issue the command to X to create a window. -Instead, they create a local data structure associated with -the window and defer the creation of the X window. -The window will actually be created by the first call to -\fBTk_MapWindow\fR. Deferred window creation allows various -aspects of the window (such as its size, background color, -etc.) to be modified after its creation without incurring -any overhead in the X server. When the window is finally -mapped all of the window attributes can be set while creating -the window. -.PP -The value returned by a window-creation procedure is not the -X token for the window (it cannot be, since X has not been -asked to create the window yet). Instead, it is a token -for Tk's local data structure for the window. Most -of the Tk library procedures take Tk_Window tokens, rather -than X identifiers. The actual -X window identifier can be retrieved from the local -data structure using the \fBTk_WindowId\fR macro; see -the manual entry for \fBTk_WindowId\fR for details. -.PP -\fBTk_DestroyWindow\fR deletes a window and all the data -structures associated with it, including any event handlers -created with \fBTk_CreateEventHandler\fR. In addition, -\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR -recursively (where children are defined in the Tk sense, consisting -of all windows that were created with the given window as \fIparent\fR). -If \fItkwin\fR is an internal window, then event -handlers interested in destroy events -are invoked immediately. If \fItkwin\fR is a top-level or main window, -then the event handlers will be invoked later, after X has seen -the request and returned an event for it. -.PP -If a window has been created -but has not been mapped, so no X window exists, it is -possible to force the creation of the X window by -calling \fBTk_MakeWindowExist\fR. This procedure issues -the X commands to instantiate the window given by \fItkwin\fR. -.SH KEYWORDS -create, deferred creation, destroy, display, internal window, -screen, top-level window, window diff --git a/tk8.6/doc/DeleteImg.3 b/tk8.6/doc/DeleteImg.3 deleted file mode 100644 index 507be72..0000000 --- a/tk8.6/doc/DeleteImg.3 +++ /dev/null @@ -1,31 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_DeleteImage \- Destroy an image. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_DeleteImage\fR(\fIinterp, name\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter for which the image was created. -.AP "const char" *name in -Name of the image. -.BE -.SH DESCRIPTION -.PP -\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR -and \fIname\fR, if there is one. All instances of that image -will redisplay as empty regions. If the given image does not -exist then the procedure has no effect. -.SH KEYWORDS -delete image, image manager diff --git a/tk8.6/doc/DrawFocHlt.3 b/tk8.6/doc/DrawFocHlt.3 deleted file mode 100644 index e2d1578..0000000 --- a/tk8.6/doc/DrawFocHlt.3 +++ /dev/null @@ -1,36 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *joinPtr -.AP Tk_Window tkwin in -Window for which the highlight is being drawn. Used to retrieve -the window's dimensions, among other things. -.AP GC gc in -Graphics context to use for drawing the highlight. -.AP int width in -Width of the highlight ring, in pixels. -.AP Drawable drawable in -Drawable in which to draw the highlight; usually an offscreen -pixmap for double buffering. -.BE -.SH DESCRIPTION -.PP -\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the -traversal highlight ring for a widget. -It is typically invoked by widgets during redisplay. -.SH KEYWORDS -focus, traversal highlight diff --git a/tk8.6/doc/EventHndlr.3 b/tk8.6/doc/EventHndlr.3 deleted file mode 100644 index 97857fb..0000000 --- a/tk8.6/doc/EventHndlr.3 +++ /dev/null @@ -1,75 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) -.sp -\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) -.SH ARGUMENTS -.AS "unsigned long" clientData -.AP Tk_Window tkwin in -Token for window in which events may occur. -.AP "unsigned long" mask in -Bit-mask of events (such as \fBButtonPressMask\fR) -for which \fIproc\fR should be called. -.AP Tk_EventProc *proc in -Procedure to invoke whenever an event in \fImask\fR occurs -in the window given by \fItkwin\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be -invoked in the future whenever one of the event types specified -by \fImask\fR occurs in the window specified by \fItkwin\fR. -The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; -this mechanism only works in programs that dispatch events -through \fBTk_HandleEvent\fR (or through other Tk procedures that -call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or -\fBTk_MainLoop\fR). -.PP -\fIProc\fR should have arguments and result that match the -type \fBTk_EventProc\fR: -.CS -typedef void \fBTk_EventProc\fR( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTk_CreateEventHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -the window in which the event occurred. \fIEventPtr\fR is -a pointer to the X event, which will be one of the ones -specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR. -.PP -\fBTk_DeleteEventHandler\fR may be called to delete a -previously-created event handler: it deletes the first handler -it finds that is associated with \fItkwin\fR and matches the -\fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. If -no such handler exists, then \fBTk_HandleEvent\fR returns -without doing anything. Although Tk supports it, it's probably -a bad idea to have more than one callback with the same \fImask\fR, -\fIproc\fR, and \fIclientData\fR arguments. -When a window is deleted all of its handlers will be deleted -automatically; in this case there is no need to call -\fBTk_DeleteEventHandler\fR. -.PP -If multiple handlers are declared for the same type of X event -on the same window, then the handlers will be invoked in the -order they were created. -.SH KEYWORDS -bind, callback, event, handler diff --git a/tk8.6/doc/FindPhoto.3 b/tk8.6/doc/FindPhoto.3 deleted file mode 100644 index dc218bf..0000000 --- a/tk8.6/doc/FindPhoto.3 +++ /dev/null @@ -1,283 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Australian National University -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), -'\" Department of Computer Science, -'\" Australian National University. -'\" -.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_PhotoHandle -\fBTk_FindPhoto\fR(\fIinterp, imageName\fR) -.sp -int -\fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ -compRule\fR) -.sp -int -\fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ -zoomX, zoomY, subsampleX, subsampleY, compRule\fR) -.sp -int -\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) -.sp -void -\fBTk_PhotoBlank\fR(\fIhandle\fR) -.sp -int -\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) -.sp -void -\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) -.sp -int -\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) -.SH ARGUMENTS -.AS Tk_PhotoImageBlock window_path -.AP Tcl_Interp *interp in -Interpreter in which image was created and in which error reporting is -to be done. -.AP "const char" *imageName in -Name of the photo image. -.AP Tk_PhotoHandle handle in -Opaque handle identifying the photo image to be affected. -.AP Tk_PhotoImageBlock *blockPtr in -Specifies the address and storage layout of image data. -.AP int x in -Specifies the X coordinate where the top-left corner of the block is -to be placed within the image. -.AP int y in -Specifies the Y coordinate where the top-left corner of the block is -to be placed within the image. -.AP int width in -Specifies the width of the image area to be affected (for -\fBTk_PhotoPutBlock\fR) or the desired image width (for -\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). -.AP int compRule in -Specifies the compositing rule used when combining transparent pixels -in a block of data with a photo image. Must be one of -\fBTK_PHOTO_COMPOSITE_OVERLAY\fR (which puts the block of data over the top -of the existing photo image, with the previous contents showing -through in the transparent bits) or \fBTK_PHOTO_COMPOSITE_SET\fR (which -discards the existing photo image contents in the rectangle covered by -the data block.) -.AP int height in -Specifies the height of the image area to be affected (for -\fBTk_PhotoPutBlock\fR) or the desired image height (for -\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). -.AP int *widthPtr out -Pointer to location in which to store the image width. -.AP int *heightPtr out -Pointer to location in which to store the image height. -.AP int subsampleX in -Specifies the subsampling factor in the X direction for input -image data. -.AP int subsampleY in -Specifies the subsampling factor in the Y direction for input -image data. -.AP int zoomX in -Specifies the zoom factor to be applied in the X direction to pixels -being written to the photo image. -.AP int zoomY in -Specifies the zoom factor to be applied in the Y direction to pixels -being written to the photo image. -.BE -.SH DESCRIPTION -.PP -\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a -particular photo image to the other procedures. The parameter is the -name of the image, that is, the name specified to the \fBimage create -photo\fR command, or assigned by that command if no name was specified. -If \fIimageName\fR does not exist or is not a photo image, -\fBTk_FindPhoto\fR returns NULL. -.PP -\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be -displayed. The call affects an area of the image of size -\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at -coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR, -\fIx\fR, and \fIy\fR must be non-negative. -If part of this area lies outside the -current bounds of the image, the image will be expanded to include the -area, unless the user has specified an explicit image size with the -\fB\-width\fR and/or \fB\-height\fR widget configuration options -(see photo(n)); in that -case the area is silently clipped to the image boundaries. -.PP -The \fIblock\fR parameter is a pointer to a -\fBTk_PhotoImageBlock\fR structure, defined as follows: -.CS -typedef struct { - unsigned char *\fIpixelPtr\fR; - int \fIwidth\fR; - int \fIheight\fR; - int \fIpitch\fR; - int \fIpixelSize\fR; - int \fIoffset\fR[4]; -} \fBTk_PhotoImageBlock\fR; -.CE -The \fIpixelPtr\fR field points to the first pixel, that is, the -top-left pixel in the block. -The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the -block of pixels. The \fIpixelSize\fR field specifies the address -difference between two horizontally adjacent pixels. It should be 4 for -RGB and 2 for grayscale image data. Other values are possible, if the -offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for -red, green and blue data stored in different planes). Using such a -layout is strongly discouraged, though. Due to a bug, it might not work -correctly if an alpha channel is provided. (see the \fBBUGS\fR section -below). The \fIpitch\fR field specifies the -address difference between two vertically adjacent pixels. The -\fIoffset\fR array contains the offsets from the address of a pixel -to the addresses of the bytes containing the red, green, blue and alpha -(transparency) components. If the offsets for red, green and blue are -equal, the image is interpreted as grayscale. If they differ, RGB data -is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data -and 0, 0, 0, 1 for grayscale. It is possible to provide image data -without an alpha channel by setting the offset for alpha to a negative -value and adjusting the \fIpixelSize\fR field accordingly. This use is -discouraged, though (see the \fBBUGS\fR section below). -.PP -The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a -compositing rule that says what to do with transparent pixels. The -value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of -the photo image should show through, and the value -\fBTK_PHOTO_COMPOSITE_SET\fR says that the previous contents of the photo -image should be completely ignored, and the values from the block be -copied directly across. The behavior in Tk8.3 and earlier was -equivalent to having \fBTK_PHOTO_COMPOSITE_OVERLAY\fR as a compositing rule. -.PP -The value given for the \fIwidth\fR and \fIheight\fR parameters to -\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified -in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a -sub-block from the image data supplied. If they are larger, the data -given are replicated (in a tiled fashion) to fill the specified area. -These rules operate independently in the horizontal and vertical -directions. -.PP -\fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot -allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is -returned instead and, if the \fIinterp\fR argument is non-NULL, an -error message is placed in the interpreter's result. -.PP -\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that -the image can be reduced or enlarged for display. The -\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the -image to be reduced by subsampling. -\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image -whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y -coordinates are multiples of \fIsubsampleY\fR. For example, an image -of 512x512 pixels can be reduced to 256x256 by setting -\fIsubsampleX\fR and \fIsubsampleY\fR to 2. -.PP -The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be -enlarged by pixel replication. Each pixel of the (possibly subsampled) -input image will be written to a block \fIzoomX\fR pixels wide and -\fIzoomY\fR pixels high of the displayed image. Subsampling and -zooming can be used together for special effects. -.PP -\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo -image. \fBTk_PhotoGetImage\fR fills -in the structure pointed to by the \fIblockPtr\fR parameter with values -that describe the address and layout of the image data that the -photo image has stored internally. The values are valid -until the image is destroyed or its size is changed. -.PP -It is possible to modify an image by writing directly to the data -the \fIpixelPtr\fR field points to. The size of the image cannot be -changed this way, though. -Also, changes made by writing directly to \fIpixelPtr\fR will not be -immediately visible, but only after a call to -\fBTk_ImageChanged\fR or after an event that causes the interested -widgets to redraw themselves. -For these reasons usually it is preferable to make changes to -a copy of the image data and write it back with -\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. -.PP -\fBTk_PhotoGetImage\fR returns 1 for compatibility with the -corresponding procedure in the old photo widget. -.PP -\fBTk_PhotoBlank\fR blanks the entire area of the -photo image. Blank areas of a photo image are transparent. -.PP -\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be -at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or -height are unchanged if the user has specified an explicit image width -or height with the \fB\-width\fR and/or \fB\-height\fR configuration -options, respectively. -If the image data -are being supplied in many small blocks, it is more efficient to use -\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than -allowing the image to expand in many small increments as image blocks -are supplied. -.PP -\fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot -allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is -returned instead and, if the \fIinterp\fR argument is non-NULL, an -error message is placed in the interpreter's result. -.PP -\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user -had specified the given \fIwidth\fR and \fIheight\fR values to the -\fB\-width\fR and \fB\-height\fR configuration options. A value of -zero for \fIwidth\fR or \fIheight\fR does not change the image's width -or height, but allows the width or height to be changed by subsequent -calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or -\fBTk_PhotoExpand\fR. -.PP -\fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot -allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is -returned instead and, if the \fIinterp\fR argument is non-NULL, an -error message is placed in the interpreter's result. -.PP -\fBTk_PhotoGetSize\fR returns the dimensions of the image in -*\fIwidthPtr\fR and *\fIheightPtr\fR. -.SH PORTABILITY -.PP -In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and -\fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to -compile code that uses the old interface against 8.4 without updating -your code, compile it with the flag --DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against -older versions of Tk will continue to work. -.PP -In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, -\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an -\fIinterp\fR argument or return any result code. If insufficient -memory was available for an image, Tk would panic. This behaviour is -still supported if you compile your extension with the additional flag --DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against -older versions of Tk will continue to work. -.SH BUGS -The \fBTk_PhotoImageBlock\fR structure used to provide image data to -\fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the -data (e.g. separate planes for the red, green, blue and alpha -channels). Unfortunately, the implementation fails to hold this -promise. The problem is that the \fIpixelSize\fR field is -(incorrectly) used to determine whether the image has an alpha channel. -Currently, if the offset for the alpha channel is greater or equal than -\fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is -present and makes the image fully opaque. This means that for layouts -where the channels are separate (or any other exotic layout where -\fIpixelSize\fR has to be smaller than the alpha offset), the alpha -channel will not be read correctly. In order to be on the safe side -if this issue will be corrected in a future release, it is strongly -recommended you always provide alpha data - even if the image has no -transparency - and only use the "standard" layout with a -\fIpixelSize\fR of 2 for grayscale and 4 for RGB data with -\fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively. -.SH CREDITS -.PP -The code for the photo image type was developed by Paul Mackerras, -based on his earlier photo widget code. -.SH KEYWORDS -photo, image diff --git a/tk8.6/doc/FontId.3 b/tk8.6/doc/FontId.3 deleted file mode 100644 index 9d35ae6..0000000 --- a/tk8.6/doc/FontId.3 +++ /dev/null @@ -1,94 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for -fonts -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Font -\fBTk_FontId(\fItkfont\fB)\fR -.sp -\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR -.sp -int -\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR -.SH ARGUMENTS -.AS Tk_FontMetrics *dsPtr -.AP Tk_Font tkfont in -Opaque font token being queried. Must have been returned by a previous -call to \fBTk_GetFont\fR. -.AP Tk_FontMetrics *fmPtr out -Pointer to structure in which the font metrics for \fItkfont\fR will -be stored. See \fBDATA STRUCTURES\fR below for details. -.AP Tcl_DString *dsPtr out -Pointer to an initialized \fBTcl_DString\fR to which the name of the -Postscript font that corresponds to \fItkfont\fR will be appended. -.BE -.SH DESCRIPTION -.PP -Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be -selected into an XGCValues structure in order to construct a graphics -context that can be used to draw text in the specified font. -.PP -\fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the -\fItkfont\fR in pixels and stores those values in the structure pointer to by -\fIfmPtr\fR. These values can be used in computations such as to space -multiple lines of text, to align the baselines of text in different -fonts, and to vertically align text in a given region. See the -documentation for the \fBfont\fR command for definitions of the terms -ascent, descent, and linespace, used in font metrics. -.PP -\fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding -Postscript font name that should be used when printing. The return value -is the size in points of the \fItkfont\fR and the Postscript font name is -appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized -\fBTcl_DString\fR. Given a -.QW reasonable -Postscript printer, the -following screen font families should print correctly: -.IP -\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, -\fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, -\fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, -\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and -\fBZapf Dingbats\fR. -.PP -Any other font families may not print correctly because the computed -Postscript font name may be incorrect or not exist on the printer. -.SH "DATA STRUCTURES" -.PP -The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to -return information about a font and is defined as follows: -.CS -typedef struct Tk_FontMetrics { - int \fIascent\fR; - int \fIdescent\fR; - int \fIlinespace\fR; -} \fBTk_FontMetrics\fR; -.CE -.PP -The \fIascent\fR field is the amount in pixels that the tallest -letter sticks up above the baseline, plus any extra blank space added -by the designer of the font. -.PP -The \fIdescent\fR is the largest amount in pixels that any letter -sticks below the baseline, plus any extra blank space added by the -designer of the font. -.PP -The \fIlinespace\fR is the sum of the ascent and descent. How far -apart two lines of text in the same font should be placed so that none -of the characters in one line overlap any of the characters in the -other line. -.SH "SEE ALSO" -font(n), MeasureChar(3) -.SH KEYWORDS -font, measurement, Postscript diff --git a/tk8.6/doc/FreeXId.3 b/tk8.6/doc/FreeXId.3 deleted file mode 100644 index dd1d141..0000000 --- a/tk8.6/doc/FreeXId.3 +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_FreeXId \- make X resource identifier available for reuse -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_FreeXId(\fIdisplay, id\fB)\fR -.SH ARGUMENTS -.AS Display *display out -.AP Display *display in -Display for which \fIid\fR was allocated. -.AP XID id in -Identifier of X resource (window, font, pixmap, cursor, graphics -context, or colormap) that is no longer in use. -.BE -.SH DESCRIPTION -.PP -The default allocator for resource identifiers provided by Xlib is very -simple-minded and does not allow resource identifiers to be re-used. -If a long-running application reaches the end of the resource id -space, it will generate an X protocol error and crash. -Tk replaces the default id allocator with its own allocator, which -allows identifiers to be reused. -In order for this to work, \fBTk_FreeXId\fR must be called to -tell the allocator about resources that have been freed. -Tk automatically calls \fBTk_FreeXId\fR whenever it frees a -resource, so if you use procedures like \fBTk_GetFont\fR, -\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call -\fBTk_FreeXId\fR. -However, if you allocate resources directly from Xlib, for example -by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR -when you call the corresponding Xlib free procedure, such as -\fBXFreePixmap\fR. -If you do not call \fBTk_FreeXId\fR then the resource identifier will -be lost, which could cause problems if the application runs long enough -to lose all of the available identifiers. -.SH KEYWORDS -resource identifier diff --git a/tk8.6/doc/GeomReq.3 b/tk8.6/doc/GeomReq.3 deleted file mode 100644 index 895f683..0000000 --- a/tk8.6/doc/GeomReq.3 +++ /dev/null @@ -1,92 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \- specify desired geometry or internal border for a window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) -.sp -\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) -.sp -\fBTk_SetInternalBorder\fR(\fItkwin, width\fR) -.sp -\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) -.SH ARGUMENTS -.AS baseHeight clientData -.AP Tk_Window tkwin in -Window for which geometry is being requested. -.AP int reqWidth in -Desired width for \fItkwin\fR, in pixel units. -.AP int reqHeight in -Desired height for \fItkwin\fR, in pixel units. -.AP int minWidth in -Desired minimum requested width for \fItkwin\fR, in pixel units. -.AP int minHeight in -Desired minimum requested height for \fItkwin\fR, in pixel units. -.AP int width in -Space to leave for internal border for \fItkwin\fR, in pixel units. -.AP int left in -Space to leave for left side of internal border for \fItkwin\fR, in pixel units. -.AP int right in -Space to leave for right side of internal border for \fItkwin\fR, in pixel units. -.AP int top in -Space to leave for top side of internal border for \fItkwin\fR, in pixel units. -.AP int bottom in -Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. -.BE -.SH DESCRIPTION -.PP -\fBTk_GeometryRequest\fR is called by widget code to indicate its -preference for the dimensions of a particular window. The arguments -to \fBTk_GeometryRequest\fR are made available to the geometry -manager for the window, which then decides on the actual geometry -for the window. Although geometry managers generally try to satisfy -requests made to \fBTk_GeometryRequest\fR, there is no guarantee that -this will always be possible. Widget code should not assume that -a geometry request will be satisfied until it receives a -\fBConfigureNotify\fR event indicating that the geometry change has -occurred. Widget code should never call procedures like -\fBTk_ResizeWindow\fR directly. Instead, it should invoke -\fBTk_GeometryRequest\fR and leave the final geometry decisions to -the geometry manager. -.PP -If \fItkwin\fR is a top-level window, then the geometry information -will be passed to the window manager using the standard ICCCM protocol. -.PP -\fBTk_SetInternalBorder\fR is called by widget code to indicate that -the widget has an internal border. This means that the widget draws -a decorative border inside the window instead of using the standard -X borders, which are external to the window's area. For example, -internal borders are used to draw 3-D effects. \fIWidth\fR -specifies the width of the border in pixels. Geometry managers will -use this information to avoid placing any children of \fItkwin\fR -overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area. -.PP -\fBTk_SetInternalBorderEx\fR works like \fBTk_SetInternalBorder\fR -but lets you specify different widths for different sides of the window. -.PP -\fBTk_SetMinimumRequestSize\fR is called by widget code to indicate -that a geometry manager should request at least this size for the -widget. This allows a widget to have some control over its size when -a propagating geometry manager is used inside it. -.PP -The information specified in calls to \fBTk_GeometryRequest\fR, -\fBTk_SetMinimumRequestSize\fR, \fBTk_SetInternalBorder\fR and -\fBTk_SetInternalBorderEx\fR can be retrieved using the macros -\fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, \fBTk_MinReqWidth\fR, -\fBTk_MinReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_InternalBorderLeft\fR, -\fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and -\fBTk_InternalBorderBottom\fR. -See the \fBTk_WindowId\fR manual entry for details. -.SH KEYWORDS -geometry, request diff --git a/tk8.6/doc/GetAnchor.3 b/tk8.6/doc/GetAnchor.3 deleted file mode 100644 index 6526772..0000000 --- a/tk8.6/doc/GetAnchor.3 +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR -.sp -int -\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR -.sp -const char * -\fBTk_NameOfAnchor(\fIanchor\fB)\fR -.SH ARGUMENTS -.AS "Tk_Anchor" *anchorPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting, or NULL. -.AP Tcl_Obj *objPtr in/out -String value contains name of anchor point: -.QW \fBn\fR , -.QW \fBne\fR , -.QW \fBe\fR , -.QW \fBse\fR , -.QW \fBs\fR , -.QW \fBsw\fR , -.QW \fBw\fR , -.QW \fBnw\fR , -or -.QW \fBcenter\fR ; -internal rep will be modified to cache corresponding Tk_Anchor. In the -case of -.QW \fBcenter\fR -on input, a non-empty abbreviation of it may also be used on input. -.AP "const char" *string in -Same as \fIobjPtr\fR except description of anchor point is passed as -a string. -.AP int *anchorPtr out -Pointer to location in which to store anchor position corresponding to -\fIobjPtr\fR or \fIstring\fR. -.AP Tk_Anchor anchor in -Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position -(enumerated type \fBTk_Anchor\fR) -corresponding to \fIobjPtr\fR's value. The result will be one of -\fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR, -\fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR, -or \fBTK_ANCHOR_CENTER\fR. -Anchor positions are typically used for indicating a point on an object -that will be used to position the object, e.g. \fBTK_ANCHOR_N\fR means -position the top center point of the object at a particular place. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIstring\fR does not contain a valid anchor position -or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, -\fI*anchorPtr\fR is unmodified, and an error message is -stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. -\fBTk_GetAnchorFromObj\fR caches information about the return -value in \fIobjPtr\fR, which speeds up future calls to -\fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR. -.PP -\fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except -that the description of the anchor is specified with a string instead -of an object. This prevents \fBTk_GetAnchor\fR from caching the -return value, so \fBTk_GetAnchor\fR is less efficient than -\fBTk_GetAnchorFromObj\fR. -.PP -\fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR. -Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a -statically-allocated string corresponding to \fIanchor\fR. -If \fIanchor\fR is not a legal anchor value, then -.QW "unknown anchor position" -is returned. -.SH KEYWORDS -anchor position diff --git a/tk8.6/doc/GetBitmap.3 b/tk8.6/doc/GetBitmap.3 deleted file mode 100644 index c4ac44e..0000000 --- a/tk8.6/doc/GetBitmap.3 +++ /dev/null @@ -1,296 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Pixmap -\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -Pixmap -\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR -.sp -Pixmap -\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR -.sp -int -\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR -.sp -const char * -\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR -.sp -\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR -.sp -\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR -.sp -\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR -.SH ARGUMENTS -.AS "unsigned long" *pixelPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting; if NULL then no error message -is left after errors. -.AP Tk_Window tkwin in -Token for window in which the bitmap will be used. -.AP Tcl_Obj *objPtr in/out -String value describes desired bitmap; internal rep will be -modified to cache pointer to corresponding Pixmap. -.AP "const char" *info in -Same as \fIobjPtr\fR except description of bitmap is passed as a string and -resulting Pixmap is not cached. -.AP "const char" *name in -Name for new bitmap to be defined. -.AP "const void" *source in -Data for bitmap, in standard bitmap format. -Must be stored in static memory whose value will never change. -.AP "int" width in -Width of bitmap. -.AP "int" height in -Height of bitmap. -.AP "int" *widthPtr out -Pointer to word to fill in with \fIbitmap\fR's width. -.AP "int" *heightPtr out -Pointer to word to fill in with \fIbitmap\fR's height. -.AP Display *display in -Display for which \fIbitmap\fR was allocated. -.AP Pixmap bitmap in -Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or -\fBTk_GetBitmap\fR. -.BE -.SH DESCRIPTION -.PP -These procedures manage a collection of bitmaps (one-plane pixmaps) -being used by an application. The procedures allow bitmaps to be -re-used efficiently, thereby avoiding server overhead, and also -allow bitmaps to be named with character strings. -.PP -\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap -that matches the description in \fIobjPtr\fR and is suitable for use -in \fItkwin\fR. It re-uses an existing bitmap, if possible, and -creates a new one otherwise. \fIObjPtr\fR's value must have one -of the following forms: -.TP 20 -\fB@\fIfileName\fR -\fIFileName\fR must be the name of a file containing a bitmap -description in the standard X11 format. -.TP 20 -\fIname\fR -\fIName\fR must be the name of a bitmap defined previously with -a call to \fBTk_DefineBitmap\fR. The following names are pre-defined -by Tk: -.RS -.TP 12 -\fBerror\fR -The international -.QW don't -symbol: a circle with a diagonal line across it. -.TP 12 -\fBgray75\fR -75% gray: a checkerboard pattern where three out of four bits are on. -.TP 12 -\fBgray50\fR -50% gray: a checkerboard pattern where every other bit is on. -.TP 12 -\fBgray25\fR -25% gray: a checkerboard pattern where one out of every four bits is on. -.TP 12 -\fBgray12\fR -12.5% gray: a pattern where one-eighth of the bits are on, consisting of -every fourth pixel in every other row. -.TP 12 -\fBhourglass\fR -An hourglass symbol. -.TP 12 -\fBinfo\fR -A large letter -.QW i . -.TP 12 -\fBquesthead\fR -The silhouette of a human head, with a question mark in it. -.TP 12 -\fBquestion\fR -A large question-mark. -.TP 12 -\fBwarning\fR -A large exclamation point. -.PP -In addition, the following pre-defined names are available only on the -\fBMacintosh\fR platform: -.TP 12 -\fBdocument\fR -A generic document. -.TP 12 -\fBstationery\fR -Document stationery. -.TP 12 -\fBedition\fR -The \fIedition\fR symbol. -.TP 12 -\fBapplication\fR -Generic application icon. -.TP 12 -\fBaccessory\fR -A desk accessory. -.TP 12 -\fBfolder\fR -Generic folder icon. -.TP 12 -\fBpfolder\fR -A locked folder. -.TP 12 -\fBtrash\fR -A trash can. -.TP 12 -\fBfloppy\fR -A floppy disk. -.TP 12 -\fBramdisk\fR -A floppy disk with chip. -.TP 12 -\fBcdrom\fR -A cd disk icon. -.TP 12 -\fBpreferences\fR -A folder with prefs symbol. -.TP 12 -\fBquerydoc\fR -A database document icon. -.TP 12 -\fBstop\fR -A stop sign. -.TP 12 -\fBnote\fR -A face with balloon words. -.TP 12 -\fBcaution\fR -A triangle with an exclamation point. -.RE -.LP -Under normal conditions, \fBTk_AllocBitmapFromObj\fR -returns an identifier for the requested bitmap. If an error -occurs in creating the bitmap, such as when \fIobjPtr\fR refers -to a non-existent file, then \fBNone\fR is returned and an error -message is left in \fIinterp\fR's result if \fIinterp\fR is not -NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return -value in \fIobjPtr\fR, which speeds up future calls to procedures -such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR. -.PP -\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except -that the description of the bitmap is specified with a string instead -of an object. This prevents \fBTk_GetBitmap\fR from caching the -return value, so \fBTk_GetBitmap\fR is less efficient than -\fBTk_AllocBitmapFromObj\fR. -.PP -\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given -the window and description used to create the bitmap. -\fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap -must already have been created with a previous call to -\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_DefineBitmap\fR associates a name with -in-memory bitmap data so that the name can be used in later -calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The \fInameId\fR -argument gives a name for the bitmap; it must not previously -have been used in a call to \fBTk_DefineBitmap\fR. -The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR -describe the bitmap. -\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs -(e.g. a bitmap named \fInameId\fR has already been defined) then -\fBTCL_ERROR\fR is returned and an error message is left in -interpreter \fIinterp\fR's result. -Note: \fBTk_DefineBitmap\fR expects the memory pointed to by -\fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make -a private copy of this memory, but uses the bytes pointed to -by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or -\fBTk_GetBitmap\fR. -.PP -Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a -bitmap file directly into a C program and then referencing -the variables defined by the file. -For example, suppose there exists a file \fBstip.bitmap\fR, -which was created by the \fBbitmap\fR program and contains -a stipple pattern. -The following code uses \fBTk_DefineBitmap\fR to define a -new bitmap named \fBfoo\fR: -.CS -Pixmap bitmap; -#include "stip.bitmap" -Tk_DefineBitmap(interp, "foo", stip_bits, - stip_width, stip_height); -\&... -bitmap = Tk_GetBitmap(interp, tkwin, "foo"); -.CE -This code causes the bitmap file to be read -at compile-time and incorporates the bitmap information into -the program's executable image. The same bitmap file could be -read at run-time using \fBTk_GetBitmap\fR: -.CS -Pixmap bitmap; -bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); -.CE -The second form is a bit more flexible (the file could be modified -after the program has been compiled, or a different string could be -provided to read a different file), but it is a little slower and -requires the bitmap file to exist separately from the program. -.PP -Tk maintains a database of all the bitmaps that are currently in use. -Whenever possible, it will return an existing bitmap rather -than creating a new one. -When a bitmap is no longer used, Tk will release it automatically. -This approach can substantially reduce server overhead, so -\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally -be used in preference to Xlib procedures like \fBXReadBitmapFile\fR. -.PP -The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR -are shared, so callers should never modify them. -If a bitmap must be modified dynamically, then it should be -created by calling Xlib procedures such as \fBXReadBitmapFile\fR -or \fBXCreatePixmap\fR directly. -.PP -The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of -\fBTk_GetBitmap\fR. -Given an X Pixmap argument, it returns the textual description that was -passed to \fBTk_GetBitmap\fR when the bitmap was created. -\fIBitmap\fR must have been the return value from a previous -call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. -.PP -\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR -argument in the words pointed to by the \fIwidthPtr\fR and -\fIheightPtr\fR arguments. As with \fBTk_NameOfBitmap\fR, -\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or -\fBTk_GetBitmap\fR. -.PP -When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or -\fBTk_FreeBitmap\fR should be called to release it. -For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified -with the same information used to create it; for -\fBTk_FreeBitmap\fR the bitmap to release is specified -with its Pixmap token. -There should be exactly one call to \fBTk_FreeBitmapFromObj\fR -or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or -\fBTk_GetBitmap\fR. -.SH BUGS -.PP -In determining whether an existing bitmap can be used to satisfy -a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR -consider only the immediate value of the string description. For -example, when a file name is passed to \fBTk_GetBitmap\fR, -\fBTk_GetBitmap\fR will assume it is safe to re-use an existing -bitmap created from the same file name: it will not check to -see whether the file itself has changed, or whether the current -directory has changed, thereby causing the name to refer to -a different file. -.SH KEYWORDS -bitmap, pixmap diff --git a/tk8.6/doc/GetCapStyl.3 b/tk8.6/doc/GetCapStyl.3 deleted file mode 100644 index 28f1a1c..0000000 --- a/tk8.6/doc/GetCapStyl.3 +++ /dev/null @@ -1,64 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR -.sp -const char * -\fBTk_NameOfCapStyle(\fIcap\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *capPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "const char" *string in -String containing name of cap style \- one of -.QW \fBbutt\fR , -.QW \fBprojecting\fR , -or -.QW \fBround\fR -\- or a unique abbreviation of one. -.AP int *capPtr out -Pointer to location in which to store X cap style corresponding to -\fIstring\fR. -.AP int cap in -Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style -corresponding to \fIstring\fR. -This will be one of the values -\fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. -Cap styles are typically used in X graphics contexts to indicate -how the end-points of lines should be capped. -See the X documentation for information on what each style -implies. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIstring\fR does not contain a valid cap style -or an abbreviation of one of these names, then an error message is -stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and -\fI*capPtr\fR is unmodified. -.PP -\fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. -Given a cap style such as \fBCapButt\fR it returns a -statically-allocated string corresponding to \fIcap\fR. -If \fIcap\fR is not a legal cap style, then -.QW "unknown cap style" -is returned. -.SH KEYWORDS -butt, cap style, projecting, round diff --git a/tk8.6/doc/GetClrmap.3 b/tk8.6/doc/GetClrmap.3 deleted file mode 100644 index 9e6da12..0000000 --- a/tk8.6/doc/GetClrmap.3 +++ /dev/null @@ -1,77 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Colormap -\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR -.sp -\fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR -.sp -\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR -.SH ARGUMENTS -.AS "Colormap" colormap -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which colormap will be used. -.AP "const char" *string in -Selects a colormap: either \fBnew\fR or the name of a window -with the same screen and visual as \fItkwin\fR. -.AP Display *display in -Display for which \fIcolormap\fR was allocated. -.AP Colormap colormap in -Colormap to free or preserve; must have been returned by a previous -call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR. -.BE -.SH DESCRIPTION -.PP -These procedures are used to manage colormaps. -\fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR. -If its \fIstring\fR argument is \fBnew\fR then a new colormap is -created; otherwise \fIstring\fR must be the name of another window -with the same screen and visual as \fItkwin\fR, and the colormap from that -window is returned. -If \fIstring\fR does not make sense, or if it refers to a window on -a different screen from \fItkwin\fR or with -a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns -\fBNone\fR and leaves an error message in \fIinterp\fR's result. -.PP -\fBTk_PreserveColormap\fR increases the internal reference count for a -colormap previously returned by \fBTk_GetColormap\fR, which allows the -colormap to be stored in several locations without knowing which order -they will be released. -.PP -\fBTk_FreeColormap\fR should be called when a colormap returned by -\fBTk_GetColormap\fR is no longer needed. -Tk maintains a reference count for each colormap returned by -\fBTk_GetColormap\fR, so there should eventually be one call to -\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each -call to \fBTk_PreserveColormap\fR. -When a colormap's reference count becomes zero, Tk releases the -X colormap. -.PP -\fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that -a new colormap created by \fBTk_GetVisual\fR may later be returned -by \fBTk_GetColormap\fR. -The reference counting mechanism for colormaps includes both procedures, -so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR -to release the colormap. -If \fBTk_GetColormap\fR is called with a \fIstring\fR value of -\fBnew\fR then the resulting colormap will never -be returned by \fBTk_GetVisual\fR; however, it can be used in other -windows by calling \fBTk_GetColormap\fR with the original window's -name as \fIstring\fR. -.SH KEYWORDS -colormap, visual diff --git a/tk8.6/doc/GetColor.3 b/tk8.6/doc/GetColor.3 deleted file mode 100644 index 15254aa..0000000 --- a/tk8.6/doc/GetColor.3 +++ /dev/null @@ -1,176 +0,0 @@ -'\" -'\" Copyright (c) 1990-1991 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -XColor * -\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -XColor * -\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR -.sp -XColor * -\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR -.sp -XColor * -\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR -.sp -const char * -\fBTk_NameOfColor(\fIcolorPtr\fB)\fR -.sp -GC -\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR -.sp -\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR -.sp -\fBTk_FreeColor(\fIcolorPtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *colorPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which color will be used. -.AP Tcl_Obj *objPtr in/out -String value describes desired color; internal rep will be -modified to cache pointer to corresponding (XColor *). -.AP char *name in -Same as \fIobjPtr\fR except description of color is passed as a string and -resulting (XColor *) is not cached. -.AP XColor *prefPtr in -Indicates red, green, and blue intensities of desired -color. -.AP XColor *colorPtr in -Pointer to X color information. Must have been allocated by previous -call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or -\fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR. -.AP Drawable drawable in -Drawable in which the result graphics context will be used. Must have -same screen and depth as the window for which the color was allocated. -.BE -.SH DESCRIPTION -.PP -These procedures manage the colors being used by a Tk application. -They allow colors to be shared whenever possible, so that colormap -space is preserved, and they pick closest available colors when -colormap space is exhausted. -.PP -Given a textual description of a color, \fBTk_AllocColorFromObj\fR -locates a pixel value that may be used to render the color -in a particular window. The desired color is specified with a -value whose string value must have one of the following forms: -.TP 20 -\fIcolorname\fR -Any of the valid textual names for a color defined in the -server's color database file, such as \fBred\fR or \fBPeachPuff\fR. -.TP 20 -\fB#\fIRGB\fR -.TP 20 -\fB#\fIRRGGBB\fR -.TP 20 -\fB#\fIRRRGGGBBB\fR -.TP 20 -\fB#\fIRRRRGGGGBBBB\fR -A numeric specification of the red, green, and blue intensities -to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR -represents a single hexadecimal digit. The four forms permit -colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. -When fewer than 16 bits are provided for each color, they represent -the most significant bits of the color, while the lower unfilled -bits will be repeatedly replicated from the available higher bits. -For example, #3a7 is the same as #3333aaaa7777. -.PP -\fBTk_AllocColorFromObj\fR returns a pointer to -an XColor structure; the structure indicates the exact intensities of -the allocated color (which may differ slightly from those requested, -depending on the limitations of the screen) and a pixel value -that may be used to draw with the color in \fItkwin\fR. -If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown -color name) then NULL is returned and an error message is stored in -\fIinterp\fR's result if \fIinterp\fR is not NULL. -If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR -will use the closest existing color in the colormap. -\fBTk_AllocColorFromObj\fR caches information about -the return value in \fIobjPtr\fR, which speeds up future calls to procedures -such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR. -.PP -\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except -that the description of the color is specified with a string instead -of a value. This prevents \fBTk_GetColor\fR from caching the -return value, so \fBTk_GetColor\fR is less efficient than -\fBTk_AllocColorFromObj\fR. -.PP -\fBTk_GetColorFromObj\fR returns the token for an existing color, given -the window and description used to create the color. -\fBTk_GetColorFromObj\fR does not actually create the color; the color -must already have been created with a previous call to -\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that -the desired color is indicated with the \fIred\fR, \fIgreen\fR, and -\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR. -.PP -This package maintains a database -of all the colors currently in use. -If the same color is requested multiple times from -\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different -windows), or if the -same intensities are requested multiple times from -\fBTk_GetColorByValue\fR, then existing pixel values will -be re-used. Re-using an existing pixel avoids any interaction -with the window server, which makes the allocation much more -efficient. These procedures also provide a portable interface that -works across all platforms. For this reason, you should generally use -\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR -instead of lower level procedures like \fBXAllocColor\fR. -.PP -Since different calls to this package -may return the same shared -pixel value, callers should never change the color of a pixel -returned by the procedures. -If you need to change a color value dynamically, you should use -\fBXAllocColorCells\fR to allocate the pixel value for the color. -.PP -The procedure \fBTk_NameOfColor\fR is roughly the inverse of -\fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created -by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value -is the string that was used to create the -color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR, -or by any other mechanism, then the return value is a string -that could be passed to \fBTk_GetColor\fR to return the same -color. Note: the string returned by \fBTk_NameOfColor\fR is -only guaranteed to persist until the next call to -\fBTk_NameOfColor\fR. -.PP -\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR -field is the pixel allocated for \fIcolorPtr\fR and whose other fields -all have default values. -This provides an easy way to do basic drawing with a color. -The graphics context is cached with the color and will exist only as -long as \fIcolorPtr\fR exists; it is freed when the last reference -to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR. -.PP -When a color is no longer needed \fBTk_FreeColorFromObj\fR or -\fBTk_FreeColor\fR should be called to release it. -For \fBTk_FreeColorFromObj\fR the color to release is specified -with the same information used to create it; for -\fBTk_FreeColor\fR the color to release is specified -with a pointer to its XColor structure. -There should be exactly one call to \fBTk_FreeColorFromObj\fR -or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR, -\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR. -.SH KEYWORDS -color, intensity, value, pixel value diff --git a/tk8.6/doc/GetCursor.3 b/tk8.6/doc/GetCursor.3 deleted file mode 100644 index 403c05e..0000000 --- a/tk8.6/doc/GetCursor.3 +++ /dev/null @@ -1,231 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Cursor -\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -Tk_Cursor -\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR -.sp -Tk_Cursor -\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR -.sp -Tk_Cursor -\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR -.sp -const char * -\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR -.sp -\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR -.sp -\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR -.SH ARGUMENTS -.AS "unsigned long" *pixelPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which the cursor will be used. -.AP Tcl_Obj *objPtr in/out -Description of cursor; see below for possible values. Internal rep will be -modified to cache pointer to corresponding Tk_Cursor. -.AP char *name in -Same as \fIobjPtr\fR except description of cursor is passed as a string and -resulting Tk_Cursor is not cached. -.AP "const char" *source in -Data for cursor cursor, in standard cursor format. -.AP "const char" *mask in -Data for mask cursor, in standard cursor format. -.AP "int" width in -Width of \fIsource\fR and \fImask\fR. -.AP "int" height in -Height of \fIsource\fR and \fImask\fR. -.AP "int" xHot in -X-location of cursor hot-spot. -.AP "int" yHot in -Y-location of cursor hot-spot. -.AP Tk_Uid fg in -Textual description of foreground color for cursor. -.AP Tk_Uid bg in -Textual description of background color for cursor. -.AP Display *display in -Display for which \fIcursor\fR was allocated. -.AP Tk_Cursor cursor in -Opaque Tk identifier for cursor. If passed to \fBTk_FreeCursor\fR, must -have been returned by some previous call to \fBTk_GetCursor\fR or -\fBTk_GetCursorFromData\fR. -.BE -.SH DESCRIPTION -.PP -These procedures manage a collection of cursors -being used by an application. The procedures allow cursors to be -re-used efficiently, thereby avoiding server overhead, and also -allow cursors to be named with character strings. -.PP -\fBTk_AllocCursorFromObj\fR takes as argument an object describing a -cursor, and returns an opaque Tk identifier for a cursor corresponding -to the description. It re-uses an existing cursor if possible and -creates a new one otherwise. \fBTk_AllocCursorFromObj\fR caches -information about the return value in \fIobjPtr\fR, which speeds up -future calls to procedures such as \fBTk_AllocCursorFromObj\fR and -\fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, -such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR -is returned and an error message will be stored in \fIinterp\fR's result -if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl -list with one of the following forms: -.TP -\fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] -\fIName\fR is the name of a cursor in the standard X cursor cursor, -i.e., any of the names defined in \fBcursorcursor.h\fR, without -the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, -or \fBleft_ptr\fR. Appendix B of -.QW "The X Window System" -by Scheifler & Gettys has illustrations showing what each of these -cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both -specified, they give the foreground and background colors to use -for the cursor (any of the forms acceptable to \fBTk_GetColor\fR -may be used). If only \fIfgColor\fR is specified, then there -will be no background color: the background will be transparent. -If no colors are specified, then the cursor -will use black for its foreground color and white for its background -color. -.RS -.PP -The Macintosh version of Tk supports all of the X cursors and -will also accept any of the standard Mac cursors -including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and -\fBarrow\fR. In addition, Tk will load Macintosh cursor resources of -the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the -name of the resource. The application and all its open -dynamic library's resource files will be searched for the named -cursor. If there are conflicts color cursors will always be loaded -in preference to black and white cursors. -.RE -.TP -\fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR -In this form, \fIsourceName\fR and \fImaskName\fR are the names of -files describing cursors for the cursor's source bits and mask. -Each file must be in standard X11 cursor format. -\fIFgColor\fR and \fIbgColor\fR -indicate the colors to use for the -cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This -form of the command will not work on Macintosh or Windows computers. -.TP -\fB@\fIsourceName\0fgColor\fR -This form is similar to the one above, except that the source is -used as mask also. This means that the cursor's background is -transparent. This form of the command will not work on Macintosh -or Windows computers. -.TP -\fB@\fIsourceName\fR -This form only works on Windows, and will load a Windows system -cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in -\fIsourceName\fR. -.PP -\fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except -that the description of the cursor is specified with a string instead -of an object. This prevents \fBTk_GetCursor\fR from caching the -return value, so \fBTk_GetCursor\fR is less efficient than -\fBTk_AllocCursorFromObj\fR. -.PP -\fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given -the window and description used to create the cursor. -\fBTk_GetCursorFromObj\fR does not actually create the cursor; the cursor -must already have been created with a previous call to -\fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_GetCursorFromData\fR allows cursors to be created from -in-memory descriptions of their source and mask cursors. \fISource\fR -points to standard cursor data for the cursor's source bits, and -\fImask\fR points to standard cursor data describing -which pixels of \fIsource\fR are to be drawn and which are to be -considered transparent. \fIWidth\fR and \fIheight\fR give the -dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the -location of the cursor's hot-spot (the point that is reported when -an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's -foreground and background colors textually (any of the forms -suitable for \fBTk_GetColor\fR may be used). Typically, the -arguments to \fBTk_GetCursorFromData\fR are created by including -a cursor file directly into the source code for a program, as in -the following example: -.CS -Tk_Cursor cursor; -#include "source.cursor" -#include "mask.cursor" -cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, - mask_bits, source_width, source_height, source_x_hot, - source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue")); -.CE -.PP -Under normal conditions \fBTk_GetCursorFromData\fR -will return an identifier for the requested cursor. If an error -occurs in creating the cursor then \fBNone\fR is returned and an error -message will be stored in \fIinterp\fR's result. -.PP -\fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and -\fBTk_GetCursorFromData\fR maintain a -database of all the cursors they have created. Whenever possible, -a call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or -\fBTk_GetCursorFromData\fR will -return an existing cursor rather than creating a new one. This -approach can substantially reduce server overhead, so the Tk -procedures should generally be used in preference to Xlib procedures -like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which -create a new cursor on each call. The Tk procedures are also more -portable than the lower-level X procedures. -.PP -The procedure \fBTk_NameOfCursor\fR is roughly the inverse of -\fBTk_GetCursor\fR. If its \fIcursor\fR argument was created -by \fBTk_GetCursor\fR, then the return value is the \fIname\fR -argument that was passed to \fBTk_GetCursor\fR to create the -cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, -or by any other mechanism, then the return value is a hexadecimal string -giving the X identifier for the cursor. -Note: the string returned by \fBTk_NameOfCursor\fR is -only guaranteed to persist until the next call to -\fBTk_NameOfCursor\fR. Also, this call is not portable except for -cursors returned by \fBTk_GetCursor\fR. -.PP -When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, -or \fBTk_GetCursorFromData\fR -is no longer needed, \fBTk_FreeCursorFromObj\fR or -\fBTk_FreeCursor\fR should be called to release it. -For \fBTk_FreeCursorFromObj\fR the cursor to release is specified -with the same information used to create it; for -\fBTk_FreeCursor\fR the cursor to release is specified -with its Tk_Cursor token. -There should be exactly one call to \fBTk_FreeCursor\fR for -each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, -or \fBTk_GetCursorFromData\fR. -.SH BUGS -.PP -In determining whether an existing cursor can be used to satisfy -a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, -and \fBTk_GetCursorFromData\fR -consider only the immediate values of their arguments. For -example, when a file name is passed to \fBTk_GetCursor\fR, -\fBTk_GetCursor\fR will assume it is safe to re-use an existing -cursor created from the same file name: it will not check to -see whether the file itself has changed, or whether the current -directory has changed, thereby causing the name to refer to -a different file. Similarly, \fBTk_GetCursorFromData\fR assumes -that if the same \fIsource\fR pointer is used in two different calls, -then the pointers refer to the same data; it does not check to -see if the actual data values have changed. -.SH KEYWORDS -cursor diff --git a/tk8.6/doc/GetDash.3 b/tk8.6/doc/GetDash.3 deleted file mode 100644 index d1eeb70..0000000 --- a/tk8.6/doc/GetDash.3 +++ /dev/null @@ -1,82 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetDash \- convert from string to valid dash structure. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR - -int -\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR) -.fi -.SH ARGUMENTS -.AS Tk_Dash *dashPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "const char" *string in -Textual value to be converted. -.AP Tk_Dash *dashPtr out -Points to place to store the dash pattern -value converted from \fIstring\fR. Must not be NULL. -.BE -.SH DESCRIPTION -.PP -These procedure parses the string and fills in the result in the -Tk_Dash structure. The string can be a list of integers or a -character string containing only -.QW \fB.,-_\fR -and spaces. If all -goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored -in the variable pointed to by \fIdashPtr\fR. -If \fIstring\fR does not have the -proper syntax then \fBTCL_ERROR\fR is returned, an error message is left -in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. -.PP -The first possible syntax is a list of integers. Each element -represents the number of pixels of a line segment. Only the odd -segments are drawn using the -.QW outline -color. The other segments are drawn transparent. -.PP -The second possible syntax is a character list containing only -5 possible characters -.QW "\fB.,-_ \fR" . -The space can be used -to enlarge the space between other line elements, and can not -occur in the first position of the string. Some examples: -.PP -.CS - \-dash . = \-dash {2 4} - \-dash - = \-dash {6 4} - \-dash -. = \-dash {6 4 2 4} - \-dash -.. = \-dash {6 4 2 4 2 4} - \-dash {. } = \-dash {2 8} - \-dash , = \-dash {4 4} -.CE -.PP -The main difference between this syntax and the numeric is that it -is shape-conserving. This means that all values in the dash -list will be multiplied by the line width before display. This -ensures that -.QW . -will always be displayed as a dot and -.QW - -always as a dash regardless of the line width. -.PP -On systems where only a limited set of dash patterns, the dash -pattern will be displayed as the most close dash pattern that -is available. For example, on Windows only the first 4 of the -above examples are available; the last 2 examples will be -displayed identically to the first one. -.SH "SEE ALSO" -canvas(n), Tk_CreateItemType(3) -.SH KEYWORDS -dash, conversion diff --git a/tk8.6/doc/GetFont.3 b/tk8.6/doc/GetFont.3 deleted file mode 100644 index 0504916..0000000 --- a/tk8.6/doc/GetFont.3 +++ /dev/null @@ -1,110 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Font -\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -Tk_Font -\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR -.sp -Tk_Font -\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR -.sp -const char * -\fBTk_NameOfFont(\fItkfont\fB)\fR -.sp -Tk_Font -\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR -.sp -void -\fBTk_FreeFont(\fItkfont\fB)\fR -.SH ARGUMENTS -.AS "const char" *tkfont -.AP "Tcl_Interp" *interp in -Interpreter to use for error reporting. If \fBNULL\fR, then no error -messages are left after errors. -.AP Tk_Window tkwin in -Token for window in which font will be used. -.AP Tcl_Obj *objPtr in/out -Gives name or description of font. See documentation -for the \fBfont\fR command for details on acceptable formats. -Internal rep will be modified to cache corresponding Tk_Font. -.AP "const char" *string in -Same as \fIobjPtr\fR except description of font is passed as a string and -resulting Tk_Font is not cached. -.AP Tk_Font tkfont in -Opaque font token. -.BE -.SH DESCRIPTION -.PP -\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and -returns a token that represents the font. The return value can be used -in subsequent calls to procedures such as \fBTk_GetFontMetrics\fR, -\fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR. The Tk_Font token -will remain valid until -\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. -\fIObjPtr\fR can contain either a symbolic name or a font description; see -the documentation for the \fBfont\fR command for a description of the -valid formats. If \fBTk_AllocFontFromObj\fR is unsuccessful (because, -for example, \fIobjPtr\fR did not contain a valid font specification) then it -returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result -if \fIinterp\fR is not \fBNULL\fR. \fBTk_AllocFontFromObj\fR caches -information about the return -value in \fIobjPtr\fR, which speeds up future calls to procedures -such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR. -.PP -\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except -that the description of the font is specified with a string instead -of an object. This prevents \fBTk_GetFont\fR from caching the -matching Tk_Font, so \fBTk_GetFont\fR is less efficient than -\fBTk_AllocFontFromObj\fR. -.PP -\fBTk_GetFontFromObj\fR returns the token for an existing font, given -the window and description used to create the font. -\fBTk_GetFontFromObj\fR does not actually create the font; the font -must already have been created with a previous call to -\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain -a database of all fonts they have allocated. If -the same font is requested multiple times (e.g. by different -windows or for different purposes), then a single Tk_Font will be -shared for all uses. The underlying resources will be freed automatically -when no-one is using the font anymore. -.PP -The procedure \fBTk_NameOfFont\fR is roughly the inverse of -\fBTk_GetFont\fR. Given a \fItkfont\fR that was created by -\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is -the \fIstring\fR argument that was -passed to \fBTk_GetFont\fR to create the font. The string returned by -\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR -is deleted. The caller must not modify this string. -.PP -When a font is no longer needed, -\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to -release it. For \fBTk_FreeFontFromObj\fR the font to release is specified -with the same information used to create it; for -\fBTk_FreeFont\fR the font to release is specified -with its Tk_Font token. There should be -exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR -for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. -.SH "SEE ALSO" -Tk_FontId(3) -.SH KEYWORDS -font diff --git a/tk8.6/doc/GetGC.3 b/tk8.6/doc/GetGC.3 deleted file mode 100644 index 44e06fb..0000000 --- a/tk8.6/doc/GetGC.3 +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetGC 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -GC -\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) -.sp -\fBTk_FreeGC(\fIdisplay, gc\fR) -.SH ARGUMENTS -.AS "unsigned long" valueMask -.AP Tk_Window tkwin in -Token for window in which the graphics context will be used. -.AP "unsigned long" valueMask in -Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) -indicating which fields of \fI*valuePtr\fR are valid. -.AP XGCValues *valuePtr in -Pointer to structure describing the desired values for the -graphics context. -.AP Display *display in -Display for which \fIgc\fR was allocated. -.AP GC gc in -X identifier for graphics context that is no longer needed. -Must have been allocated by \fBTk_GetGC\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts -being used by an application. The procedures allow graphics contexts to be -shared, thereby avoiding the server overhead that would be incurred -if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments -describing the desired graphics context and returns an X identifier -for a GC that fits the description. The graphics context that is returned -will have default values in all of the fields not specified explicitly -by \fIvalueMask\fR and \fIvaluePtr\fR. -.PP -\fBTk_GetGC\fR maintains a -database of all the graphics contexts it has created. Whenever possible, -a call to \fBTk_GetGC\fR will -return an existing graphics context rather than creating a new one. This -approach can substantially reduce server overhead, so \fBTk_GetGC\fR -should generally be used in preference to the Xlib procedure -\fBXCreateGC\fR, which creates a new graphics context on each call. -.PP -Since the return values of \fBTk_GetGC\fR -are shared, callers should never modify the graphics contexts -returned by \fBTk_GetGC\fR. -If a graphics context must be modified dynamically, then it should be -created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR. -.PP -When a graphics context -is no longer needed, \fBTk_FreeGC\fR should be called to release it. -There should be exactly one call to \fBTk_FreeGC\fR for -each call to \fBTk_GetGC\fR. -When a graphics context is no longer in use anywhere (i.e. it has -been freed as many times as it has been gotten) \fBTk_FreeGC\fR -will release it to the X server and delete it from the database. -.SH KEYWORDS -graphics context diff --git a/tk8.6/doc/GetHINSTANCE.3 b/tk8.6/doc/GetHINSTANCE.3 deleted file mode 100644 index de38051..0000000 --- a/tk8.6/doc/GetHINSTANCE.3 +++ /dev/null @@ -1,22 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetHINSTANCE \- retrieve the global application instance handle -.SH SYNOPSIS -.nf -\fB#include <tkPlatDecls.h>\fR -.sp -HINSTANCE -\fBTk_GetHINSTANCE\fR() -.BE -.SH DESCRIPTION -.PP -\fBTk_GetHINSTANCE\fR returns the Windows application instance handle -for the Tk application. This function is only available on Windows platforms. -.SH KEYWORDS -identifier, instance diff --git a/tk8.6/doc/GetHWND.3 b/tk8.6/doc/GetHWND.3 deleted file mode 100644 index 1a5ec2d..0000000 --- a/tk8.6/doc/GetHWND.3 +++ /dev/null @@ -1,36 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH HWND 3 8.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetHWND, Tk_AttachHWND \- manage interactions between the Windows handle and an X window -.SH SYNOPSIS -.nf -\fB#include <tkPlatDecls.h>\fR -.sp -HWND -\fBTk_GetHWND\fR(\fIwindow\fR) -.sp -Window -\fBTk_AttachHWND\fR(\fItkwin, hwnd\fR) -.SH ARGUMENTS -.AP Window window in -X token for window. -.AP Tk_Window tkwin in -Tk window for window. -.AP HWND hwnd in -Windows HWND for window. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetHWND\fR returns the Windows HWND identifier for X Windows -window given by \fIwindow\fR. -.PP -\fBTk_AttachHWND\fR binds the Windows HWND identifier to the -specified Tk_Window given by \fItkwin\fR. It returns an X Windows -window that encapsulates the HWND. -.SH KEYWORDS -identifier, window diff --git a/tk8.6/doc/GetImage.3 b/tk8.6/doc/GetImage.3 deleted file mode 100644 index f2407bc..0000000 --- a/tk8.6/doc/GetImage.3 +++ /dev/null @@ -1,130 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Image -\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) -.sp -\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) -.sp -\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) -.sp -\fBTk_FreeImage\fR(\fIimage\fR) -.SH ARGUMENTS -.AS Tk_ImageChangedProc *changeProc -.AP Tcl_Interp *interp in -Place to leave error message. -.AP Tk_Window tkwin in -Window in which image will be used. -.AP "const char" *name in -Name of image. -.AP Tk_ImageChangedProc *changeProc in -Procedure for Tk to invoke whenever image content or size changes. -.AP ClientData clientData in -One-word value for Tk to pass to \fIchangeProc\fR. -.AP Tk_Image image in -Token for image instance; must have been returned by a previous -call to \fBTk_GetImage\fR. -.AP int imageX in -X-coordinate of upper-left corner of region of image to redisplay -(measured in pixels from the image's upper-left corner). -.AP int imageY in -Y-coordinate of upper-left corner of region of image to redisplay -(measured in pixels from the image's upper-left corner). -.AP "int" width (in) -Width of region of image to redisplay. -.AP "int" height (in) -Height of region of image to redisplay. -.AP Drawable drawable in -Where to display image. Must either be window specified to -\fBTk_GetImage\fR or a pixmap compatible with that window. -.AP int drawableX in -Where to display image in \fIdrawable\fR: this is the x-coordinate -in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image -should be displayed. -.AP int drawableY in -Where to display image in \fIdrawable\fR: this is the y-coordinate -in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image -should be displayed. -.AP "int" widthPtr out -Store width of \fIimage\fR (in pixels) here. -.AP "int" heightPtr out -Store height of \fIimage\fR (in pixels) here. -.BE -.SH DESCRIPTION -.PP -These procedures are invoked by widgets that wish to display images. -\fBTk_GetImage\fR is invoked by a widget when it first decides to -display an image. -\fIname\fR gives the name of the desired image and \fItkwin\fR -identifies the window where the image will be displayed. -\fBTk_GetImage\fR looks up the image in the table of existing -images and returns a token for a new instance of the image. -If the image does not exist then \fBTk_GetImage\fR returns NULL -and leaves an error message in interpreter \fIinterp\fR's result. -.PP -When a widget wishes to actually display an image it must -call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR), -a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR, -\fIwidth\fR, and \fIheight\fR), and a place to display the -image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR). -Tk will then invoke the appropriate image manager, which will -display the requested portion of the image before returning. -.PP -A widget can find out the dimensions of an image by calling -\fBTk_SizeOfImage\fR: the width and height will be stored -in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR, -respectively. -.PP -When a widget is finished with an image (e.g., the widget is -being deleted or it is going to use a different image instead -of the current one), it must call \fBTk_FreeImage\fR to -release the image instance. -The widget should never again use the image token after passing -it to \fBTk_FreeImage\fR. -There must be exactly one call to \fBTk_FreeImage\fR for each -call to \fBTk_GetImage\fR. -.PP -If the contents or size of an image changes, then any widgets -using the image will need to find out about the changes so that -they can redisplay themselves. -The \fIchangeProc\fR and \fIclientData\fR arguments to -\fBTk_GetImage\fR are used for this purpose. -\fIchangeProc\fR will be called by Tk whenever a change occurs -in the image; it must match the following prototype: -.CS -typedef void \fBTk_ImageChangedProc\fR( - ClientData \fIclientData\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIimageWidth\fR, - int \fIimageHeight\fR); -.CE -The \fIclientData\fR argument to \fIchangeProc\fR is the same as the -\fIclientData\fR argument to \fBTk_GetImage\fR. -It is usually a pointer to the widget record for the widget or -some other data structure managed by the widget. -The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -identify a region within the image that must be redisplayed; -they are specified in pixels measured from the upper-left -corner of the image. -The arguments \fIimageWidth\fR and \fIimageHeight\fR give -the image's (new) size. -.SH "SEE ALSO" -Tk_CreateImageType -.SH KEYWORDS -images, redisplay diff --git a/tk8.6/doc/GetJoinStl.3 b/tk8.6/doc/GetJoinStl.3 deleted file mode 100644 index a717b72..0000000 --- a/tk8.6/doc/GetJoinStl.3 +++ /dev/null @@ -1,63 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR -.sp -const char * -\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *joinPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "const char" *string in -String containing name of join style \- one of -.QW \fBbevel\fR , -.QW \fBmiter\fR , -or -.QW \fBround\fR -\- or a unique abbreviation of one. -.AP int *joinPtr out -Pointer to location in which to store X join style corresponding to -\fIstring\fR. -.AP int join in -Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style -corresponding to \fIstring\fR, which will be one of -\fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR. -Join styles are typically used in X graphics contexts to indicate -how adjacent line segments should be joined together. -See the X documentation for information on what each style -implies. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIstring\fR does not contain a valid join style -or an abbreviation of one of these names, then an error message is -stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and -\fI*joinPtr\fR is unmodified. -.PP -\fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. -Given a join style such as \fBJoinBevel\fR it returns a -statically-allocated string corresponding to \fIjoin\fR. -If \fIjoin\fR is not a legal join style, then -.QW "unknown join style" -is returned. -.SH KEYWORDS -bevel, join style, miter, round diff --git a/tk8.6/doc/GetJustify.3 b/tk8.6/doc/GetJustify.3 deleted file mode 100644 index b51cb8d..0000000 --- a/tk8.6/doc/GetJustify.3 +++ /dev/null @@ -1,87 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR -.sp -int -\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR -.sp -const char * -\fBTk_NameOfJustify(\fIjustify\fB)\fR -.SH ARGUMENTS -.AS "Tk_Justify" *justifyPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting, or NULL. -.AP Tcl_Obj *objPtr in/out -String value contains name of justification style \- one of -.QW \fBleft\fR , -.QW \fBright\fR , -or -.QW \fBcenter\fR -\- or a unique abbreviation of one. -The internal rep will be modified to cache corresponding justify value. -.AP "const char" *string in -Same as \fIobjPtr\fR except description of justification style is passed as -a string. -.AP int *justifyPtr out -Pointer to location in which to store justify value corresponding to -\fIobjPtr\fR or \fIstring\fR. -.AP Tk_Justify justify in -Justification style (one of the values listed below). -.BE -.SH DESCRIPTION -.PP -\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value -corresponding to \fIobjPtr\fR's value. -This value will be one of the following: -.TP -\fBTK_JUSTIFY_LEFT\fR -Means that the text on each line should start at the left edge of -the line; as a result, the right edges of lines may be ragged. -.TP -\fBTK_JUSTIFY_RIGHT\fR -Means that the text on each line should end at the right edge of -the line; as a result, the left edges of lines may be ragged. -.TP -\fBTK_JUSTIFY_CENTER\fR -Means that the text on each line should be centered; as a result, -both the left and right edges of lines may be ragged. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIobjPtr\fR does not contain a valid justification style -or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, -\fI*justifyPtr\fR is unmodified, and an error message is -stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. -\fBTk_GetJustifyFromObj\fR caches information about the return -value in \fIobjPtr\fR, which speeds up future calls to -\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR. -.PP -\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except -that the description of the justification is specified with a string instead -of an object. This prevents \fBTk_GetJustify\fR from caching the -return value, so \fBTk_GetJustify\fR is less efficient than -\fBTk_GetJustifyFromObj\fR. -.PP -\fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR. -Given a justify value it returns a statically-allocated string -corresponding to \fIjustify\fR. -If \fIjustify\fR is not a legal justify value, then -.QW "unknown justification style" -is returned. -.SH KEYWORDS -center, fill, justification, string diff --git a/tk8.6/doc/GetOption.3 b/tk8.6/doc/GetOption.3 deleted file mode 100644 index 81846ad..0000000 --- a/tk8.6/doc/GetOption.3 +++ /dev/null @@ -1,42 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetOption 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetOption \- retrieve an option from the option database -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Uid -\fBTk_GetOption\fR(\fItkwin, name, class\fR) -.SH ARGUMENTS -.AS Tk_Window *class -.AP Tk_Window tkwin in -Token for window. -.AP "const char" *name in -Name of desired option. -.AP "const char" *class in -Class of desired option. Null means there is no class for -this option; do lookup based on name only. -.BE -.SH DESCRIPTION -.PP -This procedure is invoked to retrieve an option from the database -associated with \fItkwin\fR's main window. If there is an option -for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR, -then it is returned in the form of a Tk_Uid. If multiple options -match \fIname\fR and \fIclass\fR, then the highest-priority one -is returned. If no option matches, then NULL is returned. -.PP -\fBTk_GetOption\fR caches options related to \fItkwin\fR so that -successive calls for the same \fItkwin\fR will execute much more -quickly than successive calls for different windows. -.SH KEYWORDS -class, name, option, retrieve diff --git a/tk8.6/doc/GetPixels.3 b/tk8.6/doc/GetPixels.3 deleted file mode 100644 index e7a9043..0000000 --- a/tk8.6/doc/GetPixels.3 +++ /dev/null @@ -1,95 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR -.sp -int -\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR -.sp -int -\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR -.sp -int -\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *joinPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Window whose screen geometry determines the conversion between absolute -units and pixels. -.AP Tcl_Obj *objPtr in/out -String value specifies a distance on the screen; -internal rep will be modified to cache converted distance. -.AP "const char" *string in -Same as \fIobjPtr\fR except specification of distance is passed as -a string. -.AP int *intPtr out -Pointer to location in which to store converted distance in pixels. -.AP double *doublePtr out -Pointer to location in which to store converted distance in millimeters. -.BE -.SH DESCRIPTION -.PP -These procedures take as argument a specification of distance on -the screen (\fIobjPtr\fR or \fIstring\fR) and compute the -corresponding distance either in integer pixels or floating-point millimeters. -In either case, -\fIobjPtr\fR or \fIstring\fR -specifies a screen distance as a -floating-point number followed by one of the following characters -that indicates units: -.TP -<none> -The number specifies a distance in pixels. -.TP -\fBc\fR -The number specifies a distance in centimeters on the screen. -.TP -\fBi\fR -The number specifies a distance in inches on the screen. -.TP -\fBm\fR -The number specifies a distance in millimeters on the screen. -.TP -\fBp\fR -The number specifies a distance in printer's points (1/72 inch) -on the screen. -.PP -\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the -nearest even number of pixels and stores that value at \fI*intPtr\fR. -It returns \fBTCL_OK\fR under normal circumstances. -If an error occurs (e.g. \fIobjPtr\fR contains a number followed -by a character that is not one of the ones above) then -\fBTCL_ERROR\fR is returned and an error message is left -in \fIinterp\fR's result if \fIinterp\fR is not NULL. -\fBTk_GetPixelsFromObj\fR caches information about the return -value in \fIobjPtr\fR, which speeds up future calls to -\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR. -.PP -\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except -that the screen distance is specified with a string instead -of an object. This prevents \fBTk_GetPixels\fR from caching the -return value, so \fBTk_GetPixels\fR is less efficient than -\fBTk_GetPixelsFromObj\fR. -.PP -\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to -\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except -that they convert the screen distance to millimeters and -store a double-precision floating-point result at \fI*doublePtr\fR. -.SH KEYWORDS -centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/tk8.6/doc/GetPixmap.3 b/tk8.6/doc/GetPixmap.3 deleted file mode 100644 index 927c75c..0000000 --- a/tk8.6/doc/GetPixmap.3 +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Pixmap -\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR -.sp -\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR -.SH ARGUMENTS -.AS "Drawable" *pixelPtr -.AP Display *display in -X display for the pixmap. -.AP Drawable d in -Pixmap or window where the new pixmap will be used for drawing. -.AP "int" width in -Width of pixmap. -.AP "int" height in -Height of pixmap. -.AP "int" depth in -Number of bits per pixel in pixmap. -.AP Pixmap pixmap in -Pixmap to destroy. -.BE -.SH DESCRIPTION -.PP -These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR -and \fBXFreePixmap\fR, except that they have extra code to manage X -resource identifiers so that identifiers for deleted pixmaps can be -reused in the future. -It is important for Tk applications to use these procedures rather -than \fBXCreatePixmap\fR and \fBXFreePixmap\fR; otherwise long-running -applications may run out of resource identifiers. -.PP -\fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR, -with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, -and returns its identifier. -\fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes -its resource identifier available for reuse. -.SH KEYWORDS -pixmap, resource identifier diff --git a/tk8.6/doc/GetRelief.3 b/tk8.6/doc/GetRelief.3 deleted file mode 100644 index 6e8681a..0000000 --- a/tk8.6/doc/GetRelief.3 +++ /dev/null @@ -1,82 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR -.sp -int -\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR -.sp -const char * -\fBTk_NameOfRelief(\fIrelief\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *reliefPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tcl_Obj *objPtr in/out -String value contains name of relief, one of -.QW \fBflat\fR , -.QW \fBgroove\fR , -.QW \fBraised\fR , -.QW \fBridge\fR , -.QW \fBsolid\fR , -or -.QW \fBsunken\fR -(or any unique abbreviation thereof on input); -the internal rep will be modified to cache corresponding relief value. -.AP char *string in -Same as \fIobjPtr\fR except description of relief is passed as -a string. -.AP int *reliefPtr out -Pointer to location in which to store relief value corresponding to -\fIobjPtr\fR or \fIname\fR. -.AP "const char" *name -Name of the relief. -.AP int relief in -Relief value (one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, -\fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, -or \fBTK_RELIEF_RIDGE\fR). -.BE -.SH DESCRIPTION -.PP -\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value -corresponding to the value of \fIobjPtr\fR. This value will be one of -\fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, -\fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR. -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIobjPtr\fR does not contain one of the valid relief names -or an abbreviation of one of them, then \fBTCL_ERROR\fR is returned, -\fI*reliefPtr\fR is unmodified, and an error message -is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. -\fBTk_GetReliefFromObj\fR caches information about the return -value in \fIobjPtr\fR, which speeds up future calls to -\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR. -.PP -\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except -that the description of the relief is specified with a string instead -of an object. This prevents \fBTk_GetRelief\fR from caching the -return value, so \fBTk_GetRelief\fR is less efficient than -\fBTk_GetReliefFromObj\fR. -.PP -\fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR. -Given a relief value it returns the corresponding string (\fBflat\fR, -\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR). -If \fIrelief\fR is not a legal relief value, then -.QW "unknown relief" -is returned. -.SH KEYWORDS -name, relief, string diff --git a/tk8.6/doc/GetRootCrd.3 b/tk8.6/doc/GetRootCrd.3 deleted file mode 100644 index a9d2cd9..0000000 --- a/tk8.6/doc/GetRootCrd.3 +++ /dev/null @@ -1,39 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetRootCoords \- Compute root-window coordinates of window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for window. -.AP int *xPtr out -Pointer to location in which to store root-window x-coordinate -corresponding to left edge of \fItkwin\fR's border. -.AP int *yPtr out -Pointer to location in which to store root-window y-coordinate -corresponding to top edge of \fItkwin\fR's border. -.BE -.SH DESCRIPTION -.PP -This procedure scans through the structural information maintained -by Tk to compute the root-window coordinates corresponding to -the upper-left corner of \fItkwin\fR's border. If \fItkwin\fR has -no border, then \fBTk_GetRootCoords\fR returns the root-window -coordinates corresponding to location (0,0) in \fItkwin\fR. -\fBTk_GetRootCoords\fR is relatively efficient, since it does not have to -communicate with the X server. -.SH KEYWORDS -coordinates, root window diff --git a/tk8.6/doc/GetScroll.3 b/tk8.6/doc/GetScroll.3 deleted file mode 100644 index abd0880..0000000 --- a/tk8.6/doc/GetScroll.3 +++ /dev/null @@ -1,75 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR -.sp -int -\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *fractionPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP int objc in -Number of Tcl_Obj's in \fIobjv\fR array. -.AP "Tcl_Obj *const" objv[] in -Argument objects. These represent the entire widget command, of -which the first word is typically the widget name and the second -word is typically \fBxview\fR or \fByview\fR. -.AP int argc in -Number of strings in \fIargv\fR array. -.AP "const char" *argv[] in -Argument strings. These represent the entire widget command, of -which the first word is typically the widget name and the second -word is typically \fBxview\fR or \fByview\fR. -.AP double *fractionPtr out -Filled in with fraction from \fBmoveto\fR option, if any. -.AP int *stepsPtr out -Filled in with line or page count from \fBscroll\fR option, if any. -The value may be negative. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetScrollInfoObj\fR parses the arguments expected by widget -scrolling commands such as \fBxview\fR and \fByview\fR. -It receives the entire list of words that make up a widget command -and parses the words starting with \fIobjv\fR[2]. -The words starting with \fIobjv\fR[2] must have one of the following forms: -.CS -\fBmoveto \fIfraction\fR -\fBscroll \fInumber\fB units\fR -\fBscroll \fInumber\fB pages\fR -.CE -.LP -Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR -keywords may be abbreviated. -If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR -is returned as result and \fI*fractionPtr\fR is filled in with the -\fIfraction\fR argument to the command, which must be a proper real -value. -If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR -or \fBTK_SCROLL_PAGES\fR is returned and \fI*stepsPtr\fR is filled -in with the \fInumber\fR value, which must be a proper integer. -If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR -is returned and an error message is left in interpreter -\fIinterp\fR's result. -.PP -\fBTk_GetScrollInfo\fR is identical in function to -\fBTk_GetScrollInfoObj\fR. However, \fBTk_GetScrollInfo\fR accepts -string arguments, making it more appropriate for use with legacy -widgets. -.SH KEYWORDS -parse, scrollbar, scrolling command, xview, yview diff --git a/tk8.6/doc/GetSelect.3 b/tk8.6/doc/GetSelect.3 deleted file mode 100644 index 8c30a2b..0000000 --- a/tk8.6/doc/GetSelect.3 +++ /dev/null @@ -1,78 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetSelection \- retrieve the contents of a selection -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) -.SH ARGUMENTS -.AS Tk_GetSelProc clientData -.AP Tcl_Interp *interp in -Interpreter to use for reporting errors. -.AP Tk_Window tkwin in -Window on whose behalf to retrieve the selection (determines -display from which to retrieve). -.AP Atom selection in -The name of the selection to be retrieved. -.AP Atom target in -Form in which to retrieve selection. -.AP Tk_GetSelProc *proc in -Procedure to invoke to process pieces of the selection as they -are retrieved. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetSelection\fR retrieves the selection specified by the atom -\fIselection\fR in the format specified by \fItarget\fR. The -selection may actually be retrieved in several pieces; as each piece -is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR -should have arguments and result that match the type -\fBTk_GetSelProc\fR: -.PP -.CS -typedef int \fBTk_GetSelProc\fR( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIportion\fR); -.CE -.PP -The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR -will be copies of the corresponding arguments to -\fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to -a string containing part or all of the selection. For large -selections, \fIproc\fR will be called several times with successive -portions of the selection. The X Inter-Client Communication -Conventions Manual allows a selection to be returned in formats -other than strings, e.g. as an array of atoms or integers. If -this happens, Tk converts the selection back into a string -before calling \fIproc\fR. If a selection is returned as an -array of atoms, Tk converts it to a string containing the atom names -separated by white space. For any other format besides string, -Tk converts a selection to a string containing hexadecimal -values separated by white space. -.PP -\fBTk_GetSelection\fR returns to its caller when the selection has -been completely retrieved and processed by \fIproc\fR, or when a -fatal error has occurred (e.g. the selection owner did not respond -promptly). \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR; if -an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message -in interpreter \fIinterp\fR's result. \fIProc\fR should also return either -\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in -dealing with the selection, it should leave an error message in the -interpreter result and return \fBTCL_ERROR\fR; this will abort the -selection retrieval. -.SH KEYWORDS -format, get, selection retrieval diff --git a/tk8.6/doc/GetUid.3 b/tk8.6/doc/GetUid.3 deleted file mode 100644 index 06b466a..0000000 --- a/tk8.6/doc/GetUid.3 +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetUid 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetUid, Tk_Uid \- convert from string to unique identifier -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Uid -\fBTk_GetUid\fR(\fIstring\fR) -.SH ARGUMENTS -.AP char *string in -String for which the corresponding unique identifier is -desired. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetUid\fR returns the unique identifier corresponding -to \fIstring\fR. -Unique identifiers are similar to atoms in Lisp, and are used -in Tk to speed up comparisons and -searches. A unique identifier (type Tk_Uid) is a string pointer -and may be used anywhere that a variable of type -.QW "char *" -could be used. However, there is guaranteed to be exactly -one unique identifier for any given string value. If \fBTk_GetUid\fR -is called twice, once with string \fIa\fR and once with string -\fIb\fR, and if \fIa\fR and \fIb\fR have the same string value -(strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly -the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). -This means that variables of type -Tk_Uid may be compared directly (x == y) without having to call -\fBstrcmp\fR. -In addition, the return value from \fBTk_GetUid\fR will have the -same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). -.SH KEYWORDS -atom, unique identifier diff --git a/tk8.6/doc/GetVRoot.3 b/tk8.6/doc/GetVRoot.3 deleted file mode 100644 index a65ef78..0000000 --- a/tk8.6/doc/GetVRoot.3 +++ /dev/null @@ -1,46 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetVRootGeometry \- Get location and size of virtual root for window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR -.SH ARGUMENTS -.AS Tk_Window heightPtr -.AP Tk_Window tkwin in -Token for window whose virtual root is to be queried. -.AP int xPtr out -Points to word in which to store x-offset of virtual root. -.AP int yPtr out -Points to word in which to store y-offset of virtual root. -.AP "int" widthPtr out -Points to word in which to store width of virtual root. -.AP "int" heightPtr out -Points to word in which to store height of virtual root. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetVRootGeometry\fR returns geometry information about the virtual -root window associated with \fItkwin\fR. The -.QW associated -virtual root is the one in which \fItkwin\fR's nearest top-level ancestor (or -\fItkwin\fR itself if it is a top-level window) has -been reparented by the window manager. This window is identified by -a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level -window by the window manager. -If \fItkwin\fR is not associated with a virtual root (e.g. -because the window manager does not use virtual roots) then *\fIxPtr\fR and -*\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR -will be set to the dimensions of the screen containing \fItkwin\fR. -.SH KEYWORDS -geometry, height, location, virtual root, width, window manager diff --git a/tk8.6/doc/GetVisual.3 b/tk8.6/doc/GetVisual.3 deleted file mode 100644 index fe3d50c..0000000 --- a/tk8.6/doc/GetVisual.3 +++ /dev/null @@ -1,100 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetVisual \- translate from string to visual -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Visual * -\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *colormapPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which the visual will be used. -.AP "const char" *string in -String that identifies the desired visual. See below for -valid formats. -.AP int *depthPtr out -Depth of returned visual gets stored here. -.AP Colormap *colormapPtr out -If non-NULL then a suitable colormap for visual is found and its -identifier is stored here. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetVisual\fR takes a string description of a visual and -finds a suitable X Visual for use in \fItkwin\fR, if there is one. -It returns a pointer to the X Visual structure for the visual -and stores the number of bits per pixel for it at \fI*depthPtr\fR. -If \fIstring\fR is unrecognizable or if no suitable visual could -be found, then NULL is returned and \fBTk_GetVisual\fR leaves -an error message in interpreter \fIinterp\fR's result. -If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR -also locates an appropriate colormap for use with the result visual -and stores its X identifier at \fI*colormapPtr\fR. -.PP -The \fIstring\fR argument specifies the desired visual in one -of the following ways: -.TP 15 -\fIclass depth\fR -The string consists of a class name followed by an integer depth, -with any amount of white space (including none) in between. -\fIclass\fR selects what sort of visual is desired and must be one of -\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, -\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or -\fBtruecolor\fR, or a unique abbreviation. -\fIdepth\fR specifies how many bits per pixel are needed for the -visual. -If possible, \fBTk_GetVisual\fR will return a visual with this depth; -if there is no visual of the desired depth then \fBTk_GetVisual\fR -looks first for a visual with greater depth, then one with less -depth. -.TP 15 -\fBdefault\fR -Use the default visual for \fItkwin\fR's screen. -.TP 15 -\fIpathName\fR -Use the visual for the window given by \fIpathName\fR. -\fIpathName\fR must be the name of a window on the same screen -as \fItkwin\fR. -.TP 15 -\fInumber\fR -Use the visual whose X identifier is \fInumber\fR. -.TP 15 -\fBbest\fR ?\fIdepth\fR? -Choose the -.QW "best possible" -visual, using the following rules, in decreasing order of priority: -.RS -.IP (a) -a visual that has exactly the desired depth is best, followed -by a visual with greater depth than requested (but as little extra -as possible), followed by a visual with less depth than requested -(but as great a depth as possible); -.IP (b) -if no \fIdepth\fR is specified, then the deepest available visual -is chosen; -.IP (c) -\fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, -which are better than \fBstaticcolor\fR, which is better than -\fBstaticgray\fR or \fBgrayscale\fR; -.IP (d) -the default visual for the screen is better than any other visual. -.RE -.SH CREDITS -.PP -The idea for \fBTk_GetVisual\fR, and the first implementation, came -from Paul Mackerras. -.SH KEYWORDS -colormap, screen, visual diff --git a/tk8.6/doc/Grab.3 b/tk8.6/doc/Grab.3 deleted file mode 100644 index 1dba2df..0000000 --- a/tk8.6/doc/Grab.3 +++ /dev/null @@ -1,58 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH Tk_Grab 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_Grab, Tk_Ungrab \- manipulate grab state in an application -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) -.sp -void -\fBTk_Ungrab\fR(\fItkwin\fR) -.SH ARGUMENTS -.AP Tcl_Interp *interp in -Interpreter to use for error reporting -.AP Tk_Window tkwin in -Window on whose behalf the pointer is to be grabbed or released -.AP int grabGlobal in -Boolean indicating whether the grab is global or application local -.BE -.SH DESCRIPTION -.PP -These functions are used to set or release a global or -application local grab. When a grab is set on a particular window -in a Tk application, mouse and keyboard events can only be received by -that window and its descendants. Mouse and keyboard events for -windows outside the tree rooted at \fItkwin\fR will be redirected to -\fItkwin\fR. If the grab is global, then all mouse and keyboard -events for windows outside the tree rooted at \fItkwin\fR (even those -intended for windows in other applications) will be redirected to -\fItkwin\fR. If the grab is application local, only mouse and -keyboard events intended for a windows within the same application -(but outside the tree rooted at \fItkwin\fR) will be redirected. -.PP -\fBTk_Grab\fR sets a grab on a particular window. \fITkwin\fR -specifies the window on whose behalf the pointer is to be grabbed. -\fIGrabGlobal\fR indicates whether the grab should be global or -application local; if it is non-zero, it means the grab should be -global. Normally, \fBTk_Grab\fR returns \fBTCL_OK\fR; if an error occurs -and the grab cannot be set, \fBTCL_ERROR\fR is returned and an error message -is left if \fIinterp\fR's result. Once this call completes -successfully, no window outside the tree rooted at \fItkwin\fR will -receive pointer- or keyboard-related events until the next call to -Tk_Ungrab. If a previous grab was in effect within the application, -then it is replaced with a new one. -.PP -\fBTk_Ungrab\fR releases a grab on the mouse pointer and keyboard, if -there is one set on the window given by \fItkwin\fR. Once a grab is -released, pointer and keyboard events will start being delivered to -other windows again. -.SH KEYWORDS -grab, window diff --git a/tk8.6/doc/HWNDToWindow.3 b/tk8.6/doc/HWNDToWindow.3 deleted file mode 100644 index 9795099..0000000 --- a/tk8.6/doc/HWNDToWindow.3 +++ /dev/null @@ -1,26 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_HWNDToWindow \- Find Tk's window information for a Windows window -.SH SYNOPSIS -.nf -\fB#include <tkPlatDecls.h>\fR -.sp -Tk_Window -\fBTk_HWNDToWindow\fR(\fIhwnd\fR) -.SH ARGUMENTS -.AP HWND hwnd in -Windows handle for the window. -.BE -.SH DESCRIPTION -.PP -Given a Windows HWND window identifier, this procedure returns the -corresponding Tk_Window handle. If there is no Tk_Window corresponding -to \fIhwnd\fR then NULL is returned. -.SH KEYWORDS -Windows window id diff --git a/tk8.6/doc/HandleEvent.3 b/tk8.6/doc/HandleEvent.3 deleted file mode 100644 index bc293b6..0000000 --- a/tk8.6/doc/HandleEvent.3 +++ /dev/null @@ -1,46 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_HandleEvent \- invoke event handlers for window system events -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_HandleEvent\fR(\fIeventPtr\fR) -.SH ARGUMENTS -.AS XEvent *eventPtr -.AP XEvent *eventPtr in -Pointer to X event to dispatch to relevant handler(s). It is important -that all unused fields of the structure be set to zero. -.BE -.SH DESCRIPTION -.PP -\fBTk_HandleEvent\fR is a lower-level procedure that deals with window -events. It is called by \fBTcl_ServiceEvent\fR (and indirectly by -\fBTk_DoOneEvent\fR), and in a few other cases within Tk. -It makes callbacks to any window event -handlers (created by calls to \fBTk_CreateEventHandler\fR) -that match \fIeventPtr\fR and then returns. In some cases -it may be useful for an application to bypass the Tk event -queue and call \fBTk_HandleEvent\fR directly instead of -calling \fBTcl_QueueEvent\fR followed by -\fBTcl_ServiceEvent\fR. -.PP -This procedure may be invoked recursively. For example, -it is possible to invoke \fBTk_HandleEvent\fR recursively -from a handler called by \fBTk_HandleEvent\fR. This sort -of operation is useful in some modal situations, such -as when a -notifier has been popped up and an application wishes to -wait for the user to click a button in the notifier before -doing anything else. -.SH KEYWORDS -callback, event, handler, window diff --git a/tk8.6/doc/IdToWindow.3 b/tk8.6/doc/IdToWindow.3 deleted file mode 100644 index f6e397d..0000000 --- a/tk8.6/doc/IdToWindow.3 +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_IdToWindow \- Find Tk's window information for an X window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_IdToWindow\fR(\fIdisplay, window\fR) -.SH ARGUMENTS -.AS Tk_Window display -.AP Display *display in -X display containing the window. -.AP Window window in -X id for window. -.BE -.SH DESCRIPTION -.PP -Given an X window identifier and the X display it corresponds to, -this procedure returns the corresponding Tk_Window handle. -If there is no Tk_Window corresponding to \fIwindow\fR then -NULL is returned. -.SH KEYWORDS -X window id diff --git a/tk8.6/doc/ImgChanged.3 b/tk8.6/doc/ImgChanged.3 deleted file mode 100644 index f4d2c04..0000000 --- a/tk8.6/doc/ImgChanged.3 +++ /dev/null @@ -1,64 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ImageChanged \- notify widgets that image needs to be redrawn -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_ImageChanged\fR(\fIimageMaster, x, y, width, height, imageWidth, imageHeight\fR) -.SH ARGUMENTS -.AS Tk_ImageMaster imageHeight -.AP Tk_ImageMaster imageMaster in -Token for image, which was passed to image's \fIcreateProc\fR when -the image was created. -.AP int x in -X-coordinate of upper-left corner of region that needs redisplay (measured -from upper-left corner of image). -.AP int y in -Y-coordinate of upper-left corner of region that needs redisplay (measured -from upper-left corner of image). -.AP "int" width in -Width of region that needs to be redrawn, in pixels. -.AP "int" height in -Height of region that needs to be redrawn, in pixels. -.AP "int" imageWidth in -Current width of image, in pixels. -.AP "int" imageHeight in -Current height of image, in pixels. -.BE -.SH DESCRIPTION -.PP -An image manager calls \fBTk_ImageChanged\fR for an image -whenever anything happens that requires the image to be redrawn. -As a result of calling \fBTk_ImageChanged\fR, any widgets using -the image are notified so that they can redisplay themselves -appropriately. -The \fIimageMaster\fR argument identifies the image, and -\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -specify a rectangular region within the image that needs to -be redrawn. -\fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. -.PP -An image manager should call \fBTk_ImageChanged\fR during -its \fIcreateProc\fR to specify the image's initial size and to -force redisplay if there are existing instances for the image. -If any of the pixel values in the image should change later on, -\fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR, -\fIwidth\fR, and \fIheight\fR values that cover all the pixels -that changed. -If the size of the image should change, then \fBTk_ImageChanged\fR -must be called to indicate the new size, even if no pixels -need to be redisplayed. -.SH "SEE ALSO" -Tk_CreateImageType -.SH KEYWORDS -images, redisplay, image size changes diff --git a/tk8.6/doc/Inactive.3 b/tk8.6/doc/Inactive.3 deleted file mode 100644 index 0d2a1b7..0000000 --- a/tk8.6/doc/Inactive.3 +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -long -\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR -.sp -\fBTk_ResetUserInactiveTime(\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 inactivity time, \fB\-1\fR is returned. -\fBTk_ResetUserInactiveTime\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 diff --git a/tk8.6/doc/InternAtom.3 b/tk8.6/doc/InternAtom.3 deleted file mode 100644 index a16eee1..0000000 --- a/tk8.6/doc/InternAtom.3 +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Atom -\fBTk_InternAtom(\fItkwin, name\fR) -.sp -const char * -\fBTk_GetAtomName(\fItkwin, atom\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. Used to map atom or name relative to a particular display. -.AP "const char" *name in -String name for which atom is desired. -.AP Atom atom in -Atom for which corresponding string name is desired. -.BE -.SH DESCRIPTION -.PP -These procedures are similar to the Xlib procedures -\fBXInternAtom\fR and \fBXGetAtomName\fR. \fBTk_InternAtom\fR -returns the atom identifier associated with string given by -\fIname\fR; the atom identifier is only valid for the display -associated with \fItkwin\fR. -\fBTk_GetAtomName\fR returns the string associated -with \fIatom\fR on \fItkwin\fR's display. The string returned -by \fBTk_GetAtomName\fR is in Tk's storage: the caller need -not free this space when finished with the string, and the caller -should not modify the contents of the returned string. -If there is no atom \fIatom\fR on \fItkwin\fR's display, -then \fBTk_GetAtomName\fR returns the string -.QW "?bad atom?" . -.PP -Tk caches -the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR -so that future calls -for the same information can be serviced from the cache without -contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR -are generally much faster than their Xlib counterparts, and they -should be used in place of the Xlib procedures. -.SH KEYWORDS -atom, cache, display diff --git a/tk8.6/doc/MainLoop.3 b/tk8.6/doc/MainLoop.3 deleted file mode 100644 index ed4d0ea..0000000 --- a/tk8.6/doc/MainLoop.3 +++ /dev/null @@ -1,28 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MainLoop \- loop for events until all windows are deleted -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_MainLoop\fR() -.BE -.SH DESCRIPTION -.PP -\fBTk_MainLoop\fR is a procedure that loops repeatedly calling -\fBTcl_DoOneEvent\fR. It returns only when there are no applications -left in this process (i.e. no main windows exist anymore). Most -windowing applications will call \fBTk_MainLoop\fR after -initialization; the main execution of the application will consist -entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. -.SH KEYWORDS -application, event, main loop diff --git a/tk8.6/doc/MainWin.3 b/tk8.6/doc/MainWin.3 deleted file mode 100644 index c3af3e7..0000000 --- a/tk8.6/doc/MainWin.3 +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window information -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_MainWindow\fR(\fIinterp\fR) -.sp -int -\fBTk_GetNumMainWindows\fR() -.SH ARGUMENTS -.AS Tcl_Interp *pathName -.AP Tcl_Interp *interp in/out -Interpreter associated with the application. -.BE -.SH DESCRIPTION -.PP -A main window is a special kind of toplevel window used as the -outermost window in an application. -.PP -If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR -returns the application's main window. If there is no Tk application -associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and -leaves an error message in interpreter \fIinterp\fR's result. -.PP -\fBTk_GetNumMainWindows\fR returns a count of the number of main -windows currently open in the current thread. -.SH KEYWORDS -application, main window diff --git a/tk8.6/doc/MaintGeom.3 b/tk8.6/doc/MaintGeom.3 deleted file mode 100644 index d1c2d1c..0000000 --- a/tk8.6/doc/MaintGeom.3 +++ /dev/null @@ -1,99 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_MaintainGeometry\fR(\fIslave, master, x, y, width, height\fR) -.sp -\fBTk_UnmaintainGeometry\fR(\fIslave, master\fR) -.SH ARGUMENTS -.AS Tk_Window master -.AP Tk_Window slave in -Window whose geometry is to be controlled. -.AP Tk_Window master in -Window relative to which \fIslave\fR's geometry will be controlled. -.AP int x in -Desired x-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels -from the inside of \fImaster\fR's left border to the outside of -\fIslave\fR's left border. -.AP int y in -Desired y-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels -from the inside of \fImaster\fR's top border to the outside of -\fIslave\fR's top border. -.AP int width in -Desired width for \fIslave\fR, in pixels. -.AP int height in -Desired height for \fIslave\fR, in pixels. -.BE -.SH DESCRIPTION -.PP -\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it -easier for geometry managers to deal with slaves whose masters are not -their parents. -Three problems arise if the master for a slave is not its parent: -.IP [1] -The x- and y-position of the slave must be translated from the -coordinate system of the master to that of the parent before -positioning the slave. -.IP [2] -If the master window, or any of its ancestors up to the slave's -parent, is moved, then the slave must be repositioned within its -parent in order to maintain the correct position relative to the -master. -.IP [3] -If the master or one of its ancestors is mapped or unmapped, then -the slave must be mapped or unmapped to correspond. -.LP -None of these problems is an issue if the parent and master are -the same. For example, if the master or one of its ancestors -is unmapped, the slave is automatically removed by the screen -by X. -.PP -\fBTk_MaintainGeometry\fR deals with these problems for slaves -whose masters are not their parents, as well as handling the simpler -case of slaves whose masters are their parents. -\fBTk_MaintainGeometry\fR is typically called by a window manager -once it has decided where a slave should be positioned relative -to its master. -\fBTk_MaintainGeometry\fR translates the coordinates to the -coordinate system of \fIslave\fR's parent and then moves and -resizes the slave appropriately. -Furthermore, it remembers the desired position and creates event -handlers to monitor the master and all of its ancestors up -to (but not including) the slave's parent. -If any of these windows is moved, mapped, or unmapped, -the slave will be adjusted so that it is mapped only when the -master is mapped and its geometry relative to the master -remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and -\fIheight\fR. -.PP -When a window manager relinquishes control over a window, or -if it decides that it does not want the window to appear on the -screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR. -\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any -previous calls to \fBTk_MaintainGeometry\fR for the -\fImaster\fR\-\fIslave\fR pair, so that the slave's -geometry and mapped state are no longer maintained -automatically. -\fBTk_UnmaintainGeometry\fR need not be called by a geometry -manager if the slave, the master, or any of the master's ancestors -is destroyed: Tk will call it automatically. -.PP -If \fBTk_MaintainGeometry\fR is called repeatedly for the same -\fImaster\fR\-\fIslave\fR pair, the information from the most -recent call supersedes any older information. -If \fBTk_UnmaintainGeometry\fR is called for a \fImaster\fR\-\fIslave\fR -pair that is is not currently managed, the call has no effect. -.SH KEYWORDS -geometry manager, map, master, parent, position, slave, unmap diff --git a/tk8.6/doc/ManageGeom.3 b/tk8.6/doc/ManageGeom.3 deleted file mode 100644 index 520546f..0000000 --- a/tk8.6/doc/ManageGeom.3 +++ /dev/null @@ -1,90 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ManageGeometry \- arrange to handle geometry requests for a window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) -.SH ARGUMENTS -.AS Tk_GeometryProc clientData -.AP Tk_Window tkwin in -Token for window to be managed. -.AP "const Tk_GeomMgr" *mgrPtr in -Pointer to data structure containing information about the -geometry manager, or NULL to indicate that \fItkwin\fR's geometry -should not be managed anymore. -The data structure pointed to by \fImgrPtr\fR must be static: -Tk keeps a reference to it as long as the window is managed. -.AP ClientData clientData in -Arbitrary one-word value to pass to geometry manager callbacks. -.BE -.SH DESCRIPTION -.PP -\fBTk_ManageGeometry\fR arranges for a particular geometry manager, -described by the \fImgrPtr\fR argument, to control the geometry -of a particular slave window, given by \fItkwin\fR. -If \fItkwin\fR was previously managed by some other geometry manager, -the previous manager loses control in favor of the new one. -If \fImgrPtr\fR is NULL, geometry management is cancelled for -\fItkwin\fR. -.PP -The structure pointed to by \fImgrPtr\fR contains information about -the geometry manager: -.CS -typedef struct { - const char *\fIname\fR; - Tk_GeomRequestProc *\fIrequestProc\fR; - Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; -} \fBTk_GeomMgr\fR; -.CE -The \fIname\fR field is the textual name for the geometry manager, -such as \fBpack\fR or \fBplace\fR; this value will be returned -by the command \fBwinfo manager\fR. -.PP -\fIrequestProc\fR is a procedure in the geometry manager that -will be invoked whenever \fBTk_GeometryRequest\fR is called by the -slave to change its desired geometry. -\fIrequestProc\fR should have arguments and results that match the -type \fBTk_GeomRequestProc\fR: -.CS -typedef void \fBTk_GeomRequestProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); -.CE -The parameters to \fIrequestProc\fR will be identical to the -corresponding parameters passed to \fBTk_ManageGeometry\fR. -\fIclientData\fR usually points to a data -structure containing application-specific information about -how to manage \fItkwin\fR's geometry. -.PP -The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another -procedure in the geometry manager. -Tk will invoke \fIlostSlaveProc\fR if some other manager -calls \fBTk_ManageGeometry\fR to claim -\fItkwin\fR away from the current geometry manager. -\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is -called with a NULL value for \fImgrPtr\fR (presumably the current -geometry manager has made this call, so it already knows that the -window is no longer managed), nor is it called if \fImgrPtr\fR -is the same as the window's current geometry manager. -\fIlostSlaveProc\fR should have -arguments and results that match the following prototype: -.CS -typedef void \fBTk_GeomLostSlaveProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); -.CE -The parameters to \fIlostSlaveProc\fR will be identical to the -corresponding parameters passed to \fBTk_ManageGeometry\fR. -.SH KEYWORDS -callback, geometry, managed, request, unmanaged diff --git a/tk8.6/doc/MapWindow.3 b/tk8.6/doc/MapWindow.3 deleted file mode 100644 index a3c6296..0000000 --- a/tk8.6/doc/MapWindow.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Window -\fBTk_MapWindow\fR(\fItkwin\fR) -.sp -\fBTk_UnmapWindow\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. -.BE -.SH DESCRIPTION -.PP -These procedures may be used to map and unmap windows -managed by Tk. \fBTk_MapWindow\fR maps the window given -by \fItkwin\fR, and also creates an X window corresponding -to \fItkwin\fR if it does not already exist. See the -\fBTk_CreateWindow\fR manual entry for information on -deferred window creation. -\fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window -from the screen. -.PP -If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was -used to create a child window), then event handlers interested in map -and unmap events are invoked immediately. If \fItkwin\fR is not an -internal window, then the event handlers will be invoked later, after -X has seen the request and returned an event for it. -.PP -These procedures should be used in place of the X procedures -\fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update -Tk's local data structure for \fItkwin\fR. Applications -using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR -directly. -.SH KEYWORDS -map, unmap, window diff --git a/tk8.6/doc/MeasureChar.3 b/tk8.6/doc/MeasureChar.3 deleted file mode 100644 index 3959978..0000000 --- a/tk8.6/doc/MeasureChar.3 +++ /dev/null @@ -1,127 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR -.sp -int -\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR -.sp -\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR -.sp -\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR -.sp -.SH ARGUMENTS -.AS "const char" firstChar -.AP Tk_Font tkfont in -Token for font in which text is to be drawn or measured. Must have been -returned by a previous call to \fBTk_GetFont\fR. -.AP "const char" *string in -Text to be measured or displayed. Need not be null terminated. Any -non-printing meta-characters in the string (such as tabs, newlines, and -other control characters) will be measured or displayed in a -platform-dependent manner. -.AP int numBytes in -The maximum number of bytes to consider when measuring or drawing -\fIstring\fR. Must be greater than or equal to 0. -.AP int maxPixels in -If \fImaxPixels\fR is >= 0, it specifies the longest permissible -line length in pixels. Characters from \fIstring\fR are processed only -until this many pixels have been covered. If \fImaxPixels\fR is < 0, then -the line length is unbounded and the \fIflags\fR argument is ignored. -.AP int flags in -Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character -as long as any part of it fits in the length given by \fImaxPixels\fR; -otherwise, a character must fit completely to be considered. -\fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible. If -\fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no -characters could fit in the length given by \fImaxPixels\fR. If -\fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if -not even one word fits on the line, return the first few letters of the -word that did fit; if not even one letter of the word fit, then the first -letter will still be returned. -.AP int *lengthPtr out -Filled with the number of pixels occupied by the number of characters -returned as the result of \fBTk_MeasureChars\fR. -.AP Display *display in -Display on which to draw. -.AP Drawable drawable in -Window or pixmap in which to draw. -.AP GC gc in -Graphics context for drawing characters. The font selected into this GC -must be the same as the \fItkfont\fR. -.AP int "x, y" in -Coordinates at which to place the left edge of the baseline when displaying -\fIstring\fR. -.AP int firstByte in -The index of the first byte of the first character to underline in the -\fIstring\fR. Underlining begins at the left edge of this character. -.AP int lastByte in -The index of the first byte of the last character up to which the -underline will be drawn. The character specified by \fIlastByte\fR -will not itself be underlined. -.BE -.SH DESCRIPTION -.PP -These routines are for measuring and displaying simple single-font, -single-line strings. To measure and display single-font, multi-line, -justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR. -There is no programming interface in the core of Tk that supports -multi-font, multi-line text; support for that behavior must be built on -top of simpler layers. -Note that the interfaces described here are -byte-oriented not character-oriented, so index values coming from Tcl -scripts need to be converted to byte offsets using the -\fBTcl_UtfAtIndex\fR and related routines. -.PP -A glyph is the displayable picture of a letter, number, or some other -symbol. Not all character codes in a given font have a glyph. -Characters such as tabs, newlines/returns, and control characters that -have no glyph are measured and displayed by these procedures in a -platform-dependent manner; under X, they are replaced with backslashed -escape sequences, while under Windows and Macintosh hollow or solid boxes -may be substituted. Refer to the documentation for -\fBTk_ComputeTextLayout\fR for a programming interface that supports the -platform-independent expansion of tab characters into columns and -newlines/returns into multi-line text. -.PP -\fBTk_MeasureChars\fR is used both to compute the length of a given -string and to compute how many characters from a string fit in a given -amount of space. The return value is the number of bytes from -\fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to -the conditions described by \fIflags\fR. If all characters fit, the return -value will be \fInumBytes\fR. \fI*lengthPtr\fR is filled with the computed -width, in pixels, of the portion of the string that was measured. For -example, if the return value is 5, then \fI*lengthPtr\fR is filled with the -distance between the left edge of \fIstring\fR[0] and the right edge of -\fIstring\fR[4]. -.PP -\fBTk_TextWidth\fR is a wrapper function that provides a simpler interface -to the \fBTk_MeasureChars\fR function. The return value is how much -space in pixels the given \fIstring\fR needs. -.PP -\fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the -given \fIdrawable\fR. -.PP -\fBTk_UnderlineChars\fR underlines the given range of characters in the -given \fIstring\fR. It does not draw the characters (which are assumed to -have been displayed previously by \fBTk_DrawChars\fR); it just draws the -underline. This procedure is used to underline a few characters without -having to construct an underlined font. To produce natively underlined -text, the appropriate underlined font should be constructed and used. -.SH "SEE ALSO" -font(n), FontId(3) -.SH KEYWORDS -font, measurement diff --git a/tk8.6/doc/MoveToplev.3 b/tk8.6/doc/MoveToplev.3 deleted file mode 100644 index effed29..0000000 --- a/tk8.6/doc/MoveToplev.3 +++ /dev/null @@ -1,51 +0,0 @@ -'\" -'\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_MoveToplevelWindow \- Adjust the position of a top-level window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for top-level window to move. -.AP int x in -New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the -top-left pixel of the decorative border supplied for \fItkwin\fR by the -window manager, if there is one. -.AP int y in -New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the -top-left pixel of the decorative border supplied for \fItkwin\fR by the -window manager, if there is one. -.BE -.SH DESCRIPTION -.PP -In general, a window should never set its own position; this should be -done only by the geometry manger that is responsible for the window. -For top-level windows the window manager is effectively the geometry -manager; Tk provides interface code between the application and the -window manager to convey the application's desires to the geometry -manager. The desired size for a top-level window is conveyed using -the usual \fBTk_GeometryRequest\fR mechanism. The procedure -\fBTk_MoveToplevelWindow\fR may be used by an application to request -a particular position for a top-level window; this procedure is -similar in function to the \fBwm geometry\fR Tcl command except that -negative offsets cannot be specified. It is invoked by widgets such as -menus that want to appear at a particular place on the screen. -.PP -When \fBTk_MoveToplevelWindow\fR is called it does not immediately -pass on the new desired location to the window manager; it defers -this action until all other outstanding work has been completed, -using the \fBTk_DoWhenIdle\fR mechanism. -.SH KEYWORDS -position, top-level window, window manager diff --git a/tk8.6/doc/Name.3 b/tk8.6/doc/Name.3 deleted file mode 100644 index 4b9c5bc..0000000 --- a/tk8.6/doc/Name.3 +++ /dev/null @@ -1,86 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_Name 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_Uid -\fBTk_Name\fR(\fItkwin\fR) -.sp -char * -\fBTk_PathName\fR(\fItkwin\fR) -.sp -Tk_Window -\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) -.SH ARGUMENTS -.AS Tcl_Interp *pathName -.AP Tk_Window tkwin in -Token for window. -.AP Tcl_Interp *interp out -Interpreter to use for error reporting. -.AP "const char" *pathName in -Character string containing path name of window. -.BE -.SH DESCRIPTION -.PP -Each window managed by Tk has two names, a short name that identifies -a window among children of the same parent, and a path name that -identifies the window uniquely among all the windows belonging to the -same main window. The path name is used more often in Tk than the -short name; many commands, like \fBbind\fR, expect path names as -arguments. -.PP -The \fBTk_Name\fR macro returns a window's -short name, which is the same as the \fIname\fR argument -passed to \fBTk_CreateWindow\fR when -the window was created. The value is returned -as a Tk_Uid, which may be used just like a string pointer but also has -the properties of a unique identifier (see the manual entry for -\fBTk_GetUid\fR for details). -.PP -The \fBTk_PathName\fR macro returns a hierarchical name for \fItkwin\fR. -Path names have a structure similar to file names in Unix but with -dots between elements instead of slashes: the main window for -an application has the path name -.QW . ; -its children have names like -.QW .a -and -.QW .b ; -their children have names like -.QW .a.aa -and -.QW .b.bb ; -and so on. A window is considered to be a child of -another window for naming purposes if the second window was named -as the first window's \fIparent\fR when the first window was created. -This is not always the same as the X window hierarchy. For -example, a pop-up -is created as a child of the root window, but its logical parent will -usually be a window within the application. -.PP -The procedure \fBTk_NameToWindow\fR returns the token for a window -given its path name (the \fIpathName\fR argument) and another window -belonging to the same main window (\fItkwin\fR). It normally -returns a token for the named window, but if no such window exists -\fBTk_NameToWindow\fR leaves an error message in interpreter -\fIinterp\fR's result -and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR -is needed because path names are only unique within a single -application hierarchy. If, for example, a single process has opened -two main windows, each will have a separate naming hierarchy and the -same path name might appear in each of the hierarchies. Normally -\fItkwin\fR is the main window of the desired hierarchy, but this -need not be the case: any window in the desired hierarchy may be used. -.SH KEYWORDS -name, path name, token, window diff --git a/tk8.6/doc/NameOfImg.3 b/tk8.6/doc/NameOfImg.3 deleted file mode 100644 index 78332db..0000000 --- a/tk8.6/doc/NameOfImg.3 +++ /dev/null @@ -1,30 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_NameOfImage \- Return name of image. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -const char * -\fBTk_NameOfImage\fR(\fItypePtr\fR) -.SH ARGUMENTS -.AS Tk_ImageMaster *masterPtr -.AP Tk_ImageMaster *masterPtr in -Token for image, which was passed to image manager's \fIcreateProc\fR when -the image was created. -.BE -.SH DESCRIPTION -.PP -This procedure is invoked by image managers to find out the name -of an image. Given the token for the image, it returns the -string name for the image. -.SH KEYWORDS -image manager, image name diff --git a/tk8.6/doc/OwnSelect.3 b/tk8.6/doc/OwnSelect.3 deleted file mode 100644 index ed9bcab..0000000 --- a/tk8.6/doc/OwnSelect.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_OwnSelection \- make a window the owner of the primary selection -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) -.SH ARGUMENTS -.AS Tk_LostSelProc clientData -.AP Tk_Window tkwin in -Window that is to become new selection owner. -.AP Atom selection in -The name of the selection to be owned, such as XA_PRIMARY. -.AP Tk_LostSelProc *proc in -Procedure to invoke when \fItkwin\fR loses selection ownership later. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the -new owner of the selection specified by the atom -\fIselection\fR. After this call completes, future requests -for the selection will be directed to handlers created for -\fItkwin\fR using \fBTk_CreateSelHandler\fR. When \fItkwin\fR -eventually loses the selection ownership, \fIproc\fR will be -invoked so that the window can clean itself up (e.g. by -unhighlighting the selection). \fIProc\fR should have arguments and -result that match the type \fBTk_LostSelProc\fR: -.CS -typedef void \fBTk_LostSelProc\fR( - ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the -\fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is -usually a pointer to a data structure containing application-specific -information about \fItkwin\fR. -.SH KEYWORDS -own, selection owner diff --git a/tk8.6/doc/ParseArgv.3 b/tk8.6/doc/ParseArgv.3 deleted file mode 100644 index 3a9bd49..0000000 --- a/tk8.6/doc/ParseArgv.3 +++ /dev/null @@ -1,360 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ParseArgv \- process command-line options -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) -.SH ARGUMENTS -.AS Tk_ArgvInfo *argTable -.AP Tcl_Interp *interp in -Interpreter to use for returning error messages. -.AP Tk_Window tkwin in -Window to use when arguments specify Tk options. If NULL, then -no Tk options will be processed. -.AP int argcPtr in/out -Pointer to number of arguments in argv; gets modified to hold -number of unprocessed arguments that remain after the call. -.AP "const char" **argv in/out -Command line arguments passed to main program. Modified to -hold unprocessed arguments that remain after the call. -.AP Tk_ArgvInfo *argTable in -Array of argument descriptors, terminated by element with -type \fBTK_ARGV_END\fR. -.AP int flags in -If non-zero, then it specifies one or more flags that control the -parsing of arguments. Different flags may be OR'ed together. -The flags currently defined are \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR, -\fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and -\fBTK_ARGV_NO_DEFAULTS\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_ParseArgv\fR processes an array of command-line arguments according -to a table describing the kinds of arguments that are expected. -Each of the arguments in \fIargv\fR is processed in turn: if it matches -one of the entries in \fIargTable\fR, the argument is processed -according to that entry and discarded. The arguments that do not -match anything in \fIargTable\fR are copied down to the beginning -of \fIargv\fR (retaining their original order) and returned to -the caller. At the end of the call -\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of -arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR -will hold the value NULL. Normally, \fBTk_ParseArgv\fR -assumes that \fIargv[0]\fR is a command name, so it is treated like -an argument that does not match \fIargTable\fR and returned to the -caller; however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR bit is set in -\fIflags\fR then \fIargv[0]\fR will be processed just like the other -elements of \fIargv\fR. -.PP -\fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error -occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and -\fBTk_ParseArgv\fR will leave an error message in the result of -interpreter \fIinterp\fR in the standard Tcl fashion. In -the event of an error return, \fI*argvPtr\fR will not have been -modified, but \fIargv\fR could have been partially modified. The -possible causes of errors are explained below. -.PP -The \fIargTable\fR array specifies the kinds of arguments that are -expected; each of its entries has the following structure: -.CS -typedef struct { - const char *\fIkey\fR; - int \fItype\fR; - char *\fIsrc\fR; - char *\fIdst\fR; - const char *\fIhelp\fR; -} \fBTk_ArgvInfo\fR; -.CE -The \fIkey\fR field is a string such as -.QW \-display -or -.QW \-bg -that is compared with the values in \fIargv\fR. \fIType\fR -indicates how to process an argument that matches \fIkey\fR -(more on this below). \fISrc\fR and \fIdst\fR are additional -values used in processing the argument. Their exact usage -depends on \fItype\fR, but typically \fIsrc\fR indicates -a value and \fIdst\fR indicates where to store the -value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR -are placeholders: the actual types may be different. Lastly, -\fIhelp\fR is a string giving a brief description -of this option; this string is printed when users ask for help -about command-line options. -.PP -When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR -compares the argument to each of the \fIkey\fR's in \fIargTable\fR. -\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches -the argument exactly, if such a specifier exists. Otherwise -\fBTk_ParseArgv\fR selects a specifier for which the argument -is a unique abbreviation. If the argument is a unique abbreviation -for more than one specifier, then an error is returned. If there -is no matching entry in \fIargTable\fR, then the argument is -skipped and returned to the caller. -.PP -Once a matching argument specifier is found, \fBTk_ParseArgv\fR -processes the argument according to the \fItype\fR field of the -specifier. The argument that matched \fIkey\fR is called -.QW "the matching argument" -in the descriptions below. As part of the processing, -\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR -after the matching argument, which is called -.QW "the following argument" . -The legal values for \fItype\fR, and the processing -that they cause, are as follows: -.TP -\fBTK_ARGV_END\fR -Marks the end of the table. The last entry in \fIargTable\fR -must have this type; all of its other fields are ignored and it -will never match any arguments. -.TP -\fBTK_ARGV_CONSTANT\fR -\fISrc\fR is treated as an integer and \fIdst\fR is treated -as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. -The matching argument is discarded. -.TP -\fBTK_ARGV_INT\fR -The following argument must contain an -integer string in the format accepted by \fBstrtol\fR (e.g. -.QW 0 -and -.QW 0x -prefixes may be used to specify octal or hexadecimal -numbers, respectively). \fIDst\fR is treated as a pointer to an -integer; the following argument is converted to an integer value -and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching -and following arguments are discarded from \fIargv\fR. -.TP -\fBTK_ARGV_FLOAT\fR -The following argument must contain a floating-point number in -the format accepted by \fBstrtol\fR. -\fIDst\fR is treated as the address of a double-precision -floating point value; the following argument is converted to a -double-precision value and stored at \fI*dst\fR. The matching -and following arguments are discarded from \fIargv\fR. -.TP -\fBTK_ARGV_STRING\fR -In this form, \fIdst\fR is treated as a pointer to a (char *); -\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following -argument, and discards the matching and following arguments from -\fIargv\fR. \fISrc\fR is ignored. -.TP -\fBTK_ARGV_UID\fR -This form is similar to \fBTK_ARGV_STRING\fR, except that the argument -is turned into a Tk_Uid by calling \fBTk_GetUid\fR. -\fIDst\fR is treated as a pointer to a -Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid -corresponding to the following -argument, and discards the matching and following arguments from -\fIargv\fR. \fISrc\fR is ignored. -.TP -\fBTK_ARGV_CONST_OPTION\fR -This form causes a Tk option to be set (as if the \fBoption\fR -command had been invoked). The \fIsrc\fR field is treated as a -pointer to a string giving the value of an option, and \fIdst\fR -is treated as a pointer to the name of the option. The matching -argument is discarded. If \fItkwin\fR is NULL, then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_OPTION_VALUE\fR -This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the -value of the option is taken from the following argument instead -of from \fIsrc\fR. \fIDst\fR is used as the name of the option. -\fISrc\fR is ignored. The matching and following arguments -are discarded. If \fItkwin\fR is NULL, then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_OPTION_NAME_VALUE\fR -In this case the following argument is taken as the name of a Tk -option and the argument after that is taken as the value for that -option. Both \fIsrc\fR and \fIdst\fR are ignored. All three -arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, -then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_HELP\fR -When this kind of option is encountered, \fBTk_ParseArgv\fR uses the -\fIhelp\fR fields of \fIargTable\fR to format a message describing -all the valid arguments. The message is placed in interpreter -\fIinterp\fR's result -and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the -caller normally prints the help message and aborts. If the \fIkey\fR -field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will -never match any arguments; in this case the specifier simply provides -extra documentation, which will be included when some other -\fBTK_ARGV_HELP\fR entry causes help information to be returned. -.TP -\fBTK_ARGV_REST\fR -This option is used by programs or commands that allow the last -several of their options to be the name and/or options for some -other program. If a \fBTK_ARGV_REST\fR argument is found, then -\fBTk_ParseArgv\fR does not process any -of the remaining arguments; it returns them all at -the beginning of \fIargv\fR (along with any other unprocessed arguments). -In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an -integer value, and stores at \fI*dst\fR the index of the first of the -\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the -program to distinguish the \fBTK_ARGV_REST\fR options from other -unprocessed options that preceded the \fBTK_ARGV_REST\fR. -.TP -\fBTK_ARGV_FUNC\fR -For this kind of argument, \fIsrc\fR is treated as the address of -a procedure, which is invoked to process the following argument. -The procedure should have the following structure: -.RS -.CS -int -\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) - char *\fIdst\fR; - char *\fIkey\fR; - char *\fInextArg\fR; -{ -} -.CE -The \fIdst\fR and \fIkey\fR parameters will contain the -corresponding fields from the \fIargTable\fR entry, and -\fInextArg\fR will point to the following argument from \fIargv\fR -(or NULL if there are not any more arguments left in \fIargv\fR). -If \fIfunc\fR uses \fInextArg\fR (so that -\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it -should return 0 and \fBTkParseArgv\fR will process the following -argument in the normal fashion. In either event the matching argument -is discarded. -.RE -.TP -\fBTK_ARGV_GENFUNC\fR -This form provides a more general procedural escape. It treats -\fIsrc\fR as the address of a procedure, and passes that procedure -all of the remaining arguments. The procedure should have the following -form: -.RS -.CS -int -\fIgenfunc\fR(dst, interp, key, argc, argv) - char *\fIdst\fR; - Tcl_Interp *\fIinterp\fR; - char *\fIkey\fR; - int \fIargc\fR; - char **\fIargv\fR; -{ -} -.CE -The \fIdst\fR and \fIkey\fR parameters will contain the -corresponding fields from the \fIargTable\fR entry. \fIInterp\fR -will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. -\fIArgc\fR and \fIargv\fR refer to all of the options after the -matching one. \fIGenfunc\fR should behave in a fashion similar -to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, -then return any that are left by compacting them to the beginning of -\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR -should return a count of how many arguments are left in \fIargv\fR; -\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters -an error then it should leave an error message in interpreter -\fIinterp\fR's result, -in the usual Tcl fashion, and return \-1; when this happens -\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. -.RE -.SS "FLAGS" -.TP -\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR -\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program -or command name, and returns it to the caller just as if it -had not matched \fIargTable\fR. If this flag is given, then -\fIargv[0]\fR is not given special treatment. -.TP -\fBTK_ARGV_NO_ABBREV\fR -Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for -\fIkey\fR values in \fIargTable\fR. If this flag is given then -only exact matches will be acceptable. -.TP -\fBTK_ARGV_NO_LEFTOVERS\fR -Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the -caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR -will return an error if it encounters any argument that does not -match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, -which will be returned to the caller with no errors as -long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified. -.TP -\fBTK_ARGV_NO_DEFAULTS\fR -Normally, \fBTk_ParseArgv\fR searches an internal table of -standard argument specifiers in addition to \fIargTable\fR. If -this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will -use only \fIargTable\fR and not its default table. -.SH EXAMPLE -.PP -Here is an example definition of an \fIargTable\fR and -some sample command lines that use the options. Note the effect -on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR -are eliminated from \fIargv\fR, and \fIargc\fR -is updated to reflect reduced number of arguments. -.CS -/* - * Define and set default values for globals. - */ -int debugFlag = 0; -int numReps = 100; -char defaultFileName[] = "out"; -char *fileName = defaultFileName; -Boolean exec = FALSE; - -/* - * Define option descriptions. - */ -Tk_ArgvInfo argTable[] = { - {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, - "Turn on debugging printfs"}, - {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, - "Number of repetitions"}, - {"\-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, - "Name of file for output"}, - {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, - "File to exec, followed by any arguments (must be last argument)."}, - {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, - (char *) NULL} -}; - -main(argc, argv) - int argc; - char *argv[]; -{ - \&... - - if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { - fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp))); - exit(1); - } - - /* - * Remainder of the program. - */ -} -.CE -.PP -Note that default values can be assigned to variables named in -\fIargTable\fR: the variables will only be overwritten if the -particular arguments are present in \fIargv\fR. -Here are some example command lines and their effects. -.CS -prog \-N 200 infile # just sets the numReps variable to 200 -prog \-of out200 infile # sets fileName to reference "out200" -prog \-XN 10 infile # sets the debug flag, also sets numReps -.CE -In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, -\fIargv\fR[0] will be -.QW prog , -\fIargv\fR[1] will be -.QW infile , -and \fIargv\fR[2] will be NULL. -.SH KEYWORDS -arguments, command line, options diff --git a/tk8.6/doc/QWinEvent.3 b/tk8.6/doc/QWinEvent.3 deleted file mode 100644 index caa5026..0000000 --- a/tk8.6/doc/QWinEvent.3 +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CollapseMotionEvents, Tk_QueueWindowEvent \- Add a window event to the Tcl event queue -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) -.sp -\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) -.SH ARGUMENTS -.AS Tcl_QueuePosition position -.AP Display *display in -Display for which to control motion event collapsing. -.AP int collapse in -Indicates whether motion events should be collapsed or not. -.AP XEvent *eventPtr in -An event to add to the event queue. It is important -that all unused fields of the structure be set to zero. -.AP Tcl_QueuePosition position in -Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, -\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. -.BE -.SH DESCRIPTION -.PP -\fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event -queue for eventual servicing. It creates a Tcl_Event structure, copies the -event into that structure, and calls \fBTcl_QueueEvent\fR to add the event -to the queue. When the event is eventually removed from the queue it is -processed just like all window events. -.PP -When multiple motion events are received for the same window in rapid -succession, they are collapsed by default. This behavior can be controlled -with \fBTk_CollapseMotionEvents\fR. \fBTk_CollapseMotionEvents\fR always -returns the previous value for collapse behavior on the \fIdisplay\fR. -.PP -The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has -the same significance as for \fBTcl_QueueEvent\fR; see the -documentation for \fBTcl_QueueEvent\fR for details. -.SH KEYWORDS -callback, clock, handler, modal timeout, events diff --git a/tk8.6/doc/Restack.3 b/tk8.6/doc/Restack.3 deleted file mode 100644 index 2b9097f..0000000 --- a/tk8.6/doc/Restack.3 +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_RestackWindow \- Change a window's position in the stacking order -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) -.SH ARGUMENTS -.AS Tk_Window aboveBelow -.AP Tk_Window tkwin in -Token for window to restack. -.AP int aboveBelow in -Indicates new position of \fItkwin\fR relative to \fIother\fR; -must be \fBAbove\fR or \fBBelow\fR. -.AP Tk_Window other in -\fITkwin\fR will be repositioned just above or below this window. -Must be a sibling of \fItkwin\fR or a descendant of a sibling. -If NULL then \fItkwin\fR is restacked above or below all siblings. -.BE -.SH DESCRIPTION -.PP -\fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative -to its siblings. -If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned -at the top or bottom of its stacking order, depending on whether -\fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR. -If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned -just above or below \fIother\fR. -.PP -The \fIaboveBelow\fR argument must have one of the symbolic values -\fBAbove\fR or \fBBelow\fR. -Both of these values are defined by the include file <X11/Xlib.h>. -.SH KEYWORDS -above, below, obscure, stacking order diff --git a/tk8.6/doc/RestrictEv.3 b/tk8.6/doc/RestrictEv.3 deleted file mode 100644 index eb1f040..0000000 --- a/tk8.6/doc/RestrictEv.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_RestrictEvents \- filter and selectively delay X events -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_RestrictProc * -\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) -.SH ARGUMENTS -.AS Tk_RestrictProc **prevArgPtr -.AP Tk_RestrictProc *proc in -Predicate procedure to call to filter incoming X events. -NULL means do not restrict events at all. -.AP ClientData arg in -Arbitrary argument to pass to \fIproc\fR. -.AP ClientData *prevArgPtr out -Pointer to place to save argument to previous restrict procedure. -.BE -.SH DESCRIPTION -.PP -This procedure is useful in certain situations where applications -are only prepared to receive certain X events. After -\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and -hence \fBTk_MainLoop\fR) will filter X input events through -\fIproc\fR. \fIProc\fR indicates whether a -given event is to be processed immediately, deferred until some -later time (e.g. when the event restriction is lifted), or discarded. -\fIProc\fR -is a procedure with arguments and result that match -the type \fBTk_RestrictProc\fR: -.CS -typedef Tk_RestrictAction \fBTk_RestrictProc\fR( - ClientData \fIarg\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fIarg\fR argument is a copy of the \fIarg\fR passed -to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with -information it needs to filter events. The \fIeventPtr\fR points to -an event under consideration. \fIProc\fR returns a restrict action -(enumerated type \fBTk_RestrictAction\fR) that indicates what -\fBTk_DoOneEvent\fR should do with the event. If the return value is -\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. -If the return value is \fBTK_DEFER_EVENT\fR, then the event will be -left on the event queue for later processing. If the return value is -\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event -queue and discarded without being processed. -.PP -\fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR -to return information about the current event restriction procedure -(a NULL return value means there are currently no restrictions). -These values may be used to restore the previous restriction state -when there is no longer any need for the current restriction. -.PP -There are very few places where \fBTk_RestrictEvents\fR is needed. -In most cases, the best way to restrict events is by changing the -bindings with the \fBbind\fR Tcl command or by calling -\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. -The main place where \fBTk_RestrictEvents\fR must be used is when -performing synchronous actions (for example, if you need to wait -for a particular event to occur on a particular window but you do not -want to invoke any handlers for any other events). The -.QW obvious -solution in these situations is to call \fBXNextEvent\fR or -\fBXWindowEvent\fR, but these procedures cannot be used because -Tk keeps its own event queue that is separate from the X event -queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, -then call \fBTk_DoOneEvent\fR to retrieve the desired event(s). -.SH KEYWORDS -delay, event, filter, restriction diff --git a/tk8.6/doc/SetAppName.3 b/tk8.6/doc/SetAppName.3 deleted file mode 100644 index 3978850..0000000 --- a/tk8.6/doc/SetAppName.3 +++ /dev/null @@ -1,62 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetAppName \- Set the name of an application for 'send' commands -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -const char * -\fBTk_SetAppName\fR(\fItkwin, name\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window in application. Used only to select a particular -application. -.AP "const char" *name in -Name under which to register the application. -.BE -.SH DESCRIPTION -.PP -\fBTk_SetAppName\fR associates a name with a given application and -records that association on the display containing with the application's -main window. -After this procedure has been invoked, other applications on the -display will be able to use the \fBsend\fR command to invoke operations -in the application. -If \fIname\fR is already in use by some other application on the -display, then a new name will be generated by appending -.QW "\fB #2\fR" -to \fIname\fR; if this name is also in use, -the number will be incremented until an unused name is found. -The return value from the procedure is a pointer to the name actually -used. -.PP -If the application already has a name when \fBTk_SetAppName\fR is -called, then the new name replaces the old name. -.PP -\fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's -interpreter, which can be used to send commands from this application -to others on any of the displays where the application has windows. -.PP -The application's name registration persists until the interpreter is -deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which -point the name is automatically unregistered and the application -becomes inaccessible via \fBsend\fR. -The application can be made accessible again by calling \fBTk_SetAppName\fR. -.PP -\fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR, -so applications do not normally need to call it explicitly. -.PP -The command \fBtk appname\fR provides Tcl-level access to the -functionality of \fBTk_SetAppName\fR. -.SH KEYWORDS -application, name, register, send command diff --git a/tk8.6/doc/SetCaret.3 b/tk8.6/doc/SetCaret.3 deleted file mode 100644 index fd63f18..0000000 --- a/tk8.6/doc/SetCaret.3 +++ /dev/null @@ -1,36 +0,0 @@ -'\" -'\" Copyright (c) 2002 ActiveState Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetCaretPos \- set the display caret location -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) -.SH ARGUMENTS -.AP Tk_Window tkwin in -Token for window. -.AP int x in -Window-relative x coordinate. -.AP int y in -Window-relative y coordinate. -.AP int h in -Height of the caret in the window. -.BE -.SH DESCRIPTION -.PP -\fBTk_SetCaretPos\fR sets the caret location for the display of the -specified Tk_Window \fItkwin\fR. The caret is the per-display cursor -location used for indicating global focus (e.g. to comply with Microsoft -Accessibility guidelines), as well as for location of the over-the-spot XIM -(X Input Methods) or Windows IME windows. -.SH KEYWORDS -caret, cursor diff --git a/tk8.6/doc/SetClass.3 b/tk8.6/doc/SetClass.3 deleted file mode 100644 index 707975d..0000000 --- a/tk8.6/doc/SetClass.3 +++ /dev/null @@ -1,57 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetClass 3 "" Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetClass, Tk_Class \- set or retrieve a window's class -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_SetClass\fR(\fItkwin, class\fR) -.sp -Tk_Uid -\fBTk_Class\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. -.AP char *class in -New class name for window. -.BE -.SH DESCRIPTION -.PP -\fBTk_SetClass\fR is called to associate a class with a particular -window. The \fIclass\fR string identifies the type of the -window; all windows with the same general class of behavior -(button, menu, etc.) should have the same class. By -convention all class names start with a capital letter, and -there exists a Tcl command with the same name as -each class (except all in lower-case) which can be used to -create and manipulate windows of that class. -A window's class string is initialized to NULL -when the window is created. -.PP -For main windows, Tk automatically propagates the name and class -to the WM_CLASS property used by window managers. This happens -either when a main window is actually created (e.g. in -\fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR -is called, whichever occurs later. If a main window has not been -assigned a class then Tk will not set the WM_CLASS property for -the window. -.PP -\fBTk_Class\fR is a macro that returns the -current value of \fItkwin\fR's class. The value is returned -as a Tk_Uid, which may be used just like a string pointer but also has -the properties of a unique identifier (see the manual entry for -\fBTk_GetUid\fR for details). -If \fItkwin\fR has not yet been given a class, then -\fBTk_Class\fR will return NULL. -.SH KEYWORDS -class, unique identifier, window, window manager diff --git a/tk8.6/doc/SetClassProcs.3 b/tk8.6/doc/SetClassProcs.3 deleted file mode 100644 index 58618da..0000000 --- a/tk8.6/doc/SetClassProcs.3 +++ /dev/null @@ -1,87 +0,0 @@ -'\" -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetClassProcs \- register widget specific procedures -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) -.SH ARGUMENTS -.AS Tk_ClassProc instanceData -.AP Tk_Window tkwin in -Token for window to modify. -.AP "const Tk_ClassProcs" *procs in -Pointer to data structure containing widget specific procedures. -The data structure pointed to by \fIprocs\fR must be static: -Tk keeps a reference to it as long as the window exists. -.AP ClientData instanceData in -Arbitrary one-word value to pass to widget callbacks. -.BE -.SH DESCRIPTION -.PP -\fBTk_SetClassProcs\fR is called to register a set of procedures that -are used as callbacks in different places. -.PP -The structure pointed to by \fIprocs\fR contains the following: -.CS -typedef struct Tk_ClassProcs { - unsigned int \fIsize\fR; - Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; - Tk_ClassCreateProc *\fIcreateProc\fR; - Tk_ClassModalProc *\fImodalProc\fR; -} \fBTk_ClassProcs\fR; -.CE -The \fIsize\fR field is used to simplify future expansion of the -structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR. -.PP -\fIworldChangedProc\fR is invoked when the system has altered -in some way that requires some reaction from the widget. For example, -when a font alias (see the \fBfont\fR manual entry) is reconfigured, -widgets configured to use that font alias must update their display -accordingly. \fIworldChangedProc\fR should have arguments and results -that match the type \fBTk_ClassWorldChangedProc\fR: -.CS -typedef void \fBTk_ClassWorldChangedProc\fR( - ClientData \fIinstanceData\fR); -.CE -The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR -will be identical to the \fIinstanceData\fR parameter passed to -\fBTk_SetClassProcs\fR. -.PP -\fIcreateProc\fR is used to create platform-dependant windows. It is -invoked by \fBTk_MakeWindowExist\fR. \fIcreateProc\fR should have -arguments and results that match the type \fBTk_ClassCreateProc\fR: -.CS -typedef Window \fBTk_ClassCreateProc\fR( - Tk_Window \fItkwin\fR, - Window \fIparent\fR, - ClientData \fIinstanceData\fR); -.CE -The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to -the \fItkwin\fR and \fIinstanceData\fR parameters passed to -\fBTk_SetClassProcs\fR. The \fIparent\fR parameter will be the parent -of the window to be created. The \fIcreateProc\fR should return the -created window. -.PP -\fImodalProc\fR is invoked after all bindings on a widget have been -triggered in order to handle a modal loop. \fImodalProc\fR should -have arguments and results that match the type \fBTk_ClassModalProc\fR: -.CS -typedef void \fBTk_ClassModalProc\fR( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the -\fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR. The -\fIeventPtr\fR parameter will be a pointer to an XEvent structure -describing the event being processed. -.SH KEYWORDS -callback, class diff --git a/tk8.6/doc/SetGrid.3 b/tk8.6/doc/SetGrid.3 deleted file mode 100644 index 28e428b..0000000 --- a/tk8.6/doc/SetGrid.3 +++ /dev/null @@ -1,63 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) -.sp -\fBTk_UnsetGrid\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window heightInc -.AP Tk_Window tkwin in -Token for window. -.AP int reqWidth in -Width in grid units that corresponds to the pixel dimension \fItkwin\fR -has requested via \fBTk_GeometryRequest\fR. -.AP int reqHeight in -Height in grid units that corresponds to the pixel dimension \fItkwin\fR -has requested via \fBTk_GeometryRequest\fR. -.AP int widthInc in -Width of one grid unit, in pixels. -.AP int heightInc in -Height of one grid unit, in pixels. -.BE -.SH DESCRIPTION -.PP -\fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's -toplevel window and specifies the geometry of the grid. -\fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR -option is true. -It restricts interactive resizing of \fItkwin\fR's toplevel window so -that the space allocated to the toplevel is equal to its requested -size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR. -Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are -passed to the window manager so that it can report the window's -size in grid units during interactive resizes. -If \fItkwin\fR's configuration changes (e.g., the size of a grid unit -changes) then the widget should invoke \fBTk_SetGrid\fR again with the new -information. -.PP -\fBTk_UnsetGrid\fR cancels gridded geometry management for -\fItkwin\fR's toplevel window. -.PP -For each toplevel window there can be at most one internal window -with gridding enabled. -If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some -other window is already controlling gridding for \fItkwin\fR's -toplevel, the calls for the new window have no effect. -.PP -See the \fBwm\fR manual entry for additional information on gridded geometry -management. -.SH KEYWORDS -grid, window, window manager diff --git a/tk8.6/doc/SetOptions.3 b/tk8.6/doc/SetOptions.3 deleted file mode 100644 index b5f0782..0000000 --- a/tk8.6/doc/SetOptions.3 +++ /dev/null @@ -1,656 +0,0 @@ -'\" -'\" Copyright (c) 1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_OptionTable -\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR -.sp -\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR -.sp -int -\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR -.sp -\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR -.sp -\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR -.sp -Tcl_Obj * -\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR -.sp -Tcl_Obj * -\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR -.sp -\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_Offset(\fItype, field\fB)\fR -.SH ARGUMENTS -.AS Tk_SavedOptions "*const objv[]" in/out -.AP Tcl_Interp *interp in -A Tcl interpreter. Most procedures use this only for returning error -messages; if it is NULL then no error messages are returned. For -\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the -interpreter in which the option table will be used. -.AP "const Tk_OptionSpec" *templatePtr in -Points to an array of static information that describes the configuration -options that are supported. Used to build a Tk_OptionTable. The information -pointed to by this argument must exist for the lifetime of the Tk_OptionTable. -.AP Tk_OptionTable optionTable in -Token for an option table. Must have been returned by a previous call -to \fBTk_CreateOptionTable\fR. -.AP char *recordPtr in/out -Points to structure in which values of configuration options are stored; -fields of this record are modified by procedures such as \fBTk_SetOptions\fR -and read by procedures such as \fBTk_GetOptionValue\fR. -.AP Tk_Window tkwin in -For options such as \fBTK_OPTION_COLOR\fR, this argument indicates -the window in which the option will be used. If \fIoptionTable\fR uses -no window-dependent options, then a NULL value may be supplied for -this argument. -.AP int objc in -Number of values in \fIobjv\fR. -.AP Tcl_Obj "*const objv[]" in -Command-line arguments for setting configuring options. -.AP Tk_SavedOptions *savePtr out -If not NULL, the structure pointed to by this argument is filled -in with the old values of any options that were modified and old -values are restored automatically if an error occurs in \fBTk_SetOptions\fR. -.AP int *maskPtr out -If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the -bit-wise OR of the \fItypeMask\fR fields for the options that -were modified. -.AP Tk_SavedOptions *savedPtr in/out -Points to a structure previously filled in by \fBTk_SetOptions\fR with -old values of modified options. -.AP Tcl_Obj *namePtr in -The value of this object is the name of a particular option. If NULL -is passed to \fBTk_GetOptionInfo\fR then information is returned for -all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. -.AP "type name" type in -The name of the type of a record. -.AP "field name" field in -The name of a field in records of type \fItype\fR. -.BE -.SH DESCRIPTION -.PP -These procedures handle most of the details of parsing configuration -options such as those for Tk widgets. Given a description of what -options are supported, these procedures handle all the details of -parsing options and storing their values into a C structure associated -with the widget or object. The procedures were designed primarily for -widgets in Tk, but they can also be used for other kinds of objects that -have configuration options. In the rest of this manual page -.QW widget -will be used to refer to the object whose options are being managed; in -practice the object may not actually be a widget. The term -.QW "widget record" -is used to refer to the C-level structure in -which information about a particular widget or object is stored. -.PP -Note: the easiest way to learn how to use these procedures is to -look at a working example. In Tk, the simplest example is the code -that implements the button family of widgets, which is in \fBtkButton.c\fR. -Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. -.PP -In order to use these procedures, the code that implements the widget -must contain a static array of Tk_OptionSpec structures. This is a -template that describes the various options supported by that class of -widget; there is a separate template for each kind of widget. The -template contains information such as the name of each option, its type, -its default value, and where the value of the option is stored in the -widget record. See TEMPLATES below for more detail. -.PP -In order to process configuration options efficiently, the static -template must be augmented with additional information that is available -only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this -dynamic information from the template and returns a Tk_OptionTable token -that describes both the static and dynamic information. All of the -other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable -token as argument. Typically, \fBTk_CreateOptionTable\fR is called the -first time that a widget of a particular class is created and the -resulting Tk_OptionTable is used in the future for all widgets of that -class. A Tk_OptionTable may be used only in a single interpreter, given -by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an -option table is no longer needed \fBTk_DeleteOptionTable\fR should be -called to free all of its resources. All of the option tables -for a Tcl interpreter are freed automatically if the interpreter is deleted. -.PP -\fBTk_InitOptions\fR is invoked when a new widget is created to set the -default values for all of the widget's configuration options that do not -have \fBTK_OPTION_DONT_SET_DEFAULT\fR set in their \fIflags\fR field. -\fBTk_InitOptions\fR is passed a token for an option table -(\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR), -which is the C structure that holds information about this widget. -\fBTk_InitOptions\fR uses the information in the option table to choose an -appropriate default for each option, except those having -\fBTK_OPTION_DONT_SET_DEFAULT\fR set, then it stores the default value -directly into the widget record, overwriting any information that was -already present in the widget record. \fBTk_InitOptions\fR normally -returns \fBTCL_OK\fR. If an error occurred while setting the default -values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR -is returned and an error message is left in \fIinterp\fR's result if -\fIinterp\fR is not NULL. -.PP -\fBTk_SetOptions\fR is invoked to modify configuration options based -on information specified in a Tcl command. The command might be one that -creates a new widget, or a command that modifies options on an existing -widget. The \fIobjc\fR and \fIobjv\fR arguments describe the -values of the arguments from the Tcl command. \fIObjv\fR must contain -an even number of objects: the first object of each pair gives the name of -an option and the second object gives the new value for that option. -\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that -the new value of the option conforms to the type in \fIoptionTable\fR, -and stores the value of the option into the widget record given by -\fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR. If -an error occurred (such as an unknown option name or an illegal option -value) then \fBTCL_ERROR\fR is returned and an error message is left in -\fIinterp\fR's result if \fIinterp\fR is not NULL. -.PP -\fBTk_SetOptions\fR has two additional features. First, if the -\fImaskPtr\fR argument is not NULL then it points to an integer -value that is filled in with information about the options that were -modified. For each option in the template passed to -\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The -bits of this field are defined by the code that implements the widget; -for example, each bit might correspond to a particular configuration option. -Alternatively, bits might be used functionally. For example, one bit might -be used for redisplay: all options that affect the widget's display, such -that changing the option requires the widget to be redisplayed, might have -that bit set. Another bit might indicate that the geometry of the widget -must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the -\fItypeMask\fR fields from all the options that were modified and returns -this value at *\fImaskPtr\fR; the caller can then use this information -to optimize itself so that, for example, it does not redisplay the widget -if the modified options do not affect the widget's appearance. -.PP -The second additional feature of \fBTk_SetOptions\fR has to do with error -recovery. If an error occurs while processing configuration options, this -feature makes it possible to restore all the configuration options to their -previous values. Errors can occur either while processing options in -\fBTk_SetOptions\fR or later in the caller. In many cases the caller does -additional processing after \fBTk_SetOptions\fR returns; for example, it -might use an option value to set a trace on a variable and may detect -an error if the variable is an array instead of a scalar. Error recovery -is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument -to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized -Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR -overwrites the structure pointed to by \fIsavePtr\fR with information -about the old values of any options modified by the procedure. -If \fBTk_SetOptions\fR returns successfully, the -caller uses the structure in one of two ways. If the caller completes -its processing of the new options without any errors, then it must pass -the structure to \fBTk_FreeSavedOptions\fR so that the old values can be -freed. If the caller detects an error in its processing of the new -options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, -which will copy the old values back into the widget record and free -the new values. -If \fBTk_SetOptions\fR detects an error then it automatically restores -any options that had already been modified and leaves *\fIsavePtr\fR in -an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or -\fBTk_RestoreSavedOptions\fR. -If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then -\fBTk_SetOptions\fR frees each old option value immediately when it sets a new -value for the option. In this case, if an error occurs in the third -option, the old values for the first two options cannot be restored. -.PP -\fBTk_GetOptionValue\fR returns the current value of a configuration option -for a particular widget. The \fInamePtr\fR argument contains the name of -an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR -to lookup the option and extract its value from the widget record -pointed to by \fIrecordPtr\fR, then it returns an object containing -that value. If an error occurs (e.g., because \fInamePtr\fR contains an -unknown option name) then NULL is returned and an error message is left -in \fIinterp\fR's result unless \fIinterp\fR is NULL. -.PP -\fBTk_GetOptionInfo\fR returns information about configuration options in -a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR -argument is not NULL, it points to an object that gives the name of a -configuration option; \fBTk_GetOptionInfo\fR returns an object containing -a list with five elements, which are the name of the option, the name and -class used for the option in the option database, the default value for -the option, and the current value for the option. If the \fInamePtr\fR -argument is NULL, then \fBTk_GetOptionInfo\fR returns information about -all options in the form of a list of lists; each sublist describes one -option. Synonym options are handled differently depending on whether -\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for -each synonym option has only two elements, which are the name of the -option and the name of the other option that it refers to; if \fInamePtr\fR -is non-NULL and names a synonym option then the object returned -is the five-element list -for the other option that the synonym refers to. If an error occurs -(e.g., because \fInamePtr\fR contains an unknown option name) then NULL -is returned and an error message is left in \fIinterp\fR's result unless -\fIinterp\fR is NULL. -.PP -\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. -It frees all of the resources associated with any of the configuration -options defined in \fIrecordPtr\fR by \fIoptionTable\fR. -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating the -\fIobjOffset\fR and \fIinternalOffset\fR values for entries in -Tk_OptionSpec structures. It takes two arguments: the name of a type -of record, and the name of a field in that record. It returns the byte -offset of the named field in records of the given type. -.SH "TEMPLATES" -.PP -The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR -via its \fItemplatePtr\fR argument describes the configuration options -supported by a particular class of widgets. Each structure specifies -one configuration option and has the following fields: -.CS -typedef struct { - Tk_OptionType \fItype\fR; - const char *\fIoptionName\fR; - const char *\fIdbName\fR; - const char *\fIdbClass\fR; - const char *\fIdefValue\fR; - int \fIobjOffset\fR; - int \fIinternalOffset\fR; - int \fIflags\fR; - const void *\fIclientData\fR; - int \fItypeMask\fR; -} \fBTk_OptionSpec\fR; -.CE -The \fItype\fR field indicates what kind of configuration option this is -(e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for -an integer value). \fIType\fR determines how the -value of the option is parsed (more on this below). -The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; -it is the name used for the option in Tcl commands and passed to -procedures via the \fIobjc\fR or \fInamePtr\fR arguments. -The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR -to look up a default value for this option in the option database; if -\fIdbName\fR is NULL then the option database is not used by -\fBTk_InitOptions\fR for this option. The \fIdefValue\fR field -specifies a default value for this configuration option if no -value is specified in the option database. The \fIobjOffset\fR and -\fIinternalOffset\fR fields indicate where to store the value of this -option in widget records (more on this below); values for the \fIobjOffset\fR -and \fIinternalOffset\fR fields should always be generated with the -\fBTk_Offset\fR macro. -The \fIflags\fR field contains additional information -to control the processing of this configuration option (see below -for details). -\fIClientData\fR provides additional type-specific data needed -by certain types. For instance, for \fBTK_OPTION_COLOR\fR types, -\fIclientData\fR is a string giving the default value to use on -monochrome displays. See the descriptions of the different types -below for details. -The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to -return information about which options were modified; see the description -of \fBTk_SetOptions\fR above for details. -.PP -When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an -option into the widget record, they can do it in either of two ways. -If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than -or equal to zero, then the value of the option is stored as a -(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. -If the \fIinternalOffset\fR field of the Tk_OptionSpec is -greater than or equal to zero, then the value of the option is stored -in a type-specific internal form at the location in the widget record -given by \fIinternalOffset\fR. For example, if the option's type is -\fBTK_OPTION_INT\fR then the internal form is an integer. If the -\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the -value is not stored in that form. At least one of the offsets must be -greater than or equal to zero. -.PP -The \fIflags\fR field consists of one or more bits ORed together. The -following flags are supported: -.TP -\fBTK_OPTION_NULL_OK\fR -If this bit is set for an option then an empty string will be accepted as -the value for the option and the resulting internal form will be a NULL -pointer, a zero value, or \fBNone\fR, depending on the type of the option. -If the flag is not set then empty strings will result in errors. -\fBTK_OPTION_NULL_OK\fR is typically used to allow a -feature to be turned off entirely, e.g. set a cursor value to -\fBNone\fR so that a window simply inherits its parent's cursor. -Not all option types support the \fBTK_OPTION_NULL_OK\fR -flag; for those that do, there is an explicit indication of that fact -in the descriptions below. -.TP -\fBTK_OPTION_DONT_SET_DEFAULT\fR -If this bit is set for an option then no default value will be set in -\fBTk_InitOptions\fR for this option. Neither the option database, nor any -system default value, nor \fIoptionTable\fR are used to give a default -value to this option. Instead it is assumed that the caller has already -supplied a default value in the widget code. -.PP -The \fItype\fR field of each Tk_OptionSpec structure determines -how to parse the value of that configuration option. The -legal value for \fItype\fR, and the corresponding actions, are -described below. If the type requires a \fItkwin\fR value to be -passed into procedures like \fBTk_SetOptions\fR, or if it uses -the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated -explicitly; if not mentioned, the type requires neither \fItkwin\fR -nor \fIclientData\fR. -.TP -\fBTK_OPTION_ANCHOR\fR -The value must be a standard anchor position such as \fBne\fR or -\fBcenter\fR. The internal form is a Tk_Anchor value like the ones -returned by \fBTk_GetAnchorFromObj\fR. -.TP -\fBTK_OPTION_BITMAP\fR -The value must be a standard Tk bitmap name. The internal form is a -Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_BOOLEAN\fR -The value must be a standard boolean value such as \fBtrue\fR or -\fBno\fR. The internal form is an integer with value 0 or 1. -.TP -\fBTK_OPTION_BORDER\fR -The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. -The internal form is a Tk_3DBorder token like the ones returned -by \fBTk_Alloc3DBorderFromObj\fR. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_COLOR\fR -The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. -The internal form is an (XColor *) token like the ones returned by -\fBTk_AllocColorFromObj\fR. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_CURSOR\fR -The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. -The internal form is a Tk_Cursor token like the ones returned by -\fBTk_AllocCursorFromObj\fR. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR, and when the option is set the cursor -for the window is changed by calling \fBXDefineCursor\fR. This -option type also supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_CUSTOM\fR -This option allows applications to define new option types. The -clientData field of the entry points to a structure defining the new -option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. -.TP -\fBTK_OPTION_DOUBLE\fR -The string value must be a floating-point number in -the format accepted by \fBstrtol\fR. The internal form is a C -\fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR -flag; if a NULL value is set, the internal representation is set to zero. -.TP -\fBTK_OPTION_END\fR -Marks the end of the template. There must be a Tk_OptionSpec structure -with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the -\fIclientData\fR field of this structure is not NULL, then it points to -an additional array of Tk_OptionSpec's, which is itself terminated by -another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily -deeply. This feature allows common options to be shared by several -widget classes. -.TP -\fBTK_OPTION_FONT\fR -The value must be a standard font name such as \fBTimes 16\fR. -The internal form is a Tk_Font handle like the ones returned by -\fBTk_AllocFontFromObj\fR. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_INT\fR -The string value must be an integer in the format accepted by -\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to -specify octal or hexadecimal numbers, respectively). The internal -form is a C \fBint\fR value. -.TP -\fBTK_OPTION_JUSTIFY\fR -The value must be a standard justification value such as \fBleft\fR. -The internal form is a Tk_Justify like the values returned by -\fBTk_GetJustifyFromObj\fR. -.TP -\fBTK_OPTION_PIXELS\fR -The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. -The internal form is an integer value giving a -distance in pixels, like the values returned by -\fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field is not -used then information about the original value of this option will be lost. -See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option -type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the -internal representation is set to zero. -.TP -\fBTK_OPTION_RELIEF\fR -The value must be standard relief such as \fBraised\fR. -The internal form is an integer relief value such as -\fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR -flag; if the empty string is specified as the value for the option, -the integer relief value is set to \fBTK_RELIEF_NULL\fR. -.TP -\fBTK_OPTION_STRING\fR -The value may be any string. The internal form is a (char *) pointer -that points to a dynamically allocated copy of the value. -This option type supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_STRING_TABLE\fR -For this type, \fIclientData\fR is a pointer to an array of strings -suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must -be one of the strings in the table, or a unique abbreviation of -one of the strings. The internal form is an integer giving the index -into the table of the matching string, like the return value -from \fBTcl_GetStringFromObj\fR. -.TP -\fBTK_OPTION_SYNONYM\fR -This type is used to provide alternative names for an option (for -example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). -The \fBclientData\fR field is a string that gives the name of another -option in the same table. Whenever the synonym option is used, the -information from the other option will be used instead. -.TP -\fBTK_OPTION_WINDOW\fR -The value must be a window path name. The internal form is a -\fBTk_Window\fR token for the window. -This option type requires \fItkwin\fR to be supplied to procedures -such as \fBTk_SetOptions\fR (in order to identify the application), -and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.SH "STORAGE MANAGEMENT ISSUES" -.PP -If a field of a widget record has its offset stored in the \fIobjOffset\fR -or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the -procedures described here will handle all of the storage allocation and -resource management issues associated with the field. When the value -of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR) -will automatically free any resources associated with the old value, such as -Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for -\fBTK_OPTION_STRING\fR options. For an option stored as an object using the -\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the -object pointed to by the \fIobjv\fR value from the call to -\fBTk_SetOptions\fR. The reference count for this object is incremented -when a pointer to it is stored in the widget record and decremented when -the option is modified. When the widget is deleted -\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources -associated with all options and decrement reference counts for any -objects. -.PP -However, the widget code is responsible for storing NULL or \fBNone\fR in -all pointer and token fields before invoking \fBTk_InitOptions\fR. -This is needed to allow proper cleanup in the rare case where -an error occurs in \fBTk_InitOptions\fR. -.SH "OBJOFFSET VS. INTERNALOFFSET" -.PP -In most cases it is simplest to use the \fIinternalOffset\fR field of -a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This -makes the internal form of the value immediately available to the -widget code so the value does not have to be extracted from an object -each time it is used. However, there are two cases where the -\fIobjOffset\fR field is useful. The first case is for -\fBTK_OPTION_PIXELS\fR options. In this case, the internal form is -an integer pixel value that is valid only for a particular screen. -If the value of the option is retrieved, it will be returned as a simple -number. For example, after the command \fB.b configure \-borderwidth 2m\fR, -the command \fB.b configure \-borderwidth\fR might return 7, which is the -integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses -the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options -it is better to use the \fIobjOffset\fR field. In this case the original -value of the option is retained in the object and can be returned when -the option is retrieved. In most cases it is convenient to use the -\fIinternalOffset\fR field as well, so that the integer value is -immediately available for use in the widget code (alternatively, -\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from -the object whenever it is needed). Note: the problem of losing information -on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. -.PP -The second reason to use the \fIobjOffset\fR field is in order to -implement new types of options not supported by these procedures. -To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as -the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field -but not the \fIinternalOffset\fR field. Then, after calling -\fBTk_SetOptions\fR, convert the object to internal form yourself. -.SH "CUSTOM OPTION TYPES" -.PP -Applications can extend the built-in configuration types with -additional configuration types by writing procedures to parse, print, -free, and restore saved copies of the type and creating a structure -pointing to those procedures: -.CS -typedef struct Tk_ObjCustomOption { - char *name; - Tk_CustomOptionSetProc *\fIsetProc\fR; - Tk_CustomOptionGetProc *\fIgetProc\fR; - Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; - Tk_CustomOptionFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; -} \fBTk_ObjCustomOption\fR; - -typedef int \fBTk_CustomOptionSetProc\fR( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tk_Window \fItkwin\fR, - Tcl_Obj **\fIvaluePtr\fR, - char *\fIrecordPtr\fR, - int \fIinternalOffset\fR, - char *\fIsaveInternalPtr\fR, - int \fIflags\fR); - -typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIrecordPtr\fR, - int \fIinternalOffset\fR); - -typedef void \fBTk_CustomOptionRestoreProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIinternalPtr\fR, - char *\fIsaveInternalPtr\fR); - -typedef void \fBTk_CustomOptionFreeProc\fR( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIinternalPtr\fR); -.CE -.PP -The Tk_ObjCustomOption structure contains six fields: a name -for the custom option type; pointers to the four procedures; and a -\fIclientData\fR value to be passed to those procedures when they are -invoked. The \fIclientData\fR value typically points to a structure -containing information that is needed by the procedures when they are -parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR -may be NULL, indicating that no function should be called for those -operations. -.PP -The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to -convert a Tcl_Obj into an internal representation and store the -resulting value in the widget record. The arguments are: -.RS -.TP -\fIclientData\fR -A copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. -.TP -\fIinterp\fR -A pointer to a Tcl interpreter, used for error reporting. -.TP -\fITkwin\fR -A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR -.TP -\fIvaluePtr\fR -A pointer to a reference to a Tcl_Obj describing the new value for the -option; it could have been specified explicitly in the call to -\fBTk_SetOptions\fR or it could come from the option database or a -default. If the objOffset for the option is non-negative (the option -value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj -pointer referenced by \fIvaluePtr\fR is the pointer that will be -stored at the objOffset for the option. \fISetProc\fR may modify the -value if necessary; for example, \fIsetProc\fR may change the value to -NULL to support the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fIrecordPtr\fR -A pointer to the start of the widget record to modify. -.TP -\fIinternalOffset\fR -Offset in bytes from the start of the widget record to the location -where the internal representation of the option value is to be placed. -.TP -\fIsaveInternalPtr\fR -A pointer to storage allocated in a Tk_SavedOptions structure for the -internal representation of the original option value. Before setting -the option to its new value, \fIsetProc\fR should set the value -referenced by \fIsaveInternalPtr\fR to the original value of the -option in order to support \fBTk_RestoreSavedOptions\fR. -.TP -\fIflags\fR -A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the -option -.RE -.PP -\fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful -processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error -message may be left in the Tcl interpreter given by \fIinterp\fR in -the case of an error. -.PP -The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and -\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the -internal representation of an option. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR -is a pointer to the beginning of the widget record to query. -\fIInternalOffset\fR is the offset in bytes from the beginning of the -widget record to the location where the internal representation of the -option value is stored. \fIGetProc\fR must return a pointer to a -Tcl_Obj representing the value of the option. -.PP -The \fIrestoreProc\fR procedure is invoked by -\fBTk_RestoreSavedOptions\fR to restore a previously saved internal -representation of a custom option value. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR -is a pointer to the location where internal representation of the -option value is stored. -\fISaveInternalPtr\fR is a pointer to the saved value. -\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to -\fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not -free any memory associated with either \fIinternalPtr\fR or -\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that -memory if necessary. \fIRestoreProc\fR has no return value. -.PP -The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and -\fBTk_FreeSavedOptions\fR to free any storage allocated for the -internal representation of a custom option. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR -is a pointer to the location where the internal representation of the -option value is stored. The \fIfreeProc\fR must free any storage -associated with the option. \fIFreeProc\fR has no return value. -.SH KEYWORDS -anchor, bitmap, boolean, border, color, configuration option, -cursor, double, font, integer, justify, -pixels, relief, screen distance, synonym diff --git a/tk8.6/doc/SetVisual.3 b/tk8.6/doc/SetVisual.3 deleted file mode 100644 index 6d3fd83..0000000 --- a/tk8.6/doc/SetVisual.3 +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_SetWindowVisual \- change visual characteristics of window -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) -.SH ARGUMENTS -.AS "Tk_Window int" colormap -.AP Tk_Window tkwin in -Token for window. -.AP Visual *visual in -New visual type to use for \fItkwin\fR. -.AP "int" depth in -Number of bits per pixel desired for \fItkwin\fR. -.AP Colormap colormap in -New colormap for \fItkwin\fR, which must be compatible with -\fIvisual\fR and \fIdepth\fR. -.BE -.SH DESCRIPTION -.PP -When Tk creates a new window it assigns it the default visual -characteristics (visual, depth, and colormap) for its screen. -\fBTk_SetWindowVisual\fR may be called to change them. -\fBTk_SetWindowVisual\fR must be called before the window has -actually been created in X (e.g. before \fBTk_MapWindow\fR or -\fBTk_MakeWindowExist\fR has been invoked for the window). -The safest thing is to call \fBTk_SetWindowVisual\fR immediately -after calling \fBTk_CreateWindow\fR. -If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR -is called then it returns 0 and does not make any changes; otherwise -it returns 1 to signify that the operation -completed successfully. -.PP -Note: \fBTk_SetWindowVisual\fR should not be called if you just want -to change a window's colormap without changing its visual or depth; -call \fBTk_SetWindowColormap\fR instead. -.SH KEYWORDS -colormap, depth, visual diff --git a/tk8.6/doc/StrictMotif.3 b/tk8.6/doc/StrictMotif.3 deleted file mode 100644 index 4319d53..0000000 --- a/tk8.6/doc/StrictMotif.3 +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_StrictMotif \- Return value of tk_strictMotif variable -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_StrictMotif\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for window. -.BE -.SH DESCRIPTION -.PP -This procedure returns the current value of the \fBtk_strictMotif\fR -variable in the interpreter associated with \fItkwin\fR's application. -The value is returned as an integer that is either 0 or 1. -1 means that strict Motif compliance has been requested, so anything -that is not part of the Motif specification should be avoided. -0 means that -.QW Motif-like -is good enough, and extra features are welcome. -.PP -This procedure uses a link to the Tcl variable to provide much -faster access to the variable's value than could be had by calling -\fBTcl_GetVar\fR. -.SH KEYWORDS -Motif compliance, tk_strictMotif variable diff --git a/tk8.6/doc/TextLayout.3 b/tk8.6/doc/TextLayout.3 deleted file mode 100644 index 5729a44..0000000 --- a/tk8.6/doc/TextLayout.3 +++ /dev/null @@ -1,276 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures" -.so man.macros -.BS -.SH NAME -Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -Tk_TextLayout -\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR -.sp -void -\fBTk_FreeTextLayout(\fIlayout\fB)\fR -.sp -void -\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR -.sp -void -\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR -.sp -int -\fBTk_PointToChar(\fIlayout, x, y\fB)\fR -.sp -int -\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR -.sp -int -\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR -.sp -int -\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR -.sp -void -\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR -.SH ARGUMENTS -.AS Tk_TextLayout "*xPtr, *yPtr" -.AP Tk_Font tkfont in -Font to use when constructing and displaying a text layout. The -\fItkfont\fR must remain valid for the lifetime of the text layout. Must -have been returned by a previous call to \fBTk_GetFont\fR. -.AP "const char" *string in -Potentially multi-line string whose dimensions are to be computed and -stored in the text layout. The \fIstring\fR must remain valid for the -lifetime of the text layout. -.AP int numChars in -The number of characters to consider from \fIstring\fR. If -\fInumChars\fR is less than 0, then assumes \fIstring\fR is null -terminated and uses \fBTcl_NumUtfChars\fR to determine the length of -\fIstring\fR. -.AP int wrapLength in -Longest permissible line length, in pixels. Lines in \fIstring\fR will -automatically be broken at word boundaries and wrapped when they reach -this length. If \fIwrapLength\fR is too small for even a single -character to fit on a line, it will be expanded to allow one character to -fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic -wrapping; lines will get as long as they need to be and only wrap if a -newline/return character is encountered. -.AP Tk_Justify justify in -How to justify the lines in a multi-line text layout. Possible values -are \fBTK_JUSTIFY_LEFT\fR, \fBTK_JUSTIFY_CENTER\fR, or -\fBTK_JUSTIFY_RIGHT\fR. If the text layout only occupies a single -line, then \fIjustify\fR is irrelevant. -.AP int flags in -Various flag bits OR-ed together. \fBTK_IGNORE_TABS\fR means that tab -characters should not be expanded to the next tab stop. -\fBTK_IGNORE_NEWLINES\fR means that newline/return characters should -not cause a line break. If either tabs or newlines/returns are -ignored, then they will be treated as regular characters, being -measured and displayed in a platform-dependent manner as described in -\fBTk_MeasureChars\fR, and will not have any special behaviors. -.AP int *widthPtr out -If non-NULL, filled with either the width, in pixels, of the widest -line in the text layout, or the width, in pixels, of the bounding box for the -character specified by \fIindex\fR. -.AP int *heightPtr out -If non-NULL, filled with either the total height, in pixels, of all -the lines in the text layout, or the height, in pixels, of the bounding -box for the character specified by \fIindex\fR. -.AP Tk_TextLayout layout in -A token that represents the cached layout information about the single-font, -multi-line, justified piece of text. This token is returned by -\fBTk_ComputeTextLayout\fR. -.AP Display *display in -Display on which to draw. -.AP Drawable drawable in -Window or pixmap in which to draw. -.AP GC gc in -Graphics context to use for drawing text layout. The font selected in -this GC must correspond to the \fItkfont\fR used when constructing the -text layout. -.AP int "x, y" in -Point, in pixels, at which to place the upper-left hand corner of the -text layout when it is being drawn, or the coordinates of a point (with -respect to the upper-left hand corner of the text layout) to check -against the text layout. -.AP int firstChar in -The index of the first character to draw from the given text layout. -The number 0 means to draw from the beginning. -.AP int lastChar in -The index of the last character up to which to draw. The character -specified by \fIlastChar\fR itself will not be drawn. A number less -than 0 means to draw all characters in the text layout. -.AP int underline in -Index of the single character to underline in the text layout, or a number -less than 0 for no underline. -.AP int index in -The index of the character whose bounding box is desired. The bounding -box is computed with respect to the upper-left hand corner of the text layout. -.AP int "*xPtr, *yPtr" out -Filled with the upper-left hand corner, in pixels, of the bounding box -for the character specified by \fIindex\fR. Either or both \fIxPtr\fR -and \fIyPtr\fR may be NULL, in which case the corresponding value -is not calculated. -.AP int "width, height" in -Specifies the width and height, in pixels, of the rectangular area to -compare for intersection against the text layout. -.AP Tcl_Interp *interp out -Postscript code that will print the text layout is appended to -the result of interpreter \fIinterp\fR. -.BE -.SH DESCRIPTION -.PP -These routines are for measuring and displaying single-font, multi-line, -justified text. To measure and display simple single-font, single-line -strings, refer to the documentation for \fBTk_MeasureChars\fR. There is -no programming interface in the core of Tk that supports multi-font, -multi-line text; support for that behavior must be built on top of -simpler layers. -Note that unlike the lower level text display routines, the functions -described here all operate on character-oriented lengths and indices -rather than byte-oriented values. See the description of -\fBTcl_UtfAtIndex\fR for more details on converting between character -and byte offsets. -.PP -The routines described here are built on top of the programming interface -described in the \fBTk_MeasureChars\fR documentation. Tab characters and -newline/return characters may be treated specially by these procedures, -but all other characters are passed through to the lower level. -.PP -\fBTk_ComputeTextLayout\fR computes the layout information needed to -display a single-font, multi-line, justified \fIstring\fR of text and -returns a Tk_TextLayout token that holds this information. This token is -used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, -\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The -\fIstring\fR and \fItkfont\fR used when computing the layout must remain -valid for the lifetime of this token. -.PP -\fBTk_FreeTextLayout\fR is called to release the storage associated with -\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used -in any other text layout procedures once it has been released. -.PP -\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a -single-font, multi-line, justified string of text at the specified location. -.PP -\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to -display an underline below an individual character. This procedure does -not draw the text, just the underline. To produce natively underlined -text, an underlined font should be constructed and used. All characters, -including tabs, newline/return characters, and spaces at the ends of -lines, can be underlined using this method. However, the underline will -never be drawn outside of the computed width of \fIlayout\fR; the -underline will stop at the edge for any character that would extend -partially outside of \fIlayout\fR, and the underline will not be visible -at all for any character that would be located completely outside of the -layout. -.PP -\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the -character closest to the given point. The point is specified with respect -to the upper-left hand corner of the \fIlayout\fR, which is considered to be -located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be -considered closest to the first character in the text layout; any point -whose \fIy\fR-value is greater than the height of the text layout will be -considered closest to the last character in the text layout. Any point -whose \fIx\fR-value is less than 0 will be considered closest to the first -character on that line; any point whose \fIx\fR-value is greater than the -width of the text layout will be considered closest to the last character on -that line. The return value is the index of the character that was closest -to the point, or one more than the index of any character (to indicate that -the point was after the end of the string and that the corresponding caret -would be at the end of the string). Given a \fIlayout\fR with no characters, -the value 0 will always be returned, referring to a hypothetical zero-width -placeholder character. -.PP -\fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the -bounding box for the character specified by \fIindex\fR. The width of the -bounding box is the advance width of the character, and does not include any -left or right bearing. Any character that extends partially outside of -\fIlayout\fR is considered to be truncated at the edge. Any character -that would be located completely outside of \fIlayout\fR is considered to -be zero-width and pegged against the edge. The height of the bounding -box is the line height for this font, extending from the top of the -ascent to the bottom of the descent; information about the actual height -of individual letters is not available. For measurement purposes, a -\fIlayout\fR that contains no characters is considered to contain a -single zero-width placeholder character at index 0. If \fIindex\fR was -not a valid character index, the return value is 0 and \fI*xPtr\fR, -\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. -Otherwise, if \fIindex\fR did specify a valid, the return value is -non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and -\fI*heightPtr\fR are filled with the bounding box information for the -character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or -\fIheightPtr\fR are NULL, the corresponding value is not calculated or -stored. -.PP -\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from -the given point (\fIx, y\fR) to the characters in \fIlayout\fR. -Newline/return characters and non-displaying space characters that occur at -the end of individual lines in the text layout are ignored for hit detection -purposes, but tab characters are not. The return value is 0 if the point -actually hits the \fIlayout\fR. If the point did not hit the \fIlayout\fR -then the return value is the distance in pixels from the point to the -\fIlayout\fR. -.PP -\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies -entirely inside, entirely outside, or overlaps a given rectangle. -Newline/return characters and non-displaying space characters that occur -at the end of individual lines in the \fIlayout\fR are ignored for -intersection calculations. The return value is \-1 if the \fIlayout\fR is -entirely outside of the rectangle, 0 if it overlaps, and 1 if it is -entirely inside of the rectangle. -.PP -\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript -array of strings that represent the individual lines in \fIlayout\fR. It -is the responsibility of the caller to take the Postscript array of -strings and add some Postscript function operate on the array to render -each of the lines. The code that represents the Postscript array of -strings is appended to interpreter \fIinterp\fR's result. -.SH "DISPLAY MODEL" -.PP -When measuring a text layout, space characters that occur at the end of a -line are ignored. The space characters still exist and the insertion point -can be positioned amongst them, but their additional width is ignored when -justifying lines or returning the total width of a text layout. All -end-of-line space characters are considered to be attached to the right edge -of the line; this behavior is logical for left-justified text and reasonable -for center-justified text, but not very useful when editing right-justified -text. Spaces are considered variable width characters; the first space that -extends past the edge of the text layout is clipped to the edge, and any -subsequent spaces on the line are considered zero width and pegged against -the edge. Space characters that occur in the middle of a line of text are -not suppressed and occupy their normal space width. -.PP -Tab characters are not ignored for measurement calculations. If wrapping -is turned on and there are enough tabs on a line, the next tab will wrap -to the beginning of the next line. There are some possible strange -interactions between tabs and justification; tab positions are calculated -and the line length computed in a left-justified world, and then the -whole resulting line is shifted so it is centered or right-justified, -causing the tab columns not to align any more. -.PP -When wrapping is turned on, lines may wrap at word breaks (space or tab -characters) or newline/returns. A dash or hyphen character in the middle -of a word is not considered a word break. \fBTk_ComputeTextLayout\fR -always attempts to place at least one word on each line. If it cannot -because the \fIwrapLength\fR is too small, the word will be broken and as -much as fits placed on the line and the rest on subsequent line(s). If -\fIwrapLength\fR is so small that not even one character can fit on a -given line, the \fIwrapLength\fR is ignored for that line and one -character will be placed on the line anyhow. When wrapping is turned -off, only newline/return characters may cause a line break. -.PP -When a text layout has been created using an underlined \fItkfont\fR, -then any space characters that occur at the end of individual lines, -newlines/returns, and tabs will not be displayed underlined when -\fBTk_DrawTextLayout\fR is called, because those characters are never -actually drawn \- they are merely placeholders maintained in the -\fIlayout\fR. -.SH KEYWORDS -font diff --git a/tk8.6/doc/TkInitStubs.3 b/tk8.6/doc/TkInitStubs.3 deleted file mode 100644 index 04f5611..0000000 --- a/tk8.6/doc/TkInitStubs.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" 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. -'\" -.TH Tk_InitStubs 3 8.4 Tk "Tk Library Procedures" -.so man.macros -.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 -incorporating 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 and the \fBUSE_TK_STUBS\fR -symbols. Typically, you would include the \fB\-DUSE_TCL_STUBS\fR and -the \fB\-DUSE_TK_STUBS\fR flags 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 the library names with appropriate version -number but note that the extension may only be used with versions of -Tcl/Tk that have that version number or higher. -.SH DESCRIPTION -.PP -\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 diff --git a/tk8.6/doc/Tk_Init.3 b/tk8.6/doc/Tk_Init.3 deleted file mode 100644 index 7bc46dd..0000000 --- a/tk8.6/doc/Tk_Init.3 +++ /dev/null @@ -1,85 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_Init 3 8.0 Tk "Tk Library Procedures" -.so man.macros -.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 interpreter \fIinterp\fR's result. -.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 diff --git a/tk8.6/doc/Tk_Main.3 b/tk8.6/doc/Tk_Main.3 deleted file mode 100644 index ea5f771..0000000 --- a/tk8.6/doc/Tk_Main.3 +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tk_Main 3 4.0 Tk "Tk Library Procedures" -.so man.macros -.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. On Windows, when -using -DUNICODE, the parameter type changes to wchar_t *. -.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 \fBTcl_AppInitProc\fR( - 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. -.PP -\fBTk_Main\fR functions much the same as \fBTcl_Main\fR. In particular, -\fBTk_Main\fR supports both an interactive mode and a startup script -mode, with the file name and encoding of a startup script under the -control of the \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR -routines. However it calls \fBTk_MainLoop\fR after processing any -supplied script, and in interactive uses events registered with -\fBTcl_CreateFileHandler\fR to process user input. -.SH "SEE ALSO" -Tcl_DoOneEvent(3) -.SH KEYWORDS -application-specific initialization, command-line arguments, main program diff --git a/tk8.6/doc/WindowId.3 b/tk8.6/doc/WindowId.3 deleted file mode 100644 index f937963..0000000 --- a/tk8.6/doc/WindowId.3 +++ /dev/null @@ -1,188 +0,0 @@ -'\" -'\" 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. -'\" -.TH Tk_WindowId 3 "8.4" Tk "Tk Library Procedures" -.so man.macros -.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 diff --git a/tk8.6/doc/bell.n b/tk8.6/doc/bell.n deleted file mode 100644 index 21c4f1b..0000000 --- a/tk8.6/doc/bell.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" 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. -'\" -.TH bell n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/bind.n b/tk8.6/doc/bind.n deleted file mode 100644 index c260bce..0000000 --- a/tk8.6/doc/bind.n +++ /dev/null @@ -1,730 +0,0 @@ -'\" -'\" 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. -'\" -.TH bind n 8.0 Tk "Tk Built-In Commands" -.so man.macros -.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 called the -.QW "binding 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 -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. -.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. 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, called the -.QW "binding 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 or \fIuser_data\fR -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 -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. -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. 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%M\fR 5 -The number of script-based binding patterns matched so far for the -event. Valid for all event types. -.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 within a binding script, then this -binding script, including all other -.QW + -appended scripts, 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 -Within a script called from the binding script, \fBreturn\fR -\fB-code ok\fR may be used to continue processing (including -.QW + -appended scripts), or \fBreturn\fR \fB-code break\fR may be used to -stop processing all other binding scripts. -.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" -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/bindtags.n b/tk8.6/doc/bindtags.n deleted file mode 100644 index dc3973b..0000000 --- a/tk8.6/doc/bindtags.n +++ /dev/null @@ -1,102 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH bindtags n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.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 -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/bitmap.n b/tk8.6/doc/bitmap.n deleted file mode 100644 index ead3311..0000000 --- a/tk8.6/doc/bitmap.n +++ /dev/null @@ -1,124 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH bitmap n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -bitmap \- Images that display two colors -.SH SYNOPSIS -.nf -\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? - -\fIimageName \fBcget\fR \fIoption\fR -\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -.fi -.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\fR \fBbitmap\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\fR \fBbitmap\fR command. -.SH KEYWORDS -bitmap, image -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/busy.n b/tk8.6/doc/busy.n deleted file mode 100644 index ab2fd8a..0000000 --- a/tk8.6/doc/busy.n +++ /dev/null @@ -1,275 +0,0 @@ -'\" -'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. -'\" Copyright (c) 2008 Jos Decoster -'\" -'\" Permission to use, copy, modify, and distribute this software and its -'\" documentation for any purpose and without fee is hereby granted, provided -'\" that the above copyright notice appear in all copies and that both that -'\" the copyright notice and warranty disclaimer appear in supporting -'\" documentation, and that the names of Lucent Technologies any of their -'\" entities not be used in advertising or publicity pertaining to -'\" distribution of the software without specific, written prior permission. -'\" -'\" Lucent Technologies disclaims all warranties with regard to this software, -'\" including all implied warranties of merchantability and fitness. In no -'\" event shall Lucent Technologies be liable for any special, indirect or -'\" consequential damages or any damages whatsoever resulting from loss of -'\" use, data or profits, whether in an action of contract, negligence or -'\" other tortuous action, arising out of or in connection with the use or -'\" performance of this software. -'\" -'\" BLT::busy command created by George Howlett. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH busy n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -busy \- confine pointer events to a window sub-tree -.SH SYNOPSIS -\fBtk busy\fR \fIwindow \fR?\fIoptions\fR? -.sp -\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR? -.sp -\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... -.sp -\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?... -.sp -\fBtk busy current\fR ?\fIpattern\fR? -.sp -\fBtk busy status \fIwindow\fR -.BE -.SH DESCRIPTION -.PP -The \fBtk busy\fR command provides a simple means to block pointer events from -Tk widgets, while overriding the widget's cursor with a configurable busy -cursor. Note this command does not prevent keyboard events from being sent to -the widgets made busy. -.SH INTRODUCTION -.PP -There are many times in applications where you want to temporarily restrict -what actions the user can take. For example, an application could have a -.QW Run -button that when pressed causes some processing to occur. However, while the -application is busy processing, you probably don't want the user to be -able to click the -.QW Run -button again. You may also want restrict the user from other tasks such as -clicking a -.QW Print -button. -.PP -The \fBtk busy\fR command lets you make Tk widgets busy. This means that user -interactions such as button clicks, moving the mouse, typing at the keyboard, -etc.\0are ignored by the widget. You can set a special cursor (like a watch) -that overrides the widget's normal cursor, providing feedback that the -application (widget) is temporarily busy. -.PP -When a widget is made busy, the widget and all of its descendants will ignore -pointer events. It's easy to make an entire panel of widgets busy. You can -simply make the toplevel widget (such as -.QW . ) -busy. This is easier and far much more efficient than recursively traversing -the widget hierarchy, disabling each widget and re-configuring its cursor. -.PP -Often, the \fBtk busy\fR command can be used instead of Tk's \fBgrab\fR -command. Unlike \fBgrab\fR which restricts all user interactions to one -widget, with the \fBtk busy\fR command you can have more than one widget -active (for example, a -.QW Cancel -dialog and a -.QW Help -button). -.SS EXAMPLE -.PP -You can make several widgets busy by simply making its ancestor widget busy -using the \fBhold\fR operation. -.PP -.CS -frame .top -button .top.button; canvas .top.canvas -pack .top.button .top.canvas -pack .top -# . . . -\fBtk busy\fR hold .top -update -.CE -.PP -All the widgets within \fB.top\fR (including \fB.top\fR) are now busy. Using -\fBupdate\fR insures that \fBtk busy\fR command will take effect before any -other user events can occur. -.PP -When the application is no longer busy processing, you can allow user -interactions again and free any resources it allocated by the \fBforget\fR -operation. -.PP -.CS -\fBtk busy\fR forget .top -.CE -.PP -The busy window has a configurable cursor. You can change the busy cursor -using the \fBconfigure\fR operation. -.PP -.CS -\fBtk busy\fR configure .top \-cursor "watch" -.CE -.PP -Destroying the widget will also clean up any resources allocated by the \fBtk -busy\fR command. -.PP -.SH OPERATIONS -.PP -The following operations are available for the \fBtk busy\fR command: -.TP -\fBtk busy \fIwindow\fR ?\fIoption value\fR?... -. -Shortcut for \fBtk busy hold\fR command. -.TP -\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... -. -Makes the specified \fIwindow\fR (and its descendants in the Tk window -hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. -A transparent window is put in front of the specified window. This transparent -window is mapped the next time idle tasks are processed, and the specified -window and its descendants will be blocked from user interactions. Normally -\fBupdate\fR should be called immediately afterward to insure that the hold -operation is in effect before the application starts its processing. The -following configuration options are valid: -.RS -.TP -\fB\-cursor \fIcursorName\fR -. -Specifies the cursor to be displayed when the widget is made busy. -\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The -default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. -.RE -.TP -\fBtk busy cget \fIwindow\fR \fIoption\fR -. -Queries the \fBtk busy\fR command configuration options for \fIwindow\fR. -\fIWindow\fR must be the path name of a widget previously made busy by the -\fBhold\fR operation. The command returns the present value of the specified -\fIoption\fR. \fIOption\fR may have any of the values accepted by the -\fBhold\fR operation. -.TP -\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... -. -Queries or modifies the \fBtk busy\fR command configuration options for -\fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made -busy by the \fBhold\fR operation. If no options are specified, a list -describing all of the available options for \fIwindow\fR (see -\fBTk_ConfigureInfo\fR for information on the format of this list) is -returned. 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 the empty string. \fIOption\fR may have any of -the values accepted by the \fBhold\fR operation. -.RS -.PP -Please note that the option database is referenced through \fIwindow\fR. For -example, if the widget \fB.frame\fR is to be made busy, the busy cursor can be -specified for it by either \fBoption\fR command: -.PP -.CS -option add *frame.busyCursor gumby -option add *Frame.BusyCursor gumby -.CE -.RE -.TP -\fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... -. -Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR, -including the transparent window. User events will again be received by -\fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. -\fIWindow\fR must be the name of a widget specified in the \fBhold\fR -operation, otherwise an error is reported. -.TP -\fBtk busy current \fR?\fIpattern\fR? -. -Returns the pathnames of all widgets that are currently busy. If a -\fIpattern\fR is given, only the path names of busy widgets matching -\fIpattern\fR are returned. -.TP -\fBtk busy status \fIwindow\fR -. -Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not -receive user interactions, \fB1\fR is returned, otherwise \fB0\fR. -.SH "EVENT HANDLING" -.SS BINDINGS -.PP -The event blocking feature is implemented by creating and mapping a -transparent window that completely covers the widget. When the busy window is -mapped, it invisibly shields the widget and its hierarchy from all events that -may be sent. Like Tk widgets, busy windows have widget names in the Tk window -hierarchy. This means that you can use the \fBbind\fR command, to handle -events in the busy window. -.PP -.CS -\fBtk busy\fR hold .frame.canvas -bind .frame.canvas_Busy <Enter> { ... } -.CE -.PP -Normally the busy window is a sibling of the widget. The name of the busy -window is -.QW \fIwidget\fB_Busy\fR -where \fIwidget\fR is the name of the widget to be made busy. In the previous -example, the pathname of the busy window is -.QW \fB.frame.canvas_Busy\fR . -The exception is when the widget is a toplevel widget (such as -.QW . ) -where the busy window can't be made a sibling. The busy window is then a child -of the widget named -.QW \fIwidget\fB._Busy\fR -where \fIwidget\fR is the name of the toplevel widget. In the following -example, the pathname of the busy window is -.QW \fB._Busy\fR . -.PP -.CS -\fBtk busy\fR hold . -bind ._Busy <Enter> { ... } -.CE -.SS "ENTER/LEAVE EVENTS" -.PP -Mapping and unmapping busy windows generates Enter/Leave events for all -widgets they cover. Please note this if you are tracking Enter/Leave events in -widgets. -.SS "KEYBOARD EVENTS" -.PP -When a widget is made busy, the widget is prevented from gaining the keyboard -focus by a user clicking on it by the busy window. But if the widget already had -focus, it still may receive keyboard events. The widget can also still receive -focus through keyboard traversal. To prevent this, you must move -focus to another window and make sure the focus can not go back to the widgets -made busy (e.g. but restricting focus to a cancel button). -.PP -.CS -pack [frame .frame] -pack [text .frame.text] -\fBtk busy\fR hold .frame -pack [button .cancel -text "Cancel" -command exit] -focus .cancel -bind .cancel <Tab> {break} -bind .cancel <Shift-Tab> {break} -update -.CE -.PP -The above example moves the focus from .frame immediately after invoking the -\fBhold\fR so that no keyboard events will be sent to \fB.frame\fR or any of -its descendants. It also makes sure it's not possible to leave button -\fB.cancel\fR using the keyboard. -.SH PORTABILITY -.PP -Note that the \fBtk busy\fR command does not currently have any effect on OSX -when Tk is built using Aqua support. -.SH "SEE ALSO" -grab(n) -.SH KEYWORDS -busy, keyboard events, pointer events, window -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/button.n b/tk8.6/doc/button.n deleted file mode 100644 index 233feb6..0000000 --- a/tk8.6/doc/button.n +++ /dev/null @@ -1,210 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH button n 4.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -button \- Create and manipulate 'button' action 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 -\fB\-foreground\fR and \fB\-background\fR options. The active state is -typically used when the pointer is over the button. In active state -the button is displayed using the \fB\-activeforeground\fR and -\fB\-activebackground\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 \fB\-disabledforeground\fR and -\fB\-background\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 \fB\-wraplength\fR option) and -one of the characters may optionally be underlined using the -\fB\-underline\fR option. -It can display itself in either of three different ways, according -to -the \fB\-state\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 the configured activebackground -and background 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 "PLATFORM NOTES" -.PP -On Aqua/Mac OS X, some configuration options are ignored for the purpose of -drawing of the widget because they would otherwise conflict with platform -guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still -manipulate the values, but do not cause any variation to the look of the -widget. The options affected notably include \fB\-background\fR and -\fB\-relief\fR. -.SH EXAMPLES -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/canvas.n b/tk8.6/doc/canvas.n deleted file mode 100644 index 5b65283..0000000 --- a/tk8.6/doc/canvas.n +++ /dev/null @@ -1,1923 +0,0 @@ -'\" -'\" Copyright (c) 1992-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1997-1999 Scriptics Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH canvas n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets -.SH SYNOPSIS -\fBcanvas\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-borderwidth \-cursor -\-highlightbackground \-highlightcolor \-highlightthickness -\-insertbackground \-insertborderwidth \-insertofftime -\-insertontime \-insertwidth \-relief -\-selectbackground \-selectborderwidth \-selectforeground -\-takefocus \-xscrollcommand \-yscrollcommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-closeenough closeEnough CloseEnough -Specifies a floating-point value indicating how close the mouse cursor -must be to an item before it is considered to be -.QW inside -the item. Defaults to 1.0. -.OP \-confine confine Confine -Specifies a boolean value that indicates whether or not it should be -allowable to set the canvas's view outside the region defined by the -\fBscrollRegion\fR argument. -Defaults to true, which means that the view will -be constrained within the scroll region. -.OP \-height height Height -Specifies a desired window height that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the \fBCOORDINATES\fR section below. -.OP \-scrollregion scrollRegion ScrollRegion -Specifies a list with four coordinates describing the left, top, right, and -bottom coordinates of a rectangular region. -This region is used for scrolling purposes and is considered to be -the boundary of the information in the canvas. -Each of the coordinates may be specified -in any of the forms given in the \fBCOORDINATES\fR section below. -.OP \-state state State -Modifies the default state of the canvas where \fIstate\fR may be set to -one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas -objects all have their own state option which may override the default -state. Many options can take separate specifications such that the -appearance of the item can be different in different situations. The -options that start with \fBactive\fR control the appearance when the mouse -pointer is over it, while the option starting with \fBdisabled\fR controls -the appearance when the state is disabled. Canvas items which are -\fBdisabled\fR will not react to canvas bindings. -.OP \-width width width -Specifies a desired window width that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the \fBCOORDINATES\fR section below. -.OP \-xscrollincrement xScrollIncrement ScrollIncrement -Specifies an increment for horizontal scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the horizontal view in the window will be constrained so that -the canvas x coordinate at the left edge of the window is always an even -multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling -(e.g., the change in view when the left and right arrows of a scrollbar -are selected) will also be \fBxScrollIncrement\fR. If the value of -this option is less than or equal to zero, then horizontal scrolling -is unconstrained. -.OP \-yscrollincrement yScrollIncrement ScrollIncrement -Specifies an increment for vertical scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the vertical view in the window will be constrained so that -the canvas y coordinate at the top edge of the window is always an even -multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling -(e.g., the change in view when the top and bottom arrows of a scrollbar -are selected) will also be \fByScrollIncrement\fR. If the value of -this option is less than or equal to zero, then vertical scrolling -is unconstrained. -.BE -.SH INTRODUCTION -.PP -The \fBcanvas\fR command creates a new window (given -by the \fIpathName\fR argument) and makes it into a canvas widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the canvas such as its colors and 3-D relief. -The \fBcanvas\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 -Canvas widgets implement structured graphics. -A canvas displays any number of \fIitems\fR, which may be things like -rectangles, circles, lines, and text. -Items may be manipulated (e.g. moved or re-colored) and commands may -be associated with items in much the same way that the \fBbind\fR -command allows commands to be bound to widgets. For example, -a particular command may be associated with the <Button-1> event -so that the command is invoked whenever button 1 is pressed with -the mouse cursor over an item. -This means that items in a canvas can have behaviors defined by -the Tcl scripts bound to them. -.SH "DISPLAY LIST" -.PP -The items in a canvas are ordered for purposes of display, -with the first item in the display list being displayed -first, followed by the next item in the list, and so on. -Items later in the display list obscure those that are -earlier in the display list and are sometimes referred to as being -.QW "on top" -of earlier items. -When a new item is created it is placed at the end of the -display list, on top of everything else. -Widget commands may be used to re-arrange the order of the -display list. -.PP -Window items are an exception to the above rules. The underlying -window systems require them always to be drawn on top of other items. -In addition, the stacking order of window items -is not affected by any of the canvas widget commands; you must use -the Tk \fBraise\fR command and \fBlower\fR command instead. -.SH "ITEM IDS AND TAGS" -.PP -Items in a canvas widget may be named in either of two ways: -by id or by tag. -Each item has a unique identifying number, which is assigned to -that item when it is created. The id of an item never changes -and id numbers are never re-used within the lifetime of a -canvas widget. -.PP -Each item may also have any number of \fItags\fR associated -with it. A tag is just a string of characters, and it may -take any form except that of an integer. -For example, -.QW x123 -is OK but -.QW 123 -is not. -The same tag may be associated with many different items. -This is commonly done to group items in various interesting -ways; for example, all selected items might be given the tag -.QW selected . -.PP -The tag \fBall\fR is implicitly associated with every item -in the canvas; it may be used to invoke operations on -all the items in the canvas. -.PP -The tag \fBcurrent\fR is managed automatically by Tk; -it applies to the \fIcurrent item\fR, which is the -topmost item whose drawn area covers the position of -the mouse cursor (different item types interpret this in varying ways; see the -individual item type documentation for details). -If the mouse is not in the canvas widget or is not over -an item, then no item has the \fBcurrent\fR tag. -.PP -When specifying items in canvas widget commands, if the -specifier is an integer then it is assumed to refer to -the single item with that id. -If the specifier is not an integer, then it is assumed to -refer to all of the items in the canvas that have a tag -matching the specifier. -The symbol \fItagOrId\fR is used below to indicate that -an argument specifies either an id that selects a single -item or a tag that selects zero or more items. -.PP -\fItagOrId\fR may contain a logical expressions of -tags by using operators: -.QW \fB&&\fR , -.QW \fB||\fR , -.QW \fB^\fR , -.QW \fB!\fR , -and parenthesized subexpressions. For example: -.CS - .c find withtag {(a&&!b)||(!a&&b)} -.CE -or equivalently: -.CS - .c find withtag {a^b} -.CE -will find only those items with either -.QW a -or -.QW b -tags, but not both. -.PP -Some widget commands only operate on a single item at a -time; if \fItagOrId\fR is specified in a way that -names multiple items, then the normal behavior is for -the command to use the first (lowest) of these items in -the display list that is suitable for the command. -Exceptions are noted in the widget command descriptions -below. -.SH "COORDINATES" -.PP -All coordinates related to canvases are stored as floating-point -numbers. -Coordinates and distances are specified in screen units, -which are floating-point numbers optionally followed -by one of several letters. -If no letter is supplied then the distance is in pixels. -If the letter is \fBm\fR then the distance is in millimeters on -the screen; if it is \fBc\fR then the distance is in centimeters; -\fBi\fR means inches, and \fBp\fR means printers points (1/72 inch). -Larger y-coordinates refer to points lower on the screen; larger -x-coordinates refer to points farther to the right. -Coordinates can be specified either as an even number of parameters, -or as a single list parameter containing an even number of x and y -coordinate values. -.SS TRANSFORMATIONS -.PP -Normally the origin of the canvas coordinate system is at the -upper-left corner of the window containing the canvas. -It is possible to adjust the origin of the canvas -coordinate system relative to the origin of the window using the -\fBxview\fR and \fByview\fR widget commands; this is typically used -for scrolling. -Canvases do not support scaling or rotation of the canvas coordinate -system relative to the window coordinate system. -.PP -Individual items may be moved or scaled using widget commands -described below, but they may not be rotated. -.PP -Note that the default origin of the canvas's visible area is -coincident with the origin for the whole window as that makes bindings -using the mouse position easier to work with; you only need to use the -\fBcanvasx\fR and \fBcanvasy\fR widget commands if you adjust the -origin of the visible area. However, this also means that any focus -ring (as controlled by the \fB\-highlightthickness\fR option) and -window border (as controlled by the \fB\-borderwidth\fR option) must -be taken into account before you get to the visible area of the -canvas. -.SH "INDICES" -.PP -Text items support the notion of an \fIindex\fR for identifying -particular positions within the item. -In a similar fashion, line and polygon items support \fIindex\fR for -identifying, inserting and deleting subsets of their coordinates. -Indices are used for commands such as inserting or deleting -a range of characters or coordinates, and setting the insertion -cursor position. An index may be specified in any of a number -of ways, and different types of items may support different forms -for specifying indices. -Text items support the following forms for an index; if you -define new types of text-like items, it would be advisable to -support as many of these forms as practical. -Note that it is possible to refer to the character just after -the last one in the text item; this is necessary for such -tasks as inserting new text at the end of the item. -Lines and Polygons do not support the insertion cursor -and the selection. Their indices are supposed to be even -always, because coordinates always appear in pairs. -.TP 10 -\fInumber\fR -. -A decimal number giving the position of the desired character -within the text item. -0 refers to the first character, 1 to the next character, and -so on. If indexes are odd for lines and polygons, they will be -automatically decremented by one. -A number less than 0 is treated as if it were zero, and a -number greater than the length of the text item is treated -as if it were equal to the length of the text item. For -polygons, numbers less than 0 or greater than the length -of the coordinate list will be adjusted by adding or subtracting -the length until the result is between zero and the length, -inclusive. -.TP 10 -\fBend\fR -. -Refers to the character or coordinate just after the last one -in the item (same as the number of characters or coordinates -in the item). -.TP 10 -\fBinsert\fR -. -Refers to the character just before which the insertion cursor -is drawn in this item. Not valid for lines and polygons. -.TP 10 -\fBsel.first\fR -. -Refers to the first selected character in the item. -If the selection is not in this item then this form is illegal. -.TP 10 -\fBsel.last\fR -. -Refers to the last selected character in the item. -If the selection is not in this item then this form is illegal. -.TP 10 -\fB@\fIx,y\fR -. -Refers to the character or coordinate at the point given by \fIx\fR and -\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate -system of the canvas. -If \fIx\fR and \fIy\fR lie outside the coordinates covered by the -text item, then they refer to the first or last character in the -line that is closest to the given point. -.SH "DASH PATTERNS" -.PP -Many items support the notion of a dash pattern for outlines. -.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 cannot -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 which support only a limited set of dash patterns, the dash -pattern will be displayed as the closest dash pattern that is available. -For example, on Windows only the first 4 of the above examples are -available. The last 2 examples will be displayed identically to the first -one. -.SH "WIDGET COMMAND" -.PP -The \fBcanvas\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 widget commands are possible for canvas widgets: -.TP -\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR? -. -For each item that meets the constraints specified by -\fIsearchSpec\fR and the \fIarg\fRs, add -\fItag\fR to the list of tags associated with the item if it -is not already present on that list. -It is possible that no items will satisfy the constraints -given by \fIsearchSpec\fR and \fIarg\fRs, in which case the -command has no effect. -This command returns an empty string as result. -\fISearchSpec\fR and \fIarg\fR's may take any of the following -forms: -.RS -.TP -\fBabove \fItagOrId\fR -. -Selects the item just after (above) the one given by \fItagOrId\fR -in the display list. -If \fItagOrId\fR denotes more than one item, then the last (topmost) -of these items in the display list is used. -.TP -\fBall\fR -. -Selects all the items in the canvas. -.TP -\fBbelow \fItagOrId\fR -. -Selects the item just before (below) the one given by \fItagOrId\fR -in the display list. -If \fItagOrId\fR denotes more than one item, then the first (lowest) -of these items in the display list is used. -.TP -\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR? -. -Selects the item closest to the point given by \fIx\fR and \fIy\fR. -If more than one item is at the same closest distance (e.g. two -items overlap the point), then the top-most of these items (the -last one in the display list) is used. -If \fIhalo\fR is specified, then it must be a non-negative -value. -Any item closer than \fIhalo\fR to the point is considered to -overlap it. -The \fIstart\fR argument may be used to step circularly through -all the closest items. -If \fIstart\fR is specified, it names an item using a tag or id -(if by tag, it selects the first item in the display list with -the given tag). -Instead of selecting the topmost closest item, this form will -select the topmost closest item that is below \fIstart\fR in -the display list; if no such item exists, then the selection -behaves as if the \fIstart\fR argument had not been specified. -.TP -\fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR -. -Selects all the items completely enclosed within the rectangular -region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be -no greater than \fIy2\fR. -.TP -\fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR -. -Selects all the items that overlap or are enclosed within the -rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, -and \fIy2\fR. -\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be -no greater than \fIy2\fR. -.TP -\fBwithtag \fItagOrId\fR -. -Selects all the items given by \fItagOrId\fR. -.RE -.TP -\fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? -. -Returns a list with four elements giving an approximate bounding box -for all the items named by the \fItagOrId\fR arguments. -The list has the form -.QW "\fIx1 y1 x2 y2\fR" -such that the drawn -areas of all the named elements are within the region bounded by -\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top, -and \fIy2\fR on the bottom. -The return value may overestimate the actual bounding box by -a few pixels. -If no items match any of the \fItagOrId\fR arguments or if the -matching items have empty bounding boxes (i.e. they have nothing -to display) -then an empty string is returned. -.TP -\fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? -. -This command associates \fIcommand\fR with all the items given by -\fItagOrId\fR such that whenever the event sequence given by -\fIsequence\fR occurs for one of the items the command will -be invoked. -This widget command is similar to the \fBbind\fR command except that -it operates on items in a canvas rather than entire widgets. -See the \fBbind\fR manual entry for complete details -on the syntax of \fIsequence\fR and the substitutions performed -on \fIcommand\fR before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same \fIsequence\fR and \fItagOrId\fR -(if the first character of \fIcommand\fR is -.QW + -then \fIcommand\fR augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If \fIcommand\fR is omitted then the command returns the \fIcommand\fR -associated with \fItagOrId\fR and \fIsequence\fR (an error occurs -if there is no such binding). -If both \fIcommand\fR and \fIsequence\fR are omitted then the command -returns a list of all the sequences for which bindings have been -defined for \fItagOrId\fR. -.RS -.PP -The only events for which bindings may be specified are those related to -the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, -\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. -The handling of events in canvases uses the current item defined in -\fBITEM IDS AND TAGS\fR above. \fBEnter\fR and \fBLeave\fR events -trigger for an -item when it becomes the current item or ceases to be the current item; -note that these events are different than \fBEnter\fR and \fBLeave\fR -events for windows. Mouse-related events are directed to the current -item, if any. Keyboard-related events are directed to the focus item, if -any (see the \fBfocus\fR widget command below for more on this). If a -virtual event is used in a binding, that binding can trigger only if the -virtual event is defined by an underlying mouse-related or -keyboard-related event. -.PP -It is possible for multiple bindings to match a particular event. -This could occur, for example, if one binding is associated with the -item's id and another is associated with one of the item's tags. -When this occurs, all of the matching bindings are invoked. -A binding associated with the \fBall\fR tag is invoked first, -followed by one binding for each of the item's tags (in order), -followed by a binding associated with the item's id. -If there are multiple matching bindings for a single tag, -then only the most specific binding is invoked. -A \fBcontinue\fR command in a binding script terminates that -script, and a \fBbreak\fR command terminates that script -and skips any remaining scripts for the event, just as for the -\fBbind\fR command. -.PP -If bindings have been created for a canvas window using the \fBbind\fR -command, then they are invoked in addition to bindings created for -the canvas's items using the \fBbind\fR widget command. -The bindings for items will be invoked before any of the bindings -for the window as a whole. -.RE -.TP -\fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? -. -Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns -the canvas x-coordinate that is displayed at that location. -If \fIgridspacing\fR is specified, then the canvas coordinate is -rounded to the nearest multiple of \fIgridspacing\fR units. -.TP -\fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? -. -Given a window y-coordinate in the canvas \fIscreeny\fR this command returns -the canvas y-coordinate that is displayed at that location. -If \fIgridspacing\fR is specified, then the canvas coordinate is -rounded to the nearest multiple of \fIgridspacing\fR units. -.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 \fBcanvas\fR -command. -.TP -\fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption 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 \fBcanvas\fR -command. -.TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? -.TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIcoordList\fR? -. -Query or modify the coordinates that define an item. -If no coordinates are specified, this command returns a list -whose elements are the coordinates of the item named by -\fItagOrId\fR. -If coordinates are specified, then they replace the current -coordinates for the named item. -If \fItagOrId\fR refers to multiple items, then -the first one in the display list is used. -.RS -.PP -Note that for rectangles, ovals and arcs the returned list of coordinates -has a fixed order, namely the left, top, right and bottom coordinates, -which may not be the order originally given. Also the coordinates are always -returned in screen units with no units (that is, in pixels). So if the -original coordinates were specified for instance in centimeters or inches, -the returned values will nevertheless be in pixels. -.RE -.TP -\fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? -.TP -\fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR? -. -Create a new item in \fIpathName\fR of type \fItype\fR. -The exact format of the arguments after \fItype\fR depends -on \fItype\fR, but usually they consist of the coordinates for -one or more points, followed by specifications for zero or -more item options. -See the subsections on individual item types below for more -on the syntax of this command. -This command returns the id for the new item. -.TP -\fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? -. -For each item given by \fItagOrId\fR, delete the characters, or coordinates, -in the range given by \fIfirst\fR and \fIlast\fR, inclusive. -If some of the items given by \fItagOrId\fR do not support -indexing operations then they ignore this operation. -Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, -line and polygon items interpret them as indices to a coordinate (an x,y pair). -Indices are described in \fBINDICES\fR above. -If \fIlast\fR is omitted, it defaults to \fIfirst\fR. -This command returns an empty string. -.TP -\fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? -. -Delete each of the items given by each \fItagOrId\fR, and return -an empty string. -.TP -\fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? -. -For each of the items given by \fItagOrId\fR, delete the -tag given by \fItagToDelete\fR from the list of those -associated with the item. -If an item does not have the tag \fItagToDelete\fR then -the item is unaffected by the command. -If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. -This command returns an empty string. -.TP -\fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR? -. -This command returns a list consisting of all the items that -meet the constraints specified by \fIsearchCommand\fR and -\fIarg\fR's. -\fISearchCommand\fR and \fIargs\fR have any of the forms -accepted by the \fBaddtag\fR command. -The items are returned in stacking order, with the lowest item first. -.TP -\fIpathName \fBfocus \fR?\fItagOrId\fR? -. -Set the keyboard focus for the canvas widget to the item given by -\fItagOrId\fR. -If \fItagOrId\fR refers to several items, then the focus is set -to the first such item in the display list that supports the -insertion cursor. -If \fItagOrId\fR does not refer to any items, or if none of them -support the insertion cursor, then the focus is not changed. -If \fItagOrId\fR is an empty -string, then the focus item is reset so that no item has the focus. -If \fItagOrId\fR is not specified then the command returns the -id for the item that currently has the focus, or an empty string -if no item has the focus. -.RS -.PP -Once the focus has been set to an item, the item will display -the insertion cursor and all keyboard events will be directed -to that item. -The focus item within a canvas and the focus window on the -screen (set with the \fBfocus\fR command) are totally independent: -a given item does not actually have the input focus unless (a) -its canvas is the focus window and (b) the item is the focus item -within the canvas. -In most cases it is advisable to follow the \fBfocus\fR widget -command with the \fBfocus\fR command to set the focus window to -the canvas (if it was not there already). -.RE -.TP -\fIpathName \fBgettags\fR \fItagOrId\fR -. -Return a list whose elements are the tags associated with the -item given by \fItagOrId\fR. -If \fItagOrId\fR refers to more than one item, then the tags -are returned from the first such item in the display list. -If \fItagOrId\fR does not refer to any items, or if the item -contains no tags, then an empty string is returned. -.TP -\fIpathName \fBicursor \fItagOrId index\fR -. -Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR -to just before the character whose position is given by \fIindex\fR. -If some or all of the items given by \fItagOrId\fR do not support -an insertion cursor then this command has no effect on them. -See \fBINDICES\fR above for a description of the -legal forms for \fIindex\fR. -Note: the insertion cursor is only displayed in an item if -that item currently has the keyboard focus (see the \fBfocus\fR widget -command, above), but the cursor position may -be set even when the item does not have the focus. -This command returns an empty string. -.TP -\fIpathName \fBimove \fItagOrId index x y\fR -.VS 8.6 -This command causes the \fIindex\fR'th coordinate of each of the items -indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). -Each item interprets \fIindex\fR independently according to the rules -described in \fBINDICES\fR above. Out of the standard set of items, only line -and polygon items may have their coordinates relocated this way. -.VE 8.6 -.TP -\fIpathName \fBindex \fItagOrId index\fR -. -This command returns a decimal string giving the numerical index -within \fItagOrId\fR corresponding to \fIindex\fR. -\fIIndex\fR gives a textual description of the desired position -as described in \fBINDICES\fR above. -Text items interpret \fIindex\fR as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -The return value is guaranteed to lie between 0 and the number -of characters, or coordinates, within the item, inclusive. -If \fItagOrId\fR refers to multiple items, then the index -is processed in the first of these items that supports indexing -operations (in display list order). -.TP -\fIpathName \fBinsert \fItagOrId beforeThis string\fR -. -For each of the items given by \fItagOrId\fR, if the item supports -text or coordinate, insertion then \fIstring\fR is inserted into the item's -text just before the character, or coordinate, whose index is \fIbeforeThis\fR. -Text items interpret \fIbeforeThis\fR as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -For lines and polygons the \fIstring\fR must be a valid coordinate -sequence. -See \fBINDICES\fR above for information about the forms allowed -for \fIbeforeThis\fR. -This command returns an empty string. -.TP -\fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR -. -Returns the current value of the configuration option for the -item given by \fItagOrId\fR whose name is \fIoption\fR. -This command is similar to the \fBcget\fR widget command except that -it applies to a particular item rather than the widget as a whole. -\fIOption\fR may have any of the values accepted by the \fBcreate\fR -widget command when the item was created. -If \fItagOrId\fR is a tag that refers to more than one item, -the first (lowest) such item is used. -.TP -\fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -. -This command is similar to the \fBconfigure\fR widget command except -that it modifies item-specific options for the items given by -\fItagOrId\fR instead of modifying options for the overall -canvas widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the first item given by \fItagOrId\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 -each of the items given by \fItagOrId\fR; in -this case the command returns an empty string. -The \fIoption\fRs and \fIvalue\fRs are the same as those permissible -in the \fBcreate\fR widget command when the item(s) were created; -see the sections describing individual item types below for details -on the legal options. -.TP -\fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? -. -Move all of the items given by \fItagOrId\fR to a new position -in the display list just before the item given by \fIbelowThis\fR. -If \fItagOrId\fR refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -\fIBelowThis\fR is a tag or id; if it refers to more than one -item then the first (lowest) of these items in the display list is used -as the destination location for the moved items. -Note: this command has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR command and \fBlower\fR command, not the -\fBraise\fR widget command and \fBlower\fR widget command for canvases. -This command returns an empty string. -.TP -\fIpathName \fBmove \fItagOrId xAmount yAmount\fR -. -Move each of the items given by \fItagOrId\fR in the canvas coordinate -space by adding \fIxAmount\fR to the x-coordinate of each point -associated with the item and \fIyAmount\fR to the y-coordinate of -each point associated with the item. -This command returns an empty string. -.TP -\fIpathName \fBmoveto \fItagOrId xPos yPos\fR -.VS 8.6 -Move the items given by \fItagOrId\fR in the canvas coordinate -space so that the first coordinate pair of the bottommost item with -tag \fItagOrId\fR is located at -position (\fIxPos\fR,\fIyPos\fR). \fIxPos\fR and \fIyPos\fR may be -the empty string, in which case the corresponding coordinate -will be unchanged. All items matching -\fItagOrId\fR remain in the same positions relative to each other. -This command returns an empty string. -.VE 8.6 -.TP -\fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? -. -Generate a Postscript representation for part or all of the canvas. -If the \fB\-file\fR option is specified then the Postscript is written -to a file and an empty string is returned; otherwise the Postscript -is returned as the result of the command. -If the interpreter that owns the canvas is marked as safe, the operation -will fail because safe interpreters are not allowed to write files. -If the \fB\-channel\fR option is specified, the argument denotes the name -of a channel already opened for writing. The Postscript is written to -that channel, and the channel is left open for further writing at the end -of the operation. -The Postscript is created in Encapsulated Postscript form using -version 3.0 of the Document Structuring Conventions. -Note: by default Postscript is only generated for information that -appears in the canvas's window on the screen. If the canvas is -freshly created it may still have its initial size of 1x1 pixel -so nothing will appear in the Postscript. To get around this problem -either invoke the \fBupdate\fR command to wait for the canvas window -to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR -options to specify the area of the canvas to print. -The \fIoption\fR\-\fIvalue\fR argument pairs provide additional -information to control the generation of Postscript. The following -options are supported: -.RS -.TP -\fB\-channel \fIchannelName\fR -. -Specifies the name of the channel to which to write the Postscript. -If this option and the \fB\-file\fR option are -not specified then the Postscript is returned as the -result of the command. -.TP -\fB\-colormap \fIvarName\fR -. -\fIVarName\fR must be the name of an array variable -that specifies a color mapping to use in the Postscript. -Each element of \fIvarName\fR must consist of Postscript -code to set a particular color value (e.g. -.QW "\fB1.0 1.0 0.0 setrgbcolor\fR" ). -When outputting color information in the Postscript, Tk checks -to see if there is an element of \fIvarName\fR with the same -name as the color. -If so, Tk uses the value of the element as the Postscript command -to set the color. -If this option has not been specified, or if there is no entry -in \fIvarName\fR for a given color, then Tk uses the red, green, -and blue intensities from the X color. -.TP -\fB\-colormode \fImode\fR -. -Specifies how to output color information. \fIMode\fR must be either -\fBcolor\fR (for full color output), \fBgray\fR (convert all colors -to their gray-scale equivalents) or \fBmono\fR (convert all colors -to black or white). -.TP -\fB\-file \fIfileName\fR -. -Specifies the name of the file in which to write the Postscript. -If this option and the \fB\-channel\fR option are -not specified then the Postscript is returned as the -result of the command. -.TP -\fB\-fontmap \fIvarName\fR -. -\fIVarName\fR must be the name of an array variable -that specifies a font mapping to use in the Postscript. -Each element of \fIvarName\fR must consist of a Tcl list with -two elements, which are the name and point size of a Postscript font. -When outputting Postscript commands for a particular font, Tk -checks to see if \fIvarName\fR contains an element with the same -name as the font. -If there is such an element, then the font information contained in -that element is used in the Postscript. -Otherwise Tk attempts to guess what Postscript font to use. -Tk's guesses generally only work for well-known fonts such as -Times and Helvetica and Courier, and only if the X font name does not -omit any dashes up through the point size. -For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but -\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to -parse the font name). -.TP -\fB\-height \fIsize\fR -. -Specifies the height of the area of the canvas to print. -Defaults to the height of the canvas window. -.TP -\fB\-pageanchor \fIanchor\fR -. -Specifies which point of the printed area of the canvas should appear over -the positioning point on the page (which is given by the \fB\-pagex\fR -and \fB\-pagey\fR options). -For example, \fB\-pageanchor n\fR means that the top center of the -area of the canvas being printed (as it appears in the canvas window) -should be over the positioning point. Defaults to \fBcenter\fR. -.TP -\fB\-pageheight \fIsize\fR -. -Specifies that the Postscript should be scaled in both x and y so -that the printed area is \fIsize\fR high on the Postscript page. -\fISize\fR consists of a floating-point number followed by -\fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, -or \fBp\fR or nothing for printer's points (1/72 inch). -Defaults to the height of the printed area on the screen. -If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then -the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling -is not implemented). -.TP -\fB\-pagewidth \fIsize\fR -. -Specifies that the Postscript should be scaled in both x and y so -that the printed area is \fIsize\fR wide on the Postscript page. -\fISize\fR has the same form as for \fB\-pageheight\fR. -Defaults to the width of the printed area on the screen. -If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then -the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling -is not implemented). -.TP -\fB\-pagex \fIposition\fR -. -\fIPosition\fR gives the x-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. -Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. -.TP -\fB\-pagey \fIposition\fR -. -\fIPosition\fR gives the y-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. -Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. -.TP -\fB\-rotate \fIboolean\fR -. -\fIBoolean\fR specifies whether the printed area is to be rotated 90 -degrees. -In non-rotated output the x-axis of the printed area runs along -the short dimension of the page -.PQ portrait " orientation" ; -in rotated output the x-axis runs along the long dimension of the page -.PQ landscape " orientation" . -Defaults to non-rotated. -.TP -\fB\-width \fIsize\fR -. -Specifies the width of the area of the canvas to print. -Defaults to the width of the canvas window. -.TP -\fB\-x \fIposition\fR -. -Specifies the x-coordinate of the left edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the left edge of the window. -.TP -\fB\-y \fIposition\fR -. -Specifies the y-coordinate of the top edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the top edge of the window. -.RE -.TP -\fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? -. -Move all of the items given by \fItagOrId\fR to a new position -in the display list just after the item given by \fIaboveThis\fR. -If \fItagOrId\fR refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -\fIAboveThis\fR is a tag or id; if it refers to more than one -item then the last (topmost) of these items in the display list is used -as the destination location for the moved items. -This command returns an empty string. -.RS -.PP -Note: this command has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR command and \fBlower\fR command, not the -\fBraise\fR widget command and \fBlower\fR widget command for canvases. -.RE -.TP -\fIpathName \fBrchars \fItagOrId first last string\fR -.VS 8.6 -This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR -for each of the items indicated by \fItagOrId\fR to be replaced by -\fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently -according to the rules described in \fBINDICES\fR above. Out of the standard -set of items, text items support this operation by altering their text as -directed, and line and polygon items support this operation by altering their -coordinate list (in which case \fIstring\fR should be a list of coordinates to -use as a replacement). The other items ignore this operation. -.VE 8.6 -.TP -\fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR -. -Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas -coordinate space. -\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling -operation and \fIxScale\fR and \fIyScale\fR identify the scale -factors for x- and y-coordinates, respectively (a scale factor of -1.0 implies no change to that coordinate). -For each of the points defining each item, the x-coordinate is -adjusted to change the distance from \fIxOrigin\fR by a factor -of \fIxScale\fR. -Similarly, each y-coordinate is adjusted to change the distance -from \fIyOrigin\fR by a factor of \fIyScale\fR. -This command returns an empty string. -.RS -.PP -Note that some items have only a single pair of coordinates (e.g., text, -images and windows) and so scaling of them by this command can only move them -around. -.RE -.TP -\fIpathName \fBscan\fR \fIoption args\fR -. -This command is used to implement scanning on canvases. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -. -Records \fIx\fR and \fIy\fR and the canvas's current view; used -in conjunction with later \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget and \fIx\fR and \fIy\fR are the coordinates of the -mouse. It returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx y ?gain?\fR -. -This command computes the difference between its \fIx\fR and \fIy\fR -arguments (which are typically mouse coordinates) and the \fIx\fR and -\fIy\fR arguments to the last \fBscan mark\fR command for the widget. -It then adjusts the view by \fIgain\fR times the -difference in coordinates, where \fIgain\fR defaults to 10. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the canvas at high speed through its window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? -. -Manipulates the selection in one of several ways, depending on -\fIoption\fR. -The command may take any of the forms described below. -In all of the descriptions below, \fItagOrId\fR must refer to -an item that supports indexing and selection; if it refers to -multiple items then the first of -these that supports indexing and the selection is used. -\fIIndex\fR gives a textual description of a position -within \fItagOrId\fR, as described in \fBINDICES\fR above. -.RS -.TP -\fIpathName \fBselect adjust \fItagOrId index\fR -. -Locate the end of the selection in \fItagOrId\fR nearest -to the character given by \fIindex\fR, and adjust that -end of the selection to be at \fIindex\fR (i.e. including -but not going beyond \fIindex\fR). -The other end of the selection is made the anchor point -for future \fBselect to\fR commands. -If the selection is not currently in \fItagOrId\fR then -this command behaves the same as the \fBselect to\fR widget -command. -Returns an empty string. -.TP -\fIpathName \fBselect clear\fR -. -Clear the selection if it is in this widget. -If the selection is not in this widget then the command -has no effect. -Returns an empty string. -.TP -\fIpathName \fBselect from \fItagOrId index\fR -. -Set the selection anchor point for the widget to be just -before the character -given by \fIindex\fR in the item given by \fItagOrId\fR. -This command does not change the selection; it just sets -the fixed end of the selection for future \fBselect to\fR -commands. -Returns an empty string. -.TP -\fIpathName \fBselect item\fR -. -Returns the id of the selected item, if the selection is in an -item in this canvas. -If the selection is not in this canvas then an empty string -is returned. -.TP -\fIpathName \fBselect to \fItagOrId index\fR -. -Set the selection to consist of those characters of \fItagOrId\fR -between the selection anchor point and -\fIindex\fR. -The new selection will include the character given by \fIindex\fR; -it will include the character given by the anchor point only if -\fIindex\fR is greater than or equal to the anchor point. -The anchor point is determined by the most recent \fBselect adjust\fR -or \fBselect from\fR command for this widget. -If the selection anchor point for the widget is not currently in -\fItagOrId\fR, then it is set to the same character given -by \fIindex\fR. -Returns an empty string. -.RE -.TP -\fIpathName \fBtype\fI tagOrId\fR -. -Returns the type of the item given by \fItagOrId\fR, such as -\fBrectangle\fR or \fBtext\fR. -If \fItagOrId\fR refers to more than one item, then the type -of the first item in the display list is returned. -If \fItagOrId\fR does not refer to any items at all then -an empty string is returned. -.TP -\fIpathName \fBxview \fR?\fIargs\fR? -. -This command is used to query and change the horizontal position of the -information displayed in the canvas's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fBxview\fR -. -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the canvas's area (as defined by the \fB\-scrollregion\fR option) -is off-screen to the left, the middle 40% is visible -in the window, and 40% of the canvas is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -. -Adjusts the view in the window so that \fIfraction\fR of the -total width of the canvas is off-screen to the left. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -. -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units -of the \fBxScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. -If \fIwhat is \fBpages\fR then the view -adjusts in units of nine-tenths the window's width. -If \fInumber\fR is negative then information farther to the left -becomes visible; if it is positive then information farther to the right -becomes visible. -.RE -.TP -\fIpathName \fByview \fI?args\fR? -. -This command is used to query and change the vertical position of the -information displayed in the canvas's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -. -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the vertical span that is visible in the window. -For example, if the first element is .6 and the second element is 1.0, -the lowest 40% of the canvas's area (as defined by the \fB\-scrollregion\fR -option) is visible in the window. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. -.TP -\fIpathName \fByview moveto\fI fraction\fR -. -Adjusts the view in the window so that \fIfraction\fR of the canvas's -area is off-screen to the top. -\fIFraction\fR is a fraction between 0 and 1. -.TP -\fIpathName \fByview scroll \fInumber what\fR -. -This command adjusts the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units -of the \fByScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. -If \fIwhat\fR is \fBpages\fR then -the view adjusts in units of nine-tenths the window's height. -If \fInumber\fR is negative then higher information becomes -visible; if it is positive then lower information -becomes visible. -.RE -.SH "OVERVIEW OF ITEM TYPES" -.PP -The sections below describe the various types of items supported -by canvas widgets. Each item type is characterized by two things: -first, the form of the \fBcreate\fR command used to create -instances of the type; and second, a set of configuration options -for items of that type, which may be used in the -\fBcreate\fR and \fBitemconfigure\fR widget commands. -Most items do not support indexing or selection or the commands -related to them, such as \fBindex\fR and \fBinsert\fR. -Where items do support these facilities, it is noted explicitly -in the descriptions below. -At present, text, line and polygon items provide this support. -For lines and polygons the indexing facility is used to manipulate -the coordinates of the item. -.SS "COMMON ITEM OPTIONS" -.PP -Many items share a common set of options. These options are -explained here, and then referred to be each widget type for brevity. -.TP -\fB\-anchor \fIanchorPos\fR -. -\fIAnchorPos\fR tells how to position the item relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the item is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the item will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP -\fB\-dash \fIpattern\fR -.TP -\fB\-activedash \fIpattern\fR -.TP -\fB\-disableddash \fIpattern\fR -. -This option specifies dash patterns for the normal, active -state, and disabled state of an item. -\fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR. -If the dash options are omitted then the default is a solid outline. -See \fBDASH PATTERNS\fR for more information. -.TP -\fB\-dashoffset \fIoffset\fR -. -The starting \fIoffset\fR in pixels into the pattern provided by the -\fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no -\fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described -in the \fBCOORDINATES\fR section above. -.TP -\fB\-fill \fIcolor\fR -.TP -\fB\-activefill \fIcolor\fR -.TP -\fB\-disabledfill \fIcolor\fR -. -Specifies the color to be used to fill item's area. -in its normal, active, and disabled states, -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -If \fIcolor\fR is an empty string (the default), -then the item will not be filled. -For the line item, it specifies the color of the line drawn. -For the text item, it specifies the foreground color of the text. -.TP -\fB\-outline \fIcolor\fR -.TP -\fB\-activeoutline \fIcolor\fR -.TP -\fB\-disabledoutline \fIcolor\fR -. -This option specifies the color that should be used to draw the -outline of the item in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -This option defaults to \fBblack\fR. If \fIcolor\fR is specified -as an empty string then no outline is drawn for the item. -.TP -\fB\-offset \fIoffset\fR -. -Specifies the offset of stipples. The offset value can be of the form -\fBx,y\fR or \fIside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, -\fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the -first case the origin is the origin of the toplevel of the current window. -For the canvas itself and canvas objects the origin is the canvas origin, -but putting \fB#\fR in front of the coordinate pair indicates using the -toplevel origin instead. For canvas objects, the \fB\-offset\fR option is -used for stippling as well. For the line and polygon canvas items you can -also specify an index as argument, which connects the stipple origin to one -of the coordinate points of the line/polygon. Note that stipple offsets are -\fIonly supported on X11\fR; they are silently ignored on other platforms. -.TP -\fB\-outlinestipple \fIbitmap\fR -.TP -\fB\-activeoutlinestipple \fIbitmap\fR -.TP -\fB\-disabledoutlinestipple \fIbitmap\fR -. -This option specifies stipple patterns that should be used to draw the -outline of the item in its normal, active and disabled states. -Indicates that the outline for the item should be drawn with a stipple pattern; -\fIbitmap\fR specifies the stipple pattern to use, in any of the -forms accepted by \fBTk_GetBitmap\fR. -If the \fB\-outline\fR option has not been specified then this option -has no effect. -If \fIbitmap\fR is an empty string (the default), then the outline is drawn -in a solid fashion. -\fINote that stipples are not well supported on platforms that do not -use X11 as their drawing API.\fR -.TP -\fB\-outlineoffset \fIoffset\fR -. -Specifies the offset of the stipple pattern used for outlines, in the same way -that the \fB\-outline\fR option controls fill stipples. (See the -\fB\-outline\fR option for a description of the syntax of \fIoffset\fR.) -.TP -\fB\-stipple \fIbitmap\fR -.TP -\fB\-activestipple \fIbitmap\fR -.TP -\fB\-disabledstipple \fIbitmap\fR -. -This option specifies stipple patterns that should be used to fill -the item in its normal, active and disabled states. -\fIbitmap\fR specifies the stipple pattern to use, in any of the -forms accepted by \fBTk_GetBitmap\fR. -If the \fB\-fill\fR option has not been specified then this option -has no effect. -If \fIbitmap\fR is an empty string (the default), then filling is done -in a solid fashion. -For the text item, it affects the actual text. -\fINote that stipples are not well supported on platforms that do not -use X11 as their drawing API.\fR -.TP -\fB\-state \fIstate\fR -. -This allows an item to override the canvas widget's global \fIstate\fR -option. It takes the same values: -\fInormal\fR, \fIdisabled\fR or \fIhidden\fR. -.TP -\fB\-tags \fItagList\fR -. -Specifies a set of tags to apply to the item. -\fITagList\fR consists of a list of tag names, which replace any -existing tags for the item. \fITagList\fR may be an empty list. -.TP -\fB\-width \fIoutlineWidth\fR -.TP -\fB\-activewidth \fIoutlineWidth\fR -.TP -\fB\-disabledwidth \fIoutlineWidth\fR -. -Specifies the width of the outline to be drawn around -the item's region, in its normal, active and disabled states. -\fIoutlineWidth\fR may be in any of the forms described in the -\fBCOORDINATES\fR section above. -If the \fB\-outline\fR option has been specified as an empty string then -this option has no effect. This option defaults to 1.0. -For arcs, wide outlines will be drawn centered on the edges of the -arc's region. -.SH "STANDARD ITEM TYPES" -.SS "ARC ITEMS" -.PP -Items of type \fBarc\fR appear on the display as arc-shaped regions. -An arc is a section of an oval delimited by two angles (specified -by the \fB\-start\fR and \fB\-extent\fR options) and displayed in -one of several ways (specified by the \fB\-style\fR option). -Arcs are created with widget commands of the following form: -.CS -\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? -\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval that defines the arc. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. An arc item becomes the current item when the mouse pointer is -over any part that is painted or (when fully transparent) that would be -painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. -.PP -The following standard options are supported by arcs: -.DS -.ta 3i -\fB\-dash\fR \fB\-activedash\fR -\fB\-disableddash\fR \fB\-dashoffset\fR -\fB\-fill\fR \fB\-activefill\fR -\fB\-disabledfill\fR \fB\-offset\fR -\fB\-outline\fR \fB\-activeoutline\fR -\fB\-disabledoutline\fR \fB\-outlineoffset\fR -\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR -\fB\-disabledoutlinestipple\fR \fB\-stipple\fR -\fB\-activestipple\fR \fB\-disabledstipple\fR -\fB\-state\fR \fB\-tags\fR -\fB\-width\fR \fB\-activewidth\fR -\fB\-disabledwidth\fR -.DE -The following extra options are supported for arcs: -.TP -\fB\-extent \fIdegrees\fR -Specifies the size of the angular range occupied by the arc. -The arc's range extends for \fIdegrees\fR degrees counter-clockwise -from the starting angle given by the \fB\-start\fR option. -\fIDegrees\fR may be negative. -If it is greater than 360 or less than \-360, then \fIdegrees\fR -modulo 360 is used as the extent. -.TP -\fB\-start \fIdegrees\fR -Specifies the beginning of the angular range occupied by the -arc. -\fIDegrees\fR is given in units of degrees measured counter-clockwise -from the 3-o'clock position; it may be either positive or negative. -.TP -\fB\-style \fItype\fR -Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR -(the default) then the arc's region is defined by a section -of the oval's perimeter plus two line segments, one between the center -of the oval and each end of the perimeter section. -If \fItype\fR is \fBchord\fR then the arc's region is defined -by a section of the oval's perimeter plus a single line segment -connecting the two end points of the perimeter section. -If \fItype\fR is \fBarc\fR then the arc's region consists of -a section of the perimeter alone. -In this last case the \fB\-fill\fR option is ignored. -.SS "BITMAP ITEMS" -.PP -Items of type \fBbitmap\fR appear on the display as images with -two colors, foreground and background. -Bitmaps are created with widget commands of the following form: -.CS -\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value ...\fR? -\fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two -elements) specify the coordinates of a -point used to position the bitmap on the display, as controlled by the -\fB\-anchor\fR option. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. A bitmap item becomes the current item when the mouse pointer -is over any part of its bounding box. -.PP -The following standard options are supported by bitmaps: -.DS -.ta 3i -\fB\-anchor\fR \fB\-state\fR -\fB\-tags\fR -.DE -The following extra options are supported for bitmaps: -.TP -\fB\-background \fIcolor\fR -.TP -\fB\-activebackground \fIcolor\fR -.TP -\fB\-disabledbackground \fIcolor\fR -Specifies the color to use for each of the bitmap's -.QW 0 -valued pixels in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -If this option is not specified, or if it is specified as an empty -string, then nothing is displayed where the bitmap pixels are 0; this -produces a transparent effect. -.TP -\fB\-bitmap \fIbitmap\fR -.TP -\fB\-activebitmap \fIbitmap\fR -.TP -\fB\-disabledbitmap \fIbitmap\fR -Specifies the bitmaps to display in the item in its normal, active and -disabled states. -\fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR. -.TP -\fB\-foreground \fIcolor\fR -.TP -\fB\-activeforeground \fIcolor\fR -.TP -\fB\-disabledforeground \fIcolor\fR -Specifies the color to use for each of the bitmap's -.QW 1 -valued pixels in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and -defaults to \fBblack\fR. -.SS "IMAGE ITEMS" -.PP -Items of type \fBimage\fR are used to display images on a -canvas. -Images are created with widget commands of the following form: -.CS -\fIpathName \fBcreate image \fIx y \fR?\fIoption value ...\fR? -\fIpathName \fBcreate image \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the image on the display, as controlled by the -\fB\-anchor\fR option. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. An image item becomes the current item when the mouse pointer -is over any part of its bounding box. -.PP -The following standard options are supported by images: -.DS -.ta 3i -\fB\-anchor\fR \fB\-state\fR -\fB\-tags\fR -.DE -The following extra options are supported for images: -.TP -\fB\-image \fIname\fR -.TP -\fB\-activeimage \fIname\fR -.TP -\fB\-disabledimage \fIname\fR -Specifies the name of the images to display in the item in is normal, -active and disabled states. -This image must have been created previously with the -\fBimage create\fR command. -.SS "LINE ITEMS" -.PP -Items of type \fBline\fR appear on the display as one or more connected -line segments or curves. -Line items support coordinate indexing operations using the \fBdchars\fR, -\fBindex\fR and \fBinsert\fR widget commands. -Lines are created with widget commands of the following form: -.CS -\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value ...\fR? -\fIpathName \fBcreate line \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR give -the coordinates for a series of two or more points that describe -a series of connected line segments. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. A line item is the current item whenever the mouse pointer is -over any segment of the line, whether drawn or not and whether or not the line -is smoothed. -.PP -The following standard options are supported by lines: -.DS -.ta 3i -\fB\-dash\fR \fB\-activedash\fR -\fB\-disableddash\fR \fB\-dashoffset\fR -\fB\-fill\fR \fB\-activefill\fR -\fB\-disabledfill\fR \fB\-stipple\fR -\fB\-activestipple\fR \fB\-disabledstipple\fR -\fB\-state\fR \fB\-tags\fR -\fB\-width\fR \fB\-activewidth\fR -\fB\-disabledwidth\fR -.DE -The following extra options are supported for lines: -.TP -\fB\-arrow \fIwhere\fR -Indicates whether or not arrowheads are to be drawn at one or both -ends of the line. -\fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads), -\fBfirst\fR (for an arrowhead at the first point of the line), -\fBlast\fR (for an arrowhead at the last point of the line), or -\fBboth\fR (for arrowheads at both ends). -This option defaults to \fBnone\fR. -.TP -\fB\-arrowshape \fIshape\fR -This option indicates how to draw arrowheads. -The \fIshape\fR argument must be a list with three elements, each -specifying a distance in any of the forms described in -the \fBCOORDINATES\fR section above. -The first element of the list gives the distance along the line -from the neck of the arrowhead to its tip. -The second element gives the distance along the line from the -trailing points of the arrowhead to the tip, and the third -element gives the distance from the outside edge of the line to the -trailing points. -If this option is not specified then Tk picks a -.QW reasonable -shape. -.TP -\fB\-capstyle \fIstyle\fR -Specifies the ways in which caps are to be drawn at the endpoints -of the line. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR -(\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). -If this option is not specified then it defaults to \fBbutt\fR. -Where arrowheads are drawn the cap style is ignored. -.TP -\fB\-joinstyle \fIstyle\fR -Specifies the ways in which joints are to be drawn at the vertices -of the line. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR -(\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option is not specified then it defaults to \fBround\fR. -If the line only contains two points then this option is -irrelevant. -.TP -\fB\-smooth \fIsmoothMethod\fR -\fIsmoothMethod\fR must have one of the forms accepted by -\fBTcl_GetBoolean\fR or a line smoothing method. -Only \fBtrue\fR and \fBraw\fR are -supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean -false value or empty string is given, no smoothing is applied. A boolean -truth value assumes \fBtrue\fR smoothing. -If the smoothing method is \fBtrue\fR, this indicates that the line -should be drawn as a curve, rendered as a set of quadratic splines: one spline -is drawn for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated within -a curve by duplicating the end-points of the desired line segment. -If the smoothing method is \fBraw\fR, this indicates that the line -should also be drawn as a curve but where the list of coordinates is -such that the first coordinate pair (and every third coordinate pair -thereafter) is a knot point on a cubic Bezier curve, and the other -coordinates are control points on the cubic Bezier curve. Straight -line segments can be generated within a curve by making control points -equal to their neighbouring knot points. If the last point is a -control point and not a knot point, the point is repeated (one or two -times) so that it also becomes a knot point. -.TP -\fB\-splinesteps \fInumber\fR -Specifies the degree of smoothness desired for curves: each spline -will be approximated with \fInumber\fR line segments. This -option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. -.SS "OVAL ITEMS" -.PP -Items of type \fBoval\fR appear as circular or oval regions on -the display. Each oval may have an outline, a fill, or -both. Ovals are created with widget commands of the -following form: -.CS -\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? -\fIpathName \fBcreate oval \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval. -The oval will include the top and left edges of the rectangle -not the lower or right edges. -If the region is square then the resulting oval is circular; -otherwise it is elongated in shape. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. An oval item becomes the current item when the mouse pointer is -over any part that is painted or (when fully transparent) that would be -painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. -.PP -The following standard options are supported by ovals: -.DS -.ta 3i -\fB\-dash\fR \fB\-activedash\fR -\fB\-disableddash\fR \fB\-dashoffset\fR -\fB\-fill\fR \fB\-activefill\fR -\fB\-disabledfill\fR \fB\-offset\fR -\fB\-outline\fR \fB\-activeoutline\fR -\fB\-disabledoutline\fR \fB\-outlineoffset\fR -\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR -\fB\-disabledoutlinestipple\fR \fB\-stipple\fR -\fB\-activestipple\fR \fB\-disabledstipple\fR -\fB\-state\fR \fB\-tags\fR -\fB\-width\fR \fB\-activewidth\fR -\fB\-disabledwidth\fR -.DE -There are no oval-specific options. -.SS "POLYGON ITEMS" -.PP -Items of type \fBpolygon\fR appear as polygonal or curved filled regions -on the display. -Polygon items support coordinate indexing operations using the \fBdchars\fR, -\fBindex\fR and \fBinsert\fR widget commands. -Polygons are created with widget commands of the following form: -.CS -\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR? -\fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for -three or more points that define a polygon. -The first point should not be repeated as the last to -close the shape; Tk will automatically close the periphery between -the first and last points. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. A polygon item is the current item whenever the mouse pointer -is over any part of the polygon, whether drawn or not and whether or not the -outline is smoothed. -.PP -The following standard options are supported by polygons: -.DS -.ta 3i -\fB\-dash\fR \fB\-activedash\fR -\fB\-disableddash\fR \fB\-dashoffset\fR -\fB\-fill\fR \fB\-activefill\fR -\fB\-disabledfill\fR \fB\-offset\fR -\fB\-outline\fR \fB\-activeoutline\fR -\fB\-disabledoutline\fR \fB\-outlineoffset\fR -\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR -\fB\-disabledoutlinestipple\fR \fB\-stipple\fR -\fB\-activestipple\fR \fB\-disabledstipple\fR -\fB\-state\fR \fB\-tags\fR -\fB\-width\fR \fB\-activewidth\fR -\fB\-disabledwidth\fR -.DE -The following extra options are supported for polygons: -.TP -\fB\-joinstyle \fIstyle\fR -Specifies the ways in which joints are to be drawn at the vertices -of the outline. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR -(\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option is not specified then it defaults to \fBround\fR. -.TP -\fB\-smooth \fIboolean\fR -\fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR -or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are -supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean -false value or empty string is given, no smoothing is applied. A boolean -truth value assumes \fBtrue\fR smoothing. -If the smoothing method is \fBtrue\fR, this indicates that the polygon -should be drawn as a curve, rendered as a set of quadratic splines: one spline -is drawn for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated within -a curve by duplicating the end-points of the desired line segment. -If the smoothing method is \fBraw\fR, this indicates that the polygon -should also be drawn as a curve but where the list of coordinates is -such that the first coordinate pair (and every third coordinate pair -thereafter) is a knot point on a cubic Bezier curve, and the other -coordinates are control points on the cubic Bezier curve. Straight -line segments can be venerated within a curve by making control points -equal to their neighbouring knot points. If the last point is not the -second point of a pair of control points, the point is repeated (one or two -times) so that it also becomes the second point of a pair of control -points (the associated knot point will be the first control point). -.TP -\fB\-splinesteps \fInumber\fR -Specifies the degree of smoothness desired for curves: each spline -will be approximated with \fInumber\fR line segments. This -option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. -.PP -Polygon items are different from other items such as rectangles, ovals -and arcs in that interior points are considered to be -.QW inside -a polygon (e.g. for purposes of the \fBfind closest\fR and -\fBfind overlapping\fR widget commands) even if it is not filled. -For most other item types, an -interior point is considered to be inside the item only if the item -is filled or if it has neither a fill nor an outline. If you would -like an unfilled polygon whose interior points are not considered -to be inside the polygon, use a line item instead. -.SS "RECTANGLE ITEMS" -.PP -Items of type \fBrectangle\fR appear as rectangular regions on -the display. Each rectangle may have an outline, a fill, or -both. Rectangles are created with widget commands of the -following form: -.CS -\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? -\fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR -(which must have four elements) give -the coordinates of two diagonally opposite corners of the rectangle -(the rectangle will include its upper and left edges but not -its lower or right edges). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. A rectangle item becomes the current item when the mouse -pointer is over any part that is painted or (when fully transparent) that -would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were -non-empty. -.PP -The following standard options are supported by rectangles: -.DS -.ta 3i -\fB\-dash\fR \fB\-activedash\fR -\fB\-disableddash\fR \fB\-dashoffset\fR -\fB\-fill\fR \fB\-activefill\fR -\fB\-disabledfill\fR \fB\-offset\fR -\fB\-outline\fR \fB\-activeoutline\fR -\fB\-disabledoutline\fR \fB\-outlineoffset\fR -\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR -\fB\-disabledoutlinestipple\fR \fB\-stipple\fR -\fB\-activestipple\fR \fB\-disabledstipple\fR -\fB\-state\fR \fB\-tags\fR -\fB\-width\fR \fB\-activewidth\fR -\fB\-disabledwidth\fR -.DE -There are no rectangle-specific options. -.SS "TEXT ITEMS" -.PP -A text item displays a string of characters on the screen in one -or more lines. -Text items support indexing, editing and selection through the \fBdchars\fR -widget command, the \fBfocus\fR widget command, the \fBicursor\fR widget -command, the \fBindex\fR widget command, the \fBinsert\fR widget command, and -the \fBselect\fR widget command. -Text items are created with widget commands of the following -form: -.CS -\fIpathName \fBcreate text \fIx y \fR?\fIoption value ...\fR? -\fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two -elements) specify the coordinates of a -point used to position the text on the display (see the options -below for more information on how text is displayed). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. A text item becomes the current item when the mouse pointer -is over any part of its bounding box. -.PP -The following standard options are supported by text items: -.DS -.ta 3i -\fB\-anchor\fR \fB\-fill\fR -\fB\-activefill\fR \fB\-disabledfill\fR -\fB\-stipple\fR \fB\-activestipple\fR -\fB\-disabledstipple\fR \fB\-state\fR -\fB\-tags\fR -.DE -The following extra options are supported for text items: -.TP -\fB\-angle \fIrotationDegrees\fR -.VS 8.6 -\fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise -about the positioning point for the text; it may have any floating-point value -from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the -text will be drawn vertically from bottom to top. -This option defaults to \fB0.0\fR. -.VE 8.6 -.TP -\fB\-font \fIfontName\fR -Specifies the font to use for the text item. -\fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR. -If this option is not specified, it defaults to a system-dependent -font. -.TP -\fB\-justify \fIhow\fR -Specifies how to justify the text within its bounding region. -\fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, -or \fBcenter\fR. -This option will only matter if the text is displayed as multiple -lines. -If the option is omitted, it defaults to \fBleft\fR. -.TP -\fB\-text \fIstring\fR -\fIString\fR specifies the characters to be displayed in the text item. -Newline characters cause line breaks. -The characters in the item may also be changed with the -\fBinsert\fR and \fBdelete\fR widget commands. -This option defaults to an empty string. -.TP -\fB\-underline \fI\fR -Specifies the integer index of a character within the text to be -underlined. 0 corresponds to the first character of the text -displayed, 1 to the next character, and so on. \-1 means that no -underline should be drawn (if the whole text item is to be underlined, -the appropriate font should be used instead). -.TP -\fB\-width \fIlineLength\fR -Specifies a maximum line length for the text, in any of the forms -described in the \fBCOORDINATES\fR section above. -If this option is zero (the default) the text is broken into -lines only at newline characters. -However, if this option is non-zero then any line that would -be longer than \fIlineLength\fR is broken just before a space -character to make the line shorter than \fIlineLength\fR; the -space character is treated as if it were a newline -character. -.SS "WINDOW ITEMS" -.PP -Items of type \fBwindow\fR cause a particular window to be displayed -at a given position on the canvas. -Window items are created with widget commands of the following form: -.CS -\fIpathName \fBcreate window \fIx y \fR?\fIoption value ...\fR? -\fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two -elements) specify the coordinates of a -point used to position the window on the display, as controlled by the -\fB\-anchor\fR option. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. Theoretically, a window item becomes the current item when the -mouse pointer is over any part of its bounding box, but in practice this -typically does not happen because the mouse pointer ceases to be over the -canvas at that point. -.PP -The following standard options are supported by window items: -.DS -.ta 3i -\fB\-anchor\fR \fB\-state\fR -\fB\-tags\fR -.DE -The following extra options are supported for window items: -.TP -\fB\-height \fIpixels\fR -. -Specifies the height to assign to the item's window. -\fIPixels\fR may have any of the -forms described in the \fBCOORDINATES\fR section above. -If this option is not specified, or if it is specified as zero, -then the window is given whatever height it requests internally. -.TP -\fB\-width \fIpixels\fR -. -Specifies the width to assign to the item's window. -\fIPixels\fR may have any of the -forms described in the \fBCOORDINATES\fR section above. -If this option is not specified, or if it is specified as zero, -then the window is given whatever width it requests internally. -.TP -\fB\-window \fIpathName\fR -. -Specifies the window to associate with this item. -The window specified by \fIpathName\fR must either be a child of -the canvas widget or a child of some ancestor of the canvas widget. -\fIPathName\fR may not refer to a top-level window. -.PP -Note: due to restrictions in the ways that windows are managed, it is not -possible to draw other graphical items (such as lines and images) on top -of window items. A window item always obscures any graphics that -overlap it, regardless of their order in the display list. Also note that -window items, unlike other canvas items, are not clipped for display by their -containing canvas's border, and are instead clipped by the parent widget of -the window specified by the \fB\-window\fR option; when the parent widget is -the canvas, this means that the window item can overlap the canvas's border. -.SH "APPLICATION-DEFINED ITEM TYPES" -.PP -It is possible for individual applications to define new item -types for canvas widgets using C code. -See the documentation for \fBTk_CreateItemType\fR. -.SH BINDINGS -.PP -In the current implementation, new canvases are not given any -default behavior: you will have to execute explicit Tcl commands -to give the canvas its behavior. -.SH CREDITS -.PP -Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's -\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme -environment and preceded canvases by a year or two. Its simple -mechanisms for placing and animating graphical objects inspired the -functions of canvases. -.SH "SEE ALSO" -bind(n), font(n), image(n), scrollbar(n) -.SH KEYWORDS -canvas, widget -'\" Local Variables: -'\" mode: nroff -'\" fill-column: 78 -'\" End: diff --git a/tk8.6/doc/checkbutton.n b/tk8.6/doc/checkbutton.n deleted file mode 100644 index bfefca4..0000000 --- a/tk8.6/doc/checkbutton.n +++ /dev/null @@ -1,293 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH checkbutton n 4.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -checkbutton \- Create and manipulate 'checkbutton' boolean selection 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 \fB\-relief\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 \fB\-image\fR option) -when the checkbutton is selected. -This option is ignored unless the \fB\-image\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 -\fB\-foreground\fR and \fB\-background\fR options. The active state is -typically used when the pointer is over the checkbutton. In active state -the checkbutton is displayed using the \fB\-activeforeground\fR and -\fB\-activebackground\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 \fB\-disabledforeground\fR and -\fB\-background\fR options determine how the checkbutton is displayed. -.OP \-tristateimage tristateImage TristateImage -Specifies an image to display (in place of the \fB\-image\fR option) -when the checkbutton is in tri-state mode. -This option is ignored unless the \fB\-image\fR option has been -specified. -.OP \-tristatevalue tristateValue Value -Specifies the value that causes the checkbutton to display the multi-value -selection, also known as the tri-state mode. Defaults to -.QW "" . -.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 \fB\-wraplength\fR option) and -one of the characters may optionally be underlined using the -\fB\-underline\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 \fB\-state\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). -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. -.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 -(\fB+\fR) and equal (\fB=\fR) select the button, and minus (\fB\-\fR) -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 -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/chooseColor.n b/tk8.6/doc/chooseColor.n deleted file mode 100644 index 015b17d..0000000 --- a/tk8.6/doc/chooseColor.n +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_chooseColor n 4.2 Tk "Tk Built-In Commands" -.so man.macros -.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 -.PP -.CS -button .b \-bg [tk_chooseColor \-initialcolor gray \-title "Choose color"] -.CE -.SH KEYWORDS -color, color selection, dialog -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/chooseDirectory.n b/tk8.6/doc/chooseDirectory.n deleted file mode 100644 index e441d78..0000000 --- a/tk8.6/doc/chooseDirectory.n +++ /dev/null @@ -1,71 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.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\-command\fR \fIstring\fR -Specifies the prefix of a Tcl command to invoke when the user closes the -dialog after having selected an item. This callback is not called if the -user cancelled the dialog. The actual command consists of \fIstring\fR -followed by a space and the value selected by the user in the dialog. This -is only available on Mac OS X. -.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, -the initial directory defaults to the current working directory -on non-Windows systems and on Windows systems prior to Vista. -On Vista and later systems, the initial directory defaults to the last -user-selected directory for the application. If the -parameter specifies a relative path, the return value will convert the -relative path to an absolute path. -.TP -\fB\-message\fR \fIstring\fR -Specifies a message to include in the client area of the dialog. -This is only available on Mac OS X. -.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 -.PP -.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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/clipboard.n b/tk8.6/doc/clipboard.n deleted file mode 100644 index 6f047dd..0000000 --- a/tk8.6/doc/clipboard.n +++ /dev/null @@ -1,157 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH clipboard n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.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: -.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 \fBSTRING\fR or \fBFILE_NAME\fR; see the -Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to \fBSTRING\fR. -.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 \fBSTRING\fR. If \fIformat\fR is -\fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters. If -\fIformat\fR is \fBATOM\fR, 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 \fBCLIPBOARD\fR 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 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 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 \fBSTRING\fR -or \fBFILE_NAME\fR. \fIType\fR defaults to \fBSTRING\fR. This command is -equivalent to -.QW "\fBselection get\fR \fB\-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 -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/colors.n b/tk8.6/doc/colors.n deleted file mode 100644 index dc7007b..0000000 --- a/tk8.6/doc/colors.n +++ /dev/null @@ -1,957 +0,0 @@ -'\" -'\" 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 -'\" -.TH colors n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.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 -agua 0 255 255 -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 -crymson 220 20 60 -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 -fuchsia 255 0 255 -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 128 128 128 -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 128 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 128 128 128 -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 -indigo 75 0 130 -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 0 255 0 -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 128 0 0 -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 128 128 0 -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 128 0 128 -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 -silver 192 192 192 -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 -teal 0 128 128 -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 -system3dDarkShadow systemHighlight -system3dLight systemHighlightText -systemActiveBorder systemInactiveBorder -systemActiveCaption systemInactiveCaption -systemAppWorkspace systemInactiveCaptionText -systemBackground systemInfoBackground -systemButtonFace systemInfoText -systemButtonHighlight systemMenu -systemButtonShadow systemMenuText -systemButtonText systemScrollbar -systemCaptionText systemWindow -systemDisabledText systemWindowFrame -systemGrayText systemWindowText -.DE -.RE -.SH "SEE ALSO" -options(n), Tk_GetColor(3) -.SH KEYWORDS -color, option -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/console.n b/tk8.6/doc/console.n deleted file mode 100644 index 1313d3a..0000000 --- a/tk8.6/doc/console.n +++ /dev/null @@ -1,145 +0,0 @@ -'\" -'\" 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. -'\" -.TH console n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.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 only 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 -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/cursors.n b/tk8.6/doc/cursors.n deleted file mode 100644 index 1662de4..0000000 --- a/tk8.6/doc/cursors.n +++ /dev/null @@ -1,191 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net> -'\" -.TH cursors n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.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 -top_left_arrow -left_ptr -cross -crosshair -tcross -ibeam -none -xterm -.CE -And the following additional native cursors are available: -.CS -copyarrow -aliasarrow -contextualmenuarrow -movearrow -text -cross-hair -hand -openhand -closedhand -fist -pointinghand -resize -resizeleft -resizeright -resizeleftright -resizeup -resizedown -resizeupdown -resizebottomleft -resizetopleft -resizebottomright -resizetopright -notallowed -poof -wait -countinguphand -countingdownhand -countingupanddownhand -spinning -help -bucket -cancel -eyedrop -eyedrop-full -zoom-in -zoom-out -.CE -.RE -.SH KEYWORDS -cursor, option -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/destroy.n b/tk8.6/doc/destroy.n deleted file mode 100644 index 3d4743a..0000000 --- a/tk8.6/doc/destroy.n +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH destroy n "" Tk "Tk Built-In Commands" -.so man.macros -.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 -.PP -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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/dialog.n b/tk8.6/doc/dialog.n deleted file mode 100644 index d2031d3..0000000 --- a/tk8.6/doc/dialog.n +++ /dev/null @@ -1,74 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_dialog n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.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. -It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR. -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 (in a form suitable for Tk_GetBitmap) -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 -.PP -.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 -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/entry.n b/tk8.6/doc/entry.n deleted file mode 100644 index ccfcd24..0000000 --- a/tk8.6/doc/entry.n +++ /dev/null @@ -1,539 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 Scriptics Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH entry n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -entry \- Create and manipulate 'entry' one-line text entry widgets -.SH SYNOPSIS -\fBentry\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-highlightthickness \-selectbackground -\-borderwidth \-insertbackground \-selectborderwidth -\-cursor \-insertborderwidth \-selectforeground -\-exportselection \-insertofftime \-takefocus -\-font \-insertontime \-textvariable -\-foreground \-insertwidth \-xscrollcommand -\-highlightbackground \-justify -\-highlightcolor \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-disabledbackground disabledBackground DisabledBackground -Specifies the background color to use when the entry is disabled. If -this option is the empty string, the normal background color is used. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies the foreground color to use when the entry is disabled. If -this option is the empty string, the normal foreground color is used. -.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fB\-validatecommand\fR returns 0. -Setting it to {} disables this feature (the default). The best use -of this option is to set it to \fIbell\fR. See \fBVALIDATION\fR -below for more information. -.OP \-readonlybackground readonlyBackground ReadonlyBackground -Specifies the background color to use when the entry is readonly. If -this option is the empty string, the normal background color is used. -.OP \-show show Show -If this option is specified, then the true contents of the entry -are not displayed in the window. -Instead, each character in the entry's value will be displayed as -the first character in the value of this option, such as -.QW * . -This is useful, for example, if the entry is to be used to enter -a password. -If characters in the entry are selected and copied elsewhere, the -information copied will be what is displayed, not the true contents -of the entry. -.OP \-state state State -Specifies one of three states for the entry: \fBnormal\fR, -\fBdisabled\fR, or \fBreadonly\fR. If the entry is readonly, then the -value may not be changed using widget commands and no insertion cursor -will be displayed, even if the input focus is in the widget; the -contents of the widget may still be selected. If the entry is -disabled, the value may not be changed, no insertion cursor will be -displayed, the contents will not be selectable, and the entry may -be displayed in a different color, depending on the values of the -\fB\-disabledforeground\fR and \fB\-disabledbackground\fR options. -.OP \-validate validate Validate -Specifies the mode in which validation should operate: \fBnone\fR, -\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. -It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBVALIDATION\fR below for more. -.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand -Specifies a script to eval when you want to validate the input into -the entry widget. Setting it to {} disables this feature (the default). -This command must return a valid Tcl boolean value. If it returns 0 (or -the valid Tcl boolean equivalent) then it means you reject the new edition -and it will not occur and the \fB\-invalidcommand\fR will be evaluated if it -is set. If it returns 1, then the new edition occurs. -See \fBVALIDATION\fR below for more information. -.OP \-width width Width -Specifies an integer value indicating the desired width of the entry window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. -.BE -.SH DESCRIPTION -.PP -The \fBentry\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into an entry widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the entry such as its colors, font, -and relief. The \fBentry\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 -An entry is a widget that displays a one-line text string and -allows that string to be edited using widget commands described below, which -are typically bound to keystrokes and mouse actions. -When first created, an entry's string is empty. -A portion of the entry may be selected as described below. -If an entry is exporting its selection (see the \fB\-exportselection\fR -option), then it will observe the standard X11 protocols for handling the -selection; entry selections are available as type \fBSTRING\fR. -Entries also observe the standard Tk rules for dealing with the -input focus. When an entry has the input focus it displays an -\fIinsertion cursor\fR to indicate where new characters will be -inserted. -.PP -Entries are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Entries use -the standard \fB\-xscrollcommand\fR mechanism for interacting with -scrollbars (see the description of the \fB\-xscrollcommand\fR option -for details). They also support scanning, as described below. -.SH VALIDATION -.PP -Validation works by setting the \fB\-validatecommand\fR option to a -script (\fIvalidateCommand\fR) which will be evaluated according to -the \fB\-validate\fR option as follows: -.PP -.IP \fBnone\fR 10 -Default. This means no validation will occur. -.IP \fBfocus\fR 10 -\fIvalidateCommand\fR will be called when the entry receives or -loses focus. -.IP \fBfocusin\fR 10 -\fIvalidateCommand\fR will be called when the entry receives focus. -.IP \fBfocusout\fR 10 -\fIvalidateCommand\fR will be called when the entry loses focus. -.IP \fBkey\fR 10 -\fIvalidateCommand\fR will be called when the entry is edited. -.IP \fBall\fR 10 -\fIvalidateCommand\fR will be called for all above conditions. -.PP -It is possible to perform percent substitutions on the value of the -\fB\-validatecommand\fR and \fB\-invalidcommand\fR options, -just as you would in a \fBbind\fR script. The following substitutions -are recognized: -.PP -.IP \fB%d\fR 5 -Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, -or \-1 for focus, forced or textvariable validation. -.IP \fB%i\fR 5 -Index of char string to be inserted/deleted, if any, otherwise \-1. -.IP \fB%P\fR 5 -The value of the entry if the edit is allowed. If you are configuring the -entry widget to have a new textvariable, this will be the value of that -textvariable. -.IP \fB%s\fR 5 -The current value of entry prior to editing. -.IP \fB%S\fR 5 -The text string being inserted/deleted, if any, {} otherwise. -.IP \fB%v\fR 5 -The type of validation currently set. -.IP \fB%V\fR 5 -The type of validation that triggered the callback -(key, focusin, focusout, forced). -.IP \fB%W\fR 5 -The name of the entry widget. -.PP -In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR options can be -dangerous to mix. Any problems have been overcome so that using the -\fB\-validatecommand\fR will not interfere with the traditional behavior of -the entry widget. Using the \fB\-textvariable\fR for read-only purposes will -never cause problems. The danger comes when you try set the -\fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not -accept, which causes \fB\-validate\fR to become \fInone\fR (the -\fB\-invalidcommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fB\-validatecommand\fR. -.PP -Primarily, an error will occur when the \fB\-validatecommand\fR or -\fB\-invalidcommand\fR encounters an error in its script while evaluating or -\fB\-validatecommand\fR does not return a valid Tcl boolean value. The -\fB\-validate\fR option will also set itself to \fBnone\fR when you edit the -entry widget from within either the \fB\-validatecommand\fR or the -\fB\-invalidcommand\fR. Such editions will override the one that was being -validated. If you wish to edit the entry widget (for example set it to {}) -during validation and still have the \fB\-validate\fR option set, you should -include the command -.CS -after idle {%W config \-validate %v} -.CE -in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you -were editing the entry widget from). It is also recommended to not set an -associated \fB\-textvariable\fR during validation, as that can cause the -entry widget to become out of sync with the \fB\-textvariable\fR. -.SH "WIDGET COMMAND" -.PP -The \fBentry\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 subcommand \fR?\fIarg arg ...\fR? -.CE -\fISubcommand\fR and the \fIarg\fRs -determine the exact behavior of the command. -.SS INDICES -.PP -Many of the widget commands for entries take one or more indices as -arguments. An index specifies a particular character in the entry's -string, in any of the following ways: -.TP 12 -\fInumber\fR -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. -.TP 12 -\fBanchor\fR -Indicates the anchor point for the selection, which is set with the -\fBselect from\fR and \fBselect adjust\fR widget commands. -.TP 12 -\fBend\fR -Indicates the character just after the last one in the entry's string. -This is equivalent to specifying a numerical index equal to the length -of the entry's string. -.TP 12 -\fBinsert\fR -Indicates the character adjacent to and immediately following the -insertion cursor. -.TP 12 -\fBsel.first\fR -Indicates the first character in the selection. It is an error to -use this form if the selection is not in the entry window. -.TP 12 -\fBsel.last\fR -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection is not in the -entry window. -.TP 12 -\fB@\fInumber\fR -In this form, \fInumber\fR is treated as an x-coordinate in the -entry's window; the character spanning that x-coordinate is used. -For example, -.QW \fB@0\fR -indicates the left-most character in the window. -.LP -Abbreviations may be used for any of the forms above, e.g. -.QW \fBe\fR -or -.QW \fBsel.f\fR . -In general, out-of-range indices are automatically rounded to the -nearest legal value. -.SS SUBCOMMANDS -.PP -The following commands are possible for entry widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four numbers describing the bounding box of the -character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. -.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 \fBentry\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 \fBentry\fR -command. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Delete one or more elements of the entry. -\fIFirst\fR is the index of the first character to delete, and -\fIlast\fR is the index of the character just after the last -one to delete. -If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, -i.e. a single character is deleted. -This command returns an empty string. -.TP -\fIpathName \fBget\fR -Returns the entry's string. -.TP -\fIpathName \fBicursor \fIindex\fR -Arrange for the insertion cursor to be displayed just before the character -given by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBindex\fI index\fR -Returns the numerical index corresponding to \fIindex\fR. -.TP -\fIpathName \fBinsert \fIindex string\fR -Insert the characters of \fIstring\fR just before the character -indicated by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on entries. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx\fR -Records \fIx\fR and the current view in the entry window; used in -conjunction with later \fBscan dragto\fR commands. Typically this -command is associated with a mouse button press in the widget. It -returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx\fR -This command computes the difference between its \fIx\fR argument -and the \fIx\fR argument to the last \fBscan mark\fR command for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the entry at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within an entry. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection adjust \fIindex\fR -Locate the end of the selection nearest to the character given by -\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR -(i.e. including but not going beyond \fIindex\fR). The other -end of the selection is made the anchor point for future -\fBselect to\fR commands. If the selection -is not currently in the entry, then a new selection is created to -include the characters between \fIindex\fR and the most recent -selection anchor point, inclusive. -Returns an empty string. -.TP -\fIpathName \fBselection clear\fR -Clear the selection if it is currently in this widget. If the -selection is not in this widget then the command has no effect. -Returns an empty string. -.TP -\fIpathName \fBselection from \fIindex\fR -Set the selection anchor point to just before the character -given by \fIindex\fR. Does not change the selection. -Returns an empty string. -.TP -\fIpathName \fBselection present\fR -Returns 1 if there is are characters selected in the entry, -0 if nothing is selected. -.TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR -Sets the selection to include the characters starting with -the one indexed by \fIstart\fR and ending with the one just -before \fIend\fR. -If \fIend\fR refers to the same character as \fIstart\fR or an -earlier one, then the entry's selection is cleared. -.TP -\fIpathName \fBselection to \fIindex\fR -If \fIindex\fR is before the anchor point, set the selection -to the characters from \fIindex\fR up to but not including -the anchor point. -If \fIindex\fR is the same as the anchor point, do nothing. -If \fIindex\fR is after the anchor point, set the selection -to the characters from the anchor point up to but not including -\fIindex\fR. -The anchor point is determined by the most recent \fBselect from\fR -or \fBselect adjust\fR command in this widget. -If the selection is not in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. -.RE -.TP -\fIpathName \fBvalidate\fR -This command is used to force an evaluation of the \fB\-validatecommand\fR -independent of the conditions specified by the \fB\-validate\fR option. -This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. -It returns 0 or 1. -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the entry's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview\fR \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is displayed at the left edge of the window. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that the character \fIfraction\fR of the -way through the text appears at the left edge of the window. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for entries that give them -the following default behavior. In the descriptions below, -.QW word -refers to a contiguous group of letters, digits, or -.QW _ -characters, or any single character other than these. -.IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the end of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects all of the text in the -entry and positions the insertion cursor at the end of the line. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. -.IP [5] -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the entry without affecting the selection. -.IP [6] -If any normal printing characters are typed in an entry, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the entry can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the entry at the position of the mouse cursor. -.IP [8] -If the mouse is dragged out of the entry on the left or right sides -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the entry and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. -.IP [10] -The Home key, or Control-a, will move the insertion cursor to the -beginning of the entry and clear any selection in the entry. -Shift-Home moves the insertion cursor to the beginning of the entry -and also extends the selection to that point. -.IP [11] -The End key, or Control-e, will move the insertion cursor to the -end of the entry and clear any selection in the entry. -Shift-End moves the cursor to the end and extends the selection -to that point. -.IP [12] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They do not affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. -.IP [13] -Control-/ selects all the text in the entry. -.IP [14] -Control-\e clears any selection in the entry. -.IP [15] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -.IP [16] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. -.IP [17] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -.IP [18] -The Delete key deletes the selection, if there is one in the entry. -If there is no selection, it deletes the character to the right of -the insertion cursor. -.IP [19] -The BackSpace key and Control-h delete the selection, if there is one -in the entry. -If there is no selection, it deletes the character to the left of -the insertion cursor. -.IP [20] -Control-d deletes the character to the right of the insertion cursor. -.IP [21] -Meta-d deletes the word to the right of the insertion cursor. -.IP [22] -Control-k deletes all the characters to the right of the insertion -cursor. -.IP [23] -Control-t reverses the order of the two characters to the right of -the insertion cursor. -.PP -If the entry is disabled using the \fB\-state\fR option, then the entry's -view can still be adjusted and text in the entry can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place -except if the entry is linked to a variable using the \fB\-textvariable\fR -option, in which case any changes to the variable are reflected by the -entry whatever the value of its \fB\-state\fR option. -.PP -The behavior of entries can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -ttk::entry(n) -.SH KEYWORDS -entry, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/event.n b/tk8.6/doc/event.n deleted file mode 100644 index 5109794..0000000 --- a/tk8.6/doc/event.n +++ /dev/null @@ -1,604 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH event n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -event \- Miscellaneous event facilities: define virtual events and generate events -.SH SYNOPSIS -\fBevent\fI option \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBevent\fR command provides several facilities for dealing with -window system events, such as defining virtual events and synthesizing -events. The command has several different forms, determined by the -first argument. The following forms are currently supported: -.TP -\fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? -Associates the virtual event \fIvirtual\fR with the physical -event sequence(s) given by the \fIsequence\fR arguments, so that -the virtual event will trigger whenever any one of the \fIsequence\fRs -occurs. -\fIVirtual\fR may be any string value and \fIsequence\fR may have -any of the values allowed for the \fIsequence\fR argument to the -\fBbind\fR command. -If \fIvirtual\fR is already defined, the new physical event sequences -add to the existing sequences for the event. -.TP -\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\fR? -Deletes each of the \fIsequence\fRs from those associated with -the virtual event given by \fIvirtual\fR. -\fIVirtual\fR may be any string value and \fIsequence\fR may have -any of the values allowed for the \fIsequence\fR argument to the -\fBbind\fR command. -Any \fIsequence\fRs not currently associated with \fIvirtual\fR -are ignored. -If no \fIsequence\fR argument is provided, all physical event sequences -are removed for \fIvirtual\fR, so that the virtual event will not -trigger anymore. -.TP -\fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? -Generates a window event and arranges for it to be processed just as if -it had come from the window system. -\fIWindow\fR gives the path name of the window for which the event -will be generated; it may also be an identifier (such as returned by -\fBwinfo id\fR) as long as it is for a window in the current application. -\fIEvent\fR provides a basic description of -the event, such as \fB<Shift-Button-2>\fR or \fB<<Paste>>\fR. -If \fIWindow\fR is empty the whole screen is meant, and coordinates -are relative to the screen. -\fIEvent\fR may have any of the forms allowed for the \fIsequence\fR -argument of the \fBbind\fR command except that it must consist -of a single event pattern, not a sequence. -\fIOption-value\fR pairs may be used to specify additional -attributes of the event, such as the x and y mouse position; see -\fBEVENT FIELDS\fR below. If the \fB\-when\fR option is not specified, the -event is processed immediately: all of the handlers for the event -will complete before the \fBevent generate\fR command returns. -If the \fB\-when\fR option is specified then it determines when the -event is processed. Certain events, such as key events, require -that the window has focus to receive the event properly. -.TP -\fBevent info \fR?\fB<<\fIvirtual\fB>>\fR? -Returns information about virtual events. -If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value -is a list of all the virtual events that are currently defined. -If \fB<<\fIvirtual\fB>>\fR is specified then the return value is -a list whose elements are the physical event sequences currently -defined for the given virtual event; if the virtual event is -not defined then an empty string is returned. -.RS -.PP -Note that virtual events that are not bound to physical event -sequences are \fInot\fR returned by \fBevent info\fR. -.RE -.SH "EVENT FIELDS" -.PP -The following options are supported for the \fBevent generate\fR -command. These correspond to the -.QW % -expansions allowed in binding scripts for the \fBbind\fR command. -.TP -\fB\-above\fI window\fR -\fIWindow\fR specifies the \fIabove\fR field for the event, -either as a window path name or as an integer window id. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%a\fR substitution for binding scripts. -.TP -\fB\-borderwidth\fI size\fR -\fISize\fR must be a screen distance; it specifies the -\fIborder_width\fR field for the event. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%B\fR substitution for binding scripts. -.TP -\fB\-button\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIdetail\fR field -for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding -any button number provided in the base \fIevent\fR argument. -Corresponds to the \fB%b\fR substitution for binding scripts. -.TP -\fB\-count\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIcount\fR field -for the event. Valid for \fBExpose\fR events. -Corresponds to the \fB%c\fR substitution for binding scripts. -.TP -\fB\-data\fI string\fR -\fIString\fR may be any value; it specifies the \fIuser_data\fR field -for the event. Only valid for virtual events. Corresponds to the -\fB%d\fR substitution for virtual events in binding scripts. -.TP -\fB\-delta\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIdelta\fR field -for the \fBMouseWheel\fR event. The \fIdelta\fR refers to the -direction and magnitude the mouse wheel was rotated. Note the value -is not a screen distance but are units of motion in the mouse wheel. -Typically these values are multiples of 120. For example, 120 should -scroll the text widget up 4 lines and \-240 would scroll the text -widget down 8 lines. Of course, other widgets may define different -behaviors for mouse wheel motion. This field corresponds to the -\fB%D\fR substitution for binding scripts. -.TP -\fB\-detail\fI detail\fR -\fIDetail\fR specifies the \fIdetail\fR field for the event -and must 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 -Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and -\fBFocusOut\fR events. -Corresponds to the \fB%d\fR substitution for binding scripts. -.RE -.TP -\fB\-focus\fI boolean\fR -\fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR -field for the event. -Valid for \fBEnter\fR and \fBLeave\fR events. -Corresponds to the \fB%f\fR substitution for binding scripts. -.TP -\fB\-height\fI size\fR -\fISize\fR must be a screen distance; it specifies the \fIheight\fR -field for the event. Valid for \fBConfigure\fR events. -Corresponds to the \fB%h\fR substitution for binding scripts. -.TP -\fB\-keycode\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIkeycode\fR -field for the event. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. -Corresponds to the \fB%k\fR substitution for binding scripts. -.TP -\fB\-keysym\fI name\fR -\fIName\fR must be the name of a valid keysym, such as \fBg\fR, -\fBspace\fR, or \fBReturn\fR; its corresponding -keycode value is used as the \fIkeycode\fR field for event, overriding -any detail specified in the base \fIevent\fR argument. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. -Corresponds to the \fB%K\fR substitution for binding scripts. -.TP -\fB\-mode\fI notify\fR -\fINotify\fR specifies the \fImode\fR field for the event and must be -one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or -\fBNotifyWhileGrabbed\fR. -Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and -\fBFocusOut\fR events. -Corresponds to the \fB%m\fR substitution for binding scripts. -.TP -\fB\-override\fI boolean\fR -\fIBoolean\fR must be a boolean value; it specifies the -\fIoverride_redirect\fR field for the event. -Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. -Corresponds to the \fB%o\fR substitution for binding scripts. -.TP -\fB\-place\fI where\fR -\fIWhere\fR specifies the \fIplace\fR field for the event; it must be -either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. -Valid for \fBCirculate\fR events. -Corresponds to the \fB%p\fR substitution for binding scripts. -.TP -\fB\-root\fI window\fR -\fIWindow\fR must be either a window path name or an integer window -identifier; it specifies the \fIroot\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. -Corresponds to the \fB%R\fR substitution for binding scripts. -.TP -\fB\-rootx\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIx_root\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. Corresponds to the \fB%X\fR substitution for binding scripts. -.TP -\fB\-rooty\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIy_root\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. -Corresponds to the \fB%Y\fR substitution for binding scripts. -.TP -\fB\-sendevent\fI boolean\fR -\fIBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR -field for the event. Valid for all events. Corresponds to the -\fB%E\fR substitution for binding scripts. -.TP -\fB\-serial\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIserial\fR field -for the event. Valid for all events. -Corresponds to the \fB%#\fR substitution for binding scripts. -.TP -\fB\-state\fI state\fR -\fIState\fR specifies the \fIstate\fR field for the event. -For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events -it must be an integer value. -For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, -\fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. -This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR -specified in the base \fIevent\fR. -Corresponds to the \fB%s\fR substitution for binding scripts. -.TP -\fB\-subwindow\fI window\fR -\fIWindow\fR specifies the \fIsubwindow\fR field for the event, either -as a path name for a Tk widget or as an integer window identifier. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. -Similar to \fB%S\fR substitution for binding scripts. -.TP -\fB\-time\fI integer\fR -\fIInteger\fR must be an integer value; it specifies the \fItime\fR field -for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, -and \fBProperty\fR events. -Corresponds to the \fB%t\fR substitution for binding scripts. -.TP -\fB\-warp\fI boolean\fR -\fIboolean\fR must be a boolean value; it specifies whether -the screen pointer should be warped as well. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, and \fBMotion\fR events. The pointer will -only warp to a window if it is mapped. -.TP -\fB\-width\fI size\fR -\fISize\fR must be a screen distance; it specifies the \fIwidth\fR field -for the event. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%w\fR substitution for binding scripts. -.TP -\fB\-when\fI when\fR -\fIWhen\fR determines when the event will be processed; it must have one -of the following values: -.RS -.IP \fBnow\fR 10 -Process the event immediately, before the command returns. -This also happens if the \fB\-when\fR option is omitted. -.IP \fBtail\fR 10 -Place the event on Tcl's event queue behind any events already -queued for this application. -.IP \fBhead\fR 10 -Place the event at the front of Tcl's event queue, so that it -will be handled before any other events already queued. -.IP \fBmark\fR 10 -Place the event at the front of Tcl's event queue but behind any -other events already queued with \fB\-when mark\fR. -This option is useful when generating a series of events that should -be processed in order but at the front of the queue. -.RE -.TP -\fB\-x\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIx\fR field -for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, -\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR -events. -Corresponds to the \fB%x\fR substitution for binding scripts. -If \fIWindow\fR is empty the coordinate is relative to the -screen, and this option corresponds to the \fB%X\fR substitution -for binding scripts. -.TP -\fB\-y\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIy\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, -\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR -events. -Corresponds to the \fB%y\fR substitution for binding scripts. -If \fIWindow\fR is empty the coordinate is relative to the -screen, and this option corresponds to the \fB%Y\fR substitution -for binding scripts. -.PP -Any options that are not specified when generating an event are filled -with the value 0, except for \fIserial\fR, which is filled with the -next X event serial number. -.SH "PREDEFINED VIRTUAL EVENTS" -.PP -Tk defines the following virtual events for the purposes of -notification: -.TP -\fB<<AltUnderlined>>\fR -This is sent to widget to notify it that the letter it has underlined -(as an accelerator indicator) with the \fB\-underline\fR option has -been pressed in combination with the Alt key. The usual response to -this is to either focus into the widget (or some related widget) or to -invoke the widget. -.TP -\fB<<Invoke>>\fR -This can be sent to some widgets (e.g. button, listbox, menu) as an -alternative to <space>. -.TP -\fB<<ListboxSelect>>\fR -This is sent to a listbox when the set of selected item(s) in the -listbox is updated. -.TP -\fB<<MenuSelect>>\fR -This is sent to a menu when the currently selected item in the menu -changes. It is intended for use with context-sensitive help systems. -.TP -\fB<<Modified>>\fR -This is sent to a text widget when the contents of the widget are -changed. -.TP -\fB<<Selection>>\fR -This is sent to a text widget when the selection in the widget is -changed. -.TP -\fB<<ThemeChanged>>\fR -This is sent to all widgets when the ttk theme changed. The ttk -widgets listen to this event and redisplay themselves when it fires. -The legacy widgets ignore this event. -.TP -\fB<<TraverseIn>>\fR -This is sent to a widget when the focus enters the widget because of a -user-driven -.QW "tab to widget" -action. -.TP -\fB<<TraverseOut>>\fR -This is sent to a widget when the focus leaves the widget because of a -user-driven -.QW "tab to widget" -action. -.TP -\fB<<UndoStack>>\fR -This is sent to a text widget when its undo stack or redo stack becomes -empty or unempty. -.TP -\fB<<WidgetViewSync>>\fR -This is sent to a text widget when its internal data become obsolete, -and again when these internal data are back in sync with the widget -view. The detail field (%d substitution) is either true (when the -widget is in sync) or false (when it is not). -.PP -Tk defines the following virtual events for the purposes of unifying -bindings across multiple platforms. Users expect them to behave in the -following way: -.TP -\fB<<Clear>>\fR -Delete the currently selected widget contents. -.TP -\fB<<Copy>>\fR -Copy the currently selected widget contents to the clipboard. -.TP -\fB<<Cut>>\fR -Move the currently selected widget contents to the clipboard. -.TP -\fB<<LineEnd>>\fR -. -Move to the end of the line in the current widget while deselecting any -selected contents. -.TP -\fB<<LineStart>>\fR -. -Move to the start of the line in the current widget while deselecting any -selected contents. -.TP -\fB<<NextChar>>\fR -. -Move to the next item (i.e., visible character) in the current widget while -deselecting any selected contents. -.TP -\fB<<NextLine>>\fR -. -Move to the next line in the current widget while deselecting any selected -contents. -.TP -\fB<<NextPara>>\fR -. -Move to the next paragraph in the current widget while deselecting any -selected contents. -.TP -\fB<<NextWord>>\fR -. -Move to the next group of items (i.e., visible word) in the current widget -while deselecting any selected contents. -.TP -\fB<<Paste>>\fR -Replace the currently selected widget contents with the contents of -the clipboard. -.TP -\fB<<PasteSelection>>\fR -Insert the contents of the selection at the mouse location. (This -event has meaningful \fB%x\fR and \fB%y\fR substitutions). -.TP -\fB<<PrevChar>>\fR -. -Move to the previous item (i.e., visible character) in the current widget -while deselecting any selected contents. -.TP -\fB<<PrevLine>>\fR -. -Move to the previous line in the current widget while deselecting any selected -contents. -.TP -\fB<<PrevPara>>\fR -. -Move to the previous paragraph in the current widget while deselecting any -selected contents. -.TP -\fB<<PrevWindow>>\fR -Traverse to the previous window. -.TP -\fB<<PrevWord>>\fR -. -Move to the previous group of items (i.e., visible word) in the current widget -while deselecting any selected contents. -.TP -\fB<<Redo>>\fR -Redo one undone action. -.TP -\fB<<SelectAll>>\fR -. -Set the range of selected contents to the complete widget. -.TP -\fB<<SelectLineEnd>>\fR -. -Move to the end of the line in the current widget while extending the range -of selected contents. -.TP -\fB<<SelectLineStart>>\fR -. -Move to the start of the line in the current widget while extending the range -of selected contents. -.TP -\fB<<SelectNextChar>>\fR -. -Move to the next item (i.e., visible character) in the current widget while -extending the range of selected contents. -.TP -\fB<<SelectNextLine>>\fR -. -Move to the next line in the current widget while extending the range of -selected contents. -.TP -\fB<<SelectNextPara>>\fR -. -Move to the next paragraph in the current widget while extending the range -of selected contents. -.TP -\fB<<SelectNextWord>>\fR -. -Move to the next group of items (i.e., visible word) in the current widget -while extending the range of selected contents. -.TP -\fB<<SelectNone>>\fR -. -Reset the range of selected contents to be empty. -.TP -\fB<<SelectPrevChar>>\fR -. -Move to the previous item (i.e., visible character) in the current widget -while extending the range of selected contents. -.TP -\fB<<SelectPrevLine>>\fR -. -Move to the previous line in the current widget while extending the range of -selected contents. -.TP -\fB<<SelectPrevPara>>\fR -. -Move to the previous paragraph in the current widget while extending the -range of selected contents. -.TP -\fB<<SelectPrevWord>>\fR -. -Move to the previous group of items (i.e., visible word) in the current widget -while extending the range of selected contents. -.TP -\fB<<ToggleSelection>>\fR -. -Toggle the selection. -.TP -\fB<<Undo>>\fR -. -Undo the last action. -.SH EXAMPLES -.SS "MAPPING KEYS TO VIRTUAL EVENTS" -.PP -In order for a virtual event binding to trigger, two things must -happen. First, the virtual event must be defined with the -\fBevent add\fR command. Second, a binding must be created for -the virtual event with the \fBbind\fR command. -Consider the following virtual event definitions: -.PP -.CS -\fBevent add\fR <<Paste>> <Control-y> -\fBevent add\fR <<Paste>> <Button-2> -\fBevent add\fR <<Save>> <Control-X><Control-S> -\fBevent add\fR <<Save>> <Shift-F12> -if {[tk windowingsystem] eq "aqua"} { - \fBevent add\fR <<Save>> <Command-s> -} -.CE -.PP -In the \fBbind\fR command, a virtual event can be bound like any other -builtin event type as follows: -.PP -.CS -bind Entry <<Paste>> {%W insert [selection get]} -.CE -.PP -The double angle brackets are used to specify that a virtual event is being -bound. If the user types Control-y or presses button 2, or if -a \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR, -then the \fB<<Paste>>\fR binding will be invoked. -.PP -If a virtual binding has the exact same sequence as a separate -physical binding, then the physical binding will take precedence. -Consider the following example: -.PP -.CS -\fBevent add\fR <<Paste>> <Control-y> <Meta-Control-y> -bind Entry <Control-y> {puts Control-y} -bind Entry <<Paste>> {puts Paste} -.CE -.PP -When the user types Control-y the \fB<Control-y>\fR binding -will be invoked, because a physical event is considered -more specific than a virtual event, all other things being equal. -However, when the user types Meta-Control-y the -\fB<<Paste>>\fR binding will be invoked, because the -\fBMeta\fR modifier in the physical pattern associated with the -virtual binding is more specific than the \fB<Control-y\fR> sequence for -the physical event. -.PP -Bindings on a virtual event may be created before the virtual event exists. -Indeed, the virtual event never actually needs to be defined, for instance, -on platforms where the specific virtual event would be meaningless or -ungeneratable. -.PP -When a definition of a virtual event changes at run time, all windows -will respond immediately to the new definition. -Starting from the preceding example, if the following code is executed: -.PP -.CS -bind Entry <Control-y> {} -\fBevent add\fR <<Paste>> <Key-F6> -.CE -.PP -the behavior will change such in two ways. First, the shadowed -\fB<<Paste>>\fR binding will emerge. -Typing Control-y will no longer invoke the \fB<Control-y>\fR binding, -but instead invoke the virtual event \fB<<Paste>>\fR. Second, -pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding. -.SS "MOVING THE MOUSE POINTER" -.PP -Sometimes it is useful to be able to really move the mouse pointer. For -example, if you have some software that is capable of demonstrating directly -to the user how to use the program. To do this, you need to -.QW warp -the mouse around by using \fBevent generate\fR, like this: -.PP -.CS -for {set xy 0} {$xy < 200} {incr xy} { - \fBevent generate\fR . <Motion> -x $xy -y $xy -warp 1 - update - after 50 -} -.CE -.PP -Note that it is usually considered bad style to move the mouse pointer for the -user because it removes control from them. Therefore this technique should be -used with caution. Also note that it is not guaranteed to function on all -platforms. -.SH "SEE ALSO" -bind(n) -.SH KEYWORDS -event, binding, define, handle, virtual event -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/focus.n b/tk8.6/doc/focus.n deleted file mode 100644 index 4b8bb2a..0000000 --- a/tk8.6/doc/focus.n +++ /dev/null @@ -1,137 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH focus n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -focus \- Manage the input focus -.SH SYNOPSIS -.nf -\fBfocus\fR -\fBfocus \fIwindow\fR -\fBfocus \fIoption\fR ?\fIarg arg ...\fR? -.fi -.BE -.SH DESCRIPTION -.PP -The \fBfocus\fR command is used to manage the Tk input focus. -At any given time, one window on each display is designated as -the \fIfocus window\fR; any key press or key release events for the -display are sent to that window. -It is normally up to the window manager to redirect the focus among the -top-level windows of a display. For example, some window managers -automatically set the input focus to a top-level window whenever -the mouse enters it; others redirect the input focus only when -the user clicks on a window. -Usually the window manager will set the focus -only to top-level windows, leaving it up to the application to -redirect the focus among the children of the top-level. -.PP -Tk remembers one focus window for each top-level (the most recent -descendant of that top-level to receive the focus); when the window -manager gives the focus -to a top-level, Tk automatically redirects it to the remembered -window. Within a top-level Tk uses an \fIexplicit\fR focus model -by default. Moving the mouse within a top-level does not normally -change the focus; the focus changes only when a widget -decides explicitly to claim the focus (e.g., because of a button -click), or when the user types a key such as Tab that moves the -focus. -.PP -The Tcl procedure \fBtk_focusFollowsMouse\fR may be invoked to -create an \fIimplicit\fR focus model: it reconfigures Tk so that -the focus is set to a window whenever the mouse enters it. -The Tcl procedures \fBtk_focusNext\fR and \fBtk_focusPrev\fR -implement a focus order among the windows of a top-level; they -are used in the default bindings for Tab and Shift-Tab, among other -things. -.PP -The \fBfocus\fR command can take any of the following forms: -.TP -\fBfocus\fR -Returns the path name of the focus window on the display containing -the application's main window, or an empty string if no window in -this application has the focus on that display. Note: it is -better to specify the display explicitly using \fB\-displayof\fR -(see below) so that the code will work in applications using multiple -displays. -.TP -\fBfocus \fIwindow\fR -If the application currently has the input focus on \fIwindow\fR's -display, this command resets the input focus for \fIwindow\fR's display -to \fIwindow\fR and returns an empty string. -If the application does not currently have the input focus on -\fIwindow\fR's display, \fIwindow\fR will be remembered as the focus -for its top-level; the next time the focus arrives at the top-level, -Tk will redirect it to \fIwindow\fR. -If \fIwindow\fR is an empty string then the command does nothing. -.TP -\fBfocus \-displayof\fR \fIwindow\fR -Returns the name of the focus window on the display containing \fIwindow\fR. -If the focus window for \fIwindow\fR's display is not in this -application, the return value is an empty string. -.TP -\fBfocus \-force \fIwindow\fR -Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if -the application does not currently have the input focus for the display. -This command should be used sparingly, if at all. -In normal usage, an application should not claim the focus for -itself; instead, it should wait for the window manager to give it -the focus. -If \fIwindow\fR is an empty string then the command does nothing. -.TP -\fBfocus \-lastfor\fR \fIwindow\fR -Returns the name of the most recent window to have the input focus -among all the windows in the same top-level as \fIwindow\fR. -If no window in that top-level has ever had the input focus, or -if the most recent focus window has been deleted, then the name -of the top-level is returned. The return value is the window that -will receive the input focus the next time the window manager gives -the focus to the top-level. -.SH "QUIRKS" -.PP -When an internal window receives the input focus, Tk does not actually -set the X focus to that window; as far as X is concerned, the focus -will stay on the top-level window containing the window with the focus. -However, Tk generates FocusIn and FocusOut events just as if the X -focus were on the internal window. This approach gets around a -number of problems that would occur if the X focus were actually moved; -the fact that the X focus is on the top-level is invisible unless -you use C code to query the X server directly. -.SH "EXAMPLE" -.PP -To make a window that only participates in the focus traversal ring -when a variable is set, add the following bindings to the widgets -\fIbefore\fR and \fIafter\fR it in that focus ring: -.CS -button .before \-text "Before" -button .middle \-text "Middle" -button .after \-text "After" -checkbutton .flag \-variable traverseToMiddle \-takefocus 0 -pack .flag \-side left -pack .before .middle .after -bind .before <Tab> { - if {!$traverseToMiddle} { - \fBfocus\fR .after - break - } -} -bind .after <Shift\-Tab> { - if {!$traverseToMiddle} { - \fBfocus\fR .before - break - } -} -\fBfocus\fR .before -.CE -.SH KEYWORDS -events, focus, keyboard, top-level, window manager -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/focusNext.n b/tk8.6/doc/focusNext.n deleted file mode 100644 index ffcf971..0000000 --- a/tk8.6/doc/focusNext.n +++ /dev/null @@ -1,60 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_focusNext n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus. -.SH SYNOPSIS -\fBtk_focusNext \fIwindow\fR -.sp -\fBtk_focusPrev \fIwindow\fR -.sp -\fBtk_focusFollowsMouse\fR -.BE -.SH DESCRIPTION -.PP -\fBtk_focusNext\fR is a utility procedure used for keyboard traversal. -It returns the -.QW next -window after \fIwindow\fR in focus order. The focus order is determined by -the stacking order of windows and the structure of the window hierarchy. -Among siblings, the focus order is the same as the stacking order, with the -lowest window being first. -If a window has children, the window is visited first, followed by -its children (recursively), followed by its next sibling. -Top-level windows other than \fIwindow\fR are skipped, so that -\fBtk_focusNext\fR never returns a window in a different top-level -from \fIwindow\fR. -.PP -After computing the next window, \fBtk_focusNext\fR examines the -window's \fB\-takefocus\fR option to see whether it should be skipped. -If so, \fBtk_focusNext\fR continues on to the next window in the focus -order, until it eventually finds a window that will accept the focus -or returns back to \fIwindow\fR. -.PP -\fBtk_focusPrev\fR is similar to \fBtk_focusNext\fR except that it -returns the window just before \fIwindow\fR in the focus order. -.PP -\fBtk_focusFollowsMouse\fR changes the focus model for the application -to an implicit one where the window under the mouse gets the focus. -After this procedure is called, whenever the mouse enters a window -Tk will automatically give it the input focus. -The \fBfocus\fR command may be used to move the focus to a window -other than the one under the mouse, but as soon as the mouse moves -into a new window the focus will jump to that window. -Note: at present there is no built-in support for returning the -application to an explicit focus model; to do this you will have -to write a script that deletes the bindings created by -\fBtk_focusFollowsMouse\fR. -.SH KEYWORDS -focus, keyboard traversal, top-level -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/font.n b/tk8.6/doc/font.n deleted file mode 100644 index 72f9270..0000000 --- a/tk8.6/doc/font.n +++ /dev/null @@ -1,409 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net> -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH font n 8.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -font \- Create and inspect fonts. -.SH SYNOPSIS -\fBfont\fI option \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBfont\fR command provides several facilities for dealing with -fonts, such as defining named fonts and inspecting the actual attributes of -a font. The command has several different forms, determined by the -first argument. The following forms are currently supported: -.TP -\fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR? -. -Returns information about the actual attributes that are obtained when -\fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained -may differ from the attributes requested due to platform-dependent -limitations, such as the availability of font families and point sizes. -\fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the -\fIwindow\fR argument is omitted, it defaults to the main window. If -\fIoption\fR is specified, returns the value of that attribute; if it is -omitted, the return value is a list of all the attributes and their values. -See \fBFONT OPTIONS\fR below for a list of the possible attributes. If the -\fIchar\fR argument is supplied, it must be a single character. The font -attributes returned will be those of the specific font used to render -that character, which will be different from the base font if the base -font does not contain the given character. If \fIchar\fR may be a hyphen, it -should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled -\fIoption\fR. -.TP -\fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Query or modify the desired attributes for the named font called -\fIfontname\fR. If no \fIoption\fR is specified, returns a list describing -all the options and their values for \fIfontname\fR. If a single \fIoption\fR -is specified with no \fIvalue\fR, then returns the current value of that -attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, -then the command modifies the given named font to have the given values; in -this case, all widgets using that font will redisplay themselves using the -new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the -possible attributes. -.RS -.PP -Note that on Aqua/Mac OS X, the system fonts (see -\fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they -are implemented by the system theme. To achieve the effect of modification, -use \fBfont actual\fR to get their configuration and \fBfont create\fR to -synthesize a copy of the font which can be modified. -.RE -.TP -\fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? -. -Creates a new named font and returns its name. \fIfontname\fR specifies the -name for the font; if it is omitted, then Tk generates a new name of the -form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number -of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for -the new named font. See \fBFONT OPTIONS\fR below for a list of the possible -attributes. -.TP -\fBfont delete\fR \fIfontname\fR ?\fIfontname ...\fR? -. -Delete the specified named fonts. If there are widgets using the named font, -the named font will not actually be deleted until all the instances are -released. Those widgets will continue to display using the last known values -for the named font. If a deleted named font is subsequently recreated with -another call to \fBfont create\fR, the widgets will use the new named font -and redisplay themselves using the new attributes of that font. -.TP -\fBfont families\fR ?\fB\-displayof \fIwindow\fR? -. -The return value is a list of the case-insensitive names of all font families -that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is -omitted, it defaults to the main window. -.TP -\fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR -. -Measures the amount of space the string \fItext\fR would use in the given -\fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; -see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is -omitted, it -defaults to the main window. The return value is the total width in pixels -of \fItext\fR, not including the extra pixels used by highly exaggerated -characters such as cursive -.QW f . -If the string contains newlines or tabs, -those characters are not expanded or treated specially when measuring the -string. -.TP -\fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? -. -Returns information about the metrics (the font-specific data), for -\fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font -description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR -argument is -omitted, it defaults to the main window. If \fIoption\fR is specified, -returns the value of that metric; if it is omitted, the return value is a -list of all the metrics and their values. See \fBFONT METRICS\fR -below for a list of the possible metrics. -.TP -\fBfont names\fR -The return value is a list of all the named fonts that are currently defined. -.SH "FONT DESCRIPTIONS" -.PP -The following formats are accepted as a font description anywhere -\fIfont\fR is specified as an argument above; these same forms are also -permitted when specifying the \fB\-font\fR option for widgets. -.TP -[1] \fIfontname\fR -. -The name of a named font, created using the \fBfont create\fR command. When -a widget uses a named font, it is guaranteed that this will never cause an -error, as long as the named font exists, no matter what potentially invalid -or meaningless set of attributes the named font has. If the named font -cannot be displayed with exactly the specified attributes, some other close -font will be substituted automatically. -.TP -[2] \fIsystemfont\fR -. -The platform-specific name of a font, interpreted by the graphics server. -This also includes, under X, an XLFD (see [4]) for which a single -.QW \fB*\fR -character was used to elide more than one field in the middle of the -name. See \fBPLATFORM SPECIFIC FONTS\fR for a list of the system fonts. -.TP -[3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? -. -A properly formed list whose first element is the desired font -\fIfamily\fR and whose optional second element is the desired \fIsize\fR. -The interpretation of the \fIsize\fR attribute follows the same rules -described for \fB\-size\fR in \fBFONT OPTIONS\fR below. Any -additional optional -arguments following the \fIsize\fR are font \fIstyle\fRs. Possible values -for the \fIstyle\fR arguments are as follows: -.RS -.DS -.ta 3c 6c 9c -\fBnormal\fR \fBbold\fR \fBroman\fR \fBitalic\fR -\fBunderline\fR \fBoverstrike\fR -.DE -.RE -.TP -[4] X-font names (XLFD) -. -A Unix-centric font name of the form -\fI\-foundry\-family\-weight\-slant\-setwidth\-addstyle\-pixel\-point\-resx\-resy\-spacing\-width\-charset\-encoding\fR. -The -.QW \fB*\fR -character may be used to skip individual fields that the -user does not care about. There must be exactly one -.QW \fB*\fR -for each field skipped, except that a -.QW \fB*\fR -at the end of the XLFD skips any -remaining fields; the shortest valid XLFD is simply -.QW \fB*\fR , -signifying all fields as defaults. Any fields that were skipped are -given default -values. For compatibility, an XLFD always chooses a font of the specified -pixel size (not point size); although this interpretation is not strictly -correct, all existing applications using XLFDs assumed that one -.QW point -was in fact one pixel and would display incorrectly (generally larger) if -the correct size font were actually used. -.TP -[5] \fIoption value \fR?\fIoption value ...\fR? -. -A properly formed list of \fIoption\fR\-\fIvalue\fR pairs that specify -the desired attributes of the font, in the same format used when defining -a named font; see \fBFONT OPTIONS\fR below. -.LP -When font description \fIfont\fR is used, the system attempts to parse the -description according to each of the above five rules, in the order specified. -Cases [1] and [2] must match the name of an existing named font or of a -system font. Cases [3], [4], and [5] are accepted on all -platforms and the closest available font will be used. In some situations -it may not be possible to find any close font (e.g., the font family was -a garbage value); in that case, some system-dependent default font is -chosen. If the font description does not match any of the above patterns, -an error is generated. -.SH "FONT METRICS" -.PP -The following options are used by the \fBfont metrics\fR command to query -font-specific data determined when the font was created. These properties are -for the whole font itself and not for individual characters drawn in that -font. In the following definitions, the -.QW baseline -of a font is the -horizontal line where the bottom of most letters line up; certain letters, -such as lower-case -.QW g -stick below the baseline. -.TP -\fB\-ascent \0\fR -. -The amount in pixels that the tallest letter sticks up above the baseline of -the font, plus any extra blank space added by the designer of the font. -.TP -\fB\-descent \0\fR -. -The largest amount in pixels that any letter sticks down below the baseline -of the font, plus any extra blank space added by the designer of the font. -.TP -\fB\-linespace\fR -. -Returns how far apart vertically in pixels two lines of text using the same -font should be placed so that none of the characters in one line overlap any -of the characters in the other line. This is generally the sum of the ascent -above the baseline line plus the descent below the baseline. -.TP -\fB\-fixed \0\fR -. -Returns a boolean flag that is -.QW \fB1\fR -if this is a fixed-width font, -where each normal character is the same width as all the other -characters, or is -.QW \fB0\fR -if this is a proportionally-spaced font, where -individual characters have different widths. The widths of control -characters, tab characters, and other non-printing characters are not -included when calculating this value. -.SH "FONT OPTIONS" -.PP -The following options are supported on all platforms, and are used when -constructing a named font or when specifying a font using style [5] as -above: -.TP -\fB\-family \fIname\fR -. -The case-insensitive font family name. Tk guarantees to support the font -families named \fBCourier\fR (a monospaced -.QW typewriter -font), \fBTimes\fR (a serifed -.QW newspaper -font), and \fBHelvetica\fR (a sans-serif -.QW European -font). The most closely matching native font family will -automatically be substituted when one of the above font families is used. -The \fIname\fR may also be the name of a native, platform-specific font -family; in that case it will work as desired on one platform but may not -display correctly on other platforms. If the family is unspecified or -unrecognized, a platform-specific default font will be chosen. -.TP -\fB\-size \fIsize\fR -. -The desired size of the font. If the \fIsize\fR argument is a positive -number, it is interpreted as a size in points. If \fIsize\fR is a negative -number, its absolute value is interpreted as a size in pixels. If a -font cannot be displayed at the specified size, a nearby size will be -chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default -size will be chosen. -.RS -.PP -Sizes should normally be specified in points so the application will remain -the same ruler size on the screen, even when changing screen resolutions or -moving scripts across platforms. However, specifying pixels is useful in -certain circumstances such as when a piece of text must line up with respect -to a fixed-size bitmap. The mapping between points and pixels is set when -the application starts, based on properties of the installed monitor, but it -can be overridden by calling the \fBtk scaling\fR command. -.RE -.TP -\fB\-weight \fIweight\fR -. -The nominal thickness of the characters in the font. The value -\fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a -bold font. The closest available weight to the one specified will -be chosen. The default weight is \fBnormal\fR. -.TP -\fB\-slant \fIslant\fR -The amount the characters in the font are slanted away from the -vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. -A roman font is the normal, upright appearance of a font, while -an italic font is one that is tilted some number of degrees from upright. -The closest available slant to the one specified will be chosen. -The default slant is \fBroman\fR. -.TP -\fB\-underline \fIboolean\fR -The value is a boolean flag that specifies whether characters in this -font should be underlined. The default value for underline is \fBfalse\fR. -.TP -\fB\-overstrike \fIboolean\fR -The value is a boolean flag that specifies whether a horizontal line should -be drawn through the middle of characters in this font. The default value -for overstrike is \fBfalse\fR. -.SH "STANDARD FONTS" -.PP -The following named fonts are supported on all systems, and default to values -that match appropriate system defaults. -.TP -\fBTkDefaultFont\fR -. -This font is the default for all GUI items not otherwise specified. -.TP -\fBTkTextFont\fR -. -This font should be used for user text in entry widgets, listboxes etc. -.TP -\fBTkFixedFont\fR -. -This font is the standard fixed-width font. -.TP -\fBTkMenuFont\fR -. -This font is used for menu items. -.TP -\fBTkHeadingFont\fR -. -This font should be used for column headings in lists and tables. -.TP -\fBTkCaptionFont\fR -. -This font should be used for window and dialog caption bars. -.TP -\fBTkSmallCaptionFont\fR -. -This font should be used for captions on contained windows or tool dialogs. -.TP -\fBTkIconFont\fR -. -This font should be used for icon captions. -.TP -\fBTkTooltipFont\fR -. -This font should be used for tooltip windows (transient information windows). -.LP -It is \fInot\fR advised to change these fonts, as they may be modified by Tk -itself in response to system changes. Instead, make a copy of the font and -modify that. -.SH "PLATFORM SPECIFIC FONTS" -.PP -The following system fonts are supported: -.TP -\fBX Windows\fR -All valid X font names, including those listed by xlsfonts(1), are available. -.TP -\fBMS Windows\fR -The following fonts are supported, and are mapped to the user's -style defaults. -.RS -.DS -.ta 3c 6c -\fBsystem\fR \fBansi\fR \fBdevice\fR -\fBsystemfixed\fR \fBansifixed\fR \fBoemfixed\fR -.DE -.RE -.TP -\fBMac OS X\fR -The following fonts are supported, and are mapped to the user's -style defaults. -.RS -.DS -.ta 3c 6c -\fBsystem\fR \fBapplication\fR \fBmenu\fR -.DE -.PP -Additionally, the following named fonts provide access to the Aqua -theme fonts: -.DS -.ta 5c -\fBsystemSystemFont\fR \fBsystemEmphasizedSystemFont\fR -\fBsystemSmallSystemFont\fR \fBsystemSmallEmphasizedSystemFont\fR -\fBsystemApplicationFont\fR \fBsystemLabelFont\fR -\fBsystemViewsFont\fR \fBsystemMenuTitleFont\fR -\fBsystemMenuItemFont\fR \fBsystemMenuItemMarkFont\fR -\fBsystemMenuItemCmdKeyFont\fR \fBsystemWindowTitleFont\fR -\fBsystemPushButtonFont\fR \fBsystemUtilityWindowTitleFont\fR -\fBsystemAlertHeaderFont\fR \fBsystemToolbarFont\fR -\fBsystemMiniSystemFont\fR \fBsystemDetailSystemFont\fR -\fBsystemDetailEmphasizedSystemFont\fR -.DE -.RE -.SH EXAMPLE -.PP -Fill a text widget with lots of font demonstrators, one for every font -family installed on your system: -.CS -pack [text .t \-wrap none] \-fill both \-expand 1 -set count 0 -set tabwidth 0 -foreach family [lsort \-dictionary [\fBfont families\fR]] { - .t tag configure f[incr count] \-font [list $family 10] - .t insert end ${family}:\\t {} \e - "This is a simple sampler\en" f$count - set w [\fBfont measure\fR [.t cget \-font] ${family}:] - if {$w+5 > $tabwidth} { - set tabwidth [expr {$w+5}] - .t configure \-tabs $tabwidth - } -} -.CE -.SH "SEE ALSO" -options(n) -.SH KEYWORDS -font -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/fontchooser.n b/tk8.6/doc/fontchooser.n deleted file mode 100644 index bdd51c7..0000000 --- a/tk8.6/doc/fontchooser.n +++ /dev/null @@ -1,181 +0,0 @@ -'\" -'\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net> -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH fontchooser n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -fontchooser \- control font selection dialog -.SH SYNOPSIS -\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR? -.sp -\fBtk fontchooser\fR \fBshow\fR -.sp -\fBtk fontchooser\fR \fBhide\fR -.BE -.SH DESCRIPTION -.PP -The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses -the native platform font selection dialog where available, or a dialog -implemented in Tcl otherwise. -.PP -Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not -return an immediate result, as on some platforms (Mac OS X) the standard font -dialog is modeless while on others (Windows) it is modal. To accommodate this -difference, all user interaction with the dialog will be communicated to the -caller via callbacks or virtual events. -.PP -The \fBtk fontchooser\fR command can have one of the following forms: -.TP -\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR? -. -Set or query one or more of the configurations options below (analogous to Tk -widget configuration). -.TP -\fBtk fontchooser\fR \fBshow\fR -. -Show the font selection dialog. Depending on the platform, may return -immediately or only once the dialog has been withdrawn. -.TP -\fBtk fontchooser\fR \fBhide\fR -. -Hide the font selection dialog if it is visible and cause any pending -\fBtk fontchooser\fR \fBshow\fR command to return. -.PP -.SH "CONFIGURATION OPTIONS" -.TP -\fB\-parent\fR -Specifies/returns the logical parent window of the font selection dialog -(similar to the \fB\-parent\fR option to other dialogs). The font selection -dialog is hidden if it is visible when the parent window is destroyed. -.TP -\fB\-title\fR -Specifies/returns the title of the dialog. Has no effect on platforms where the -font selection dialog does not support titles. -.TP -\fB\-font\fR -Specifies/returns the font that is currently selected in the dialog if it is -visible, or that will be initially selected when the dialog is shown (if -supported by the platform). Can be set to the empty string to indicate that no -font should be selected. Fonts can be specified in any form given by the "FONT -DESCRIPTION" section in the \fBfont\fR manual page. -.TP -\fB\-command\fR -Specifies/returns the command prefix to be called when a font selection has -been made by the user. The command prefix is evaluated at the global level -after having the specification of the selected font appended. On platforms -where the font selection dialog offers the user control of further font -attributes (such as color), additional key/value pairs may be appended before -evaluation. Can be set to the empty string to indicate that no callback should -be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" -section in the \fBfont\fR manual page (i.e. a list of the form -\fI{family size style ?style ...?}\fR). -.TP -\fB\-visible\fR -Read-only option that returns a boolean indicating whether the font selection -dialog is currently visible. Attempting to set this option results in an error. - -.PP -.SH "VIRTUAL EVENTS" -.TP -\fB<<TkFontchooserVisibility>>\fR -Sent to the dialog parent whenever the visibility of the font selection dialog -changes, both as a result of user action (e.g. disposing of the dialog via -OK/Cancel button or close box) and of the \fBtk fontchooser\fR -\fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the -current visibility of the dialog by querying the \fB\-visible\fR configuration -option. -.TP -\fB<<TkFontchooserFontChanged>>\fR -Sent to the dialog parent whenever the font selection dialog is visible and the -selected font changes, both as a result of user action and of the \fB\-font\fR -configuration option being set. Binding scripts can determine the currently -selected font by querying the \fB\-font\fR configuration option. -.PP -.SH NOTES -.PP -Callers should not expect a result from \fBtk fontchooser\fR \fBshow\fR and may -not assume that the dialog has been withdrawn or closed when the command -returns. All user interaction with the dialog is communicated to the caller via -the \fB\-command\fR callback and the \fB<<TkFontchooser*>>\fR virtual events. -It is implementation dependent which exact user actions result in the callback -being called resp. the virtual events being sent. Where an Apply or OK button -is present in the dialog, that button will trigger the \fB\-command\fR callback -and \fB<<TkFontchooserFontChanged>>\fR virtual event. On some implementations -other user actions may also have that effect; on Mac OS X for instance, the -standard font selection dialog immediately reflects all user choices to the -caller. -.PP -In the presence of multiple widgets intended to be influenced by the font -selection dialog, care needs to be taken to correctly handle focus changes: the -font selected in the dialog should always match the current font of the widget -with the focus, and the \fB\-command\fR callback should only act on the widget -with the focus. The recommended practice is to set font dialog \fB\-font\fR and -\fB\-command\fR configuration options in per\-widget \fB<FocusIn>\fR handlers -(and if necessary to unset them \- i.e. set to the empty string \- in -corresponding \fB<FocusOut>\fR handlers). This is particularly important for -implementers of library code using the font selection dialog, to avoid -conflicting with application code that may also want to use the dialog. -.PP -Because the font selection dialog is application-global, in the presence of -multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR -callback set by the interpreter that most recently called \fBtk fontchooser\fR -\fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response -to user action and only the \fB\-parent\fR set by that interpreter will receive -\fB<<TkFontchooser*>>\fR virtual events. -.PP -The font dialog implementation may only store (and return) \fBfont\fR -\fBactual\fR data as the value of the \fB\-font\fR configuration option. This -can be an issue when \fB\-font\fR is set to a named font, if that font is -subsequently changed, the font dialog \fB\-font\fR option needs to be set again -to ensure its selected font matches the new value of the named font. -.PP -.SH EXAMPLE -.PP -.CS -proc fontchooserDemo {} { - wm title . "Font Chooser Demo" - \fBtk fontchooser\fR \fBconfigure\fR \-parent . - button .b \-command fontchooserToggle \-takefocus 0 - fontchooserVisibility .b - bind . \fB<<TkFontchooserVisibility>>\fR \\ - [list fontchooserVisibility .b] - foreach w {.t1 .t2} { - text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid - bind $w <FocusIn> [list fontchooserFocus $w] - $w insert end "Text Widget $w" - } - .t1 configure \-font {Courier 14} - .t2 configure \-font {Times 16} - pack .b .t1 .t2; focus .t1 -} -proc fontchooserToggle {} { - \fBtk fontchooser\fR [expr { - [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? - "\fBhide\fR" : "\fBshow\fR"}] -} -proc fontchooserVisibility {w} { - $w configure \-text [expr { - [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? - "Hide Font Dialog" : "Show Font Dialog"}] -} -proc fontchooserFocus {w} { - \fBtk fontchooser\fR \fBconfigure\fR \-font [$w cget \-font] \\ - \-command [list fontchooserFontSelection $w] -} -proc fontchooserFontSelection {w font args} { - $w configure \-font [font actual $font] -} -fontchooserDemo -.CE -.SH "SEE ALSO" -font(n), tk(n) -.SH KEYWORDS -dialog, font, font selection, font chooser, font panel -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/frame.n b/tk8.6/doc/frame.n deleted file mode 100644 index 72a22db..0000000 --- a/tk8.6/doc/frame.n +++ /dev/null @@ -1,139 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH frame n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -frame \- Create and manipulate 'frame' simple container widgets -.SH SYNOPSIS -\fBframe\fR \fIpathName\fR ?\fIoptions\fR? -.SO -\-borderwidth \-highlightcolor \-pady -\-cursor \-highlightthickness \-relief -\-highlightbackground \-padx \-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fB\-background\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fB\-class\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fB\-colormap\fR option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-container container Container -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the \fBconfigure\fR -widget command. -Note that \fB\-borderwidth\fR, \fB\-padx\fR and \fB\-pady\fR are ignored when -configured as a container since a container has no border. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. If this option is less than or equal -to zero then the window will not request any size at all. Note that this -sets the total height of the frame, any \fB\-borderwidth\fR or similar is -not added. Normally \fB\-height\fR should not be used if a propagating -geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the -frame since the geometry manager will override the height of the frame. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the same -visual as its parent. -The \fB\-visual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. If this option is less than or equal -to zero then the window will not request any size at all. Note that this -sets the total width of the frame, any \fB\-borderwidth\fR or similar is -not added. Normally \fB\-width\fR should not be used if a propagating -geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the -frame since the geometry manager will override the width of the frame. -.BE -.SH DESCRIPTION -.PP -The \fBframe\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a frame widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the frame such as its background color -and relief. The \fBframe\fR command returns the -path name of the new window. -.PP -A frame is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. The only features -of a frame are its background color and an optional 3-D border to make the -frame appear raised or sunken. -.SH "WIDGET COMMAND" -.PP -The \fBframe\fR command creates a new Tcl command whose -name is the same as the path name of the frame's window. 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 -\fIPathName\fR is the name of the command, which is the same as -the frame widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for frame 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 \fBframe\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value 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 \fBframe\fR -command. -.SH BINDINGS -.PP -When a new frame is created, it has no default event bindings: -frames are not intended to be interactive. -.SH "SEE ALSO" -labelframe(n), toplevel(n), ttk::frame(n) -.SH KEYWORDS -frame, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/getOpenFile.n b/tk8.6/doc/getOpenFile.n deleted file mode 100644 index d2323de..0000000 --- a/tk8.6/doc/getOpenFile.n +++ /dev/null @@ -1,207 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_getOpenFile, tk_getSaveFile \- pop up a dialog box for the user to select a file to open or save. -.SH SYNOPSIS -.nf -\fBtk_getOpenFile \fR?\fIoption value ...\fR? -\fBtk_getSaveFile \fR?\fIoption value ...\fR? -.fi -.BE -.SH DESCRIPTION -.PP -The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a -dialog box for the user to select a file to open or save. The -\fBtk_getOpenFile\fR command is usually associated with the \fBOpen\fR -command in the \fBFile\fR menu. Its purpose is for the user to select an -existing file \fIonly\fR. If the user enters a non-existent file, the -dialog box gives the user an error prompt and requires the user to give -an alternative selection. If an application allows the user to create -new files, it should do so by providing a separate \fBNew\fR menu command. -.PP -The \fBtk_getSaveFile\fR command is usually associated with the \fBSave -as\fR command in the \fBFile\fR menu. If the user enters a file that -already exists, the dialog box prompts the user for confirmation -whether the existing file should be overwritten or not. -.PP -The following \fIoption\-value\fR pairs are possible as command line -arguments to these two commands: -.TP -\fB\-command\fR \fIstring\fR -Specifies the prefix of a Tcl command to invoke when the user closes the -dialog after having selected an item. This callback is not called if the -user cancelled the dialog. The actual command consists of \fIstring\fR -followed by a space and the value selected by the user in the dialog. This -is only available on Mac OS X. -.TP -\fB\-confirmoverwrite\fR \fIboolean\fR -Configures how the Save dialog reacts when the selected file already -exists, and saving would overwrite it. A true value requests a -confirmation dialog be presented to the user. A false value requests -that the overwrite take place without confirmation. Default value is true. -.TP -\fB\-defaultextension\fR \fIextension\fR -. -Specifies a string that will be appended to the filename if the user -enters a filename without an extension. The default value is the empty -string, which means no extension will be appended to the filename in -any case. This option is ignored on Mac OS X, which -does not require extensions to filenames, -and the UNIX implementation guesses reasonable values for this from -the \fB\-filetypes\fR option when this is not supplied. -.TP -\fB\-filetypes\fR \fIfilePatternList\fR -. -If a \fBFile types\fR listbox exists in the file dialog on the particular -platform, this option gives the \fIfiletype\fRs in this listbox. When -the user choose a filetype in the listbox, only the files of that type -are listed. If this option is unspecified, or if it is set to the -empty list, or if the \fBFile types\fR listbox is not supported by the -particular platform then all files are listed regardless of their -types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a -discussion on the contents of \fIfilePatternList\fR. -.TP -\fB\-initialdir\fR \fIdirectory\fR -. -Specifies that the files in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, -the initial directory defaults to the current working directory -on non-Windows systems and on Windows systems prior to Vista. -On Vista and later systems, the initial directory defaults to the last -user-selected directory for the application. If the -parameter specifies a relative path, the return value will convert the -relative path to an absolute path. -.TP -\fB\-initialfile\fR \fIfilename\fR -. -Specifies a filename to be displayed in the dialog when it pops up. -.TP -\fB\-message\fR \fIstring\fR -. -Specifies a message to include in the client area of the dialog. -This is only available on Mac OS X. -.TP -\fB\-multiple\fR \fIboolean\fR -. -Allows the user to choose multiple files from the Open dialog. -.TP -\fB\-parent\fR \fIwindow\fR -. -Makes \fIwindow\fR the logical parent of the file dialog. The file -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 is displayed. -.TP -\fB\-typevariable\fR \fIvariableName\fR -. -The global variable \fIvariableName\fR is used to preselect which filter is -used from \fIfilterList\fR when the dialog box is opened and is -updated when the dialog box is closed, to the last selected -filter. The variable is read once at the beginning to select the -appropriate filter. If the variable does not exist, or its value does -not match any filter typename, or is empty (\fB{}\fR), the dialog box -will revert to the default behavior of selecting the first filter in -the list. If the dialog is canceled, the variable is not modified. -.PP -If the user selects a file, both \fBtk_getOpenFile\fR and -\fBtk_getSaveFile\fR return the full pathname of this file. If the -user cancels the operation, both commands return the empty string. -.SH "SPECIFYING FILE PATTERNS" -.PP -The \fIfilePatternList\fR value given by the \fB\-filetypes\fR option -is a list of file patterns. Each file pattern is a list of the -form -.CS -\fItypeName\fR {\fIextension\fR ?\fIextension ...\fR?} ?{\fImacType\fR ?\fImacType ...\fR?}? -.CE -\fItypeName\fR is the name of the file type described by this -file pattern and is the text string that appears in the \fBFile types\fR -listbox. \fIextension\fR is a file extension for this file pattern. -\fImacType\fR is a four-character Macintosh file type. The list of -\fImacType\fRs is optional and may be omitted for applications that do -not need to execute on the Macintosh platform. -.PP -Several file patterns may have the same \fItypeName,\fR in which case -they refer to the same file type and share the same entry in the -listbox. When the user selects an entry in the listbox, all the files -that match at least one of the file patterns corresponding -to that entry are listed. Usually, each file pattern corresponds to a -distinct type of file. The use of more than one file pattern for one -type of file is only necessary on the Macintosh platform. -.PP -On the Macintosh platform, a file matches a file pattern if its -name matches at least one of the \fIextension\fR(s) AND it -belongs to at least one of the \fImacType\fR(s) of the -file pattern. For example, the \fBC Source Files\fR file pattern in the -sample code matches with files that have a \fB\.c\fR extension AND -belong to the \fImacType\fR \fBTEXT\fR. To use the OR rule instead, -you can use two file patterns, one with the \fIextensions\fR only and -the other with the \fImacType\fR only. The \fBGIF Files\fR file type -in the sample code matches files that \fIeither\fR have a \fB\.gif\fR -extension OR belong to the \fImacType\fR \fBGIFF\fR. -.PP -On the Unix and Windows platforms, a file matches a file pattern -if its name matches at least one of the \fIextension\fR(s) of -the file pattern. The \fImacType\fRs are ignored. -.SH "SPECIFYING EXTENSIONS" -.PP -On the Unix and Macintosh platforms, extensions are matched using -glob-style pattern matching. On the Windows platform, extensions are -matched by the underlying operating system. The types of possible -extensions are: -.IP (1) -the special extension -.QW * -matches any file; -.IP (2) -the special extension -.MT -matches any files that do not have an extension (i.e., the filename -contains no full stop character); -.IP (3) -any character string that does not contain any wild card characters (* -and ?). -.PP -Due to the different pattern matching rules on the various platforms, -to ensure portability, wild card characters are not allowed in the -extensions, except as in the special extension -.QW * . -Extensions without a full stop character (e.g. -.QW ~ ) -are allowed but may not work on all platforms. -.SH EXAMPLE -.PP -.CS -set types { - {{Text Files} {.txt} } - {{TCL Scripts} {.tcl} } - {{C Source Files} {.c} TEXT} - {{GIF Files} {.gif} } - {{GIF Files} {} GIFF} - {{All Files} * } -} -set filename [\fBtk_getOpenFile\fR \-filetypes $types] - -if {$filename ne ""} { - # Open the file ... -} -.CE -.SH "SEE ALSO" -tk_chooseDirectory -.SH KEYWORDS -file selection dialog -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/grab.n b/tk8.6/doc/grab.n deleted file mode 100644 index a6d0d19..0000000 --- a/tk8.6/doc/grab.n +++ /dev/null @@ -1,140 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH grab n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -grab \- Confine pointer and keyboard events to a window sub-tree -.SH SYNOPSIS -\fBgrab \fR?\fB\-global\fR? \fIwindow\fR -.sp -\fBgrab \fIoption \fR?\fIarg arg \fR...? -.BE -.SH DESCRIPTION -.PP -This command implements simple pointer and keyboard grabs for Tk. -Tk's grabs are different than the grabs -described in the Xlib documentation. -When a grab is set for a particular window, Tk restricts all pointer -events to the grab window and its descendants in Tk's window hierarchy. -Whenever the pointer is within the grab window's subtree, the pointer -will behave exactly the same as if there had been no grab at all -and all events will be reported in the normal fashion. -When the pointer is outside \fIwindow\fR's tree, button presses and -releases and -mouse motion events are reported to \fIwindow\fR, and window entry -and window exit events are ignored. The grab subtree -.QW owns -the pointer: -windows outside the grab subtree will be visible on the screen -but they will be insensitive until the grab is released. -The tree of windows underneath the grab window can include top-level -windows, in which case all of those top-level windows -and their descendants will continue to receive mouse events -during the grab. -.PP -Two forms of grabs are possible: local and global. -A local grab affects only the grabbing application: events will -be reported to other applications as if the grab had never occurred. -Grabs are local by default. -A global grab locks out all applications on the screen, -so that only the given subtree of the grabbing application will be -sensitive to pointer events (mouse button presses, mouse button releases, -pointer motions, window entries, and window exits). -During global grabs the window manager will not receive pointer -events either. -.PP -During local grabs, keyboard events (key presses and key releases) -are delivered as usual: the window -manager controls which application receives keyboard events, and -if they are sent to any window in the grabbing application then they are -redirected to the focus window. -During a global grab Tk grabs the keyboard so that all keyboard events -are always sent to the grabbing application. -The \fBfocus\fR command is still used to determine which window in the -application receives the keyboard events. -The keyboard grab is released when the grab is released. -.PP -Grabs apply to particular displays. If an application has windows -on multiple displays then it can establish a separate grab on each -display. -The grab on a particular display affects only the windows on -that display. -It is possible for different applications on a single display to have -simultaneous local grabs, but only one application can have a global -grab on a given display at once. -.PP -The \fBgrab\fR command can take any of the following forms: -.TP -\fBgrab \fR?\fB\-global\fR? \fIwindow\fR -Same as \fBgrab set\fR, described below. -.TP -\fBgrab current \fR?\fIwindow\fR? -If \fIwindow\fR is specified, returns the name of the current grab -window in this application for \fIwindow\fR's display, or an empty -string if there is no such window. -If \fIwindow\fR is omitted, the command returns a list whose elements -are all of the windows grabbed by this application for all displays, -or an empty string if the application has no grabs. -.TP -\fBgrab release \fIwindow\fR -Releases the grab on \fIwindow\fR if there is one, otherwise does -nothing. Returns an empty string. -.TP -\fBgrab set \fR?\fB\-global\fR? \fIwindow\fR -Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the -grab is global, otherwise it is local. -If a grab was already in effect for this application on -\fIwindow\fR's display then it is automatically released. -If there is already a grab on \fIwindow\fR and it has the same -global/local form as the requested grab, then the command -does nothing. Returns an empty string. -.TP -\fBgrab status \fIwindow\fR -Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, -\fBlocal\fR if a local grab is set on \fIwindow\fR, and -\fBglobal\fR if a global grab is set. -.SH WARNING -.PP -It is very easy to use global grabs to render a display completely -unusable (e.g. by setting a grab on a widget which does not respond to -events and not providing any mechanism for releasing the grab). Take -\fIextreme\fR care when using them! -.SH BUGS -.PP -It took an incredibly complex and gross implementation to produce -the simple grab effect described above. -Given the current implementation, it is not safe for applications -to use the Xlib grab facilities at all except through the Tk grab -procedures. -If applications try to manipulate X's grab mechanisms directly, -things will probably break. -.PP -If a single process is managing several different Tk applications, -only one of those applications can have a local grab for a given -display at any given time. If the applications are in different -processes, this restriction does not exist. -.SH EXAMPLE -.PP -Set a grab so that only one button may be clicked out of a group. The -other buttons are unresponsive to the mouse until the middle button is -clicked. -.CS -pack [button .b1 \-text "Click me! #1" \-command {destroy .b1}] -pack [button .b2 \-text "Click me! #2" \-command {destroy .b2}] -pack [button .b3 \-text "Click me! #3" \-command {destroy .b3}] -\fBgrab\fR .b2 -.CE -.SH "SEE ALSO" -busy(n) -.SH KEYWORDS -grab, keyboard events, pointer events, window -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/grid.n b/tk8.6/doc/grid.n deleted file mode 100644 index c558071..0000000 --- a/tk8.6/doc/grid.n +++ /dev/null @@ -1,456 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH grid n 8.5 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -grid \- Geometry manager that arranges widgets in a grid -.SH SYNOPSIS -\fBgrid \fIoption arg \fR?\fIarg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBgrid\fR command is used to communicate with the grid -geometry manager that arranges widgets in rows and columns inside -of another window, called the geometry master (or master window). -The \fBgrid\fR command can have any of several forms, depending -on the \fIoption\fR argument: -.TP -\fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -. -If the first argument to \fBgrid\fR is suitable as the first slave -argument to \fBgrid configure\fR, either a window name (any value -starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR -(see the \fBRELATIVE PLACEMENT\fR section below), then the command is -processed in the same way as \fBgrid configure\fR. -.TP -\fBgrid anchor \fImaster\fR ?\fIanchor\fR? -. -The anchor value controls how to place the grid within the master -when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below -for further details. The default \fIanchor\fR is \fInw\fR. -.TP -\fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? -. -With no arguments, -the bounding box (in pixels) of the grid is returned. -The return value consists of 4 integers. The first two are the pixel -offset from the master window (x then y) of the top-left corner of the -grid, and the second two integers are the width and height of the grid, -also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on -the command line, then the bounding box for that cell is returned, where the -top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR -arguments are specified, then the bounding box spanning the rows and columns -indicated is returned. -.TP -\fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR? -. -Query or set the column properties of the \fIindex\fR column of the -geometry master, \fImaster\fR. -The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR -and \fB\-pad\fR. -If one or more options are provided, then \fIindex\fR may be given as -a list of column indices to which the configuration options will operate on. -Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR -the options apply to all columns currently occupied be slave windows. For -a window name, that window must be a slave of this master and the options -apply to all columns currently occupied be the slave. -The \fB\-minsize\fR option sets the minimum size, in screen units, -that will be permitted for this column. -The \fB\-weight\fR option (an integer value) -sets the relative weight for apportioning -any extra spaces among -columns. -A weight of zero (0) indicates the column will not deviate from its requested -size. A column whose weight is two will grow at twice the rate as a column -of weight one when extra space is allocated to the layout. -The \fB\-uniform\fR option, when a non-empty value is supplied, places -the column in a \fIuniform group\fR with other columns that have the -same value for \fB\-uniform\fR. The space for columns belonging to a -uniform group is allocated so that their sizes are always in strict -proportion to their \fB\-weight\fR values. See -\fBTHE GRID ALGORITHM\fR below for further details. -The \fB\-pad\fR option specifies the number of screen units that will be -added to the largest window contained completely in that column when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in a list of -.QW "\-option value" -pairs. -.TP -\fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -. -The arguments consist of the names of one or more slave windows -followed by pairs of arguments that specify how -to manage the slaves. -The characters \fB\-\fR, \fBx\fR and \fB^\fR, -can be specified instead of a window name to alter the default -location of a \fIslave\fR, as described in the \fBRELATIVE PLACEMENT\fR -section, below. -The following options are supported: -.RS -.TP -\fB\-column \fIn\fR -. -Insert the slave so that it occupies the \fIn\fRth column in the grid. -Column numbers start with 0. If this option is not supplied, then the -slave is arranged just to the right of previous slave specified on this -call to \fBgrid\fR, or column -.QW 0 -if it is the first slave. For each -\fBx\fR that immediately precedes the \fIslave\fR, the column position -is incremented by one. Thus the \fBx\fR represents a blank column -for this row in the grid. -.TP -\fB\-columnspan \fIn\fR -. -Insert the slave so that it occupies \fIn\fR columns in the grid. -The default is one column, unless the window name is followed by a -\fB\-\fR, in which case the columnspan is incremented once for each immediately -following \fB\-\fR. -.TP -\fB\-in \fIother\fR -. -Insert the slave(s) in the master -window given by \fIother\fR. The default is the first slave's -parent window. -.TP -\fB\-ipadx \fIamount\fR -. -The \fIamount\fR specifies how much horizontal internal padding to -leave on each side of the slave(s). This is space is added -inside the slave(s) border. -The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. -It defaults to 0. -.TP -\fB\-ipady \fIamount\fR -. -The \fIamount\fR specifies how much vertical internal padding to -leave on the top and bottom of the slave(s). -This space is added inside the slave(s) border. -The \fIamount\fR defaults to 0. -.TP -\fB\-padx \fIamount\fR -. -The \fIamount\fR specifies how much horizontal external padding to -leave on each side of the slave(s), in screen units. -\fIAmount\fR may be a list -of two values to specify padding for left and right separately. -The \fIamount\fR defaults to 0. -This space is added outside the slave(s) border. -.TP -\fB\-pady \fIamount\fR -. -The \fIamount\fR specifies how much vertical external padding to -leave on the top and bottom of the slave(s), in screen units. -\fIAmount\fR may be a list -of two values to specify padding for top and bottom separately. -The \fIamount\fR defaults to 0. -This space is added outside the slave(s) border. -.TP -\fB\-row \fIn\fR -. -Insert the slave so that it occupies the \fIn\fRth row in the grid. -Row numbers start with 0. If this option is not supplied, then the -slave is arranged on the same row as the previous slave specified on this -call to \fBgrid\fR, or the next row after the highest occupied row -if this is the first slave. -.TP -\fB\-rowspan \fIn\fR -. -Insert the slave so that it occupies \fIn\fR rows in the grid. -The default is one row. If the next \fBgrid\fR command contains -\fB^\fR characters instead of \fIslaves\fR that line up with the columns -of this \fIslave\fR, then the \fBrowspan\fR of this \fIslave\fR is -extended by one. -.TP -\fB\-sticky \fIstyle\fR -. -If a slave's cell is larger than its requested dimensions, this -option may be used to position (or stretch) the slave within its cell. -\fIStyle\fR is a string that contains zero or more of the characters -\fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. -The string can optionally contains spaces or -commas, but they are ignored. Each letter refers to a side (north, south, -east, or west) that the slave will -.QW stick -to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are -specified, the slave will be stretched to fill the entire -height (or width) of its cavity. The \fB\-sticky\fR option subsumes the -combination of \fB\-anchor\fR and \fB\-fill\fR that is used by \fBpack\fR. -The default is -.QW "" , -which causes the slave to be centered in its cavity, at its requested size. -.LP -If any of the slaves are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. -.RE -.TP -\fBgrid forget \fIslave \fR?\fIslave ...\fR? -. -Removes each of the \fIslave\fRs from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -The configuration options for that window are forgotten, so that if the -slave is managed once more by the grid geometry manager, the initial -default settings are used. -.TP -\fBgrid info \fIslave\fR -. -Returns a list whose elements are the current configuration state of -the slave given by \fIslave\fR in the same option-value form that -might be specified to \fBgrid configure\fR. -The first two elements of the list are -.QW "\fB\-in \fImaster\fR" -where \fImaster\fR is the slave's master. -.TP -\fBgrid location \fImaster x y\fR -. -Given \fIx\fR and \fIy\fR values in screen units relative to the master window, -the column and row number at that \fIx\fR and \fIy\fR location is returned. -For locations that are above or to the left of the grid, \fB\-1\fR is -returned. -.TP -\fBgrid propagate \fImaster\fR ?\fIboolean\fR? -. -If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR -then propagation is enabled for \fImaster\fR, which must be a window -name (see \fBGEOMETRY PROPAGATION\fR below). -If \fIboolean\fR has a false boolean value then propagation is -disabled for \fImaster\fR. -In either of these cases an empty string is returned. -If \fIboolean\fR is omitted then the command returns \fB0\fR or -\fB1\fR to indicate whether propagation is currently enabled -for \fImaster\fR. -Propagation is enabled by default. -.TP -\fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR? -. -Query or set the row properties of the \fIindex\fR row of the -geometry master, \fImaster\fR. -The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR -and \fB\-pad\fR. -If one or more options are provided, then \fIindex\fR may be given as -a list of row indices to which the configuration options will operate on. -Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR -the options apply to all rows currently occupied be slave windows. For -a window name, that window must be a slave of this master and the options -apply to all rows currently occupied be the slave. -The \fB\-minsize\fR option sets the minimum size, in screen units, -that will be permitted for this row. -The \fB\-weight\fR option (an integer value) -sets the relative weight for apportioning -any extra spaces among -rows. -A weight of zero (0) indicates the row will not deviate from its requested -size. A row whose weight is two will grow at twice the rate as a row -of weight one when extra space is allocated to the layout. -The \fB\-uniform\fR option, when a non-empty value is supplied, places -the row in a \fIuniform group\fR with other rows that have the -same value for \fB\-uniform\fR. The space for rows belonging to a -uniform group is allocated so that their sizes are always in strict -proportion to their \fB\-weight\fR values. See -\fBTHE GRID ALGORITHM\fR below for further details. -The \fB\-pad\fR option specifies the number of screen units that will be -added to the largest window contained completely in that row when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in a list of -.QW "-option value" -pairs. -.TP -\fBgrid remove \fIslave \fR?\fIslave ...\fR? -. -Removes each of the \fIslave\fRs from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -However, the configuration options for that window are remembered, -so that if the -slave is managed once more by the grid geometry manager, the previous -values are retained. -.TP -\fBgrid size \fImaster\fR -. -Returns the size of the grid (in columns then rows) for \fImaster\fR. -The size is determined either by the \fIslave\fR occupying the largest -row or column, or the largest column or row with a \fB\-minsize\fR, -\fB\-weight\fR, or \fB\-pad\fR that is non-zero. -.TP -\fBgrid slaves \fImaster\fR ?\fI\-option value\fR? -. -If no options are supplied, a list of all of the slaves in \fImaster\fR -are returned, most recently manages first. -\fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which -causes only the slaves in the row (or column) specified by \fIvalue\fR -to be returned. -.SH "RELATIVE PLACEMENT" -.PP -The \fBgrid\fR command contains a limited set of capabilities that -permit layouts to be created without specifying the row and column -information for each slave. This permits slaves to be rearranged, -added, or removed without the need to explicitly specify row and -column information. -When no column or row information is specified for a \fIslave\fR, -default values are chosen for -\fB\-column\fR, \fB\-row\fR, \fB\-columnspan\fR and \fB\-rowspan\fR -at the time the \fIslave\fR is managed. The values are chosen -based upon the current layout of the grid, the position of the \fIslave\fR -relative to other \fIslave\fRs in the same grid command, and the presence -of the characters \fB\-\fR, \fBx\fR, and \fB^\fR in \fBgrid\fR -command where \fIslave\fR names are normally expected. -.RS -.TP -\fB\-\fR -. -This increases the \fB\-columnspan\fR of the \fIslave\fR to the left. Several -\fB\-\fR's in a row will successively increase the number of columns spanned. A \fB\-\fR -may not follow a \fB^\fR or a \fBx\fR, nor may it be the first \fIslave\fR -argument to \fBgrid configure\fR. -.TP -\fBx\fR -. -This leaves an empty column between the \fIslave\fR on the left and -the \fIslave\fR on the right. -.TP -\fB^\fR -. -This extends the \fB\-rowspan\fR of the \fIslave\fR above the \fB^\fR's -in the grid. The number of \fB^\fR's in a row must match the number of -columns spanned by the \fIslave\fR above it. -.RE -.SH "THE GRID ALGORITHM" -.PP -The grid geometry manager lays out its slaves in three steps. -In the first step, the minimum size needed to fit all of the slaves -is computed, then (if propagation is turned on), a request is made -of the master window to become that size. -In the second step, the requested size is compared against the actual size -of the master. If the sizes are different, then spaces is added to or taken -away from the layout as needed. -For the final step, each slave is positioned in its row(s) and column(s) -based on the setting of its \fIsticky\fR flag. -.PP -To compute the minimum size of a layout, the grid geometry manager -first looks at all slaves whose \fB\-columnspan\fR and \fB\-rowspan\fR values are one, -and computes the nominal size of each row or column to be either the -\fIminsize\fR for that row or column, or the sum of the \fIpad\fRding -plus the size of the largest slave, whichever is greater. After that -the rows or columns in each uniform group adapt to each other. Then -the slaves whose row-spans or column-spans are greater than one are -examined. If a group of rows or columns need to be increased in size -in order to accommodate these slaves, then extra space is added to each -row or column in the group according to its \fIweight\fR. For each -group whose weights are all zero, the additional space is apportioned -equally. -.PP -When multiple rows or columns belong to a uniform group, the space -allocated to them is always in proportion to their weights. (A weight -of zero is considered to be 1.) In other words, a row or column -configured with \fB\-weight 1 \-uniform a\fR will have exactly the same -size as any other row or column configured with \fB\-weight 1 \-uniform -a\fR. A row or column configured with \fB\-weight 2 \-uniform b\fR will -be exactly twice as large as one that is configured with \fB\-weight 1 -\-uniform b\fR. -.PP -More technically, each row or column in the group will have a size -equal to \fIk*weight\fR for some constant \fIk\fR. The constant -\fIk\fR is chosen so that no row or column becomes smaller than its -minimum size. For example, if all rows or columns in a group have the -same weight, then each row or column will have the same size as the -largest row or column in the group. -.PP -For masters whose size is larger than the requested layout, the additional -space is apportioned according to the row and column weights. If all of -the weights are zero, the layout is placed within its master according to -the \fIanchor\fR value. -For masters whose size is smaller than the requested layout, space is taken -away from columns and rows according to their weights. However, once a -column or row shrinks to its minsize, its weight is taken to be zero. -If more space needs to be removed from a layout than would be permitted, as -when all the rows or columns are at their minimum sizes, the layout is -placed and clipped according to the \fIanchor\fR value. -.SH "GEOMETRY PROPAGATION" -.PP -The grid geometry manager normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the \fBgrid propagate\fR command may be used to -turn off propagation for one or more masters. -If propagation is disabled then grid will not set -the requested width and height of the master window. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. -.SH "RESTRICTIONS ON MASTER WINDOWS" -.PP -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. -In addition, all slaves in one call to \fBgrid\fR must have the same master. -.SH "STACKING ORDER" -.PP -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave has not been managed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. -.SH CREDITS -.PP -The \fBgrid\fR command is based on ideas taken from the \fIGridBag\fR -geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry -manager, written by George Howlett. -.SH EXAMPLES -.PP -A toplevel window containing a text widget and two scrollbars: -.PP -.CS -# Make the widgets -toplevel .t -text .t.txt \-wrap none \-xscroll {.t.h set} \-yscroll {.t.v set} -scrollbar .t.v \-orient vertical \-command {.t.txt yview} -scrollbar .t.h \-orient horizontal \-command {.t.txt xview} - -# Lay them out -\fBgrid\fR .t.txt .t.v \-sticky nsew -\fBgrid\fR .t.h \-sticky nsew - -# Tell the text widget to take all the extra room -\fBgrid rowconfigure\fR .t .t.txt \-weight 1 -\fBgrid columnconfigure\fR .t .t.txt \-weight 1 -.CE -.PP -Three widgets of equal width, despite their different -.QW natural -widths: -.PP -.CS -button .b \-text "Foo" -entry .e \-variable foo -label .l \-text "This is a fairly long piece of text" - -\fBgrid\fR .b .e .l \-sticky ew -\fBgrid columnconfigure\fR . "all" \-uniform allTheSame -.CE -.SH "SEE ALSO" -pack(n), place(n) -.SH KEYWORDS -geometry manager, location, grid, cell, propagation, size, pack -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/image.n b/tk8.6/doc/image.n deleted file mode 100644 index fd51cc0..0000000 --- a/tk8.6/doc/image.n +++ /dev/null @@ -1,102 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH image n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -image \- Create and manipulate images -.SH SYNOPSIS -\fBimage\fR \fIoption \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBimage\fR command is used to create, delete, and query images. -It can take several different forms, depending on the -\fIoption\fR argument. The legal forms are: -.TP -\fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? -Creates a new image and a command with the same name and returns its name. -\fItype\fR specifies the type of the image, which must be one of -the types currently defined (e.g., \fBbitmap\fR). -\fIname\fR specifies the name for the image; if it is omitted then -Tk picks a name of the form \fBimage\fIx\fR, where \fIx\fR is -an integer. -There may be any number of \fIoption\fR\-\fIvalue\fR pairs, -which provide configuration options for the new image. -The legal set of options is defined separately for each image -type; see below for details on the options for built-in image types. -If an image already exists by the given name then it is replaced -with the new image and any instances of that image will redisplay -with the new contents. -It is important to note that the image command will silently overwrite any -procedure that may currently be defined by the given name, so choose the -name wisely. It is recommended to use a separate namespace for image names -(e.g., \fB::img::logo\fR, \fB::img::large\fR). -.TP -\fBimage delete \fR?\fIname name\fR ...? -Deletes each of the named images and returns an empty string. -If there are instances of the images displayed in widgets, -the images will not actually be deleted until all of the instances -are released. -However, the association between the instances and the image -manager will be dropped. -Existing instances will retain their sizes but redisplay as -empty areas. -If a deleted image is recreated with another call to \fBimage create\fR, -the existing instances will use the new image. -.TP -\fBimage height \fIname\fR -Returns a decimal string giving the height of image \fIname\fR -in pixels. -.TP -\fBimage inuse \fIname\fR -Returns a boolean value indicating whether or not the image given by -\fIname\fR is in use by any widgets. -.TP -\fBimage names\fR -Returns a list containing the names of all existing images. -.TP -\fBimage type \fIname\fR -Returns the type of image \fIname\fR (the value of the \fItype\fR -argument to \fBimage create\fR when the image was created). -.TP -\fBimage types\fR -Returns a list whose elements are all of the valid image types -(i.e., all of the values that may be supplied for the \fItype\fR -argument to \fBimage create\fR). -.TP -\fBimage width \fIname\fR -Returns a decimal string giving the width of image \fIname\fR -in pixels. -.PP -Additional operations (e.g. writing the image to a file) may be -available as subcommands of the image instance command. See the manual -page for the particular image type for details. -.SH "BUILT-IN IMAGE TYPES" -.PP -The following image types are defined by Tk so they will be available -in any Tk application. -Individual applications or extensions may define additional types. -.TP -\fBbitmap\fR -Each pixel in the image displays a foreground color, a background -color, or nothing. -See the \fBbitmap\fR manual entry for more information. -.TP -\fBphoto\fR -Displays a variety of full-color images, using dithering to -approximate colors on displays with limited color capabilities. -See the \fBphoto\fR manual entry for more information. -.SH "SEE ALSO" -bitmap(n), options(n), photo(n) -.SH KEYWORDS -height, image, types of images, width -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/keysyms.n b/tk8.6/doc/keysyms.n deleted file mode 100644 index 512c1a6..0000000 --- a/tk8.6/doc/keysyms.n +++ /dev/null @@ -1,937 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -.TH keysyms n 8.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -keysyms \- keysyms recognized by Tk -.BE -.SH DESCRIPTION -.PP -Tk recognizes many keysyms when specifying key bindings (e.g., -.QW "\fBbind\fR \fB. <Key-\fR\fIkeysym\fR\fB>\fR" ). -The following list enumerates the -keysyms that will be recognized by Tk. Note that not all keysyms will -be valid on all platforms, and some keysyms are also available on -platforms that have a different native name for that key. -For example, on Unix systems, the presence -of a particular keysym is dependant on the configuration of the -keyboard modifier map. This list shows keysyms along with their -decimal and hexadecimal values. -.PP -.CS -space 32 0x0020 -exclam 33 0x0021 -quotedbl 34 0x0022 -numbersign 35 0x0023 -dollar 36 0x0024 -percent 37 0x0025 -ampersand 38 0x0026 -quoteright 39 0x0027 -parenleft 40 0x0028 -parenright 41 0x0029 -asterisk 42 0x002a -plus 43 0x002b -comma 44 0x002c -minus 45 0x002d -period 46 0x002e -slash 47 0x002f -0 48 0x0030 -1 49 0x0031 -2 50 0x0032 -3 51 0x0033 -4 52 0x0034 -5 53 0x0035 -6 54 0x0036 -7 55 0x0037 -8 56 0x0038 -9 57 0x0039 -colon 58 0x003a -semicolon 59 0x003b -less 60 0x003c -equal 61 0x003d -greater 62 0x003e -question 63 0x003f -at 64 0x0040 -A 65 0x0041 -B 66 0x0042 -C 67 0x0043 -D 68 0x0044 -E 69 0x0045 -F 70 0x0046 -G 71 0x0047 -H 72 0x0048 -I 73 0x0049 -J 74 0x004a -K 75 0x004b -L 76 0x004c -M 77 0x004d -N 78 0x004e -O 79 0x004f -P 80 0x0050 -Q 81 0x0051 -R 82 0x0052 -S 83 0x0053 -T 84 0x0054 -U 85 0x0055 -V 86 0x0056 -W 87 0x0057 -X 88 0x0058 -Y 89 0x0059 -Z 90 0x005a -bracketleft 91 0x005b -backslash 92 0x005c -bracketright 93 0x005d -asciicircum 94 0x005e -underscore 95 0x005f -quoteleft 96 0x0060 -a 97 0x0061 -b 98 0x0062 -c 99 0x0063 -d 100 0x0064 -e 101 0x0065 -f 102 0x0066 -g 103 0x0067 -h 104 0x0068 -i 105 0x0069 -j 106 0x006a -k 107 0x006b -l 108 0x006c -m 109 0x006d -n 110 0x006e -o 111 0x006f -p 112 0x0070 -q 113 0x0071 -r 114 0x0072 -s 115 0x0073 -t 116 0x0074 -u 117 0x0075 -v 118 0x0076 -w 119 0x0077 -x 120 0x0078 -y 121 0x0079 -z 122 0x007a -braceleft 123 0x007b -bar 124 0x007c -braceright 125 0x007d -asciitilde 126 0x007e -nobreakspace 160 0x00a0 -exclamdown 161 0x00a1 -cent 162 0x00a2 -sterling 163 0x00a3 -currency 164 0x00a4 -yen 165 0x00a5 -brokenbar 166 0x00a6 -section 167 0x00a7 -diaeresis 168 0x00a8 -copyright 169 0x00a9 -ordfeminine 170 0x00aa -guillemotleft 171 0x00ab -notsign 172 0x00ac -hyphen 173 0x00ad -registered 174 0x00ae -macron 175 0x00af -degree 176 0x00b0 -plusminus 177 0x00b1 -twosuperior 178 0x00b2 -threesuperior 179 0x00b3 -acute 180 0x00b4 -mu 181 0x00b5 -paragraph 182 0x00b6 -periodcentered 183 0x00b7 -cedilla 184 0x00b8 -onesuperior 185 0x00b9 -masculine 186 0x00ba -guillemotright 187 0x00bb -onequarter 188 0x00bc -onehalf 189 0x00bd -threequarters 190 0x00be -questiondown 191 0x00bf -Agrave 192 0x00c0 -Aacute 193 0x00c1 -Acircumflex 194 0x00c2 -Atilde 195 0x00c3 -Adiaeresis 196 0x00c4 -Aring 197 0x00c5 -AE 198 0x00c6 -Ccedilla 199 0x00c7 -Egrave 200 0x00c8 -Eacute 201 0x00c9 -Ecircumflex 202 0x00ca -Ediaeresis 203 0x00cb -Igrave 204 0x00cc -Iacute 205 0x00cd -Icircumflex 206 0x00ce -Idiaeresis 207 0x00cf -Eth 208 0x00d0 -Ntilde 209 0x00d1 -Ograve 210 0x00d2 -Oacute 211 0x00d3 -Ocircumflex 212 0x00d4 -Otilde 213 0x00d5 -Odiaeresis 214 0x00d6 -multiply 215 0x00d7 -Ooblique 216 0x00d8 -Ugrave 217 0x00d9 -Uacute 218 0x00da -Ucircumflex 219 0x00db -Udiaeresis 220 0x00dc -Yacute 221 0x00dd -Thorn 222 0x00de -ssharp 223 0x00df -agrave 224 0x00e0 -aacute 225 0x00e1 -acircumflex 226 0x00e2 -atilde 227 0x00e3 -adiaeresis 228 0x00e4 -aring 229 0x00e5 -ae 230 0x00e6 -ccedilla 231 0x00e7 -egrave 232 0x00e8 -eacute 233 0x00e9 -ecircumflex 234 0x00ea -ediaeresis 235 0x00eb -igrave 236 0x00ec -iacute 237 0x00ed -icircumflex 238 0x00ee -idiaeresis 239 0x00ef -eth 240 0x00f0 -ntilde 241 0x00f1 -ograve 242 0x00f2 -oacute 243 0x00f3 -ocircumflex 244 0x00f4 -otilde 245 0x00f5 -odiaeresis 246 0x00f6 -division 247 0x00f7 -oslash 248 0x00f8 -ugrave 249 0x00f9 -uacute 250 0x00fa -ucircumflex 251 0x00fb -udiaeresis 252 0x00fc -yacute 253 0x00fd -thorn 254 0x00fe -ydiaeresis 255 0x00ff -Aogonek 417 0x01a1 -breve 418 0x01a2 -Lstroke 419 0x01a3 -Lcaron 421 0x01a5 -Sacute 422 0x01a6 -Scaron 425 0x01a9 -Scedilla 426 0x01aa -Tcaron 427 0x01ab -Zacute 428 0x01ac -.CE -.CS -Zcaron 430 0x01ae -Zabovedot 431 0x01af -aogonek 433 0x01b1 -ogonek 434 0x01b2 -lstroke 435 0x01b3 -lcaron 437 0x01b5 -sacute 438 0x01b6 -caron 439 0x01b7 -scaron 441 0x01b9 -scedilla 442 0x01ba -tcaron 443 0x01bb -zacute 444 0x01bc -doubleacute 445 0x01bd -zcaron 446 0x01be -zabovedot 447 0x01bf -Racute 448 0x01c0 -Abreve 451 0x01c3 -Cacute 454 0x01c6 -Ccaron 456 0x01c8 -Eogonek 458 0x01ca -Ecaron 460 0x01cc -Dcaron 463 0x01cf -Nacute 465 0x01d1 -Ncaron 466 0x01d2 -Odoubleacute 469 0x01d5 -Rcaron 472 0x01d8 -Uring 473 0x01d9 -Udoubleacute 475 0x01db -Tcedilla 478 0x01de -racute 480 0x01e0 -abreve 483 0x01e3 -cacute 486 0x01e6 -ccaron 488 0x01e8 -eogonek 490 0x01ea -ecaron 492 0x01ec -dcaron 495 0x01ef -nacute 497 0x01f1 -ncaron 498 0x01f2 -odoubleacute 501 0x01f5 -rcaron 504 0x01f8 -uring 505 0x01f9 -udoubleacute 507 0x01fb -tcedilla 510 0x01fe -abovedot 511 0x01ff -Hstroke 673 0x02a1 -Hcircumflex 678 0x02a6 -Iabovedot 681 0x02a9 -Gbreve 683 0x02ab -Jcircumflex 684 0x02ac -hstroke 689 0x02b1 -hcircumflex 694 0x02b6 -idotless 697 0x02b9 -gbreve 699 0x02bb -jcircumflex 700 0x02bc -Cabovedot 709 0x02c5 -Ccircumflex 710 0x02c6 -Gabovedot 725 0x02d5 -Gcircumflex 728 0x02d8 -Ubreve 733 0x02dd -Scircumflex 734 0x02de -cabovedot 741 0x02e5 -ccircumflex 742 0x02e6 -gabovedot 757 0x02f5 -gcircumflex 760 0x02f8 -ubreve 765 0x02fd -scircumflex 766 0x02fe -kappa 930 0x03a2 -Rcedilla 931 0x03a3 -Itilde 933 0x03a5 -Lcedilla 934 0x03a6 -Emacron 938 0x03aa -Gcedilla 939 0x03ab -Tslash 940 0x03ac -rcedilla 947 0x03b3 -itilde 949 0x03b5 -lcedilla 950 0x03b6 -emacron 954 0x03ba -gacute 955 0x03bb -tslash 956 0x03bc -ENG 957 0x03bd -eng 959 0x03bf -Amacron 960 0x03c0 -Iogonek 967 0x03c7 -Eabovedot 972 0x03cc -Imacron 975 0x03cf -Ncedilla 977 0x03d1 -Omacron 978 0x03d2 -Kcedilla 979 0x03d3 -Uogonek 985 0x03d9 -Utilde 989 0x03dd -Umacron 990 0x03de -amacron 992 0x03e0 -iogonek 999 0x03e7 -eabovedot 1004 0x03ec -imacron 1007 0x03ef -ncedilla 1009 0x03f1 -omacron 1010 0x03f2 -kcedilla 1011 0x03f3 -uogonek 1017 0x03f9 -utilde 1021 0x03fd -umacron 1022 0x03fe -overline 1150 0x047e -kana_fullstop 1185 0x04a1 -kana_openingbracket 1186 0x04a2 -kana_closingbracket 1187 0x04a3 -kana_comma 1188 0x04a4 -kana_middledot 1189 0x04a5 -kana_WO 1190 0x04a6 -kana_a 1191 0x04a7 -kana_i 1192 0x04a8 -kana_u 1193 0x04a9 -kana_e 1194 0x04aa -kana_o 1195 0x04ab -kana_ya 1196 0x04ac -kana_yu 1197 0x04ad -kana_yo 1198 0x04ae -kana_tu 1199 0x04af -prolongedsound 1200 0x04b0 -kana_A 1201 0x04b1 -kana_I 1202 0x04b2 -kana_U 1203 0x04b3 -kana_E 1204 0x04b4 -kana_O 1205 0x04b5 -kana_KA 1206 0x04b6 -kana_KI 1207 0x04b7 -kana_KU 1208 0x04b8 -kana_KE 1209 0x04b9 -kana_KO 1210 0x04ba -kana_SA 1211 0x04bb -kana_SHI 1212 0x04bc -kana_SU 1213 0x04bd -kana_SE 1214 0x04be -kana_SO 1215 0x04bf -kana_TA 1216 0x04c0 -kana_TI 1217 0x04c1 -kana_TU 1218 0x04c2 -kana_TE 1219 0x04c3 -kana_TO 1220 0x04c4 -kana_NA 1221 0x04c5 -kana_NI 1222 0x04c6 -kana_NU 1223 0x04c7 -kana_NE 1224 0x04c8 -kana_NO 1225 0x04c9 -kana_HA 1226 0x04ca -kana_HI 1227 0x04cb -kana_HU 1228 0x04cc -kana_HE 1229 0x04cd -kana_HO 1230 0x04ce -kana_MA 1231 0x04cf -kana_MI 1232 0x04d0 -kana_MU 1233 0x04d1 -kana_ME 1234 0x04d2 -kana_MO 1235 0x04d3 -kana_YA 1236 0x04d4 -kana_YU 1237 0x04d5 -kana_YO 1238 0x04d6 -kana_RA 1239 0x04d7 -kana_RI 1240 0x04d8 -kana_RU 1241 0x04d9 -kana_RE 1242 0x04da -kana_RO 1243 0x04db -kana_WA 1244 0x04dc -kana_N 1245 0x04dd -voicedsound 1246 0x04de -semivoicedsound 1247 0x04df -Arabic_comma 1452 0x05ac -Arabic_semicolon 1467 0x05bb -Arabic_question_mark 1471 0x05bf -Arabic_hamza 1473 0x05c1 -Arabic_maddaonalef 1474 0x05c2 -Arabic_hamzaonalef 1475 0x05c3 -Arabic_hamzaonwaw 1476 0x05c4 -Arabic_hamzaunderalef 1477 0x05c5 -Arabic_hamzaonyeh 1478 0x05c6 -Arabic_alef 1479 0x05c7 -Arabic_beh 1480 0x05c8 -Arabic_tehmarbuta 1481 0x05c9 -Arabic_teh 1482 0x05ca -Arabic_theh 1483 0x05cb -Arabic_jeem 1484 0x05cc -Arabic_hah 1485 0x05cd -Arabic_khah 1486 0x05ce -Arabic_dal 1487 0x05cf -Arabic_thal 1488 0x05d0 -Arabic_ra 1489 0x05d1 -Arabic_zain 1490 0x05d2 -Arabic_seen 1491 0x05d3 -Arabic_sheen 1492 0x05d4 -Arabic_sad 1493 0x05d5 -Arabic_dad 1494 0x05d6 -Arabic_tah 1495 0x05d7 -Arabic_zah 1496 0x05d8 -Arabic_ain 1497 0x05d9 -Arabic_ghain 1498 0x05da -Arabic_tatweel 1504 0x05e0 -Arabic_feh 1505 0x05e1 -Arabic_qaf 1506 0x05e2 -Arabic_kaf 1507 0x05e3 -Arabic_lam 1508 0x05e4 -Arabic_meem 1509 0x05e5 -.CE -.CS -Arabic_noon 1510 0x05e6 -Arabic_heh 1511 0x05e7 -Arabic_waw 1512 0x05e8 -Arabic_alefmaksura 1513 0x05e9 -Arabic_yeh 1514 0x05ea -Arabic_fathatan 1515 0x05eb -Arabic_dammatan 1516 0x05ec -Arabic_kasratan 1517 0x05ed -Arabic_fatha 1518 0x05ee -Arabic_damma 1519 0x05ef -Arabic_kasra 1520 0x05f0 -Arabic_shadda 1521 0x05f1 -Arabic_sukun 1522 0x05f2 -Serbian_dje 1697 0x06a1 -Macedonia_gje 1698 0x06a2 -Cyrillic_io 1699 0x06a3 -Ukranian_je 1700 0x06a4 -Macedonia_dse 1701 0x06a5 -Ukranian_i 1702 0x06a6 -Ukranian_yi 1703 0x06a7 -Serbian_je 1704 0x06a8 -Serbian_lje 1705 0x06a9 -Serbian_nje 1706 0x06aa -Serbian_tshe 1707 0x06ab -Macedonia_kje 1708 0x06ac -Byelorussian_shortu 1710 0x06ae -Serbian_dze 1711 0x06af -numerosign 1712 0x06b0 -Serbian_DJE 1713 0x06b1 -Macedonia_GJE 1714 0x06b2 -Cyrillic_IO 1715 0x06b3 -Ukranian_JE 1716 0x06b4 -Macedonia_DSE 1717 0x06b5 -Ukranian_I 1718 0x06b6 -Ukranian_YI 1719 0x06b7 -Serbian_JE 1720 0x06b8 -Serbian_LJE 1721 0x06b9 -Serbian_NJE 1722 0x06ba -Serbian_TSHE 1723 0x06bb -Macedonia_KJE 1724 0x06bc -Byelorussian_SHORTU 1726 0x06be -Serbian_DZE 1727 0x06bf -Cyrillic_yu 1728 0x06c0 -Cyrillic_a 1729 0x06c1 -Cyrillic_be 1730 0x06c2 -Cyrillic_tse 1731 0x06c3 -Cyrillic_de 1732 0x06c4 -Cyrillic_ie 1733 0x06c5 -Cyrillic_ef 1734 0x06c6 -Cyrillic_ghe 1735 0x06c7 -Cyrillic_ha 1736 0x06c8 -Cyrillic_i 1737 0x06c9 -Cyrillic_shorti 1738 0x06ca -Cyrillic_ka 1739 0x06cb -Cyrillic_el 1740 0x06cc -Cyrillic_em 1741 0x06cd -Cyrillic_en 1742 0x06ce -Cyrillic_o 1743 0x06cf -Cyrillic_pe 1744 0x06d0 -Cyrillic_ya 1745 0x06d1 -Cyrillic_er 1746 0x06d2 -Cyrillic_es 1747 0x06d3 -Cyrillic_te 1748 0x06d4 -Cyrillic_u 1749 0x06d5 -Cyrillic_zhe 1750 0x06d6 -Cyrillic_ve 1751 0x06d7 -Cyrillic_softsign 1752 0x06d8 -Cyrillic_yeru 1753 0x06d9 -Cyrillic_ze 1754 0x06da -Cyrillic_sha 1755 0x06db -Cyrillic_e 1756 0x06dc -Cyrillic_shcha 1757 0x06dd -Cyrillic_che 1758 0x06de -Cyrillic_hardsign 1759 0x06df -Cyrillic_YU 1760 0x06e0 -Cyrillic_A 1761 0x06e1 -Cyrillic_BE 1762 0x06e2 -Cyrillic_TSE 1763 0x06e3 -Cyrillic_DE 1764 0x06e4 -Cyrillic_IE 1765 0x06e5 -Cyrillic_EF 1766 0x06e6 -Cyrillic_GHE 1767 0x06e7 -Cyrillic_HA 1768 0x06e8 -Cyrillic_I 1769 0x06e9 -Cyrillic_SHORTI 1770 0x06ea -Cyrillic_KA 1771 0x06eb -Cyrillic_EL 1772 0x06ec -Cyrillic_EM 1773 0x06ed -Cyrillic_EN 1774 0x06ee -Cyrillic_O 1775 0x06ef -Cyrillic_PE 1776 0x06f0 -Cyrillic_YA 1777 0x06f1 -Cyrillic_ER 1778 0x06f2 -Cyrillic_ES 1779 0x06f3 -Cyrillic_TE 1780 0x06f4 -Cyrillic_U 1781 0x06f5 -Cyrillic_ZHE 1782 0x06f6 -Cyrillic_VE 1783 0x06f7 -Cyrillic_SOFTSIGN 1784 0x06f8 -Cyrillic_YERU 1785 0x06f9 -Cyrillic_ZE 1786 0x06fa -Cyrillic_SHA 1787 0x06fb -Cyrillic_E 1788 0x06fc -Cyrillic_SHCHA 1789 0x06fd -Cyrillic_CHE 1790 0x06fe -Cyrillic_HARDSIGN 1791 0x06ff -Greek_ALPHAaccent 1953 0x07a1 -Greek_EPSILONaccent 1954 0x07a2 -Greek_ETAaccent 1955 0x07a3 -Greek_IOTAaccent 1956 0x07a4 -Greek_IOTAdiaeresis 1957 0x07a5 -Greek_IOTAaccentdiaeresis 1958 0x07a6 -Greek_OMICRONaccent 1959 0x07a7 -Greek_UPSILONaccent 1960 0x07a8 -Greek_UPSILONdieresis 1961 0x07a9 -Greek_UPSILONaccentdieresis 1962 0x07aa -Greek_OMEGAaccent 1963 0x07ab -Greek_alphaaccent 1969 0x07b1 -Greek_epsilonaccent 1970 0x07b2 -Greek_etaaccent 1971 0x07b3 -Greek_iotaaccent 1972 0x07b4 -Greek_iotadieresis 1973 0x07b5 -Greek_iotaaccentdieresis 1974 0x07b6 -Greek_omicronaccent 1975 0x07b7 -Greek_upsilonaccent 1976 0x07b8 -Greek_upsilondieresis 1977 0x07b9 -Greek_upsilonaccentdieresis 1978 0x07ba -Greek_omegaaccent 1979 0x07bb -Greek_ALPHA 1985 0x07c1 -Greek_BETA 1986 0x07c2 -Greek_GAMMA 1987 0x07c3 -Greek_DELTA 1988 0x07c4 -Greek_EPSILON 1989 0x07c5 -Greek_ZETA 1990 0x07c6 -Greek_ETA 1991 0x07c7 -Greek_THETA 1992 0x07c8 -Greek_IOTA 1993 0x07c9 -Greek_KAPPA 1994 0x07ca -Greek_LAMBDA 1995 0x07cb -Greek_MU 1996 0x07cc -Greek_NU 1997 0x07cd -Greek_XI 1998 0x07ce -Greek_OMICRON 1999 0x07cf -Greek_PI 2000 0x07d0 -Greek_RHO 2001 0x07d1 -Greek_SIGMA 2002 0x07d2 -Greek_TAU 2004 0x07d4 -Greek_UPSILON 2005 0x07d5 -Greek_PHI 2006 0x07d6 -Greek_CHI 2007 0x07d7 -Greek_PSI 2008 0x07d8 -Greek_OMEGA 2009 0x07d9 -Greek_alpha 2017 0x07e1 -Greek_beta 2018 0x07e2 -Greek_gamma 2019 0x07e3 -Greek_delta 2020 0x07e4 -Greek_epsilon 2021 0x07e5 -Greek_zeta 2022 0x07e6 -Greek_eta 2023 0x07e7 -Greek_theta 2024 0x07e8 -Greek_iota 2025 0x07e9 -Greek_kappa 2026 0x07ea -Greek_lambda 2027 0x07eb -Greek_mu 2028 0x07ec -Greek_nu 2029 0x07ed -Greek_xi 2030 0x07ee -Greek_omicron 2031 0x07ef -Greek_pi 2032 0x07f0 -Greek_rho 2033 0x07f1 -Greek_sigma 2034 0x07f2 -Greek_finalsmallsigma 2035 0x07f3 -Greek_tau 2036 0x07f4 -Greek_upsilon 2037 0x07f5 -Greek_phi 2038 0x07f6 -Greek_chi 2039 0x07f7 -Greek_psi 2040 0x07f8 -Greek_omega 2041 0x07f9 -leftradical 2209 0x08a1 -topleftradical 2210 0x08a2 -horizconnector 2211 0x08a3 -topintegral 2212 0x08a4 -botintegral 2213 0x08a5 -vertconnector 2214 0x08a6 -topleftsqbracket 2215 0x08a7 -botleftsqbracket 2216 0x08a8 -toprightsqbracket 2217 0x08a9 -botrightsqbracket 2218 0x08aa -topleftparens 2219 0x08ab -botleftparens 2220 0x08ac -toprightparens 2221 0x08ad -botrightparens 2222 0x08ae -leftmiddlecurlybrace 2223 0x08af -rightmiddlecurlybrace 2224 0x08b0 -topleftsummation 2225 0x08b1 -botleftsummation 2226 0x08b2 -topvertsummationconnector 2227 0x08b3 -botvertsummationconnector 2228 0x08b4 -toprightsummation 2229 0x08b5 -botrightsummation 2230 0x08b6 -rightmiddlesummation 2231 0x08b7 -.CE -.CS -lessthanequal 2236 0x08bc -notequal 2237 0x08bd -greaterthanequal 2238 0x08be -integral 2239 0x08bf -therefore 2240 0x08c0 -variation 2241 0x08c1 -infinity 2242 0x08c2 -nabla 2245 0x08c5 -approximate 2248 0x08c8 -similarequal 2249 0x08c9 -ifonlyif 2253 0x08cd -implies 2254 0x08ce -identical 2255 0x08cf -radical 2262 0x08d6 -includedin 2266 0x08da -includes 2267 0x08db -intersection 2268 0x08dc -union 2269 0x08dd -logicaland 2270 0x08de -logicalor 2271 0x08df -partialderivative 2287 0x08ef -function 2294 0x08f6 -leftarrow 2299 0x08fb -uparrow 2300 0x08fc -rightarrow 2301 0x08fd -downarrow 2302 0x08fe -blank 2527 0x09df -soliddiamond 2528 0x09e0 -checkerboard 2529 0x09e1 -ht 2530 0x09e2 -ff 2531 0x09e3 -cr 2532 0x09e4 -lf 2533 0x09e5 -nl 2536 0x09e8 -vt 2537 0x09e9 -lowrightcorner 2538 0x09ea -uprightcorner 2539 0x09eb -upleftcorner 2540 0x09ec -lowleftcorner 2541 0x09ed -crossinglines 2542 0x09ee -horizlinescan1 2543 0x09ef -horizlinescan3 2544 0x09f0 -horizlinescan5 2545 0x09f1 -horizlinescan7 2546 0x09f2 -horizlinescan9 2547 0x09f3 -leftt 2548 0x09f4 -rightt 2549 0x09f5 -bott 2550 0x09f6 -topt 2551 0x09f7 -vertbar 2552 0x09f8 -emspace 2721 0x0aa1 -enspace 2722 0x0aa2 -em3space 2723 0x0aa3 -em4space 2724 0x0aa4 -digitspace 2725 0x0aa5 -punctspace 2726 0x0aa6 -thinspace 2727 0x0aa7 -hairspace 2728 0x0aa8 -emdash 2729 0x0aa9 -endash 2730 0x0aaa -signifblank 2732 0x0aac -ellipsis 2734 0x0aae -doubbaselinedot 2735 0x0aaf -onethird 2736 0x0ab0 -twothirds 2737 0x0ab1 -onefifth 2738 0x0ab2 -twofifths 2739 0x0ab3 -threefifths 2740 0x0ab4 -fourfifths 2741 0x0ab5 -onesixth 2742 0x0ab6 -fivesixths 2743 0x0ab7 -careof 2744 0x0ab8 -figdash 2747 0x0abb -leftanglebracket 2748 0x0abc -decimalpoint 2749 0x0abd -rightanglebracket 2750 0x0abe -marker 2751 0x0abf -oneeighth 2755 0x0ac3 -threeeighths 2756 0x0ac4 -fiveeighths 2757 0x0ac5 -seveneighths 2758 0x0ac6 -trademark 2761 0x0ac9 -signaturemark 2762 0x0aca -trademarkincircle 2763 0x0acb -leftopentriangle 2764 0x0acc -rightopentriangle 2765 0x0acd -emopencircle 2766 0x0ace -emopenrectangle 2767 0x0acf -leftsinglequotemark 2768 0x0ad0 -rightsinglequotemark 2769 0x0ad1 -leftdoublequotemark 2770 0x0ad2 -rightdoublequotemark 2771 0x0ad3 -prescription 2772 0x0ad4 -minutes 2774 0x0ad6 -seconds 2775 0x0ad7 -latincross 2777 0x0ad9 -hexagram 2778 0x0ada -filledrectbullet 2779 0x0adb -filledlefttribullet 2780 0x0adc -filledrighttribullet 2781 0x0add -emfilledcircle 2782 0x0ade -emfilledrect 2783 0x0adf -enopencircbullet 2784 0x0ae0 -enopensquarebullet 2785 0x0ae1 -openrectbullet 2786 0x0ae2 -opentribulletup 2787 0x0ae3 -opentribulletdown 2788 0x0ae4 -openstar 2789 0x0ae5 -enfilledcircbullet 2790 0x0ae6 -enfilledsqbullet 2791 0x0ae7 -filledtribulletup 2792 0x0ae8 -filledtribulletdown 2793 0x0ae9 -leftpointer 2794 0x0aea -rightpointer 2795 0x0aeb -club 2796 0x0aec -diamond 2797 0x0aed -heart 2798 0x0aee -maltesecross 2800 0x0af0 -dagger 2801 0x0af1 -doubledagger 2802 0x0af2 -checkmark 2803 0x0af3 -ballotcross 2804 0x0af4 -musicalsharp 2805 0x0af5 -musicalflat 2806 0x0af6 -malesymbol 2807 0x0af7 -femalesymbol 2808 0x0af8 -telephone 2809 0x0af9 -telephonerecorder 2810 0x0afa -phonographcopyright 2811 0x0afb -caret 2812 0x0afc -singlelowquotemark 2813 0x0afd -doublelowquotemark 2814 0x0afe -cursor 2815 0x0aff -leftcaret 2979 0x0ba3 -rightcaret 2982 0x0ba6 -downcaret 2984 0x0ba8 -upcaret 2985 0x0ba9 -overbar 3008 0x0bc0 -downtack 3010 0x0bc2 -upshoe 3011 0x0bc3 -downstile 3012 0x0bc4 -underbar 3014 0x0bc6 -jot 3018 0x0bca -quad 3020 0x0bcc -uptack 3022 0x0bce -circle 3023 0x0bcf -upstile 3027 0x0bd3 -downshoe 3030 0x0bd6 -rightshoe 3032 0x0bd8 -leftshoe 3034 0x0bda -lefttack 3036 0x0bdc -righttack 3068 0x0bfc -hebrew_aleph 3296 0x0ce0 -hebrew_beth 3297 0x0ce1 -hebrew_gimmel 3298 0x0ce2 -hebrew_daleth 3299 0x0ce3 -hebrew_he 3300 0x0ce4 -hebrew_waw 3301 0x0ce5 -hebrew_zayin 3302 0x0ce6 -hebrew_het 3303 0x0ce7 -hebrew_teth 3304 0x0ce8 -hebrew_yod 3305 0x0ce9 -hebrew_finalkaph 3306 0x0cea -hebrew_kaph 3307 0x0ceb -hebrew_lamed 3308 0x0cec -hebrew_finalmem 3309 0x0ced -hebrew_mem 3310 0x0cee -hebrew_finalnun 3311 0x0cef -hebrew_nun 3312 0x0cf0 -hebrew_samekh 3313 0x0cf1 -hebrew_ayin 3314 0x0cf2 -hebrew_finalpe 3315 0x0cf3 -hebrew_pe 3316 0x0cf4 -hebrew_finalzadi 3317 0x0cf5 -hebrew_zadi 3318 0x0cf6 -hebrew_kuf 3319 0x0cf7 -hebrew_resh 3320 0x0cf8 -hebrew_shin 3321 0x0cf9 -hebrew_taf 3322 0x0cfa -BackSpace 65288 0xff08 -Tab 65289 0xff09 -Linefeed 65290 0xff0a -Clear 65291 0xff0b -Return 65293 0xff0d -Pause 65299 0xff13 -Scroll_Lock 65300 0xff14 -Sys_Req 65301 0xff15 -Escape 65307 0xff1b -Multi_key 65312 0xff20 -Kanji 65313 0xff21 -Home 65360 0xff50 -Left 65361 0xff51 -Up 65362 0xff52 -Right 65363 0xff53 -Down 65364 0xff54 -Prior 65365 0xff55 -Next 65366 0xff56 -End 65367 0xff57 -Begin 65368 0xff58 -Win_L 65371 0xff5b -Win_R 65372 0xff5c -.CE -.CS -App 65373 0xff5d -Select 65376 0xff60 -Print 65377 0xff61 -Execute 65378 0xff62 -Insert 65379 0xff63 -Undo 65381 0xff65 -Redo 65382 0xff66 -Menu 65383 0xff67 -Find 65384 0xff68 -Cancel 65385 0xff69 -Help 65386 0xff6a -Break 65387 0xff6b -Hebrew_switch 65406 0xff7e -Num_Lock 65407 0xff7f -KP_Space 65408 0xff80 -KP_Tab 65417 0xff89 -KP_Enter 65421 0xff8d -KP_F1 65425 0xff91 -KP_F2 65426 0xff92 -KP_F3 65427 0xff93 -KP_F4 65428 0xff94 -KP_Multiply 65450 0xffaa -KP_Add 65451 0xffab -KP_Separator 65452 0xffac -KP_Subtract 65453 0xffad -KP_Decimal 65454 0xffae -KP_Divide 65455 0xffaf -KP_0 65456 0xffb0 -KP_1 65457 0xffb1 -KP_2 65458 0xffb2 -KP_3 65459 0xffb3 -KP_4 65460 0xffb4 -KP_5 65461 0xffb5 -KP_6 65462 0xffb6 -KP_7 65463 0xffb7 -KP_8 65464 0xffb8 -KP_9 65465 0xffb9 -KP_Equal 65469 0xffbd -F1 65470 0xffbe -F2 65471 0xffbf -F3 65472 0xffc0 -F4 65473 0xffc1 -F5 65474 0xffc2 -F6 65475 0xffc3 -F7 65476 0xffc4 -F8 65477 0xffc5 -F9 65478 0xffc6 -F10 65479 0xffc7 -L1 65480 0xffc8 -L2 65481 0xffc9 -L3 65482 0xffca -L4 65483 0xffcb -L5 65484 0xffcc -L6 65485 0xffcd -L7 65486 0xffce -L8 65487 0xffcf -L9 65488 0xffd0 -L10 65489 0xffd1 -R1 65490 0xffd2 -R2 65491 0xffd3 -R3 65492 0xffd4 -R4 65493 0xffd5 -R5 65494 0xffd6 -R6 65495 0xffd7 -R7 65496 0xffd8 -R8 65497 0xffd9 -R9 65498 0xffda -R10 65499 0xffdb -R11 65500 0xffdc -R12 65501 0xffdd -F33 65502 0xffde -R14 65503 0xffdf -R15 65504 0xffe0 -Shift_L 65505 0xffe1 -Shift_R 65506 0xffe2 -Control_L 65507 0xffe3 -Control_R 65508 0xffe4 -Caps_Lock 65509 0xffe5 -Shift_Lock 65510 0xffe6 -Meta_L 65511 0xffe7 -Meta_R 65512 0xffe8 -Alt_L 65513 0xffe9 -Alt_R 65514 0xffea -Super_L 65515 0xffeb -Super_R 65516 0xffec -Hyper_L 65517 0xffed -Hyper_R 65518 0xffee -Delete 65535 0xffff -XF86AudioLowerVolume 269025041 0x1008FF11 -XF86AudioMute 269025042 0x1008FF12 -XF86AudioRaiseVolume 269025043 0x1008FF13 -XF86AudioPlay 269025044 0x1008FF14 -XF86AudioStop 269025045 0x1008FF15 -XF86AudioPrev 269025046 0x1008FF16 -XF86AudioNext 269025047 0x1008FF17 -.CE -.SH "SEE ALSO" -bind(n), event(n) -.SH KEYWORDS -bind, binding, event, keysym -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/label.n b/tk8.6/doc/label.n deleted file mode 100644 index f2ba88c..0000000 --- a/tk8.6/doc/label.n +++ /dev/null @@ -1,130 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH label n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -label \- Create and manipulate 'label' non-interactive text or image widgets -.SH SYNOPSIS -\fBlabel\fR \fIpathName \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 \-height height Height -Specifies a desired height for the label. -If an image or bitmap is being displayed in the label 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 label's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-state state State -Specifies one of three states for the label: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the button is displayed using the -\fB\-foreground\fR and \fB\-background\fR options. In active state -the label is displayed using the \fB\-activeforeground\fR and -\fB\-activebackground\fR options. In the disabled state the -\fB\-disabledforeground\fR and \fB\-background\fR options determine how -the button is displayed. -.OP \-width width Width -Specifies a desired width for the label. -If an image or bitmap is being displayed in the label 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 label's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE -.SH DESCRIPTION -.PP -The \fBlabel\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a label widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the label such as its colors, font, -text, and initial relief. The \fBlabel\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 label 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 \fB\-wraplength\fR option) and -one of the characters may optionally be underlined using the -\fB\-underline\fR option. -The label can be manipulated in a few simple ways, such as -changing its relief or text, using the commands described below. -.SH "WIDGET COMMAND" -.PP -The \fBlabel\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 label 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 \fBlabel\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 \fBlabel\fR -command. -.SH BINDINGS -.PP -When a new label is created, it has no default event bindings: -labels are not intended to be interactive. -.SH EXAMPLE -.PP -.CS -# Make the widgets -\fBlabel\fR .t \-text "This widget is at the top" \-bg red -\fBlabel\fR .b \-text "This widget is at the bottom" \-bg green -\fBlabel\fR .l \-text "Left\enHand\enSide" -\fBlabel\fR .r \-text "Right\enHand\enSide" -text .mid -\&.mid insert end "This layout is like Java's BorderLayout" -# Lay them out -pack .t \-side top \-fill x -pack .b \-side bottom \-fill x -pack .l \-side left \-fill y -pack .r \-side right \-fill y -pack .mid \-expand 1 \-fill both -.CE -.SH "SEE ALSO" -labelframe(n), button(n), ttk::label(n) -.SH KEYWORDS -label, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/labelframe.n b/tk8.6/doc/labelframe.n deleted file mode 100644 index 857208e..0000000 --- a/tk8.6/doc/labelframe.n +++ /dev/null @@ -1,175 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH labelframe n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -labelframe \- Create and manipulate 'labelframe' labelled container widgets -.SH SYNOPSIS -\fBlabelframe\fR \fIpathName\fR ?\fIoptions\fR? -.SO -\-borderwidth \-highlightbackground \-pady -\-cursor \-highlightcolor \-relief -\-font \-highlightthickness \-takefocus -\-foreground \-padx \-text -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fB\-background\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fB\-class\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fB\-colormap\fR option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.OP \-labelanchor labelAnchor LabelAnchor -Specifies where to place the label. A label is only displayed if the -\fB\-text\fR option is not the empty string. -Valid values for this option are (listing them clockwise) -\fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, -\fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. -The default value is \fBnw\fR. -.OP \-labelwidget labelWidget LabelWidget -Specifies a widget to use as label. This overrides any \fB\-text\fR -option. The widget must exist before being used as \fB\-labelwidget\fR -and if it is not a descendant of this window, it will be raised -above it in the stacking order. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the same -visual as its parent. -The \fB\-visual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.BE -.SH DESCRIPTION -.PP -The \fBlabelframe\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a labelframe widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the labelframe such as its background color -and relief. The \fBlabelframe\fR command returns the -path name of the new window. -.PP -A labelframe is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. It has the features -of a \fBframe\fR plus the ability to display a label. -.SH "WIDGET COMMAND" -.PP -The \fBlabelframe\fR command creates a new Tcl command whose -name is the same as the path name of the labelframe's window. 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 -\fIPathName\fR is the name of the command, which is the same as -the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for frame 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 \fBlabelframe\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value 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 \fBlabelframe\fR -command. -.SH BINDINGS -.PP -When a new labelframe is created, it has no default event bindings: -labelframes are not intended to be interactive. -.SH EXAMPLE -.PP -This shows how to build part of a GUI for a hamburger vendor. The -\fBlabelframe\fR widgets are used to organize the available choices by -the kinds of things that the choices are being made over. -.PP -.CS -grid [\fBlabelframe\fR .burger \-text "Burger"] \e - [\fBlabelframe\fR .bun \-text "Bun"] \-sticky news -grid [\fBlabelframe\fR .cheese \-text "Cheese Option"] \e - [\fBlabelframe\fR .pickle \-text "Pickle Option"] \-sticky news -foreach {type name val} { - burger Beef beef - burger Lamb lamb - burger Vegetarian beans - - bun Plain white - bun Sesame seeds - bun Wholemeal brown - - cheese None none - cheese Cheddar cheddar - cheese Edam edam - cheese Brie brie - cheese Gruy\eu00e8re gruyere - cheese "Monterey Jack" jack - - pickle None none - pickle Gherkins gherkins - pickle Onions onion - pickle Chili chili -} { - set w [radiobutton .$type.$val \-text $name \-anchor w \e - \-variable $type \-value $val] - pack $w \-side top \-fill x -} -set burger beef -set bun white -set cheese none -set pickle none -.CE -.SH "SEE ALSO" -frame(n), label(n), ttk::labelframe(n) -.SH KEYWORDS -labelframe, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/license.terms b/tk8.6/doc/license.terms deleted file mode 100644 index 0126435..0000000 --- a/tk8.6/doc/license.terms +++ /dev/null @@ -1,40 +0,0 @@ -This software is copyrighted by the Regents of the University of -California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState -Corporation, Apple Inc. and other parties. The following terms apply to -all files associated with the software unless explicitly disclaimed in -individual files. - -The authors hereby grant permission to use, copy, modify, distribute, -and license this software and its documentation for any purpose, provided -that existing copyright notices are retained in all copies and that this -notice is included verbatim in any distributions. No written agreement, -license, or royalty fee is required for any of the authorized uses. -Modifications to this software may be copyrighted by their authors -and need not follow the licensing terms described here, provided that -the new terms are clearly indicated on the first page of each file where -they apply. - -IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY -FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY -DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - -THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE -IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE -NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR -MODIFICATIONS. - -GOVERNMENT USE: If you are acquiring this software on behalf of the -U.S. government, the Government shall have only "Restricted Rights" -in the software and related documentation as defined in the Federal -Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you -are acquiring the software on behalf of the Department of Defense, the -software shall be classified as "Commercial Computer Software" and the -Government shall have only "Restricted Rights" as defined in Clause -252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the -authors grant the U.S. Government and others acting in its behalf -permission to use and distribute the software in accordance with the -terms specified in this license. diff --git a/tk8.6/doc/listbox.n b/tk8.6/doc/listbox.n deleted file mode 100644 index 66b75b9..0000000 --- a/tk8.6/doc/listbox.n +++ /dev/null @@ -1,582 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH listbox n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -listbox \- Create and manipulate 'listbox' item list widgets -.SH SYNOPSIS -\fBlistbox\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-borderwidth \-cursor -\-disabledforeground \-exportselection \-font -\-foreground \-highlightbackground \-highlightcolor -\-highlightthickness \-justify \-relief -\-selectbackground \-selectborderwidth \-selectforeground -\-setgrid \-takefocus \-xscrollcommand -\-yscrollcommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-activestyle activeStyle ActiveStyle -Specifies the style in which to draw the active element. This must be -one of \fBdotbox\fR (show a focus ring around the active element), -\fBnone\fR (no special indication of active element) or -\fBunderline\fR (underline the active element). -The default is \fBunderline\fR on Windows, and \fBdotbox\fR elsewhere. -.OP \-height height Height -Specifies the desired height for the window, in lines. -If zero or less, then the desired height for the window is made just -large enough to hold all the elements in the listbox. -.OP \-listvariable listVariable Variable -Specifies the name of a global variable. The value of the variable is a list to -be displayed inside the widget; if the variable value changes then the -widget will automatically update itself to reflect the new value. Attempts -to assign a variable with an invalid list value to \fB\-listvariable\fR -will cause an error. Attempts to unset a variable in use as a -\fB\-listvariable\fR will fail but will not generate an error. -.OP \-selectmode selectMode SelectMode -Specifies one of several styles for manipulating the selection. -The value of the option may be arbitrary, but the default bindings -expect it to be either \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, -or \fBextended\fR; the default value is \fBbrowse\fR. -.OP \-state state State -Specifies one of two states for the listbox: \fBnormal\fR or \fBdisabled\fR. -If the listbox is disabled then items may not be inserted or deleted, -items are drawn in the \fB\-disabledforeground\fR color, and selection -cannot be modified and is not shown (though selection information is retained). -.OP \-width width Width -Specifies the desired width for the window in characters. -If the font does not have a uniform width then the width of the character -.QW 0 -is used in translating from character units to screen units. -If zero or less, then the desired width for the window is made just -large enough to hold all the elements in the listbox. -.BE -.SH DESCRIPTION -.PP -The \fBlistbox\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a listbox widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the listbox such as its colors, font, -text, and relief. The \fBlistbox\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 listbox is a widget that displays a list of strings, one per line. -When first created, a new listbox has no elements. -Elements may be added or deleted using widget commands described -below. In addition, one or more elements may be selected as described -below. -If a listbox is exporting its selection (see \fB\-exportselection\fR -option), then it will observe the standard X11 protocols -for handling the selection. -Listbox selections are available as type \fBSTRING\fR; -the value of the selection will be the text of the selected elements, with -newlines separating the elements. -.PP -It is not necessary for all the elements to be -displayed in the listbox window at once; commands described below -may be used to change the view in the window. Listboxes allow -scrolling in both directions using the standard \fB\-xscrollcommand\fR -and \fB\-yscrollcommand\fR options. -They also support scanning, as described below. -.SH "INDICES" -.PP -Many of the widget commands for listboxes take one or more indices -as arguments. -An index specifies a particular element of the listbox, in any of -the following ways: -.TP 12 -\fInumber\fR -. -Specifies the element as a numerical index, where 0 corresponds -to the first element in the listbox. -.TP 12 -\fBactive\fR -. -Indicates the element that has the location cursor. This element -will be displayed as specified by \fB\-activestyle\fR when the listbox -has the keyboard focus, and it is specified with the \fBactivate\fR -widget command. -.TP 12 -\fBanchor\fR -. -Indicates the anchor point for the selection, which is set with the -\fBselection anchor\fR widget command. -.TP 12 -\fBend\fR -. -Indicates the end of the listbox. -For most commands this refers to the last element in the listbox, -but for a few commands such as \fBindex\fR and \fBinsert\fR -it refers to the element just after the last one. -.TP 12 -\fB@\fIx\fB,\fIy\fR -Indicates the element that covers the point in the listbox window -specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no -element covers that point, then the closest element to that -point is used. -.LP -In the widget command descriptions below, arguments named \fIindex\fR, -\fIfirst\fR, and \fIlast\fR always contain text indices in one of -the above forms. -.SH "WIDGET COMMAND" -.PP -The \fBlistbox\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 listbox widgets: -.TP -\fIpathName \fBactivate\fR \fIindex\fR -. -Sets the active element to the one indicated by \fIindex\fR. -If \fIindex\fR is outside the range of elements in the listbox -then the closest element is activated. -The active element is drawn as specified by \fB\-activestyle\fR when the -widget has the input focus, and its index may be retrieved with the -index \fBactive\fR. -.TP -\fIpathName \fBbbox\fR \fIindex\fR -. -Returns a list of four numbers describing the bounding box of -the text in the element given by \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the screen area covered by the text -(specified in pixels relative to the widget) and the last two -elements give the width and height of the area, in pixels. -If no part of the element given by \fIindex\fR is visible on the -screen, -or if \fIindex\fR refers to a non-existent element, -then the result is an empty string; if the element is -partially visible, the result gives the full area of the element, -including any parts that are not visible. -.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 \fBlistbox\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 \fBlistbox\fR -command. -.TP -\fIpathName \fBcurselection\fR -. -Returns a list containing the numerical indices of -all of the elements in the listbox that are currently selected. -If there are no elements selected in the listbox then an empty -string is returned. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -. -Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR -are indices specifying the first and last elements in the range -to delete. If \fIlast\fR is not specified it defaults to -\fIfirst\fR, i.e. a single element is deleted. -.TP -\fIpathName \fBget \fIfirst\fR ?\fIlast\fR? -. -If \fIlast\fR is omitted, returns the contents of the listbox -element indicated by \fIfirst\fR, -or an empty string if \fIfirst\fR refers to a non-existent element. -If \fIlast\fR is specified, the command returns a list whose elements -are all of the listbox elements between \fIfirst\fR and \fIlast\fR, -inclusive. -Both \fIfirst\fR and \fIlast\fR may have any of the standard -forms for indices. -.TP -\fIpathName \fBindex \fIindex\fR -. -Returns the integer index value that corresponds to \fIindex\fR. -If \fIindex\fR is \fBend\fR the return value is a count of the number -of elements in the listbox (not the index of the last element). -.TP -\fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? -. -Inserts zero or more new elements in the list just before the -element given by \fIindex\fR. If \fIindex\fR is specified as -\fBend\fR then the new elements are added to the end of the -list. Returns an empty string. -.TP -\fIpathName \fBitemcget \fIindex option\fR -. -Returns the current value of the item configuration option given -by \fIoption\fR. \fIOption\fR may have any of the values accepted -by the \fBitemconfigure\fR command. -.TP -\fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -. -Query or modify the configuration options of an item in the listbox. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the item (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. The following options -are currently supported for items: -.RS -.TP -\fB\-background \fIcolor\fR -. -\fIColor\fR specifies the background color to use when displaying the -item. It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-foreground \fIcolor\fR -. -\fIColor\fR specifies the foreground color to use when displaying the -item. It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-selectbackground \fIcolor\fR -. -\fIcolor\fR specifies the background color to use when displaying the -item while it is selected. It may have any of the forms accepted by -\fBTk_GetColor\fR. -.TP -\fB\-selectforeground \fIcolor\fR -. -\fIcolor\fR specifies the foreground color to use when displaying the -item while it is selected. It may have any of the forms accepted by -\fBTk_GetColor\fR. -.RE -.TP -\fIpathName \fBnearest \fIy\fR -. -Given a y-coordinate within the listbox window, this command returns -the index of the (visible) listbox element nearest to that y-coordinate. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -. -This command is used to implement scanning on listboxes. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -. -Records \fIx\fR and \fIy\fR and the current view in the listbox -window; used in conjunction with later \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget. It returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx y\fR. -. -This command computes the difference between its \fIx\fR and \fIy\fR -arguments and the \fIx\fR and \fIy\fR arguments to the last -\fBscan mark\fR command for the widget. -It then adjusts the view by 10 times the -difference in coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the list at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBsee \fIindex\fR -. -Adjust the view in the listbox so that the element given by \fIindex\fR -is visible. -If the element is already visible then the command has no effect; -if the element is near one edge of the window then the listbox -scrolls to bring the element into view at the edge; otherwise -the listbox scrolls to center the element. -.TP -\fIpathName \fBselection \fIoption arg\fR -. -This command is used to adjust the selection within a listbox. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection anchor \fIindex\fR -. -Sets the selection anchor to the element given by \fIindex\fR. -If \fIindex\fR refers to a non-existent element, then the closest -element is used. -The selection anchor is the end of the selection that is fixed -while dragging out a selection with the mouse. -The index \fBanchor\fR may be used to refer to the anchor -element. -.TP -\fIpathName \fBselection clear \fIfirst \fR?\fIlast\fR? -. -If any of the elements between \fIfirst\fR and \fIlast\fR -(inclusive) are selected, they are deselected. -The selection state is not changed for elements outside -this range. -.TP -\fIpathName \fBselection includes \fIindex\fR -. -Returns 1 if the element indicated by \fIindex\fR is currently -selected, 0 if it is not. -.TP -\fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? -. -Selects all of the elements in the range between -\fIfirst\fR and \fIlast\fR, inclusive, without affecting -the selection state of elements outside that range. -.RE -.TP -\fIpathName \fBsize\fR -. -Returns a decimal string indicating the total number of elements -in the listbox. -.TP -\fIpathName \fBxview \fR?\fIargs\fR -. -This command is used to query and change the horizontal position of the -information in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -. -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the listbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview \fIindex\fR -. -Adjusts the view in the window so that the character position given by -\fIindex\fR is displayed at the left edge of the window. -Character positions are defined by the width of the character \fB0\fR. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -. -Adjusts the view in the window so that \fIfraction\fR of the -total width of the listbox text is off-screen to the left. -\fIfraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -. -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR character units (the width of the \fB0\fR character) -on the display; if it is \fBpages\fR then the view adjusts by -\fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.TP -\fIpathName \fByview \fR?\fIargs\fR? -. -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the listbox element at the -top of the window, relative to the listbox as a whole (0.5 means -it is halfway through the listbox, for example). -The second element gives the position of the listbox element just after -the last one in the window, relative to the listbox as a whole. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. -.TP -\fIpathName \fByview \fIindex\fR -. -Adjusts the view in the window so that the element given by -\fIindex\fR is displayed at the top of the window. -.TP -\fIpathName \fByview moveto\fI fraction\fR -. -Adjusts the view in the window so that the element given by \fIfraction\fR -appears at the top of the window. -\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first -element in the listbox, 0.33 indicates the element one-third the -way through the listbox, and so on. -.TP -\fIpathName \fByview scroll \fInumber what\fR -. -This command adjusts the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR lines; if it is \fBpages\fR then -the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then earlier elements -become visible; if it is positive then later elements -become visible. -.RE -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for listboxes that give them -Motif-like behavior. Much of the behavior of a listbox is determined -by its \fB\-selectmode\fR option, which selects one of four ways -of dealing with the selection. -.PP -If the selection mode is \fBsingle\fR or \fBbrowse\fR, at most one -element can be selected in the listbox at once. -In both modes, clicking button 1 on an element selects -it and deselects any other selected item. -In \fBbrowse\fR mode it is also possible to drag the selection -with button 1. -On button 1, the listbox will also take focus if it has a \fBnormal\fR -state. -.PP -If the selection mode is \fBmultiple\fR or \fBextended\fR, -any number of elements may be selected at once, including discontiguous -ranges. In \fBmultiple\fR mode, clicking button 1 on an element -toggles its selection state without affecting any other elements. -In \fBextended\fR mode, pressing button 1 on an element selects -it, deselects everything else, and sets the anchor to the element -under the mouse; dragging the mouse with button 1 -down extends the selection to include all the elements between -the anchor and the element under the mouse, inclusive. -.PP -Most people will probably want to use \fBbrowse\fR mode for -single selections and \fBextended\fR mode for multiple selections; -the other modes appear to be useful only in special situations. -.PP -Any time the set of selected item(s) in the listbox is updated by the -user through the keyboard or mouse, the virtual event -\fB<<ListboxSelect>>\fR will be generated. This virtual event will not -be generated when adjusting the selection with the \fIpathName -\fBselection\fR command. It is easiest to bind to this event to be -made aware of any user changes to listbox selection. -.PP -In addition to the above behavior, the following additional behavior -is defined by the default bindings: -.IP [1] -In \fBextended\fR mode, the selected range can be adjusted by pressing -button 1 with the Shift key down: this modifies the selection to -consist of the elements between the anchor and the element under -the mouse, inclusive. -The un-anchored end of this new selection can also be dragged with -the button down. -.IP [2] -In \fBextended\fR mode, pressing button 1 with the Control key down -starts a toggle operation: the anchor is set to the element under -the mouse, and its selection state is reversed. The selection state -of other elements is not changed. -If the mouse is dragged with button 1 down, then the selection state -of all elements between the anchor and the element under the mouse -is set to match that of the anchor element; the selection state of -all other elements remains what it was before the toggle operation -began. -.IP [3] -If the mouse leaves the listbox window with button 1 down, the window -scrolls away from the mouse, making information visible that used -to be off-screen on the side of the mouse. -The scrolling continues until the mouse re-enters the window, the -button is released, or the end of the listbox is reached. -.IP [4] -Mouse button 2 may be used for scanning. -If it is pressed and dragged over the listbox, the contents of -the listbox drag at high speed in the direction the mouse moves. -.IP [5] -If the Up or Down key is pressed, the location cursor (active -element) moves up or down one element. -If the selection mode is \fBbrowse\fR or \fBextended\fR then the -new active element is also selected and all other elements are -deselected. -In \fBextended\fR mode the new active element becomes the -selection anchor. -.IP [6] -In \fBextended\fR mode, Shift-Up and Shift-Down move the location -cursor (active element) up or down one element and also extend -the selection to that element in a fashion similar to dragging -with mouse button 1. -.IP [7] -The Left and Right keys scroll the listbox view left and right -by the width of the character \fB0\fR. -Control-Left and Control-Right scroll the listbox view left and -right by the width of the window. -Control-Prior and Control-Next also scroll left and right by -the width of the window. -.IP [8] -The Prior and Next keys scroll the listbox view up and down -by one page (the height of the window). -.IP [9] -The Home and End keys scroll the listbox horizontally to -the left and right edges, respectively. -.IP [10] -Control-Home sets the location cursor to the first element in -the listbox, selects that element, and deselects everything else -in the listbox. -.IP [11] -Control-End sets the location cursor to the last element in -the listbox, selects that element, and deselects everything else -in the listbox. -.IP [12] -In \fBextended\fR mode, Control-Shift-Home extends the selection -to the first element in the listbox and Control-Shift-End extends -the selection to the last element. -.IP [13] -In \fBmultiple\fR mode, Control-Shift-Home moves the location cursor -to the first element in the listbox and Control-Shift-End moves -the location cursor to the last element. -.IP [14] -The space and Select keys make a selection at the location cursor -(active element) just as if mouse button 1 had been pressed over -this element. -.IP [15] -In \fBextended\fR mode, Control-Shift-space and Shift-Select -extend the selection to the active element just as if button 1 -had been pressed with the Shift key down. -.IP [16] -In \fBextended\fR mode, the Escape key cancels the most recent -selection and restores all the elements in the selected range -to their previous selection state. -.IP [17] -Control-slash selects everything in the widget, except in -\fBsingle\fR and \fBbrowse\fR modes, in which case it selects -the active element and deselects everything else. -.IP [18] -Control-backslash deselects everything in the widget, except in -\fBbrowse\fR mode where it has no effect. -.IP [19] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is -a selection. -.PP -The behavior of listboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -ttk::treeview(n) -.SH KEYWORDS -listbox, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/loadTk.n b/tk8.6/doc/loadTk.n deleted file mode 100644 index 3673e98..0000000 --- a/tk8.6/doc/loadTk.n +++ /dev/null @@ -1,69 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -safe::loadTk \- Load Tk into a safe interpreter. -.SH SYNOPSIS -\fBsafe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? -.BE -.SH DESCRIPTION -.PP -Safe Tk is based on Safe Tcl, which provides a mechanism that allows -restricted and mediated access to auto-loading and packages for safe -interpreters. Safe Tk adds the ability to configure the interpreter for safe -Tk operations and load Tk into safe interpreters. -.PP -The \fBsafe::loadTk\fR command initializes the required data structures in -the named safe interpreter and then loads Tk into it. The interpreter must -have been created with \fBsafe::interpCreate\fR or have been initialized -with \fBsafe::interpInit\fR. The command returns the name of the safe -interpreter. If \fB\-use\fR is specified, the window identified by the -specified system dependent identifier \fIwindowId\fR is used to contain the -.QW . -window of the safe interpreter; it can be any valid id, eventually referencing -a window belonging to another application. As a convenience, if the window you -plan to use is a Tk Window of the application you can use the window name -(e.g., -.QW \fB.x.y\fR ) -instead of its window Id (e.g., from \fBwinfo id\fR \fB.x.y\fR). -When \fB\-use\fR is not specified, a new toplevel window is created for the -.QW . -window of the safe interpreter. On X11 if you want the embedded window to use -another display than the default one, specify it with \fB\-display\fR. See -the \fBSECURITY ISSUES\fR section below for implementation details. -.SH "SECURITY ISSUES" -.PP -Please read the \fBsafe\fR manual page for Tcl to learn about the basic -security considerations for Safe Tcl. -.PP -\fBsafe::loadTk\fR adds the value of \fBtk_library\fR taken from the master -interpreter to the virtual access path of the safe interpreter so that -auto-loading will work in the safe interpreter. -.PP -Tk initialization is now safe with respect to not trusting the slave's state -for startup. \fBsafe::loadTk\fR registers the slave's name so when the Tk -initialization (\fBTk_SafeInit\fR) is called and in turn calls the master's -\fBsafe::InitTk\fR it will return the desired \fBargv\fR equivalent -(\fB\-use\fR \fIwindowId\fR, correct \fB\-display\fR, etc.) -.PP -When \fB\-use\fR is not used, the new toplevel created is specially decorated -so the user is always aware that the user interface presented comes from a -potentially unsafe code and can easily delete the corresponding interpreter. -.PP -On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely to generate a -fatal X error. -.SH "SEE ALSO" -safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) -.SH KEYWORDS -alias, auto-loading, auto_mkindex, load, master interpreter, safe -interpreter, slave interpreter, source -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/lower.n b/tk8.6/doc/lower.n deleted file mode 100644 index 8159a8b..0000000 --- a/tk8.6/doc/lower.n +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH lower n 3.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lower \- Change a window's position in the stacking order -.SH SYNOPSIS -\fBlower \fIwindow \fR?\fIbelowThis\fR? -.BE -.SH DESCRIPTION -.PP -If the \fIbelowThis\fR argument is omitted then the command lowers -\fIwindow\fR so that it is below all of its siblings in the stacking -order (it will be obscured by any siblings that overlap it and -will not obscure any siblings). -If \fIbelowThis\fR is specified then it must be the path name of -a window that is either a sibling of \fIwindow\fR or the descendant -of a sibling of \fIwindow\fR. -In this case the \fBlower\fR command will insert -\fIwindow\fR into the stacking order just below \fIbelowThis\fR -(or the ancestor of \fIbelowThis\fR that is a sibling of \fIwindow\fR); -this could end up either raising or lowering \fIwindow\fR. -.PP -All \fBtoplevel\fR windows may be restacked with respect to each -other, whatever their relative path names, but the window manager is -not obligated to strictly honor requests to restack. -.SH "SEE ALSO" -raise -.SH KEYWORDS -lower, obscure, stacking order -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/man.macros b/tk8.6/doc/man.macros deleted file mode 100644 index ddd073d..0000000 --- a/tk8.6/doc/man.macros +++ /dev/null @@ -1,267 +0,0 @@ -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. diff --git a/tk8.6/doc/menu.n b/tk8.6/doc/menu.n deleted file mode 100644 index 5742e23..0000000 --- a/tk8.6/doc/menu.n +++ /dev/null @@ -1,837 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH menu n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars -.SH SYNOPSIS -.nf -\fBmenu\fR \fIpathName \fR?\fIoptions\fR? -\fBtk_menuSetFocus\fR \fIpathName\fR -.SO -\-activebackground \-borderwidth \-foreground -\-activeborderwidth \-cursor \-relief -\-activeforeground \-disabledforeground \-takefocus -\-background \-font -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-postcommand postCommand Command -If this option is specified then it provides a Tcl command to execute -each time the menu is posted. The command is invoked by the \fBpost\fR -widget command before posting the menu. Note that in Tk 8.0 on Macintosh -and Windows, all post-commands in a system of menus are executed before any -of those menus are posted. -This is due to the limitations in the individual platforms' menu managers. -.OP \-selectcolor selectColor Background -For menu entries that are check buttons or radio buttons, this option -specifies the color to display in the indicator when the check button -or radio button is selected. -.OP \-tearoff tearOff TearOff -This option must have a proper boolean value, which specifies -whether or not the menu should include a tear-off entry at the -top. If so, it will exist as entry 0 of the menu and the other -entries will number starting at 1. The default -menu bindings arrange for the menu to be torn off when the tear-off -entry is invoked. -This option is ignored under Aqua/Mac OS X, where menus cannot -be torn off. -.OP \-tearoffcommand tearOffCommand TearOffCommand -If this option has a non-empty value, then it specifies a Tcl command -to invoke whenever the menu is torn off. The actual command will -consist of the value of this option, followed by a space, followed -by the name of the menu window, followed by a space, followed by -the name of the name of the torn off menu window. For example, if -the option's value is -.QW "\fBa b\fR" -and menu \fB.x.y\fR is torn off to -create a new menu \fB.x.tearoff1\fR, then the command -.QW "\fBa b .x.y .x.tearoff1\fR" -will be invoked. -This option is ignored under Aqua/Mac OS X, where menus cannot -be torn off. -.OP \-title title Title -The string will be used to title the window created when this menu is -torn off. If the title is NULL, then the window will have the title -of the menubutton or the text of the cascade item from which this menu -was invoked. -.OP \-type type Type -This option can be one of \fBmenubar\fR, \fBtearoff\fR, or -\fBnormal\fR, and is set when the menu is created. While the string -returned by the configuration database will change if this option is -changed, this does not affect the menu widget's behavior. This is used -by the cloning mechanism and is not normally set outside of the Tk -library. -.BE -.SH INTRODUCTION -.PP -The \fBmenu\fR command creates a new top-level window (given -by the \fIpathName\fR argument) and makes it into a menu widget. -That menu widget can either be used as a pop-up window or applied to a -\fBtoplevel\fR (with its \fB\-menu\fR option) to make it into the menubar for -that toplevel. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menu such as its colors and font. -The \fBmenu\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 menu is a widget that displays a collection of one-line entries arranged -in one or more columns. There exist several different types of entries, -each with different properties. Entries of different types may be -combined in a single menu. Menu entries are not the same as -entry widgets. In fact, menu entries are not even distinct widgets; -the entire menu is one widget. -.PP -Menu entries are displayed with up to three separate fields. -The main field is a label in the form of a text string, -a bitmap, or an image, controlled by the \fB\-label\fR, -\fB\-bitmap\fR, and \fB\-image\fR options for the entry. -If the \fB\-accelerator\fR option is specified for an entry then a second -textual field is displayed to the right of the label. The accelerator -typically describes a keystroke sequence that may be used in the -application to cause the same result as invoking the menu entry. -This is a display option, it does not actually set the corresponding -binding (which can be achieved using the \fBbind\fR command). -The third field is an \fIindicator\fR. The indicator is present only for -checkbutton or radiobutton entries. It indicates whether the entry -is selected or not, and is displayed to the left of the entry's -string. -.PP -In normal use, an entry becomes active (displays itself differently) -whenever the mouse pointer is over the entry. If a mouse -button is released over the entry then the entry is \fIinvoked\fR. -The effect of invocation is different for each type of entry; -these effects are described below in the sections on individual -entries. -.PP -Entries may be \fIdisabled\fR, which causes their labels -and accelerators to be displayed -with dimmer colors. -The default menu bindings will not allow -a disabled entry to be activated or invoked. -Disabled entries may be re-enabled, at which point it becomes -possible to activate and invoke them again. -.PP -Whenever a menu's active entry is changed, a <<MenuSelect>> virtual -event is send to the menu. The active item can then be queried from -the menu, and an action can be taken, such as setting -context-sensitive help text for the entry. -.SH "TYPES OF ENTRIES" -.SS "COMMAND ENTRIES" -.PP -The most common kind of menu entry is a command entry, which -behaves much like a button widget. When a command entry is -invoked, a Tcl command is executed. The Tcl -command is specified with the \fB\-command\fR option. -.SS "SEPARATOR ENTRIES" -.PP -A separator is an entry that is displayed as a horizontal dividing -line. A separator may not be activated or invoked, and it has -no behavior other than its display appearance. -.SS "CHECKBUTTON ENTRIES" -.PP -A checkbutton menu entry behaves much like a checkbutton widget. -When it is invoked it toggles back and forth between the selected -and deselected states. When the entry is selected, a particular -value is stored in a particular global variable (as determined by -the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when -the entry is deselected another value (determined by the -\fB\-offvalue\fR option) is stored in the global variable. -An indicator box is displayed to the left of the label in a checkbutton -entry. If the entry is selected then the indicator's center is displayed -in the color given by the \fB\-selectcolor\fR option for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a \fB\-command\fR option is specified for a checkbutton -entry, then its value is evaluated as a Tcl command each time the entry -is invoked; this happens after toggling the entry's -selected state. -.SS "RADIOBUTTON ENTRIES" -.PP -A radiobutton menu entry behaves much like a radiobutton widget. -Radiobutton entries are organized in groups of which only one -entry may be selected at a time. Whenever a particular entry -becomes selected it stores a particular value into a particular -global variable (as determined by the \fB\-value\fR and -\fB\-variable\fR options for the entry). This action -causes any previously-selected entry in the same group -to deselect itself. -Once an entry has become selected, any change to the entry's -associated variable will cause the entry to deselect itself. -Grouping of radiobutton entries is determined by their -associated variables: if two entries have the same associated -variable then they are in the same group. -An indicator diamond is displayed to the left of the label in each -radiobutton entry. If the entry is selected then the indicator's -center is displayed in the color given by the \fB\-selectcolor\fR option -for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a \fB\-command\fR option is specified for a radiobutton -entry, then its value is evaluated as a Tcl command each time the entry -is invoked; this happens after selecting the entry. -.SS "CASCADE ENTRIES" -.PP -A cascade entry is one with an associated menu (determined -by the \fB\-menu\fR option). Cascade entries allow the construction -of cascading menus. -The \fBpostcascade\fR widget command can be used to post and unpost -the associated menu just next to of the cascade entry. -The associated menu must be a child of the menu containing -the cascade entry (this is needed in order for menu traversal to -work correctly). -.PP -A cascade entry posts its associated menu by invoking a -Tcl command of the form -.CS -\fImenu\fB post \fIx y\fR -.CE -where \fImenu\fR is the path name of the associated menu, and \fIx\fR -and \fIy\fR are the root-window coordinates of the upper-right -corner of the cascade entry. -On Unix, the lower-level menu is unposted by executing a Tcl command with -the form -.CS -\fImenu\fB unpost\fR -.CE -where \fImenu\fR is the name of the associated menu. -On other platforms, the platform's native code takes care of unposting the -menu. -.PP -If a \fB\-command\fR option is specified for a cascade entry then it is -evaluated as a Tcl command whenever the entry is invoked. This is not -supported on Windows. -.SS "TEAR-OFF ENTRIES" -.PP -A tear-off entry appears at the top of the menu if enabled with the -\fB\-tearoff\fR option. It is not like other menu entries in that -it cannot be created with the \fBadd\fR widget command and -cannot be deleted with the \fBdelete\fR widget command. -When a tear-off entry is created it appears as a dashed line at -the top of the menu. Under the default bindings, invoking the -tear-off entry causes a torn-off copy to be made of the menu and -all of its submenus. -.SH "MENUBARS" -.PP -Any menu can be set as a menubar for a toplevel window (see -\fBtoplevel\fR command for syntax). On the Macintosh, whenever the -toplevel is in front, this menu's cascade items will appear in the -menubar across the top of the main monitor. On Windows and Unix, this -menu's items will be displayed in a menubar across the top of the -window. These menus will behave according to the interface guidelines -of their platforms. For every menu set as a menubar, a clone menu is -made. See the \fBCLONES\fR section for more information. -.PP -As noted, menubars may behave differently on different platforms. One -example of this concerns the handling of checkbuttons and radiobuttons -within the menu. While it is permitted to put these menu elements on -menubars, they may not be drawn with indicators on some platforms, due -to system restrictions. -.SS "SPECIAL MENUS IN MENUBARS" -.PP -Certain menus in a menubar will be treated specially. On the Macintosh, -access to the special Application, Window and Help menus is provided. On -Windows, access to the Windows System menu in each window is provided. -On X Windows, a special right-justified help menu may be provided if -Motif menu compatibility is enabled. In all cases, these menus must be -created with the command name of the menubar menu concatenated with the -special name. So for a menubar named .menubar, on the Macintosh, the -special menus would be .menubar.apple, .menubar.window and .menubar.help; -on Windows, the special menu would be .menubar.system; on X Windows, -the help menu would be .menubar.help. -.PP -When Tk sees a .menubar.apple menu as the first menu in a menubar on the -Macintosh, that menu's contents make up the first items of the -Application menu whenever the window containing the menubar is in front. -After all of the Tk-defined items, the menu will have a separator, -followed by all standard Application menu items. -Such a .apple menu must be present in a menu when that menu is first -configured as a toplevel's menubar, otherwise a default application menu -(hidden from Tk) will be inserted into the menubar at that time and -subsequent addition of a .apple menu will no longer result in it -becoming the Application menu. -.PP -When Tk sees a .menubar.window menu on the Macintosh, the menu's -contents are inserted into the standard Window menu of the user's -menubar whenever the window's menubar is in front. The first items in -the menu are provided by Mac OS X, and the names of the current -toplevels are automatically appended after all the Tk-defined items and -a separator. -.PP -When Tk sees a .menubar.help menu on the Macintosh, the menu's contents -are appended to the standard Help menu of the user's menubar whenever -the window's menubar is in front. The first items in the menu -are provided by Mac OS X. -.PP -When Tk sees a System menu on Windows, its items are appended to the -system menu that the menubar is attached to. This menu is tied to the -application icon and can be invoked with the mouse or by typing -Alt+Spacebar. Due to limitations in the Windows API, any font changes, -colors, images, bitmaps, or tearoff images will not appear in the -system menu. -.PP -When Tk sees a Help menu on X Windows and Motif menu compatibility is -enabled the menu is moved to be last in the menubar and is right -justified. Motif menu compatibility is enabled by setting the Tk option -\fB*Menu.useMotifHelp\fR to true or by calling -\fBtk::classic::restore menu\fR. -.SH "CLONES" -.PP -When a menu is set as a menubar for a toplevel window, or when a menu -is torn off, a clone of the menu is made. This clone is a menu widget -in its own right, but it is a child of the original. Changes in the -configuration of the original are reflected in the -clone. Additionally, any cascades that are pointed to are also cloned -so that menu traversal will work right. Clones are destroyed when -either the tearoff or menubar goes away, or when the original menu is -destroyed. -.SH "WIDGET COMMAND" -.PP -The \fBmenu\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. -.PP -Many of the widget commands for a menu take as one argument an -indicator of which entry of the menu to operate on. These -indicators are called \fIindex\fRes and may be specified in -any of the following forms: -.TP 12 -\fBactive\fR -. -Indicates the entry that is currently active. If no entry is -active then this form is equivalent to \fBnone\fR. This form may -not be abbreviated. -.TP 12 -\fBend\fR -. -Indicates the bottommost entry in the menu. If there are no -entries in the menu then this form is equivalent to \fBnone\fR. -This form may not be abbreviated. -.TP 12 -\fBlast\fR -. -Same as \fBend\fR. -.TP 12 -\fBnone\fR -. -Indicates -.QW "no entry at all" ; -this is used most commonly with -the \fBactivate\fR option to deactivate all the entries in the -menu. In most cases the specification of \fBnone\fR causes -nothing to happen in the widget command. -This form may not be abbreviated. -.TP 12 -\fB@\fInumber\fR -. -In this form, \fInumber\fR is treated as a y-coordinate in the -menu's window; the entry closest to that y-coordinate is used. -For example, -.QW \fB@0\fR -indicates the top-most entry in the window. -.TP 12 -\fInumber\fR -. -Specifies the entry numerically, where 0 corresponds -to the top-most entry of the menu, 1 to the entry below it, and -so on. -.TP 12 -\fIpattern\fR -. -If the index does not satisfy one of the above forms then this -form is used. \fIPattern\fR is pattern-matched against the label of -each entry in the menu, in order from the top down, until a -matching entry is found. The rules of \fBstring match\fR -are used. -.PP -If the index could match more than one of the above forms, then -the form earlier in the above list takes precedence. -.PP -The following widget commands are possible for menu widgets: -.TP -\fIpathName \fBactivate \fIindex\fR -. -Change the state of the entry indicated by \fIindex\fR to \fBactive\fR -and redisplay it using its active colors. -Any previously-active entry is deactivated. If \fIindex\fR -is specified as \fBnone\fR, or if the specified entry is -disabled, then the menu ends up with no active entry. -Returns an empty string. -.TP -\fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR? -. -Add a new entry to the bottom of the menu. The new entry's type -is given by \fItype\fR and must be one of \fBcascade\fR, -\fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, -or a unique abbreviation of one of the above. If additional arguments -are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR -section below. -The \fBadd\fR widget command returns an empty string. -.TP -\fIpathName \fBcget \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 \fBmenu\fR -command. -.TP -\fIpathName \fBclone \fInewPathname\fR ?\fIcloneType\fR? -. -Makes a clone of the current menu named \fInewPathName\fR. This clone -is a menu in its own right, but any changes to the clone are -propagated to the original menu and vice versa. \fIcloneType\fR can be -\fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be -called outside of the Tk library. See the \fBCLONES\fR section for -more information. -.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 \fBmenu\fR -command. -.TP -\fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? -. -Delete all of the menu entries between \fIindex1\fR and -\fIindex2\fR inclusive. -If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. -Attempts to delete a tear-off menu entry are ignored (instead, you -should change the \fB\-tearoff\fR option to remove the tear-off entry). -.TP -\fIpathName \fBentrycget \fIindex option\fR -. -Returns the current value of a configuration option for -the entry given by \fIindex\fR. -\fIOption\fR may have any of the names described in the -\fBMENU ENTRY OPTIONS\fR section below. -.TP -\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions...\fR? -. -This command is similar to the \fBconfigure\fR command, except that -it applies to the options for an individual entry, whereas \fBconfigure\fR -applies to the options for the menu as a whole. -\fIOptions\fR may have any of the values described in the -\fBMENU ENTRY OPTIONS\fR -section below. If \fIoptions\fR are specified, options are -modified as indicated in the command and the command returns an empty string. -If no \fIoptions\fR are specified, returns a list describing -the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). -.TP -\fIpathName \fBindex \fIindex\fR -. -Returns the numerical index corresponding to \fIindex\fR, or -\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. -.TP -\fIpathName \fBinsert \fIindex type \fR?\fIoption value option value ...\fR? -. -Same as the \fBadd\fR widget command except that it inserts the new -entry just before the entry given by \fIindex\fR, instead of appending -to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR -arguments have the same interpretation as for the \fBadd\fR widget -command. It is not possible to insert new menu entries before the -tear-off entry, if the menu has one. -.TP -\fIpathName \fBinvoke \fIindex\fR -. -Invoke the action of the menu entry. See the sections on the -individual entries above for details on what happens. If the -menu entry is disabled then nothing happens. If the -entry has a command associated with it then the result of that -command is returned as the result of the \fBinvoke\fR widget -command. Otherwise the result is an empty string. Note: invoking -a menu entry does not automatically unpost the menu; the default -bindings normally take care of this before invoking the \fBinvoke\fR -widget command. -.TP -\fIpathName \fBpost \fIx y\fR -. -Arrange for the menu to be displayed on the screen at the root-window -coordinates given by \fIx\fR and \fIy\fR. These coordinates are -adjusted if necessary to guarantee that the entire menu is visible on -the screen. This command normally returns an empty string. -If the \fB\-postcommand\fR option has been specified, then its value is -executed as a Tcl script before posting the menu and the result of -that script is returned as the result of the \fBpost\fR widget -command. -If an error returns while executing the command, then the error is -returned without posting the menu. -.TP -\fIpathName \fBpostcascade \fIindex\fR -. -Posts the submenu associated with the cascade entry given by -\fIindex\fR, and unposts any previously posted submenu. -If \fIindex\fR does not correspond to a cascade entry, -or if \fIpathName\fR is not posted, -the command has no effect except to unpost any currently posted -submenu. -.TP -\fIpathName \fBtype \fIindex\fR -. -Returns the type of the menu entry given by \fIindex\fR. -This is the \fItype\fR argument passed to the \fBadd\fR or \fBinsert\fR widget -command when the entry was created, such as \fBcommand\fR -or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. -.TP -\fIpathName \fBunpost\fR -. -Unmap the window so that it is no longer displayed. If a -lower-level cascaded menu is posted, unpost that menu. Returns an -empty string. This subcommand does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. -.TP -\fIpathName \fBxposition \fIindex\fR -. -Returns a decimal string giving the x-coordinate within the menu -window of the leftmost pixel in the entry specified by \fIindex\fR. -.TP -\fIpathName \fByposition \fIindex\fR -. -Returns a decimal string giving the y-coordinate within the menu -window of the topmost pixel in the entry specified by \fIindex\fR. -.SH "MENU ENTRY OPTIONS" -The following options are allowed on menu entries. Most options are not -supported by all entry types. -.TP -\fB\-activebackground \fIvalue\fR -. -Specifies a background color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -\fB\-activebackground\fR option for the overall menu is used. -If the \fBtk_strictMotif\fR variable has been set to request strict -Motif compliance, then this option is ignored and the \fB\-background\fR -option is used in its place. -This option is not available for separator or tear-off entries. -.TP -\fB\-activeforeground \fIvalue\fR -. -Specifies a foreground color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -\fB\-activeforeground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-accelerator \fIvalue\fR -. -Specifies a string to display at the right side of the menu entry. -Normally describes an accelerator keystroke sequence that may be -used to invoke the same function as the menu entry. This is a display -option, it does not actually set the corresponding binding (which can -be achieved using the \fBbind\fR command). This option is not available -for separator or tear-off entries. -.TP -\fB\-background \fIvalue\fR -. -Specifies a background color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -\fB\-background\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-bitmap \fIvalue\fR -. -Specifies a bitmap to display in the menu instead of a textual -label, in any of the forms accepted by \fBTk_GetBitmap\fR. -This option overrides the \fB\-label\fR option -(as controlled by the \fB\-compound\fR option) -but may be reset -to an empty string to enable a textual label to be displayed. -If a \fB\-image\fR option has been specified, it overrides -\fB\-bitmap\fR. -This option is not available for separator or tear-off entries. -.TP -\fB\-columnbreak \fIvalue\fR -. -When this option is zero, the entry appears below the previous entry. When -this option is one, the entry appears at the top of a new column in the -menu. -This option is ignored on Aqua/Mac OS X, where menus are always a single -column. -.TP -\fB\-command \fIvalue\fR -. -Specifies a Tcl command to execute when the menu entry is invoked. -Not available for separator or tear-off entries. -.TP -\fB\-compound \fIvalue\fR -. -Specifies whether the menu entry should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the button will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. -.TP -\fB\-font \fIvalue\fR -. -Specifies the font to use when drawing the label or accelerator -string in this entry. -If this option is specified as an empty string (the default) then -the \fB\-font\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-foreground \fIvalue\fR -. -Specifies a foreground color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -\fB\-foreground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-hidemargin \fIvalue\fR -. -Specifies whether the standard margins should be drawn for this menu -entry. This is useful when creating palette with images in them, i.e., -color palettes, pattern palettes, etc. 1 indicates that the margin for -the entry is hidden; 0 means that the margin is used. -.TP -\fB\-image \fIvalue\fR -. -Specifies an image to display in the menu instead of a text string -or bitmap. -The image must have been created by some previous invocation of -\fBimage create\fR. -This option overrides the \fB\-label\fR and \fB\-bitmap\fR options -(as controlled by the \fB\-compound\fR option) -but may be reset to an empty string to enable a textual or -bitmap label to be displayed. -This option is not available for separator or tear-off entries. -.TP -\fB\-indicatoron \fIvalue\fR -. -Available only for checkbutton and radiobutton entries. -\fIValue\fR is a boolean that determines whether or not the -indicator should be displayed. -.TP -\fB\-label \fIvalue\fR -. -Specifies a string to display as an identifying label in the menu -entry. Not available for separator or tear-off entries. -.TP -\fB\-menu \fIvalue\fR -. -Available only for cascade entries. Specifies the path name of -the submenu associated with this entry. -The submenu must be a child of the menu. -.TP -\fB\-offvalue \fIvalue\fR -. -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is -deselected. -.TP -\fB\-onvalue \fIvalue\fR -. -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. -.TP -\fB\-selectcolor \fIvalue\fR -. -Available only for checkbutton and radiobutton entries. -Specifies the color to display in the indicator when the entry is -selected. -If the value is an empty string (the default) then the \fB\-selectcolor\fR -option for the menu determines the indicator color. -.TP -\fB\-selectimage \fIvalue\fR -. -Available only for checkbutton and radiobutton entries. -Specifies an image to display in the entry (in place of -the \fB\-image\fR option) when it is selected. -\fIValue\fR is the name of an image, which must have been created -by some previous invocation of \fBimage create\fR. -This option is ignored unless the \fB\-image\fR option has -been specified. -.TP -\fB\-state \fIvalue\fR -. -Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the entry is displayed using the -\fB\-foreground\fR option for the menu and the \fB\-background\fR -option from the entry or the menu. -The active state is typically used when the pointer is over the entry. -In active state the entry is displayed using the \fB\-activeforeground\fR -option for the menu along with the \fB\-activebackground\fR option from -the entry. Disabled state means that the entry -should be insensitive: the default bindings will refuse to activate -or invoke the entry. -In this state the entry is displayed according to the -\fB\-disabledforeground\fR option for the menu and the -\fB\-background\fR option from the entry. -This option is not available for separator entries. -.TP -\fB\-underline \fIvalue\fR -. -Specifies the integer index of a character to underline in the entry. -This option is also queried by the default bindings and used to -implement keyboard traversal. -0 corresponds to the first character of the text displayed in the entry, -1 to the next character, and so on. -If a bitmap or image is displayed in the entry then this option is ignored. -This option is not available for separator or tear-off entries. -.TP -\fB\-value \fIvalue\fR -. -Available only for radiobutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. -If an empty string is specified, then the \fB\-label\fR option -for the entry as the value to store in the variable. -.TP -\fB\-variable \fIvalue\fR -. -Available only for checkbutton and radiobutton entries. Specifies -the name of a global variable to set when the entry is selected. -For checkbutton entries the variable is also set when the entry -is deselected. For radiobutton entries, changing the variable -causes the currently-selected entry to deselect itself. -.RS -.PP -For checkbutton entries, the default value of this option is taken from the -\fB\-label\fR option, and for radiobutton entries a single fixed value is -used. It is recommended that you always set the \fB\-variable\fR option when -creating either a checkbutton or a radiobutton. -.RE -.SH "MENU CONFIGURATIONS" -.PP -The default bindings support four different ways of using menus: -.TP -\fBPulldown Menus in Menubar\fR -. -This is the most common case. You create a menu widget that will become the -menu bar. You then add cascade entries to this menu, specifying the -pull down menus you wish to use in your menu bar. You then create all -of the pulldowns. Once you have done this, specify the menu using the -\fB\-menu\fR option of the toplevel's widget command. See the -\fBtoplevel\fR manual entry for details. -.TP -\fBPulldown Menus in Menu Buttons\fR -. -This is the compatible way to do menu bars. You create one menubutton -widget for each top-level menu, and typically you arrange a series of -menubuttons in a row in a menubar window. You also create the top-level menus -and any cascaded submenus, and tie them together with \fB\-menu\fR -options in menubuttons and cascade menu entries. The top-level menu must -be a child of the menubutton, and each submenu must be a child of the -menu that refers to it. Once you have done this, the default bindings -will allow users to traverse and invoke the tree of menus via its -menubutton; see the \fBmenubutton\fR manual entry for details. -.TP -\fBPopup Menus\fR -. -Popup menus typically post in response to a mouse button press or -keystroke. You create the popup menus and any cascaded submenus, -then you call the \fBtk_popup\fR procedure at the appropriate time -to post the top-level menu. -.TP -\fBOption Menus\fR -. -An option menu consists of a menubutton with an associated menu -that allows you to select one of several values. The current value -is displayed in the menubutton and is also stored in a global -variable. Use the \fBtk_optionMenu\fR procedure to create option -menubuttons and their menus. -.TP -\fBTorn-off Menus\fR -. -You create a torn-off menu by invoking the tear-off entry at -the top of an existing menu. The default bindings will create a new menu -that is a copy of the original menu and leave it permanently -posted as a top-level window. The torn-off menu behaves just -the same as the original menu. -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for menus that give them -the following default behavior: -.IP [1] -When the mouse enters a menu, the entry underneath the mouse -cursor activates; as the mouse moves around the menu, the active -entry changes to track the mouse. -.IP [2] -When the mouse leaves a menu all of the entries in the menu -deactivate, except in the special case where the mouse moves from -a menu to a cascaded submenu. -.IP [3] -When a button is released over a menu, the active entry (if any) is invoked. -The menu also unposts unless it is a torn-off menu. -.IP [4] -The Space and Return keys invoke the active entry and -unpost the menu. -.IP [5] -If any of the entries in a menu have letters underlined with -the \fB\-underline\fR option, then pressing one of the underlined -letters (or its upper-case or lower-case equivalent) invokes that -entry and unposts the menu. -.IP [6] -The Escape key aborts a menu selection in progress without invoking any -entry. It also unposts the menu unless it is a torn-off menu. -.IP [7] -The Up and Down keys activate the next higher or lower entry -in the menu. When one end of the menu is reached, the active -entry wraps around to the other end. -.IP [8] -The Left key moves to the next menu to the left. -If the current menu is a cascaded submenu, then the submenu is -unposted and the current menu entry becomes the cascade entry -in the parent. -If the current menu is a top-level menu posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the left is posted. -Otherwise the key has no effect. -The left-right order of menubuttons is determined by their stacking -order: Tk assumes that the lowest menubutton (which by default -is the first one created) is on the left. -.IP [9] -The Right key moves to the next menu to the right. -If the current entry is a cascade entry, then the submenu is -posted and the current menu entry becomes the first entry -in the submenu. -Otherwise, if the current menu was posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the right is posted. -.PP -Disabled menu entries are non-responsive: they do not activate and -they ignore mouse button presses and releases. -.PP -Several of the bindings make use of the command \fBtk_menuSetFocus\fR. -It saves the current focus and sets the focus to its \fIpathName\fR -argument, which is a menu widget. -.PP -The behavior of menus can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH BUGS -.PP -At present it is not possible to use the -option database to specify values for the options to individual -entries. -.SH "SEE ALSO" -bind(n), menubutton(n), ttk::menubutton(n), toplevel(n) -.SH KEYWORDS -menu, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/menubar.n b/tk8.6/doc/menubar.n deleted file mode 100644 index 023bf37..0000000 --- a/tk8.6/doc/menubar.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_menuBar n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_menuBar, tk_bindForTraversal \- Obsolete support for menu bars -.SH SYNOPSIS -\fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR? -.sp -\fBtk_bindForTraversal \fIarg arg ... \fR -.BE -.SH DESCRIPTION -.PP -These procedures were used in Tk 3.6 and earlier releases to help -manage pulldown menus and to implement keyboard traversal of menus. -In Tk 4.0 and later releases they are no -longer needed. Stubs for these procedures have been retained for -backward compatibility, but they have no effect. You should remove -calls to these procedures from your code, since eventually the -procedures will go away. -.PP -From Tk 8.0 onwards, you should instead construct your menubar as a -normal \fBmenu\fR and then attach it to the \fBtoplevel\fR of your -choice using the \fB\-menu\fR option of that widget. -.SH "SEE ALSO" -menu(n), toplevel(n) -.SH KEYWORDS -keyboard traversal, menu, menu bar, post -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/menubutton.n b/tk8.6/doc/menubutton.n deleted file mode 100644 index 08b52a0..0000000 --- a/tk8.6/doc/menubutton.n +++ /dev/null @@ -1,202 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH menubutton n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets -.SH SYNOPSIS -\fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-disabledforeground \-padx -\-activeforeground \-font \-pady -\-anchor \-foreground \-relief -\-background \-highlightbackground \-takefocus -\-bitmap \-highlightcolor \-text -\-borderwidth \-highlightthickness \-textvariable -\-cursor \-image \-underline -\-compound \-justify \-wraplength -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-direction direction Height -Specifies where the menu is going to be popup up. \fBabove\fR tries to -pop the menu above the menubutton. \fBbelow\fR tries to pop the menu -below the menubutton. \fBleft\fR tries to pop the menu to the left of -the menubutton. \fBright\fR tries to pop the menu to the right of the -menu button. \fBflush\fR pops the menu directly over the menubutton. -In the case of \fBabove\fR or \fBbelow\fR, the direction will be -reversed if the menu would show offscreen. -.OP \-height height Height -Specifies a desired height for the menubutton. -If an image or bitmap is being displayed in the menubutton 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 menubutton's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-indicatoron indicatorOn IndicatorOn -The value must be a proper boolean value. If it is true then -a small indicator rectangle will be displayed on the right side -of the menubutton and the default menu bindings will treat this -as an option menubutton. If false then no indicator will be -displayed. -.OP \-menu menu MenuName -Specifies the path name of the menu associated with this menubutton. -The menu must be a child of the menubutton. -.OP \-state state State -Specifies one of three states for the menubutton: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the menubutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is -typically used when the pointer is over the menubutton. In active state -the menubutton is displayed using the \fB\-activeforeground\fR and -\fB\-activebackground\fR options. Disabled state means that the menubutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fB\-disabledforeground\fR and -\fB\-background\fR options determine how the button is displayed. -.OP \-width width Width -Specifies a desired width for the menubutton. -If an image or bitmap is being displayed in the menubutton 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 menubutton's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE -.SH INTRODUCTION -.PP -The \fBmenubutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a menubutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menubutton such as its colors, font, -text, and initial relief. The \fBmenubutton\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 menubutton is a widget that displays a textual string, bitmap, or image -and is associated with a menu widget. -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 \fB\-wraplength\fR option) and -one of the characters may optionally be underlined using the -\fB\-underline\fR option. In normal usage, pressing -mouse button 1 over the menubutton causes the associated menu to -be posted just underneath the menubutton. If the mouse is moved over -the menu before releasing the mouse button, the button release -causes the underlying menu entry to be invoked. When the button -is released, the menu is unposted. -.PP -Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the -preferred mechanism for allowing a user to select one item from a list -on Mac OS X. -.PP -Menubuttons were also typically organized into groups called menu bars -that allow scanning: -if the mouse button is pressed over one menubutton (causing it -to post its menu) and the mouse is moved over another menubutton -in the same menu bar without releasing the mouse button, then the -menu of the first menubutton is unposted and the menu of the -new menubutton is posted instead. -\fIThis use is deprecated\fR in favor of setting a \fBmenu\fR directly as a -menubar; see the \fBtoplevel\fR's \fB\-menu\fR option for how to do that. -.PP -There are several interactions between menubuttons and menus; see -the \fBmenu\fR manual entry for information on various menu configurations, -such as pulldown menus and option menus. -.SH "WIDGET COMMAND" -.PP -The \fBmenubutton\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 menubutton widgets: -.TP -\fIpathName \fBcget \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 \fBmenubutton\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 \fBmenubutton\fR -command. -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for menubuttons that give them -the following default behavior: -.IP [1] -A menubutton activates whenever the mouse passes over it and deactivates -whenever the mouse leaves it. -.IP [2] -Pressing mouse button 1 over a menubutton posts the menubutton: -its relief changes to raised and its associated menu is posted -under the menubutton. If the mouse is dragged down into the menu -with the button still down, and if the mouse button is then -released over an entry in the menu, the menubutton is unposted -and the menu entry is invoked. -.IP [3] -If button 1 is pressed over a menubutton and then released over that -menubutton, the menubutton stays posted: you can still move the mouse -over the menu and click button 1 on an entry to invoke it. -Once a menu entry has been invoked, the menubutton unposts itself. -.IP [4] -If button 1 is pressed over a menubutton and then dragged over some -other menubutton, the original menubutton unposts itself and the -new menubutton posts. -.IP [5] -If button 1 is pressed over a menubutton and released outside -any menubutton or menu, the menubutton unposts without invoking -any menu entry. -.IP [6] -When a menubutton is posted, its associated menu claims the input -focus to allow keyboard traversal of the menu and its submenus. -See the \fBmenu\fR manual entry for details on these bindings. -.IP [7] -If the \fB\-underline\fR option has been specified for a menubutton -then keyboard traversal may be used to post the menubutton: -Alt+\fIx\fR, where \fIx\fR is the underlined character (or its -lower-case or upper-case equivalent), may be typed in any window -under the menubutton's toplevel to post the menubutton. -.IP [8] -The F10 key may be typed in any window to post the first menubutton -under its toplevel window that is not disabled. -.IP [9] -If a menubutton has the input focus, the space and return keys -post the menubutton. -.PP -If the menubutton's state is \fBdisabled\fR then none of the above -actions occur: the menubutton is completely non-responsive. -.PP -The behavior of menubuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -ttk::menubutton(n), menu(n) -.SH KEYWORDS -menubutton, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/message.n b/tk8.6/doc/message.n deleted file mode 100644 index bd635ac..0000000 --- a/tk8.6/doc/message.n +++ /dev/null @@ -1,150 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH message n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -message \- Create and manipulate 'message' non-interactive text widgets -.SH SYNOPSIS -\fBmessage\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-anchor \-background \-borderwidth -\-cursor \-font \-foreground -\-highlightbackground \-highlightcolor \-highlightthickness -\-padx \-pady \-relief -\-takefocus \-text \-textvariable -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-aspect aspect Aspect -Specifies a non-negative integer value indicating desired -aspect ratio for the text. The aspect ratio is specified as -100*width/height. 100 means the text should -be as wide as it is tall, 200 means the text should -be twice as wide as it is tall, 50 means the text should -be twice as tall as it is wide, and so on. -Used to choose line length for text if \fB\-width\fR option -is not specified. -Defaults to 150. -.OP \-justify justify Justify -Specifies how to justify lines of text. -Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. Defaults -to \fBleft\fR. -This option works together with the \fB\-anchor\fR, \fB\-aspect\fR, -\fB\-padx\fR, \fB\-pady\fR, and \fB\-width\fR options to provide a variety -of arrangements of the text within the window. -The \fB\-aspect\fR and \fB\-width\fR options determine the amount of -screen space needed to display the text. -The \fB\-anchor\fR, \fB\-padx\fR, and \fB\-pady\fR options determine where this -rectangular area is displayed within the widget's window, and the -\fB\-justify\fR option determines how each line is displayed within that -rectangular region. -For example, suppose \fB\-anchor\fR is \fBe\fR and \fB\-justify\fR is -\fBleft\fR, and that the message window is much larger than needed -for the text. -The text will be displayed so that the left edges of all the lines -line up and the right edge of the longest line is \fB\-padx\fR from -the right side of the window; the entire text block will be centered -in the vertical span of the window. -.OP \-width width Width -Specifies the length of lines in the window. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If this option has a value greater than zero then the \fB\-aspect\fR -option is ignored and the \fB\-width\fR option determines the line -length. -If this option has a value less than or equal to zero, then -the \fB\-aspect\fR option determines the line length. -.BE -.SH DESCRIPTION -.PP -The \fBmessage\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a message widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the message such as its colors, font, -text, and initial relief. The \fBmessage\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 message is a widget that displays a textual string. A message -widget has three special features that differentiate it from a -\fBlabel\fR widget. First, it breaks up -its string into lines in order to produce a given aspect ratio -for the window. The line breaks are chosen at word boundaries -wherever possible (if not even a single word would fit on a -line, then the word will be split across lines). Newline characters -in the string will force line breaks; they can be used, for example, -to leave blank lines in the display. -.PP -The second feature of a message widget is justification. The text -may be displayed left-justified (each line starts at the left side of -the window), centered on a line-by-line basis, or right-justified -(each line ends at the right side of the window). -.PP -The third feature of a message widget is that it handles control -characters and non-printing characters specially. Tab characters -are replaced with enough blank space to line up on the next -8-character boundary. Newlines cause line breaks. Other control -characters (ASCII code less than 0x20) and characters not defined -in the font are displayed as a four-character sequence \fB\ex\fIhh\fR where -\fIhh\fR is the two-digit hexadecimal number corresponding to -the character. In the unusual case where the font does not contain -all of the characters in -.QW 0123456789abcdef\ex -then control characters and undefined characters are not displayed at all. -.SH "WIDGET COMMAND" -.PP -The \fBmessage\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 message widgets: -.TP -\fIpathName \fBcget \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 \fBmessage\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 \fBmessage\fR -command. -.SH "DEFAULT BINDINGS" -.PP -When a new message is created, it has no default event bindings: -messages are intended for output purposes only. -.SH BUGS -.PP -Tabs do not work very well with text that is centered or right-justified. -The most common result is that the line is justified wrong. -.SH "SEE ALSO" -label(n) -.SH KEYWORDS -message, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/messageBox.n b/tk8.6/doc/messageBox.n deleted file mode 100644 index 6bcbc09..0000000 --- a/tk8.6/doc/messageBox.n +++ /dev/null @@ -1,122 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_messageBox n 4.2 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_messageBox \- pops up a message window and waits for user response. -.SH SYNOPSIS -\fBtk_messageBox \fR?\fIoption value ...\fR? -.BE -.SH DESCRIPTION -.PP -This procedure creates and displays a message window with an -application-specified message, an icon and a set of buttons. Each of -the buttons in the message window is identified by a unique symbolic -name (see the \fB\-type\fR options). After the message window is -popped up, \fBtk_messageBox\fR waits for the user to select one of the -buttons. Then it returns the symbolic name of the selected button. -.PP -The following option-value pairs are supported: -.TP -\fB\-command\fR \fIstring\fR -Specifies the prefix of a Tcl command to invoke when the user closes the -dialog. The actual command consists of \fIstring\fR followed by a space -and the name of the button clicked by the user to close the dialog. This -is only available on Mac OS X. -.TP -\fB\-default\fR \fIname\fR -. -\fIName\fR gives the symbolic name of the default button for -this message window ( -.QW ok , -.QW cancel , -and so on). See \fB\-type\fR -for a list of the symbolic names. If this option is not specified, -the first button in the dialog will be made the default. -.TP -\fB\-detail\fR \fIstring\fR -. -Specifies an auxiliary message to the main message given by the -\fB\-message\fR option. The message detail will be presented beneath the main -message and, where supported by the OS, in a less emphasized font than the -main message. -.TP -\fB\-icon\fR \fIiconImage\fR -. -Specifies an icon to display. \fIIconImage\fR must be one of the -following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or -\fBwarning\fR. If this option is not specified, then the info icon will be -displayed. -.TP -\fB\-message\fR \fIstring\fR -. -Specifies the message to display in this message box. The -default value is an empty string. -.TP -\fB\-parent\fR \fIwindow\fR -. -Makes \fIwindow\fR the logical parent of the message box. The message -box is displayed on top of its parent window. -.TP -\fB\-title\fR \fItitleString\fR -. -Specifies a string to display as the title of the message box. This option -is ignored on Mac OS X, where platform guidelines forbid the use of a title -on this kind of dialog. -.TP -\fB\-type\fR \fIpredefinedType\fR -. -Arranges for a predefined set of buttons to be displayed. The -following values are possible for \fIpredefinedType\fR: -.RS -.TP 18 -\fBabortretryignore\fR -. -Displays three buttons whose symbolic names are \fBabort\fR, -\fBretry\fR and \fBignore\fR. -.TP 18 -\fBok\fR -. -Displays one button whose symbolic name is \fBok\fR. -.TP 18 -\fBokcancel\fR -. -Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR. -.TP 18 -\fBretrycancel\fR -. -Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR. -.TP 18 -\fByesno\fR -. -Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR. -.TP 18 -\fByesnocancel\fR -. -Displays three buttons whose symbolic names are \fByes\fR, \fBno\fR -and \fBcancel\fR. -.RE -.PP -.SH EXAMPLE -.PP -.CS -set answer [\fBtk_messageBox\fR \-message "Really quit?" \e - \-icon question \-type yesno \e - \-detail "Select \e"Yes\e" to make the application exit"] -switch \-\- $answer { - yes exit - no {\fBtk_messageBox\fR \-message "I know you like this application!" \e - \-type ok} -} -.CE -.SH KEYWORDS -message box -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/option.n b/tk8.6/doc/option.n deleted file mode 100644 index 2763d64..0000000 --- a/tk8.6/doc/option.n +++ /dev/null @@ -1,140 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH option n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -option \- Add/retrieve window options to/from the option database -.SH SYNOPSIS -.nf -\fBoption add \fIpattern value \fR?\fIpriority\fR? -\fBoption clear\fR -\fBoption get \fIwindow name class\fR -\fBoption readfile \fIfileName \fR?\fIpriority\fR? -.fi -.BE -.SH DESCRIPTION -.PP -The \fBoption\fR command allows you to add entries to the Tk option -database or to retrieve options from the database. The \fBadd\fR -form of the command adds a new option to the database. -\fIPattern\fR contains -the option being specified, and consists of names and/or classes -separated by asterisks or dots, in the usual X format (see -\fBPATTERN FORMAT\fR). \fIValue\fR -contains a text string to associate with \fIpattern\fR; this is the -value that will be returned in calls to \fBTk_GetOption\fR or by -invocations of the \fBoption get\fR command. If \fIpriority\fR -is specified, it indicates the priority level for this option (see -below for legal values); it defaults to \fBinteractive\fR. -This command always returns an empty string. -.PP -The \fBoption clear\fR command clears the option database. Default -options (from the -\fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR -file) will be reloaded automatically the next time an -option is added to the database or removed from it. This command -always returns an empty string. -.PP -The \fBoption get\fR command returns the value of the option -specified for \fIwindow\fR -under \fIname\fR and \fIclass\fR. If several entries in the option -database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then -the command returns whichever was created with highest -\fIpriority\fR level. If there are several matching -entries at the same priority level, then it returns whichever entry -was most recently entered into the option database. If there are -no matching entries, then the empty string is returned. -.PP -The \fBreadfile\fR form of the command reads \fIfileName\fR, -which should have the standard format for an -X resource database such as \fB.Xdefaults\fR, and adds all the -options specified in that file to the option database. If \fIpriority\fR -is specified, it indicates the priority level at which to enter the -options; \fIpriority\fR defaults to \fBinteractive\fR. -.PP -The file is read through a channel which is in "utf-8" encoding, -invalid byte sequences are automatically converted to valid ones. -This means that encodings like ISO 8859-1 or cp1252 with high -probability will work as well, but this cannot be guaranteed. -This cannot be changed, setting the [encoding system] has no effect. -.PP -The \fIpriority\fR arguments to the \fBoption\fR command are -normally specified symbolically using one of the following values: -.TP -\fBwidgetDefault\fR -Level 20. Used for default values hard-coded into widgets. -.TP -\fBstartupFile\fR -Level 40. Used for options specified in application-specific -startup files. -.TP -\fBuserDefault\fR -Level 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. -.TP -\fBinteractive\fR -Level 80. Used for options specified interactively after the application -starts running. If \fIpriority\fR is not specified, it defaults to -this level. -.PP -Any of the above keywords may be abbreviated. In addition, priorities -may be specified numerically using integers between 0 and 100, -inclusive. The numeric form is probably a bad idea except for new priority -levels other than the ones given above. -.SH "PATTERN FORMAT" -.PP -Patterns consist of a sequence of words separated by either periods, -.QW . , -or asterisks -.QW * . -The overall pattern may also be optionally preceded by an asterisk. -.PP -Each word in the pattern conventionally starts with either an upper-case -letter (in which case it denotes the class of either a widget or an option) or -any other character, when it denotes the name of a widget or option. The last -word in the pattern always indicates the option; the preceding ones constrain -which widgets that option will be looked for in. -.PP -When two words are separated by a period, the latter widget must be a direct -child of the former (or the option must apply to only the indicated widgets). -When two words are separated by an asterisk, any depth of widgets may lie -between the former and latter widgets (and the option applies to all widgets -that are children of the former widget). -.PP -If the overall pattern is preceded by an asterisk, then the overall pattern -applies anywhere it can throughout the whole widget hierarchy. Otherwise the -first word of the pattern is matched against the name and class of the -.QW \fB.\fR -\fBtoplevel\fR, which are usually set by options to \fBwish\fR. -.SH EXAMPLES -.PP -Instruct every button in the application to have red text on it unless -explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR -class (note that on some platforms the option is ignored): -.CS -\fBoption add\fR *Button.foreground red startupFile -.CE -.PP -Allow users to control what happens in an entry widget when the Return -key is pressed by specifying a script in the option database and add a -default option for that which rings the bell: -.CS -entry .e -bind .e <Return> [\fBoption get\fR .e returnCommand Command] -\fBoption add\fR *.e.returnCommand bell widgetDefault -.CE -.SH "SEE ALSO" -options(n), wish(1) -.SH KEYWORDS -database, option, priority, retrieve -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/optionMenu.n b/tk8.6/doc/optionMenu.n deleted file mode 100644 index 42275ce..0000000 --- a/tk8.6/doc/optionMenu.n +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_optionMenu \- Create an option menubutton and its menu -.SH SYNOPSIS -\fBtk_optionMenu \fIpathName varName value \fR?\fIvalue value ...\fR? -.BE -.SH DESCRIPTION -.PP -This procedure creates an option menubutton whose name is \fIpathName\fR, -plus an associated menu. -Together they allow the user to select one of the values -given by the \fIvalue\fR arguments. -The current value will be stored in the global variable whose -name is given by \fIvarName\fR and it will also be displayed as the label -in the option menubutton. -The user can click on the menubutton to display a menu containing -all of the \fIvalue\fRs and thereby select a new value. -Once a new value is selected, it will be stored in the variable -and appear in the option menubutton. -The current value can also be changed by setting the variable. -.PP -The return value from \fBtk_optionMenu\fR is the name of the menu -associated with \fIpathName\fR, so that the caller can change its -configuration options or manipulate it in other ways. -.SH EXAMPLE -.PP -.CS -tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble -pack .foo -.CE -.SH KEYWORDS -option menu -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/options.n b/tk8.6/doc/options.n deleted file mode 100644 index 738a1c6..0000000 --- a/tk8.6/doc/options.n +++ /dev/null @@ -1,358 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH options n 4.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -options \- Standard options supported by widgets -.BE -.SH DESCRIPTION -.PP -This manual entry describes the common configuration options supported -by widgets in the Tk toolkit. Every widget does not necessarily support -every option (see the manual entries for individual widgets for a list -of the standard options supported by that widget), but if a widget does -support an option with one of the names listed below, then the option -has exactly the effect described below. -.PP -In the descriptions below, -.QW "Command-Line Name" -refers to the -switch used in class commands and \fBconfigure\fR widget commands to -set this value. For example, if an option's command-line switch is -\fB\-foreground\fR and there exists a widget \fB.a.b.c\fR, then the -command -.CS -\&\fB.a.b.c\0\0configure\0\0\-foreground black\fR -.CE -may be used to specify the value \fBblack\fR for the option in -the widget \fB.a.b.c\fR. Command-line switches may be abbreviated, -as long as the abbreviation is unambiguous. -.QW "Database Name" -refers to the option's name in the option database (e.g. in .Xdefaults files). -.QW "Database Class" -refers to the option's class value in the option database. -.OP \-activebackground activeBackground Foreground -Specifies background color to use when drawing active elements. -An element (a widget or portion of a widget) is active if the -mouse cursor is positioned over the element and pressing a mouse button -will cause some action to occur. -If strict Motif compliance has been requested by setting the -\fBtk_strictMotif\fR variable, this option will normally be -ignored; the normal background color will be used instead. -For some elements on Windows and Macintosh systems, the active color -will only be used while mouse button 1 is pressed over the element. -.OP \-activeborderwidth activeBorderWidth BorderWidth -Specifies a non-negative value indicating -the width of the 3-D border drawn around active elements. See above for -definition of active elements. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -This option is typically only available in widgets displaying more -than one element at a time (e.g. menus but not buttons). -.OP \-activeforeground activeForeground Background -Specifies foreground color to use when drawing active elements. -See above for definition of active elements. -.OP \-anchor anchor Anchor -Specifies how the information in a widget (e.g. text or a bitmap) -is to be displayed in the widget. -Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. -For example, \fBnw\fR means display the information such that its -top-left corner is at the top-left corner of the widget. -.OP "\-background or \-bg" background Background -Specifies the normal background color to use when displaying the -widget. -.OP \-bitmap bitmap Bitmap -Specifies a bitmap to display in the widget, in any of the forms -acceptable to \fBTk_GetBitmap\fR. -The exact way in which the bitmap is displayed may be affected by -other options such as \fB\-anchor\fR or \fB\-justify\fR. -Typically, if this option is specified then it overrides other -options that specify a textual value to display in the widget -but this is controlled by the \fB\-compound\fR option; -the \fB\-bitmap\fR option may be reset to an empty string to re-enable -a text display. -In widgets that support both \fB\-bitmap\fR and \fB\-image\fR options, -\fB\-image\fR will usually override \fB\-bitmap\fR. -.OP "\-borderwidth or \-bd" borderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around the outside of the widget (if such a -border is being drawn; the \fB\-relief\fR option typically determines -this). The value may also be used when drawing 3-D effects in the -interior of the widget. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-cursor cursor Cursor -Specifies the mouse cursor to be used for the widget. -The value may have any of the forms acceptable to \fBTk_GetCursor\fR. -In addition, if an empty string is specified, it indicates that the -widget should defer to its parent for cursor specification. -.OP \-compound compound Compound -Specifies if the widget should display text and bitmaps/images at the -same time, and if so, where the bitmap/image should be placed relative -to the text. Must be one of the values \fBnone\fR, \fBbottom\fR, -\fBtop\fR, \fBleft\fR, \fBright\fR, or \fBcenter\fR. For example, the -(default) value \fBnone\fR specifies that the bitmap or image should -(if defined) be displayed instead of the text, the value \fBleft\fR -specifies that the bitmap or image should be displayed to the left of -the text, and the value \fBcenter\fR specifies that the bitmap or -image should be displayed on top of the text. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies foreground color to use when drawing a disabled element. -If the option is specified as an empty string (which is typically the -case on monochrome displays), disabled elements are drawn with the -normal foreground color but they are dimmed by drawing them -with a stippled fill pattern. -.OP \-exportselection exportSelection ExportSelection -Specifies whether or not a selection in the widget should also be -the X selection. -The value may have any of the forms accepted by \fBTcl_GetBoolean\fR, -such as \fBtrue\fR, \fBfalse\fR, \fB0\fR, \fB1\fR, \fByes\fR, or \fBno\fR. -If the selection is exported, then selecting in the widget deselects -the current X selection, selecting outside the widget deselects any -widget selection, and the widget will respond to selection retrieval -requests when it has a selection. The default is usually for widgets -to export selections. -.OP \-font font Font -Specifies the font to use when drawing text inside the widget. -The value may have any of the forms described in the \fBfont\fR manual -page under \fBFONT DESCRIPTION\fR. -.OP "\-foreground or \-fg" foreground Foreground -Specifies the normal foreground color to use when displaying the widget. -.OP \-highlightbackground highlightBackground HighlightBackground -Specifies the color to display in the traversal highlight region when -the widget does not have the input focus. -.OP \-highlightcolor highlightColor HighlightColor -Specifies the color to use for the traversal highlight rectangle that is -drawn around the widget when it has the input focus. -.OP \-highlightthickness highlightThickness HighlightThickness -Specifies a non-negative value indicating the width of the highlight -rectangle to draw around the outside of the widget when it has the -input focus. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If the value is zero, no focus highlight is drawn around the widget. -.OP \-image image Image -Specifies an image to display in the widget, which must have been -created with the \fBimage create\fR command. -Typically, if the \fB\-image\fR option is specified then it overrides other -options that specify a bitmap or textual value to display in the -widget, though this is controlled by the \fB\-compound\fR option; -the \fB\-image\fR option may be reset to an empty string to re-enable -a bitmap or text display. -.OP \-insertbackground insertBackground Foreground -Specifies the color to use as background in the area covered by the -insertion cursor. This color will normally override either the normal -background for the widget (or the selection background if the insertion -cursor happens to fall in the selection). -.OP \-insertborderwidth insertBorderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around the insertion cursor. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-insertofftime insertOffTime OffTime -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain -.QW off -in each blink cycle. -If this option is zero then the cursor does not blink: it is on -all the time. -.OP \-insertontime insertOnTime OnTime -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain -.QW on -in each blink cycle. -.OP \-insertwidth insertWidth InsertWidth -Specifies a value indicating the total width of the insertion cursor. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If a border has been specified for the insertion -cursor (using the \fB\-insertborderwidth\fR option), the border -will be drawn inside the width specified by the \fB\-insertwidth\fR -option. -.OP \-jump jump Jump -For widgets with a slider that can be dragged to adjust a value, -such as scrollbars, this option determines when -notifications are made about changes in the value. -The option's value must be a boolean of the form accepted by -\fBTcl_GetBoolean\fR. -If the value is false, updates are made continuously as the -slider is dragged. -If the value is true, updates are delayed until the mouse button -is released to end the drag; at that point a single notification -is made (the value -.QW jumps -rather than changing smoothly). -.OP \-justify justify Justify -When there are multiple lines of text displayed in a widget, this -option determines how the lines line up with each other. -Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -\fBLeft\fR means that the lines' left edges all line up, \fBcenter\fR -means that the lines' centers are aligned, and \fBright\fR means -that the lines' right edges line up. -.OP \-orient orient Orient -For widgets that can lay themselves out with either a horizontal -or vertical orientation, such as scrollbars, this option specifies -which orientation should be used. Must be either \fBhorizontal\fR -or \fBvertical\fR or an abbreviation of one of these. -.OP \-padx padX Pad -Specifies a non-negative value indicating how much extra space -to request for the widget in the X-direction. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -When computing how large a window it needs, the widget will -add this amount to the width it would normally need (as determined -by the width of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space to the left and/or right of what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. -.OP \-pady padY Pad -Specifies a non-negative value indicating how much extra space -to request for the widget in the Y-direction. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -When computing how large a window it needs, the widget will add -this amount to the height it would normally need (as determined by -the height of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space above and/or below what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. -.OP \-relief relief Relief -Specifies the 3-D effect desired for the widget. Acceptable -values are \fBraised\fR, \fBsunken\fR, \fBflat\fR, \fBridge\fR, -\fBsolid\fR, and \fBgroove\fR. -The value -indicates how the interior of the widget should appear relative -to its exterior; for example, \fBraised\fR means the interior of -the widget should appear to protrude from the screen, relative to -the exterior of the widget. -.OP \-repeatdelay repeatDelay RepeatDelay -Specifies the number of milliseconds a button or key must be held -down before it begins to auto-repeat. Used, for example, on the -up- and down-arrows in scrollbars. -.OP \-repeatinterval repeatInterval RepeatInterval -Used in conjunction with \fB\-repeatdelay\fR: once auto-repeat -begins, this option determines the number of milliseconds between -auto-repeats. -.OP \-selectbackground selectBackground Foreground -Specifies the background color to use when displaying selected -items. -.OP \-selectborderwidth selectBorderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around selected items. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-selectforeground selectForeground Background -Specifies the foreground color to use when displaying selected -items. -.OP \-setgrid setGrid SetGrid -Specifies a boolean value that determines whether this widget controls the -resizing grid for its top-level window. -This option is typically used in text widgets, where the information -in the widget has a natural size (the size of a character) and it makes -sense for the window's dimensions to be integral numbers of these units. -These natural window sizes form a grid. -If the \fB\-setgrid\fR option is set to true then the widget will -communicate with the window manager so that when the user interactively -resizes the top-level window that contains the widget, the dimensions of -the window will be displayed to the user in grid units and the window -size will be constrained to integral numbers of grid units. -See the section \fBGRIDDED GEOMETRY MANAGEMENT\fR in the \fBwm\fR manual -entry for more details. -.OP \-takefocus takeFocus TakeFocus -Determines whether the window accepts the focus during keyboard -traversal (e.g., Tab and Shift-Tab). -Before setting the focus to a window, the traversal scripts -consult the value of the \fB\-takefocus\fR option. -A value of \fB0\fR means that the window should be skipped entirely -during keyboard traversal. -\fB1\fR means that the window should receive the input -focus as long as it is viewable (it and all of its ancestors are mapped). -An empty value for the option means that the traversal scripts make -the decision about whether or not to focus on the window: the current -algorithm is to skip the window if it is -disabled, if it has no key bindings, or if it is not viewable. -If the value has any other form, then the traversal scripts take -the value, append the name of the window to it (with a separator space), -and evaluate the resulting string as a Tcl script. -The script must return \fB0\fR, \fB1\fR, or an empty string: a -\fB0\fR or \fB1\fR value specifies whether the window will receive -the input focus, and an empty string results in the default decision -described above. -Note: this interpretation of the option is defined entirely by -the Tcl scripts that implement traversal: the widget implementations -ignore the option entirely, so you can change its meaning if you -redefine the keyboard traversal scripts. -.OP \-text text Text -Specifies a string to be displayed inside the widget. The way in which -the string is displayed depends on the particular widget and may be -determined by other options, such as \fB\-anchor\fR or \fB\-justify\fR. -.OP \-textvariable textVariable Variable -Specifies the name of a global variable. The value of the variable is a text -string to be displayed inside the widget; if the variable value changes -then the widget will automatically update itself to reflect the new value. -The way in which the string is displayed in the widget depends on the -particular widget and may be determined by other options, such as -\fB\-anchor\fR or \fB\-justify\fR. -.OP \-troughcolor troughColor Background -Specifies the color to use for the rectangular trough areas -in widgets such as scrollbars and scales. This option is ignored for -scrollbars on Windows (native widget does not recognize this option). -.OP \-underline underline Underline -Specifies the integer index of a character to underline in the widget. -This option is used by the default bindings to implement keyboard -traversal for menu buttons and menu entries. -0 corresponds to the first character of the text displayed in the -widget, 1 to the next character, and so on. -.OP \-wraplength wrapLength WrapLength -For widgets that can perform word-wrapping, this option specifies -the maximum line length. -Lines that would exceed this length are wrapped onto the next line, -so that no line is longer than the specified length. -The value may be specified in any of the standard forms for -screen distances. -If this value is less than or equal to 0 then no wrapping is done: lines -will break only at newline characters in the text. -.OP \-xscrollcommand xScrollCommand ScrollCommand -Specifies the prefix for a command used to communicate with horizontal -scrollbars. -When the view in the widget's window changes (or -whenever anything else occurs that could change the display in a -scrollbar, such as a change in the total size of the widget's -contents), the widget will -generate a Tcl command by concatenating the scroll command and -two numbers. -Each of the numbers is a fraction between 0 and 1, which indicates -a position in the document. 0 indicates the beginning of the document, -1 indicates the end, .333 indicates a position one third the way through -the document, and so on. -The first fraction indicates the first information in the document -that is visible in the window, and the second fraction indicates -the information just after the last portion that is visible. -The command is -then passed to the Tcl interpreter for execution. Typically the -\fB\-xscrollcommand\fR option consists of the path name of a scrollbar -widget followed by -.QW set , -e.g. -.QW ".x.scrollbar set" : -this will cause -the scrollbar to be updated whenever the view in the window changes. -If this option is not specified, then no command will be executed. -.OP \-yscrollcommand yScrollCommand ScrollCommand -Specifies the prefix for a command used to communicate with vertical -scrollbars. This option is treated in the same way as the -\fB\-xscrollcommand\fR option, except that it is used for vertical -scrollbars and is provided by widgets that support vertical scrolling. -See the description of \fB\-xscrollcommand\fR for details -on how this option is used. -.SH "SEE ALSO" -colors, cursors, font -.SH KEYWORDS -class, name, standard option, switch -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/pack-old.n b/tk8.6/doc/pack-old.n deleted file mode 100644 index 217dba9..0000000 --- a/tk8.6/doc/pack-old.n +++ /dev/null @@ -1,195 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH pack-old n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pack-old \- Obsolete syntax for packer geometry manager -.SH SYNOPSIS -\fBpack after \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack append \fIparent \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack before \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack unpack \fIwindow\fR -.BE -.SH DESCRIPTION -.PP -\fINote: this manual entry describes the syntax for the \fBpack\fI -command as it existed before Tk version 3.3. -Although this syntax continues to be supported for backward -compatibility, it is obsolete and should not be used anymore. -At some point in the future it may cease to be supported.\fR -.PP -The packer is a geometry manager that arranges the -children of a parent by packing them in order around the edges of -the parent. The first child is placed against one side of -the window, occupying the entire span of the window along that -side. This reduces the space remaining for other children as -if the side had been moved in by the size of the first child. -Then the next child is placed against one side of the remaining -cavity, and so on until all children have been placed or there -is no space left in the cavity. -.PP -The \fBbefore\fR, \fBafter\fR, and \fBappend\fR forms of the \fBpack\fR -command are used to insert one or more children into the packing order -for their parent. The \fBbefore\fR form inserts the children before -window \fIsibling\fR in the order; all of the other windows must be -siblings of \fIsibling\fR. The \fBafter\fR form inserts the windows -after \fIsibling\fR, and the \fBappend\fR form appends one or more -windows to the end of the packing order for \fIparent\fR. If a -\fIwindow\fR named in any of these commands is already packed in -its parent, it is removed from its current position in the packing -order and repositioned as indicated by the command. All of these -commands return an empty string as result. -.PP -The \fBunpack\fR form of the \fBpack\fR command removes \fIwindow\fR -from the packing order of its parent and unmaps it. After the -execution of this command the packer will no longer manage -\fIwindow\fR's geometry. -.PP -The placement of each child is actually a four-step process; -the \fIoptions\fR argument following each \fIwindow\fR consists of -a list of one or more fields that govern the placement of that -window. In the discussion below, the term \fIcavity\fR refers -to the space left in a parent when a particular child is placed -(i.e. all the space that was not claimed by earlier children in -the packing order). The term \fIparcel\fR refers to the space -allocated to a particular child; this is not necessarily the -same as the child window's final geometry. -.PP -The first step in placing a child is to determine which side of -the cavity it will lie against. Any one of the following options -may be used to specify a side: -.TP -\fBtop\fR -Position the child's parcel against the top of the cavity, -occupying the full width of the cavity. -.TP -\fBbottom\fR -Position the child's parcel against the bottom of the cavity, -occupying the full width of the cavity. -.TP -\fBleft\fR -Position the child's parcel against the left side of the cavity, -occupying the full height of the cavity. -.TP -\fBright\fR -Position the child's parcel against the right side of the cavity, -occupying the full height of the cavity. -.LP -At most one of these options should be specified for any given window. -If no side is specified, then the default is \fBtop\fR. -.PP -The second step is to decide on a parcel for the child. For \fBtop\fR -and \fBbottom\fR windows, the desired parcel width is normally the cavity -width and the desired parcel height is the window's requested height, -as passed to \fBTk_GeometryRequest\fR. For \fBleft\fR and \fBright\fR -windows, the desired parcel height is normally the cavity height and the -desired width is the window's requested width. However, extra -space may be requested for the window using any of the following -options: -.TP 12 -\fBpadx \fInum\fR -Add \fInum\fR pixels to the window's requested width before computing -the parcel size as described above. -.TP 12 -\fBpady \fInum\fR -Add \fInum\fR pixels to the window's requested height before computing -the parcel size as described above. -.TP 12 -\fBexpand\fR -This option requests that the window's parcel absorb any extra space left over -in the parent's cavity after packing all the children. -The amount of space left over depends on the sizes requested by the -other children, and may be zero. If several windows have all specified -\fBexpand\fR then the extra width will be divided equally among all the -\fBleft\fR and \fBright\fR windows that specified \fBexpand\fR and -the extra height will be divided equally among all the \fBtop\fR and -\fBbottom\fR windows that specified \fBexpand\fR. -.LP -If the desired width or height for a parcel is larger than the corresponding -dimension of the cavity, then the cavity's dimension is used instead. -.PP -The third step in placing the window is to decide on the window's -width and height. The default is for the window to receive either -its requested width and height or the those of the parcel, whichever -is smaller. If the parcel is larger than the window's requested -size, then the following options may be used to expand the -window to partially or completely fill the parcel: -.TP -\fBfill\fR -Set the window's size to equal the parcel size. -.TP -\fBfillx\fR -Increase the window's width to equal the parcel's width, but retain -the window's requested height. -.TP -\fBfilly\fR -Increase the window's height to equal the parcel's height, but retain -the window's requested width. -.PP -The last step is to decide the window's location within its parcel. -If the window's size equals the parcel's size, then the window simply -fills the entire parcel. If the parcel is larger than the window, -then one of -the following options may be used to specify where the window should -be positioned within its parcel: -.TP 15 -\fBframe center\fR -Center the window in its parcel. This is the default if no framing -option is specified. -.TP 15 -\fBframe n\fR -Position the window with its top edge centered on the top edge of -the parcel. -.TP 15 -\fBframe ne\fR -Position the window with its upper-right corner at the upper-right corner -of the parcel. -.TP 15 -\fBframe e\fR -Position the window with its right edge centered on the right edge of -the parcel. -.TP 15 -\fBframe se\fR -Position the window with its lower-right corner at the lower-right corner -of the parcel. -.TP 15 -\fBframe s\fR -Position the window with its bottom edge centered on the bottom edge of -the parcel. -.TP 15 -\fBframe sw\fR -Position the window with its lower-left corner at the lower-left corner -of the parcel. -.TP 15 -\fBframe w\fR -Position the window with its left edge centered on the left edge of -the parcel. -.TP 15 -\fBframe nw\fR -Position the window with its upper-left corner at the upper-left corner -of the parcel. -.PP -The packer manages the mapped/unmapped state of all the packed -children windows. It automatically maps the windows when it packs -them, and it unmaps any windows for which there was no space left -in the cavity. -.PP -The packer makes geometry requests on behalf of the parent windows -it manages. For each parent window it requests a size large enough -to accommodate all the options specified by all the packed children, -such that zero space would be leftover for \fBexpand\fR options. -.SH KEYWORDS -geometry manager, location, packer, parcel, size -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/pack.n b/tk8.6/doc/pack.n deleted file mode 100644 index 538af62..0000000 --- a/tk8.6/doc/pack.n +++ /dev/null @@ -1,283 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH pack n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pack \- Geometry manager that packs around edges of cavity -.SH SYNOPSIS -\fBpack \fIoption arg \fR?\fIarg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBpack\fR command is used to communicate with the packer, -a geometry manager that arranges the children of a parent by -packing them in order around the edges of the parent. -The \fBpack\fR command can have any of several forms, depending -on the \fIoption\fR argument: -.TP -\fBpack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -If the first argument to \fBpack\fR is a window name (any value -starting with -.QW . ), -then the command is processed in the same way as \fBpack configure\fR. -.TP -\fBpack configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -The arguments consist of the names of one or more slave windows -followed by pairs of arguments that specify how -to manage the slaves. -See \fBTHE PACKER ALGORITHM\fR below for details on how the options -are used by the packer. -The following options are supported: -.RS -.TP -\fB\-after \fIother\fR -\fIOther\fR must the name of another window. -Use its master as the master for the slaves, and insert -the slaves just after \fIother\fR in the packing order. -.TP -\fB\-anchor \fIanchor\fR -\fIAnchor\fR must be a valid anchor position such as \fBn\fR -or \fBsw\fR; it specifies where to position each slave in its -parcel. -Defaults to \fBcenter\fR. -.TP -\fB\-before \fIother\fR -\fIOther\fR must the name of another window. -Use its master as the master for the slaves, and insert -the slaves just before \fIother\fR in the packing order. -.TP -\fB\-expand \fIboolean\fR -Specifies whether the slaves should be expanded to consume -extra space in their master. -\fIBoolean\fR may have any proper boolean value, such as \fB1\fR -or \fBno\fR. -Defaults to 0. -.TP -\fB\-fill \fIstyle\fR -If a slave's parcel is larger than its requested dimensions, this -option may be used to stretch the slave. -\fIStyle\fR must have one of the following values: -.RS -.TP -\fBnone\fR -Give the slave its requested dimensions plus any internal padding -requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. -.TP -\fBx\fR -Stretch the slave horizontally to fill the entire width of its -parcel (except leave external padding as specified by \fB\-padx\fR). -.TP -\fBy\fR -Stretch the slave vertically to fill the entire height of its -parcel (except leave external padding as specified by \fB\-pady\fR). -.TP -\fBboth\fR -Stretch the slave both horizontally and vertically. -.RE -.TP -\fB\-in \fIother\fR -Insert the slave(s) at the end of the packing order for the master -window given by \fIother\fR. -.TP -\fB\-ipadx \fIamount\fR -\fIAmount\fR specifies how much horizontal internal padding to -leave on each side of the slave(s). -\fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. -It defaults to 0. -.TP -\fB\-ipady \fIamount\fR -\fIAmount\fR specifies how much vertical internal padding to -leave on each side of the slave(s). -\fIAmount\fR defaults to 0. -.TP -\fB\-padx \fIamount\fR -\fIAmount\fR specifies how much horizontal external padding to -leave on each side of the slave(s). \fIAmount\fR may be a list -of two values to specify padding for left and right separately. -\fIAmount\fR defaults to 0. -.TP -\fB\-pady \fIamount\fR -\fIAmount\fR specifies how much vertical external padding to -leave on each side of the slave(s). \fIAmount\fR may be a list -of two values to specify padding for top and bottom separately. -\fIAmount\fR defaults to 0. -.TP -\fB\-side \fIside\fR -Specifies which side of the master the slave(s) will be packed against. -Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. -Defaults to \fBtop\fR. -.LP -If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified -then each of the slaves will be inserted at the end of the packing list -for its parent unless it is already managed by the packer (in which -case it will be left where it is). -If one of these options is specified then all the slaves will be -inserted at the specified point. -If any of the slaves are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. -.RE -.TP -\fBpack forget \fIslave \fR?\fIslave ...\fR? -Removes each of the \fIslave\fRs from the packing order for its -master and unmaps their windows. -The slaves will no longer be managed by the packer. -.TP -\fBpack info \fIslave\fR -Returns a list whose elements are the current configuration state of -the slave given by \fIslave\fR in the same option-value form that -might be specified to \fBpack configure\fR. -The first two elements of the list are -.QW "\fB\-in \fImaster\fR" -where \fImaster\fR is the slave's master. -.TP -\fBpack propagate \fImaster\fR ?\fIboolean\fR? -If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR -then propagation is enabled for \fImaster\fR, which must be a window -name (see \fBGEOMETRY PROPAGATION\fR below). -If \fIboolean\fR has a false boolean value then propagation is -disabled for \fImaster\fR. -In either of these cases an empty string is returned. -If \fIboolean\fR is omitted then the command returns \fB0\fR or -\fB1\fR to indicate whether propagation is currently enabled -for \fImaster\fR. -Propagation is enabled by default. -.TP -\fBpack slaves \fImaster\fR -Returns a list of all of the slaves in the packing order for \fImaster\fR. -The order of the slaves in the list is the same as their order in -the packing order. -If \fImaster\fR has no slaves then an empty string is returned. -.SH "THE PACKER ALGORITHM" -.PP -For each master the packer maintains an ordered list of slaves -called the \fIpacking list\fR. -The \fB\-in\fR, \fB\-after\fR, and \fB\-before\fR configuration -options are used to specify the master for each slave and the slave's -position in the packing list. -If none of these options is given for a slave then the slave -is added to the end of the packing list for its parent. -.PP -The packer arranges the slaves for a master by scanning the -packing list in order. -At the time it processes each slave, a rectangular area within -the master is still unallocated. -This area is called the \fIcavity\fR; for the first slave it -is the entire area of the master. -.PP -For each slave the packer carries out the following steps: -.IP [1] -The packer allocates a rectangular \fIparcel\fR for the slave -along the side of the cavity given by the slave's \fB\-side\fR option. -If the side is top or bottom then the width of the parcel is -the width of the cavity and its height is the requested height -of the slave plus the \fB\-ipady\fR and \fB\-pady\fR options. -For the left or right side the height of the parcel is -the height of the cavity and the width is the requested width -of the slave plus the \fB\-ipadx\fR and \fB\-padx\fR options. -The parcel may be enlarged further because of the \fB\-expand\fR -option (see \fBEXPANSION\fR below) -.IP [2] -The packer chooses the dimensions of the slave. -The width will normally be the slave's requested width plus -twice its \fB\-ipadx\fR option and the height will normally be -the slave's requested height plus twice its \fB\-ipady\fR -option. -However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR -then the width of the slave is expanded to fill the width of the parcel, -minus twice the \fB\-padx\fR option. -If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR -then the height of the slave is expanded to fill the width of the parcel, -minus twice the \fB\-pady\fR option. -.IP [3] -The packer positions the slave over its parcel. -If the slave is smaller than the parcel then the \fB\-anchor\fR -option determines where in the parcel the slave will be placed. -If \fB\-padx\fR or \fB\-pady\fR is non-zero, then the given -amount of external padding will always be left between the -slave and the edges of the parcel. -.PP -Once a given slave has been packed, the area of its parcel -is subtracted from the cavity, leaving a smaller rectangular -cavity for the next slave. -If a slave does not use all of its parcel, the unused space -in the parcel will not be used by subsequent slaves. -If the cavity should become too small to meet the needs of -a slave then the slave will be given whatever space is -left in the cavity. -If the cavity shrinks to zero size, then all remaining slaves -on the packing list will be unmapped from the screen until -the master window becomes large enough to hold them again. -.SS "EXPANSION" -.PP -If a master window is so large that there will be extra space -left over after all of its slaves have been packed, then the -extra space is distributed uniformly among all of the slaves -for which the \fB\-expand\fR option is set. -Extra horizontal space is distributed among the expandable -slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR, -and extra vertical space is distributed among the expandable -slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. -.SS "GEOMETRY PROPAGATION" -.PP -The packer normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the \fBpack propagate\fR command may be used to -turn off propagation for one or more masters. -If propagation is disabled then the packer will not set -the requested width and height of the packer. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. -.SH "RESTRICTIONS ON MASTER WINDOWS" -.PP -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. -.SH "PACKING ORDER" -.PP -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave has not been packed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. -Or, you can use the \fBraise\fR and \fBlower\fR commands to change -the stacking order of either the master or the slave. -.SH EXAMPLE -.PP -.CS -# Make the widgets -label .t \-text "This widget is at the top" \-bg red -label .b \-text "This widget is at the bottom" \-bg green -label .l \-text "Left\enHand\enSide" -label .r \-text "Right\enHand\enSide" -text .mid -\&.mid insert end "This layout is like Java's BorderLayout" -# Lay them out -\fBpack\fR .t \-side top \-fill x -\fBpack\fR .b \-side bottom \-fill x -\fBpack\fR .l \-side left \-fill y -\fBpack\fR .r \-side right \-fill y -\fBpack\fR .mid \-expand 1 \-fill both -.CE -.SH "SEE ALSO" -grid(n), place(n) -.SH KEYWORDS -geometry manager, location, packer, parcel, propagation, size -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/palette.n b/tk8.6/doc/palette.n deleted file mode 100644 index 085c4c6..0000000 --- a/tk8.6/doc/palette.n +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_setPalette, tk_bisque \- Modify the Tk color palette -.SH SYNOPSIS -\fBtk_setPalette \fIbackground\fR -.sp -\fBtk_setPalette \fIname value \fR?\fIname value ...\fR? -.sp -\fBtk_bisque\fR -.BE -.SH DESCRIPTION -.PP -The \fBtk_setPalette\fR procedure changes the color scheme for Tk. -It does this by modifying the colors of existing widgets and by changing -the option database so that future widgets will use the new color scheme. -If \fBtk_setPalette\fR is invoked with a single argument, the -argument is the name of a color to use as the normal background -color; \fBtk_setPalette\fR will compute a complete color palette -from this background color. -Alternatively, the arguments to \fBtk_setPalette\fR may consist of any number -of \fIname\fR\-\fIvalue\fR pairs, where the first argument of the pair -is the name of an option in the Tk option database and the second -argument is the new value to use for that option. The following -database names are currently supported: -.DS -.ta 4c 8c -\fBactiveBackground\fR \fBforeground\fR \fBselectColor\fR -\fBactiveForeground\fR \fBhighlightBackground\fR \fBselectBackground\fR -\fBbackground\fR \fBhighlightColor\fR \fBselectForeground\fR -\fBdisabledForeground\fR \fBinsertBackground\fR \fBtroughColor\fR -.DE -\fBtk_setPalette\fR tries to compute reasonable defaults for any -options that you do not specify. You can specify options other -than the above ones and Tk will change those options on widgets as -well. This feature may be useful if you are using custom widgets with -additional color options. -.PP -Once it has computed the new value to use for each of the color options, -\fBtk_setPalette\fR scans the widget hierarchy to modify the options -of all existing widgets. For each widget, it checks to see if any -of the above options is defined for the widget. If so, and if the -option's current value is the default, then the value is changed; if -the option has a value other than the default, \fBtk_setPalette\fR -will not change it. The default for an option is the one provided by -the widget (\fB[lindex [$w configure $option] 3]\fR) unless -\fBtk_setPalette\fR has been run previously, in which case it is the -value specified in the previous invocation of \fBtk_setPalette\fR. -.PP -After modifying all the widgets in the application, \fBtk_setPalette\fR -adds options to the option database to change the defaults for -widgets created in the future. The new options are added at -priority \fBwidgetDefault\fR, so they will be overridden by options -from the .Xdefaults file or options specified on the command-line -that creates a widget. -.PP -The procedure \fBtk_bisque\fR is provided for backward compatibility: -it restores the application's colors to the light brown -.PQ bisque -color scheme used in Tk 3.6 and earlier versions. -.SH KEYWORDS -bisque, color, palette -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/panedwindow.n b/tk8.6/doc/panedwindow.n deleted file mode 100644 index 40997a9..0000000 --- a/tk8.6/doc/panedwindow.n +++ /dev/null @@ -1,347 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH panedwindow n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -panedwindow \- Create and manipulate 'panedwindow' split container widgets -.SH SYNOPSIS -\fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-borderwidth \-cursor -\-orient \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-handlepad handlePad HandlePad -When sash handles are drawn, specifies the distance from the top or -left end of the sash (depending on the orientation of the widget) at -which to draw the handle. May be any value accepted by \fBTk_GetPixels\fR. -.OP \-handlesize handleSize HandleSize -Specifies the side length of a sash handle. Handles are always -drawn as squares. May be any value accepted by \fBTk_GetPixels\fR. -.OP \-height height Height -Specifies a desired height for the overall panedwindow widget. May be any -value accepted by \fBTk_GetPixels\fR. If an empty string, the widget will be -made high enough to allow all contained widgets to have their natural height. -.OP \-opaqueresize opaqueResize OpaqueResize -Specifies whether panes should be resized as a sash is moved (true), -or if resizing should be deferred until the sash is placed (false). -In the latter case, a -.QW ghost -version of the sash is displayed during the resizing to show where the -panes will be resized to when releasing the mouse button. This -.QW ghost -version of the sash is the proxy. It's rendering can be configured -using the \fB-proxybackground\fR, \fB-proxyborderwidth\fR and -\fB-proxyrelief\fR options. -.OP \-proxybackground proxyBackground ProxyBackground -Background color to use when drawing the proxy. If an empty string, the -value of the \fB-background\fR option will be used. -.OP \-proxyborderwidth proxyBorderWidth ProxyBorderWidth -Specifies the borderwidth of the proxy. May be any value accepted by -\fBTk_GetPixels\fR. -.OP \-proxyrelief proxyRelief ProxyRelief -Relief to use when drawing the proxy. May be any of the standard Tk -relief values. If an empty string, the value of the \fB-sashrelief\fR -option will be used. -.OP \-sashcursor sashCursor SashCursor -Mouse cursor to use when over a sash. If null, -\fBsb_h_double_arrow\fR will be used for horizontal panedwindows, and -\fBsb_v_double_arrow\fR will be used for vertical panedwindows. -.OP \-sashpad sashPad SashPad -Specifies the amount of padding to leave of each side of a sash. May -be any value accepted by \fBTk_GetPixels\fR. -.OP \-sashrelief sashRelief SashRelief -Relief to use when drawing a sash. May be any of the standard Tk -relief values. -.OP \-sashwidth sashWidth SashWidth -Specifies the width of each sash. May be any value accepted by -\fBTk_GetPixels\fR. -.OP \-showhandle showHandle ShowHandle -Specifies whether sash handles should be shown. May be any valid Tcl -boolean value. -.OP \-width width Width -Specifies a desired width for the overall panedwindow widget. May be any -value accepted by \fBTk_GetPixels\fR. If an empty string, the widget will be -made wide enough to allow all contained widgets to have their natural width. -.BE -.SH DESCRIPTION -.PP -The \fBpanedwindow\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a panedwindow widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the panedwindow -such as its default background color and relief. The -\fBpanedwindow\fR command returns the path name of the new window. -.PP -A panedwindow widget contains any number of panes, arranged -horizontally or vertically, according to the value of the -\fB\-orient\fR option. Each pane contains one widget, and each pair of -panes is separated by a moveable (via mouse movements) sash. Moving a -sash causes the widgets on either side of the sash to be resized. -.SH "WIDGET COMMAND" -.PP -The \fBpanedwindow\fR command creates a new Tcl command whose name is -the same as the path name of the panedwindow's window. 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 -\fIPathName\fR is the name of the command, which is the same as -the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for panedwindow widgets: -.TP -\fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? -. -Add one or more windows to the panedwindow, each in a separate pane. -The arguments consist of the names of one or more windows -followed by pairs of arguments that specify how to manage the windows. -\fIOption\fR may have any of the values accepted by the -\fBconfigure\fR subcommand. -.TP -\fIpathName \fBcget \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 -\fBpanedwindow\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 \fBpanedwindow\fR command. -.TP -\fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? -. -Remove the pane containing \fIwindow\fR from the panedwindow. All -geometry management options for \fIwindow\fR will be forgotten. -.TP -\fIpathName \fBidentify \fIx y\fR -. -Identify the panedwindow component underneath the point given by -\fIx\fR and \fIy\fR, in window coordinates. If the point is over a -sash or a sash handle, the result is a two element list containing the -index of the sash or handle, and a word indicating whether it is over -a sash or a handle, such as {0 sash} or {2 handle}. If the point is -over any other part of the panedwindow, the result is an empty list. -.TP -\fIpathName \fBpanecget \fIwindow option\fR -. -Query a management option for \fIwindow\fR. \fIOption\fR may be any -value allowed by the \fBpaneconfigure\fR subcommand. -.TP -\fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Query or modify the management options for \fIwindow\fR. 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. The following options -are supported: -.RS -.TP -\fB\-after \fIwindow\fR -. -Insert the window after the window specified. \fIwindow\fR should be the -name of a window already managed by \fIpathName\fR. -.TP -\fB\-before \fIwindow\fR -. -Insert the window before the window specified. \fIwindow\fR should be -the name of a window already managed by \fIpathName\fR. -.TP -\fB\-height \fIsize\fR -. -Specify a height for the window. The height will be the outer -dimension of the window including its border, if any. If \fIsize\fR -is an empty string, or if \fB\-height\fR is not specified, then the -height requested internally by the window will be used initially; the -height may later be adjusted by the movement of sashes in the -panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. -.TP -\fB\-hide \fIboolean\fR -. -Controls the visibility of a pane. When the \fIboolean\fR is true -(according to \fBTcl_GetBoolean\fR) the pane will not be visible, but -it will still be maintained in the list of panes. -.TP -\fB\-minsize \fIn\fR -. -Specifies that the size of the window cannot be made less than -\fIn\fR. This constraint only affects the size of the widget in the -paned dimension \(em the x dimension for horizontal panedwindows, the y -dimension for vertical panedwindows. May be any value accepted by -\fBTk_GetPixels\fR. -.TP -\fB\-padx \fIn\fR -. -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the X-direction. The value may -have any of the forms accepted by \fBTk_GetPixels\fR. -.TP -\fB\-pady \fIn\fR -. -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the Y-direction. The value may -have any of the forms accepted by \fBTk_GetPixels\fR. -.TP -\fB\-sticky \fIstyle\fR -. -If a window's pane is larger than the requested dimensions of the -window, this option may be used to position (or stretch) the window -within its pane. \fIStyle\fR is a string that contains zero or more -of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. The string -can optionally contains spaces or commas, but they are ignored. Each -letter refers to a side (north, south, east, or west) that the window -will -.QW stick -to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) -are specified, the window will be stretched to fill the entire height -(or width) of its cavity. -.TP -\fB\-stretch \fIwhen\fR -. -Controls how extra space is allocated to each of the panes. -\fIWhen\fR is one of \fBalways\fR, \fBfirst\fR, \fBlast\fR, -\fBmiddle\fR, and \fBnever\fR. -The panedwindow will calculate the required size of all its panes. Any -remaining (or deficit) space will be distributed to those panes marked -for stretching. The space will be distributed based on each panes -current ratio of the whole. The \fIwhen\fR values have the following -definition: -.RS -.TP -\fBalways\fR -. -This pane will always stretch. -.TP -\fBfirst\fR -. -Only if this pane is the first pane (left-most or top-most) will it -stretch. -.TP -\fBlast\fR -. -Only if this pane is the last pane (right-most or bottom-most) will it -stretch. This is the default value. -.TP -\fBmiddle\fR -. -Only if this pane is not the first or last pane will it stretch. -.TP -\fBnever\fR -. -This pane will never stretch. -.RE -.TP -\fB\-width \fIsize\fR -. -Specify a width for the window. The width will be the outer -dimension of the window including its border, if any. If \fIsize\fR -is an empty string, or if \fB\-width\fR is not specified, then the -width requested internally by the window will be used initially; the -width may later be adjusted by the movement of sashes in the -panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. -.RE -.TP -\fIpathName \fBpanes\fR -. -Returns an ordered list of the widgets managed by \fIpathName\fR. -.TP -\fIpathName \fBproxy \fR?\fIargs\fR? -. -This command is used to query and change the position of the sash -proxy, used for rubberband-style pane resizing. It can take any of -the following forms: -.RS -.TP -\fIpathName \fBproxy coord\fR -. -Return a list containing the x and y coordinates of the most recent -proxy location. -.TP -\fIpathName \fBproxy forget\fR -. -Remove the proxy from the display. -.TP -\fIpathName \fBproxy place \fIx y\fR -. -Place the proxy at the given \fIx\fR and \fIy\fR coordinates. -.RE -.TP -\fIpathName \fBsash \fR?\fIargs\fR? -This command is used to query and change the position of sashes in the -panedwindow. It can take any of the following forms: -.RS -.TP -\fIpathName \fBsash coord \fIindex\fR -. -Return the current x and y coordinate pair for the sash given by -\fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than -the number of panes in the panedwindow. The coordinates given are -those of the top left corner of the region containing the sash. -.TP -\fIpathName \fBsash dragto \fIindex x y\fR -. -This command computes the difference between the given coordinates and the -coordinates given to the last \fBsash mark\fR command for the given -sash. It then moves that sash the computed difference. The return -value is the empty string. -.TP -\fIpathName \fBsash mark \fIindex x y\fR -. -Records \fIx\fR and \fIy\fR for the sash given by \fIindex\fR; used in -conjunction with later \fBsash dragto\fR commands to move the sash. -.TP -\fIpathName \fBsash place \fIindex x y\fR -. -Place the sash given by \fIindex\fR at the given coordinates. -.RE -.SH "RESIZING PANES" -.PP -A pane is resized by grabbing the sash (or sash handle if present) and -dragging with the mouse. This is accomplished via mouse motion -bindings on the widget. When a sash is moved, the sizes of the panes -on each side of the sash, and thus the widgets in those panes, are -adjusted. -.PP -When a pane is resized from outside (e.g. it is packed to expand and -fill, and the containing toplevel is resized), space is added to the final -(rightmost or bottommost) pane in the window. -.PP -Unlike slave windows managed by e.g. pack or grid, the panes managed by a -panedwindow do not change width or height to accomodate changes in the -requested widths or heights of the panes, once these have become mapped. -Therefore it may be advisable, particularly when creating layouts -interactively, to not add a pane to the panedwindow widget until after the -geometry requests of that pane has been finalized (i.e., all components of -the pane inserted, all options affecting geometry set to their proper -values, etc.). -.SH "SEE ALSO" -ttk::panedwindow(n) -.SH KEYWORDS -panedwindow, widget, geometry management -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/photo.n b/tk8.6/doc/photo.n deleted file mode 100644 index 0fe0c61..0000000 --- a/tk8.6/doc/photo.n +++ /dev/null @@ -1,543 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Australian National University -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), -'\" Department of Computer Science, -'\" Australian National University. -'\" -.TH photo n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -photo \- Full-color images -.SH SYNOPSIS -.nf -\fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? - -\fIimageName \fBblank\fR -\fIimageName \fBcget \fIoption\fR -\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -\fIimageName \fBcopy \fIsourceImage\fR ?\fIoption value(s) ...\fR? -\fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? -\fIimageName \fBget \fIx y\fR -\fIimageName \fBput \fIdata\fR ?\fIoption value(s) ...\fR? -\fIimageName \fBread \fIfilename\fR ?\fIoption value(s) ...\fR? -\fIimageName \fBredither\fR -\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? -\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? -.fi -.BE -.SH DESCRIPTION -.PP -A photo is an image whose pixels can display any color or be -transparent. A photo image is stored internally in full color (32 -bits per pixel), and is displayed using dithering if necessary. Image -data for a photo image can be obtained from a file or a string, or it -can be supplied from -C code through a procedural interface. At present, only -.VS 8.6 -PNG, -.VE 8.6 -GIF and PPM/PGM -formats are supported, but an interface exists to allow additional -image file formats to be added easily. A photo image is transparent -in regions where no image data has been supplied -or where it has been set transparent by the \fBtransparency set\fR -subcommand. -.SH "CREATING PHOTOS" -.PP -Like all images, photos are created using the \fBimage create\fR -command. -Photos support the following \fIoptions\fR: -.TP -\fB\-data \fIstring\fR -. -Specifies the contents of the image as a string. The string should -contain binary data or, for some formats, base64-encoded data (this is -currently guaranteed to be supported for PNG and GIF images). The -format of the -string must be one of those for which there is an image file format -handler that will accept string data. If both the \fB\-data\fR -and \fB\-file\fR options are specified, the \fB\-file\fR option takes -precedence. -.TP -\fB\-format \fIformat-name\fR -. -Specifies the name of the file format for the data specified with the -\fB\-data\fR or \fB\-file\fR option. -.TP -\fB\-file \fIname\fR -. -\fIname\fR gives the name of a file that is to be read to supply data -for the photo image. The file format must be one of those for which -there is an image file format handler that can read data. -.TP -\fB\-gamma \fIvalue\fR -. -Specifies that the colors allocated for displaying this image in a -window should be corrected for a non-linear display with the specified -gamma exponent value. (The intensity produced by most -CRT displays is a power function of the input value, to a good -approximation; gamma is the exponent and is typically around 2). -The value specified must be greater than zero. The default -value is one (no correction). In general, values greater than one -will make the image lighter, and values less than one will make it -darker. -.TP -\fB\-height \fInumber\fR -. -Specifies the height of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink vertically to fit the data stored in it. -.TP -\fB\-palette \fIpalette-spec\fR -. -Specifies the resolution of the color cube to be allocated for -displaying this image, and thus the number of colors used from the -colormaps of the windows where it is displayed. The -\fIpalette-spec\fR string may be either a single decimal number, -specifying the number of shades of gray to use, or three decimal -numbers separated by slashes (/), specifying the number of shades of -red, green and blue to use, respectively. If the first form (a single -number) is used, the image will be displayed in monochrome (i.e., -grayscale). -.TP -\fB\-width \fInumber\fR -. -Specifies the width of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink horizontally to fit the data stored in it. -.SH "IMAGE COMMAND" -.PP -When a photo 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. -.PP -Those options that write data to the image generally expand the size -of the image, if necessary, to accommodate the data written to the -image, unless the user has specified non-zero values for the -\fB\-width\fR and/or \fB\-height\fR configuration options, in which -case the width and/or height, respectively, of the image will not be -changed. -.PP -The following commands are possible for photo images: -.TP -\fIimageName \fBblank\fR -. -Blank the image; that is, set the entire image to have no data, so it -will be displayed as transparent, and the background of whatever -window it is displayed in will show through. -.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\fR \fBphoto\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\fR \fBphoto\fR command. -.TP -\fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? -. -Copies a region from the image called \fIsourceImage\fR (which must -be a photo image) to the image called \fIimageName\fR, possibly with -pixel zooming and/or subsampling. If no options are specified, this -command copies the whole of \fIsourceImage\fR into \fIimageName\fR, -starting at coordinates (0,0) in \fIimageName\fR. The following -options may be specified: -.RS -.TP -\fB\-from \fIx1 y1 x2 y2\fR -. -Specifies a rectangular sub-region of the source image to be copied. -(\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of -the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the -default value is the bottom-right corner of the source image. The -pixels copied will include the left and top edges of the specified -rectangle but not the bottom or right edges. If the \fB\-from\fR -option is not given, the default is the whole source image. -.TP -\fB\-to \fIx1 y1 x2 y2\fR -. -Specifies a rectangular sub-region of the destination image to be -affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite -corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, -the default value is (\fIx1,y1\fR) plus the size of the source -region (after subsampling and zooming, if specified). If \fIx2\fR and -\fIy2\fR are specified, the source region will be replicated if -necessary to fill the destination region in a tiled fashion. -.TP -\fB\-shrink\fR -. -Specifies that the size of the destination image should be reduced, if -necessary, so that the region being copied into is at the bottom-right -corner of the image. This option will not affect the width or height -of the image if the user has specified a non-zero value for the -\fB\-width\fR or \fB\-height\fR configuration option, respectively. -.TP -\fB\-zoom \fIx y\fR -. -Specifies that the source region should be magnified by a factor of -\fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR -is not given, the default value is the same as \fIx\fR. With this -option, each pixel in the source image will be expanded into a block -of \fIx\fR x \fIy\fR pixels in the destination image, all the same -color. \fIx\fR and \fIy\fR must be greater than 0. -.TP -\fB\-subsample \fIx y\fR -. -Specifies that the source image should be reduced in size by using -only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in -the Y direction. Negative values will cause the image to be flipped -about the Y or X axes, respectively. If \fIy\fR is not given, the -default value is the same as \fIx\fR. -.TP -\fB\-compositingrule \fIrule\fR -. -Specifies how transparent pixels in the source image are combined with -the destination image. When a compositing rule of \fIoverlay\fR is -set, the old contents of the destination image are visible, as if the -source image were printed on a piece of transparent film and placed -over the top of the destination. When a compositing rule of \fIset\fR -is set, the old contents of the destination image are discarded and -the source image is used as-is. The default compositing rule is -\fIoverlay\fR. -.RE -.TP -\fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? -. -Returns image data in the form of a string. The following options -may be specified: -.RS -.TP -\fB\-background\fI color\fR -. -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. -.TP -\fB\-format\fI format-name\fR -. -Specifies the name of the image file format handler to be used. -Specifically, this subcommand searches -for the first handler whose name matches an initial substring of -\fIformat-name\fR and which has the capability to write a string -containing this image data. -If this option is not given, this subcommand uses a format that -consists of a list (one element per row) of lists (one element per -pixel/column) of colors in -.QW \fB#\fIrrggbb\fR -format (where \fIrr\fR is a pair of hexadecimal digits for the red -channel, \fIgg\fR for green, and \fIbb\fR for blue). -.TP -\fB\-from \fIx1 y1 x2 y2\fR -. -Specifies a rectangular region of \fIimageName\fR to be returned. -If only \fIx1\fR and \fIy1\fR are specified, the region -extends from \fI(x1,y1)\fR to the bottom-right corner of -\fIimageName\fR. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region, including x1,y1 -and excluding x2,y2. The default, if this option is not given, is the -whole image. -.TP -\fB\-grayscale\fR -. -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. -.RE -.TP -\fIimageName \fBget\fR \fIx y\fR -. -Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the -image as a list of three integers between 0 and 255, representing the -red, green and blue components respectively. -.TP -\fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR? -. -Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. -This command first searches the list of image file format handlers for -a handler that can interpret the data in \fIdata\fR, and then reads -the image encoded within into \fIimageName\fR (the destination image). -If \fIdata\fR does not match any known format, an attempt to interpret -it as a (top-to-bottom) list of scan-lines is made, with each -scan-line being a (left-to-right) list of pixel colors (see -\fBTk_GetColor\fR for a description of valid colors.) Every scan-line -must be of the same length. Note that when \fIdata\fR is a single -color name, you are instructing Tk to fill a rectangular region with -that color. The following options may be specified: -.RS -.TP -\fB\-format \fIformat-name\fR -. -Specifies the format of the image data in \fIdata\fR. -Specifically, only image file format handlers whose names begin with -\fIformat-name\fR will be used while searching for an image data -format handler to read the data. -.TP -\fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? -. -Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR) -of the region of \fIimageName\fR into which the image data will be -copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given -and \fIdata\fR is not large enough to cover the rectangle specified by -this option, the image data extracted will be tiled so it covers the -entire destination rectangle. Note that if \fIdata\fR specifies a -single color value, then a region extending to the bottom-right corner -represented by (\fIx2\fR,\fIy2\fR) will be filled with that color. -.RE -.TP -\fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? -. -Reads image data from the file named \fIfilename\fR into the image. -This command first searches the list of -image file format handlers for a handler that can interpret the data -in \fIfilename\fR, and then reads the image in \fIfilename\fR into -\fIimageName\fR (the destination image). The following options may be -specified: -.RS -.TP -\fB\-format \fIformat-name\fR -. -Specifies the format of the image data in \fIfilename\fR. -Specifically, only image file format handlers whose names begin with -\fIformat-name\fR will be used while searching for an image data -format handler to read the data. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -. -Specifies a rectangular sub-region of the image file data to be copied -to the destination image. If only \fIx1\fR and \fIy1\fR are -specified, the region extends from (\fIx1,y1\fR) to the bottom-right -corner of the image in the image file. If all four coordinates are -specified, they specify diagonally opposite corners or the region. -The default, if this option is not specified, is the whole of the -image in the image file. -.TP -\fB\-shrink\fR -. -If this option, the size of \fIimageName\fR will be reduced, if -necessary, so that the region into which the image file data are read -is at the bottom-right corner of the \fIimageName\fR. This option -will not affect the width or height of the image if the user has -specified a non-zero value for the \fB\-width\fR or \fB\-height\fR -configuration option, respectively. -.TP -\fB\-to \fIx y\fR -. -Specifies the coordinates of the top-left corner of the region of -\fIimageName\fR into which data from \fIfilename\fR are to be read. -The default is (0,0). -.RE -.TP -\fIimageName \fBredither\fR -. -The dithering algorithm used in displaying photo images propagates -quantization errors from one pixel to its neighbors. -If the image data for \fIimageName\fR is supplied in pieces, the -dithered image may not be exactly correct. Normally the difference is -not noticeable, but if it is a problem, this command can be used to -recalculate the dithered image in each window where the image is -displayed. -.TP -\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? -. -Allows examination and manipulation of the transparency information in -the photo image. Several subcommands are available: -.RS -.TP -\fIimageName \fBtransparency get \fIx y\fR -. -Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is -transparent. -.TP -\fIimageName \fBtransparency set \fIx y boolean\fR -. -Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is -true, and makes that pixel opaque otherwise. -.RE -.TP -\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? -. -Writes image data from \fIimageName\fR to a file named \fIfilename\fR. -The following options may be specified: -.RS -.TP -\fB\-background\fI color\fR -. -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. -.TP -\fB\-format\fI format-name\fR -. -Specifies the name of the image file format handler to be used to -write the data to the file. Specifically, this subcommand searches -for the first handler whose name matches an initial substring of -\fIformat-name\fR and which has the capability to write an image -file. If this option is not given, the format is guessed from -the file extension. If that cannot be determined, this subcommand -uses the first handler that has the capability to write an image file. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -. -Specifies a rectangular region of \fIimageName\fR to be written to the -image file. If only \fIx1\fR and \fIy1\fR are specified, the region -extends from \fI(x1,y1)\fR to the bottom-right corner of -\fIimageName\fR. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region. The default, -if this option is not given, is the whole image. -.TP -\fB\-grayscale\fR -. -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. -.RE -.SH "IMAGE FORMATS" -.PP -The photo image code is structured to allow handlers for additional -image file formats to be added easily. The photo image code maintains -a list of these handlers. Handlers are added to the list by -registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The -standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF -formats, which are automatically registered on initialization. -.PP -When reading an image file or processing -string data specified with the \fB\-data\fR configuration option, the -photo image code invokes each handler in turn until one is -found that claims to be able to read the data in the file or string. -Usually this will find the correct handler, but if it does not, the -user may give a format name with the \fB\-format\fR option to specify -which handler to use. In fact the photo image code will try those -handlers whose names begin with the string specified for the -\fB\-format\fR option (the comparison is case-insensitive). For -example, if the user specifies \fB\-format gif\fR, then a handler -named GIF87 or GIF89 may be invoked, but a handler -named JPEG may not (assuming that such handlers had been -registered). -.PP -When writing image data to a file, the processing of the -\fB\-format\fR option is slightly different: the string value given -for the \fB\-format\fR option must begin with the complete name of the -requested handler, and may contain additional information following -that, which the handler can use, for example, to specify which variant -to use of the formats supported by the handler. -Note that not all image handlers may support writing transparency data -to a file, even where the target image format does. -.SS "FORMAT SUBOPTIONS" -.PP -.VS 8.6 -Some image formats support sub-options, which are specified at the time that -the image is loaded using additional words in the \fB\-format\fR option. At -the time of writing, the following are supported: -.TP -\fBgif \-index\fI indexValue\fR -. -When parsing a multi-part GIF image, Tk normally only accesses the first -image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value -may be used instead. The \fIindexValue\fR must be an integer from 0 up to the -number of image parts in the GIF data. -.TP -\fBpng \-alpha\fI alphaValue\fR -. -An additional alpha filtering for the overall image, which allows the -background on which the image is displayed to show through. This usually also -has the effect of desaturating the image. The \fIalphaValue\fR must be between -0.0 and 1.0. -.VE 8.6 -.SH "COLOR ALLOCATION" -.PP -When a photo image is displayed in a window, the photo image code -allocates colors to use to display the image and dithers the image, if -necessary, to display a reasonable approximation to the image using -the colors that are available. The colors are allocated as a color -cube, that is, the number of colors allocated is the product of the -number of shades of red, green and blue. -.PP -Normally, the number of -colors allocated is chosen based on the depth of the window. For -example, in an 8-bit PseudoColor window, the photo image code will -attempt to allocate seven shades of red, seven shades of green and -four shades of blue, for a total of 198 colors. In a 1-bit StaticGray -(monochrome) window, it will allocate two colors, black and white. In -a 24-bit DirectColor or TrueColor window, it will allocate 256 shades -each of red, green and blue. Fortunately, because of the way that -pixel values can be combined in DirectColor and TrueColor windows, -this only requires 256 colors to be allocated. If not all of the -colors can be allocated, the photo image code reduces the number of -shades of each primary color and tries again. -.PP -The user can exercise some control over the number of colors that a -photo image uses with the \fB\-palette\fR configuration option. If -this option is used, it specifies the maximum number of shades of -each primary color to try to allocate. It can also be used to force -the image to be displayed in shades of gray, even on a color display, -by giving a single number rather than three numbers separated by -slashes. -.SH CREDITS -.PP -The photo image type was designed and implemented by Paul Mackerras, -based on his earlier photo widget and some suggestions from -John Ousterhout. -.SH EXAMPLE -.PP -Load an image from a file and tile it to the size of a window, which -is useful for producing a tiled background: -.PP -.CS -# These lines should be called once -\fBimage create photo\fR untiled \-file "theFile.ppm" -\fBimage create photo\fR tiled - -# These lines should be called whenever .someWidget changes -# size; a <Configure> binding is useful here -set width [winfo width .someWidget] -set height [winfo height .someWidget] -tiled \fBcopy\fR untiled \-to 0 0 $width $height \-shrink -.CE -.PP -.VS 8.6 -The PNG image loader allows the application of an additional alpha factor -during loading, which is useful for generating images suitable for disabled -buttons: -.PP -.CS -\fBimage create photo\fR icon \-file "icon.png" -\fBimage create photo\fR iconDisabled \-file "icon.png" \e - \-format "png \-alpha 0.5" -button .b \-image icon \-disabledimage iconDisabled -.CE -.VE 8.6 -.SH "SEE ALSO" -image(n) -.SH KEYWORDS -photo, image, color -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/place.n b/tk8.6/doc/place.n deleted file mode 100644 index 3a092c2..0000000 --- a/tk8.6/doc/place.n +++ /dev/null @@ -1,255 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH place n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -place \- Geometry manager for fixed or rubber-sheet placement -.SH SYNOPSIS -\fBplace \fIoption arg \fR?\fIarg ...\fR? -.BE -.SH DESCRIPTION -.PP -The placer is a geometry manager for Tk. -It provides simple fixed placement of windows, where you specify -the exact size and location of one window, called the \fIslave\fR, -within another window, called the \fImaster\fR. -The placer also provides rubber-sheet placement, where you specify the -size and location of the slave in terms of the dimensions of -the master, so that the slave changes size and location -in response to changes in the size of the master. -Lastly, the placer allows you to mix these styles of placement so -that, for example, the slave has a fixed width and height but is -centered inside the master. -.PP -.TP -\fBplace \fIwindow option value \fR?\fIoption value ...\fR? -Arrange for the placer to manage the geometry of a slave whose -pathName is \fIwindow\fR. The remaining arguments consist of one or -more \fIoption\-value\fR pairs that specify the way in which -\fIwindow\fR's geometry is managed. \fIOption\fR may have any of the -values accepted by the \fBplace configure\fR command. -.TP -\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the geometry options of the slave given by -\fIwindow\fR. If no \fIoption\fR is specified, this command returns a -list describing the available options (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. -.RS -.PP -The following \fIoption\-value\fR pairs are supported: -.TP -\fB\-anchor \fIwhere\fR -\fIWhere\fR specifies which point of \fIwindow\fR is to be positioned -at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, -\fB\-relx\fR, and \fB\-rely\fR options. -The anchor point is in terms of the outer area of \fIwindow\fR -including its border, if any. -Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of -\fIwindow\fR's border will appear at the given (x,y) location -in the master. -The anchor position defaults to \fBnw\fR. -.TP -\fB\-bordermode \fImode\fR -\fIMode\fR determines the degree to which borders within the -master are used in determining the placement of the slave. -The default and most common value is \fBinside\fR. -In this case the placer considers the area of the master to -be the innermost area of the master, inside any border: -an option of \fB\-x 0\fR corresponds to an x-coordinate just -inside the border and an option of \fB\-relwidth 1.0\fR -means \fIwindow\fR will fill the area inside the master's -border. -.RS -.PP -If \fImode\fR is \fBoutside\fR then the placer considers -the area of the master to include its border; -this mode is typically used when placing \fIwindow\fR -outside its master, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. -Lastly, \fImode\fR may be specified as \fBignore\fR, in which -case borders are ignored: the area of the master is considered -to be its official X area, which includes any internal border but -no external border. A bordermode of \fBignore\fR is probably -not very useful. -.RE -.TP -\fB\-height \fIsize\fR -\fISize\fR specifies the height for \fIwindow\fR in screen units -(i.e. any of the forms accepted by \fBTk_GetPixels\fR). -The height will be the outer dimension of \fIwindow\fR including its -border, if any. -If \fIsize\fR is an empty string, or if no \fB\-height\fR or -\fB\-relheight\fR option is specified, then the height requested -internally by the window will be used. -.TP -\fB\-in \fImaster\fR -\fIMaster\fR specifies the path name of the window relative -to which \fIwindow\fR is to be placed. -\fIMaster\fR must either be \fIwindow\fR's parent or a descendant -of \fIwindow\fR's parent. -In addition, \fImaster\fR and \fIwindow\fR must both be descendants -of the same top-level window. -These restrictions are necessary to guarantee -that \fIwindow\fR is visible whenever \fImaster\fR is visible. -If this option is not specified then the master defaults to -\fIwindow\fR's parent. -.TP -\fB\-relheight \fIsize\fR -\fISize\fR specifies the height for \fIwindow\fR. -In this case the height is specified as a floating-point number -relative to the height of the master: 0.5 means \fIwindow\fR will -be half as high as the master, 1.0 means \fIwindow\fR will have -the same height as the master, and so on. -If both \fB\-height\fR and \fB\-relheight\fR are specified for a slave, -their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR -makes the slave 2 pixels shorter than the master. -.TP -\fB\-relwidth \fIsize\fR -\fISize\fR specifies the width for \fIwindow\fR. -In this case the width is specified as a floating-point number -relative to the width of the master: 0.5 means \fIwindow\fR will -be half as wide as the master, 1.0 means \fIwindow\fR will have -the same width as the master, and so on. -If both \fB\-width\fR and \fB\-relwidth\fR are specified for a slave, -their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR -makes the slave 5 pixels wider than the master. -.TP -\fB\-relx \fIlocation\fR -\fILocation\fR specifies the x-coordinate within the master window -of the anchor point for \fIwindow\fR. -In this case the location is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the left edge -of the master and 1.0 corresponds to the right edge of the master. -\fILocation\fR need not be in the range 0.0\-1.0. -If both \fB\-x\fR and \fB\-relx\fR are specified for a slave -then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR -positions the left edge of the slave 2 pixels to the left of the -center of its master. -.TP -\fB\-rely \fIlocation\fR -\fILocation\fR specifies the y-coordinate within the master window -of the anchor point for \fIwindow\fR. -In this case the value is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the top edge -of the master and 1.0 corresponds to the bottom edge of the master. -\fILocation\fR need not be in the range 0.0\-1.0. -If both \fB\-y\fR and \fB\-rely\fR are specified for a slave -then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR -positions the top edge of the slave 3 pixels below the -center of its master. -.TP -\fB\-width \fIsize\fR -\fISize\fR specifies the width for \fIwindow\fR in screen units -(i.e. any of the forms accepted by \fBTk_GetPixels\fR). -The width will be the outer width of \fIwindow\fR including its -border, if any. -If \fIsize\fR is an empty string, or if no \fB\-width\fR -or \fB\-relwidth\fR option is specified, then the width requested -internally by the window will be used. -.TP -\fB\-x \fIlocation\fR -\fILocation\fR specifies the x-coordinate within the master window -of the anchor point for \fIwindow\fR. -The location is specified in screen units (i.e. any of the forms -accepted by \fBTk_GetPixels\fR) and need not lie within the bounds -of the master window. -.TP -\fB\-y \fIlocation\fR -\fILocation\fR specifies the y-coordinate within the master window -of the anchor point for \fIwindow\fR. -The location is specified in screen units (i.e. any of the forms -accepted by \fBTk_GetPixels\fR) and need not lie within the bounds -of the master window. -.PP -If the same value is specified separately with -two different options, such as \fB\-x\fR and \fB\-relx\fR, then -the most recent option is used and the older one is ignored. -.RE -.TP -\fBplace forget \fIwindow\fR -Causes the placer to stop managing the geometry of \fIwindow\fR. As a -side effect of this command \fIwindow\fR will be unmapped so that it -does not appear on the screen. If \fIwindow\fR is not currently managed -by the placer then the command has no effect. This command returns an -empty string. -.TP -\fBplace info \fIwindow\fR -Returns a list giving the current configuration of \fIwindow\fR. -The list consists of \fIoption\-value\fR pairs in exactly the -same form as might be specified to the \fBplace configure\fR -command. -.TP -\fBplace slaves \fIwindow\fR -Returns a list of all the slave windows for which \fIwindow\fR is the master. -If there are no slaves for \fIwindow\fR then an empty string is returned. -.PP -If the configuration of a window has been retrieved with -\fBplace info\fR, that configuration can be restored later by -first using \fBplace forget\fR to erase any existing information -for the window and then invoking \fBplace configure\fR with -the saved information. -.SH "FINE POINTS" -.PP -It is not necessary for the master window to be the parent -of the slave window. -This feature is useful in at least two situations. -First, for complex window layouts it means you can create a -hierarchy of subwindows whose only purpose -is to assist in the layout of the parent. -The -.QW "real children" -of the parent (i.e. the windows that -are significant for the application's user interface) can be -children of the parent yet be placed inside the windows -of the geometry-management hierarchy. -This means that the path names of the -.QW "real children" -do not reflect the geometry-management hierarchy and users -can specify options for the real children -without being aware of the structure of the geometry-management -hierarchy. -.PP -A second reason for having a master different than the slave's -parent is to tie two siblings together. -For example, the placer can be used to force a window always to -be positioned centered just below one of its -siblings by specifying the configuration -.CS -\fB\-in \fIsibling\fB \-relx 0.5 \-rely 1.0 \-anchor n \-bordermode outside\fR -.CE -Whenever the sibling is repositioned in the future, the slave -will be repositioned as well. -.PP -Unlike many other geometry managers (such as the packer) -the placer does not make any attempt to manipulate the geometry of -the master windows or the parents of slave windows (i.e. it does not -set their requested sizes). -To control the sizes of these windows, make them windows like -frames and canvases that provide configuration options for this purpose. -.SH EXAMPLE -.PP -Make the label occupy the middle bit of the toplevel, no matter how it -is resized: -.CS -label .l \-text "In the\enMiddle!" \-bg black \-fg white -\fBplace\fR .l \-relwidth .3 \-relx .35 \-relheight .3 \-rely .35 -.CE -.SH "SEE ALSO" -grid(n), pack(n) -.SH KEYWORDS -geometry manager, height, location, master, place, rubber sheet, slave, width -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/popup.n b/tk8.6/doc/popup.n deleted file mode 100644 index 0d32362..0000000 --- a/tk8.6/doc/popup.n +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_popup n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_popup \- Post a popup menu -.SH SYNOPSIS -\fBtk_popup \fImenu x y \fR?\fIentry\fR? -.BE -.SH DESCRIPTION -.PP -This procedure posts a menu at a given position on the screen and -configures Tk so that the menu and its cascaded children can be -traversed with the mouse or the keyboard. -\fIMenu\fR is the name of a menu widget and \fIx\fR and \fIy\fR -are the root coordinates at which to display the menu. -If \fIentry\fR is omitted or an empty string, the -menu's upper left corner is positioned at the given point. -Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and -the menu will be positioned so that the entry is positioned over -the given point. -.SH EXAMPLE -.PP -How to attach a simple popup menu to a widget. -.CS -# Create a menu -set m [menu .popupMenu] -$m add command \-label "Example 1" \-command bell -$m add command \-label "Example 2" \-command bell - -# Create something to attach it to -pack [label .l \-text "Click me!"] - -# Arrange for the menu to pop up when the label is clicked -bind .l <1> {\fBtk_popup\fR .popupMenu %X %Y} -.CE -.SH "SEE ALSO" -bind(n), menu(n), tk_optionMenu(n) -.SH KEYWORDS -menu, popup -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/radiobutton.n b/tk8.6/doc/radiobutton.n deleted file mode 100644 index fceb1ec..0000000 --- a/tk8.6/doc/radiobutton.n +++ /dev/null @@ -1,265 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH radiobutton n 4.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -radiobutton \- Create and manipulate 'radiobutton' pick-one widgets -.SH SYNOPSIS -\fBradiobutton\fR \fIpathName \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 \fB\-relief\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 Align-Left, Align-Right, and Center radiobuttons on the toolbar of a -word-processor, for example. -.OP \-overrelief overRelief OverRelief -Specifies an alternative relief for the radiobutton, 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 radiobutton. -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 \fB\-indicatoron\fR is false, this color is used as the background -for the entire widget, in place of \fB\-background\fR or \fB\-activeBackground\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 \fB\-image\fR option) -when the radiobutton is selected. -This option is ignored unless the \fB\-image\fR option has been -specified. -.OP \-state state State -Specifies one of three states for the radiobutton: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the radiobutton is displayed using the -\fB\-foreground\fR and \fB\-background\fR options. The active state is -typically used when the pointer is over the radiobutton. In active state -the radiobutton is displayed using the \fB\-activeforeground\fR and -\fB\-activebackground\fR options. Disabled state means that the radiobutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fB\-disabledforeground\fR and -\fB\-background\fR options determine how the radiobutton is displayed. -.OP \-tristateimage tristateImage TristateImage -Specifies an image to display (in place of the \fB\-image\fR option) -when the radiobutton is selected. -This option is ignored unless the \fB\-image\fR option has been -specified. -.OP \-tristatevalue tristateValue Value -Specifies the value that causes the radiobutton to display the multi-value -selection, also known as the tri-state mode. Defaults to -.QW "" . -.OP \-value value Value -Specifies value to store in the button's associated variable whenever -this button is selected. -.OP \-variable variable Variable -Specifies the name of a global variable to set whenever this button is -selected. Changes in this variable also cause the button to select -or deselect itself. -Defaults to the value \fBselectedButton\fR. -.OP \-width width Width -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button, 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 \fBradiobutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a radiobutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the radiobutton such as its colors, font, -text, and initial relief. The \fBradiobutton\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 radiobutton is a widget that displays a textual string, bitmap or image -and a diamond or circle 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 \fB\-wraplength\fR option) and -one of the characters may optionally be underlined using the -\fB\-underline\fR option. A radiobutton has -all of the behavior of a simple button: it can display itself in either -of three different ways, according to the \fB\-state\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 -check button. -.PP -In addition, radiobuttons can be \fIselected\fR. -If a radiobutton is selected, the indicator is normally -drawn with a selected appearance, and -a Tcl variable associated with the radiobutton is set to a particular -value (normally 1). -Under Unix, the indicator is drawn with a sunken relief and a special -color. Under Windows, the indicator is drawn with a round mark inside. -If the radiobutton 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 round mark inside. -Typically, several radiobuttons share a single variable and the -value of the variable indicates which radiobutton is to be selected. -When a radiobutton is selected it sets the value of the variable to -indicate that fact; each radiobutton also monitors the value of -the variable and automatically selects and deselects itself when the -variable's value changes. -If the variable's value matches the \fB\-tristatevalue\fR, then the radiobutton -is drawn using the tri-state mode. This mode is used to indicate mixed or -multiple values. (This is used when the radiobutton represents the state -of multiple items.) -By default the variable \fBselectedButton\fR -is used; its contents give the name of the button that is -selected, or the empty string if no button associated with that -variable is selected. -The name of the variable for a radiobutton, -plus the variable to be stored into 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 radiobutton is configured to select itself on button clicks. -.SH "WIDGET COMMAND" -.PP -The \fBradiobutton\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 radiobutton 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 \fBradiobutton\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, 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, 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 \fBradiobutton\fR -command. -.TP -\fIpathName \fBdeselect\fR -. -Deselects the radiobutton and sets the associated variable to an -empty string. -If this radiobutton was not currently selected, the command has -no effect. -.TP -\fIpathName \fBflash\fR -. -Flashes the radiobutton. This is accomplished by redisplaying the radiobutton -several times, alternating between active and normal colors. At -the end of the flash the radiobutton is left in the same normal/active -state as when the command was invoked. -This command is ignored if the radiobutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBinvoke\fR -. -Does just what would have happened if the user invoked the radiobutton -with the mouse: selects the button and invokes -its associated Tcl command, 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 radiobutton. -This command is ignored if the radiobutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBselect\fR -. -Selects the radiobutton and sets the associated variable to the -value corresponding to this widget. -.SH BINDINGS -.PP -Tk automatically creates class bindings for radiobuttons that give them -the following default behavior: -.IP [1] -On Unix systems, a radiobutton activates whenever the mouse passes -over it and deactivates whenever the mouse leaves the radiobutton. On -Mac and Windows systems, when mouse button 1 is pressed over a -radiobutton, 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 radiobutton it is invoked (it -becomes selected and the command associated with the button is -invoked, if there is one). -.IP [3] -When a radiobutton has the input focus, the space key causes the radiobutton -to be invoked. -.PP -If the radiobutton's state is \fBdisabled\fR then none of the above -actions occur: the radiobutton is completely non-responsive. -.PP -The behavior of radiobuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -checkbutton(n), labelframe(n), listbox(n), options(n), scale(n), ttk::radiobutton(n) -.SH KEYWORDS -radiobutton, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/raise.n b/tk8.6/doc/raise.n deleted file mode 100644 index c8feb71..0000000 --- a/tk8.6/doc/raise.n +++ /dev/null @@ -1,57 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH raise n 3.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -raise \- Change a window's position in the stacking order -.SH SYNOPSIS -\fBraise \fIwindow \fR?\fIaboveThis\fR? -.BE -.SH DESCRIPTION -.PP -If the \fIaboveThis\fR argument is omitted then the command raises -\fIwindow\fR so that it is above all of its siblings in the stacking -order (it will not be obscured by any siblings and will obscure -any siblings that overlap it). -If \fIaboveThis\fR is specified then it must be the path name of -a window that is either a sibling of \fIwindow\fR or the descendant -of a sibling of \fIwindow\fR. -In this case the \fBraise\fR command will insert -\fIwindow\fR into the stacking order just above \fIaboveThis\fR -(or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); -this could end up either raising or lowering \fIwindow\fR. -.PP -All \fBtoplevel\fR windows may be restacked with respect to each -other, whatever their relative path names, but the window manager is -not obligated to strictly honor requests to restack. -.PP -On macOS raising an iconified \fBtoplevel\fR window causes it to be -deiconified. -.SH EXAMPLE -.PP -Make a button appear to be in a sibling frame that was created after -it. This is is often necessary when building GUIs in the style where -you create your activity widgets first before laying them out on the -display: -.CS -button .b \-text "Hi there!" -pack [frame .f \-background blue] -pack [label .f.l1 \-text "This is above"] -pack .b \-in .f -pack [label .f.l2 \-text "This is below"] -\fBraise\fR .b -.CE -.SH "SEE ALSO" -lower(n) -.SH KEYWORDS -obscure, raise, stacking order -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/scale.n b/tk8.6/doc/scale.n deleted file mode 100644 index 6b960ce..0000000 --- a/tk8.6/doc/scale.n +++ /dev/null @@ -1,253 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH scale n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -scale \- Create and manipulate 'scale' value-controlled slider widgets -.SH SYNOPSIS -\fBscale\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-foreground \-relief -\-background \-highlightbackground \-repeatdelay -\-borderwidth \-highlightcolor \-repeatinterval -\-cursor \-highlightthickness \-takefocus -\-font \-orient \-troughcolor -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-bigincrement bigIncrement BigIncrement -Some interactions with the scale cause its value to change by -.QW large -increments; this option specifies the size of the -large increments. If specified as 0, the large increments default -to 1/10 the range of the scale. -.OP \-command command Command -Specifies the prefix of a Tcl command to invoke whenever the scale's -value is changed via a widget command. -The actual command consists -of this option followed by a space and a real number indicating the -new value of the scale. -.OP \-digits digits Digits -An integer specifying how many significant digits should be retained -when converting the value of the scale to a string. -If the number is less than or equal to zero, then the scale picks -the smallest value that guarantees that every possible slider -position prints as a different string. -.OP \-from from From -A real value corresponding to the left or top end of the scale. -.OP \-label label Label -A string to display as a label for the scale. For -vertical scales the label is displayed just to the right of the -top end of the scale. For horizontal scales the label is displayed -just above the left end of the scale. If the option is specified -as an empty string, no label is displayed. -.OP \-length length Length -Specifies the desired long dimension of the scale in screen units -(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). -For vertical scales this is the scale's height; for horizontal scales -it is the scale's width. -.OP \-resolution resolution Resolution -A real value specifying the resolution for the scale. -If this value is greater than zero then the scale's value will always be -rounded to an even multiple of this value, as will tick marks and -the endpoints of the scale. If the value is less than zero then no -rounding occurs. Defaults to 1 (i.e., the value will be integral). -.OP \-showvalue showValue ShowValue -Specifies a boolean value indicating whether or not the current -value of the scale is to be displayed. -.OP \-sliderlength sliderLength SliderLength -Specifies the size of the slider, measured in screen units along the slider's -long dimension. The value may be specified in any of the forms acceptable -to \fBTk_GetPixels\fR. -.OP \-sliderrelief sliderRelief SliderRelief -Specifies the relief to use when drawing the slider, such as \fBraised\fR -or \fBsunken\fR. -.OP \-state state State -Specifies one of three states for the scale: \fBnormal\fR, -\fBactive\fR, or \fBdisabled\fR. -If the scale is disabled then the value may not be changed and the scale -will not activate. -If the scale is active, the slider is displayed using the color -specified by the \fB\-activebackground\fR option. -.OP \-tickinterval tickInterval TickInterval -Must be a real value. -Determines the spacing between numerical -tick marks displayed below or to the left of the slider. -If 0, no tick marks will be displayed. -.OP \-to to To -Specifies a real value corresponding -to the right or bottom end of the scale. -This value may be either less than or greater than the \fB\-from\fR option. -.OP \-variable variable Variable -Specifies the name of a global variable to link to the scale. Whenever the -value of the variable changes, the scale will update to reflect this -value. -Whenever the scale is manipulated interactively, the variable -will be modified to reflect the scale's new value. -.OP \-width width Width -Specifies the desired narrow dimension of the scale in screen units -(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). -For vertical scales this is the scale's width; for horizontal scales -this is the scale's height. -.BE -.SH DESCRIPTION -.PP -The \fBscale\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a scale widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the scale such as its colors, orientation, -and relief. The \fBscale\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 scale is a widget that displays a rectangular \fItrough\fR and a -small \fIslider\fR. The trough corresponds to a range -of real values (determined by the \fB\-from\fR, \fB\-to\fR, and -\fB\-resolution\fR options), -and the position of the slider selects a particular real value. -The slider's position (and hence the scale's value) may be adjusted -with the mouse or keyboard as described in the \fBBINDINGS\fR -section below. Whenever the scale's value is changed, a Tcl -command is invoked (using the \fB\-command\fR option) to notify -other interested widgets of the change. -In addition, the value -of the scale can be linked to a Tcl variable (using the \fB\-variable\fR -option), so that changes in either are reflected in the other. -.PP -Three annotations may be displayed in a scale widget: a label -appearing at the top right of the widget (top left for horizontal -scales), a number displayed just to the left of the slider -(just above the slider for horizontal scales), and a collection -of numerical tick marks just to the left of the current value -(just below the trough for horizontal scales). Each of these three -annotations may be enabled or disabled using the -configuration options. -.SH "WIDGET COMMAND" -.PP -The \fBscale\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 scale 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 \fBscale\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 \fBscale\fR -command. -.TP -\fIpathName \fBcoords \fR?\fIvalue\fR? -. -Returns a list whose elements are the x and y coordinates of -the point along the centerline of the trough that corresponds -to \fIvalue\fR. -If \fIvalue\fR is omitted then the scale's current value is used. -.TP -\fIpathName \fBget\fR ?\fIx y\fR? -. -If \fIx\fR and \fIy\fR are omitted, returns the current value -of the scale. If \fIx\fR and \fIy\fR are specified, they give -pixel coordinates within the widget; the command returns -the scale value corresponding to the given pixel. -Only one of \fIx\fR or \fIy\fR is used: for horizontal scales -\fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. -.TP -\fIpathName \fBidentify \fIx y\fR -. -Returns a string indicating what part of the scale lies under -the coordinates given by \fIx\fR and \fIy\fR. -A return value of \fBslider\fR means that the point is over -the slider; \fBtrough1\fR means that the point is over the -portion of the slider above or to the left of the slider; -and \fBtrough2\fR means that the point is over the portion -of the slider below or to the right of the slider. -If the point is not over one of these elements, an empty string -is returned. -.TP -\fIpathName \fBset \fIvalue\fR -. -This command is invoked to change the current value of the scale, -and hence the position at which the slider is displayed. \fIValue\fR -gives the new value for the scale. -The command has no effect if the scale is disabled. -.SH BINDINGS -.PP -Tk automatically creates class bindings for scales that give them -the following default behavior. -Where the behavior is different for vertical and horizontal scales, -the horizontal behavior is described in parentheses. -.IP [1] -If button 1 is pressed in the trough, the scale's value will -be incremented or decremented by the value of the \fB\-resolution\fR -option so that the slider moves in the direction of the cursor. -If the button is held down, the action auto-repeats. -.IP [2] -If button 1 is pressed over the slider, the slider can be dragged -with the mouse. -.IP [3] -If button 1 is pressed in the trough with the Control key down, -the slider moves all the way to the end of its range, in the -direction towards the mouse cursor. -.IP [4] -If button 2 is pressed, the scale's value is set to the mouse -position. If the mouse is dragged with button 2 down, the scale's -value changes with the drag. -.IP [5] -The Up and Left keys move the slider up (left) by the value -of the \fB\-resolution\fR option. -.IP [6] -The Down and Right keys move the slider down (right) by the value -of the \fB\-resolution\fR option. -.IP [7] -Control-Up and Control-Left move the slider up (left) by the -value of the \fB\-bigincrement\fR option. -.IP [8] -Control-Down and Control-Right move the slider down (right) by the -value of the \fB\-bigincrement\fR option. -.IP [9] -Home moves the slider to the top (left) end of its range. -.IP [10] -End moves the slider to the bottom (right) end of its range. -.PP -If the scale is disabled using the \fB\-state\fR option then -none of the above bindings have any effect. -.PP -The behavior of scales can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -ttk::scale(n) -.SH KEYWORDS -scale, slider, trough, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/scrollbar.n b/tk8.6/doc/scrollbar.n deleted file mode 100644 index 4d148af..0000000 --- a/tk8.6/doc/scrollbar.n +++ /dev/null @@ -1,360 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH scrollbar n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets -.SH SYNOPSIS -\fBscrollbar\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-highlightcolor \-repeatdelay -\-background \-highlightthickness \-repeatinterval -\-borderwidth \-jump \-takefocus -\-cursor \-orient \-troughcolor -\-highlightbackground \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-activerelief activeRelief ActiveRelief -Specifies the relief to use when displaying the element that is -active, if any. -Elements other than the active element are always displayed with -a raised relief. -.OP \-command command Command -Specifies the prefix of a Tcl command to invoke to change the view -in the widget associated with the scrollbar. When a user requests -a view change by manipulating the scrollbar, a Tcl command is -invoked. The actual command consists of this option followed by -additional information as described later. This option almost always has -a value such as \fB.t xview\fR or \fB.t yview\fR, consisting of the -name of a widget and either \fBxview\fR (if the scrollbar is for -horizontal scrolling) or \fByview\fR (for vertical scrolling). -All scrollable widgets have \fBxview\fR and \fByview\fR commands -that take exactly the additional arguments appended by the scrollbar -as described in \fBSCROLLING COMMANDS\fR below. -.OP \-elementborderwidth elementBorderWidth BorderWidth -Specifies the width of borders drawn around the internal elements -of the scrollbar (the two arrows and the slider). The value may -have any of the forms acceptable to \fBTk_GetPixels\fR. -If this value is less than zero, the value of the \fB\-borderwidth\fR -option is used in its place. -.OP \-width width Width -Specifies the desired narrow dimension of the scrollbar window, -not including 3-D border, if any. For vertical -scrollbars this will be the width and for horizontal scrollbars -this will be the height. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.BE -.SH DESCRIPTION -.PP -The \fBscrollbar\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a scrollbar widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the scrollbar -such as its colors, orientation, and relief. -The \fBscrollbar\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 scrollbar is a widget that displays two arrows, one at each end of -the scrollbar, and a \fIslider\fR in the middle portion of the -scrollbar. -It provides information about what is visible in an \fIassociated window\fR -that displays a document of some sort (such as a file being edited or -a drawing). -The position and size of the slider indicate which portion of the -document is visible in the associated window. For example, if the -slider in a vertical scrollbar covers the top third of the area -between the two arrows, it means that the associated window displays -the top third of its document. -.PP -Scrollbars can be used to adjust the view in the associated window -by clicking or dragging with the mouse. See the \fBBINDINGS\fR section -below for details. -.SH "ELEMENTS" -.PP -A scrollbar displays five elements, which are referred to in the -widget commands for the scrollbar: -.TP 10 -\fBarrow1\fR -The top or left arrow in the scrollbar. -.TP 10 -\fBtrough1\fR -The region between the slider and \fBarrow1\fR. -.TP 10 -\fBslider\fR -The rectangle that indicates what is visible in the associated widget. -.TP 10 -\fBtrough2\fR -The region between the slider and \fBarrow2\fR. -.TP 10 -\fBarrow2\fR -The bottom or right arrow in the scrollbar. -.SH "WIDGET COMMAND" -.PP -The \fBscrollbar\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 scrollbar widgets: -.TP -\fIpathName \fBactivate \fR?\fIelement\fR? -. -Marks the element indicated by \fIelement\fR as active, which -causes it to be displayed as specified by the \fB\-activebackground\fR -and \fB\-activerelief\fR options. -The only element values understood by this command are \fBarrow1\fR, -\fBslider\fR, or \fBarrow2\fR. -If any other value is specified then no element of the scrollbar -will be active. -If \fIelement\fR is not specified, the command returns -the name of the element that is currently active, or an empty string -if no element is active. -.TP -\fIpathName \fBcget \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 \fBscrollbar\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 \fBscrollbar\fR -command. -.TP -\fIpathName \fBdelta \fIdeltaX deltaY\fR -. -Returns a real number indicating the fractional change in -the scrollbar setting that corresponds to a given change -in slider position. For example, if the scrollbar is horizontal, -the result indicates how much the scrollbar setting must change -to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is -ignored in this case). -If the scrollbar is vertical, the result indicates how much the -scrollbar setting must change to move the slider \fIdeltaY\fR pixels -down. The arguments and the result may be zero or negative. -.TP -\fIpathName \fBfraction \fIx y\fR -. -Returns a real number between 0 and 1 indicating where the point -given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. -The value 0 corresponds to the top or left of the trough, the -value 1 corresponds to the bottom or right, 0.5 corresponds to -the middle, and so on. -\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar -widget. -If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest -point in the trough is used. -.TP -\fIpathName \fBget\fR -. -Returns the scrollbar settings in the form of a list whose -elements are the arguments to the most recent \fBset\fR widget command. -.TP -\fIpathName \fBidentify \fIx y\fR -. -Returns the name of the element under the point given by \fIx\fR and -\fIy\fR (such as \fBarrow1\fR), or an empty string if the point does -not lie in any element of the scrollbar. -\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar -widget. -.TP -\fIpathName \fBset \fIfirst last\fR -. -This command is invoked by the scrollbar's associated widget to -tell the scrollbar about the current view in the widget. -The command takes two arguments, each of which is a real fraction -between 0 and 1. -The fractions describe the range of the document that is visible in -the associated widget. -For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means -that the first part of the document visible in the window is 20% -of the way through the document, and the last visible part is 40% -of the way through. -.SH "SCROLLING COMMANDS" -.PP -When the user interacts with the scrollbar, for example by dragging -the slider, the scrollbar notifies the associated widget that it -must change its view. -The scrollbar makes the notification by evaluating a Tcl command -generated from the scrollbar's \fB\-command\fR option. -The command may take any of the following forms. -In each case, \fIprefix\fR is the contents of the -\fB\-command\fR option, which usually has a form like -.QW \fB.t yview\fR . -.TP -\fIprefix \fBmoveto \fIfraction\fR -. -\fIFraction\fR is a real number between 0 and 1. -The widget should adjust its view so that the point given -by \fIfraction\fR appears at the beginning of the widget. -If \fIfraction\fR is 0 it refers to the beginning of the -document. 1.0 refers to the end of the document, 0.333 -refers to a point one-third of the way through the document, -and so on. -.TP -\fIprefix \fBscroll \fInumber \fBunits\fR -. -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. -.TP -\fIprefix \fBscroll \fInumber \fBpages\fR -. -The widget should adjust its view by \fInumber\fR pages. -It is up to the widget to define the meaning of a page; typically -it is slightly less than what fits in the window, so that there -is a slight overlap between the old and new views. -\fINumber\fR is either 1, which means the next page should -become visible, or \-1, which means that the previous page should -become visible. -.SH "OLD COMMAND SYNTAX" -.PP -In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget -commands used a different form. -This form is still supported for backward compatibility, but it -is deprecated. -In the old command syntax, the \fBset\fR widget command has the -following form: -.TP -\fIpathName \fBset \fItotalUnits windowUnits firstUnit lastUnit\fR -In this form the arguments are all integers. -\fITotalUnits\fR gives the total size of the object being displayed in the -associated widget. The meaning of one unit depends on the associated -widget; for example, in a text editor widget units might -correspond to lines of -text. \fIWindowUnits\fR indicates the total number of units that -can fit in the associated window at one time. \fIFirstUnit\fR -and \fIlastUnit\fR give the indices of the first and last units -currently visible in the associated window (zero corresponds to the -first unit of the object). -.LP -Under the old syntax the \fBget\fR widget command returns a list -of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR, -\fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR -widget command. -.PP -The commands generated by scrollbars also have a different form -when the old syntax is being used: -.TP -\fIprefix\fR \fIunit\fR -\fIUnit\fR is an integer that indicates what should appear at -the top or left of the associated widget's window. -It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR -arguments to the \fBset\fR widget command. -.LP -The most recent \fBset\fR widget command determines whether or not -to use the old syntax. -If it is given two real arguments then the new syntax will be -used in the future, and if it is given four integer arguments then -the old syntax will be used. -.SH BINDINGS -.PP -Tk automatically creates class bindings for scrollbars that give them -the following default behavior. -If the behavior is different for vertical and horizontal scrollbars, -the horizontal behavior is described in parentheses. -.IP [1] -Pressing button 1 over \fBarrow1\fR causes the view in the -associated widget to shift up (left) by one unit so that the -document appears to move down (right) one unit. -If the button is held down, the action auto-repeats. -.IP [2] -Pressing button 1 over \fBtrough1\fR causes the view in the -associated widget to shift up (left) by one screenful so that the -document appears to move down (right) one screenful. -If the button is held down, the action auto-repeats. -.IP [3] -Pressing button 1 over the slider and dragging causes the view -to drag with the slider. -If the \fBjump\fR option is true, then the view does not drag along -with the slider; it changes only when the mouse button is released. -.IP [4] -Pressing button 1 over \fBtrough2\fR causes the view in the -associated widget to shift down (right) by one screenful so that the -document appears to move up (left) one screenful. -If the button is held down, the action auto-repeats. -.IP [5] -Pressing button 1 over \fBarrow2\fR causes the view in the -associated widget to shift down (right) by one unit so that the -document appears to move up (left) one unit. -If the button is held down, the action auto-repeats. -.IP [6] -If button 2 is pressed over the trough or the slider, it sets -the view to correspond to the mouse position; dragging the -mouse with button 2 down causes the view to drag with the mouse. -If button 2 is pressed over one of the arrows, it causes the -same behavior as pressing button 1. -.IP [7] -If button 1 is pressed with the Control key down, then if the -mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes -to the very top (left) of the document; if the mouse is over -\fBarrow2\fR or \fBtrough2\fR the view changes -to the very bottom (right) of the document; if the mouse is -anywhere else then the button press has no effect. -.IP [8] -In vertical scrollbars the Up and Down keys have the same behavior -as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. -In horizontal scrollbars these keys have no effect. -.IP [9] -In vertical scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -In horizontal scrollbars these keys have no effect. -.IP [10] -In horizontal scrollbars the Up and Down keys have the same behavior -as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. -In vertical scrollbars these keys have no effect. -.IP [11] -In horizontal scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -In vertical scrollbars these keys have no effect. -.IP [12] -The Prior and Next keys have the same behavior -as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -.IP [13] -The Home key adjusts the view to the top (left edge) of the document. -.IP [14] -The End key adjusts the view to the bottom (right edge) of the document. -.SH EXAMPLE -.PP -Create a window with a scrollable \fBtext\fR widget: -.CS -toplevel .tl -text .tl.t \-yscrollcommand {.tl.s set} -\fBscrollbar\fR .tl.s \-command {.tl.t yview} -grid .tl.t .tl.s \-sticky nsew -grid columnconfigure .tl 0 \-weight 1 -grid rowconfigure .tl 0 \-weight 1 -.CE -.SH "SEE ALSO" -ttk:scrollbar(n) -.SH KEYWORDS -scrollbar, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/selection.n b/tk8.6/doc/selection.n deleted file mode 100644 index ec678fa..0000000 --- a/tk8.6/doc/selection.n +++ /dev/null @@ -1,206 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH selection n 8.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -selection \- Manipulate the X selection -.SH SYNOPSIS -\fBselection \fIoption\fR ?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -This command provides a Tcl interface to the X selection mechanism and -implements the full selection functionality described in the -X Inter-Client Communication Conventions Manual (ICCCM). -.PP -Note that for management of the \fBCLIPBOARD\fR selection (see below), the -\fBclipboard\fR command may also be used. -.PP -The first argument to \fBselection\fR determines the format of the -rest of the arguments and the behavior of the command. The following -forms are currently supported: -.TP -\fBselection clear\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? -. -If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it -so that no window owns the selection anymore. \fISelection\fR -specifies the X selection that should be cleared, and should be an -atom name such as \fBPRIMARY\fR or \fBCLIPBOARD\fR; see the Inter-Client -Communication Conventions Manual for complete details. -\fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to -.QW . . -Returns an empty string. -.TP -\fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? -. -Retrieves the value of \fIselection\fR from \fIwindow\fR's display and -returns it as a result. \fISelection\fR defaults to \fBPRIMARY\fR and -\fIwindow\fR defaults to -.QW . . -\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 \fBSTRING\fR or \fBFILE_NAME\fR; see the -Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to \fBSTRING\fR. The selection owner may choose to -return the selection in any of several different representation -formats, such as \fBSTRING\fR, \fBUTF8_STRING\fR, \fBATOM\fR, -\fBINTEGER\fR, etc. (this format is different -than the selection type; see the ICCCM for all the confusing details). -If the selection is returned in a non-string format, such as \fBINTEGER\fR -or \fBATOM\fR, the \fBselection\fR command converts it to string format as a -collection of fields separated by spaces: atoms are converted to their -textual names, and anything else is converted to hexadecimal integers. -Note that \fBselection get\fR does not retrieve the selection in the -\fBUTF8_STRING\fR format unless told to. -.TP -\fBselection handle\fR ?\fB\-selection\fR \fIs\fR? ?\fB\-type\fR \fIt\fR? ?\fB\-format\fR \fIf\fR? \fIwindow command\fR -. -Creates a handler for selection requests, such that \fIcommand\fR will -be executed whenever selection \fIs\fR is owned by \fIwindow\fR and -someone attempts to retrieve it in the form given by type \fIt\fR -(e.g. \fIt\fR is specified in the \fBselection get\fR command). -\fIS\fR defaults to \fBPRIMARY\fR, \fIt\fR defaults to \fBSTRING\fR, and -\fIf\fR defaults to \fBSTRING\fR. If \fIcommand\fR is an empty string -then any existing handler for \fIwindow\fR, \fIt\fR, and -\fIs\fR is removed. -Note that when the selection is handled as type \fBSTRING\fR it is also -automatically handled as type \fBUTF8_STRING\fR as well. -.RS -.PP -When \fIselection\fR is requested, \fIwindow\fR is the selection owner, -and \fItype\fR is the requested type, \fIcommand\fR will be executed -as a Tcl command with two additional numbers appended to it -(with space separators). -The two additional numbers -are \fIoffset\fR and \fImaxChars\fR: \fIoffset\fR specifies a starting -character position in the selection and \fImaxChars\fR gives the maximum -number of characters to retrieve. The command should return a value consisting -of at most \fImaxChars\fR of the selection, starting at position -\fIoffset\fR. For very large selections (larger than \fImaxChars\fR) -the selection will be retrieved using several invocations of \fIcommand\fR -with increasing \fIoffset\fR values. If \fIcommand\fR returns a string -whose length is less than \fImaxChars\fR, the return value is assumed to -include all of the remainder of the selection; if the length of -\fIcommand\fR's result is equal to \fImaxChars\fR then -\fIcommand\fR will be invoked again, until it eventually -returns a result shorter than \fImaxChars\fR. The value of \fImaxChars\fR -will always be relatively large (thousands of characters). -.PP -If \fIcommand\fR returns an error then the selection retrieval is rejected -just as if the selection did not exist at all. -.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 \fBSTRING\fR. If \fIformat\fR is -\fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters (i.e. -just in the form returned by \fIcommand\fR, in the system \fBencoding\fR; -the \fBUTF8_STRING\fR format always uses UTF-8 as its encoding). -If \fIformat\fR is -\fBATOM\fR, then the return value from \fIcommand\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, the return value from \fIcommand\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. -.PP -The \fIformat\fR argument is needed only for compatibility with -selection requesters that do not use Tk. If Tk is being -used to retrieve the selection then the value is converted back to -a string at the requesting end, so \fIformat\fR is -irrelevant. -.RE -.TP -\fBselection own\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? -.TP -\fBselection own\fR ?\fB\-command\fR \fIcommand\fR? ?\fB\-selection\fR \fIselection\fR? \fIwindow\fR -. -The first form of \fBselection own\fR returns the path name of the -window in this application that owns \fIselection\fR on the display -containing \fIwindow\fR, or an empty string if no window in this -application owns the selection. \fISelection\fR defaults to \fBPRIMARY\fR and -\fIwindow\fR defaults to -.QW . . -.RS -.PP -The second form of \fBselection own\fR causes \fIwindow\fR to become -the new owner of \fIselection\fR on \fIwindow\fR's display, returning -an empty string as result. The existing owner, if any, is notified -that it has lost the selection. -If \fIcommand\fR is specified, it is a Tcl script to execute when -some other window claims ownership of the selection away from -\fIwindow\fR. \fISelection\fR defaults to PRIMARY. -.RE -.SH WIDGET FACILITIES -.PP -The \fBtext\fR, \fBentry\fR, \fBttk::entry\fR, \fBlistbox\fR, \fBspinbox\fR and \fBttk::spinbox\fR widgets have the option \fB\-exportselection\fR. If a widget has this option set to boolean \fBtrue\fR, then (in an unsafe interpreter) a selection made in the widget is automatically written to the \fBPRIMARY\fR selection. -.PP -A GUI event, for example \fB<<PasteSelection>>\fR, can copy the \fBPRIMARY\fR selection to certain widgets. This copy is implemented by a widget binding to the event. The binding script makes appropriate calls to the \fBselection\fR command. -.PP -.SH PORTABILITY ISSUES -.PP -On X11, the \fBPRIMARY\fR selection is a system-wide feature of the X server, allowing communication between different processes that are X11 clients. -.PP -On Windows, the \fBPRIMARY\fR selection is not provided by the system, but only by Tk, and so it is shared only between windows of a master interpreter and its unsafe slave interpreters. It is not shared between interpreters in different processes or different threads. Each master interpreter has a separate \fBPRIMARY\fR selection that is shared only with its unsafe slaves. -.PP -.SH SECURITY -.PP -A safe interpreter cannot read from the \fBPRIMARY\fR selection because its \fBselection\fR command is hidden. For this reason the \fBPRIMARY\fR selection cannot be written to the Tk widgets of a safe interpreter. -.PP -A Tk widget can have its option \fB\-exportselection\fR set to boolean \fBtrue\fR, but in a safe interpreter this option has no effect: writing from the widget to the \fBPRIMARY\fR selection is disabled. -.PP -These are security features. A safe interpreter may run untrusted code, and it is a security risk if this untrusted code can read or write the \fBPRIMARY\fR selection used by other interpreters. -.PP -.SH EXAMPLES -.PP -On X11 platforms, one of the standard selections available is the -\fBSECONDARY\fR selection. Hardly anything uses it, but here is how to read -it using Tk: -.PP -.CS -set selContents [\fBselection get\fR \-selection SECONDARY] -.CE -.PP -Many different types of data may be available for a selection; the -special type \fBTARGETS\fR allows you to get a list of available types: -.PP -.CS -foreach type [\fBselection get\fR \-type TARGETS] { - puts "Selection PRIMARY supports type $type" -} -.CE -.PP -To claim the selection, you must first set up a handler to supply the -data for the selection. Then you have to claim the selection... -.CS -# Set up the data handler ready for incoming requests -set foo "This is a string with some data in it... blah blah" -\fBselection handle\fR \-selection SECONDARY . getData -proc getData {offset maxChars} { - puts "Retrieving selection starting at $offset" - return [string range $::foo $offset [expr {$offset+$maxChars-1}]] -} - -# Now we grab the selection itself -puts "Claiming selection" -\fBselection own\fR \-command lost \-selection SECONDARY . -proc lost {} { - puts "Lost selection" -} -.CE -.SH "SEE ALSO" -clipboard(n) -.SH KEYWORDS -clear, format, handler, ICCCM, own, selection, target, type -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/send.n b/tk8.6/doc/send.n deleted file mode 100644 index 2a683d5..0000000 --- a/tk8.6/doc/send.n +++ /dev/null @@ -1,109 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH send n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -send \- Execute a command in a different application -.SH SYNOPSIS -\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the -application named by \fIapp\fR. It returns the result or -error from that command execution. -\fIApp\fR may be the name of any application whose main window is -on the display containing the sender's main window; it need not -be within the same process. -If no \fIarg\fR arguments are present, then the command to be executed is -contained entirely within the \fIcmd\fR argument. If one or -more \fIarg\fRs are present, they are concatenated to form the -command to be executed, just as for the \fBeval\fR command. -.PP -If the initial arguments of the command begin with -.QW \- -they are treated as options. The following options are currently defined: -.TP -\fB\-async\fR -Requests asynchronous invocation. In this case the \fBsend\fR -command will complete immediately without waiting for \fIcmd\fR -to complete in the target application; no result will be available -and errors in the sent command will be ignored. -If the target application is in the same process as the sending -application then the \fB\-async\fR option is ignored. -.TP -\fB\-displayof\fR \fIpathName\fR -Specifies that the target application's main window is on the display -of the window given by \fIpathName\fR, instead of the display containing -the application's main window. -.TP -\fB\-\|\-\fR -Serves no purpose except to terminate the list of options. This -option is needed only if \fIapp\fR could contain a leading -.QW \- -character. -.SH "APPLICATION NAMES" -.PP -The name of an application is set initially from the name of the -program or script that created the application. -You can query and change the name of an application with the -\fBtk appname\fR command. -.SH "DISABLING SENDS" -.PP -If the \fBsend\fR command is removed from an application (e.g. -with the command \fBrename\fR \fBsend {}\fR) then the application -will not respond to incoming send requests anymore, nor will it -be able to issue outgoing requests. -Communication can be reenabled by invoking the \fBtk appname\fR -command. -.SH SECURITY -.PP -The \fBsend\fR command is potentially a serious security loophole. On Unix, -any application that can connect to your X server can send -scripts to your applications. -These incoming scripts can use Tcl to read and -write your files and invoke subprocesses under your name. -Host-based access control such as that provided by \fBxhost\fR -is particularly insecure, since it allows anyone with an account -on particular hosts to connect to your server, and if disabled it -allows anyone anywhere to connect to your server. -In order to provide at least a small amount of -security, Tk checks the access control being used by the server -and rejects incoming sends unless (a) \fBxhost\fR-style access control -is enabled (i.e. only certain hosts can establish connections) and (b) the -list of enabled hosts is empty. -This means that applications cannot connect to your server unless -they use some other form of authorization -such as that provide by \fBxauth\fR. -Under Windows, \fBsend\fR is currently disabled. Most of the -functionality is provided by the \fBdde\fR command instead. -.SH EXAMPLE -.PP -This script fragment can be used to make an application that only runs -once on a particular display. -.CS -if {[tk appname FoobarApp] ne "FoobarApp"} { - \fBsend\fR \-async FoobarApp RemoteStart $argv - exit -} -# The command that will be called remotely, which raises -# the application main window and opens the requested files -proc RemoteStart args { - raise . - foreach filename $args { - OpenFile $filename - } -} -.CE -.SH KEYWORDS -application, dde, name, remote execution, security, send -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/spinbox.n b/tk8.6/doc/spinbox.n deleted file mode 100644 index acf06d6..0000000 --- a/tk8.6/doc/spinbox.n +++ /dev/null @@ -1,602 +0,0 @@ -'\" -'\" Copyright (c) 2000 Jeffrey Hobbs. -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH spinbox n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -spinbox \- Create and manipulate 'spinbox' value spinner widgets -.SH SYNOPSIS -\fBspinbox\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-highlightthickness \-repeatinterval -\-background \-insertbackground \-selectbackground -\-borderwidth \-insertborderwidth \-selectborderwidth -\-cursor \-insertontime \-selectforeground -\-exportselection \-insertwidth \-takefocus -\-font \-insertofftime \-textvariable -\-foreground \-justify \-xscrollcommand -\-highlightbackground \-relief -\-highlightcolor \-repeatdelay -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-buttonbackground buttonBackground Background -The background color to be used for the spin buttons. -.OP \-buttoncursor buttonCursor Cursor -The cursor to be used when over the spin buttons. If this is empty -(the default), a default cursor will be used. -.OP \-buttondownrelief buttonDownRelief Relief -The relief to be used for the upper spin button. -.OP \-buttonuprelief buttonUpRelief Relief -The relief to be used for the lower spin button. -.OP \-command command Command -Specifies a Tcl command to invoke whenever a spinbutton is invoked. -The command recognizes several percent substitutions: \fB%W\fR for -the widget path, \fB%s\fR for the current value of the widget, and -\fB%d\fR for the direction of the button pressed (\fBup\fR or \fBdown\fR). -.OP \-disabledbackground disabledBackground DisabledBackground -Specifies the background color to use when the spinbox is disabled. If -this option is the empty string, the normal background color is used. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies the foreground color to use when the spinbox is disabled. If -this option is the empty string, the normal foreground color is used. -.OP \-format format Format -Specifies an alternate format to use when setting the string value -when using the \fB\-from\fR and \fB\-to\fR range. -This must be a format specifier of the form \fB%<pad>.<pad>f\fR, -as it will format a floating-point number. -.OP \-from from From -A floating-point value corresponding to the lowest value for a spinbox, to -be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all -are specified correctly, the spinbox will use these values to control its -contents. This value must be less than the \fB\-to\fR option. -If \fB\-values\fR is specified, it supersedes this option. -.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting -it to an empty string disables this feature (the default). The best use of -this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for -more information. -.OP \-increment increment Increment -A floating-point value specifying the increment. When used with -\fB\-from\fR and \fB\-to\fR, the value in the widget will be adjusted by -\fB\-increment\fR when a spin button is pressed (up adds the value, -down subtracts the value). -.OP \-readonlybackground readonlyBackground ReadonlyBackground -Specifies the background color to use when the spinbox is readonly. If -this option is the empty string, the normal background color is used. -.OP \-state state State -Specifies one of three states for the spinbox: \fBnormal\fR, -\fBdisabled\fR, or \fBreadonly\fR. If the spinbox is readonly, then the -value may not be changed using widget commands and no insertion cursor -will be displayed, even if the input focus is in the widget; the -contents of the widget may still be selected. If the spinbox is -disabled, the value may not be changed, no insertion cursor will be -displayed, the contents will not be selectable, and the spinbox may -be displayed in a different color, depending on the values of the -\fB\-disabledforeground\fR and \fB\-disabledbackground\fR options. -.OP \-to to To -A floating-point value corresponding to the highest value for the spinbox, -to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When -all are specified correctly, the spinbox will use these values to control -its contents. This value must be greater than the \fB\-from\fR option. -If \fB\-values\fR is specified, it supersedes this option. -.OP \-validate validate Validate -Specifies the mode in which validation should operate: \fBnone\fR, -\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. -It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBVALIDATION\fR below for more. -.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand -Specifies a script to evaluate when you want to validate the input in the -widget. Setting it to an empty string disables this feature (the default). -Validation occurs according to the value of \fB\-validate\fR. -This command must return a valid Tcl boolean value. If it returns 0 (or -the valid Tcl boolean equivalent) then the value of the widget will not -change and the \fB\-invalidcommand\fR will be evaluated if it is set. If it -returns 1, then value will be changed. -See \fBVALIDATION\fR below for more information. -.OP \-values values Values -Must be a proper list value. If specified, the spinbox will use these -values as to control its contents, starting with the first value. This -option has precedence over the \fB\-from\fR and \fB\-to\fR range. -.OP \-width width Width -Specifies an integer value indicating the desired width of the spinbox window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. -.OP \-wrap wrap wrap -Must be a proper boolean value. If on, the spinbox will wrap around the -values of data in the widget. -.BE -.SH DESCRIPTION -.PP -The \fBspinbox\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a spinbox widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the spinbox such as its colors, font, -and relief. The \fBspinbox\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 \fBspinbox\fR is an extended \fBentry\fR widget that allows he user -to move, or spin, through a fixed set of ascending or descending values -such as times or dates in addition to editing the value as in an -\fBentry\fR. When first created, a spinbox's string is empty. -A portion of the spinbox may be selected as described below. -If a spinbox is exporting its selection (see the \fB\-exportselection\fR -option), then it will observe the standard protocols for handling the -selection; spinbox selections are available as type \fBSTRING\fR. -Spinboxes also observe the standard Tk rules for dealing with the -input focus. When a spinbox has the input focus it displays an -\fIinsertion cursor\fR to indicate where new characters will be -inserted. -.PP -Spinboxes are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Spinboxes use -the standard \fB\-xscrollcommand\fR mechanism for interacting with -scrollbars (see the description of the \fB\-xscrollcommand\fR option -for details). They also support scanning, as described below. -.SH VALIDATION -.PP -Validation works by setting the \fB\-validatecommand\fR -option to a script which will be evaluated according to the \fB\-validate\fR -option as follows: -.PP -.IP \fBnone\fR 10 -Default. This means no validation will occur. -.IP \fBfocus\fR 10 -The \fB\-validatecommand\fR will be called when the spinbox receives or -loses focus. -.IP \fBfocusin\fR 10 -The \fB\-validatecommand\fR will be called when the spinbox receives focus. -.IP \fBfocusout\fR 10 -The \fB\-validatecommand\fR will be called when the spinbox loses focus. -.IP \fBkey\fR 10 -The \fB\-validatecommand\fR will be called when the spinbox is edited. -.IP \fBall\fR 10 -The \fB\-validatecommand\fR will be called for all above conditions. -.PP -It is possible to perform percent substitutions on the \fB\-validatecommand\fR -and \fB\-invalidcommand\fR scripts, just as you would in a \fBbind\fR script. The -following substitutions are recognized: -.PP -.IP \fB%d\fR 5 -Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, -or \-1 for focus, forced or textvariable validation. -.IP \fB%i\fR 5 -Index of char string to be inserted/deleted, if any, otherwise \-1. -.IP \fB%P\fR 5 -The value of the spinbox should edition occur. If you are configuring the -spinbox widget to have a new textvariable, this will be the value of that -textvariable. -.IP \fB%s\fR 5 -The current value of spinbox before edition. -.IP \fB%S\fR 5 -The text string being inserted/deleted, if any. -Otherwise it is an empty string. -.IP \fB%v\fR 5 -The type of validation currently set. -.IP \fB%V\fR 5 -The type of validation that triggered the callback -(key, focusin, focusout, forced). -.IP \fB%W\fR 5 -The name of the spinbox widget. -.PP -In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR can be -dangerous to mix. Any problems have been overcome so that using the -\fB\-validatecommand\fR will not interfere with the traditional behavior of -the spinbox widget. Using the \fB\-textvariable\fR for read-only purposes will -never cause problems. The danger comes when you try set the -\fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not -accept, which causes \fB\-validate\fR to become \fBnone\fR (the -\fB\-invalidcommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fB\-validatecommand\fR. -.PP -Primarily, an error will occur when the \fB\-validatecommand\fR or -\fB\-invalidcommand\fR encounters an error in its script while evaluating or -\fB\-validatecommand\fR does not return a valid Tcl boolean value. The -\fB\-validate\fR option will also set itself to \fBnone\fR when you edit the -spinbox widget from within either the \fB\-validatecommand\fR or the -\fB\-invalidcommand\fR. Such editions will override the one that was being -validated. If you wish to edit the value of the widget -during validation and still have the \fB\-validate\fR option set, you should -include the command -.CS - \fI%W config \-validate %v\fR -.CE -in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you -were editing the spinbox widget from). It is also recommended to not set an -associated \fB\-textvariable\fR during validation, as that can cause the -spinbox widget to become out of sync with the \fB\-textvariable\fR. -.PP -Also, the \fB-validate\fR option will set itself to \fBnone\fR when the -spinbox value gets changed because of adjustment of \fB-from\fR or \fB-to\fR -and the \fB-validatecommand\fR returns false. For instance -.CS - \fIspinbox pathName \-from 1 \-to 10 \-validate all \-vcmd {return 0}\fR -.CE -will in fact set the \fB-validate\fR option to \fBnone\fR because the default -value for the spinbox gets changed (due to the \fB-from\fR and \fB-to\fR -options) to a value not accepted by the validation script. -.PP -Moreover, forced validation is performed when invoking any spinbutton of -the spinbox. If the validation script returns false in this situation, -then the \fB-validate\fR option will be automatically set to \fBnone\fR. -.SH "WIDGET COMMAND" -.PP -The \fBspinbox\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. -.SS INDICES -.PP -Many of the widget commands for spinboxes take one or more indices as -arguments. An index specifies a particular character in the spinbox's -string, in any of the following ways: -.TP 12 -\fInumber\fR -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. -.TP 12 -\fBanchor\fR -Indicates the anchor point for the selection, which is set with the -\fBselect from\fR and \fBselect adjust\fR widget commands. -.TP 12 -\fBend\fR -Indicates the character just after the last one in the spinbox's string. -This is equivalent to specifying a numerical index equal to the length -of the spinbox's string. -.TP 12 -\fBinsert\fR -Indicates the character adjacent to and immediately following the -insertion cursor. -.TP 12 -\fBsel.first\fR -Indicates the first character in the selection. It is an error to -use this form if the selection is not in the spinbox window. -.TP 12 -\fBsel.last\fR -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection is not in the -spinbox window. -.TP 12 -\fB@\fInumber\fR -In this form, \fInumber\fR is treated as an x-coordinate in the -spinbox's window; the character spanning that x-coordinate is used. -For example, -.QW \fB@0\fR -indicates the left-most character in the window. -.LP -Abbreviations may be used for any of the forms above, e.g. -.QW \fBe\fR -or -.QW \fBsel.f\fR . -In general, out-of-range indices are automatically rounded to the -nearest legal value. -.SS SUBCOMMANDS -.PP -The following commands are possible for spinbox widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four numbers describing the bounding box of the -character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. -.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 \fBspinbox\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 \fBspinbox\fR -command. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Delete one or more elements of the spinbox. -\fIFirst\fR is the index of the first character to delete, and -\fIlast\fR is the index of the character just after the last -one to delete. -If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, -i.e. a single character is deleted. -This command returns an empty string. -.TP -\fIpathName \fBget\fR -Returns the spinbox's string. -.TP -\fIpathName \fBicursor \fIindex\fR -Arrange for the insertion cursor to be displayed just before the character -given by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBidentify\fI x y\fR -Returns the name of the window element corresponding to coordinates -\fIx\fR and \fIy\fR in the spinbox. Return value is one of: -\fBnone\fR, \fBbuttondown\fR, \fBbuttonup\fR, \fBentry\fR. -.TP -\fIpathName \fBindex\fI index\fR -Returns the numerical index corresponding to \fIindex\fR. -.TP -\fIpathName \fBinsert \fIindex string\fR -Insert the characters of \fIstring\fR just before the character -indicated by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBinvoke\fI element\fR -Causes the specified element, either \fBbuttondown\fR or \fBbuttonup\fR, -to be invoked, triggering the action associated with it. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on spinboxes. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx\fR -Records \fIx\fR and the current view in the spinbox window; used in -conjunction with later \fBscan dragto\fR commands. Typically this -command is associated with a mouse button press in the widget. It -returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx\fR -This command computes the difference between its \fIx\fR argument -and the \fIx\fR argument to the last \fBscan mark\fR command for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the spinbox at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within a spinbox. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection adjust \fIindex\fR -Locate the end of the selection nearest to the character given by -\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR -(i.e. including but not going beyond \fIindex\fR). The other -end of the selection is made the anchor point for future -\fBselect to\fR commands. If the selection -is not currently in the spinbox, then a new selection is created to -include the characters between \fIindex\fR and the most recent -selection anchor point, inclusive. -Returns an empty string. -.TP -\fIpathName \fBselection clear\fR -Clear the selection if it is currently in this widget. If the -selection is not in this widget then the command has no effect. -Returns an empty string. -.TP -\fIpathName \fBselection element\fR ?\fIelement\fR? -Sets or gets the currently selected element. If a spinbutton element -is specified, it will be displayed depressed. -.TP -\fIpathName \fBselection from \fIindex\fR -Set the selection anchor point to just before the character -given by \fIindex\fR. Does not change the selection. -Returns an empty string. -.TP -\fIpathName \fBselection present\fR -Returns 1 if there is are characters selected in the spinbox, -0 if nothing is selected. -.TP -\fIpathName \fBselection range \fIstart end\fR -Sets the selection to include the characters starting with -the one indexed by \fIstart\fR and ending with the one just -before \fIend\fR. -If \fIend\fR refers to the same character as \fIstart\fR or an -earlier one, then the spinbox's selection is cleared. -.TP -\fIpathName \fBselection to \fIindex\fR -If \fIindex\fR is before the anchor point, set the selection -to the characters from \fIindex\fR up to but not including -the anchor point. -If \fIindex\fR is the same as the anchor point, do nothing. -If \fIindex\fR is after the anchor point, set the selection -to the characters from the anchor point up to but not including -\fIindex\fR. -The anchor point is determined by the most recent \fBselect from\fR -or \fBselect adjust\fR command in this widget. -If the selection is not in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. -.RE -.TP -\fIpathName \fBset\fR ?\fIstring\fR? -If \fIstring\fR is specified, the spinbox will try and set it to this -value, otherwise it just returns the spinbox's string. -If validation is on, it will occur when setting the string. -.TP -\fIpathName \fBvalidate\fR -This command is used to force an evaluation of the \fB\-validatecommand\fR -independent of the conditions specified by the \fB\-validate\fR option. -This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. -It returns 0 or 1. -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the spinbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is displayed at the left edge of the window. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that the character \fIfraction\fR of the -way through the text appears at the left edge of the window. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for spinboxes that give them -the following default behavior. -In the descriptions below, -.QW word -refers to a contiguous group of letters, digits, or -.QW _ -characters, or any single character other than these. -.IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects all of the text in the -spinbox and positions the insertion cursor before the first character. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. -.IP [5] -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the spinbox without affecting the selection. -.IP [6] -If any normal printing characters are typed in a spinbox, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the spinbox can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the spinbox at the position of the mouse cursor. -.IP [8] -If the mouse is dragged out of the spinbox on the left or right sides -while button 1 is pressed, the spinbox will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the spinbox and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. -.IP [10] -The Home key, or Control-a, will move the insertion cursor to the -beginning of the spinbox and clear any selection in the spinbox. -Shift-Home moves the insertion cursor to the beginning of the spinbox -and also extends the selection to that point. -.IP [11] -The End key, or Control-e, will move the insertion cursor to the -end of the spinbox and clear any selection in the spinbox. -Shift-End moves the cursor to the end and extends the selection -to that point. -.IP [12] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They do not affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. -.IP [13] -Control-/ selects all the text in the spinbox. -.IP [14] -Control-\e clears any selection in the spinbox. -.IP [15] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -.IP [16] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. -.IP [17] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -.IP [18] -The Delete key deletes the selection, if there is one in the spinbox. -If there is no selection, it deletes the character to the right of -the insertion cursor. -.IP [19] -The BackSpace key and Control-h delete the selection, if there is one -in the spinbox. -If there is no selection, it deletes the character to the left of -the insertion cursor. -.IP [20] -Control-d deletes the character to the right of the insertion cursor. -.IP [21] -Meta-d deletes the word to the right of the insertion cursor. -.IP [22] -Control-k deletes all the characters to the right of the insertion -cursor. -.IP [23] -Control-t reverses the order of the two characters to the right of -the insertion cursor. -.PP -If the spinbox is disabled using the \fB\-state\fR option, then the spinbox's -view can still be adjusted and text in the spinbox can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. -.PP -The behavior of spinboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. -.SH "SEE ALSO" -ttk::spinbox(n) -.SH KEYWORDS -spinbox, entry, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/text.n b/tk8.6/doc/text.n deleted file mode 100644 index 2a161e6..0000000 --- a/tk8.6/doc/text.n +++ /dev/null @@ -1,2285 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH text n 8.5 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets -.SH SYNOPSIS -.nf -\fBtext\fR \fIpathName \fR?\fIoptions\fR? -\fBtk_textCopy\fR \fIpathName\fR -\fBtk_textCut\fR \fIpathName\fR -\fBtk_textPaste\fR \fIpathName\fR -.SO -\-background \-highlightthickness \-relief -\-borderwidth \-insertbackground \-selectbackground -\-cursor \-insertborderwidth \-selectborderwidth -\-exportselection \-insertofftime \-selectforeground -\-font \-insertontime \-setgrid -\-foreground \-insertwidth \-takefocus -\-highlightbackground \-padx \-xscrollcommand -\-highlightcolor \-pady \-yscrollcommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-autoseparators autoSeparators AutoSeparators -Specifies a boolean that says whether separators are automatically inserted in -the undo stack. Only meaningful when the \fB\-undo\fR option is true. -.OP \-blockcursor blockCursor BlockCursor -Specifies a boolean that says whether the blinking insertion cursor should be -drawn as a character-sized rectangular block. If false (the default) a thin -vertical line is used for the insertion cursor. -.OP \-endline endLine EndLine -Specifies an integer line index representing the line of the underlying -textual data store that should be just after the last line contained in -the widget. This allows a text widget to reflect only a portion of a -larger piece of text. Instead of an integer, the empty string can be -provided to this configuration option, which will configure the widget -to end at the very last line in the textual data store. -.OP \-height height Height -Specifies the desired height for the window, in units of characters in the -font given by the \fB\-font\fR option. Must be at least one. -.OP \-inactiveselectbackground inactiveSelectBackground Foreground -Specifies the colour to use for the selection (the \fBsel\fR tag) when the -window does not have the input focus. If empty, \fB{}\fR, then no selection is -shown when the window does not have the focus. -.OP \-insertunfocussed insertUnfocussed InsertUnfocussed -.VS 8.6 -Specifies how to display the insertion cursor when the widget does not have -the focus. Must be \fBnone\fR (the default) which means to not display the -cursor, \fBhollow\fR which means to display a hollow box, or \fBsolid\fR which -means to display a solid box. Note that \fBhollow\fR and \fBsolid\fR will -appear very similar when the \fB\-blockcursor\fR option is false. -.VE 8.6 -.OP \-maxundo maxUndo MaxUndo -Specifies the maximum number of compound undo actions on the undo stack. A -zero or a negative value imply an unlimited undo stack. -.OP \-spacing1 spacing1 Spacing1 -Requests additional space above each text line in the widget, using any of the -standard forms for screen distances. If a line wraps, this option only applies -to the first line on the display. This option may be overridden with -\fB\-spacing1\fR options in tags. -.OP \-spacing2 spacing2 Spacing2 -For lines that wrap (so that they cover more than one line on the display) -this option specifies additional space to provide between the display lines -that represent a single line of text. The value may have any of the standard -forms for screen distances. This option may be overridden with -\fB\-spacing2\fR options in tags. -.OP \-spacing3 spacing3 Spacing3 -Requests additional space below each text line in the widget, using any of the -standard forms for screen distances. If a line wraps, this option only applies -to the last line on the display. This option may be overridden with -\fB\-spacing3\fR options in tags. -.OP \-startline startLine StartLine -Specifies an integer line index representing the first line of the underlying -textual data store that should be contained in the widget. This allows a text -widget to reflect only a portion of a larger piece of text. Instead of an -integer, the empty string can be provided to this configuration option, which -will configure the widget to start at the very first line in the textual data -store. -.OP \-state state State -Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. If -the text is disabled then characters may not be inserted or deleted and no -insertion cursor will be displayed, even if the input focus is in the widget. -.OP \-tabs tabs Tabs -Specifies a set of tab stops for the window. The option's value consists of a -list of screen distances giving the positions of the tab stops, each of which -is a distance relative to the left edge of the widget (excluding borders, -padding, etc). Each position may optionally be followed in the next list -element by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, or -\fBnumeric\fR, which specifies how to justify text relative to the tab stop. -\fBLeft\fR is the default; it causes the text following the tab character to -be positioned with its left edge at the tab position. \fBRight\fR means that -the right edge of the text following the tab character is positioned at the -tab position, and \fBcenter\fR means that the text is centered at the tab -position. \fBNumeric\fR means that the decimal point in the text is positioned -at the tab position; if there is no decimal point then the least significant -digit of the number is positioned just to the left of the tab position; if -there is no number in the text then the text is right-justified at the tab -position. For example, -.QW "\fB\-tabs {2c left 4c 6c center}\fR" -creates three tab stops at two-centimeter intervals; the first two use left -justification and the third uses center justification. -.RS -.PP -If the list of tab stops does not have enough elements to cover all of the -tabs in a text line, then Tk extrapolates new tab stops using the spacing and -alignment from the last tab stop in the list. Tab distances must be strictly -positive, and must always increase from one tab stop to the next (if not, an -error is thrown). The value of the \fB\-tabs\fR option may be overridden by -\fB\-tabs\fR options in tags. -.PP -If no \fB\-tabs\fR option is specified, or if it is specified as an empty -list, then Tk uses default tabs spaced every eight (average size) characters. -To achieve a different standard spacing, for example every 4 characters, -simply configure the widget with -.QW "\fB\-tabs \N'34'[expr {4 * [font measure $font 0]}] left\N'34' \-tabstyle wordprocessor\fR" . -.RE -.OP \-tabstyle tabStyle TabStyle -Specifies how to interpret the relationship between tab stops on a line and -tabs in the text of that line. The value must be \fBtabular\fR (the default) -or \fBwordprocessor\fR. Note that tabs are interpreted as they are encountered -in the text. If the tab style is \fBtabular\fR then the \fIn\fR'th tab -character in the line's text will be associated with the \fIn\fR'th tab stop -defined for that line. If the tab character's x coordinate falls to the right -of the \fIn\fR'th tab stop, then a gap of a single space will be inserted as a -fallback. If the tab style is \fBwordprocessor\fR then any tab character being -laid out will use (and be defined by) the first tab stop to the right of the -preceding characters already laid out on that line. The value of the -\fB\-tabstyle\fR option may be overridden by \fB\-tabstyle\fR options in tags. -.OP \-undo undo Undo -Specifies a boolean that says whether the undo mechanism is active or not. -.OP \-width width Width -Specifies the desired width for the window in units of characters in the font -given by the \fB\-font\fR option. If the font does not have a uniform width -then the width of the character -.QW 0 -is used in translating from character units to screen units. -.OP \-wrap wrap Wrap -Specifies how to handle lines in the text that are too long to be displayed in -a single line of the text's window. The value must be \fBnone\fR or \fBchar\fR -or \fBword\fR. A wrap mode of \fBnone\fR means that each line of text appears -as exactly one line on the screen; extra characters that do not fit on the -screen are not displayed. In the other modes each line of text will be broken -up into several screen lines if necessary to keep all the characters visible. -In \fBchar\fR mode a screen line break may occur after any character; in -\fBword\fR mode a line break will only be made at word boundaries. -.BE -.SH DESCRIPTION -.PP -The \fBtext\fR command creates a new window (given by the \fIpathName\fR -argument) and makes it into a text widget. Additional options, described -above, may be specified on the command line or in the option database to -configure aspects of the text such as its default background color and relief. -The \fBtext\fR command returns the path name of the new window. -.PP -A text widget displays one or more lines of text and allows that text to be -edited. Text widgets support four different kinds of annotations on the text, -called tags, marks, embedded windows or embedded images. Tags allow different -portions of the text to be displayed with different fonts and colors. In -addition, Tcl commands can be associated with tags so that scripts are invoked -when particular actions such as keystrokes and mouse button presses occur in -particular ranges of the text. See \fBTAGS\fR below for more details. -.PP -The second form of annotation consists of floating markers in the text called -.QW marks . -Marks are used to keep track of various interesting positions in the text as -it is edited. See \fBMARKS\fR below for more details. -.PP -The third form of annotation allows arbitrary windows to be embedded in a text -widget. See \fBEMBEDDED WINDOWS\fR below for more details. -.PP -The fourth form of annotation allows Tk images to be embedded in a text -widget. See \fBEMBEDDED IMAGES\fR below for more details. -.PP -The text widget also has a built-in undo/redo mechanism. See -\fBTHE UNDO MECHANISM\fR below for more details. -.PP -The text widget allows for the creation of peer widgets. These are other text -widgets which share the same underlying data (text, marks, tags, images, etc). -See \fBPEER WIDGETS\fR below for more details. -.SH INDICES -.PP -Many of the widget commands for texts take one or more indices as arguments. -An index is a string used to indicate a particular place within a text, such -as a place to insert characters or one endpoint of a range of characters to -delete. Indices have the syntax -.CS -\fIbase modifier modifier modifier ...\fR -.CE -Where \fIbase\fR gives a starting point and the \fImodifier\fRs adjust the -index from the starting point (e.g. move forward or backward one character). -Every index must contain a \fIbase\fR, but the \fImodifier\fRs are optional. -Most modifiers (as documented below) allow an optional submodifier. Valid -submodifiers are \fBany\fR and \fBdisplay\fR. If the submodifier is -abbreviated, then it must be followed by whitespace, but otherwise there need -be no space between the submodifier and the following \fImodifier\fR. -Typically the \fBdisplay\fR submodifier adjusts the meaning of the following -\fImodifier\fR to make it refer to visual or non-elided units rather than -logical units, but this is explained for each relevant case below. Lastly, -where \fIcount\fR is used as part of a modifier, it can be positive or -negative, so -.QW "\fIbase\fR \- \-3 lines" -is perfectly valid (and equivalent to -.QW "\fIbase\fR +3lines" ). -.PP -The \fIbase\fR for an index must have one of the following forms: -.TP 12 -\fIline\fB.\fIchar\fR -. -Indicates \fIchar\fR'th character on line \fIline\fR. Lines are numbered from -1 for consistency with other UNIX programs that use this numbering scheme. -Within a line, characters are numbered from 0. If \fIchar\fR is \fBend\fR then -it refers to the newline character that ends the line. -.TP 12 -\fB@\fIx\fB,\fIy\fR -. -Indicates the character that covers the pixel whose x and y coordinates within -the text's window are \fIx\fR and \fIy\fR. -.TP 12 -\fBend\fR -. -Indicates the end of the text (the character just after the last newline). -.TP 12 -\fImark\fR -. -Indicates the character just after the mark whose name is \fImark\fR. -.TP 12 -\fItag\fB.first\fR -. -Indicates the first character in the text that has been tagged with \fItag\fR. -This form generates an error if no characters are currently tagged with -\fItag\fR. -.TP 12 -\fItag\fB.last\fR -. -Indicates the character just after the last one in the text that has been -tagged with \fItag\fR. This form generates an error if no characters are -currently tagged with \fItag\fR. -.TP 12 -\fIpathName\fR -. -Indicates the position of the embedded window whose name is \fIpathName\fR. -This form generates an error if there is no embedded window by the given name. -.TP 12 -\fIimageName\fR -. -Indicates the position of the embedded image whose name is \fIimageName\fR. -This form generates an error if there is no embedded image by the given name. -.PP -If the \fIbase\fR could match more than one of the above forms, such as a -\fImark\fR and \fIimageName\fR both having the same value, then the form -earlier in the above list takes precedence. If modifiers follow the base -index, each one of them must have one of the forms listed below. Keywords such -as \fBchars\fR and \fBwordend\fR may be abbreviated as long as the -abbreviation is unambiguous. -.TP -\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR -. -Adjust the index forward by \fIcount\fR characters, moving to later lines in -the text if necessary. If there are fewer than \fIcount\fR characters in the -text after the current index, then set the index to the last index in the -text. Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR -submodifier is given, elided characters are skipped over without being -counted. If \fBany\fR is given, then all characters are counted. For -historical reasons, if neither modifier is given then the count actually takes -place in units of index positions (see \fBINDICES\fR for details). This -behaviour may be changed in a future major release, so if you need an index -count, you are encouraged to use \fBindices\fR instead wherever possible. -.TP -\fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR -. -Adjust the index backward by \fIcount\fR characters, moving to earlier lines -in the text if necessary. If there are fewer than \fIcount\fR characters in -the text before the current index, then set the index to the first index in -the text (1.0). Spaces on either side of \fIcount\fR are optional. If the -\fBdisplay\fR submodifier is given, elided characters are skipped over without -being counted. If \fBany\fR is given, then all characters are counted. For -historical reasons, if neither modifier is given then the count actually takes -place in units of index positions (see \fBINDICES\fR for details). This -behavior may be changed in a future major release, so if you need an index -count, you are encouraged to use \fBindices\fR instead wherever possible. -.TP -\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR -. -Adjust the index forward by \fIcount\fR index positions, moving to later lines -in the text if necessary. If there are fewer than \fIcount\fR index positions -in the text after the current index, then set the index to the last index -position in the text. Spaces on either side of \fIcount\fR are optional. Note -that an index position is either a single character or a single embedded image -or embedded window. If the \fBdisplay\fR submodifier is given, elided indices -are skipped over without being counted. If \fBany\fR is given, then all -indices are counted; this is also the default behaviour if no modifier is -given. -.TP -\fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR -. -Adjust the index backward by \fIcount\fR index positions, moving to earlier -lines in the text if necessary. If there are fewer than \fIcount\fR index -positions in the text before the current index, then set the index to the -first index position (1.0) in the text. Spaces on either side of \fIcount\fR -are optional. If the \fBdisplay\fR submodifier is given, elided indices are -skipped over without being counted. If \fBany\fR is given, then all indices -are counted; this is also the default behaviour if no modifier is given. -.TP -\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR -. -Adjust the index forward by \fIcount\fR lines, retaining the same character -position within the line. If there are fewer than \fIcount\fR lines after the -line containing the current index, then set the index to refer to the same -character position on the last line of the text. Then, if the line is not long -enough to contain a character at the indicated character position, adjust the -character position to refer to the last character of the line (the newline). -Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR -submodifier is given, then each visual display line is counted separately. -Otherwise, if \fBany\fR (or no modifier) is given, then each logical line (no -matter how many times it is visually wrapped) counts just once. If the -relevant lines are not wrapped, then these two methods of counting are -equivalent. -.TP -\fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR -. -Adjust the index backward by \fIcount\fR logical lines, retaining the same -character position within the line. If there are fewer than \fIcount\fR lines -before the line containing the current index, then set the index to refer to -the same character position on the first line of the text. Then, if the line -is not long enough to contain a character at the indicated character position, -adjust the character position to refer to the last character of the line (the -newline). Spaces on either side of \fIcount\fR are optional. If the -\fBdisplay\fR submodifier is given, then each visual display line is counted -separately. Otherwise, if \fBany\fR (or no modifier) is given, then each -logical line (no matter how many times it is visually wrapped) counts just -once. If the relevant lines are not wrapped, then these two methods of -counting are equivalent. -.TP -?\fIsubmodifier\fR? \fBlinestart\fR -. -Adjust the index to refer to the first index on the line. If the \fBdisplay\fR -submodifier is given, this is the first index on the display line, otherwise -on the logical line. -.TP -?\fIsubmodifier\fR? \fBlineend\fR -. -Adjust the index to refer to the last index on the line (the newline). If the -\fBdisplay\fR submodifier is given, this is the last index on the display -line, otherwise on the logical line. -.TP -?\fIsubmodifier\fR? \fBwordstart\fR -. -Adjust the index to refer to the first character of the word containing the -current index. A word consists of any number of adjacent characters that are -letters, digits, or underscores, or a single character that is not one of -these. If the \fBdisplay\fR submodifier is given, this only examines -non-elided characters, otherwise all characters (elided or not) are examined. -.TP -?\fIsubmodifier\fR? \fBwordend\fR -. -Adjust the index to refer to the character just after the last one of the word -containing the current index. If the current index refers to the last -character of the text then it is not modified. If the \fBdisplay\fR -submodifier is given, this only examines non-elided characters, otherwise all -characters (elided or not) are examined. -.PP -If more than one modifier is present then they are applied in left-to-right -order. For example, the index -.QW "\fBend \- 1 chars\fR" -refers to the next-to-last character in the text and -.QW "\fBinsert wordstart \- 1 c\fR" -refers to the character just before the first one in the word containing the -insertion cursor. Modifiers are applied one by one in this left to right -order, and after each step the resulting index is constrained to be a valid -index in the text widget. So, for example, the index -.QW "\fB1.0 \-1c +1c\fR" -refers to the index -.QW \fB2.0\fR . -.PP -Where modifiers result in index changes by display lines, display chars or -display indices, and the \fIbase\fR refers to an index inside an elided tag, -that base index is considered to be equivalent to the first following -non-elided index. -.SH TAGS -.PP -The first form of annotation in text widgets is a tag. A tag is a textual -string that is associated with some of the characters in a text. Tags may -contain arbitrary characters, but it is probably best to avoid using the -characters -.QW " " -(space), \fB+\fR, or \fB\-\fR: these characters have special meaning in -indices, so tags containing them cannot be used as indices. There may be any -number of tags associated with characters in a text. Each tag may refer to a -single character, a range of characters, or several ranges of characters. An -individual character may have any number of tags associated with it. -.PP -A priority order is defined among tags, and this order is used in implementing -some of the tag-related functions described below. When a tag is defined (by -associating it with characters or setting its display options or binding -commands to it), it is given a priority higher than any existing tag. The -priority order of tags may be redefined using the -.QW "\fIpathName \fBtag raise\fR" -and -.QW "\fIpathName \fBtag lower\fR" -widget commands. -.PP -Tags serve three purposes in text widgets. First, they control the way -information is displayed on the screen. By default, characters are displayed -as determined by the \fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR -options for the text widget. However, display options may be associated with -individual tags using the -.QW "\fIpathName \fBtag configure\fR" -widget command. If a character has been tagged, then the display options -associated with the tag override the default display style. The following -options are currently supported for tags: -.TP -\fB\-background \fIcolor\fR -. -\fIColor\fR specifies the background color to use for characters associated -with the tag. It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-bgstipple \fIbitmap\fR -. -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern for the -background. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If -\fIbitmap\fR has not been specified, or if it is specified as an empty string, -then a solid fill will be used for the background. -.TP -\fB\-borderwidth \fIpixels\fR -. -\fIPixels\fR specifies the width of a border to draw around the tag using any -of the forms accepted by \fBTk_GetPixels\fR. This option should be used in -conjunction with the \fB\-relief\fR option to provide the desired border. -.TP -\fB\-elide \fIboolean\fR -. -\fIElide\fR specifies whether the data should be elided. Elided data -(characters, images, embedded windows, etc.) is not displayed and takes no -space on screen, but further on behaves just as normal data. -.TP -\fB\-fgstipple \fIbitmap\fR -. -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern when drawing -text and other foreground information such as underlines. It may have any of -the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been -specified, or if it is specified as an empty string, then a solid fill will be -used. -.TP -\fB\-font \fIfontName\fR -. -\fIFontName\fR is the name of a font to use for drawing characters. It may -have any of the forms accepted by \fBTk_GetFont\fR. -.TP -\fB\-foreground \fIcolor\fR -. -\fIColor\fR specifies the color to use when drawing text and other foreground -information such as underlines. It may have any of the forms accepted by -\fBTk_GetColor\fR. -.TP -\fB\-justify \fIjustify\fR -. -If the first non-elided character of a display line has a tag for which this -option has been specified, then \fIjustify\fR determines how to justify the -line. It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. If a line -wraps, then the justification for each line on the display is determined by -the first non-elided character of that display line. -.TP -\fB\-lmargin1 \fIpixels\fR -. -If the first non-elided character of a text line has a tag for which this -option has been specified, then \fIpixels\fR specifies how much the line -should be indented from the left edge of the window. \fIPixels\fR may have any -of the standard forms for screen distances. If a line of text wraps, this -option only applies to the first line on the display; the \fB\-lmargin2\fR -option controls the indentation for subsequent lines. -.TP -\fB\-lmargin2 \fIpixels\fR -. -If the first non-elided character of a display line has a tag for which this -option has been specified, and if the display line is not the first for its -text line (i.e., the text line has wrapped), then \fIpixels\fR specifies how -much the line should be indented from the left edge of the window. -\fIPixels\fR may have any of the standard forms for screen distances. This -option is only used when wrapping is enabled, and it only applies to the -second and later display lines for a text line. -.TP -\fB\-lmargincolor \fIcolor\fR -. -\fIColor\fR specifies the background color to use in regions that do not -contain characters because they are indented by \fB\-lmargin1\fR or -\fB\-lmargin2\fR. It may have any of the forms accepted by -\fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is -specified as an empty string, then the color used is specified by the -\fB-background\fR tag option (or, if this is also unspecified, by the -\fB-background\fR widget option). -.TP -\fB\-offset \fIpixels\fR -. -\fIPixels\fR specifies an amount by which the text's baseline should be offset -vertically from the baseline of the overall line, in pixels. For example, a -positive offset can be used for superscripts and a negative offset can be used -for subscripts. \fIPixels\fR may have any of the standard forms for screen -distances. -.TP -\fB\-overstrike \fIboolean\fR -. -Specifies whether or not to draw a horizontal rule through the middle of -characters. \fIBoolean\fR may have any of the forms accepted by -\fBTcl_GetBoolean\fR. -.TP -\fB\-overstrikefg \fIcolor\fR -. -\fIColor\fR specifies the color to use when displaying the overstrike. It may -have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not -been specified, or if it is specified as an empty string, then the color -specified by the \fB\-foreground\fR tag option is used. -.TP -\fB\-relief \fIrelief\fR -. -\fIRelief\fR specifies the relief style to use for drawing the border, in any -of the forms accepted by \fBTk_GetRelief\fR. This option is used in -conjunction with the \fB\-borderwidth\fR option to enable to the desired -border appearance. -.TP -\fB\-rmargin \fIpixels\fR -. -If the first non-elided character of a display line has a tag for which this -option has been specified, then \fIpixels\fR specifies how wide a margin to -leave between the end of the line and the right edge of the window. -\fIPixels\fR may have any of the standard forms for screen distances. This -option is only used when wrapping is enabled. If a text line wraps, the right -margin for each line on the display is determined by the first non-elided -character of that display line. -.TP -\fB\-rmargincolor \fIcolor\fR -. -\fIColor\fR specifies the background color to use in regions that do not -contain characters because they are indented by \fB\-rmargin\fR. It may -have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not -been specified, or if it is specified as an empty string, then the color -used is specified by the \fB-background\fR tag option (or, if this is also -unspecified, by the \fB-background\fR widget option). -.TP -\fB\-selectbackground \fIcolor\fR -\fIColor\fR specifies the background color to use when displaying selected -items. It may have any of the forms accepted by \fBTk_GetColor\fR. If -\fIcolor\fR has not been specified, or if it is specified as an empty -string, then the color specified by the \fB\-background\fR tag option is -used. -.TP -\fB\-selectforeground \fIcolor\fR -\fIColor\fR specifies the foreground color to use when displaying selected -items. It may have any of the forms accepted by \fBTk_GetColor\fR. If -\fIcolor\fR has not been specified, or if it is specified as an empty -string, then the color specified by the \fB\-foreground\fR tag option is -used. -.TP -\fB\-spacing1 \fIpixels\fR -. -\fIPixels\fR specifies how much additional space should be left above each -text line, using any of the standard forms for screen distances. If a line -wraps, this option only applies to the first line on the display. -.TP -\fB\-spacing2 \fIpixels\fR -. -For lines that wrap, this option specifies how much additional space to leave -between the display lines for a single text line. \fIPixels\fR may have any of -the standard forms for screen distances. -.TP -\fB\-spacing3 \fIpixels\fR -. -\fIPixels\fR specifies how much additional space should be left below each -text line, using any of the standard forms for screen distances. If a line -wraps, this option only applies to the last line on the display. -.TP -\fB\-tabs \fItabList\fR -. -\fITabList\fR specifies a set of tab stops in the same form as for the -\fB\-tabs\fR option for the text widget. This option only applies to a display -line if it applies to the first non-elided character on that display line. If -this option is specified as an empty string, it cancels the option, leaving it -unspecified for the tag (the default). If the option is specified as a -non-empty string that is an empty list, such as \fB\-tags\0{\0}\fR, then it -requests default 8-character tabs as described for the \fB\-tags\fR widget -option. -.TP -\fB\-tabstyle \fIstyle\fR -. -\fIStyle\fR specifies either the \fItabular\fR or \fIwordprocessor\fR style of -tabbing to use for the text widget. This option only applies to a display line -if it applies to the first non-elided character on that display line. If this -option is specified as an empty string, it cancels the option, leaving it -unspecified for the tag (the default). -.TP -\fB\-underline \fIboolean\fR -. -\fIBoolean\fR specifies whether or not to draw an underline underneath -characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR. -.TP -\fB\-underlinefg \fIcolor\fR -. -\fIColor\fR specifies the color to use when displaying the underline. It may -have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not -been specified, or if it is specified as an empty string, then the color -specified by the \fB\-foreground\fR tag option is used. -.TP -\fB\-wrap \fImode\fR -. -\fIMode\fR specifies how to handle lines that are wider than the text's -window. This option only applies to a display line if it applies to the -first non-elided character on that display line. It has the same legal -values as the \fB\-wrap\fR option for the text widget: \fBnone\fR, -\fBchar\fR, or \fBword\fR. If this tag option is specified, it -overrides the \fB\-wrap\fR option for the text widget. -.PP -If a character has several tags associated with it, and if their display -options conflict, then the options of the highest priority tag are used. If a -particular display option has not been specified for a particular tag, or if -it is specified as an empty string, then that option will never be used; the -next-highest-priority tag's option will used instead. If no tag specifies a -particular display option, then the default style for the widget will be used. -.PP -The second purpose for tags is event bindings. You can associate bindings with -a tag in much the same way you can associate bindings with a widget class: -whenever particular X events occur on characters with the given tag, a given -Tcl command will be executed. Tag bindings can be used to give behaviors to -ranges of characters; among other things, this allows hypertext-like features -to be implemented. For details, see the description of the -.QW "\fIpathName \fBtag bind\fR" -widget command below. Tag bindings are shared between all peer widgets -(including any bindings for the special \fBsel\fR tag). -.PP -The third use for tags is in managing the selection. See \fBTHE SELECTION\fR -below. With the exception of the special \fBsel\fR tag, all tags are shared -between peer text widgets, and may be manipulated on an equal basis from any -such widget. The \fBsel\fR tag exists separately and independently in each -peer text widget (but any tag bindings to \fBsel\fR are shared). -.SH MARKS -.PP -The second form of annotation in text widgets is a mark. Marks are used for -remembering particular places in a text. They are something like tags, in that -they have names and they refer to places in the file, but a mark is not -associated with particular characters. Instead, a mark is associated with the -gap between two characters. Only a single position may be associated with a -mark at any given time. If the characters around a mark are deleted the mark -will still remain; it will just have new neighbor characters. In contrast, if -the characters containing a tag are deleted then the tag will no longer have -an association with characters in the file. Marks may be manipulated with the -.QW "\fIpathName \fBmark\fR" -widget command, and their current locations may be determined by using the -mark name as an index in widget commands. -.PP -Each mark also has a -.QW gravity , -which is either \fBleft\fR or \fBright\fR. The gravity for a mark specifies -what happens to the mark when text is inserted at the point of the mark. If a -mark has left gravity, then the mark is treated as if it were attached to the -character on its left, so the mark will remain to the left of any text -inserted at the mark position. If the mark has right gravity, new text -inserted at the mark position will appear to the left of the mark (so that the -mark remains rightmost). The gravity for a mark defaults to \fBright\fR. -.PP -The name space for marks is different from that for tags: the same name may be -used for both a mark and a tag, but they will refer to different things. -.PP -Two marks have special significance. First, the mark \fBinsert\fR is -associated with the insertion cursor, as described under -\fBTHE INSERTION CURSOR\fR -below. Second, the mark \fBcurrent\fR is associated with the -character closest to the mouse and is adjusted automatically to track the -mouse position and any changes to the text in the widget (one exception: -\fBcurrent\fR is not updated in response to mouse motions if a mouse button is -down; the update will be deferred until all mouse buttons have been released). -Neither of these special marks may be deleted. With the exception of these two -special marks, all marks are shared between peer text widgets, and may be -manipulated on an equal basis from any peer. -.SH "EMBEDDED WINDOWS" -.PP -The third form of annotation in text widgets is an embedded window. Each -embedded window annotation causes a window to be displayed at a particular -point in the text. There may be any number of embedded windows in a text -widget, and any widget may be used as an embedded window (subject to the usual -rules for geometry management, which require the text window to be the parent -of the embedded window or a descendant of its parent). -.PP -The embedded window's position on the screen will be updated as the text is -modified or scrolled, and it will be mapped and unmapped as it moves into and -out of the visible area of the text widget. Each embedded window occupies one -unit's worth of index space in the text widget, and it may be referred to -either by the name of its embedded window or by its position in the widget's -index space. If the range of text containing the embedded window is deleted -then the window is destroyed. Similarly if the text widget as a whole is -deleted, then the window is destroyed. -.PP -Eliding an embedded window immediately after scheduling it for creation via -\fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it from being -effectively created. Uneliding an elided embedded window scheduled for creation -via \fIpathName \fBwindow create \fIindex \fB-create\fR will automatically -trigger the associated creation script. After destroying an elided embedded -window, the latter won't get automatically recreated. -.PP -When an embedded window is added to a text widget with the \fIpathName -\fBwindow create\fR widget command, several configuration options may be -associated with it. These options may be modified later with the \fIpathName -\fBwindow configure\fR widget command. The following options are currently -supported: -.TP -\fB\-align \fIwhere\fR -. -If the window is not as tall as the line in which it is displayed, this option -determines where the window is displayed in the line. \fIWhere\fR must have -one of the values \fBtop\fR (align the top of the window with the top of the -line), \fBcenter\fR (center the window within the range of the line), -\fBbottom\fR (align the bottom of the window with the bottom of the line's -area), or \fBbaseline\fR (align the bottom of the window with the baseline of -the line). -.TP -\fB\-create \fIscript\fR -. -Specifies a Tcl script that may be evaluated to create the window for the -annotation. If no \fB\-window\fR option has been specified for the annotation -this script will be evaluated when the annotation is about to be displayed on -the screen. \fIScript\fR must create a window for the annotation and return -the name of that window as its result. Two substitutions will be performed in -\fIscript\fR before evaluation. \fI%W\fR will be substituted by the name of -the parent text widget, and \fI%%\fR will be substituted by a single \fI%\fR. -If the annotation's window should ever be deleted, \fIscript\fR will be -evaluated again the next time the annotation is displayed. -.TP -\fB\-padx \fIpixels\fR -. -\fIPixels\fR specifies the amount of extra space to leave on each side of the -embedded window. It may have any of the usual forms defined for a screen -distance. -.TP -\fB\-pady \fIpixels\fR -. -\fIPixels\fR specifies the amount of extra space to leave on the top and on -the bottom of the embedded window. It may have any of the usual forms defined -for a screen distance. -.TP -\fB\-stretch \fIboolean\fR -. -If the requested height of the embedded window is less than the height of the -line in which it is displayed, this option can be used to specify whether the -window should be stretched vertically to fill its line. If the \fB\-pady\fR -option has been specified as well, then the requested padding will be retained -even if the window is stretched. -.TP -\fB\-window \fIpathName\fR -. -Specifies the name of a window to display in the annotation. Note that if a -\fIpathName\fR has been set, then later configuring a window to the empty -string will not delete the widget corresponding to the old \fIpathName\fR. -Rather it will remove the association between the old \fIpathName\fR and the -text widget. If multiple peer widgets are in use, it is usually simpler to use -the \fB\-create\fR option if embedded windows are desired in each peer. -.SH "EMBEDDED IMAGES" -.PP -The final form of annotation in text widgets is an embedded image. Each -embedded image annotation causes an image to be displayed at a particular -point in the text. There may be any number of embedded images in a text -widget, and a particular image may be embedded in multiple places in the same -text widget. -.PP -The embedded image's position on the screen will be updated as the text is -modified or scrolled. Each embedded image occupies one unit's worth of index -space in the text widget, and it may be referred to either by its position in -the widget's index space, or the name it is assigned when the image is inserted -into the text widget with \fIpathName \fBimage create\fR. If the range of text -containing the embedded image is deleted then that copy of the image is removed -from the screen. -.PP -Eliding an embedded image immediately after scheduling it for creation via -\fIpathName \fBimage create \fIindex \fB-create\fR will prevent it from being -effectively created. Uneliding an elided embedded image scheduled for creation -via \fIpathName \fBimage create \fIindex \fB-create\fR will automatically -trigger the associated creation script. After destroying an elided embedded -image, the latter won't get automatically recreated. -.PP -When an embedded image is added to a text widget with the \fIpathName \fBimage -create\fR widget command, a name unique to this instance of the image is -returned. This name may then be used to refer to this image instance. The name -is taken to be the value of the \fB\-name\fR option (described below). If the -\fB\-name\fR option is not provided, the \fB\-image\fR name is used instead. -If the \fIimageName\fR is already in use in the text widget, then \fB#\fInn\fR -is added to the end of the \fIimageName\fR, where \fInn\fR is an arbitrary -integer. This insures the \fIimageName\fR is unique. Once this name is -assigned to this instance of the image, it does not change, even though the -\fB\-image\fR or \fB\-name\fR values can be changed with \fIpathName \fBimage -configure\fR. -.PP -When an embedded image is added to a text widget with the \fIpathName \fBimage -create\fR widget command, several configuration options may be associated with -it. These options may be modified later with the \fIpathName \fBimage -configure\fR widget command. The following options are currently supported: -.TP -\fB\-align \fIwhere\fR -. -If the image is not as tall as the line in which it is displayed, this option -determines where the image is displayed in the line. \fIWhere\fR must have one -of the values \fBtop\fR (align the top of the image with the top of the line), -\fBcenter\fR (center the image within the range of the line), \fBbottom\fR -(align the bottom of the image with the bottom of the line's area), or -\fBbaseline\fR (align the bottom of the image with the baseline of the line). -.TP -\fB\-image \fIimage\fR -. -Specifies the name of the Tk image to display in the annotation. If -\fIimage\fR is not a valid Tk image, then an error is returned. -.TP -\fB\-name \fIImageName\fR -. -Specifies the name by which this image instance may be referenced in the text -widget. If \fIImageName\fR is not supplied, then the name of the Tk image is -used instead. If the \fIimageName\fR is already in use, \fI#nn\fR is appended -to the end of the name as described above. -.TP -\fB\-padx \fIpixels\fR -. -\fIPixels\fR specifies the amount of extra space to leave on each side of the -embedded image. It may have any of the usual forms defined for a screen -distance. -.TP -\fB\-pady \fIpixels\fR -. -\fIPixels\fR specifies the amount of extra space to leave on the top and on -the bottom of the embedded image. It may have any of the usual forms defined -for a screen distance. -.SH "THE SELECTION" -.PP -Selection support is implemented via tags. If the \fB\-exportselection\fR option -for the text widget is true then the \fBsel\fR tag will be associated with the -selection: -.IP [1] -Whenever characters are tagged with \fBsel\fR the text widget will claim -ownership of the selection. -.IP [2] -Attempts to retrieve the selection will be serviced by the text widget, -returning all the characters with the \fBsel\fR tag. -.IP [3] -If the selection is claimed away by another application or by another window -within this application, then the \fBsel\fR tag will be removed from all -characters in the text. -.IP [4] -Whenever the \fBsel\fR tag range changes a virtual event \fB<<Selection>>\fR -is generated. -.PP -The \fBsel\fR tag is automatically defined when a text widget is created, and -it may not be deleted with the -.QW "\fIpathName \fBtag delete\fR" -widget command. Furthermore, the \fB\-selectbackground\fR, -\fB\-selectborderwidth\fR, and \fB\-selectforeground\fR options for the text -widget are tied to the \fB\-background\fR, \fB\-borderwidth\fR, and -\fB\-foreground\fR options for the \fBsel\fR tag: changes in either will -automatically be reflected in the other. Also the -\fB\-inactiveselectbackground\fR option for the text widget is used instead of -\fB\-selectbackground\fR when the text widget does not have the focus. This -allows programmatic control over the visualization of the \fBsel\fR tag for -foreground and background windows, or to have \fBsel\fR not shown at all (when -\fB\-inactiveselectbackground\fR is empty) for background windows. Each peer -text widget has its own \fBsel\fR tag which can be separately configured and -set. -.SH "THE INSERTION CURSOR" -.PP -The mark named \fBinsert\fR has special significance in text widgets. It is -defined automatically when a text widget is created and it may not be unset -with the -.QW "\fIpathName \fBmark unset\fR" -widget command. The \fBinsert\fR mark represents the position of the insertion -cursor, and the insertion cursor will automatically be drawn at this point -whenever the text widget has the input focus. -.SH "THE MODIFIED FLAG" -.PP -The text widget can keep track of changes to the content of the widget by -means of the modified flag. Inserting or deleting text will set this flag. The -flag can be queried, set and cleared programmatically as well. Whenever the -flag changes state a \fB<<Modified>>\fR virtual event is generated. See the -\fIpathName \fBedit modified\fR widget command for more details. -.SH "THE UNDO MECHANISM" -.PP -The text widget has an unlimited undo and redo mechanism (when the -\fB\-undo\fR widget option is true) which records every insert and delete -action on a stack. -.PP -Boundaries (called -.QW separators ) -are inserted between edit actions. The purpose of these separators is to group -inserts, deletes and replaces into one compound edit action. When undoing a -change everything between two separators will be undone. The undone changes -are then moved to the redo stack, so that an undone edit can be redone again. -The redo stack is cleared whenever new edit actions are recorded on the undo -stack. The undo and redo stacks can be cleared to keep their depth under -control. -.PP -Separators are inserted automatically when the \fB\-autoseparators\fR widget -option is true. You can insert separators programmatically as well. If a -separator is already present at the top of the undo stack no other will be -inserted. That means that two separators on the undo stack are always -separated by at least one insert or delete action. -.PP -The \fB<<UndoStack>>\fR virtual event is generated every time the undo stack -or the redo stack becomes empty or unempty. -.PP -The undo mechanism is also linked to the modified flag. This means that -undoing or redoing changes can take a modified text widget back to the -unmodified state or vice versa. The modified flag will be set automatically to -the appropriate state. This automatic coupling does not work when the modified -flag has been set by the user, until the flag has been reset again. -.PP -See below for the \fIpathName \fBedit\fR widget command that controls the undo -mechanism. -.SH "PEER WIDGETS" -.PP -The text widget has a separate store of all its data concerning each line's -textual contents, marks, tags, images and windows, and the undo stack. -.PP -While this data store cannot be accessed directly (i.e. without a text widget -as an intermediary), multiple text widgets can be created, each of which -present different views on the same underlying data. Such text widgets are -known as peer text widgets. -.PP -As text is added, deleted, edited and coloured in any one widget, and as -images, marks, tags are adjusted, all such changes will be reflected in all -peers. -.PP -All data and markup is shared, except for a few small details. First, the -\fBsel\fR tag may be set and configured (in its display style) differently for -each peer. Second, each peer has its own \fBinsert\fR and \fBcurrent\fR mark -positions (but all other marks are shared). Third, embedded windows, which are -arbitrary other widgets, cannot be shared between peers. This means the -\fB\-window\fR option of embedded windows is independently set for each peer -(it is advisable to use the \fB\-create\fR script capabilities to allow each -peer to create its own embedded windows as needed). Fourth, all of the -configuration options of each peer (e.g. \fB\-font\fR, etc) can be set -independently, with the exception of \fB\-undo\fR, \fB\-maxundo\fR, -\fB\-autoseparators\fR (i.e. all undo, redo and modified state issues are -shared). -.PP -Finally any single peer need not contain all lines from the underlying data -store. When creating a peer, a contiguous range of lines (e.g. only lines 52 -through 125) may be specified. This allows a peer to contain just a small -portion of the overall text. The range of lines will expand and contract as -text is inserted or deleted. The peer will only ever display complete lines of -text (one cannot share just part of a line). If the peer's contents contracts -to nothing (i.e. all complete lines in the peer widget have been deleted from -another widget), then it is impossible for new lines to be inserted. The peer -will simply become an empty shell on which the background can be configured, -but which will never show any content (without manual reconfiguration of the -start and end lines). Note that a peer which does not contain all of the -underlying data store still has indices numbered from -.QW 1.0 -to -.QW end . -It is simply that those indices reflect a subset of the total data, and data -outside the contained range is not accessible to the peer. This means that the -command \fIpeerName \fBindex end\fR may return quite different values in -different peers. Similarly, commands like \fIpeerName \fBtag ranges\fR will -not return index ranges outside that which is meaningful to the peer. The -configuration options \fB\-startline\fR and \fB\-endline\fR may be used to -control how much of the underlying data is contained in any given text widget. -.PP -Note that peers are really peers. Deleting the -.QW original -text widget will not cause any other peers to be deleted, or otherwise -affected. -.PP -See below for the \fIpathName \fBpeer\fR widget command that controls the -creation of peer widgets. -.SH "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" -.PP -In order to maintain a responsive user-experience, the text widget calculates -lines metrics (line heights in pixels) asynchronously. Because of this, some -commands of the text widget may return wrong results if the asynchronous -calculations are not finished at the time of calling. This applies to -\fIpathName \fBcount -ypixels\fR and \fIpathName \fByview\fR. -.PP -Again for performance reasons, it would not be appropriate to let these -commands always wait for the end of the update calculation each time they are -called. In most use cases of these commands a more or less inaccurate result -does not really matter compared to execution speed. -.PP -In case accurate result is needed (and if the text widget is managed by a -geometry manager), one can resort to \fIpathName \fBsync\fR and \fIpathName -\fBpendingsync\fR to control the synchronization of the view of text widgets. -.PP -The \fB<<WidgetViewSync>>\fR virtual event fires when the line heights of the -text widget become obsolete (due to some editing command or configuration -change), and again when the internal data of the text widget are back in sync -with the widget view. The detail field (%d substitution) is either true (when -the widget is in sync) or false (when it is not). -.PP -\fIpathName \fBsync\fR, \fIpathName \fBpendingsync\fR and -\fB<<WidgetViewSync>>\fR apply to each text widget independently of its peers. -.PP -Examples of use: -.CS -## Example 1: -# immediately complete line metrics at any cost (GUI unresponsive) -$w sync -$w yview moveto $fraction - -## Example 2: -# synchronously wait for up-to-date line metrics (GUI responsive) -# before executing the scheduled command, but don't block execution flow -$w sync -command [list $w yview moveto $fraction] - -## Example 3: -# init -set yud($w) 0 -proc updateaction w { -\&set ::yud($w) 1 -\&# any other update action here... -} -# runtime, synchronously wait for up-to-date line metrics (GUI responsive) -$w sync -command [list updateaction $w] -vwait yud($w) -$w yview moveto $fraction - -## Example 4: -# init -set todo($w) {} -proc updateaction w { -\&foreach cmd $::todo($w) {uplevel #0 $cmd} -\&set todo($w) {} -} -# runtime -lappend todo($w) [list $w yview moveto $fraction] -$w sync -command [list updateaction $w] - -## Example 5: -# init -set todo($w) {} -bind $w <<WidgetViewSync>> { -\&if {%d} { -\&\&foreach cmd $todo(%W) {eval $cmd} -\&\&set todo(%W) {} -\&} -} -# runtime -if {![$w pendingsync]} { -\&$w yview moveto $fraction -} else { -\&lappend todo($w) [list $w yview moveto $fraction] -} -.CE -.SH "WIDGET COMMAND" -.PP -The \fBtext\fR command creates a new Tcl command whose name is the same as the -path name of the text's window. 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 -\fIPathName\fR is the name of the command, which is the same as the text -widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact -behavior of the command. The following commands are possible for text widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -. -Returns a list of four elements describing the screen area of the character -given by \fIindex\fR. The first two elements of the list give the x and y -coordinates of the upper-left corner of the area occupied by the character, -and the last two elements give the width and height of the area. If the -character is only partially visible on the screen, then the return value -reflects just the visible part. If the character is not visible on the screen -then the return value is an empty list. -.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 \fBtext\fR command. -.TP -\fIpathName \fBcompare\fR \fIindex1 op index2\fR -. -Compares the indices given by \fIindex1\fR and \fIindex2\fR according to the -relational operator given by \fIop\fR, and returns 1 if the relationship is -satisfied and 0 if it is not. \fIOp\fR must be one of the operators <, <=, ==, ->=, >, or !=. If \fIop\fR is == then 1 is returned if the two indices refer to -the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR refers -to an earlier character in the text than \fIindex2\fR, and so on. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value 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 \fBtext\fR command. -.TP -\fIpathName \fBcount\fR \fI?options\fR? \fIindex1 index2\fR -. -Counts the number of relevant things between the two indices. If \fIindex1\fR -is after \fIindex2\fR, the result will be a negative number (and this holds -for each of the possible options). The actual items which are counted depend -on the options given. The result is a list of integers, one for the result of -each counting option given. Valid counting options are \fB\-chars\fR, -\fB\-displaychars\fR, \fB\-displayindices\fR, \fB\-displaylines\fR, -\fB\-indices\fR, \fB\-lines\fR, \fB\-xpixels\fR and \fB\-ypixels\fR. The -default value, if no option is specified, is \fB\-indices\fR. There is an -additional possible option \fB\-update\fR which is a modifier. If given (and -if the text widget is managed by a geometry manager), then all subsequent -options ensure that any possible out of date information is recalculated. -This currently only has any effect for the \fB\-ypixels\fR count (which, if -\fB\-update\fR is not given, will use the text widget's current cached value -for each line). This \fB\-update\fR option is obsoleted by \fIpathName -\fBsync\fR, \fIpathName \fBpendingsync\fR and \fB<<WidgetViewSync>>\fR. The -count options are interpreted as follows: -.RS -.IP \fB\-chars\fR -count all characters, whether elided or not. Do not count embedded windows or -images. -.IP \fB\-displaychars\fR -count all non-elided characters. -.IP \fB\-displayindices\fR -count all non-elided characters, windows and images. -.IP \fB\-displaylines\fR -count all display lines (i.e. counting one for each time a line wraps) from -the line of the first index up to, but not including the display line of the -second index. Therefore if they are both on the same display line, zero will -be returned. By definition displaylines are visible and therefore this only -counts portions of actual visible lines. -.IP \fB\-indices\fR -count all characters and embedded windows or images (i.e. everything which -counts in text-widget index space), whether they are elided or not. -.IP \fB\-lines\fR -count all logical lines (irrespective of wrapping) from the line of the first -index up to, but not including the line of the second index. Therefore if they -are both on the same line, zero will be returned. Logical lines are counted -whether they are currently visible (non-elided) or not. -.IP \fB\-xpixels\fR -count the number of horizontal pixels from the first pixel of the first index -to (but not including) the first pixel of the second index. To count the total -desired width of the text widget (assuming wrapping is not enabled), first -find the longest line and then use -.QW ".text count \-xpixels \N'34'${line}.0\N'34' \N'34'${line}.0 lineend\N'34'" . -.IP \fB\-ypixels\fR -count the number of vertical pixels from the first pixel of the first index to -(but not including) the first pixel of the second index. If both indices are -on the same display line, zero will be returned. To count the total number of -vertical pixels in the text widget, use -.QW ".text count \-ypixels 1.0 end" , -and to ensure this is up to date, use -.QW ".text count \-update \-ypixels 1.0 end" . -.PP -The command returns a positive or negative integer corresponding to the number -of items counted between the two indices. One such integer is returned for -each counting option given, so a list is returned if more than one option was -supplied. For example -.QW ".text count \-xpixels \-ypixels 1.3 4.5" -is perfectly valid and will return a list of two elements. -.RE -.TP -\fIpathName \fBdebug \fR?\fIboolean\fR? -. -If \fIboolean\fR is specified, then it must have one of the true or false -values accepted by Tcl_GetBoolean. If the value is a true one then internal -consistency checks will be turned on in the B-tree code associated with text -widgets. If \fIboolean\fR has a false value then the debugging checks will be -turned off. In either case the command returns an empty string. If -\fIboolean\fR is not specified then the command returns \fBon\fR or \fBoff\fR -to indicate whether or not debugging is turned on. There is a single debugging -switch shared by all text widgets: turning debugging on or off in any widget -turns it on or off for all widgets. For widgets with large amounts of text, -the consistency checks may cause a noticeable slow-down. -.RS -.PP -When debugging is turned on, the drawing routines of the text widget set the -global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of -indices that are redrawn. The values of these variables are tested by Tk's -test suite. -.RE -.TP -\fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? -. -Delete a range of characters from the text. -If both \fIindex1\fR and \fIindex2\fR are specified, then delete -all the characters starting with the one given by \fIindex1\fR -and stopping just before \fIindex2\fR (i.e. the character at -\fIindex2\fR is not deleted). -If \fIindex2\fR does not specify a position later in the text -than \fIindex1\fR then no characters are deleted. -If \fIindex2\fR is not specified then the single character at -\fIindex1\fR is deleted. -Attempts to delete characters in a way that would leave -the text without a newline as the last character will be tweaked by the -text widget to avoid this. In particular, deletion of complete lines of -text up to the end of the text will also delete the newline character just -before the deleted block so that it is replaced by the new final newline -of the text widget. -The command returns an empty string. -If more indices are given, multiple ranges of text will be deleted. -All indices are first checked for validity before any deletions are made. -They are sorted and the text is removed from the last range to the -first range so deleted text does not cause an undesired index shifting -side-effects. If multiple ranges with the same start index are given, -then the longest range is used. If overlapping ranges are given, then -they will be merged into spans that do not cause deletion of text -outside the given ranges due to text shifted during deletion. -.TP -\fIpathName \fBdlineinfo \fIindex\fR -. -Returns a list with five elements describing the area occupied by the display -line containing \fIindex\fR. The first two elements of the list give the x and -y coordinates of the upper-left corner of the area occupied by the line, the -third and fourth elements give the width and height of the area, and the fifth -element gives the position of the baseline for the line, measured down from -the top of the area. All of this information is measured in pixels. If the -current wrap mode is \fBnone\fR and the line extends beyond the boundaries of -the window, the area returned reflects the entire area of the line, including -the portions that are out of the window. If the line is shorter than the full -width of the window then the area returned reflects just the portion of the -line that is occupied by characters and embedded windows. If the display line -containing \fIindex\fR is not visible on the screen then the return value is -an empty list. -.TP -\fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? -. -Return the contents of the text widget from \fIindex1\fR up to, but not -including \fIindex2\fR, including the text and information about marks, tags, -and embedded windows. If \fIindex2\fR is not specified, then it defaults to -one character past \fIindex1\fR. The information is returned in the following -format: -.RS -.LP -\fIkey1 value1 index1 key2 value2 index2\fR ... -.LP -The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR, -\fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding \fIvalue\fR is -the text, mark name, tag name, image name, or window name. The \fIindex\fR -information is the index of the start of the text, mark, tag transition, image -or window. One or more of the following switches (or abbreviations thereof) -may be specified to control the dump: -.TP -\fB\-all\fR -. -Return information about all elements: text, marks, tags, images and windows. -This is the default. -.TP -\fB\-command \fIcommand\fR -. -Instead of returning the information as the result of the dump operation, -invoke the \fIcommand\fR on each element of the text widget within the range. -The command has three arguments appended to it before it is evaluated: the -\fIkey\fR, \fIvalue\fR, and \fIindex\fR. -.TP -\fB\-image\fR -. -Include information about images in the dump results. -.TP -\fB\-mark\fR -. -Include information about marks in the dump results. -.TP -\fB\-tag\fR -. -Include information about tag transitions in the dump results. Tag information -is returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the begin -and end of each range of each tag, respectively. -.TP -\fB\-text\fR -. -Include information about text in the dump results. The value is the text up -to the next element or the end of range indicated by \fIindex2\fR. A text -element does not span newlines. A multi-line block of text that contains no -marks or tag transitions will still be dumped as a set of text segments that -each end with a newline. The newline is part of the value. -.TP -\fB\-window\fR -. -Include information about embedded windows in the dump results. The value of a -window is its Tk pathname, unless the window has not been created yet. (It -must have a create script.) In this case an empty string is returned, and you -must query the window by its index position to get more information. -.RE -.TP -\fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? -. -This command controls the undo mechanism and the modified flag. The exact -behavior of the command depends on the \fIoption\fR argument that follows the -\fBedit\fR argument. The following forms of the command are currently -supported: -.RS -.TP -\fIpathName \fBedit canredo\fR -. -Returns a boolean true if redo is possible, i.e. when the redo stack is not -empty. Otherwise returns false. -.TP -\fIpathName \fBedit canundo\fR -. -Returns a boolean true if undo is possible, i.e. when the undo stack is not -empty. Otherwise returns false. -.TP -\fIpathName \fBedit modified \fR?\fIboolean\fR? -. -If \fIboolean\fR is not specified, returns the modified flag of the widget. -The insert, delete, edit undo and edit redo commands or the user can set or -clear the modified flag. If \fIboolean\fR is specified, sets the modified flag -of the widget to \fIboolean\fR. -.TP -\fIpathName \fBedit redo\fR -. -When the \fB\-undo\fR option is true, reapplies the last undone edits provided -no other edits were done since then. Generates an error when the redo stack is -empty. Does nothing when the \fB\-undo\fR option is false. -.TP -\fIpathName \fBedit reset\fR -. -Clears the undo and redo stacks. -.TP -\fIpathName \fBedit separator\fR -. -Inserts a separator (boundary) on the undo stack. Does nothing when the -\fB\-undo\fR option is false. -.TP -\fIpathName \fBedit undo\fR -. -Undoes the last edit action when the \fB\-undo\fR option is true. An edit -action is defined as all the insert and delete commands that are recorded on -the undo stack in between two separators. Generates an error when the undo -stack is empty. Does nothing when the \fB\-undo\fR option is false. -.RE -.TP -\fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? -. -Return a range of characters from the text. The return value will be all the -characters in the text starting with the one whose index is \fIindex1\fR and -ending just before the one whose index is \fIindex2\fR (the character at -\fIindex2\fR will not be returned). If \fIindex2\fR is omitted then the single -character at \fIindex1\fR is returned. If there are no characters in the -specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR -is less than or equal to \fIindex1\fR) then an empty string is returned. If -the specified range contains embedded windows, no information about them is -included in the returned string. If multiple index pairs are given, multiple -ranges of text will be returned in a list. Invalid ranges will not be -represented with empty strings in the list. The ranges are returned in the -order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is -given, then, within each range, only those characters which are not elided -will be returned. This may have the effect that some of the returned ranges -are empty strings. -.TP -\fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? -. -This command is used to manipulate embedded images. The behavior of the -command depends on the \fIoption\fR argument that follows the \fBtag\fR -argument. The following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBimage cget \fIindex option\fR -. -Returns the value of a configuration option for an embedded image. \fIIndex\fR -identifies the embedded image, and \fIoption\fR specifies a particular -configuration option, which must be one of the ones listed in the section -\fBEMBEDDED IMAGES\fR. -.TP -\fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? -. -Query or modify the configuration options for an embedded image. If no -\fIoption\fR is specified, returns a list describing all of the available -options for the embedded image at \fIindex\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. See -\fBEMBEDDED IMAGES\fR for information on the options that are supported. -.TP -\fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? -. -This command creates a new image annotation, which will appear in the text at -the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may -be specified to configure the annotation. Returns a unique identifier that may -be used as an index to refer to this image. See \fBEMBEDDED IMAGES\fR for -information on the options that are supported, and a description of the -identifier returned. -.TP -\fIpathName \fBimage names\fR -. -Returns a list whose elements are the names of all image instances currently -embedded in \fIwindow\fR. -.RE -.TP -\fIpathName \fBindex \fIindex\fR -. -Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR -where \fIline\fR is the line number and \fIchar\fR is the character number. -\fIIndex\fR may have any of the forms described under \fBINDICES\fR above. -.TP -\fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? -. -Inserts all of the \fIchars\fR arguments just before the character at -\fIindex\fR. If \fIindex\fR refers to the end of the text (the character after -the last newline) then the new text is inserted just before the last newline -instead. If there is a single \fIchars\fR argument and no \fItagList\fR, then -the new text will receive any tags that are present on both the character -before and the character after the insertion point; if a tag is present on -only one of these characters then it will not be applied to the new text. If -\fItagList\fR is specified then it consists of a list of tag names; the new -characters will receive all of the tags in this list and no others, regardless -of the tags present around the insertion point. If multiple -\fIchars\fR\-\fItagList\fR argument pairs are present, they produce the same -effect as if a separate \fIpathName \fBinsert\fR widget command had been -issued for each pair, in order. The last \fItagList\fR argument may be -omitted. -.TP -\fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR? -. -This command is used to manipulate marks. The exact behavior of the command -depends on the \fIoption\fR argument that follows the \fBmark\fR argument. The -following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR? -. -If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR to -indicate which of its adjacent characters \fImarkName\fR is attached to. If -\fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; the -gravity of \fImarkName\fR is set to the given value. -.TP -\fIpathName \fBmark names\fR -. -Returns a list whose elements are the names of all the marks that are -currently set. -.TP -\fIpathName \fBmark next \fIindex\fR -. -Returns the name of the next mark at or after \fIindex\fR. If \fIindex\fR is -specified in numerical form, then the search for the next mark begins at that -index. If \fIindex\fR is the name of a mark, then the search for the next mark -begins immediately after that mark. This can still return a mark at the same -position if there are multiple marks at the same index. These semantics mean -that the \fBmark next\fR operation can be used to step through all the marks -in a text widget in the same order as the mark information returned by the -\fIpathName \fBdump\fR operation. If a mark has been set to the special -\fBend\fR index, then it appears to be \fIafter\fR \fBend\fR with respect to -the \fIpathName \fBmark next\fR operation. An empty string is returned if -there are no marks after \fIindex\fR. -.TP -\fIpathName \fBmark previous \fIindex\fR -. -Returns the name of the mark at or before \fIindex\fR. If \fIindex\fR is -specified in numerical form, then the search for the previous mark begins with -the character just before that index. If \fIindex\fR is the name of a mark, -then the search for the next mark begins immediately before that mark. This -can still return a mark at the same position if there are multiple marks at -the same index. These semantics mean that the \fIpathName \fBmark previous\fR -operation can be used to step through all the marks in a text widget in the -reverse order as the mark information returned by the \fIpathName \fBdump\fR -operation. An empty string is returned if there are no marks before -\fIindex\fR. -.TP -\fIpathName \fBmark set \fImarkName index\fR -. -Sets the mark named \fImarkName\fR to a position just before the character at -\fIindex\fR. If \fImarkName\fR already exists, it is moved from its old -position; if it does not exist, a new mark is created. This command returns an -empty string. -.TP -\fIpathName \fBmark unset \fImarkName \fR?\fImarkName markName ...\fR? -. -Remove the mark corresponding to each of the \fImarkName\fR arguments. The -removed marks will not be usable in indices and will not be returned by future -calls to -.QW "\fIpathName \fBmark names\fR" . -This command returns an empty string. -.RE -.TP -\fIpathName \fBpeer \fIoption args\fR -. -This command is used to create and query widget peers. It has two forms, -depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBpeer create \fInewPathName\fR ?\fIoptions\fR? -. -Creates a peer text widget with the given \fInewPathName\fR, and any optional -standard configuration options (as for the \fItext\fR command). By default the -peer will have the same start and end line as the parent widget, but these can -be overridden with the standard configuration options. -.TP -\fIpathName \fBpeer names\fR -. -Returns a list of peers of this widget (this does not include the widget -itself). The order within this list is undefined. -.RE -.TP -\fIpathName \fBpendingsync\fR -Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. -.TP -\fIpathName \fBreplace\fR \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR? -Replaces the range of characters between \fIindex1\fR and \fIindex2\fR -with the given characters and tags. See the section on \fIpathName -\fBinsert\fR for an explanation of the handling of the \fItagList...\fR -arguments, and the section on \fIpathName -\fBdelete\fR for an explanation of the handling of the indices. If -\fIindex2\fR corresponds to an index earlier in the text than -\fIindex1\fR, an error will be generated. -.RS -.PP -The deletion and insertion are arranged so that no unnecessary scrolling of -the window or movement of insertion cursor occurs. In addition the undo/redo -stack are correctly modified, if undo operations are active in the text -widget. The command returns an empty string. -.RE -.TP -\fIpathName \fBscan \fIoption args\fR -. -This command is used to implement scanning on texts. It has two forms, -depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -. -Records \fIx\fR and \fIy\fR and the current view in the text window, for use -in conjunction with later \fIpathName \fBscan dragto\fR commands. Typically -this command is associated with a mouse button press in the widget. It returns -an empty string. -.TP -\fIpathName \fBscan dragto \fIx y\fR -. -This command computes the difference between its \fIx\fR and \fIy\fR arguments -and the \fIx\fR and \fIy\fR arguments to the last \fIpathName \fBscan mark\fR -command for the widget. It then adjusts the view by 10 times the difference in -coordinates. This command is typically associated with mouse motion events in -the widget, to produce the effect of dragging the text at high speed through -the window. The return value is an empty string. -.RE -.TP -\fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? -. -Searches the text in \fIpathName\fR starting at \fIindex\fR for a range of -characters that matches \fIpattern\fR. If a match is found, the index of the -first character in the match is returned as result; otherwise an empty string -is returned. One or more of the following switches (or abbreviations thereof) -may be specified to control the search: -.RS -.TP -\fB\-forwards\fR -. -The search will proceed forward through the text, finding the first matching -range starting at or after the position given by \fIindex\fR. This is the -default. -.TP -\fB\-backwards\fR -. -The search will proceed backward through the text, finding the matching range -closest to \fIindex\fR whose first character is before \fIindex\fR (it is not -allowed to be at \fIindex\fR). Note that, for a variety of reasons, backwards -searches can be substantially slower than forwards searches (particularly when -using \fB\-regexp\fR), so it is recommended that performance-critical code use -forward searches. -.TP -\fB\-exact\fR -. -Use exact matching: the characters in the matching range must be identical to -those in \fIpattern\fR. This is the default. -.TP -\fB\-regexp\fR -. -Treat \fIpattern\fR as a regular expression and match it against the text -using the rules for regular expressions (see the \fBregexp\fR command -and the \fBre_syntax\fR page for -details). The default matching automatically passes both the -\fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless -\fB\-nolinestop\fR is used), so that \fI^$\fR match beginning and end of line, -and \fI.\fR, \fI[^\fR sequences will never match the newline character -\fI\en\fR. -.TP -\fB\-nolinestop\fR -. -This allows \fI.\fR and \fI[^\fR sequences to match the newline character -\fI\en\fR, which they will otherwise not do (see the \fBregexp\fR command for -details). This option is only meaningful if \fB\-regexp\fR is also given, and -an error will be thrown otherwise. For example, to match the entire text, use -.QW "\fIpathName \fBsearch \-nolinestop \-regexp\fR \N'34'.*\N'34' 1.0" . -.TP -\fB\-nocase\fR -. -Ignore case differences between the pattern and the text. -.TP -\fB\-count\fI varName\fR -. -The argument following \fB\-count\fR gives the name of a variable; if a match -is found, the number of index positions between beginning and end of the -matching range will be stored in the variable. If there are no embedded images -or windows in the matching range (and there are no elided characters if -\fB\-elide\fR is not given), this is equivalent to the number of characters -matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count -chars\fR will return the entire matched text. -.TP -\fB\-all\fR -. -Find all matches in the given range and return a list of the indices of the -first character of each match. If a \fB\-count\fI varName\fR switch is given, -then \fIvarName\fR is also set to a list containing one element for each -successful match. Note that, even for exact searches, the elements of this -list may be different, if there are embedded images, windows or hidden text. -Searches with \fB\-all\fR behave very similarly to the Tcl command \fBregexp -\-all\fR, in that overlapping matches are not normally returned. For example, -applying an \fB\-all\fR search of the pattern -.QW \ew+ -against -.QW "hello there" -will just match twice, once for each word, and matching -.QW "Z[a\-z]+Z" -against -.QW ZooZooZoo -will just match once. -.TP -\fB\-overlap\fR -. -When performing \fB\-all\fR searches, the normal behaviour is that matches -which overlap an already-found match will not be returned. This switch changes -that behaviour so that all matches which are not totally enclosed within -another match are returned. For example, applying an \fB\-overlap\fR search of -the pattern -.QW \ew+ -against -.QW "hello there" -will just match twice (i.e. no different to just \fB\-all\fR), but matching -.QW Z[a\-z]+Z -against -.QW ZooZooZoo -will now match twice. An error will be thrown if this switch is used without -\fB\-all\fR. -.TP -\fB\-strictlimits\fR -. -When performing any search, the normal behaviour is that the start and stop -limits are checked with respect to the start of the matching text. With the -\fB\-strictlimits\fR flag, the entire matching range must lie inside the start -and stop limits specified for the match to be valid. -.TP -\fB\-elide\fR -. -Find elided (hidden) text as well. By default only displayed text is searched. -.TP -\fB\-\|\-\fR -. -This switch has no effect except to terminate the list of switches: the next -argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. -.PP -The matching range may be within a single line of text, or run across multiple -lines (if parts of the pattern can match a new-line). For regular expression -matching one can use the various newline-matching features such as \fB$\fR to -match the end of a line, \fB^\fR to match the beginning of a line, and to -control whether \fB.\fR is allowed to match a new-line. If \fIstopIndex\fR is -specified, the search stops at that index: for forward searches, no match at -or after \fIstopIndex\fR will be considered; for backward searches, no match -earlier in the text than \fIstopIndex\fR will be considered. If -\fIstopIndex\fR is omitted, the entire text will be searched: when the -beginning or end of the text is reached, the search continues at the other end -until the starting location is reached again; if \fIstopIndex\fR is specified, -no wrap-around will occur. This means that, for example, if the search is -\fB\-forwards\fR but \fIstopIndex\fR is earlier in the text than -\fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a -number of minor limitations of the \fIpathName \fBsearch\fR command. -.RE -.TP -\fIpathName \fBsee \fIindex\fR -. -Adjusts the view in the window so that the character given by \fIindex\fR is -completely visible. If \fIindex\fR is already visible then the command does -nothing. If \fIindex\fR is a short distance out of view, the command adjusts -the view just enough to make \fIindex\fR visible at the edge of the window. -If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the -window. -.TP -\fIpathName \fBsync\fR ?\fB-command \fIcommand\fR? -Controls the synchronization of the view of the text widget. -.RS -.TP -\fIpathName \fBsync\fR -Immediately brings the line metrics up-to-date by forcing computation of any -outdated line heights. The command returns immediately if there is no such -outdated line heights, otherwise it returns only at the end of the computation. -The command returns an empty string. -.TP -\fIpathName \fBsync -command \fIcommand\fR -Schedules \fIcommand\fR to be executed (by the event loop) exactly once as soon -as all line heights are up-to-date. If there are no pending line metrics -calculations, the scheduling is immediate. The command returns the empty -string. \fBbgerror\fR is called on \fIcommand\fR failure. -.RE -.TP -\fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR? -. -This command is used to manipulate tags. The exact behavior of the command -depends on the \fIoption\fR argument that follows the \fBtag\fR argument. The -following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBtag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -. -Associate the tag \fItagName\fR with all of the characters starting with -\fIindex1\fR and ending just before \fIindex2\fR (the character at -\fIindex2\fR is not tagged). A single command may contain any number of -\fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the -single character at \fIindex1\fR is tagged. If there are no characters in the -specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR -is less than or equal to \fIindex1\fR) then the command has no effect. -.TP -\fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? -. -This command associates \fIscript\fR with the tag given by \fItagName\fR. -Whenever the event sequence given by \fIsequence\fR occurs for a character -that has been tagged with \fItagName\fR, the script will be invoked. This -widget command is similar to the \fBbind\fR command except that it operates on -characters in a text rather than entire widgets. See the \fBbind\fR manual -entry for complete details on the syntax of \fIsequence\fR and the -substitutions performed on \fIscript\fR before invoking it. If all arguments -are specified then a new binding is created, replacing any existing binding -for the same \fIsequence\fR and \fItagName\fR (if the first character of -\fIscript\fR is -.QW + -then \fIscript\fR augments an existing binding rather than replacing it). In -this case the return value is an empty string. If \fIscript\fR is omitted then -the command returns the \fIscript\fR associated with \fItagName\fR and -\fIsequence\fR (an error occurs if there is no such binding). If both -\fIscript\fR and \fIsequence\fR are omitted then the command returns a list of -all the sequences for which bindings have been defined for \fItagName\fR. -.RS -.PP -The only events for which bindings may be specified are those related to the -mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, -\fBMotion\fR, and \fBKeyPress\fR) or virtual events. Event bindings for a text -widget use the \fBcurrent\fR mark described under \fBMARKS\fR above. An -\fBEnter\fR event triggers for a tag when the tag first becomes present on the -current character, and a \fBLeave\fR event triggers for a tag when it ceases -to be present on the current character. \fBEnter\fR and \fBLeave\fR events can -happen either because the \fBcurrent\fR mark moved or because the character at -that position changed. Note that these events are different than \fBEnter\fR -and \fBLeave\fR events for windows. Mouse and keyboard events are directed to -the current character. If a virtual event is used in a binding, that binding -can trigger only if the virtual event is defined by an underlying -mouse-related or keyboard-related event. -.PP -It is possible for the current character to have multiple tags, and for each -of them to have a binding for a particular event sequence. When this occurs, -one binding is invoked for each tag, in order from lowest-priority to highest -priority. If there are multiple matching bindings for a single tag, then the -most specific binding is chosen (see the manual entry for the \fBbind\fR -command for details). \fBcontinue\fR and \fBbreak\fR commands within binding -scripts are processed in the same way as for bindings created with the -\fBbind\fR command. -.PP -If bindings are created for the widget as a whole using the \fBbind\fR -command, then those bindings will supplement the tag bindings. The tag -bindings will be invoked first, followed by bindings for the window as a -whole. -.RE -.TP -\fIpathName \fBtag cget \fItagName option\fR -. -This command returns the current value of the option named \fIoption\fR -associated with the tag given by \fItagName\fR. \fIOption\fR may have any of -the values accepted by the \fIpathName \fBtag configure\fR widget command. -.TP -\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -. -This command is similar to the \fIpathName \fBconfigure\fR widget command -except that it modifies options associated with the tag given by \fItagName\fR -instead of modifying options for the overall text widget. If no \fIoption\fR -is specified, the command returns a list describing all of the available -options for \fItagName\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 \fItagName\fR; in this case the command returns an empty string. -See \fBTAGS\fR above for details on the options available for tags. -.TP -\fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR? -. -Deletes all tag information for each of the \fItagName\fR arguments. The -command removes the tags from all characters in the file and also deletes any -other information associated with the tags, such as bindings and display -information. The command returns an empty string. -.TP -\fIpathName\fB tag lower \fItagName \fR?\fIbelowThis\fR? -. -Changes the priority of tag \fItagName\fR so that it is just lower in priority -than the tag whose name is \fIbelowThis\fR. If \fIbelowThis\fR is omitted, -then \fItagName\fR's priority is changed to make it lowest priority of all -tags. -.TP -\fIpathName \fBtag names \fR?\fIindex\fR? -. -Returns a list whose elements are the names of all the tags that are active at -the character position given by \fIindex\fR. If \fIindex\fR is omitted, then -the return value will describe all of the tags that exist for the text (this -includes all tags that have been named in a -.QW "\fIpathName \fBtag\fR" -widget command but have not been deleted by a -.QW "\fIpathName \fBtag delete\fR" -widget command, even if no characters are currently marked with the tag). The -list will be sorted in order from lowest priority to highest priority. -.TP -\fIpathName \fBtag nextrange \fItagName index1 \fR?\fIindex2\fR? -. -This command searches the text for a range of characters tagged with -\fItagName\fR where the first character of the range is no earlier than the -character at \fIindex1\fR and no later than the character just before -\fIindex2\fR (a range starting at \fIindex2\fR will not be considered). If -several matching ranges exist, the first one is chosen. The command's return -value is a list containing two elements, which are the index of the first -character of the range and the index of the character just after the last one -in the range. If no matching range is found then the return value is an empty -string. If \fIindex2\fR is not given then it defaults to the end of the text. -.TP -\fIpathName \fBtag prevrange \fItagName index1 \fR?\fIindex2\fR? -. -This command searches the text for a range of characters tagged with -\fItagName\fR where the first character of the range is before the character -at \fIindex1\fR and no earlier than the character at \fIindex2\fR (a range -starting at \fIindex2\fR will be considered). If several matching ranges -exist, the one closest to \fIindex1\fR is chosen. The command's return value -is a list containing two elements, which are the index of the first character -of the range and the index of the character just after the last one in the -range. If no matching range is found then the return value is an empty string. -If \fIindex2\fR is not given then it defaults to the beginning of the text. -.TP -\fIpathName\fB tag raise \fItagName \fR?\fIaboveThis\fR? -. -Changes the priority of tag \fItagName\fR so that it is just higher in -priority than the tag whose name is \fIaboveThis\fR. If \fIaboveThis\fR is -omitted, then \fItagName\fR's priority is changed to make it highest priority -of all tags. -.TP -\fIpathName \fBtag ranges \fItagName\fR -. -Returns a list describing all of the ranges of text that have been tagged with -\fItagName\fR. The first two elements of the list describe the first tagged -range in the text, the next two elements describe the second range, and so on. -The first element of each pair contains the index of the first character of -the range, and the second element of the pair contains the index of the -character just after the last one in the range. If there are no characters -tagged with \fItag\fR then an empty string is returned. -.TP -\fIpathName \fBtag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -. -Remove the tag \fItagName\fR from all of the characters starting at -\fIindex1\fR and ending just before \fIindex2\fR (the character at -\fIindex2\fR is not affected). A single command may contain any number of -\fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the -tag is removed from the single character at \fIindex1\fR. If there are no -characters in the specified range (e.g. \fIindex1\fR is past the end of the -file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command -has no effect. This command returns an empty string. -.RE -.TP -\fIpathName \fBwindow \fIoption \fR?\fIarg arg ...\fR? -. -This command is used to manipulate embedded windows. The behavior of the -command depends on the \fIoption\fR argument that follows the \fBwindow\fR -argument. The following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBwindow cget \fIindex option\fR -. -Returns the value of a configuration option for an embedded window. -\fIIndex\fR identifies the embedded window, and \fIoption\fR specifies a -particular configuration option, which must be one of the ones listed in the -section \fBEMBEDDED WINDOWS\fR. -.TP -\fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? -. -Query or modify the configuration options for an embedded window. If no -\fIoption\fR is specified, returns a list describing all of the available -options for the embedded window at \fIindex\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. See -\fBEMBEDDED WINDOWS\fR for information on the options that are supported. -.TP -\fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR? -. -This command creates a new window annotation, which will appear in the text at -the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may -be specified to configure the annotation. See \fBEMBEDDED WINDOWS\fR for -information on the options that are supported. Returns an empty string. -.TP -\fIpathName \fBwindow names\fR -. -Returns a list whose elements are the names of all windows currently embedded -in \fIwindow\fR. -.RE -.TP -\fIpathName \fBxview \fIoption args\fR -. -This command is used to query and change the horizontal position of the text -in the widget's window. It can take any of the following forms: -.RS -.TP -\fIpathName \fBxview\fR -. -Returns a list containing two elements. Each element is a real fraction -between 0 and 1; together they describe the portion of the document's -horizontal span that is visible in the window. For example, if the first -element is .2 and the second element is .6, 20% of the text is off-screen to -the left, the middle 40% is visible in the window, and 40% of the text is -off-screen to the right. The fractions refer only to the lines that are -actually visible in the window: if the lines in the window are all very short, -so that they are entirely visible, the returned fractions will be 0 and 1, -even if there are other lines in the text that are much wider than the window. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -. -Adjusts the view in the window so that \fIfraction\fR of the horizontal span -of the text is off-screen to the left. \fIFraction\fR is a fraction between 0 -and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -. -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or -\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR -must be an integer, otherwise number may be specified in any of the forms -acceptable to \fBTk_GetPixels\fR, such as -.QW 2.0c -or -.QW 1i -(the result is rounded to the nearest integer value. If no units are given, -pixels are assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts left or -right by \fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is -\fBpixels\fR then the view adjusts by \fInumber\fR pixels. If \fInumber\fR is -negative then characters farther to the left become visible; if it is positive -then characters farther to the right become visible. -.RE -.TP -\fIpathName \fByview \fR?\fIargs\fR? -. -This command is used to query and change the vertical position of the text in -the widget's window. It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -. -Returns a list containing two elements, both of which are real fractions -between 0 and 1. The first element gives the position of the first visible -pixel of the first character (or image, etc) in the top line in the window, -relative to the text as a whole (0.5 means it is halfway through the text, for -example). The second element gives the position of the first pixel just after -the last visible one in the bottom line of the window, relative to the text as -a whole. These are the same values passed to scrollbars via the -\fB\-yscrollcommand\fR option. -.TP -\fIpathName \fByview moveto\fI fraction\fR -. -Adjusts the view in the window so that the pixel given by \fIfraction\fR -appears at the top of the top line of the window. \fIFraction\fR is a fraction -between 0 and 1; 0 indicates the first pixel of the first character in the -text, 0.33 indicates the pixel that is one-third the way through the text; and -so on. Values close to 1 will indicate values close to the last pixel in the -text (1 actually refers to one pixel beyond the last pixel), but in such cases -the widget will never scroll beyond the last pixel, and so a value of 1 will -effectively be rounded back to whatever fraction ensures the last pixel is at -the bottom of the window, and some other pixel is at the top. -.TP -\fIpathName \fByview scroll \fInumber what\fR -. -This command adjust the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or -\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR -must be an integer, otherwise number may be specified in any of the forms -acceptable to \fBTk_GetPixels\fR, such as -.QW 2.0c -or -.QW 1i -(the result is rounded to the nearest integer value. If no units are given, -pixels are assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts up or down -by \fInumber\fR lines on the display; if it is \fBpages\fR then the view -adjusts by \fInumber\fR screenfuls; if it is \fBpixels\fR then the view -adjusts by \fInumber\fR pixels. If \fInumber\fR is negative then earlier -positions in the text become visible; if it is positive then later positions -in the text become visible. -.TP -\fIpathName \fByview \fR?\fB\-pickplace\fR? \fIindex\fR -. -Changes the view in the widget's window to make \fIindex\fR visible. If the -\fB\-pickplace\fR option is not specified then \fIindex\fR will appear at the -top of the window. If \fB\-pickplace\fR is specified then the widget chooses -where \fIindex\fR appears in the window: -.RS -.IP [1] -If \fIindex\fR is already visible somewhere in the window then the command -does nothing. -.IP [2] -If \fIindex\fR is only a few lines off-screen above the window then it will be -positioned at the top of the window. -.IP [3] -If \fIindex\fR is only a few lines off-screen below the window then it will be -positioned at the bottom of the window. -.IP [4] -Otherwise, \fIindex\fR will be centered in the window. -.PP -The \fB\-pickplace\fR option has been obsoleted by the \fIpathName \fBsee\fR -widget command (\fIpathName \fBsee\fR handles both x- and y-motion to make a -location visible, whereas the \fB\-pickplace\fR mode only handles motion in -y). -.RE -.TP -\fIpathName \fByview \fInumber\fR -. -This command makes the first character on the line after the one given by -\fInumber\fR visible at the top of the window. \fINumber\fR must be an -integer. This command used to be used for scrolling, but now it is obsolete. -.RE -.SH BINDINGS -.PP -Tk automatically creates class bindings for texts that give them the following -default behavior. In the descriptions below, -.QW word -is dependent on the value of the \fBtcl_wordchars\fR variable. See -\fBtclvars\fR(n). -.IP [1] -Clicking mouse button 1 positions the insertion cursor just before the -character underneath the mouse cursor, sets the input focus to this widget, -and clears any selection in the widget. Dragging with mouse button 1 strokes -out a selection between the insertion cursor and the character under the -mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse and -positions the insertion cursor at the start of the word. Dragging after a -double click will stroke out a selection consisting of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects the line under the mouse and -positions the insertion cursor at the start of the line. Dragging after a -triple click will stroke out a selection consisting of whole lines. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse button 1 -while the Shift key is down; this will adjust the end of the selection that -was nearest to the mouse cursor when button 1 was pressed. If the button is -double-clicked before dragging then the selection will be adjusted in units of -whole words; if it is triple-clicked then the selection will be adjusted in -units of whole lines. -.IP [5] -Clicking mouse button 1 with the Control key down will reposition the -insertion cursor without affecting the selection. -.IP [6] -If any normal printing characters are typed, they are inserted at the point of -the insertion cursor. -.IP [7] -The view in the widget can be adjusted by dragging with mouse button 2. If -mouse button 2 is clicked without moving the mouse, the selection is copied -into the text at the position of the mouse cursor. The Insert key also inserts -the selection, but at the position of the insertion cursor. -.IP [8] -If the mouse is dragged out of the widget while button 1 is pressed, the entry -will automatically scroll to make more text visible (if there is more text -off-screen on the side where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the left or -right; they also clear any selection in the text. If Left or Right is typed -with the Shift key down, then the insertion cursor moves and the selection is -extended to include the new character. Control-Left and Control-Right move the -insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move -the insertion cursor by words and also extend the selection. Control-b and -Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f -behave the same as Control-Left and Control-Right, respectively. -.IP [10] -The Up and Down keys move the insertion cursor one line up or down and clear -any selection in the text. If Up or Right is typed with the Shift key down, -then the insertion cursor moves and the selection is extended to include the -new character. Control-Up and Control-Down move the insertion cursor by -paragraphs (groups of lines separated by blank lines), and Control-Shift-Up -and Control-Shift-Down move the insertion cursor by paragraphs and also extend -the selection. Control-p and Control-n behave the same as Up and Down, -respectively. -.IP [11] -The Next and Prior keys move the insertion cursor forward or backwards by one -screenful and clear any selection in the text. If the Shift key is held down -while Next or Prior is typed, then the selection is extended to include the -new character. -.IP [12] -Control-Next and Control-Prior scroll the view right or left by one page -without moving the insertion cursor or affecting the selection. -.IP [13] -Home and Control-a move the insertion cursor to the beginning of its display -line and clear any selection in the widget. Shift-Home moves the insertion -cursor to the beginning of the display line and also extends the selection to -that point. -.IP [14] -End and Control-e move the insertion cursor to the end of the display line and -clear any selection in the widget. Shift-End moves the cursor to the end of -the display line and extends the selection to that point. -.IP [15] -Control-Home and Meta-< move the insertion cursor to the beginning of the text -and clear any selection in the widget. Control-Shift-Home moves the insertion -cursor to the beginning of the text and also extends the selection to that -point. -.IP [16] -Control-End and Meta-> move the insertion cursor to the end of the text and -clear any selection in the widget. Control-Shift-End moves the cursor to the -end of the text and extends the selection to that point. -.IP [17] -The Select key and Control-Space set the selection anchor to the position of -the insertion cursor. They do not affect the current selection. Shift-Select -and Control-Shift-Space adjust the selection to the current position of the -insertion cursor, selecting from the anchor to the insertion cursor if there -was not any selection previously. -.IP [18] -Control-/ selects the entire contents of the widget. -.IP [19] -Control-\e clears any selection in the widget. -.IP [20] -The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the -selection in the widget to the clipboard, if there is a selection. This -action is carried out by the command \fBtk_textCopy\fR. -.IP [21] -The F20 key (labelled Cut on many Sun workstations) or Control-w copies the -selection in the widget to the clipboard and deletes the selection. This -action is carried out by the command \fBtk_textCut\fR. If there is no -selection in the widget then these keys have no effect. -.IP [22] -The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the -contents of the clipboard at the position of the insertion cursor. This action -is carried out by the command \fBtk_textPaste\fR. -.IP [23] -The Delete key deletes the selection, if there is one in the widget. If there -is no selection, it deletes the character to the right of the insertion -cursor. -.IP [24] -Backspace and Control-h delete the selection, if there is one in the widget. -If there is no selection, they delete the character to the left of the -insertion cursor. -.IP [25] -Control-d deletes the character to the right of the insertion cursor. -.IP [26] -Meta-d deletes the word to the right of the insertion cursor. -.IP [27] -Control-k deletes from the insertion cursor to the end of its line; if the -insertion cursor is already at the end of a line, then Control-k deletes the -newline character. -.IP [28] -Control-o opens a new line by inserting a newline character in front of the -insertion cursor without moving the insertion cursor. -.IP [29] -Meta-backspace and Meta-Delete delete the word to the left of the insertion -cursor. -.IP [30] -Control-x deletes whatever is selected in the text widget after copying it to -the clipboard. -.IP [31] -Control-t reverses the order of the two characters to the right of the -insertion cursor. -.IP [32] -Control-z undoes the last edit action if the \fB\-undo\fR option is true. -Does nothing otherwise. -.IP [33] -Control-Z (or Control-y on Windows) reapplies the last undone edit action if -the \fB\-undo\fR option is true. Does nothing otherwise. -.PP -If the widget is disabled using the \fB\-state\fR option, then its view can -still be adjusted and text can still be selected, but no insertion cursor will -be displayed and no text modifications will take place. -.PP -The behavior of texts can be changed by defining new bindings for individual -widgets or by redefining the class bindings. -.SH "KNOWN ISSUES" -.SS "ISSUES CONCERNING CHARS AND INDICES" -.PP -Before Tk 8.5, the widget used the string -.QW chars -to refer to index positions (which included characters, embedded windows and -embedded images). As of Tk 8.5 the text widget deals separately and correctly -with -.QW chars -and -.QW indices . -For backwards compatibility, however, the index modifiers -.QW "+N chars" -and -.QW "\-N chars" -continue to refer to indices. One must use any of the full forms -.QW "+N any chars" -or -.QW "\-N any chars" -etc. to refer to actual character indices. This confusion may be fixed in a -future release by making the widget correctly interpret -.QW "+N chars" -as a synonym for -.QW "+N any chars" . -.SS "PERFORMANCE ISSUES" -.PP -Text widgets should run efficiently under a variety of conditions. The text -widget uses about 2-3 bytes of main memory for each byte of text, so texts -containing a megabyte or more should be practical on most workstations. Text -is represented internally with a modified B-tree structure that makes -operations relatively efficient even with large texts. Tags are included in -the B-tree structure in a way that allows tags to span large ranges or have -many disjoint smaller ranges without loss of efficiency. Marks are also -implemented in a way that allows large numbers of marks. In most cases it is -fine to have large numbers of unique tags, or a tag that has many distinct -ranges. -.PP -One performance problem can arise if you have hundreds or thousands of -different tags that all have the following characteristics: the first and last -ranges of each tag are near the beginning and end of the text, respectively, -or a single tag range covers most of the text widget. The cost of adding and -deleting tags like this is proportional to the number of other tags with the -same properties. In contrast, there is no problem with having thousands of -distinct tags if their overall ranges are localized and spread uniformly -throughout the text. -.PP -Very long text lines can be expensive, especially if they have many marks and -tags within them. -.PP -The display line with the insert cursor is redrawn each time the cursor -blinks, which causes a steady stream of graphics traffic. Set the -\fB\-insertofftime\fR attribute to 0 avoid this. -.SS "KNOWN BUGS" -.PP -The \fIpathName \fBsearch \-regexp\fR sub-command attempts to perform -sophisticated regexp matching across multiple lines in an efficient fashion -(since Tk 8.5), examining each line individually, and then in small groups of -lines, whether searching forwards or backwards. Under certain conditions the -search result might differ from that obtained by applying the same regexp to -the entire text from the widget in one go. For example, when searching with a -greedy regexp, the widget will continue to attempt to add extra lines to the -match as long as one of two conditions are true: either Tcl's regexp library -returns a code to indicate a longer match is possible (but there are known -bugs in Tcl which mean this code is not always correctly returned); or if each -extra line added results in at least a partial match with the pattern. This -means in the case where the first extra line added results in no match and -Tcl's regexp system returns the incorrect code and adding a second extra line -would actually match, the text widget will return the wrong result. In -practice this is a rare problem, but it can occur, for example: -.CS -pack [\fBtext\fR .t] -\&.t insert 1.0 "aaaa\enbbbb\encccc\enbbbb\enaaaa\en" -\&.t search \-regexp \-\- {(a+|b+\enc+\enb+)+\ena+} 1.0 -.CE -will not find a match when one exists of 19 characters starting from the first -.QW b . -.PP -Whenever one possible match is fully enclosed in another, the search command -will attempt to ensure only the larger match is returned. When performing -backwards regexp searches it is possible that Tcl will not always achieve -this, in the case where a match is preceded by one or more short, -non-overlapping matches, all of which are preceded by a large match which -actually encompasses all of them. The search algorithm used by the widget does -not look back arbitrarily far for a possible match which might cover large -portions of the widget. For example: -.CS -pack [\fBtext\fR .t] -\&.t insert 1.0 "aaaa\enbbbb\enbbbb\enbbbb\enbbbb\\n" -\&.t search \-regexp \-backward \-\- {b+\en|a+\en(b+\en)+} end -.CE -matches at -.QW 5.0 -when a true greedy match would match at -.QW 1.0 . -Similarly if we add \fB\-all\fR to this case, it matches at all of -.QW 5.0 , -.QW 4.0 , -.QW 3.0 -and -.QW 1.0 , -when really it should only match at -.QW 1.0 -since that match encloses all the others. -.SH "SEE ALSO" -entry(n), scrollbar(n) -.SH KEYWORDS -text, widget, tkvars -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/tk.n b/tk8.6/doc/tk.n deleted file mode 100644 index 1165b67..0000000 --- a/tk8.6/doc/tk.n +++ /dev/null @@ -1,135 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk \- Manipulate Tk internal state -.SH SYNOPSIS -\fBtk\fR \fIoption \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBtk\fR command provides access to miscellaneous -elements of Tk's internal state. -Most of the information manipulated by this command pertains to the -application as a whole, or to a screen or display, rather than to a -particular window. -The command can take any of a number of different forms -depending on the \fIoption\fR argument. The legal forms are: -.TP -\fBtk appname \fR?\fInewName\fR? -. -If \fInewName\fR is not specified, this command returns the name -of the application (the name that may be used in \fBsend\fR -commands to communicate with the application). -If \fInewName\fR is specified, then the name of the application -is changed to \fInewName\fR. -If the given name is already in use, then a suffix of the form -.QW "\fB #2\fR" -or -.QW "\fB #3\fR" -is appended in order to make the name unique. -The command's result is the name actually chosen. -\fInewName\fR should not start with a capital letter. -This will interfere with option processing, since names starting with -capitals are assumed to be classes; as a result, Tk may not -be able to find some options for the application. -If sends have been disabled by deleting the \fBsend\fR command, -this command will reenable them and recreate the \fBsend\fR -command. -.TP -\fBtk busy \fIsubcommand\fR ... -. -This command controls the marking of window hierarchies as -.QW busy , -rendering them non-interactive while some other operation is proceeding. For -more details see the \fBbusy\fR manual page. -.TP -\fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? -. -Sets and queries the caret location for the display of the specified -Tk window \fIwindow\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. If no options are specified, -the last values used for setting the caret are return in option-value pair -format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and -\fB\-height\fR is the height of the current cursor location, or the height -of the specified \fIwindow\fR if none is given. -.TP -\fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? -. -Returns a positive integer, the number of milliseconds since the last -time the user interacted with the system. If the \fB\-displayof\fR -option is given then the return value refers to the display of -\fIwindow\fR; otherwise it refers to the display of the application's -main window. -.RS -.PP -\fBtk inactive\fR will return \-1, if querying the user inactive time -is not supported by the system, and in safe interpreters. -.PP -If the literal string \fBreset\fR is given as an additional argument, -the timer is reset and an empty string is returned. Resetting the -inactivity time is forbidden in safe interpreters and will throw an -error if tried. -.RE -.TP -\fBtk fontchooser \fIsubcommand\fR ... -Controls the Tk font selection dialog. For more details see the -\fBfontchooser\fR manual page. -.TP -\fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? -. -Sets and queries the current scaling factor used by Tk to convert between -physical units (for example, points, inches, or millimeters) and pixels. The -\fInumber\fR argument is a floating point number that specifies the number of -pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is -omitted, it defaults to the main window. If the \fInumber\fR argument is -omitted, the current value of the scaling factor is returned. -.RS -.PP -A -.QW point -is a unit of measurement equal to 1/72 inch. A scaling factor -of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard -72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, -which is the setting for a 90 dpi monitor; setting the scaling factor to -1.25 on a 72 dpi monitor would cause everything in the application to be -displayed 1.25 times as large as normal. The initial value for the scaling -factor is set when the application starts, based on properties of the -installed monitor, but it can be changed at any time. Measurements made -after the scaling factor is changed will use the new scaling factor, but it -is undefined whether existing widgets will resize themselves dynamically to -accommodate the new scaling factor. -.RE -.TP -\fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? -. -Sets and queries the state of whether Tk should use XIM (X Input Methods) -for filtering events. The resulting state is returned. XIM is used in -some locales (i.e., Japanese, Korean), to handle special input devices. This -feature is only significant on X. If XIM support is not available, this -will always return 0. If the \fIwindow\fR argument is omitted, it defaults -to the main window. If the \fIboolean\fR argument is omitted, the current -state is returned. This is turned on by default for the main display. -.TP -\fBtk windowingsystem\fR -. -Returns the current Tk windowing system, one of -\fBx11\fR (X11-based), \fBwin32\fR (MS Windows), -or \fBaqua\fR (Mac OS X Aqua). -.SH "SEE ALSO" -busy(n), fontchooser(n), send(n), winfo(n) -.SH KEYWORDS -application name, send -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/tk_mac.n b/tk8.6/doc/tk_mac.n deleted file mode 100644 index f29ef2f..0000000 --- a/tk8.6/doc/tk_mac.n +++ /dev/null @@ -1,237 +0,0 @@ -'\" -'\" Copyright (c) 2011 Kevin Walzer. -'\" Copyright (c) 2011 Donal K. Fellows. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk::mac n 8.6 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk::mac \- Access Mac-Specific Functionality on OS X from Tk -.SH SYNOPSIS -.nf -\fB::tk::mac::ShowPreferences\fR -\fB::tk::mac::OpenApplication\fR -\fB::tk::mac::ReopenApplication\fR -\fB::tk::mac::OpenDocument \fIfile...\fR -\fB::tk::mac::PrintDocument \fIfile...\fR -\fB::tk::mac::Quit\fR -\fB::tk::mac::OnHide\fR -\fB::tk::mac::OnShow\fR -\fB::tk::mac::ShowHelp\fR - -\fB::tk::mac::standardAboutPanel\fR - -\fB::tk::mac::useCompatibilityMetrics \fIboolean\fR -\fB::tk::mac::CGAntialiasLimit \fIlimit\fR -\fB::tk::mac::antialiasedtext \fInumber\fR -\fB::tk::mac::useThemedToplevel \fIboolean\fR - -\fB::tk::mac::iconBitmap \fIname width height \-kind value\fR -.fi -.BE -.SH "EVENT HANDLER CALLBACKS" -.PP -The Aqua/Mac OS X application environment defines a number of additional -events that applications should respond to. These events are mapped by Tk to -calls to commands in the \fB::tk::mac\fR namespace; unless otherwise noted, if -the command is absent, no action will be taken. -.TP -\fB::tk::mac::ShowPreferences\fR -. -The default Apple Event handler for kAEShowPreferences, -.QW pref . -The application menu -.QW "Preferences" -menu item is only enabled when this proc is defined. Typically this command is -used to wrap a specific own preferences command, which pops up a preferences -window. Something like: -.RS -.PP -.CS -proc ::tk::mac::ShowPreferences {} { - setPref -} -.CE -.RE -.TP -\fB::tk::mac::OpenApplication\fR -. -If a proc of this name is defined, this proc fill fire when your application -is intially opened. It is the default Apple Event handler for -kAEOpenApplication, -.QW oapp . -.TP -\fB::tk::mac::ReopenApplication\fR -. -If a proc of this name is defined it is the default Apple Event handler for -kAEReopenApplication, -.QW rapp , -the Apple Event sent when your application is opened when it is already -running (e.g. by clicking its icon in the Dock). Here is a sample that raises -a minimized window when the Dock icon is clicked: -.RS -.PP -.CS -proc ::tk::mac::ReopenApplication {} { - if {[wm state .] eq "withdrawn"} { - wm state . normal - } else { - wm deiconify . - } - raise . -} -.CE -.RE -.TP -\fB::tk::mac::OpenDocument \fIfile...\fR -. -If a proc of this name is defined it is the default Apple Event handler for -kAEOpenDocuments, -.QW odoc , -the Apple Event sent when your application is asked to open one or more -documents (e.g., by drag & drop onto the app or by opening a document of a -type associated to the app). The proc should take as arguments paths to the -files to be opened, like so: -.RS -.PP -.CS -proc ::tk::mac::OpenDocument {args} { - foreach f $args {my_open_document $f} -} -.CE -.RE -.TP -\fB::tk::mac::PrintDocument \fIfile...\fR -. -If a proc of this name is defined it is the default Apple Event handler for -kAEPrintDocuments, -.QW pdoc , -the Apple Event sent when your application is asked to print one or more -documents (e.g., via the Print menu item in the Finder). It works the same -way as \fBtk::mac::OpenDocument\fR in terms of arguments. -.TP -\fB::tk::mac::Quit\fR -. -If a proc of this name is defined it is the default Apple Event handler for -kAEQuitApplication, -.QW quit , -the Apple Event sent when your application is asked to be quit, e.g. via the -quit menu item in the application menu, the quit menu item in the Dock menu, -or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is -called instead. -.TP -\fB::tk::mac::OnHide\fR -. -If defined, this is called when your application receives a kEventAppHidden -event, e.g. via the hide menu item in the application or Dock menus. -.TP -\fB::tk::mac::OnShow\fR -. -If defined, this is called when your application receives a kEventAppShown -event, e.g. via the show all menu item in the application menu, or by clicking -the Dock icon of a hidden application. -.TP -\fB::tk::mac::ShowHelp\fR -. -Customizes behavior of Apple Help menu; if this procedure is not defined, the -platform-specific standard Help menu item -.QW "YourApp Help" -performs the default Cocoa action of showing the Help Book configured in the -application's Info.plist (or displaying an alert if no Help Book is set). -.SH "ADDITIONAL DIALOGS" -.PP -The Aqua/Mac OS X defines additional dialogs that applications should -support. -.TP -\fB::tk::mac::standardAboutPanel\fR -. -Brings the standard Cocoa about panel to the front, with all its information -filled in from your application bundle files (standard about panel with no -options specified). See Apple Technote TN2179 and the AppKit documentation for --[NSApplication orderFrontStandardAboutPanelWithOptions:] for details on the -Info.plist keys and app bundle files used by the about panel. -.SH "SYSTEM CONFIGURATION" -.PP -There are a number of additional global configuration options that control the -details of how Tk renders by default. -.TP -\fB::tk::mac::useCompatibilityMetrics \fIboolean\fR -. -Preserves compatibility with older Tk/Aqua metrics; set to \fBfalse\fR for -more native spacing. -.TP -\fB::tk::mac::CGAntialiasLimit \fIlimit\fR -. -Sets the antialiasing limit; lines thinner that \fIlimit\fR pixels will not be -antialiased. Integer, set to 0 by default, making all lines be antialiased. -.TP -\fB::tk::mac::antialiasedtext \fInumber\fR -. -Sets anti-aliased text. Controls text antialiasing, possible values for -\fInumber\fR are -1 (default, use system default for text AA), 0 (no text AA), -1 (use text AA). -.TP -\fB::tk::mac::useThemedToplevel \fIboolean\fR -. -Sets toplevel windows to draw with the modern grayish/ pinstripe Mac -background. Equivalent to configuring the toplevel with -.QW "\fB\-background systemWindowHeaderBackground\fR" , -or to using a \fBttk::frame\fR. -.SH "SUPPORT COMMANDS" -.TP -\fB::tk::mac::iconBitmap \fIname width height \-kind value\fR -. -Renders native icons and bitmaps in Tk applications (including any image file -readable by NSImage). A native bitmap name is interpreted as follows (in -order): -.RS -.IP \(bu 3 -predefined builtin 32x32 icon name (\fBstop\fR, \fBcaution\fR, \fBdocument\fR, -etc.) -.IP \(bu 3 -\fIname\fR, as defined by \fBtk::mac::iconBitmap\fR -.IP \(bu 3 -NSImage named image name -.IP \(bu 3 -NSImage url string -.IP \(bu 3 -4-char OSType of IconServices icon -.PP -The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define -the dimensions of the image to create, and \fI\-kind\fR must be one of: -.TP -\fB\-file\fR -. -icon of file at given path -.TP -\fB\-fileType\fR -. -icon of given file type -.TP -\fB\-osType\fR -. -icon of given 4-char OSType file type -.TP -\fB\-systemType\fR -. -icon for given IconServices 4-char OSType -.TP -\fB\-namedImage\fR -. -named NSImage for given name -.TP -\fB\-imageFile\fR -. -image at given path -.RE -.SH "SEE ALSO" -bind(n), wm(n) -.SH KEYWORDS -about dialog, antialiasing, Apple event, icon, NSImage -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/tkerror.n b/tk8.6/doc/tkerror.n deleted file mode 100644 index 53cb0d1..0000000 --- a/tk8.6/doc/tkerror.n +++ /dev/null @@ -1,37 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tkerror n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tkerror \- Command invoked to process background errors -.SH SYNOPSIS -\fBtkerror \fImessage\fR -.BE -.SH DESCRIPTION -.PP -Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to -\fBbgerror\fR because the event loop (which is what usually invokes -it) is now part of Tcl. For backward compatibility -the \fBbgerror\fR provided by the current Tk version still -tries to call \fBtkerror\fR if there is one (or an auto loadable one), -so old script defining that error handler should still work, but you -should anyhow modify your scripts to use \fBbgerror\fR instead -of \fBtkerror\fR because that support for the old name might vanish -in the near future. If that call fails, \fBbgerror\fR -posts a dialog showing the error and offering to see the stack trace -to the user. If you want your own error management you should -directly override \fBbgerror\fR instead of \fBtkerror\fR. -Documentation for \fBbgerror\fR is available as part of Tcl's -documentation. -.SH KEYWORDS -background error, reporting -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/tkvars.n b/tk8.6/doc/tkvars.n deleted file mode 100644 index a80fd54..0000000 --- a/tk8.6/doc/tkvars.n +++ /dev/null @@ -1,110 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tkvars n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -geometry, tk_library, tk_patchLevel, tk_strictMotif, tk_version \- Variables used or set by Tk -.BE -.SH DESCRIPTION -.PP -The following Tcl variables are either set or used by Tk at various times -in its execution: -.TP 15 -\fBtk_library\fR -. -This variable holds the file name for a directory containing a library -of Tcl scripts related to Tk. These scripts include an initialization -file that is normally processed whenever a Tk application starts up, -plus other files containing procedures that implement default behaviors -for widgets. -.RS -.PP -The initial value of \fBtcl_library\fR is set when Tk is added to -an interpreter; this is done by searching several different directories -until one is found that contains an appropriate Tk startup script. -If the \fBTK_LIBRARY\fR environment variable exists, then -the directory it names is checked first. -If \fBTK_LIBRARY\fR is not set or does not refer to an appropriate -directory, then Tk checks several other directories based on a -compiled-in default location, the location of the Tcl library directory, -the location of the binary containing the application, and the current -working directory. -.PP -The variable can be modified by an application to switch to a different -library. -.RE -.TP -\fBtk_patchLevel\fR -. -Contains a dot-separated sequence of decimal integers giving the -current patch level for Tk. -The patch level is incremented for each new release or patch, and -it uniquely identifies an official version of Tk. -.RS -.PP -This value is normally the same as the result of -.QW "\fBpackage require\fR \fBTk\fR" . -.RE -.TP -\fBtk_strictMotif\fR -. -This variable is set to zero by default. -If an application sets it to one, then Tk attempts to adhere as -closely as possible to Motif look-and-feel standards. -For example, active elements such as buttons and scrollbar -sliders will not change color when the pointer passes over them. -Modern applications should not normally set this variable. -.TP 15 -\fBtk_version\fR -. -Tk sets this variable in the interpreter for each application. -The variable holds the current version number of the Tk -library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and -\fIminor\fR are integers. The major version number increases in -any Tk release that includes changes that are not backward compatible -(i.e. whenever existing Tk applications and scripts may have to change to -work with the new release). The minor version number increases with -each new release of Tk, except that it resets to zero whenever the -major version number changes. -.SS "INTERNAL AND DEBUGGING VARIABLES" -.PP -These variables should not normally be set by user code. -.TP -\fBtk::Priv\fR -. -This variable is an array containing several pieces of information -that are private to Tk. The elements of \fBtk::Priv\fR are used by -Tk library procedures and default bindings. -They should not be accessed by any code outside Tk. -.TP -\fBtk_textRedraw\fR -.TP -\fBtk_textRelayout\fR -. -These variables are set by text widgets when they have debugging -turned on. The values written to these variables can be used to -test or debug text widget operations. These variables are mostly -used by Tk's test suite. -.SH "OTHER GLOBAL VARIABLES" -The following variables are only guaranteed to exist in \fBwish\fR -executables; the Tk library does not define them itself but many Tk -environments do. -.TP 6 -\fBgeometry\fR -. -If set, contains the user-supplied geometry specification to use for -the main Tk window. -.SH "SEE ALSO" -package(n), tclvars(n), wish(1) -.SH KEYWORDS -environment, text, variables, version -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/tkwait.n b/tk8.6/doc/tkwait.n deleted file mode 100644 index a31aee7..0000000 --- a/tk8.6/doc/tkwait.n +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tkwait n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tkwait \- Wait for variable to change or window to be destroyed -.SH SYNOPSIS -\fBtkwait variable \fIname\fR -.sp -\fBtkwait visibility \fIname\fR -.sp -\fBtkwait window \fIname\fR -.BE -.SH DESCRIPTION -.PP -The \fBtkwait\fR command waits for one of several things to happen, -then it returns without taking any other actions. -The return value is always an empty string. -If the first argument is \fBvariable\fR (or any abbreviation of -it) then the second argument is the name of a global variable and the -command waits for that variable to be modified. -If the first argument is \fBvisibility\fR (or any abbreviation -of it) then the second argument is the name of a window and the -\fBtkwait\fR command waits for a change in its -visibility state (as indicated by the arrival of a VisibilityNotify -event). This form is typically used to wait for a newly-created -window to appear on the screen before taking some action. -If the first argument is \fBwindow\fR (or any abbreviation -of it) then the second argument is the name of a window and the -\fBtkwait\fR command waits for that window to be destroyed. -This form is typically used to wait for a user to finish interacting -with a dialog box before using the result of that interaction. -.PP -While the \fBtkwait\fR command is waiting it processes events in -the normal fashion, so the application will continue to respond -to user interactions. -If an event handler invokes \fBtkwait\fR again, the nested call -to \fBtkwait\fR must complete before the outer call can complete. -.SH "SEE ALSO" -bind(n), vwait(n) -.SH KEYWORDS -variable, visibility, wait, window -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/toplevel.n b/tk8.6/doc/toplevel.n deleted file mode 100644 index 271d9f1..0000000 --- a/tk8.6/doc/toplevel.n +++ /dev/null @@ -1,157 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH toplevel n 8.4 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -toplevel \- Create and manipulate 'toplevel' main and popup window widgets -.SH SYNOPSIS -\fBtoplevel\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-borderwidth \-highlightcolor \-pady -\-cursor \-highlightthickness \-relief -\-highlightbackground \-padx \-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fB\-background\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fB\-class\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fB\-colormap\fR option is not specified, the new window -uses the default colormap of its screen. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-container container Container -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.OP \-menu menu Menu -Specifies a menu widget to be used as a menubar. On the Macintosh, the -menubar will be displayed across the top of the main monitor. On -Microsoft Windows and all UNIX platforms, the menu will appear across -the toplevel window as part of the window dressing maintained by the -window manager. -.OP \-screen "" "" -Specifies the screen on which to place the new window. -Any valid screen name may be used, even one associated with a -different display. -Defaults to the same screen as its parent. -This option is special in that it may not be specified via the option -database, and it may not be modified with the \fBconfigure\fR -widget command. -.OP \-use use Use -This option is used for embedding. If the value is not an empty string, -it must be the window identifier of a container window, specified as -a hexadecimal string like the ones returned by the \fBwinfo id\fR -command. The toplevel widget will be created as a child of the given -container instead of the root window for the screen. If the container -window is in a Tk application, it must be a frame or toplevel widget for -which the \fB\-container\fR option was specified. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the default -visual for its screen. -The \fB\-visual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.BE -.SH DESCRIPTION -.PP -The \fBtoplevel\fR command creates a new toplevel widget (given -by the \fIpathName\fR argument). Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the toplevel such as its background color -and relief. The \fBtoplevel\fR command returns the -path name of the new window. -.PP -A toplevel is similar to a frame except that it is created as a -top-level window: its X parent is the root window of a screen -rather than the logical parent from its path name. The primary -purpose of a toplevel is to serve as a container for dialog boxes -and other collections of widgets. The only visible features -of a toplevel are its background color and an optional 3-D border -to make the toplevel appear raised or sunken. -.SH "WIDGET COMMAND" -.PP -The \fBtoplevel\fR command creates a new Tcl command whose -name is the same as the path name of the toplevel's window. 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 -\fIPathName\fR is the name of the command, which is the same as -the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for toplevel widgets: -.TP -\fIpathName \fBcget \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 \fBtoplevel\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 \fBtoplevel\fR -command. -.SH BINDINGS -.PP -When a new toplevel is created, it has no default event bindings: -toplevels are not intended to be interactive. -.SH "SEE ALSO" -frame(n) -.SH KEYWORDS -toplevel, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_Geometry.3 b/tk8.6/doc/ttk_Geometry.3 deleted file mode 100644 index 61015c5..0000000 --- a/tk8.6/doc/ttk_Geometry.3 +++ /dev/null @@ -1,223 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -.TH Geometry 3 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -Ttk_MakeBox, Ttk_PadBox, Ttk_ExpandBox, Ttk_PackBox, Ttk_StickBox, Ttk_PlaceBox, Ttk_BoxContains, Ttk_MakePadding, Ttk_UniformPadding, Ttk_AddPadding, Ttk_RelievePadding, Ttk_GetPaddingFromObj, Ttk_GetBorderFromObj, Ttk_GetStickyFromObj \- Tk themed geometry utilities -.SH SYNOPSIS -.nf -\fB#include <tkTheme.h>\fR - -Ttk_Box -\fBTtk_MakeBox\fR(int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR); - -Ttk_Box -\fBTtk_PadBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); - -Ttk_Box -\fBTtk_ExpandBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); - -Ttk_Box -\fBTtk_PackBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR); - -Ttk_Box -\fBTtk_StickBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, unsigned \fIsticky\fR); - -Ttk_Box -\fBTtk_PlaceBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR, unsigned \fIsticky\fR); - -Ttk_Box -\fBTtk_AnchorBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, Tk_Anchor \fIanchor\fR); - -Ttk_Padding -\fBTtk_MakePadding\fR(short \fIleft\fR, short \fItop\fR, short \fIright\fR, short \fIbottom\fR); - -Ttk_Padding -\fBTtk_UniformPadding\fR(short \fIborder\fR); - -Ttk_Padding -\fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR; - -Ttk_Padding -\fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR); - -int -\fBTtk_BoxContains\fR(Ttk_Box \fIbox\fR, int \fIx\fR, int \fIy\fR); - -int -\fBTtk_GetPaddingFromObj\fR(Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); - -int -\fBTtk_GetBorderFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); - -int -\fBTtk_GetStickyFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, int *\fIsticky_rtn\fR); -.fi -.SH ARGUMENTS -.AP Tk_Anchor anchor in -One of the symbolic constants \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, -etc. See \fITk_GetAnchorFromObj(3)\fR. -.AP "Ttk_Box *" cavity in/out -A rectangular region from which a parcel is allocated. -.AP short border in -Extra padding (in pixels) to add uniformly to each side of a region. -.AP short bottom in -Extra padding (in pixels) to add to the bottom of a region. -.AP Ttk_Box box in -.AP "Ttk_Box *" box_rtn out -Specifies a rectangular region. -.AP int height in -The height in pixels of a region. -.AP "Tcl_Interp *" interp in -Used to store error messages. -.AP int left in -Extra padding (in pixels) to add to the left side of a region. -.AP "Tcl_Obj *" objPtr in -String value contains a symbolic name -to be converted to an enumerated value or bitmask. -Internal rep may be be modified to cache corresponding value. -.AP Ttk_Padding padding in -.AP "Ttk_Padding *" padding_rtn out -Extra padding to add on the inside of a region. -.AP Ttk_Box parcel in -A rectangular region, allocated from a cavity. -.AP int relief in -One of the standard Tk relief options -(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.). -See \fBTk_GetReliefFromObj\fR. -.AP short right in -Extra padding (in pixels) to add to the right side of a region. -.AP Ttk_Side side in -One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, -\fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR. -.AP unsigned sticky in -A bitmask containing one or more of the bits -\fBTTK_STICK_W\fR (west, or left), -\fBTTK_STICK_E\fR (east, or right, -\fBTTK_STICK_N\fR (north, or top), and -\fBTTK_STICK_S\fR (south, or bottom). -\fBTTK_FILL_X\fR is defined as a synonym for (TTK_STICK_W|TTK_STICK_E), -\fBTTK_FILL_Y\fR is a synonym for (TTK_STICK_N|TTK_STICK_S), -and \fBTTK_FILL_BOTH\fR and \fBTTK_STICK_ALL\fR -are synonyms for (TTK_FILL_X|TTK_FILL_Y). -See also: \fIgrid(n)\fR. -.AP Tk_Window tkwin in -Window whose screen geometry determines -the conversion between absolute units and pixels. -.AP short top in -Extra padding at the top of a region. -.AP int width in -The width in pixels of a region. -.AP int x in -X coordinate of upper-left corner of region. -.AP int y in -Y coordinate of upper-left corner of region. -.BE -.SH "BOXES" -.PP -The \fBTtk_Box\fR structure represents a rectangular region of a window: -.CS -typedef struct { - int \fIx\fR; - int \fIy\fR; - int \fIwidth\fR; - int \fIheight\fR; -} \fBTtk_Box\fR; -.CE -All coordinates are relative to the window. -.PP -\fBTtk_MakeBox\fR is a convenience routine that constructs -a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels -wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates. -.PP -\fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR, -shrunken according to the left, top, right, and bottom margins -specified by \fIpadding\fR. -.PP -\fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fR: -it returns a new box surrounding the specified \fIparcel\fR, -expanded according to the left, top, right, and bottom margins -specified by \fIpadding\fR. -.PP -\fBTtk_PackBox\fR allocates a parcel \fIwidth\fR by \fIheight\fR -pixels wide on the specified \fIside\fR of the \fIcavity\fR, -and shrinks the \fIcavity\fR accordingly. -.PP -\fBTtk_StickBox\fR places a box with the requested \fIwidth\fR -and \fIheight\fR inside the \fIparcel\fR according to the -\fIsticky\fR bits. -.PP -\fBTtk_PlaceBox\fR combines \fBTtk_PackBox\fR and \fBTtk_StickBox\fR: -it allocates a parcel on the specified \fIside\fR of the \fIcavity\fR, -places a box of the requested size inside the parcel according to \fIsticky\fR, -and shrinks the \fIcavity\fR. -.PP -\fBTtk_AnchorBox\fR places a box with the requested \fIwidth\fR -and \fIheight\fR inside the \fIparcel\fR according to the -specified \fIanchor\fR option. -.PP -\fBTtk_BoxContains\fR tests if the specified \fIx, y\fR coordinate -lies within the rectangular region \fIbox\fR. -.SH "PADDDING" -.PP -The \fBTtk_Padding\fR structure is used to represent -borders, internal padding, and external margins: -.CS -typedef struct { - short \fIleft\fR; - short \fItop\fR; - short \fIright\fR; - short \fIbottom\fR; -} \fBTtk_Padding\fR; -.CE -.PP -\fBTtk_MakePadding\fR is a convenience routine that constructs -a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom -components. -.PP -\fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure -with all components equal to the specified \fIborder\fR. -.PP -\fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together -and returns a combined padding containing the sum of the -individual padding components. -.PP -\fBTtk_RelievePadding\fR -adds an extra 2 pixels of padding to \fIpadding\fR -according to the specified \fIrelief\fR. -If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, -adds two pixels at the top and left -so the inner region is shifted down and to the left. -If it is \fBTK_RELIEF_RAISED\fR, adds two pixels -at the bottom and right so -the inner region is shifted up and to the right. -Otherwise, adds 1 pixel on all sides. -This is typically used in element geometry procedures to simulate a -.QW pressed-in -look for pushbuttons. -.SH "CONVERSION ROUTINES" -.PP -\fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR -to a \fBTtk_Padding\fR structure. -The string representation is a list of -up to four length specifications -.QW "\fIleft top right bottom\fR" . -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications. -.PP -\fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fR -except that the lengths are specified as integers -(i.e., resolution-dependant values like \fI3m\fR are not allowed). -.PP -\fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR -to a \fIsticky\fR bitmask. The string contains zero or more -of the characters \fBn\fR, \fBs\fR, \fBe\fR, or \fBw\fR. -.SH "SEE ALSO" -Tk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3) -.SH "KEYWORDS" -geometry, padding, margins, box, region, sticky, relief diff --git a/tk8.6/doc/ttk_Theme.3 b/tk8.6/doc/ttk_Theme.3 deleted file mode 100644 index 8031b8a..0000000 --- a/tk8.6/doc/ttk_Theme.3 +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" Copyright (c) 2003 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Ttk_CreateTheme 3 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -Ttk_CreateTheme, Ttk_GetTheme, Ttk_GetDefaultTheme, Ttk_GetCurrentTheme \- create and use Tk themes. -.SH SYNOPSIS -.nf -Ttk_Theme Ttk_CreateTheme(\fIinterp\fR, \fIname\fR, \fIparentTheme\fR); -Ttk_Theme Ttk_GetTheme(\fIinterp\fR, \fIname\fR); -Ttk_Theme Ttk_GetDefaultTheme(\fIinterp\fR); -Ttk_Theme Ttk_GetCurrentTheme(\fIinterp\fR); -.fi -.SH ARGUMENTS -.AP "Tcl_Interp *" interp in -The Tcl interpreter in which to register/query available themes. -.AP "Ttk_Theme" parentTheme in -Fallback or parent theme from which the new theme will -inherit elements and layouts. -.AP "const char *" name in -The name of the theme. -.BE -.SH DESCRIPTION -.\" TODO - Document these functions better! -.SH "SEE ALSO" -Ttk_RegisterLayout, Ttk_BuildLayout -.\" .SH KEYWORDS diff --git a/tk8.6/doc/ttk_button.n b/tk8.6/doc/ttk_button.n deleted file mode 100644 index cf47a1a..0000000 --- a/tk8.6/doc/ttk_button.n +++ /dev/null @@ -1,109 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::button n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::button \- Widget that issues a command when pressed -.SH SYNOPSIS -\fBttk::button\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -A \fBttk::button\fR widget displays a textual label and/or image, -and evaluates a command when pressed. -.SO ttk_widget -\-class \-compound \-cursor -\-image \-state \-style -\-takefocus \-text \-textvariable -\-underline \-width -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -A script to evaluate when the widget is invoked. -.OP \-default default Default -May be set to one of \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. -In a dialog box, one button may be designated the -.QW default -button (meaning, roughly, -.QW "the one that gets invoked when the user presses <Enter>" ). -\fBactive\fR indicates that this is currently the default button; -\fBnormal\fR means that it may become the default button, and -\fBdisabled\fR means that it is not defaultable. -The default is \fBnormal\fR. -.RS -.PP -Depending on the theme, the default button may be displayed -with an extra highlight ring, or with a different border color. -.RE -.\" Not documented -- may go away -.\" .OP \-padding padding Padding -.\" .OP \-foreground foreground Foreground -.\" .OP \-font font Font -.\" .OP \-anchor anchor Anchor -.\" .OP \-relief relief Relief -.SH "WIDGET COMMAND" -.PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, buttons support the following additional widget commands: -.TP -\fIpathName \fBinvoke\fR -Invokes the command associated with the button. -.SH "STANDARD STYLES" -.PP -\fBTtk::button\fR widgets support the \fBToolbutton\fR style in all standard -themes, which is useful for creating widgets for toolbars. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::button\fP is \fBTButton\fP. -.PP -Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBpressed\fP, \fBreadonly\fP. -.PP -\fBTButton\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-anchor\fP \fIanchor\fP -.br -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.br -\fB\-highlightcolor\fP \fIcolor\fP -.br -\fB\-highlightthickness\fP \fIamount\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-relief\fP \fIrelief\fP -.br -\fB\-shiftrelief\fP \fIamount\fP -.RS -\fB\-shiftrelief\fP specifies how far the button contents are -shifted down and right in the \fIpressed\fP state. -This action provides additional skeumorphic feedback. -.RE -\fB\-width\fP \fIamount\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), button(n) -.SH "KEYWORDS" -widget, button, default, command -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_checkbutton.n b/tk8.6/doc/ttk_checkbutton.n deleted file mode 100644 index a18a886..0000000 --- a/tk8.6/doc/ttk_checkbutton.n +++ /dev/null @@ -1,105 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::checkbutton n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::checkbutton \- On/off widget -.SH SYNOPSIS -\fBttk::checkbutton\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -A \fBttk::checkbutton\fR widget is used to show or change a setting. -It has two states, selected and deselected. -The state of the checkbutton may be linked to a Tcl variable. -.SO ttk_widget -\-class \-compound \-cursor -\-image \-state \-style -\-takefocus \-text \-textvariable -\-underline \-width -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -A Tcl script to execute whenever the widget is invoked. -.OP \-offvalue offValue OffValue -The value to store in the associated \fB\-variable\fR -when the widget is deselected. Defaults to \fB0\fR. -.OP \-onvalue onValue OnValue -The value to store in the associated \fB\-variable\fR -when the widget is selected. Defaults to \fB1\fR. -.OP \-variable variable Variable -The name of a global variable whose value is linked to the widget. -Defaults to the widget pathname if not specified. -.SH "WIDGET COMMAND" -.PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, checkbuttons support the following additional -widget commands: -.TP -\fIpathname\fB invoke\fR -Toggles between the selected and deselected states -and evaluates the associated \fB\-command\fR. -If the widget is currently selected, sets the \fB\-variable\fR -to the \fB\-offvalue\fR and deselects the widget; -otherwise, sets the \fB\-variable\fR to the \fB\-onvalue\fR -Returns the result of the \fB\-command\fR. -.\" Missing: select, deselect, toggle -.\" Are these useful? They don't invoke the -command -.\" Missing: flash. This is definitely not useful. -.SH "WIDGET STATES" -.PP -The widget does not respond to user input if the \fBdisabled\fR state is set. -The widget sets the \fBselected\fR state whenever -the linked \fB\-variable\fR is set to the widget's \fB\-onvalue\fR, -and clears it otherwise. -The widget sets the \fBalternate\fR state whenever the -linked \fB\-variable\fR is unset. -(The \fBalternate\fR state may be used to indicate a -.QW tri-state -or -.QW indeterminate -selection.) -.SH "STANDARD STYLES" -.PP -\fBTtk::checkbutton\fR widgets support the \fBToolbutton\fR style in all -standard themes, which is useful for creating widgets for toolbars. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::checkbutton\fP is \fBTCheckbutton\fP. -.PP -Dynamic states: \fBactive\fP, \fBalternate\fP, \fBdisabled\fP, -\fBpressed\fP, \fBselected\fP, \fBreadonly\fP. -.PP -\fBTCheckbutton\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-indicatorbackground\fP \fIcolor\fP -.br -\fB\-indicatorcolor\fP \fIcolor\fP -.br -\fB\-indicatormargin\fP \fIpadding\fP -.br -\fB\-indicatorrelief\fP \fIrelief\fP -.br -\fB\-padding\fP \fIpadding\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::radiobutton(n), checkbutton(n) -.SH "KEYWORDS" -widget, button, toggle, check, option -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_combobox.n b/tk8.6/doc/ttk_combobox.n deleted file mode 100644 index 9c01409..0000000 --- a/tk8.6/doc/ttk_combobox.n +++ /dev/null @@ -1,196 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::combobox n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::combobox \- text field with popdown selection list -.SH SYNOPSIS -\fBttk::combobox\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::combobox\fR combines a text field with a pop-down list of values; -the user may select the value of the text field from among the -values in the list. -.SO ttk_widget -\-class \-cursor \-takefocus -\-style -.SE -.\" ALSO: Other entry widget options -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-exportselection exportSelection ExportSelection -Boolean value. -If set, the widget selection is linked to the X selection. -.OP \-justify justify Justify -Specifies how the text is aligned within the widget. -Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -.OP \-height height Height -Specifies the height of the pop-down listbox, in rows. -.OP \-postcommand postCommand PostCommand -A Tcl script to evaluate immediately before displaying the listbox. -The \fB\-postcommand\fR script may specify the \fB\-values\fR to display. -.OP \-state state State -One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fR. -In the \fBreadonly\fR state, -the value may not be edited directly, and -the user can only select one of the \fB\-values\fR from the -dropdown list. -In the \fBnormal\fR state, -the text field is directly editable. -In the \fBdisabled\fR state, no interaction is possible. -.OP \-textvariable textVariable TextVariable -Specifies the name of a global variable whose value is linked -to the widget value. -Whenever the variable changes value the widget value is updated, -and vice versa. -.OP \-values values Values -Specifies the list of values to display in the drop-down listbox. -.OP \-width width Width -Specifies an integer value indicating the desired width of the entry window, -in average-size characters of the widget's font. -.SH "WIDGET COMMAND" -.PP -The following subcommands are possible for combobox widgets: -'\".TP -'\"\fIpathName \fBcget\fR \fIoption\fR -'\"Returns the current value of the specified \fIoption\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -'\"Modify or query widget options. -'\"See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBcurrent\fR ?\fInewIndex\fR? -If \fInewIndex\fR is supplied, sets the combobox value -to the element at position \fInewIndex\fR in the list of \fB\-values\fR. -Otherwise, returns the index of the current value in the list of -\fB\-values\fR or \fB\-1\fR if the current value does not appear in the list. -.TP -\fIpathName \fBget\fR -Returns the current value of the combobox. -'\".TP -'\"\fIpathName \fBidentify \fIx y\fR -'\"Returns the name of the element at position \fIx\fR, \fIy\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBinstate \fIstateSpec\fR ?\fIscript\fR? -'\"Test the widget state. -'\"See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBset\fR \fIvalue\fR -Sets the value of the combobox to \fIvalue\fR. -'\".TP -'\"\fIpathName \fBstate\fR ?\fIstateSpec\fR? -'\"Modify or query the widget state. -'\"See \fIttk::widget(n)\fR. -.PP -The combobox widget also supports the following \fBttk::entry\fR -widget subcommands (see \fIttk::entry(n)\fR for details): -.DS -.ta 5.5c 11c -\fBbbox\fR \fBdelete\fR \fBicursor\fR -\fBindex\fR \fBinsert\fR \fBselection\fR -\fBxview\fR -.DE -The combobox widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR \fBidentify\fR -\fBinstate\fR \fBstate\fR -.DE -.SH "VIRTUAL EVENTS" -.PP -The combobox widget generates a \fB<<ComboboxSelected>>\fR virtual event -when the user selects an element from the list of values. -If the selection action unposts the listbox, -this event is delivered after the listbox is unposted. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::combobox\fP is \fBTCombobox\fP. -The \fBttk::combobox\fP uses the \fBentry\fP and -\fBlistbox\fP widgets internally. -The listbox frame has a class name of \fBComboboxPopdownFrame\fP. -.PP -Dynamic states: \fBdisabled\fP, \fBfocus\fP, \fBpressed\fP, \fBreadonly\fP. -.PP -\fBTCombobox\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-arrowcolor\fP \fIcolor\fP -.br -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-focusfill\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-fieldbackground\fP \fIcolor\fP -.RS -Can only be changed when using non-native and non-graphical themes. -.RE -\fB\-insertwidth\fP \fIamount\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-postoffset\fP \fIpadding\fP -.br -\fB\-selectbackground\fP \fIcolor\fP -.RS -Text entry select background. -.RE -\fB\-selectforeground\fP \fIcolor\fP -.RS -Text entry select foreground. -.RE -.PP -The \fBttk::combobox\fP popdown listbox cannot be configured using -\fBttk::style\fP nor via the widget \fBconfigure\fP command. The listbox -can be configured using the option database. -.PP -option add *TCombobox*Listbox.background \fIcolor\fP -.br -option add *TCombobox*Listbox.font \fIfont\fP -.br -option add *TCombobox*Listbox.foreground \fIcolor\fP -.br -option add *TCombobox*Listbox.selectBackground \fIcolor\fP -.br -option add *TCombobox*Listbox.selectForeground \fIcolor\fP -.PP -To configure a specific listbox (subject to future change): -.CS -set popdown [ttk::combobox::PopdownWindow .mycombobox] -$popdown.f.l configure \-font \fIfont\fP -.CE -.PP -\fBComboboxPopdownFrame\fP -styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-borderwidth\fP \fIamount\fP -.br -\fB\-relief\fP \fIrelief\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::entry(n) -.SH KEYWORDS -choice, entry, list box, text box, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_entry.n b/tk8.6/doc/ttk_entry.n deleted file mode 100644 index d752670..0000000 --- a/tk8.6/doc/ttk_entry.n +++ /dev/null @@ -1,511 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 Scriptics Corporation. -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::entry n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::entry \- Editable text field widget -.SH SYNOPSIS -\fBttk::entry\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -An \fBttk::entry\fR widget displays a one-line text string and -allows that string to be edited by the user. -The value of the string may be linked to a Tcl variable -with the \fB\-textvariable\fR option. -Entry widgets support horizontal scrolling with the -standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. -.SO ttk_widget -\-class \-cursor \-style -\-takefocus \-xscrollcommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-exportselection exportSelection ExportSelection -A boolean value specifying whether or not -a selection in the widget should be linked to the X selection. -If the selection is exported, then selecting in the widget deselects -the current X selection, selecting outside the widget deselects any -widget selection, and the widget will respond to selection retrieval -requests when it has a selection. -.\" MAYBE: .OP \-font font Font -.\" MAYBE: .OP \-foreground foreground Foreground -.\" MAYBE: .OP \-insertbackground insertBackground Foreground -.\" MAYBE: .OP \-insertwidth insertWidth InsertWidth -.OP \-invalidcommand invalidCommand InvalidCommand -A script template to evaluate whenever the \fB\-validatecommand\fR returns 0. -See \fBVALIDATION\fR below for more information. -.OP \-justify justify Justify -Specifies how the text is aligned within the entry widget. -One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -.\" MAYBE: .OP \-selectbackground selectBackground Foreground -.\" MAYBE: .OP \-selectborderwidth selectBorderWidth BorderWidth -.\" MAYBE: .OP \-selectforeground selectForeground Background -.OP \-show show Show -If this option is specified, then the true contents of the entry -are not displayed in the window. -Instead, each character in the entry's value will be displayed as -the first character in the value of this option, such as -.QW * -or a bullet. -This is useful, for example, if the entry is to be used to enter -a password. -If characters in the entry are selected and copied elsewhere, the -information copied will be what is displayed, not the true contents -of the entry. -.OP \-state state State -Compatibility option; see \fIttk::widget(n)\fR for details. -Specifies one of three states for the entry, -\fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. -See \fBWIDGET STATES\fR, below. -.OP \-textvariable textVariable Variable -Specifies the name of a global variable whose value is linked -to the entry widget's contents. -Whenever the variable changes value, the widget's contents are updated, -and vice versa. -.OP \-validate validate Validate -Specifies the mode in which validation should operate: -\fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. -Default is \fBnone\fR, meaning that validation is disabled. -See \fBVALIDATION\fR below. -.OP \-validatecommand validateCommand ValidateCommand -A script template to evaluate whenever validation is triggered. -If set to the empty string (the default), validation is disabled. -The script must return a boolean value. -See \fBVALIDATION\fR below. -.OP \-width width Width -Specifies an integer value indicating the desired width of the entry window, -in average-size characters of the widget's font. -.\" Not in ttk: If the value is less than or equal to zero, the widget picks a -.\" Not in ttk: size just large enough to hold its current text. -.SH NOTES -.PP -A portion of the entry may be selected as described below. -If an entry is exporting its selection (see the \fB\-exportselection\fR -option), then it will observe the standard X11 protocols for handling the -selection; entry selections are available as type \fBSTRING\fR. -Entries also observe the standard Tk rules for dealing with the -input focus. When an entry has the input focus it displays an -\fIinsert cursor\fR to indicate where new characters will be -inserted. -.PP -Entries are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Entries use -the standard \fB\-xscrollcommand\fR mechanism for interacting with -scrollbars (see the description of the \fB\-xscrollcommand\fR option -for details). -.SH "INDICES" -.PP -Many of the \fBentry\fR widget commands take one or more indices as -arguments. An index specifies a particular character in the entry's -string, in any of the following ways: -.IP \fInumber\fR -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. -.IP \fB@\fInumber\fR -In this form, \fInumber\fR is treated as an x-coordinate in the -entry's window; the character spanning that x-coordinate is used. -For example, -.QW \fB@0\fR -indicates the left-most character in the window. -.IP \fBend\fR -Indicates the character just after the last one in the entry's string. -This is equivalent to specifying a numerical index equal to the length -of the entry's string. -.IP \fBinsert\fR -Indicates the character adjacent to and immediately following the -insert cursor. -.IP \fBsel.first\fR -Indicates the first character in the selection. It is an error to -use this form if the selection is not in the entry window. -.IP \fBsel.last\fR -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection is not in the -entry window. -.LP -Abbreviations may be used for any of the forms above, e.g.\| -.QW \fBe\fR -or -.QW \fBsel.l\fR . -In general, out-of-range indices are automatically rounded to the -nearest legal value. -.SH "WIDGET COMMAND" -.PP -The following subcommands are possible for entry widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four numbers describing the bounding box of the -character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. -'\".TP -'\"\fIpathName \fBcget\fR \fIoption\fR -'\"Returns the current value of the specified \fIoption\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -'\"Modify or query widget options. -'\"See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Delete one or more elements of the entry. -\fIFirst\fR is the index of the first character to delete, and -\fIlast\fR is the index of the character just after the last -one to delete. -If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, -i.e. a single character is deleted. -This command returns the empty string. -.TP -\fIpathName \fBget\fR -Returns the entry's string. -.TP -\fIpathName \fBicursor \fIindex\fR -Arrange for the insert cursor to be displayed just before the character -given by \fIindex\fR. Returns the empty string. -'\".TP -'\"\fIpathName \fBidentify \fIx y\fR -'\"Returns the name of the element at position \fIx\fR, \fIy\fR, -'\"or the empty string if the coordinates are outside the window. -.TP -\fIpathName \fBindex\fI index\fR -Returns the numerical index corresponding to \fIindex\fR. -.TP -\fIpathName \fBinsert \fIindex string\fR -Insert \fIstring\fR just before the character -indicated by \fIindex\fR. Returns the empty string. -'\".TP -'\"\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -'\"Test the widget state. -'\"See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within an entry. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection clear\fR -Clear the selection if it is currently in this widget. -If the selection is not in this widget then the command has no effect. -Returns the empty string. -.TP -\fIpathName \fBselection present\fR -Returns 1 if there is are characters selected in the entry, -0 if nothing is selected. -.TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR -Sets the selection to include the characters starting with -the one indexed by \fIstart\fR and ending with the one just -before \fIend\fR. -If \fIend\fR refers to the same character as \fIstart\fR or an -earlier one, then the entry's selection is cleared. -.RE -'\".TP -'\"\fIpathName \fBstate\fR ?\fIstateSpec\fR? -'\"Modify or query the widget state. -'\"See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBvalidate\fR -Force revalidation, independent of the conditions specified -by the \fB\-validate\fR option. -Returns 0 if validation fails, 1 if it succeeds. -Sets or clears the \fBinvalid\fR state accordingly. -See \fBVALIDATION\fR below for more details. -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the entry's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview\fR \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is displayed at the left edge of the window. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that the character \fIfraction\fR of the -way through the text appears at the left edge of the window. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -'\" or an abbreviation of one of these, but we don't document that. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.PP -The entry widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR \fBidentify\fR -\fBinstate\fR \fBstate\fR -.DE -.SH VALIDATION -.PP -The \fB\-validate\fR, \fB\-validatecommand\fR, and \fB\-invalidcommand\fR -options are used to enable entry widget validation. -.SS "VALIDATION MODES" -.PP -There are two main validation modes: \fIprevalidation\fR, -in which the \fB\-validatecommand\fR is evaluated prior to each edit -and the return value is used to determine whether to accept -or reject the change; -and \fIrevalidation\fR, in which the \fB\-validatecommand\fR is -evaluated to determine whether the current value is valid. -.PP -The \fB\-validate\fR option determines when validation occurs; -it may be set to any of the following values: -.RS -.IP \fBnone\fR -Default. This means validation will only occur when -specifically requested by the \fBvalidate\fR widget command. -.IP \fBkey\fR -The entry will be prevalidated prior to each edit -(specifically, whenever the \fBinsert\fR or \fBdelete\fR -widget commands are called). -If prevalidation fails, the edit is rejected. -.IP \fBfocus\fR -The entry is revalidated when the entry receives or loses focus. -.IP \fBfocusin\fR -The entry is revalidated when the entry receives focus. -.IP \fBfocusout\fR -The entry is revalidated when the entry loses focus. -.IP \fBall\fR -Validation is performed for all above conditions. -.RE -.PP -The \fB\-invalidcommand\fR is evaluated whenever -the \fB\-validatecommand\fR returns a false value. -.PP -The \fB\-validatecommand\fR and \fB\-invalidcommand\fR -may modify the entry widget's value -via the widget \fBinsert\fR or \fBdelete\fR commands, -or by setting the linked \fB\-textvariable\fR. -If either does so during prevalidation, -then the edit is rejected -regardless of the value returned by the \fB\-validatecommand\fR. -.PP -If \fB\-validatecommand\fR is empty (the default), -validation always succeeds. -.SS "VALIDATION SCRIPT SUBSTITUTIONS" -.PP -It is possible to perform percent substitutions on the -\fB\-validatecommand\fR and \fB\-invalidcommand\fR, -just as in a \fBbind\fR script. -The following substitutions are recognized: -.RS -.IP \fB%d\fR -Type of action: 1 for \fBinsert\fR prevalidation, -0 for \fBdelete\fR prevalidation, -or \-1 for revalidation. -.IP \fB%i\fR -Index of character string to be inserted/deleted, if any, otherwise \-1. -.IP \fB%P\fR -In prevalidation, the new value of the entry if the edit is accepted. -In revalidation, the current value of the entry. -.IP \fB%s\fR -The current value of entry prior to editing. -.IP \fB%S\fR -The text string being inserted/deleted, if any, {} otherwise. -.IP \fB%v\fR -The current value of the \fB\-validate\fR option. -.IP \fB%V\fR -The validation condition that triggered the callback -(\fBkey\fR, \fBfocusin\fR, \fBfocusout\fR, or \fBforced\fR). -.IP \fB%W\fR -The name of the entry widget. -.RE -.SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION" -.PP -The standard Tk entry widget automatically disables validation -(by setting \fB\-validate\fR to \fBnone\fR) -if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies -the entry's value. -The Tk themed entry widget only disables validation if one -of the validation scripts raises an error, or if \fB\-validatecommand\fR -does not return a valid boolean value. -(Thus, it is not necessary to re-enable validation after -modifying the entry value in a validation script). -.PP -In addition, the standard entry widget invokes validation whenever the linked -\fB\-textvariable\fR is modified; the Tk themed entry widget does not. -.SH "DEFAULT BINDINGS" -.PP -The entry widget's default bindings enable the following behavior. -In the descriptions below, -.QW word -refers to a contiguous group of letters, digits, or -.QW _ -characters, or any single character other than these. -.IP \0\(bu 4 -Clicking mouse button 1 positions the insert cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 down strokes out a selection between -the insert cursor and the character under the mouse. -.IP \0\(bu 4 -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insert cursor at the end of the word. -Dragging after a double click strokes out a selection consisting -of whole words. -.IP \0\(bu 4 -Triple-clicking with mouse button 1 selects all of the text in the -entry and positions the insert cursor at the end of the line. -.IP \0\(bu 4 -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. -.IP \0\(bu 4 -Clicking mouse button 1 with the Control key down will position the -insert cursor in the entry without affecting the selection. -.IP \0\(bu 4 -If any normal printing characters are typed in an entry, they are -inserted at the point of the insert cursor. -.IP \0\(bu 4 -The view in the entry can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the entry at the position of the mouse cursor. -.IP \0\(bu 4 -If the mouse is dragged out of the entry on the left or right sides -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP \0\(bu 4 -The Left and Right keys move the insert cursor one character to the -left or right; they also clear any selection in the entry. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insert cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insert cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -.IP \0\(bu 4 -The Home key and Control-a move the insert cursor to the -beginning of the entry and clear any selection in the entry. -Shift-Home moves the insert cursor to the beginning of the entry -and extends the selection to that point. -.IP \0\(bu 4 -The End key and Control-e move the insert cursor to the -end of the entry and clear any selection in the entry. -Shift-End moves the cursor to the end and extends the selection -to that point. -.IP \0\(bu 4 -Control-/ selects all the text in the entry. -.IP \0\(bu 4 -Control-\e clears any selection in the entry. -.IP \0\(bu 4 -The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> -virtual events operate on the selection in the expected manner. -.IP \0\(bu 4 -The Delete key deletes the selection, if there is one in the entry. -If there is no selection, it deletes the character to the right of -the insert cursor. -.IP \0\(bu 4 -The BackSpace key and Control-h delete the selection, if there is one -in the entry. -If there is no selection, it deletes the character to the left of -the insert cursor. -.IP \0\(bu 4 -Control-d deletes the character to the right of the insert cursor. -.IP \0\(bu 4 -Control-k deletes all the characters to the right of the insertion -cursor. -.SH "WIDGET STATES" -.PP -In the \fBdisabled\fR state, -the entry cannot be edited and the text cannot be selected. -In the \fBreadonly\fR state, -no insert cursor is displayed and -the entry cannot be edited -(specifically: the \fBinsert\fR and \fBdelete\fR commands have no effect). -The \fBdisabled\fR state is the same as \fBreadonly\fR, -and in addition text cannot be selected. -.PP -Note that changes to the linked \fB\-textvariable\fR will -still be reflected in the entry, even if it is disabled or readonly. -.PP -Typically, the text is -.QW grayed-out -in the \fBdisabled\fR state, -and a different background is used in the \fBreadonly\fR state. -.PP -The entry widget sets the \fBinvalid\fR state if revalidation fails, -and clears it whenever validation succeeds. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::entry\fP is \fBTEntry\fP. -.PP -Dynamic states: \fBdisabled\fP, \fBfocus\fP, \fBreadonly\fP. -.PP -\fBTEntry\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.RS -When using the aqua theme (Mac OS X), changes the \fB\-fieldbackground\fP. -.RE -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-fieldbackground\fP \fIcolor\fP -.RS -Does not work with the aqua theme (Mac OS X). -.br -Some themes use a graphical background and their field background colors cannot be changed. -.RE -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-insertwidth\fP \fIamount\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-relief\fP \fIrelief\fP -.br -\fB\-selectbackground\fP \fIcolor\fP -.br -\fB\-selectborderwidth\fP \fIamount\fP -.br -\fB\-selectforeground\fP \fIcolor\fP -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), entry(n) -.SH KEYWORDS -entry, widget, text field -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_frame.n b/tk8.6/doc/ttk_frame.n deleted file mode 100644 index 8702592..0000000 --- a/tk8.6/doc/ttk_frame.n +++ /dev/null @@ -1,67 +0,0 @@ -'\" -'\" Copyright (c) 2005 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::frame n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::frame \- Simple container widget -.SH SYNOPSIS -\fBttk::frame\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::frame\fR widget is a container, used to group other widgets -together. -.SO ttk_widget -\-class \-cursor \-padding \-style -\-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-borderwidth borderWidth BorderWidth -The desired width of the widget border. Defaults to 0. -.OP \-relief relief Relief -One of the standard Tk border styles: -\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, -\fBsolid\fR, or \fBsunken\fR. -Defaults to \fBflat\fR. -.OP \-width width Width -If specified, the widget's requested width in pixels. -.OP \-height height Height -If specified, the widget's requested height in pixels. -.SH "WIDGET COMMAND" -.PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. -.SH "NOTES" -.PP -Note that if the \fBpack\fR, \fBgrid\fR, or other geometry managers -are used to manage the children of the \fBframe\fR, -by the GM's requested size will normally take precedence -over the \fBframe\fR widget's \fB\-width\fR and \fB\-height\fR options. -\fBpack propagate\fR and \fBgrid propagate\fR can be used -to change this. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::frame\fP is \fBTFrame\fP. -.PP -\fBTFrame\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::labelframe(n), frame(n) -.SH "KEYWORDS" -widget, frame, container -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_image.n b/tk8.6/doc/ttk_image.n deleted file mode 100644 index bc1dd3f..0000000 --- a/tk8.6/doc/ttk_image.n +++ /dev/null @@ -1,98 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk_image n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk_image \- Define an element based on an image -.SH SYNOPSIS -\fBttk::style element create \fIname\fR \fBimage\fR \fIimageSpec\fR ?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -The \fIimage\fR element factory creates a new element -in the current theme whose visual appearance is determined -by Tk images. -\fIimageSpec\fP is a list of one or more elements. -The first element is the default image name. -The rest of the list is a sequence of \fIstatespec / value\fR -pairs specifying other images to use when the element is -in a particular state or combination of states. -.SH OPTIONS -.PP -Valid \fIoptions\fR are: -.TP -\fB\-border\fR \fIpadding\fR -\fIpadding\fR is a list of up to four integers, specifying -the left, top, right, and bottom borders, respectively. -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right border; -a list of two numbers specify the horizontal and the vertical border; -a single number specifies the same border all the way around the element. -See \fBIMAGE STRETCHING\fR, below. -.TP -\fB\-height \fIheight\fR -Specifies a minimum height for the element. -If less than zero, the base image's height is used as a default. -.TP -\fB\-padding\fR \fIpadding\fR -Specifies the element's interior padding. -The padding is a list of up to four length specifications -\fIleft top right bottom\fR. -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; -a single number specifies the same padding all the way around the widget. -Defaults to \fB\-border\fR if not specified. -.TP -\fB\-sticky\fR \fIspec\fR -Specifies how the image is placed within the final parcel. -\fIspec\fR contains zero or more characters -.QW n , -.QW s , -.QW w , -or -.QW e . -.TP -\fB\-width \fIwidth\fR -Specifies a minimum width for the element. -If less than zero, the base image's width is used as a default. -.SH "IMAGE STRETCHING" -.PP -If the element's allocated parcel is larger than the image, -the image will be placed in the parcel based on the \fB\-sticky\fR option. -If the image needs to stretch horizontally (i.e., \fB\-sticky ew\fR) -or vertically (\fB\-sticky ns\fR), -subregions of the image are replicated to fill the parcel -based on the \fB\-border\fR option. -The \fB\-border\fR divides the image into 9 regions: -four fixed corners, top and left edges (which may be tiled horizontally), -left and right edges (which may be tiled vertically), -and the central area (which may be tiled in both directions). -.SH "EXAMPLE" -.PP -.CS -set img1 [image create photo \-file button.png] -set img2 [image create photo \-file button-pressed.png] -set img3 [image create photo \-file button-active.png] -style element create Button.button image \e - [list $img1 pressed $img2 active $img3] \e - \-border {2 4} \-sticky we -.CE -.SH "SEE ALSO" -ttk::intro(n), ttk::style(n), ttk_vsapi(n), image(n), photo(n) -.SH KEYWORDS -style, theme, appearance, pixmap theme, image -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_intro.n b/tk8.6/doc/ttk_intro.n deleted file mode 100644 index bc3cd69..0000000 --- a/tk8.6/doc/ttk_intro.n +++ /dev/null @@ -1,177 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::intro n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::intro \- Introduction to the Tk theme engine -.BE -.SH "OVERVIEW" -.PP -The Tk themed widget set is based on a revised and enhanced version -of TIP #48 (http://tip.tcl.tk/48) specified style engine. -The main concepts are described below. -The basic idea is to separate, to the extent possible, -the code implementing a widget's behavior from -the code implementing its appearance. -Widget class bindings are primarily responsible for -maintaining the widget state and invoking callbacks; -all aspects of the widget's appearance are controlled by the style of -the widget (i.e. the style of the elements of the widget). -.SH "THEMES" -.PP -A \fItheme\fR is a collection of elements and styles -that determine the look and feel of the widget set. -Themes can be used to: -.IP \(bu -isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...) -.IP \(bu -adapt to display limitations (low-color, grayscale, monochrome, tiny screens) -.IP \(bu -accessibility (high contrast, large type) -.IP \(bu -application suite branding -.IP \(bu -blend in with the rest of the desktop (Gnome, KDE, Java) -.IP \(bu -and, of course: eye candy. -.SH "ELEMENTS" -.PP -An \fIelement\fR displays an individual part of a widget. -For example, a vertical scrollbar widget contains \fBuparrow\fR, -\fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements. -.PP -Element names use a recursive dotted notation. -For example, \fBuparrow\fR identifies a generic arrow element, -and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify -widget-specific elements. -When looking for an element, the style engine looks for -the specific name first, and if an element of that name is -not found it looks for generic elements by stripping off -successive leading components of the element name. -.PP -Like widgets, elements have \fIoptions\fR which -specify what to display and how to display it. -For example, the \fBtext\fR element -(which displays a text string) has -\fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, -\fB\-underline\fR, and \fB\-width\fR options. -The value of an element option is taken from: -.IP \(bu -an option of the same name and type in the widget containing the element; -.IP \(bu -a dynamic setting specified by \fBstyle map\fR and the current state; -.IP \(bu -the default setting specified by \fBstyle configure\fR; or -.IP \(bu -the element's built-in default value for the option. -.SH "LAYOUTS" -.PP -A \fIlayout\fR specifies which elements make up a widget -and how they are arranged. -The layout engine uses a simplified version of the \fBpack\fR -algorithm: starting with an initial cavity equal to the size -of the widget, elements are allocated a parcel within the cavity along -the side specified by the \fB\-side\fR option, -and placed within the parcel according to the \fB\-sticky\fR -option. -For example, the layout for a horizontal scrollbar is: -.PP -.CS -ttk::\fBstyle layout\fR Horizontal.TScrollbar { - Scrollbar.trough \-children { - Scrollbar.leftarrow \-side left \-sticky w - Scrollbar.rightarrow \-side right \-sticky e - Scrollbar.thumb \-side left \-expand true \-sticky ew - } -} -.CE -.PP -By default, the layout for a widget is the same as its class name. -Some widgets may override this (for example, the \fBttk::scrollbar\fR -widget chooses different layouts based on the \fB\-orient\fR option). -.SH "STATES" -.PP -In standard Tk, many widgets have a \fB\-state\fR option -which (in most cases) is either \fBnormal\fR or \fBdisabled\fR. -Some widgets support additional states, such -as the \fBentry\fR widget which has a \fBreadonly\fR state -and the various flavors of buttons which have \fBactive\fR state. -.PP -The themed Tk widgets generalizes this idea: -every widget has a bitmap of independent state flags. -Widget state flags include \fBactive\fR, \fBdisabled\fR, -\fBpressed\fR, \fBfocus\fR, etc., -(see \fIttk::widget(n)\fR for the full list of state flags). -.PP -Instead of a \fB\-state\fR option, every widget now has -a \fBstate\fR widget command which is used to set or query -the state. -A \fIstate specification\fR is a list of symbolic state names -indicating which bits are set, each optionally prefixed with an -exclamation point indicating that the bit is cleared instead. -.PP -For example, the class bindings for the \fBttk::button\fR -widget are: -.PP -.CS -bind TButton <Enter> { %W state active } -bind TButton <Leave> { %W state !active } -bind TButton <ButtonPress-1> { %W state pressed } -bind TButton <Button1-Leave> { %W state !pressed } -bind TButton <Button1-Enter> { %W state pressed } -bind TButton <ButtonRelease-1> \e - { %W instate {pressed} { %W state !pressed ; %W invoke } } -.CE -.PP -This specifies that the widget becomes \fBactive\fR when -the pointer enters the widget, and inactive when it leaves. -Similarly it becomes \fBpressed\fR when the mouse button is pressed, -and \fB!pressed\fR on the ButtonRelease event. -In addition, the button unpresses if -pointer is dragged outside the widget while Button-1 is held down, -and represses if it's dragged back in. -Finally, when the mouse button is released, the widget's -\fB\-command\fR is invoked, but only if the button is currently -in the \fBpressed\fR state. -(The actual bindings are a little more complicated than the above, -but not by much). -'\" Note to self: rewrite that paragraph. It's horrible. -.SH "STYLES" -.PP -Each widget is associated with a \fIstyle\fR, -which specifies values for element options. -Style names use a recursive dotted notation like layouts and elements; -by default, widgets use the class name to look up a style in the current theme. -For example: -.PP -.CS -ttk::\fBstyle configure\fR TButton \e - \-background #d9d9d9 \e - \-foreground black \e - \-relief raised \e - ; -.CE -.PP -Many elements are displayed differently depending on the widget state. -For example, buttons have a different background when they are active, -a different foreground when disabled, and a different relief when pressed. -The \fBstyle map\fR command specifies dynamic option settings -for a particular style: -.PP -.CS -ttk::\fBstyle map\fR TButton \e - \-background [list disabled #d9d9d9 active #ececec] \e - \-foreground [list disabled #a3a3a3] \e - \-relief [list {pressed !disabled} sunken] \e - ; -.CE -.SH "SEE ALSO" -ttk::widget(n), ttk::style(n) -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_label.n b/tk8.6/doc/ttk_label.n deleted file mode 100644 index aae95e6..0000000 --- a/tk8.6/doc/ttk_label.n +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::label n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::label \- Display a text string and/or image -.SH SYNOPSIS -\fBttk::label\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::label\fR widget displays a textual label and/or image. -The label may be linked to a Tcl variable -to automatically change the displayed text. -.SO ttk_widget -\-class \-compound \-cursor -\-image \-padding \-state \-style \-takefocus -\-text \-textvariable \-underline -\-width -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-anchor anchor Anchor -Specifies how the information in the widget is positioned -relative to the inner margins. Legal values are -\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR. -See also \fB\-justify\fR. -.OP \-background frameColor FrameColor -The widget's background color. -If unspecified, the theme default is used. -.OP \-font font Font -Font to use for label text. -.OP \-foreground textColor TextColor -The widget's foreground color. -If unspecified, the theme default is used. -.OP \-justify justify Justify -If there are multiple lines of text, specifies how -the lines are laid out relative to one another. -One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -See also \fB\-anchor\fR. -.OP \-relief relief Relief -.\" Rewrite this: -Specifies the 3-D effect desired for the widget border. -Valid values are -\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, -and \fBsunken\fR. -.OP \-text text Text -Specifies a text string to be displayed inside the widget -(unless overridden by \fB\-textvariable\fR). -.OP \-wraplength wrapLength WrapLength -Specifies the maximum line length (in pixels). -If this option is less than or equal to zero, -then automatic wrapping is not performed; otherwise -the text is split into lines such that no line is longer -than the specified value. -.SH "WIDGET COMMAND" -.PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::label\fP is \fBTLabel\fP. -.PP -Dynamic states: \fBdisabled\fP, \fBreadonly\fP. -.PP -\fBTLabel\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), label(n) -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_labelframe.n b/tk8.6/doc/ttk_labelframe.n deleted file mode 100644 index 12f0b89..0000000 --- a/tk8.6/doc/ttk_labelframe.n +++ /dev/null @@ -1,114 +0,0 @@ -'\" -'\" Copyright (c) 2005 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::labelframe n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::labelframe \- Container widget with optional label -.SH SYNOPSIS -\fBttk::labelframe\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::labelframe\fR widget is a container used to group other widgets -together. It has an optional label, which may be a plain text string or -another widget. -.SO ttk_widget -\-class \-cursor \-padding \-style -\-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.\" XXX: Currently included, but may go away: -.\" XXX: .OP -borderwidth borderWidth BorderWidth -.\" XXX: The desired width of the widget border. Default is theme-dependent. -.\" XXX: .OP -relief relief Relief -.\" XXX: One of the standard Tk border styles: -.\" XXX: \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, -.\" XXX: \fBsolid\fR, or \fBsunken\fR. -.\" XXX: Default is theme-dependent. -.OP \-labelanchor labelAnchor LabelAnchor -Specifies where to place the label. -Allowed values are (clockwise from the top upper left corner): -\fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, -\fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. -The default value is theme-dependent. -.\" Alternate explanation: The first character must be one of n, s, e, or w -.\" and specifies which side the label should be placed on; -.\" the remaining characters specify how the label is aligned on that side. -.\" NOTE: Now allows other values as well; leave this undocumented for now -.OP \-text text Text -Specifies the text of the label. -.OP \-underline underline Underline -If set, specifies the integer index (0-based) of a character to -underline in the text string. -The underlined character is used for mnemonic activation. -Mnemonic activation for a \fBttk::labelframe\fR -sets the keyboard focus to the first child of the \fBttk::labelframe\fR widget. -.OP \-labelwidget labelWidget LabelWidget -The name of a widget to use for the label. -If set, overrides the \fB\-text\fR option. -The \fB\-labelwidget\fR must be a child of the \fBlabelframe\fR widget -or one of the \fBlabelframe\fR's ancestors, and must belong to the -same top-level widget as the \fBlabelframe\fR. -.OP \-width width Width -If specified, the widget's requested width in pixels. -.OP \-height height Height -If specified, the widget's requested height in pixels. -(See \fIttk::frame(n)\fR for further notes on \fB\-width\fR and -\fB\-height\fR). -.SH "WIDGET COMMAND" -.PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::labelframe\fP is \fBTLabelframe\fP. -The text label -has a class of \fBTLabelframe.Label\fP. -.PP -Dynamic states: \fBdisabled\fP, \fBreadonly\fP. -.PP -\fBTLabelframe\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-borderwidth\fP \fIamount\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-labelmargins\fP \fIamount\fP -.br -\fB\-labeloutside\fP \fIboolean\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-relief\fP \fIrelief\fP -.PP -\fBTLabelframe.Label\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.br -\fB\-foreground\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::frame(n), labelframe(n) -.SH "KEYWORDS" -widget, frame, container, label, groupbox -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_menubutton.n b/tk8.6/doc/ttk_menubutton.n deleted file mode 100644 index 76d3829..0000000 --- a/tk8.6/doc/ttk_menubutton.n +++ /dev/null @@ -1,81 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::menubutton n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::menubutton \- Widget that pops down a menu when pressed -.SH SYNOPSIS -\fBttk::menubutton\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::menubutton\fR widget displays a textual label and/or image, -and displays a menu when pressed. -.SO ttk_widget -\-class \-compound \-cursor -\-image \-state \-style -\-takefocus \-text \-textvariable -\-underline \-width -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-direction direction Direction -Specifies where the menu is to be popped up relative -to the menubutton. -One of: \fBabove\fR, \fBbelow\fR, \fBleft\fR, \fBright\fR, -or \fBflush\fR. The default is \fBbelow\fR. -\fBflush\fR pops the menu up directly over the menubutton. -.OP \-menu menu Menu -Specifies the path name of the menu associated with the menubutton. -To be on the safe side, the menu ought to be a direct child of the -menubutton. -.\" not documented: may go away: -.\" .OP \-anchor anchor Anchor -.\" .OP \-padding padding Pad -.SH "WIDGET COMMAND" -.PP -Menubutton widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. -.SH "STANDARD STYLES" -.PP -\fBTtk::menubutton\fR widgets support the \fBToolbutton\fR style in all -standard themes, which is useful for creating widgets for toolbars. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::menubutton\fP is \fBTMenubutton\fP. -.PP -Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBreadonly\fP. -.PP -\fBTMenubutton\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-arrowsize\fP \fIamount\fP -.br -\fB\-background\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-relief\fP \fIrelief\fP -.br -\fB\-width\fP \fIamount\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), menu(n), menubutton(n) -.SH "KEYWORDS" -widget, button, menu -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_notebook.n b/tk8.6/doc/ttk_notebook.n deleted file mode 100644 index 19416b5..0000000 --- a/tk8.6/doc/ttk_notebook.n +++ /dev/null @@ -1,267 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::notebook n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::notebook \- Multi-paned container widget -.SH SYNOPSIS -.nf -\fBttk::notebook\fR \fIpathname \fR?\fIoptions...\fR? -.br -\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? -.fi -.BE -.SH DESCRIPTION -A \fBttk::notebook\fR widget manages a collection of windows -and displays a single one at a time. -Each slave window is associated with a \fItab\fR, -which the user may select to change the currently-displayed window. -.SO ttk_widget -\-class \-cursor \-takefocus -\-style -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-height height Height -If present and greater than zero, -specifies the desired height of the pane area -(not including internal padding or tabs). -Otherwise, the maximum height of all panes is used. -.OP \-padding padding Padding -Specifies the amount of extra space to add around the outside -of the notebook. -The padding is a list of up to four length specifications -\fIleft top right bottom\fR. -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; -a single number specifies the same padding all the way around the widget. -.OP \-width width Width -If present and greater than zero, -specifies the desired width of the pane area -(not including internal padding). -Otherwise, the maximum width of all panes is used. -.SH "TAB OPTIONS" -The following options may be specified for individual notebook panes: -.OP \-state state State -Either \fBnormal\fR, \fBdisabled\fR or \fBhidden\fR. -If \fBdisabled\fR, then the tab is not selectable. -If \fBhidden\fR, then the tab is not shown. -.OP \-sticky sticky Sticky -Specifies how the slave window is positioned within the pane area. -Value is a string containing zero or more of the characters -\fBn, s, e,\fR or \fBw\fR. -Each letter refers to a side (north, south, east, or west) -that the slave window will -.QW stick -to, as per the \fBgrid\fR geometry manager. -.OP \-padding padding Padding -Specifies the amount of extra space to add between the notebook and this pane. -Syntax is the same as for the widget \fB\-padding\fR option. -.OP \-text text Text -Specifies a string to be displayed in the tab. -.OP \-image image Image -Specifies an image to display in the tab. -See \fIttk_widget(n)\fR for details. -.OP \-compound compound Compound -Specifies how to display the image relative to the text, -in the case both \fB\-text\fR and \fB\-image\fR are present. -See \fIlabel(n)\fR for legal values. -.OP \-underline underline Underline -Specifies the integer index (0-based) of a character to underline -in the text string. -The underlined character is used for mnemonic activation -if \fBttk::notebook::enableTraversal\fR is called. -.SH "TAB IDENTIFIERS" -The \fItabid\fR argument to the following commands may take -any of the following forms: -.IP \(bu -An integer between zero and the number of tabs; -.IP \(bu -The name of a slave window; -.IP \(bu -A positional specification of the form -.QW @\fIx\fR,\fIy\fR , -which identifies the tab -.IP \(bu -The literal string -.QW \fBcurrent\fR , -which identifies the currently-selected tab; or: -.IP \(bu -The literal string -.QW \fBend\fR , -which returns the number of tabs -(only valid for -.QW "\fIpathname \fBindex\fR" ). -.SH "WIDGET COMMAND" -.TP -\fIpathname \fBadd \fIwindow\fR ?\fIoptions...\fR? -Adds a new tab to the notebook. -See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR. -If \fIwindow\fR is currently managed by the notebook but hidden, -it is restored to its previous position. -.TP -\fIpathname \fBconfigure\fR ?\fIoptions\fR? -See \fIttk::widget(n)\fR. -.TP -\fIpathname \fBcget \fIoption\fR -See \fIttk::widget(n)\fR. -.TP -\fIpathname \fBforget \fItabid\fR -Removes the tab specified by \fItabid\fR, -unmaps and unmanages the associated window. -.TP -\fIpathname \fBhide \fItabid\fR -Hides the tab specified by \fItabid\fR. -The tab will not be displayed, but the associated window -remains managed by the notebook and its configuration remembered. -Hidden tabs may be restored with the \fBadd\fR command. -.TP -\fIpathname \fBidentify\fI component x y\fR -Returns the name of the element under the point given by \fIx\fR and \fIy\fR, -or the empty string if no component is present at that location. -The following subcommands are supported: -.RS -.TP -\fIpathname \fBidentify element\fR \fIx y\fR -Returns the name of the element at the specified location. -.TP -\fIpathname \fBidentify tab\fR \fIx y\fR -Returns the index of the tab at the specified location. -.RE -.TP -\fIpathname \fBindex \fItabid\fR -Returns the numeric index of the tab specified by \fItabid\fR, -or the total number of tabs if \fItabid\fR is the string -.QW \fBend\fR . -.TP -\fIpathname \fBinsert \fIpos subwindow options...\fR -Inserts a pane at the specified position. -\fIpos\fR is either the string \fBend\fR, an integer index, -or the name of a managed subwindow. -If \fIsubwindow\fR is already managed by the notebook, -moves it to the specified position. -See \fBTAB OPTIONS\fR for the list of available options. -.TP -\fIpathname \fBinstate \fIstatespec \fR?\fIscript...\fR? -See \fIttk::widget(n)\fR. -.TP -\fIpathname \fBselect\fR ?\fItabid\fR? -Selects the specified tab. -The associated slave window will be displayed, -and the previously-selected window (if different) is unmapped. -If \fItabid\fR is omitted, returns the widget name of the -currently selected pane. -.TP -\fIpathname \fBstate\fR ?\fIstatespec\fR? -See \fIttk::widget(n)\fR. -.TP -\fIpathname \fBtab \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR -Query or modify the options of the specific tab. -If no \fI\-option\fR is specified, -returns a dictionary of the tab option values. -If one \fI\-option\fR is specified, -returns the value of that \fIoption\fR. -Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. -See \fBTAB OPTIONS\fR for the available options. -.TP -\fIpathname \fBtabs\fR -Returns the list of windows managed by the notebook, in the index order of -their associated tabs. -.SH "KEYBOARD TRAVERSAL" -To enable keyboard traversal for a toplevel window -containing a notebook widget \fI$nb\fR, call: -.CS -ttk::notebook::enableTraversal $nb -.CE -.PP -This will extend the bindings for the toplevel window -containing the notebook as follows: -.IP \(bu -\fBControl-Tab\fR selects the tab following the currently selected one. -.IP \(bu -\fBControl-Shift-Tab\fR selects the tab preceding the currently selected one. -.IP \(bu -\fBAlt-\fIK\fR, where \fIK\fR is the mnemonic (underlined) character -of any tab, will select that tab. -.PP -Multiple notebooks in a single toplevel may be enabled for traversal, -including nested notebooks. -However, notebook traversal only works properly if all panes -are direct children of the notebook. -.SH "VIRTUAL EVENTS" -The notebook widget generates a \fB<<NotebookTabChanged>>\fR -virtual event after a new tab is selected. -.SH "EXAMPLE" -.CS -pack [\fBttk::notebook\fR .nb] -\&.nb add [frame .nb.f1] \-text "First tab" -\&.nb add [frame .nb.f2] \-text "Second tab" -\&.nb select .nb.f2 -ttk::notebook::enableTraversal .nb -.CE -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::notebook\fP is \fBTNotebook\fP. The tab has -a class name of \fBTNotebook.Tab\fP -.PP -Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBselected\fP. -.PP -\fBTNotebook\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-tabmargins\fP \fIpadding\fP -.br -\fB\-tabposition\fP \fIside\fP -.br -.PP -\fBTNotebook.Tab\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-expand\fP \fIpadding\fP -.RS -Defines how much the tab grows in size. Usually used with the -\fBselected\fP dynamic state. \fB\-tabmargins\fP should be -set appropriately so that there is room for the tab growth. -.RE -\fB\-font\fP \fIfont\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), grid(n) -.SH "KEYWORDS" -pane, tab -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_panedwindow.n b/tk8.6/doc/ttk_panedwindow.n deleted file mode 100644 index d6b3ea3..0000000 --- a/tk8.6/doc/ttk_panedwindow.n +++ /dev/null @@ -1,162 +0,0 @@ -'\" -'\" Copyright (c) 2005 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::panedwindow n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::panedwindow \- Multi-pane container window -.SH SYNOPSIS -.nf -\fBttk::panedwindow\fR \fIpathname \fR?\fIoptions\fR? -.br -\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? -.fi -.BE -.SH DESCRIPTION -A \fBttk::panedwindow\fR widget displays a number of subwindows, -stacked either vertically or horizontally. -The user may adjust the relative sizes of the subwindows -by dragging the sash between panes. -.SO ttk_widget -\-class \-cursor \-takefocus -\-style -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-orient orient Orient -Specifies the orientation of the window. -If \fBvertical\fR, subpanes are stacked top-to-bottom; -if \fBhorizontal\fR, subpanes are stacked left-to-right. -.OP \-width width Width -If present and greater than zero, -specifies the desired width of the widget in pixels. -Otherwise, the requested width is determined by the width -of the managed windows. -.OP \-height height Height -If present and greater than zero, -specifies the desired height of the widget in pixels. -Otherwise, the requested height is determined by the height -of the managed windows. -.SH "PANE OPTIONS" -The following options may be specified for each pane: -.OP \-weight weight Weight -An integer specifying the relative stretchability of the pane. -When the paned window is resized, the extra space is added -or subtracted to each pane proportionally to its \fB\-weight\fR. -.SH "WIDGET COMMAND" -Supports the standard \fBconfigure\fR, \fBcget\fR, \fBstate\fR, -and \fBinstate\fR commands; see \fIttk::widget(n)\fR for details. -Additional commands: -.TP -\fIpathname \fBadd \fIsubwindow options...\fR -Adds a new pane to the window. -See \fBPANE OPTIONS\fR for the list of available options. -.TP -\fIpathname \fBforget \fIpane\fR -Removes the specified subpane from the widget. -\fIpane\fR is either an integer index or the name of a managed subwindow. -.TP -\fIpathname \fBidentify \fIcomponent x y\fR -Returns the name of the element under the point given by \fIx\fR and \fIy\fR, -or the empty string if no component is present at that location. -If \fIcomponent\fR is omitted, it defaults to \fBsash\fR. -The following subcommands are supported: -.RS -.TP -\fIpathname \fBidentify element \fIx y\fR -Returns the name of the element at the specified location. -.TP -\fIpathname \fBidentify sash \fIx y\fR -Returns the index of the sash at the specified location. -.RE -.TP -\fIpathname \fBinsert \fIpos subwindow options...\fR -Inserts a pane at the specified position. -\fIpos\fR is either the string \fBend\fR, an integer index, -or the name of a managed subwindow. -If \fIsubwindow\fR is already managed by the paned window, -moves it to the specified position. -See \fBPANE OPTIONS\fR for the list of available options. -.TP -\fIpathname \fBpane \fIpane \-option \fR?\fIvalue \fR?\fI\-option value...\fR -Query or modify the options of the specified \fIpane\fR, -where \fIpane\fR is either an integer index or the name of a managed subwindow. -If no \fI\-option\fR is specified, returns a dictionary of the pane -option values. -If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. -Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. -.TP -\fIpathname \fBpanes\fR -Returns the list of all windows managed by the widget, in the index order of -their associated panes. -.TP -\fIpathname \fBsashpos \fIindex\fR ?\fInewpos\fR? -If \fInewpos\fR is specified, sets the position -of sash number \fIindex\fR. -May adjust the positions of adjacent sashes -to ensure that positions are monotonically increasing. -Sash positions are further constrained to be between 0 -and the total size of the widget. -.\" Full story: "total size" is either the -height (resp -width), -.\" or the actual window height (resp actual window width), -.\" depending on which changed most recently. -Returns the new position of sash number \fIindex\fR. -.\" Full story: new position may be different than the requested position. -.PP -The panedwindow widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR -\fBinstate\fR \fBstate\fR -.DE -.SH "VIRTUAL EVENTS" -.PP -The panedwindow widget generates an \fB<<EnteredChild>>\fR virtual event on -LeaveNotify/NotifyInferior events, because Tk does not execute binding scripts -for <Leave> events when the pointer crosses from a parent to a child. The -panedwindow widget needs to know when that happens. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::panedwindow\fP is \fBTPanedwindow\fP. The -sash has a class name of \fBSash\fP. -.PP -\fBTPanedwindow\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.PP -\fBSash\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-gripcount\fP \fIcount\fP -.br -\fB\-handlepad\fP \fIamount\fP -.br -\fB\-handlesize\fP \fIamount\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-sashpad\fP \fIamount\fP -.br -\fB\-sashrelief\fP \fIrelief\fP -.br -\fB\-sashthickness\fP \fIamount\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::notebook(n), panedwindow(n) -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_progressbar.n b/tk8.6/doc/ttk_progressbar.n deleted file mode 100644 index 1687123..0000000 --- a/tk8.6/doc/ttk_progressbar.n +++ /dev/null @@ -1,122 +0,0 @@ -'\" -'\" Copyright (c) 2005 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::progressbar n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::progressbar \- Provide progress feedback -.SH SYNOPSIS -\fBttk::progressbar\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::progressbar\fR widget shows the status of a long-running -operation. They can operate in two modes: \fIdeterminate\fR mode shows the -amount completed relative to the total amount of work to be done, and -\fIindeterminate\fR mode provides an animated display to let the user know -that something is happening. -.SO ttk_widget -\-class \-cursor \-takefocus -\-style -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-length length Length -Specifies the length of the long axis of the progress bar -(width if horizontal, height if vertical). -.OP \-maximum maximum Maximum -A floating point number specifying the maximum \fB\-value\fR. -Defaults to 100. -.OP \-mode mode Mode -One of \fBdeterminate\fR or \fBindeterminate\fR. -.OP \-orient orient Orient -One of \fBhorizontal\fR or \fBvertical\fR. -Specifies the orientation of the progress bar. -.OP \-phase phase Phase -Read-only option. -The widget periodically increments the value of this option -whenever the \fB\-value\fR is greater than 0 and, -in \fIdeterminate\fR mode, less than \fB\-maximum\fR. -This option may be used by the current theme -to provide additional animation effects. -.OP \-value value Value -The current value of the progress bar. -In \fIdeterminate\fR mode, this represents the amount of work completed. -In \fIindeterminate\fR mode, it is interpreted modulo \fB\-maximum\fR; -that is, the progress bar completes one -.QW cycle -when the \fB\-value\fR increases by \fB\-maximum\fR. -.OP \-variable variable Variable -The name of a global Tcl variable which is linked to the \fB\-value\fR. -If specified, the \fB\-value\fR of the progress bar is -automatically set to the value of the variable whenever -the latter is modified. -.SH "WIDGET COMMAND" -.PP -.TP -\fIpathName \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBstart\fR ?\fIinterval\fR? -Begin autoincrement mode: -schedules a recurring timer event that calls \fBstep\fR -every \fIinterval\fR milliseconds. -If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBstep\fR ?\fIamount\fR? -Increments the \fB\-value\fR by \fIamount\fR. -\fIamount\fR defaults to 1.0 if omitted. -.TP -\fIpathName \fBstop\fR -Stop autoincrement mode: -cancels any recurring timer event initiated by \fIpathName \fBstart\fR. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::progressbar\fP is \fBTProgressbar\fP. -.PP -\fBTProgressbar\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-maxphase\fP -.RS -For the aqua theme. -.RE -\fB\-period\fP -.RS -For the aqua theme. -.RE -\fB\-troughcolor\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n) -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_radiobutton.n b/tk8.6/doc/ttk_radiobutton.n deleted file mode 100644 index 1344ae2..0000000 --- a/tk8.6/doc/ttk_radiobutton.n +++ /dev/null @@ -1,102 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::radiobutton n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::radiobutton \- Mutually exclusive option widget -.SH SYNOPSIS -\fBttk::radiobutton\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -\fBttk::radiobutton\fR widgets are used in groups to show or change -a set of mutually-exclusive options. -Radiobuttons are linked to a Tcl variable, -and have an associated value; when a radiobutton is clicked, -it sets the variable to its associated value. -.SO ttk_widget -\-class \-compound \-cursor -\-image \-state \-style -\-takefocus \-text \-textvariable -\-underline \-width -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -A Tcl script to evaluate whenever the widget is invoked. -.OP \-value Value Value -The value to store in the associated \fB\-variable\fR -when the widget is selected. -.OP \-variable variable Variable -The name of a global variable whose value is linked to the widget. -Default value is \fB::selectedButton\fR. -.SH "WIDGET COMMAND" -.PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, radiobuttons support the following additional -widget commands: -.TP -\fIpathname\fB invoke\fR -Sets the \fB\-variable\fR to the \fB\-value\fR, selects the widget, -and evaluates the associated \fB\-command\fR. -Returns the result of the \fB\-command\fR, or the empty -string if no \fB\-command\fR is specified. -.\" Missing: select, deselect. Useful? -.\" Missing: flash. This is definitely not useful. -.SH "WIDGET STATES" -.PP -The widget does not respond to user input if the \fBdisabled\fR state is set. -The widget sets the \fBselected\fR state whenever -the linked \fB\-variable\fR is set to the widget's \fB\-value\fR, -and clears it otherwise. -The widget sets the \fBalternate\fR state whenever the -linked \fB\-variable\fR is unset. -(The \fBalternate\fR state may be used to indicate a -.QW tri-state -or -.QW indeterminate -selection.) -.SH "STANDARD STYLES" -.PP -\fBTtk::radiobutton\fR widgets support the \fBToolbutton\fR style in all -standard themes, which is useful for creating widgets for toolbars. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::radiobutton\fP is \fBTRadiobutton\fP. -.PP -Dynamic states: \fBactive\fP, \fBalternate\fP, \fBdisabled\fP, -\fBpressed\fP, \fBreadonly\fP, \fBselected\fP. -.PP -\fBTRadiobutton\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-indicatorbackground\fP \fIcolor\fP -.br -\fB\-indicatorcolor\fP \fIcolor\fP -.br -\fB\-indicatormargin\fP \fIpadding\fP -.br -\fB\-indicatorrelief\fP \fIrelief\fP -.br -\fB\-padding\fP \fIpadding\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::checkbutton(n), radiobutton(n) -.SH "KEYWORDS" -widget, button, option -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_scale.n b/tk8.6/doc/ttk_scale.n deleted file mode 100644 index 4e16999..0000000 --- a/tk8.6/doc/ttk_scale.n +++ /dev/null @@ -1,130 +0,0 @@ -.\" -.\" Copyright (c) 2008 Donal Fellows -.\" -.\" See the file "license.terms" for information on usage and redistribution -.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -.\" -.TH ttk::scale n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::scale \- Create and manipulate a scale widget -.SH SYNOPSIS -\fBttk::scale \fIpathName \fR?\fIoptions...\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::scale\fR widget is typically used to control the numeric value of a -linked variable that varies uniformly over some range. A scale displays a -\fIslider\fR that can be moved along over a \fItrough\fR, with the relative -position of the slider over the trough indicating the value of the variable. -.SO ttk_widget -\-class \-cursor \-style -\-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -Specifies the prefix of a Tcl command to invoke whenever the scale's value is -changed via a widget command. The actual command consists of this option -followed by a space and a real number indicating the new value of the scale. -.OP \-from from From -A real value corresponding to the left or top end of the scale. -.OP \-length length Length -Specifies the desired long dimension of the scale in screen units (i.e. any of -the forms acceptable to \fBTk_GetPixels\fR). For vertical scales this is the -scale's height; for horizontal scales it is the scale's width. -.OP \-orient orient Orient -Specifies which orientation whether the widget should be laid out horizontally -or vertically. Must be either \fBhorizontal\fR or \fBvertical\fR or an -abbreviation of one of these. -.OP \-to to To -Specifies a real value corresponding to the right or bottom end of the scale. -This value may be either less than or greater than the \fB\-from\fR option. -.OP \-value value Value -Specifies the current floating-point value of the variable. -.OP \-variable variable Variable -Specifies the name of a global variable to link to the scale. Whenever the -value of the variable changes, the scale will update to reflect this value. -Whenever the scale is manipulated interactively, the variable will be modified -to reflect the scale's new value. -.SH "WIDGET COMMAND" -.PP -.TP -\fIpathName \fBcget \fIoption\fR -. -Returns the current value of the specified \fIoption\fR; see -\fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Modify or query widget options; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBget \fR?\fIx y\fR? -. -Get the current value of the \fB\-value\fR option, or the value corresponding -to the coordinates \fIx,y\fR if they are specified. \fIX\fR and \fIy\fR are -pixel coordinates relative to the scale widget origin. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -. -Test the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBset \fIvalue\fR -. -Set the value of the widget (i.e. the \fB\-value\fR option) to \fIvalue\fR. -The value will be clipped to the range given by the \fB\-from\fR and -\fB\-to\fR options. Note that setting the linked variable (i.e. the variable -named in the \fB\-variable\fR option) does not cause such clipping. -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -. -Modify or query the widget state; see \fIttk::widget(n)\fR. -.SH "INTERNAL COMMANDS" -.PP -.TP -\fIpathName \fBcoords \fR?\fIvalue\fR? -. -Get the coordinates corresponding to \fIvalue\fR, or the coordinates -corresponding to the current value of the \fB\-value\fR option if \fIvalue\fR -is omitted. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::scale\fP is \fBTProgressbar\fP. -.PP -Dynamic states: \fBactive\fP. -.PP -\fBTProgressbar\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-borderwidth\fP \fIamount\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-groovewidth\fP \fIamount\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-sliderwidth\fP \fIamount\fP -.br -\fB\-troughcolor\fP \fIcolor\fP -.br -\fB\-troughrelief\fP \fIrelief\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), scale(n) -.SH KEYWORDS -scale, slider, trough, widget -.\" Local Variables: -.\" mode: nroff -.\" fill-column: 78 -.\" End: diff --git a/tk8.6/doc/ttk_scrollbar.n b/tk8.6/doc/ttk_scrollbar.n deleted file mode 100644 index 49681a1..0000000 --- a/tk8.6/doc/ttk_scrollbar.n +++ /dev/null @@ -1,190 +0,0 @@ -'\" -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::scrollbar n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::scrollbar \- Control the viewport of a scrollable widget -.SH SYNOPSIS -\fBttk::scrollbar\fR \fIpathName \fR?\fIoptions...\fR? -.BE -.SH DESCRIPTION -.PP -\fBttk::scrollbar\fR widgets are typically linked to an associated window -that displays a document of some sort, such as a file being edited or a -drawing. -A scrollbar displays a \fIthumb\fR in the middle portion of the scrollbar, -whose position and size provides information about the portion of the -document visible in the associated window. -The thumb may be dragged by the user to control the visible region. -Depending on the theme, two or more arrow buttons may also be present; -these are used to scroll the visible region in discrete units. -.SO ttk_widget -\-class \-cursor \-style -\-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -A Tcl script prefix to evaluate -to change the view in the widget associated with the scrollbar. -Additional arguments are appended to the value of this option, -as described in \fBSCROLLING COMMANDS\fR below, -whenever the user requests a view change by manipulating the scrollbar. -.RS -.PP -This option typically consists of a two-element list, -containing the name of a scrollable widget followed by -either \fBxview\fR (for horizontal scrollbars) -or \fByview\fR (for vertical scrollbars). -.RE -.OP \-orient orient Orient -One of \fBhorizontal\fR or \fBvertical\fR. -Specifies the orientation of the scrollbar. -.SH "WIDGET COMMAND" -.PP -.TP -\fIpathName \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBget\fR -Returns the scrollbar settings in the form of a list whose -elements are the arguments to the most recent \fBset\fR widget command. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBset \fIfirst last\fR -This command is normally invoked by the scrollbar's associated widget -from an \fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. -Specifies the visible range to be displayed. -\fIfirst\fR and \fIlast\fR are real fractions between 0 and 1. -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. -.SH "INTERNAL COMMANDS" -.PP -The following widget commands are used internally -by the TScrollbar widget class bindings. -.TP -\fIpathName \fBdelta \fIdeltaX deltaY\fR -Returns a real number indicating the fractional change in -the scrollbar setting that corresponds to a given change -in thumb position. For example, if the scrollbar is horizontal, -the result indicates how much the scrollbar setting must change -to move the thumb \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is -ignored in this case). -If the scrollbar is vertical, the result indicates how much the -scrollbar setting must change to move the thumb \fIdeltaY\fR pixels -down. The arguments and the result may be zero or negative. -.TP -\fIpathName \fBfraction \fIx y\fR -Returns a real number between 0 and 1 indicating where the point -given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar, -where 0.0 corresponds to the top or left of the trough -and 1.0 corresponds to the bottom or right. -\fIX\fR and \fIy\fR are pixel coordinates relative to the scrollbar -widget. -If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest -point in the trough is used. -.SH "SCROLLING COMMANDS" -.PP -When the user interacts with the scrollbar, for example by dragging -the thumb, the scrollbar notifies the associated widget that it -must change its view. -The scrollbar makes the notification by evaluating a Tcl command -generated from the scrollbar's \fB\-command\fR option. -The command may take any of the following forms. -In each case, \fIprefix\fR is the contents of the -\fB\-command\fR option, which usually has a form like \fB.t yview\fR -.TP -\fIprefix \fBmoveto \fIfraction\fR -\fIFraction\fR is a real number between 0 and 1. -The widget should adjust its view so that the point given -by \fIfraction\fR appears at the beginning of the widget. -If \fIfraction\fR is 0 it refers to the beginning of the -document. 1.0 refers to the end of the document, 0.333 -refers to a point one-third of the way through the document, -and so on. -.TP -\fIprefix \fBscroll \fInumber \fBunits\fR -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. -.TP -\fIprefix \fBscroll \fInumber \fBpages\fR -The widget should adjust its view by \fInumber\fR pages. -It is up to the widget to define the meaning of a page; typically -it is slightly less than what fits in the window, so that there -is a slight overlap between the old and new views. -\fINumber\fR is either 1, which means the next page should -become visible, or \-1, which means that the previous page should -become visible. -.SH "WIDGET STATES" -.PP -The scrollbar automatically sets the \fBdisabled\fR state bit. -when the entire range is visible (range is 0.0 to 1.0), -and clears it otherwise. -It also sets the \fBactive\fR and \fBpressed\fR state flags -of individual elements, based on the position and state of the mouse pointer. -.SH EXAMPLE -.PP -.CS -set f [frame .f] -ttk::scrollbar $f.hsb \-orient horizontal \-command [list $f.t xview] -ttk::scrollbar $f.vsb \-orient vertical \-command [list $f.t yview] -text $f.t \-xscrollcommand [list $f.hsb set] \-yscrollcommand [list $f.vsb set] -grid $f.t \-row 0 \-column 0 \-sticky nsew -grid $f.vsb \-row 0 \-column 1 \-sticky nsew -grid $f.hsb \-row 1 \-column 0 \-sticky nsew -grid columnconfigure $f 0 \-weight 1 -grid rowconfigure $f 0 \-weight 1 -.CE -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::scrollbar\fP is \fBTScrollbar\fP. -.PP -Dynamic states: \fBactive\fP, \fBdisabled\fP. -.PP -\fBTScrollbar\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-arrowcolor\fP \fIcolor\fP -.br -\fB\-background\fP \fIcolor\fP -.br -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-troughcolor\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), scrollbar(n) -.SH KEYWORDS -scrollbar, widget -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_separator.n b/tk8.6/doc/ttk_separator.n deleted file mode 100644 index 4befb0a..0000000 --- a/tk8.6/doc/ttk_separator.n +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::separator n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::separator \- Separator bar -.SH SYNOPSIS -\fBttk::separator\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::separator\fR widget displays a horizontal or vertical separator -bar. -.SO ttk_widget -\-class \-cursor -\-style \-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-orient orient Orient -One of \fBhorizontal\fR or \fBvertical\fR. -Specifies the orientation of the separator. -.SH "WIDGET COMMAND" -.PP -Separator widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. -.PP -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::separator\fP is \fBTSeparator\fP. -.PP -\fBTSeparator\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n) -.SH "KEYWORDS" -widget, separator -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_sizegrip.n b/tk8.6/doc/ttk_sizegrip.n deleted file mode 100644 index 707a17e..0000000 --- a/tk8.6/doc/ttk_sizegrip.n +++ /dev/null @@ -1,82 +0,0 @@ -'\" -'\" Copyright (c) 2006 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::sizegrip n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::sizegrip \- Bottom-right corner resize widget -.SH SYNOPSIS -\fBttk::sizegrip\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::sizegrip\fR widget (also known as a \fIgrow box\fR) -allows the user to resize the containing toplevel window -by pressing and dragging the grip. -.SO ttk_widget -\-class \-cursor -\-style \-takefocus -.SE -.SH "WIDGET COMMAND" -.PP -Sizegrip widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. -.SH "PLATFORM-SPECIFIC NOTES" -.PP -On Mac OSX, toplevel windows automatically include a built-in -size grip by default. -Adding a \fBttk::sizegrip\fR there is harmless, since -the built-in grip will just mask the widget. -.SH EXAMPLES -.PP -Using pack: -.CS -pack [ttk::frame $top.statusbar] \-side bottom \-fill x -pack [\fBttk::sizegrip\fR $top.statusbar.grip] \-side right \-anchor se -.CE -.PP -Using grid: -.CS -grid [\fBttk::sizegrip\fR $top.statusbar.grip] \e - \-row $lastRow \-column $lastColumn \-sticky se -# ... optional: add vertical scrollbar in $lastColumn, -# ... optional: add horizontal scrollbar in $lastRow -.CE -.SH "BUGS" -.PP -If the containing toplevel's position was specified -relative to the right or bottom of the screen -(e.g., -.QW "\fBwm geometry ... \fIw\fBx\fIh\fB\-\fIx\fB\-\fIy\fR" -instead of -.QW "\fBwm geometry ... \fIw\fBx\fIh\fB+\fIx\fB+\fIy\fR" ), -the sizegrip widget will not resize the window. -.PP -\fBttk::sizegrip\fR widgets only support -.QW southeast -resizing. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::sizegrip\fP is \fBTSizegrip\fP. -.PP -\fBTSizegrip\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n) -.SH "KEYWORDS" -widget, sizegrip, grow box -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_spinbox.n b/tk8.6/doc/ttk_spinbox.n deleted file mode 100644 index 325d4d8..0000000 --- a/tk8.6/doc/ttk_spinbox.n +++ /dev/null @@ -1,128 +0,0 @@ -'\" -'\" Copyright (c) 2008 Pat Thoyts -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::spinbox n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::spinbox \- Selecting text field widget -.SH SYNOPSIS -\fBttk::spinbox\fR \fIpathName \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -A \fBttk::spinbox\fR widget is a \fBttk::entry\fR widget with built-in -up and down buttons that are used to either modify a numeric value or -to select among a set of values. The widget implements all the features -of the \fBttk::entry\fR widget including support of the -\fB\-textvariable\fR option to link the value displayed by the widget -to a Tcl variable. -.SO ttk_widget -\-class \-cursor \-state \-style -\-takefocus \-xscrollcommand -.SE -.SO ttk_entry -\-validate \-validatecommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -Specifies a Tcl command to be invoked whenever a spinbutton is invoked. -.OP \-format format Format -Specifies an alternate format to use when setting the string value -when using the \fB\-from\fR and \fB\-to\fR range. -This must be a format specifier of the form \fB%<pad>.<pad>f\fR, -as it will format a floating-point number. -.OP \-from from From -A floating\-point value specifying the lowest value for the spinbox. This is -used in conjunction with \fB\-to\fR and \fB\-increment\fR to set a numerical -range. -.OP \-increment increment Increment -A floating\-point value specifying the change in value to be applied each -time one of the widget spin buttons is pressed. The up button applies a -positive increment, the down button applies a negative increment. -.OP \-to to To -A floating\-point value specifying the highest permissible value for the -widget. See also \fB\-from\fR and \fB\-increment\fR. -range. -.OP \-values values Values -This must be a Tcl list of values. If this option is set then this will -override any range set using the \fB\-from\fR, \fB\-to\fR and -\fB\-increment\fR options. The widget will instead use the values -specified beginning with the first value. -.OP \-wrap wrap Wrap -Must be a proper boolean value. If on, the spinbox will wrap around the -values of data in the widget. -.SH "INDICES" -.PP -See the \fBttk::entry\fR manual for information about indexing characters. -.SH "VALIDATION" -.PP -See the \fBttk::entry\fR manual for information about using the -\fB\-validate\fR and \fB\-validatecommand\fR options. -.SH "WIDGET COMMAND" -.PP -The following subcommands are possible for spinbox widgets in addition to -the commands described for the \fBttk::entry\fR widget: -.TP -\fIpathName \fBget\fR -Returns the spinbox's current value. -.TP -\fIpathName \fBset \fIvalue\fR -Set the spinbox string to \fIvalue\fR. If a \fB\-format\fR option has -been configured then this format will be applied. If formatting fails -or is not set or the \fB\-values\fR option has been used then the value -is set directly. -.SH "VIRTUAL EVENTS" -.PP -The spinbox widget generates a \fB<<Increment>>\fR virtual event when -the user presses <Up>, and a \fB<<Decrement>>\fR virtual event when the -user presses <Down>. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::spinbox\fP is \fBTSpinbox\fP. -.PP -Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBfocus\fP, \fBreadonly\fP. -.PP -\fBTSpinbox\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-arrowcolor\fP \fIcolor\fP -.br -\fB\-arrowsize\fP \fIamount\fP -.br -\fB\-background\fP \fIcolor\fP -.RS -When using the aqua theme (Mac OS X), changes the \fB\-fieldbackground\fP. -.RE -\fB\-bordercolor\fP \fIcolor\fP -.br -\fB\-darkcolor\fP \fIcolor\fP -.br -\fB\-fieldbackground\fP \fIcolor\fP -.RS -Does not work with the aqua theme (Mac OS X). -.RE -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-lightcolor\fP \fIcolor\fP -.br -\fB\-padding\fP \fIpadding\fP -.br -\fB\-selectbackground\fP \fIcolor\fP -.br -\fB\-selectforeground\fP \fIcolor\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), ttk::entry(n), spinbox(n) -.SH KEYWORDS -entry, spinbox, widget, text field -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_style.n b/tk8.6/doc/ttk_style.n deleted file mode 100644 index 985e3cd..0000000 --- a/tk8.6/doc/ttk_style.n +++ /dev/null @@ -1,131 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::style n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::style \- Manipulate style database -.SH SYNOPSIS -\fBttk::style\fR \fIoption\fR ?\fIargs\fR? -.BE -.SH NOTES -.PP -See also the Tcl'2004 conference presentation, -available at http://tktable.sourceforge.net/tile/tile-tcl2004.pdf -.SH DEFINITIONS -.PP -Each widget is assigned a \fIstyle\fR, -which specifies the set of elements making up the widget -and how they are arranged, along with dynamic and default -settings for element options. -By default, the style name is the same as the widget's class; -this may be overridden by the \fB\-style\fR option. -.PP -A \fItheme\fR is a collection of elements and styles -which controls the overall look and feel of an application. -.SH DESCRIPTION -.PP -The \fBttk::style\fR command takes the following arguments: -.TP -\fBttk::style configure \fIstyle\fR ?\fI\-option\fR ?\fIvalue option value...\fR? ? -Sets the default value of the specified option(s) in \fIstyle\fR. -.TP -\fBttk::style map \fIstyle\fR ?\fI\-option\fB { \fIstatespec value...\fB }\fR? -Sets dynamic values of the specified option(s) in \fIstyle\fR. -Each \fIstatespec / value\fR pair is examined in order; -the value corresponding to the first matching \fIstatespec\fR -is used. -.TP -\fBttk::style lookup \fIstyle\fR \fI\-option \fR?\fIstate \fR?\fIdefault\fR?? -Returns the value specified for \fI\-option\fR in style \fIstyle\fR -in state \fIstate\fR, using the standard lookup rules for element options. -\fIstate\fR is a list of state names; if omitted, -it defaults to all bits off (the -.QW normal -state). -If the \fIdefault\fR argument is present, it is used as a fallback -value in case no specification for \fI\-option\fR is found. -.\" Otherwise -- signal error? return empty string? Leave unspecified for now. -.TP -\fBttk::style layout \fIstyle\fR ?\fIlayoutSpec\fR? -Define the widget layout for style \fIstyle\fR. -See \fBLAYOUTS\fR below for the format of \fIlayoutSpec\fR. -If \fIlayoutSpec\fR is omitted, return the layout specification -for style \fIstyle\fR. -.TP -\fBttk::style element create\fR \fIelementName\fR \fItype\fR ?\fIargs...\fR? -Creates a new element in the current theme of type \fItype\fR. -The only cross-platform built-in element type is \fIimage\fR -(see \fBttk_image\fR(n)) but themes may define other element types -(see \fBTtk_RegisterElementFactory\fR). On suitable versions of Windows -an element factory is registered to create Windows theme elements -(see \fBttk_vsapi\fR(n)). -.TP -\fBttk::style element names\fR -Returns the list of elements defined in the current theme. -.TP -\fBttk::style element options \fIelement\fR -Returns the list of \fIelement\fR's options. -.TP -\fBttk::style theme create\fR \fIthemeName\fR ?\fB\-parent \fIbasedon\fR? ?\fB\-settings \fIscript...\fR ? -Creates a new theme. It is an error if \fIthemeName\fR already exists. -If \fB\-parent\fR is specified, the new theme will inherit -styles, elements, and layouts from the parent theme \fIbasedon\fR. -If \fB\-settings\fR is present, \fIscript\fR is evaluated in the -context of the new theme as per \fBttk::style theme settings\fR. -.TP -\fBttk::style theme settings \fIthemeName\fR \fIscript\fR -Temporarily sets the current theme to \fIthemeName\fR, -evaluate \fIscript\fR, then restore the previous theme. -Typically \fIscript\fR simply defines styles and elements, -though arbitrary Tcl code may appear. -.TP -\fBttk::style theme names\fR -Returns a list of all known themes. -.TP -\fBttk::style theme use\fR ?\fIthemeName\fR? -Without an argument the result is the name of the current theme. -Otherwise this command sets the current theme to \fIthemeName\fR, -and refreshes all widgets. -.SH LAYOUTS -.PP -A \fIlayout\fR specifies a list of elements, each followed -by one or more options specifying how to arrange the element. -The layout mechanism uses a simplified version of the \fBpack\fR -geometry manager: given an initial cavity, -each element is allocated a parcel. -Valid options are: -.TP -\fB\-side \fIside\fR -Specifies which side of the cavity to place the element; -one of \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. -If omitted, the element occupies the entire cavity. -.TP -\fB\-sticky\fR \fB[\fInswe\fB]\fR -Specifies where the element is placed inside its allocated parcel. -.TP -\fB\-children { \fIsublayout... \fB}\fR -Specifies a list of elements to place inside the element. -.\" Also: -border, -unit, -expand: may go away. -.PP -For example: -.CS -ttk::style layout Horizontal.TScrollbar { - Scrollbar.trough \-children { - Scrollbar.leftarrow \-side left - Scrollbar.rightarrow \-side right - Horizontal.Scrollbar.thumb \-side left \-sticky ew - } -} -.CE -.SH "SEE ALSO" -ttk::intro(n), ttk::widget(n), photo(n), ttk_image(n) -.SH KEYWORDS -style, theme, appearance -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_treeview.n b/tk8.6/doc/ttk_treeview.n deleted file mode 100644 index b81bc62..0000000 --- a/tk8.6/doc/ttk_treeview.n +++ /dev/null @@ -1,547 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::treeview n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::treeview \- hierarchical multicolumn data display widget -.SH SYNOPSIS -\fBttk::treeview \fIpathname \fR?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -The \fBttk::treeview\fR widget displays a hierarchical collection of items. -Each item has a textual label, an optional image, -and an optional list of data values. -The data values are displayed in successive columns after -the tree label. -.PP -The order in which data values are displayed may be controlled -by setting the \fB\-displaycolumns\fR widget option. -The tree widget can also display column headings. -Columns may be accessed by number or by symbolic names -listed in the \fB\-columns\fR widget option; -see \fBCOLUMN IDENTIFIERS\fR. -.PP -Each item is identified by a unique name. -The widget will generate item IDs if they are not supplied by the caller. -There is a distinguished root item, named \fB{}\fR. -The root item itself is not displayed; -its children appear at the top level of the hierarchy. -.PP -Each item also has a list of \fItags\fR, -which can be used to associate event bindings with individual items -and control the appearance of the item. -.\" .PP -.\" @@@HERE: describe selection, focus item -.PP -Treeview widgets support horizontal and vertical scrolling with the -standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options -and [\fBxy\fR]\fBview\fR widget commands. -.SO ttk_widget -\-class \-cursor \-takefocus -\-style \-xscrollcommand \-yscrollcommand -\-padding -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-columns columns Columns -A list of column identifiers, -specifying the number of columns and their names. -.\"X: This is a read-only option; it may only be set when the widget is created. -.OP \-displaycolumns displayColumns DisplayColumns -A list of column identifiers -(either symbolic names or integer indices) -specifying which data columns are displayed -and the order in which they appear, -or the string \fB#all\fP. -If set to \fB#all\fP (the default), -all columns are shown in the order given. -.OP \-height height Height -Specifies the number of rows which should be visible. -Note: -the requested width is determined from the sum of the column widths. -.OP \-selectmode selectMode SelectMode -Controls how the built-in class bindings manage the selection. -One of \fBextended\fR, \fBbrowse\fR, or \fBnone\fR. -.RS -.PP -If set to \fBextended\fR (the default), multiple items may be selected. -If \fBbrowse\fR, only a single item will be selected at a time. -If \fBnone\fR, the selection will not be changed. -.PP -Note that application code and tag bindings can set the selection -however they wish, regardless of the value of \fB\-selectmode\fR. -.RE -.OP \-show show Show -A list containing zero or more of the following values, specifying -which elements of the tree to display. -.RS -.IP \fBtree\fR -Display tree labels in column #0. -.IP \fBheadings\fR -Display the heading row. -.PP -The default is \fBtree headings\fR, i.e., show all elements. -.PP -\fBNOTE:\fR Column #0 always refers to the tree column, -even if \fB\-show tree\fR is not specified. -.RE -.SH "WIDGET COMMAND" -.PP -.TP -\fIpathname \fBbbox \fIitem\fR ?\fIcolumn\fR? -Returns the bounding box (relative to the treeview widget's window) -of the specified \fIitem\fR -in the form \fIx y width height\fR. -If \fIcolumn\fR is specified, returns the bounding box of that cell. -If the \fIitem\fR is not visible -(i.e., if it is a descendant of a closed item or is scrolled offscreen), -returns the empty list. -.TP -\fIpathname \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. -.TP -\fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? -If \fInewchildren\fR is not specified, -returns the list of children belonging to \fIitem\fR. -.RS -.PP -If \fInewchildren\fR is specified, replaces \fIitem\fR's child list -with \fInewchildren\fR. -Items in the old child list not present in the new child list -are detached from the tree. -None of the items in \fInewchildren\fR may be an ancestor -of \fIitem\fR. -.RE -.TP -\fIpathname \fBcolumn \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? -Query or modify the options for the specified \fIcolumn\fR. -If no \fI\-option\fR is specified, -returns a dictionary of option/value pairs. -If a single \fI\-option\fR is specified, -returns the value of that option. -Otherwise, the options are updated with the specified values. -The following options may be set on each column: -.RS -.TP -\fB\-id \fIname\fR -The column name. This is a read-only option. -For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] -returns the data column associated with display column #\fIn\fR. -.TP -\fB\-anchor\fR -Specifies how the text in this column should be aligned -with respect to the cell. One of -\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. -.TP -\fB\-minwidth\fR -The minimum width of the column in pixels. -The treeview widget will not make the column any smaller than -\fB\-minwidth\fR when the widget is resized or the user drags a -column separator. -.TP -\fB\-stretch\fR -Specifies whether or not the column's width should be adjusted -when the widget is resized. -.TP -\fB\-width \fIw\fR -The width of the column in pixels. Default is something reasonable, -probably 200 or so. -.PP -Use \fIpathname column #0\fR to configure the tree column. -.RE -.TP -\fIpathname \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. -.TP -\fIpathname \fBdelete \fIitemList\fR -Deletes each of the items in \fIitemList\fR and all of their descendants. -The root item may not be deleted. -See also: \fBdetach\fR. -.TP -\fIpathname \fBdetach \fIitemList\fR -Unlinks all of the specified items in \fIitemList\fR from the tree. -The items and all of their descendants are still present -and may be reinserted at another point in the tree -with the \fBmove\fR operation, -but will not be displayed until that is done. -The root item may not be detached. -See also: \fBdelete\fR. -.TP -\fIpathname \fBexists \fIitem\fR -Returns 1 if the specified \fIitem\fR is present in the tree, -0 otherwise. -.TP -\fIpathname \fBfocus \fR?\fIitem\fR? -If \fIitem\fR is specified, sets the focus item to \fIitem\fR. -Otherwise, returns the current focus item, or \fB{}\fR if there is none. -.\" Need: way to clear the focus item. {} works for this... -.TP -\fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? -Query or modify the heading options for the specified \fIcolumn\fR. -Valid options are: -.RS -.TP -\fB\-text \fItext\fR -The text to display in the column heading. -.TP -\fB\-image \fIimageName\fR -Specifies an image to display to the right of the column heading. -.TP -\fB\-anchor \fIanchor\fR -Specifies how the heading text should be aligned. -One of the standard Tk anchor values. -.TP -\fB\-command \fIscript\fR -A script to evaluate when the heading label is pressed. -.PP -Use \fIpathname heading #0\fR to configure the tree column heading. -.RE -.TP -\fIpathname \fBidentify \fIcomponent x y\fR -Returns a description of the specified \fIcomponent\fR -under the point given by \fIx\fR and \fIy\fR, -or the empty string if no such \fIcomponent\fR is present at that position. -The following subcommands are supported: -.RS -.TP -\fIpathname \fBidentify region \fIx y\fR -.RS -Returns one of: -.IP heading -Tree heading area; -use [\fBpathname identify column \fIx y\fR] -to determine the heading number. -.IP separator -Space between two column headings; -[\fBpathname identify column \fIx y\fR] -will return the display column identifier -of the heading to left of the separator. -.IP tree -The tree area. -.IP cell -A data cell. -.RE -\fIpathname \fBidentify item \fIx y\fR -Returns the item ID of the item at position \fIy\fR. -.TP -\fIpathname \fBidentify column \fIx y\fR -Returns the data column identifier of the cell at position \fIx\fR. -The tree column has ID \fB#0\fR. -.TP -\fIpathname \fBidentify element \fIx y\fR -The element at position \fIx,y\fR. -.TP -\fIpathname \fBidentify row \fIx y\fR -Obsolescent synonym for \fIpathname \fBidentify item\fR. -.PP -See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns -and data columns. -.RE -.TP -\fIpathname \fBindex \fIitem\fR -Returns the integer index of \fIitem\fR within its parent's list of children. -.TP -\fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR -Creates a new item. -\fIparent\fR is the item ID of the parent item, -or the empty string \fB{}\fR -to create a new top-level item. -\fIindex\fR is an integer, or the value \fBend\fR, specifying where in the -list of \fIparent\fR's children to insert the new item. -If \fIindex\fR is less than or equal to zero, -the new node is inserted at the beginning; -if \fIindex\fR is greater than or equal to the current number of children, -it is inserted at the end. -If \fB\-id\fR is specified, it is used as the item identifier; -\fIid\fR must not already exist in the tree. -Otherwise, a new unique identifier is generated. -.RS -.PP -\fIpathname \fBinsert\fR returns the item identifier of the -newly created item. -See \fBITEM OPTIONS\fR for the list of available options. -.RE -.TP -\fIpathname \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? -Query or modify the options for the specified \fIitem\fR. -If no \fI\-option\fR is specified, -returns a dictionary of option/value pairs. -If a single \fI\-option\fR is specified, -returns the value of that option. -Otherwise, the item's options are updated with the specified values. -See \fBITEM OPTIONS\fR for the list of available options. -.TP -\fIpathname \fBmove \fIitem parent index\fR -Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. -It is illegal to move an item under one of its descendants. -.RS -.PP -If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved -to the beginning; if greater than or equal to the number of children, -it is moved to the end. -.RE -.TP -\fIpathname \fBnext \fIitem\fR -Returns the identifier of \fIitem\fR's next sibling, -or \fB{}\fR if \fIitem\fR is the last child of its parent. -.TP -\fIpathname \fBparent \fIitem\fR -Returns the ID of the parent of \fIitem\fR, -or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. -.TP -\fIpathname \fBprev \fIitem\fR -Returns the identifier of \fIitem\fR's previous sibling, -or \fB{}\fR if \fIitem\fR is the first child of its parent. -.TP -\fIpathname \fBsee \fIitem\fR -Ensure that \fIitem\fR is visible: -sets all of \fIitem\fR's ancestors to \fB\-open true\fR, -and scrolls the widget if necessary so that \fIitem\fR is -within the visible portion of the tree. -.TP -\fIpathname \fBselection\fR ?\fIselop itemList\fR? -If \fIselop\fR is not specified, returns the list of selected items. -Otherwise, \fIselop\fR is one of the following: -.RS -.TP -\fIpathname \fBselection set \fIitemList\fR -\fIitemList\fR becomes the new selection. -.TP -\fIpathname \fBselection add \fIitemList\fR -Add \fIitemList\fR to the selection -.TP -\fIpathname \fBselection remove \fIitemList\fR -Remove \fIitemList\fR from the selection -.TP -\fIpathname \fBselection toggle \fIitemList\fR -Toggle the selection state of each item in \fIitemList\fR. -.RE -.TP -\fIpathname \fBset \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? -With one argument, returns a dictionary of column/value pairs -for the specified \fIitem\fR. -With two arguments, returns the current value of the specified \fIcolumn\fR. -With three arguments, sets the value of column \fIcolumn\fR -in item \fIitem\fR to the specified \fIvalue\fR. -See also \fBCOLUMN IDENTIFIERS\fR. -.TP -\fIpathname \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBtag \fIargs...\fR -.RS -.TP -\fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? -Add a Tk binding script for the event sequence \fIsequence\fR -to the tag \fItagName\fR. When an X event is delivered to an item, -binding scripts for each of the item's \fB\-tags\fR are evaluated -in order as per \fIbindtags(n)\fR. -.RS -.PP -\fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events -are sent to the focus item. -\fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events -are sent to the item under the mouse pointer. -No other event types are supported. -.PP -The binding \fIscript\fR undergoes \fB%\fR-substitutions before -evaluation; see \fBbind(n)\fR for details. -.RE -.TP -\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue option value...\fR? -Query or modify the options for the specified \fItagName\fR. -If one or more \fIoption/value\fR pairs are specified, -sets the value of those options for the specified tag. -If a single \fIoption\fR is specified, -returns the value of that option -(or the empty string if the option has not been specified for \fItagName\fR). -With no additional arguments, -returns a dictionary of the option settings for \fItagName\fR. -See \fBTAG OPTIONS\fR for the list of available options. -.TP -\fIpathName \fBtag has \fItagName\fR ?\fIitem\fR? -If \fIitem\fR is specified, returns 1 or 0 -depending on whether the specified item has the named tag. -Otherwise, returns a list of all items which have -the specified tag. -.TP -\fIpathName \fBtag names\fR -Returns a list of all tags used by the widget. -.TP -\fIpathName \fBtag add \fItag items\fR -Adds the specified \fItag\fR to each of the listed \fIitems\fR. -If \fItag\fR is already present for a particular item, -then the \fB\-tags\fR for that item are unchanged. -.TP -\fIpathName \fBtag remove \fItag\fR ?\fIitems\fR? -Removes the specified \fItag\fR from each of the listed \fIitems\fR. -If \fIitems\fR is omitted, removes \fItag\fR from each item in the tree. -If \fItag\fR is not present for a particular item, -then the \fB\-tags\fR for that item are unchanged. -.RE -.TP -\fIpathName \fBxview \fIargs\fR -Standard command for horizontal scrolling; see \fIwidget(n)\fR. -.TP -\fIpathName \fByview \fIargs\fR -Standard command for vertical scrolling; see \fIttk::widget(n)\fR. -.SH "ITEM OPTIONS" -.PP -The following item options may be specified for items -in the \fBinsert\fR and \fBitem\fR widget commands. -.OP \-text text Text -The textual label to display for the item. -.OP \-image image Image -A Tk image, displayed to the left of the label. -.OP \-values values Values -The list of values associated with the item. -.RS -.PP -Each item should have the same number of values as -the \fB\-columns\fR widget option. -If there are fewer values than columns, -the remaining values are assumed empty. -If there are more values than columns, -the extra values are ignored. -.RE -.OP \-open open Open -A boolean value indicating whether the item's children -should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). -.OP \-tags tags Tags -A list of tags associated with this item. -.SH "TAG OPTIONS" -.PP -The following options may be specified on tags: -.IP \fB\-foreground\fR -Specifies the text foreground color. -.IP \fB\-background\fR -Specifies the cell or item background color. -.IP \fB\-font\fR -Specifies the font to use when drawing text. -.\" ??? Maybe: .IP \-anchor -.\" ??? Maybe: .IP \-padding -.\" ??? Maybe: .IP \-text -.IP \fB\-image\fR -Specifies the item image, in case the item's \fB\-image\fR option is empty. -.\" .PP -.\" \fI(@@@ TODO: sort out order of precedence for options)\fR -.SH "COLUMN IDENTIFIERS" -.PP -Column identifiers take any of the following forms: -.IP \(bu -A symbolic name from the list of \fB\-columns\fR. -.IP \(bu -An integer \fIn\fR, specifying the \fIn\fRth data column. -.IP \(bu -A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, -specifying the \fIn\fRth display column. -.PP -\fBNOTE:\fR -Item \fB\-values\fR may be displayed in a different order than -the order in which they are stored. -.PP -\fBNOTE:\fR Column #0 always refers to the tree column, -even if \fB\-show tree\fR is not specified. -.PP -A \fIdata column number\fR is an index into an item's \fB\-values\fR list; -a \fIdisplay column number\fR is the column number in the tree -where the values are displayed. -Tree labels are displayed in column #0. -If \fB\-displaycolumns\fR is not set, -then data column \fIn\fR is displayed in display column \fB#\fIn+1\fR. -Again, \fBcolumn #0 always refers to the tree column\fR. -.SH "VIRTUAL EVENTS" -.PP -The treeview widget generates the following virtual events. -.IP <<TreeviewSelect>> -Generated whenever the selection changes. -.IP <<TreeviewOpen>> -Generated just before setting the focus item to \fB\-open true\fR. -.IP <<TreeviewClose>> -Generated just after setting the focus item to \fB\-open false\fR. -.PP -The \fBfocus\fR and \fBselection\fR widget commands can be used -to determine the affected item or items. -'\" Not yet: -'\" In Tk 8.5, the affected item is also passed as the \fB\-detail\fR field -'\" of the virtual event. -.SH "STYLING OPTIONS" -.PP -The class name for a \fBttk::treeview\fP is \fBTreeview\fP. -The treeview header class name is \fBHeading\fP. -The treeview item class name is \fBItem\fP. -The treeview cell class name is \fBCell\fP. -.PP -Dynamic states: \fBdisabled\fP, \fBselected\fP. -.PP -\fBTreeview\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-fieldbackground\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.br -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-rowheight\fP \fIamount\fP -.RS -The \fB\-rowheight\fP value is not corrected by the \fBtk scaling\fP -value or by the configured font size and must always be set. Also make -sure that the \fB\-rowheight\fP is large enough to contain any images. -.PP -To adjust the \fB\-rowheight\fP for the Treeview style, use the following code -after \fBtk scaling\fP has been applied. -Note that even if you do not support or change \fBtk scaling\fP -in your program, your users may have it set in their .wishrc. -.RE -.PP -.CS -ttk::style configure Treeview \\ - \-rowheight [expr {[font metrics \fIfont\fP \-linespace] + 2}] -.CE -.PP -\fBHeading\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-background\fP \fIcolor\fP -.br -\fB\-font\fP \fIfont\fP -.br -\fB\-relief\fP \fIrelief\fP -.PP -\fBItem\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-foreground\fP \fIcolor\fP -.br -\fB\-indicatormargins\fP \fIpadding\fP -.br -\fB\-indicatorsize\fP \fIamount\fP -.br -\fB\-padding\fP \fIpadding\fP -.PP -\fBCell\fP styling options configurable with \fBttk::style\fP -are: -.PP -\fB\-padding\fP \fIpadding\fP -.PP -Some options are only available for specific themes. -.PP -See the \fBttk::style\fP manual page for information on how to configure -ttk styles. -.SH "SEE ALSO" -ttk::widget(n), listbox(n), image(n), bind(n) -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_vsapi.n b/tk8.6/doc/ttk_vsapi.n deleted file mode 100644 index af63c39..0000000 --- a/tk8.6/doc/ttk_vsapi.n +++ /dev/null @@ -1,113 +0,0 @@ -'\" -'\" Copyright (c) 2008 Pat Thoyts -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk_vsapi n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk_vsapi \- Define a Microsoft Visual Styles element -.SH SYNOPSIS -\fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR \fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR? -.BE -.SH DESCRIPTION -.PP -The \fBvsapi\fR element factory creates a new element -in the current theme whose visual appearance is drawn using the -Microsoft Visual Styles API which is responsible for the themed styles -on Windows XP and Vista. This factory permits any of the Visual -Styles parts to be declared as Ttk elements that can then be -included in a style layout to modify the appearance of Ttk widgets. -.PP -\fIclassName\fR and \fIpartId\fR are required parameters and specify -the Visual Styles class and part as given in the Microsoft -documentation. The \fIstateMap\fR may be provided to map Ttk states to -Visual Styles API states (see \fBSTATE MAP\fR). -.SH "OPTIONS" -.PP -Valid \fIoptions\fR are: -.TP -\fB\-padding \fIpadding\fR -. -Specify the element's interior padding. -\fIpadding\fR is a list of up to four integers specifying -the left, top, right and bottom padding quantities respectively. -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; -a single number specifies the same padding all the way around the widget. -This option may not be mixed with any other options. -.TP -\fB\-margins \fIpadding\fR -. -Specifies the elements exterior padding. -\fIpadding\fR is a list of up to four integers specifying -the left, top, right and bottom padding quantities respectively. -This option may not be mixed with any other options. -.TP -\fB\-width \fIwidth\fR -. -Specifies the height for the element. If this option is set then -the Visual Styles API will not be queried for the recommended -size or the part. If this option is set then \fB\-height\fR should -also be set. The \fB\-width\fR and \fB\-height\fR options cannot -be mixed with the \fB\-padding\fR or \fB\-margins\fR options. -.TP -\fB\-height \fIheight\fR -. -Specifies the height of the element. See the comments for \fB\-width\fR. -.SH "STATE MAP" -.PP -The \fIstateMap\fR parameter is a list of ttk states and the -corresponding Visual Styles API state value. -This permits the element appearance to respond to changes in the -widget state such as becoming active or being pressed. The list should -be as described for the \fBttk::style map\fR command but note that the -last pair in the list should be the default state and is typically an -empty list and 1. Unfortunately all the Visual Styles parts have -different state values and these must be looked up either in the -Microsoft documentation or more likely in the header files. The -original header to use was \fItmschema.h\fR, but in more recent -versions of the Windows Development Kit this is \fIvssym32.h\fR. -.PP -If no \fIstateMap\fR parameter is given there is an implicit default -map of {{} 1} -.SH "EXAMPLE" -.PP -Create a correctly themed close button by changing the layout of -a \fBttk::button\fR(n). This uses the WINDOW part WP_SMALLCLOSEBUTTON -and as documented the states CBS_DISABLED, CBS_HOT, CBS_NORMAL and -CBS_PUSHED are mapped from ttk states. -.CS -ttk::style element create smallclose \fBvsapi\fR WINDOW 19 \\ - {disabled 4 pressed 3 active 2 {} 1} -ttk::style layout CloseButton {CloseButton.smallclose -sticky news} -pack [ttk::button .close -style CloseButton] -.CE -.PP -Change the appearance of a \fBttk::checkbutton\fR(n) to use the -Explorer pin part EBP_HEADERPIN. -.CS -ttk::style element create pin \fBvsapi\fR EXPLORERBAR 3 { - {pressed !selected} 3 - {active !selected} 2 - {pressed selected} 6 - {active selected} 5 - {selected} 4 - {} 1 -} -ttk::style layout Explorer.Pin {Explorer.Pin.pin -sticky news} -pack [ttk::checkbutton .pin -style Explorer.Pin] -.CE -.SH "SEE ALSO" -ttk::intro(n), ttk::widget(n), ttk::style(n), ttk_image(n) -.SH "KEYWORDS" -style, theme, appearance, windows -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/ttk_widget.n b/tk8.6/doc/ttk_widget.n deleted file mode 100644 index ad90e99..0000000 --- a/tk8.6/doc/ttk_widget.n +++ /dev/null @@ -1,291 +0,0 @@ -'\" -'\" Copyright (c) 2004 Joe English -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH ttk::widget n 8.5 Tk "Tk Themed Widget" -.so man.macros -.BS -.SH NAME -ttk::widget \- Standard options and commands supported by Tk themed widgets -.BE -.SH DESCRIPTION -This manual describes common widget options and commands. -.SH "STANDARD OPTIONS" -The following options are supported by all Tk themed widgets: -.OP \-class undefined undefined -Specifies the window class. -The class is used when querying the option database -for the window's other options, to determine the default -bindtags for the window, and to select the widget's default -layout and style. -This is a read-only option: -it may only be specified when the window is created, -and may not be changed with the \fBconfigure\fR widget command. -.OP \-cursor cursor Cursor -Specifies the mouse cursor to be used for the widget. -See \fBTk_GetCursor\fR and \fIcursors(n)\fR in the Tk reference manual -for the legal values. -If set to the empty string (the default), -the cursor is inherited from the parent widget. -.OP \-takefocus takeFocus TakeFocus -Determines whether the window accepts the focus during keyboard traversal. -Either \fB0\fR, \fB1\fR, a command prefix (to which the widget path -is appended, and which should return \fB0\fR or \fB1\fR), -or the empty string. -See \fIoptions(n)\fR in the Tk reference manual for the full description. -.OP \-style style Style -May be used to specify a custom widget style. -.SH "SCROLLABLE WIDGET OPTIONS" -The following options are supported by widgets that -are controllable by a scrollbar. -See \fIscrollbar(n)\fR for more information -.OP \-xscrollcommand xScrollCommand ScrollCommand -A command prefix, used to communicate with horizontal scrollbars. -.RS -When the view in the widget's window changes, the widget will -generate a Tcl command by concatenating the scroll command and -two numbers. -Each of the numbers is a fraction between 0 and 1 indicating -a position in the document; 0 indicates the beginning, -and 1 indicates the end. -The first fraction indicates the first information in the widget -that is visible in the window, and the second fraction indicates -the information just after the last portion that is visible. -.PP -Typically the \fB\-xscrollcommand\fR option consists of the path name -of a \fBscrollbar\fR widget followed by -.QW set , -e.g. -.QW ".x.scrollbar set" . -This will cause the scrollbar to be updated whenever the view in the -window changes. -.PP -If this option is set to the empty string (the default), -then no command will be executed. -.RE -.OP \-yscrollcommand yScrollCommand ScrollCommand -A command prefix, used to communicate with vertical scrollbars. -See the description of \fB\-xscrollcommand\fR above for details. -.SH "LABEL OPTIONS" -The following options are supported by labels, buttons, -and other button-like widgets: -.OP \-compound compound Compound -Specifies how to display the image relative to the text, -in the case both \fB\-text\fR and \fB\-image\fR are present. -Valid values are: -.RS -.IP text -Display text only. -.IP image -Display image only. -.IP center -Display text centered on top of image. -.IP top -.IP bottom -.IP left -.IP right -Display image above, below, left of, or right of the text, respectively. -.IP none -The default; display the image if present, otherwise the text. -.RE -.OP \-image image Image -Specifies an image to display. -This is a list of 1 or more elements. -The first element is the default image name. -The rest of the list is a sequence of \fIstatespec / value\fR pairs -as per \fBstyle map\fR, specifying different images to use when -the widget is in a particular state or combination of states. -All images in the list should have the same size. -.OP \-padding padding Padding -Specifies the internal padding for the widget. -The padding is a list of up to four length specifications -\fIleft top right bottom\fR. -If fewer than four elements are specified, -\fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and -\fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; -a single number specifies the same padding all the way around the widget. -.OP \-text text Text -Specifies a text string to be displayed inside the widget -(unless overridden by \fB\-textvariable\fR). -.OP \-textvariable textVariable Variable -Specifies the name of a global variable whose value will be used -in place of the \fB\-text\fR resource. -.OP \-underline underline Underline -If set, specifies the integer index (0-based) of a character to underline -in the text string. -The underlined character is used for mnemonic activation. -.OP \-width width Width -If greater than zero, specifies how much space, in character widths, -to allocate for the text label. -If less than zero, specifies a minimum width. -If zero or unspecified, the natural width of the text label is used. -.SH "COMPATIBILITY OPTIONS" -This option is only available for themed widgets that have -.QW corresponding -traditional Tk widgets. -.OP \-state state State -May be set to \fBnormal\fR or \fBdisabled\fR -to control the \fBdisabled\fR state bit. -This is a write-only option: -setting it changes the widget state, -but the \fBstate\fR widget command -does not affect the \fB\-state\fR option. -.SH COMMANDS -.TP -\fIpathName \fBcget \fIoption\fR -. -Returns the current value of the configuration option given -by \fIoption\fR. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Query or modify the configuration options of the widget. -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. -If \fIoption\fR is specified with no \fIvalue\fR, -then the command returns a list describing the named option: -the elements of the list are the -option name, database name, database class, default value, -and current value. -.\" Note: Ttk widgets don't use TK_OPTION_SYNONYM. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR. -.TP -\fIpathName \fBidentify element \fIx y\fR -. -Returns the name of the element under the point given -by \fIx\fR and \fIy\fR, or an empty string if the point does -not lie within any element. -\fIx\fR and \fIy\fR are pixel coordinates relative to the widget. -Some widgets accept other \fBidentify\fR subcommands. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -. -Test the widget's state. -If \fIscript\fR is not specified, returns 1 if -the widget state matches \fIstatespec\fR and 0 otherwise. -If \fIscript\fR is specified, equivalent to -.CS -if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR -.CE -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -. -Modify or inquire widget state. -If \fIstateSpec\fR is present, sets the widget state: -for each flag in \fIstateSpec\fR, sets the corresponding flag -or clears it if prefixed by an exclamation point. -.RS -Returns a new state spec indicating which flags were changed: -.CS -set changes [\fIpathName \fRstate \fIspec\fR] -\fIpathName \fRstate $changes -.CE -will restore \fIpathName\fR to the original state. -If \fIstateSpec\fR is not specified, -returns a list of the currently-enabled state flags. -.RE -.SH "WIDGET STATES" -The widget state is a bitmap of independent state flags. -Widget state flags include: -.TP -\fBactive\fR -. -The mouse cursor is over the widget -and pressing a mouse button will cause some action to occur. (aka -.QW prelight -(Gnome), -.QW hot -(Windows), -.QW hover ). -.TP -\fBdisabled\fR -. -Widget is disabled under program control (aka -.QW unavailable , -.QW inactive ). -.TP -\fBfocus\fR -. -Widget has keyboard focus. -.TP -\fBpressed\fR -. -Widget is being pressed (aka -.QW armed -in Motif). -.TP -\fBselected\fR -. -.QW On , -.QW true , -or -.QW current -for things like checkbuttons and radiobuttons. -.TP -\fBbackground\fR -. -Windows and the Mac have a notion of an -.QW active -or foreground window. -The \fBbackground\fR state is set for widgets in a background window, -and cleared for those in the foreground window. -.TP -\fBreadonly\fR -. -Widget should not allow user modification. -.TP -\fBalternate\fR -. -A widget-specific alternate display format. -For example, used for checkbuttons and radiobuttons in the -.QW tristate -or -.QW mixed -state, and for buttons with \fB\-default active\fR. -.TP -\fBinvalid\fR -. -The widget's value is invalid. -(Potential uses: scale widget value out of bounds, -entry widget value failed validation.) -.TP -\fBhover\fR -. -The mouse cursor is within the widget. -This is similar to the \fBactive\fP state; -it is used in some themes for widgets that -provide distinct visual feedback for -the active widget in addition to the active element -within the widget. -.PP -A \fIstate specification\fR or \fIstateSpec\fR is a list -of state names, optionally prefixed with an exclamation point (!) -indicating that the bit is off. -.SH EXAMPLES -.CS -set b [ttk::button .b] - -# Disable the widget: -$b \fBstate\fR disabled - -# Invoke the widget only if it is currently pressed and enabled: -$b \fBinstate\fR {pressed !disabled} { .b invoke } - -# Reenable widget: -$b \fBstate\fR !disabled -.CE -.SH "SEE ALSO" -ttk::intro(n), ttk::style(n) -.SH KEYWORDS -state, configure, option -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/winfo.n b/tk8.6/doc/winfo.n deleted file mode 100644 index 5008448..0000000 --- a/tk8.6/doc/winfo.n +++ /dev/null @@ -1,354 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH winfo n 4.3 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -winfo \- Return window-related information -.SH SYNOPSIS -\fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBwinfo\fR command is used to retrieve information about windows -managed by Tk. It can take any of a number of different forms, -depending on the \fIoption\fR argument. The legal forms are: -.TP -\fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR -Returns a decimal string giving the integer identifier for the -atom whose name is \fIname\fR. If no atom exists with the name -\fIname\fR then a new one is created. -If the \fB\-displayof\fR option is given then the atom is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -.TP -\fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR -Returns the textual name for the atom whose integer identifier is -\fIid\fR. -If the \fB\-displayof\fR option is given then the identifier is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -This command is the inverse of the \fBwinfo atom\fR command. -It generates an error if no such atom exists. -.TP -\fBwinfo cells \fIwindow\fR -Returns a decimal string giving the number of cells in the -color map for \fIwindow\fR. -.TP -\fBwinfo children \fIwindow\fR -Returns a list containing the path names of all the children -of \fIwindow\fR. Top-level windows are returned as children -of their logical parents. The list is in stacking order, with -the lowest window first, except for Top-level windows which -are not returned in stacking order. Use the \fBwm stackorder\fR -command to query the stacking order of Top-level windows. -.TP -\fBwinfo class \fIwindow\fR -Returns the class name for \fIwindow\fR. -.TP -\fBwinfo colormapfull \fIwindow\fR -Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 -otherwise. The colormap for a window is -.QW known -to be full if the last -attempt to allocate a new color on that window failed and this -application has not freed any colors in the colormap since the -failed allocation. -.TP -\fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR -Returns the path name for the window containing the point given -by \fIrootX\fR and \fIrootY\fR. -\fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. -any form acceptable to \fBTk_GetPixels\fR) in the coordinate -system of the root window (if a virtual-root window manager is in -use then the coordinate system of the virtual root window is used). -If the \fB\-displayof\fR option is given then the coordinates refer -to the screen containing \fIwindow\fR; otherwise they refer to the -screen of the application's main window. -If no window in this application contains the point then an empty -string is returned. -In selecting the containing window, children are given higher priority -than parents and among siblings the highest one in the stacking order is -chosen. -.TP -\fBwinfo depth \fIwindow\fR -Returns a decimal string giving the depth of \fIwindow\fR (number -of bits per pixel). -.TP -\fBwinfo exists \fIwindow\fR -Returns 1 if there exists a window named \fIwindow\fR, 0 if no such -window exists. -.TP -\fBwinfo fpixels \fIwindow\fR \fInumber\fR -Returns a floating-point value giving the number of pixels -in \fIwindow\fR corresponding to the distance given by \fInumber\fR. -\fINumber\fR may be specified in any of the forms acceptable -to \fBTk_GetScreenMM\fR, such as -.QW 2.0c -or -.QW 1i . -The return value may be fractional; for an integer value, use -\fBwinfo pixels\fR. -.TP -\fBwinfo geometry \fIwindow\fR -Returns the geometry for \fIwindow\fR, in the form -\fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are -in pixels. -.TP -\fBwinfo height \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's height in pixels. -When a window is first created its height will be 1 pixel; the -height will eventually be changed by a geometry manager to fulfil -the window's needs. -If you need the true height immediately after creating a widget, -invoke \fBupdate\fR to force the geometry manager to arrange it, -or use \fBwinfo reqheight\fR to get the window's requested height -instead of its actual height. -.TP -\fBwinfo id \fIwindow\fR -Returns a hexadecimal string giving a low-level platform-specific -identifier for \fIwindow\fR. On Unix platforms, this is the X -window identifier. Under Windows, this is the Windows -HWND. On the Macintosh the value has no meaning outside Tk. -.TP -\fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? -Returns a list whose members are the names of all Tcl interpreters -(e.g. all Tk-based applications) currently registered for a particular display. -If the \fB\-displayof\fR option is given then the return value refers -to the display of \fIwindow\fR; otherwise it refers to -the display of the application's main window. -.TP -\fBwinfo ismapped \fIwindow\fR -Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. -.TP -\fBwinfo manager \fIwindow\fR -Returns the name of the geometry manager currently -responsible for \fIwindow\fR, or an empty string if \fIwindow\fR -is not managed by any geometry manager. -The name is usually the name of the Tcl command for the geometry -manager, such as \fBpack\fR or \fBplace\fR. -If the geometry manager is a widget, such as canvases or text, the -name is the widget's class command, such as \fBcanvas\fR. -.TP -\fBwinfo name \fIwindow\fR -Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed -to its full path name). -The command \fBwinfo name .\fR will return the name of the application. -.TP -\fBwinfo parent \fIwindow\fR -Returns the path name of \fIwindow\fR's parent, or an empty string -if \fIwindow\fR is the main window of the application. -.TP -\fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR -Returns the path name of the window whose X identifier is \fIid\fR. -\fIId\fR must be a decimal, hexadecimal, or octal integer and must -correspond to a window in the invoking application. -If the \fB\-displayof\fR option is given then the identifier is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -.TP -\fBwinfo pixels \fIwindow\fR \fInumber\fR -Returns the number of pixels in \fIwindow\fR corresponding -to the distance given by \fInumber\fR. -\fINumber\fR may be specified in any of the forms acceptable -to \fBTk_GetPixels\fR, such as -.QW 2.0c -or -.QW 1i . -The result is rounded to the nearest integer value; for a -fractional result, use \fBwinfo fpixels\fR. -.TP -\fBwinfo pointerx \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns the -pointer's x coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position is -measured in the virtual root. -If the mouse pointer is not on the same screen as \fIwindow\fR then --1 is returned. -.TP -\fBwinfo pointerxy \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns a list -with two elements, which are the pointer's x and y coordinates measured -in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer is not on the same screen as \fIwindow\fR then -both of the returned coordinates are \-1. -.TP -\fBwinfo pointery \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns the -pointer's y coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer is not on the same screen as \fIwindow\fR then --1 is returned. -.TP -\fBwinfo reqheight \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's requested height, -in pixels. This is the value used by \fIwindow\fR's geometry -manager to compute its geometry. -.TP -\fBwinfo reqwidth \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's requested width, -in pixels. This is the value used by \fIwindow\fR's geometry -manager to compute its geometry. -.TP -\fBwinfo rgb \fIwindow color\fR -Returns a list containing three decimal values in the range 0 to -65535, which are the -red, green, and blue intensities that correspond to \fIcolor\fR in -the window given by \fIwindow\fR. \fIColor\fR -may be specified in any of the forms acceptable for a color -option. -.TP -\fBwinfo rootx \fIwindow\fR -Returns a decimal string giving the x-coordinate, in the root -window of the screen, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo rooty \fIwindow\fR -Returns a decimal string giving the y-coordinate, in the root -window of the screen, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo screen \fIwindow\fR -Returns the name of the screen associated with \fIwindow\fR, in -the form \fIdisplayName\fR.\fIscreenIndex\fR. -.TP -\fBwinfo screencells \fIwindow\fR -Returns a decimal string giving the number of cells in the default -color map for \fIwindow\fR's screen. -.TP -\fBwinfo screendepth \fIwindow\fR -Returns a decimal string giving the depth of the root window -of \fIwindow\fR's screen (number of bits per pixel). -.TP -\fBwinfo screenheight \fIwindow\fR -Returns a decimal string giving the height of \fIwindow\fR's screen, -in pixels. -.TP -\fBwinfo screenmmheight \fIwindow\fR -Returns a decimal string giving the height of \fIwindow\fR's screen, -in millimeters. -.TP -\fBwinfo screenmmwidth \fIwindow\fR -Returns a decimal string giving the width of \fIwindow\fR's screen, -in millimeters. -.TP -\fBwinfo screenvisual \fIwindow\fR -Returns one of the following strings to indicate the default visual -class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, -\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or -\fBtruecolor\fR. -.TP -\fBwinfo screenwidth \fIwindow\fR -Returns a decimal string giving the width of \fIwindow\fR's screen, -in pixels. -.TP -\fBwinfo server \fIwindow\fR -Returns a string containing information about the server for -\fIwindow\fR's display. The exact format of this string may vary -from platform to platform. For X servers the string -has the form -.QW "\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR" -where \fImajor\fR and \fIminor\fR are the version and revision -numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR -is the name of the vendor for the server, and \fIvendorRelease\fR -is an integer release number provided by the server. -.TP -\fBwinfo toplevel \fIwindow\fR -Returns the path name of the top-of-hierarchy window containing \fIwindow\fR. -In standard Tk this will always be a \fBtoplevel\fR widget, but extensions may -create other kinds of top-of-hierarchy widgets. -.TP -\fBwinfo viewable \fIwindow\fR -Returns 1 if \fIwindow\fR and all of its ancestors up through the -nearest toplevel window are mapped. Returns 0 if any of these -windows are not mapped. -.TP -\fBwinfo visual \fIwindow\fR -Returns one of the following strings to indicate the visual -class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, -\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or -\fBtruecolor\fR. -.TP -\fBwinfo visualid \fIwindow\fR -Returns the X identifier for the visual for \fIwindow\fR. -.TP -\fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? -Returns a list whose elements describe the visuals available for -\fIwindow\fR's screen. -Each element consists of a visual class followed by an integer depth. -The class has the same form as returned by \fBwinfo visual\fR. -The depth gives the number of bits per pixel in the visual. -In addition, if the \fBincludeids\fR argument is provided, then the -depth is followed by the X identifier for the visual. -.TP -\fBwinfo vrootheight \fIwindow\fR -Returns the height of the virtual root window associated with \fIwindow\fR -if there is one; otherwise returns the height of \fIwindow\fR's screen. -.TP -\fBwinfo vrootwidth \fIwindow\fR -Returns the width of the virtual root window associated with \fIwindow\fR -if there is one; otherwise returns the width of \fIwindow\fR's screen. -.TP -\fBwinfo vrootx \fIwindow\fR -Returns the x-offset of the virtual root window associated with \fIwindow\fR, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for \fIwindow\fR. -.TP -\fBwinfo vrooty \fIwindow\fR -Returns the y-offset of the virtual root window associated with \fIwindow\fR, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for \fIwindow\fR. -.TP -\fBwinfo width \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's width in pixels. -When a window is first created its width will be 1 pixel; the -width will eventually be changed by a geometry manager to fulfil -the window's needs. -If you need the true width immediately after creating a widget, -invoke \fBupdate\fR to force the geometry manager to arrange it, -or use \fBwinfo reqwidth\fR to get the window's requested width -instead of its actual width. -.TP -\fBwinfo x \fIwindow\fR -Returns a decimal string giving the x-coordinate, in \fIwindow\fR's -parent, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo y \fIwindow\fR -Returns a decimal string giving the y-coordinate, in \fIwindow\fR's -parent, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.SH EXAMPLE -.PP -Print where the mouse pointer is and what window it is currently over: -.CS -lassign [\fBwinfo pointerxy\fR .] x y -puts \-nonewline "Mouse pointer at ($x,$y) which is " -set win [\fBwinfo containing\fR $x $y] -if {$win eq ""} { - puts "over no window" -} else { - puts "over $win" -} -.CE -.SH KEYWORDS -atom, children, class, geometry, height, identifier, information, interpreters, -mapped, parent, path name, screen, virtual root, width, window -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/tk8.6/doc/wish.1 b/tk8.6/doc/wish.1 deleted file mode 100644 index 93ade0d..0000000 --- a/tk8.6/doc/wish.1 +++ /dev/null @@ -1,218 +0,0 @@ -'\" -'\" Copyright (c) 1991-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH wish 1 8.0 Tk "Tk Applications" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -wish \- Simple windowing shell -.SH SYNOPSIS -\fBwish\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? -.SH OPTIONS -.IP "\fB\-encoding \fIname\fR" 20 -Specifies the encoding of the text stored in \fIfileName\fR. -This option is only recognized prior to the \fIfileName\fR argument. -.IP "\fB\-colormap \fInew\fR" 20 -Specifies that the window should have a new private colormap instead of -using the default colormap for the screen. -.IP "\fB\-display \fIdisplay\fR" 20 -Display (and screen) on which to display window. -.IP "\fB\-geometry \fIgeometry\fR" 20 -Initial geometry to use for window. If this option is specified, its -value is stored in the \fBgeometry\fR global variable of the application's -Tcl interpreter. -.IP "\fB\-name \fIname\fR" 20 -Use \fIname\fR as the title to be displayed in the window, and -as the name of the interpreter for \fBsend\fR commands. -.IP "\fB\-sync\fR" 20 -Execute all X server commands synchronously, so that errors -are reported immediately. This will result in much slower -execution, but it is useful for debugging. -.IP "\fB\-use\fR \fIid\fR" 20 -Specifies that the main window for the application is to be embedded in -the window whose identifier is \fIid\fR, instead of being created as an -independent toplevel window. \fIId\fR must be specified in the same -way as the value for the \fB\-use\fR option for toplevel widgets (i.e. -it has a form like that returned by the \fBwinfo id\fR command). -.RS -Note that on some platforms this will only work correctly if \fIid\fR -refers to a Tk \fBframe\fR or \fBtoplevel\fR that has its -\fB\-container\fR option enabled. -.RE -.IP "\fB\-visual \fIvisual\fR" 20 -Specifies the visual to use for the window. -\fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR -procedure. -.IP "\fB\-\|\-\fR" 20 -Pass all remaining arguments through to the script's \fBargv\fR -variable without interpreting them. -This provides a mechanism for passing arguments such as \fB\-name\fR -to a script instead of having \fBwish\fR interpret them. -.BE -.SH DESCRIPTION -.PP -\fBWish\fR is a simple program consisting of the Tcl command -language, the Tk toolkit, and a main program that reads commands -from standard input or from a file. -It creates a main window and then processes Tcl commands. -If \fBwish\fR is invoked with arguments, then the first few -arguments, ?\fB\-encoding \fIname\fR? ?\fIfileName\fR?, specify the -name of a script file, and, optionally, the -encoding of the text data stored in that script file. A value -for \fIfileName\fR is recognized if the appropriate argument -does not start with -.QW \- . -.PP -If there are no arguments, or the arguments do not specify a \fIfileName\fR, -then wish reads Tcl commands interactively from standard input. -It will continue processing commands until all windows have been -deleted or until end-of-file is reached on standard input. -If there exists a file -.QW \fB.wishrc\fR -in the home directory of the user, \fBwish\fR evaluates the file as a -Tcl script just before reading the first command from standard input. -.PP -If arguments to \fBwish\fR do specify a \fIfileName\fR, then -\fIfileName\fR is treated as the name of a script file. -\fBWish\fR will evaluate the script in \fIfileName\fR (which -presumably creates a user interface), then it will respond to events -until all windows have been deleted. -Commands will not be read from standard input. -There is no automatic evaluation of -.QW \fB.wishrc\fR -when the name of a script file is presented on the \fBwish\fR command line, -but the script file can always \fBsource\fR it if desired. -.PP -Note that on Windows, the \fBwish\fIversion\fB.exe\fR program varies -from the \fBtclsh\fIversion\fB.exe\fR program in an additional -important way: it does not connect to a standard Windows console and -is instead a windowed program. Because of this, it additionally -provides access to its own \fBconsole\fR command. -.SH "OPTION PROCESSING" -.PP -\fBWish\fR automatically processes all of the command-line options -described in the \fBOPTIONS\fR summary above. -Any other command-line arguments besides these are passed through -to the application using the \fBargc\fR and \fBargv\fR variables -described later. -.SH "APPLICATION NAME AND CLASS" -.PP -The name of the application, which is used for purposes such as -\fBsend\fR commands, is taken from the \fB\-name\fR option, -if it is specified; otherwise it is taken from \fIfileName\fR, -if it is specified, or from the command name by which -\fBwish\fR was invoked. In the last two cases, if the name contains a -.QW / -character, then only the characters after the last slash are used -as the application name. -.PP -The class of the application, which is used for purposes such as -specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults -file, is the same as its name except that the first letter is -capitalized. -.SH "VARIABLES" -.PP -\fBWish\fR sets the following Tcl variables: -.TP 15 -\fBargc\fR -Contains a count of the number of \fIarg\fR arguments (0 if none), -not including the options described above. -.TP 15 -\fBargv\fR -Contains a Tcl list whose elements are the \fIarg\fR arguments -that follow a \fB\-\|\-\fR option or do not match any of the -options described in \fBOPTIONS\fR above, in order, or an empty string -if there are no such arguments. -.TP 15 -\fBargv0\fR -Contains \fIfileName\fR if it was specified. -Otherwise, contains the name by which \fBwish\fR was invoked. -.TP 15 -\fBgeometry\fR -If the \fB\-geometry\fR option is specified, \fBwish\fR copies its -value into this variable. If the variable still exists after -\fIfileName\fR has been evaluated, \fBwish\fR uses the value of -the variable in a \fBwm geometry\fR command to set the main -window's geometry. -.TP 15 -\fBtcl_interactive\fR -Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR -was not specified and standard input is a terminal-like -device), 0 otherwise. -.SH "SCRIPT FILES" -.PP -If you create a Tcl script in a file whose first line is -.CS -\fB#!/usr/local/bin/wish\fR -.CE -then you can invoke the script file directly from your shell if -you mark it as executable. -This assumes that \fBwish\fR has been installed in the default -location in /usr/local/bin; if it is installed somewhere else -then you will have to modify the above line to match. -Many UNIX systems do not allow the \fB#!\fR line to exceed about -30 characters in length, so be sure that the \fBwish\fR executable -can be accessed with a short file name. -.PP -An even better approach is to start your script files with the -following three lines: -.CS -\fB#!/bin/sh -# the next line restarts using wish \e -exec wish "$0" ${1+"$@"}\fR -.CE -This approach has three advantages over the approach in the previous -paragraph. First, the location of the \fBwish\fR binary does not have -to be hard-wired into the script: it can be anywhere in your shell -search path. Second, it gets around the 30-character file name limit -in the previous approach. -Third, this approach will work even if \fBwish\fR is -itself a shell script (this is done on some systems in order to -handle multiple architectures or operating systems: the \fBwish\fR -script selects one of several binaries to run). The three lines -cause both \fBsh\fR and \fBwish\fR to process the script, but the -\fBexec\fR is only executed by \fBsh\fR. -\fBsh\fR processes the script first; it treats the second -line as a comment and executes the third line. -The \fBexec\fR statement cause the shell to stop processing and -instead to start up \fBwish\fR to reprocess the entire script. -When \fBwish\fR starts up, it treats all three lines as comments, -since the backslash at the end of the second line causes the third -line to be treated as part of the comment on the second line. -.PP -The end of a script file may be marked either by the physical end of -the medium, or by the character, -.QW \e032 -.PQ \eu001a ", control-Z" . -If this character is present in the file, the \fBwish\fR application -will read text up to but not including the character. An application -that requires this character in the file may encode it as -.QW \e032 , -.QW \ex1a , -or -.QW \eu001a ; -or may generate it by use of commands such as \fBformat\fR or \fBbinary\fR. -.SH PROMPTS -.PP -When \fBwish\fR is invoked interactively it normally prompts for each -command with -.QW "\fB% \fR" . -You can change the prompt by setting the -variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable -\fBtcl_prompt1\fR exists then it must consist of a Tcl script -to output a prompt; instead of outputting a prompt \fBwish\fR -will evaluate the script in \fBtcl_prompt1\fR. -The variable \fBtcl_prompt2\fR is used in a similar way when -a newline is typed but the current command is not yet complete; -if \fBtcl_prompt2\fR is not set then no prompt is output for -incomplete commands. -.SH "SEE ALSO" -tclsh(1), toplevel(n), Tk_Main(3), Tk_MainLoop(3), Tk_MainWindow(3) -.SH KEYWORDS -application, argument, interpreter, prompt, script file, shell, -toolkit, toplevel diff --git a/tk8.6/doc/wm.n b/tk8.6/doc/wm.n deleted file mode 100644 index e7aedf7..0000000 --- a/tk8.6/doc/wm.n +++ /dev/null @@ -1,859 +0,0 @@ -'\" -'\" Copyright (c) 1991-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH wm n 8.5 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -wm \- Communicate with window manager -.SH SYNOPSIS -\fBwm\fR \fIoption window \fR?\fIargs\fR? -.BE -.SH DESCRIPTION -.PP -The \fBwm\fR command is used to interact with window managers in -order to control such things as the title for a window, its geometry, -or the increments in terms of which it may be resized. The \fBwm\fR -command can take any of a number of different forms, depending on -the \fIoption\fR argument. All of the forms expect at least one -additional argument, \fIwindow\fR, which must be the path name of a -top-level window. -.PP -The legal forms for the \fBwm\fR command are: -.TP -\fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? -. -If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR -are all specified, then they will be passed to the window manager -and the window manager should use them to enforce a range of -acceptable aspect ratios for \fIwindow\fR. The aspect ratio of -\fIwindow\fR (width/length) will be constrained to lie -between \fIminNumer\fR/\fIminDenom\fR and \fImaxNumer\fR/\fImaxDenom\fR. -If \fIminNumer\fR etc. are all specified as empty strings, then -any existing aspect ratio restrictions are removed. -If \fIminNumer\fR etc. are specified, then the command returns an -empty string. Otherwise, it returns -a Tcl list containing four elements, which are the current values -of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR -(if no aspect restrictions are in effect, then an empty string is -returned). -.TP -\fBwm attributes \fIwindow\fR -.TP -\fBwm attributes \fIwindow\fR ?\fBoption\fR? -.TP -\fBwm attributes \fIwindow\fR ?\fBoption value option value...\fR? -. -This subcommand returns or sets platform specific attributes associated -with a window. The first form returns a list of the platform specific -flags and their values. The second form returns the value for the -specific option. The third form sets one or more of the values. The -values are as follows: -.RS -.PP -All platforms support the following attributes (though X11 users -should see the notes below): -.TP -\fB\-alpha\fR -. -Specifies the alpha transparency level of the toplevel. It accepts a value -from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values outside that -range will be constrained. Where not supported, the \fB\-alpha\fR value -remains at \fB1.0\fR. -.TP -\fB\-fullscreen\fR -. -Places the window in a mode that takes up the entire screen, has no -borders, and covers the general use area (i.e. Start menu and taskbar on -Windows, dock and menubar on OSX, general window decorations on X11). -.TP -\fB\-topmost\fR -. -Specifies whether this is a topmost window (displays above all other windows). -.PP -On Windows, the following attributes may be set. -.TP -\fB\-disabled\fR -. -Specifies whether the window is in a disabled state. -.TP -\fB\-toolwindow\fR -. -Specifies a toolwindow style window (as defined in the MSDN). -.TP -\fB\-transparentcolor\fR -. -Specifies the transparent color index of the toplevel. It takes any color -value accepted by \fBTk_GetColor\fR. If the empty string is specified -(default), no transparent color is used. This is supported on Windows -2000/XP+. Where not supported, the \fB\-transparentcolor\fR value remains -at \fB{}\fR. -.PP -On Mac OS X, the following attributes may be set. -.TP -\fB\-modified\fR -. -Specifies the modification state of the window (determines whether the -window close widget contains the modification indicator and whether the -proxy icon is draggable). -.TP -\fB\-notify\fR -. -Specifies process notification state (bouncing of the application dock icon). -.TP -\fB\-titlepath\fR -. -Specifies the path of the file referenced as the window proxy icon (which -can be dragged and dropped in lieu of the file's finder icon). -.TP -\fB\-transparent\fR -. -Makes the window content area transparent and turns off the window shadow. For -the transparency to be effective, the toplevel background needs to be set to a -color with some alpha, e.g. -.QW systemTransparent . -.PP -On X11, the following attributes may be set. These are not supported by all -window managers, and will have no effect under older WMs. -.\" See http://www.freedesktop.org/Standards/wm-spec -.TP -\fB\-type\fR -.VS 8.6 -Requests that the window should be interpreted by the window manager as being -of the specified type(s). This may cause the window to be decorated in a -different way or otherwise managed differently, though exactly what happens is -entirely up to the window manager. A list of types may be used, in order of -preference. The following values are mapped to constants defined in the EWMH -specification (using others is possible, but not advised): -.RS -.TP -\fBdesktop\fR -. -indicates a desktop feature, -.TP -\fBdock\fR -. -indicates a dock/panel feature, -.TP -\fBtoolbar\fR -. -indicates a toolbar window that should be acting on behalf of another window, -as indicated with \fBwm transient\fR, -.TP -\fBmenu\fR -. -indicates a torn-off menu that should be acting on behalf of another window, -as indicated with \fBwm transient\fR, -.TP -\fButility\fR -. -indicates a utility window (e.g., palette or toolbox) that should be acting on -behalf of another window, as indicated with \fBwm transient\fR, -.TP -\fBsplash\fR -. -indicates a splash screen, displayed during application start up, -.TP -\fBdialog\fR -. -indicates a general dialog window, that should be acting on behalf of another -window, as indicated with \fBwm transient\fR, -.TP -\fBdropdown_menu\fR -. -indicates a menu summoned from a menu bar, which should usually also be set to -be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBpopup_menu\fR -. -indicates a popup menu, which should usually also be set to be -override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBtooltip\fR -. -indicates a tooltip window, which should usually also be set to be -override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBnotification\fR -. -indicates a window that provides a background notification of some event, -which should usually also be set to be override-redirected (with \fBwm -overrideredirect\fR), -.TP -\fBcombo\fR -. -indicates the drop-down list of a combobox widget, which should usually also -be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBdnd\fR -. -indicates a window that represents something being dragged, which should -usually also be set to be override-redirected (with -\fBwm overrideredirect\fR), -.TP -\fBnormal\fR -. -indicates a window that has no special interpretation. -.RE -.VE 8.6 -.TP -\fB\-zoomed\fR -. -Requests that the window should be maximized. This is the same as \fBwm state -zoomed\fR on Windows and Mac OS X. -.PP -On X11, changes to window attributes are performed asynchronously. Querying -the value of an attribute returns the current state, which will not be the -same as the value most recently set if the window manager has not yet -processed the request or if it does not support the attribute. -.RE -.TP -\fBwm client \fIwindow\fR ?\fIname\fR? -. -If \fIname\fR is specified, this command stores \fIname\fR (which -should be the name of -the host on which the application is executing) in \fIwindow\fR's -\fBWM_CLIENT_MACHINE\fR property for use by the window manager or -session manager. -The command returns an empty string in this case. -If \fIname\fR is not specified, the command returns the last name -set in a \fBwm client\fR command for \fIwindow\fR. -If \fIname\fR is specified as an empty string, the command deletes the -\fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. -.TP -\fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? -. -This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR -property, which provides information to the window managers about -windows that have private colormaps. -.RS -.PP -If \fIwindowList\fR is not specified, the command returns a list -whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR -property. -If \fIwindowList\fR is specified, it consists of a list of window -path names; the command overwrites the \fBWM_COLORMAP_WINDOWS\fR -property with the given windows and returns an empty string. -The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a -list of the internal windows within \fIwindow\fR whose colormaps differ -from their parents. -.PP -The order of the windows in the property indicates a priority order: -the window manager will attempt to install as many colormaps as possible -from the head of this list when \fIwindow\fR gets the colormap focus. -If \fIwindow\fR is not included among the windows in \fIwindowList\fR, -Tk implicitly adds it at the end of the \fBWM_COLORMAP_WINDOWS\fR -property, so that its colormap is lowest in priority. -If \fBwm colormapwindows\fR is not invoked, Tk will automatically set -the property for each top-level window to all the internal windows -whose colormaps differ from their parents, followed by the top-level -itself; the order of the internal windows is undefined. -See the ICCCM documentation for more information on the -\fBWM_COLORMAP_WINDOWS\fR property. -.RE -.TP -\fBwm command \fIwindow\fR ?\fIvalue\fR? -. -If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's -\fBWM_COMMAND\fR property for use by the window manager or -session manager and returns an empty string. -\fIValue\fR must have proper list structure; the elements should -contain the words of the command used to invoke the application. -If \fIvalue\fR is not specified then the command returns the last value -set in a \fBwm command\fR command for \fIwindow\fR. -If \fIvalue\fR is specified as an empty string, the command -deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. -.TP -\fBwm deiconify \fIwindow\fR -. -Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. -This is done by mapping the window. If the window has never been -mapped then this command will not map the window, but it will ensure -that when the window is first mapped it will be displayed -in de-iconified form. On Windows, a deiconified window will also be -raised and be given the focus (made the active window). -Returns an empty string. -.TP -\fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? -. -If \fBactive\fR or \fBpassive\fR is supplied as an optional argument -to the command, then it specifies the focus model for \fIwindow\fR. -In this case the command returns an empty string. If no additional -argument is supplied, then the command returns the current focus -model for \fIwindow\fR. -.RS -.PP -An \fBactive\fR focus model means that \fIwindow\fR will claim the -input focus for itself or its descendants, even at times when -the focus is currently in some other application. \fBPassive\fR means that -\fIwindow\fR will never claim the focus for itself: the window manager -should give the focus to \fIwindow\fR at appropriate times. However, -once the focus has been given to \fIwindow\fR or one of its descendants, -the application may re-assign the focus among \fIwindow\fR's descendants. -The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command -assumes a passive model of focusing. -.RE -.TP -\fBwm forget \fIwindow\fR -. -The \fIwindow\fR will be unmapped from the screen and will no longer -be managed by \fBwm\fR. Windows created with the \fBtoplevel\fR -command will be treated like \fBframe\fR windows once they are no -longer managed by \fBwm\fR, however, the \fB\-menu\fR configuration will be -remembered and the menus will return once the widget is managed again. -.TP -\fBwm frame \fIwindow\fR -. -If \fIwindow\fR has been reparented by the window manager into a -decorative frame, the command returns the platform specific window -identifier for the outermost frame that contains \fIwindow\fR (the -window whose parent is the root or virtual root). If \fIwindow\fR -has not been reparented by the window manager then the command returns -the platform specific window identifier for \fIwindow\fR. -.TP -\fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? -. -If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR -is changed and an empty string is returned. Otherwise the current -geometry for \fIwindow\fR is returned (this is the most recent -geometry specified either by manual resizing or -in a \fBwm geometry\fR command). \fINewGeometry\fR has -the form \fB=\fIwidth\fBx\fIheight\fB\(+-\fIx\fB\(+-\fIy\fR, where -any of \fB=\fR, \fIwidth\fBx\fIheight\fR, or \fB\(+-\fIx\fB\(+-\fIy\fR -may be omitted. \fIWidth\fR and \fIheight\fR are positive integers -specifying the desired dimensions of \fIwindow\fR. If \fIwindow\fR -is gridded (see \fBGRIDDED GEOMETRY MANAGEMENT\fR below) then the dimensions -are specified in grid units; otherwise they are specified in pixel -units. -.RS -.PP -\fIX\fR and \fIy\fR specify the desired location of -\fIwindow\fR on the screen, in pixels. -If \fIx\fR is preceded by \fB+\fR, it specifies -the number of pixels between the left edge of the screen and the left -edge of \fIwindow\fR's border; if preceded by \fB\-\fR then -\fIx\fR specifies the number of pixels -between the right edge of the screen and the right edge of \fIwindow\fR's -border. If \fIy\fR is preceded by \fB+\fR then it specifies the -number of pixels between the top of the screen and the top -of \fIwindow\fR's border; if \fIy\fR is preceded by \fB\-\fR then -it specifies the number of pixels between the bottom of \fIwindow\fR's -border and the bottom of the screen. -.PP -If \fInewGeometry\fR is specified as an empty string then any -existing user-specified geometry for \fIwindow\fR is cancelled, and -the window will revert to the size requested internally by its -widgets. -.PP -Note that this is related to \fBwinfo geometry\fR, but not the same. That can -only query the geometry, and always reflects Tk's current understanding of the -actual size and location of \fIwindow\fR, whereas \fBwm geometry\fR allows -both setting and querying of the \fIwindow manager\fR's understanding of the -size and location of the window. This can vary significantly, for example to -reflect the addition of decorative elements to \fIwindow\fR such as title -bars, and window managers are not required to precisely follow the requests -made through this command. -.RE -.TP -\fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? -. -This command indicates that \fIwindow\fR is to be managed as a -gridded window. -It also specifies the relationship between grid units and pixel units. -\fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid -units corresponding to the pixel dimensions requested internally -by \fIwindow\fR using \fBTk_GeometryRequest\fR. \fIWidthInc\fR -and \fIheightInc\fR specify the number of pixels in each horizontal -and vertical grid unit. -These four values determine a range of acceptable sizes for -\fIwindow\fR, corresponding to grid-based widths and heights -that are non-negative integers. -Tk will pass this information to the window manager; during -manual resizing, the window manager will restrict the window's size -to one of these acceptable sizes. -.RS -.PP -Furthermore, during manual resizing the window manager will display -the window's current size in terms of grid units rather than pixels. -If \fIbaseWidth\fR etc. are all specified as empty strings, then -\fIwindow\fR will no longer be managed as a gridded window. If -\fIbaseWidth\fR etc. are specified then the return value is an -empty string. -.PP -Otherwise the return value is a Tcl list containing -four elements corresponding to the current \fIbaseWidth\fR, -\fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if -\fIwindow\fR is not currently gridded, then an empty string -is returned. -.PP -Note: this command should not be needed very often, since the -\fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option -provide easier access to the same functionality. -.RE -.TP -\fBwm group \fIwindow\fR ?\fIpathName\fR? -. -If \fIpathName\fR is specified, it gives the path name for the leader of -a group of related windows. The window manager may use this information, -for example, to unmap all of the windows in a group when the group's -leader is iconified. \fIPathName\fR may be specified as an empty string to -remove \fIwindow\fR from any group association. If \fIpathName\fR is -specified then the command returns an empty string; otherwise it -returns the path name of \fIwindow\fR's current group leader, or an empty -string if \fIwindow\fR is not part of any group. -.TP -\fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? -. -If \fIbitmap\fR is specified, then it names a bitmap in the standard -forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). -This bitmap is passed to the window manager to be displayed in -\fIwindow\fR's icon, and the command returns an empty string. If -an empty string is specified for \fIbitmap\fR, then any current icon -bitmap is cancelled for \fIwindow\fR. -If \fIbitmap\fR is specified then the command returns an empty string. -Otherwise it returns the name of -the current icon bitmap associated with \fIwindow\fR, or an empty -string if \fIwindow\fR has no icon bitmap. On the Windows operating -system, an additional flag is supported: -.RS -.TP -\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR? -. -If the \fB\-default\fR -flag is given, the icon is applied to all toplevel windows (existing -and future) to which no other specific icon has yet been applied. -In addition to bitmap image types, a full path specification to -any file which contains a valid -Windows icon is also accepted (usually .ico or .icr files), or any -file for which the shell has assigned an icon. Tcl will -first test if the file contains an icon, then if it has an assigned -icon, and finally, if that fails, test for -a bitmap. -.RE -.TP -\fBwm iconify \fIwindow\fR -. -Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not -yet been mapped for the first time, this command will arrange for -it to appear in the iconified state when it is eventually mapped. -.TP -\fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? -. -If \fIbitmap\fR is specified, then it names a bitmap in the standard -forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). -This bitmap is passed to the window manager to be used as a mask -in conjunction with the \fBiconbitmap\fR option: where the mask -has zeroes no icon will be displayed; where it has ones, the bits -from the icon bitmap will be displayed. If -an empty string is specified for \fIbitmap\fR then any current icon -mask is cancelled for \fIwindow\fR (this is equivalent to specifying -a bitmap of all ones). If \fIbitmap\fR is specified -then the command returns an empty string. Otherwise it -returns the name of the current icon mask associated with -\fIwindow\fR, or an empty string if no mask is in effect. -.TP -\fBwm iconname \fIwindow\fR ?\fInewName\fR? -. -If \fInewName\fR is specified, then it is passed to the window -manager; the window manager should display \fInewName\fR inside -the icon associated with \fIwindow\fR. In this case an empty -string is returned as result. If \fInewName\fR is not specified -then the command returns the current icon name for \fIwindow\fR, -or an empty string if no icon name has been specified (in this -case the window manager will normally display the window's title, -as specified with the \fBwm title\fR command). -.TP -\fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR? -. -Sets the titlebar icon for \fIwindow\fR based on the named photo images. -If \fB\-default\fR is specified, this is applied to all future created -toplevels as well. The data in the images is taken as a snapshot at the -time of invocation. If the images are later changed, this is not -reflected to the titlebar icons. Multiple images are accepted to allow -different images sizes (e.g., 16x16 and 32x32) to be provided. The window -manager may scale provided icons to an appropriate size. -.RS -.PP -On Windows, the images are packed into a Windows icon structure. -This will override an ico specified to \fBwm iconbitmap\fR, and -vice versa. -.PP -On X, the images are arranged into the _NET_WM_ICON X property, which -most modern window managers support. A \fBwm iconbitmap\fR may exist -simultaneously. It is recommended to use not more than 2 icons, placing -the larger icon first. -.PP -On Macintosh, the first image called is loaded into an OSX-native icon -format, and becomes the application icon in dialogs, the Dock, and -other contexts. At the -script level the command will accept only the first image passed in the -parameters as support for multiple sizes/resolutions on macOS is outside Tk's -scope. Developers should use the largest icon they can support -(preferably 512 pixels) to ensure smooth rendering on the Mac. -.RE -.TP -\fBwm iconposition \fIwindow\fR ?\fIx y\fR? -. -If \fIx\fR and \fIy\fR are specified, they are passed to the window -manager as a hint about where to position the icon for \fIwindow\fR. -In this case an empty string is returned. If \fIx\fR and \fIy\fR are -specified as empty strings then any existing icon position hint is cancelled. -If neither \fIx\fR nor \fIy\fR is specified, then the command returns -a Tcl list containing two values, which are the current icon position -hints (if no hints are in effect then an empty string is returned). -.TP -\fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? -. -If \fIpathName\fR is specified, it is the path name for a window to -use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then -\fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR -is de-iconified then \fIpathName\fR will be unmapped again. If -\fIpathName\fR is specified as an empty string then any existing -icon window association for \fIwindow\fR will be cancelled. If -the \fIpathName\fR argument is specified then an empty string is -returned. Otherwise the command returns the path name of the -current icon window for \fIwindow\fR, or an empty string if there -is no icon window currently specified for \fIwindow\fR. -Button press events are disabled for \fIwindow\fR as long as it is -an icon window; this is needed in order to allow window managers to -.QW own -those events. -Note: not all window managers support the notion of an icon window. -.TP -\fBwm manage \fIwidget\fR -. -The \fIwidget\fR specified will become a stand alone top-level window. The -window will be decorated with the window managers title bar, etc. Only -\fIframe\fR, \fIlabelframe\fR and \fItoplevel\fR widgets can be used -with this command. Attempting to pass any other widget type will raise -an error. Attempting to manage a \fItoplevel\fR widget is benign and -achieves nothing. See also \fBGEOMETRY MANAGEMENT\fR. -.TP -\fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? -. -If \fIwidth\fR and \fIheight\fR are specified, they give -the maximum permissible dimensions for \fIwindow\fR. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -less than or equal to \fIwidth\fR and \fIheight\fR. -If \fIwidth\fR and \fIheight\fR are -specified, then the command returns an empty string. Otherwise -it returns a Tcl list with two elements, which are the -maximum width and height currently in effect. -The maximum size defaults to the size of the screen. -See the sections on geometry management below for more information. -.TP -\fBwm minsize \fIwindow\fR ?\fIwidth height\fR? -. -If \fIwidth\fR and \fIheight\fR are specified, they give the -minimum permissible dimensions for \fIwindow\fR. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -greater than or equal to \fIwidth\fR and \fIheight\fR. -If \fIwidth\fR and \fIheight\fR are -specified, then the command returns an empty string. Otherwise -it returns a Tcl list with two elements, which are the -minimum width and height currently in effect. -The minimum size defaults to one pixel in each dimension. -See the sections on geometry management below for more information. -.TP -\fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? -. -If \fIboolean\fR is specified, it must have a proper boolean form and -the override-redirect flag for \fIwindow\fR is set to that value. -If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is -returned to indicate whether or not the override-redirect flag -is currently set for \fIwindow\fR. -Setting the override-redirect flag for a window causes -it to be ignored by the window manager; among other things, this means -that the window will not be reparented from the root window into a -decorative frame and the user will not be able to manipulate the -window using the normal window manager mechanisms. -.RS -.PP -Note that the override-redirect flag is only guaranteed to be taken notice of -when the window is first mapped or when mapped after the state is changed from -withdrawn to normal. Some, but not all, platforms will take notice at -additional times. -.RE -.TP -\fBwm positionfrom \fIwindow\fR ?\fIwho\fR? -. -If \fIwho\fR is specified, it must be either \fBprogram\fR or -\fBuser\fR, or an abbreviation of one of these two. It indicates -whether \fIwindow\fR's current position was requested by the -program or by the user. Many window managers ignore program-requested -initial positions and ask the user to manually position the window; if -\fBuser\fR is specified then the window manager should position the -window at the given place without asking the user for assistance. -If \fIwho\fR is specified as an empty string, then the current position -source is cancelled. -If \fIwho\fR is specified, then the command returns an empty string. -Otherwise it returns \fBuser\fR or \fBprogram\fR to indicate the -source of the window's current position, or an empty string if -no source has been specified yet. Most window managers interpret -.QW "no source" -as equivalent to \fBprogram\fR. -Tk will automatically set the position source to \fBuser\fR -when a \fBwm geometry\fR command is invoked, unless the source has -been set explicitly to \fBprogram\fR. -.TP -\fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? -. -This command is used to manage window manager protocols such as -\fBWM_DELETE_WINDOW\fR. -\fIName\fR is the name of an atom corresponding to a window manager -protocol, such as \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR -or \fBWM_TAKE_FOCUS\fR. -If both \fIname\fR and \fIcommand\fR are specified, then \fIcommand\fR -is associated with the protocol specified by \fIname\fR. -\fIName\fR will be added to \fIwindow\fR's \fBWM_PROTOCOLS\fR -property to tell the window manager that the application has a -protocol handler for \fIname\fR, and \fIcommand\fR will -be invoked in the future whenever the window manager sends a -message to the client for that protocol. -In this case the command returns an empty string. -If \fIname\fR is specified but \fIcommand\fR is not, then the current -command for \fIname\fR is returned, or an empty string if there -is no handler defined for \fIname\fR. -If \fIcommand\fR is specified as an empty string then the current -handler for \fIname\fR is deleted and it is removed from the -\fBWM_PROTOCOLS\fR property on \fIwindow\fR; an empty string is -returned. -Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the -command returns a list of all the protocols for which handlers -are currently defined for \fIwindow\fR. -.RS -.PP -Tk always defines a protocol handler for \fBWM_DELETE_WINDOW\fR, even if -you have not asked for one with \fBwm protocol\fR. -If a \fBWM_DELETE_WINDOW\fR message arrives when you have not defined -a handler, then Tk handles the message by destroying the window for -which it was received. -.RE -.TP -\fBwm resizable \fIwindow\fR ?\fIwidth height\fR? -. -This command controls whether or not the user may interactively -resize a top-level window. If \fIwidth\fR and \fIheight\fR are -specified, they are boolean values that determine whether the -width and height of \fIwindow\fR may be modified by the user. -In this case the command returns an empty string. -If \fIwidth\fR and \fIheight\fR are omitted then the command -returns a list with two 0/1 elements that indicate whether the -width and height of \fIwindow\fR are currently resizable. -By default, windows are resizable in both dimensions. -If resizing is disabled, then the window's size will be the size -from the most recent interactive resize or \fBwm geometry\fR -command. If there has been no such operation then -the window's natural size will be used. -.TP -\fBwm sizefrom \fIwindow\fR ?\fIwho\fR? -. -If \fIwho\fR is specified, it must be either \fBprogram\fR or -\fBuser\fR, or an abbreviation of one of these two. It indicates -whether \fIwindow\fR's current size was requested by the -program or by the user. Some window managers ignore program-requested -sizes and ask the user to manually size the window; if -\fBuser\fR is specified then the window manager should give the -window its specified size without asking the user for assistance. -If \fIwho\fR is specified as an empty string, then the current size -source is cancelled. -If \fIwho\fR is specified, then the command returns an empty string. -Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the -source of the window's current size, or an empty string if -no source has been specified yet. Most window managers interpret -.QW "no source" -as equivalent to \fBprogram\fR. -.TP -\fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? -. -The \fBstackorder\fR command returns a list of toplevel windows -in stacking order, from lowest to highest. When a single toplevel -window is passed, the returned list recursively includes all of the -window's children that are toplevels. Only those toplevels -that are currently mapped to the screen are returned. -The \fBstackorder\fR command can also be used to determine if one -toplevel is positioned above or below a second toplevel. -When two window arguments separated by either \fBisabove\fR or -\fBisbelow\fR are passed, a boolean result indicates whether -or not the first window is currently above or below the second -window in the stacking order. -.TP -\fBwm state \fIwindow\fR ?newstate? -. -If \fInewstate\fR is specified, the window will be set to the new state, -otherwise it returns the current state of \fIwindow\fR: either -\fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and Mac -OS X only) \fBzoomed\fR. -The difference between \fBiconic\fR and \fBicon\fR is that -\fBiconic\fR refers to a window that has been iconified (e.g., with the -\fBwm iconify\fR command) while \fBicon\fR refers to a window whose only -purpose is to serve as the icon for some other window (via the \fBwm -iconwindow\fR command). The \fBicon\fR state cannot be set. -.TP -\fBwm title \fIwindow\fR ?\fIstring\fR? -. -If \fIstring\fR is specified, then it will be passed to the window -manager for use as the title for \fIwindow\fR (the window manager -should display this string in \fIwindow\fR's title bar). In this -case the command returns an empty string. If \fIstring\fR is not -specified then the command returns the current title for the -\fIwindow\fR. The title for a window defaults to its name. -.TP -\fBwm transient \fIwindow\fR ?\fImaster\fR? -. -If \fImaster\fR is specified, then the window manager is informed -that \fIwindow\fR is a transient window (e.g. pull-down menu) working -on behalf of \fImaster\fR (where \fImaster\fR is the -path name for a top-level window). If \fImaster\fR -is specified as an empty string then \fIwindow\fR is marked as not -being a transient window any more. Otherwise the command -returns the path name of \fIwindow\fR's current master, or an -empty string if \fIwindow\fR is not currently a transient window. -A transient window will mirror state changes in the master and -inherit the state of the master when initially mapped. It is an -error to attempt to make a window a transient of itself. -The window manager may also decorate a transient window differently, removing -some features normally present (e.g., minimize and maximize buttons) though -this is entirely at the discretion of the window manager. -.TP -\fBwm withdraw \fIwindow\fR -. -Arranges for \fIwindow\fR to be withdrawn from the screen. This -causes the window to be unmapped and forgotten about by the window -manager. If the window -has never been mapped, then this command -causes the window to be mapped in the withdrawn state. Not all -window managers appear to know how to handle windows that are -mapped in the withdrawn state. -Note: it sometimes seems to be necessary to withdraw a -window and then re-map it (e.g. with \fBwm deiconify\fR) to get some -window managers to pay attention to changes in window attributes -such as group. -.SH "GEOMETRY MANAGEMENT" -.PP -By default a top-level window appears on the screen in its -\fInatural size\fR, which is the one determined internally by its -widgets and geometry managers. -If the natural size of a top-level window changes, then the window's size -changes to match. -A top-level window can be given a size other than its natural size in two ways. -First, the user can resize the window manually using the facilities -of the window manager, such as resize handles. -Second, the application can request a particular size for a -top-level window using the \fBwm geometry\fR command. -These two cases are handled identically by Tk; in either case, -the requested size overrides the natural size. -You can return the window to its natural by invoking \fBwm geometry\fR -with an empty \fIgeometry\fR string. -.PP -Normally a top-level window can have any size from one pixel in each -dimension up to the size of its screen. -However, you can use the \fBwm minsize\fR and \fBwm maxsize\fR commands -to limit the range of allowable sizes. -The range set by \fBwm minsize\fR and \fBwm maxsize\fR applies to -all forms of resizing, including the window's natural size as -well as manual resizes and the \fBwm geometry\fR command. -You can also use the command \fBwm resizable\fR to completely -disable interactive resizing in one or both dimensions. -.PP -The \fBwm manage\fR and \fBwm forget\fR commands may be used to -perform undocking and docking of windows. After a widget is managed -by \fBwm manage\fR command, all other \fBwm\fR subcommands may be used -with the widget. Only widgets created using the toplevel command may -have an attached menu via the \fB\-menu\fR configure option. A toplevel -widget may be used as a frame and managed with any of the other -geometry managers after using the \fBwm forget\fR command. Any menu -associated with a toplevel widget will be hidden when managed by -another geometry managers. The menus will reappear once the window is -managed by \fBwm\fR. All custom bindtags for widgets in a subtree -that have their top-level widget changed via a \fBwm manage\fR or -\fBwm forget\fR command, must be redone to adjust any top-level widget -path in the bindtags. Bindtags that have not been customized do not -have to be redone. -.SH "GRIDDED GEOMETRY MANAGEMENT" -.PP -Gridded geometry management occurs when one of the widgets of an -application supports a range of useful sizes. -This occurs, for example, in a text editor where the scrollbars, -menus, and other adornments are fixed in size but the edit widget -can support any number of lines of text or characters per line. -In this case, it is usually desirable to let the user specify the -number of lines or characters-per-line, either with the -\fBwm geometry\fR command or by interactively resizing the window. -In the case of text, and in other interesting cases also, only -discrete sizes of the window make sense, such as integral numbers -of lines and characters-per-line; arbitrary pixel sizes are not useful. -.PP -Gridded geometry management provides support for this kind of -application. -Tk (and the window manager) assume that there is a grid of some -sort within the application and that the application should be -resized in terms of \fIgrid units\fR rather than pixels. -Gridded geometry management is typically invoked by turning on -the \fBsetGrid\fR option for a widget; it can also be invoked -with the \fBwm grid\fR command or by calling \fBTk_SetGrid\fR. -In each of these approaches the particular widget (or sometimes -code in the application as a whole) specifies the relationship between -integral grid sizes for the window and pixel sizes. -To return to non-gridded geometry management, invoke -\fBwm grid\fR with empty argument strings. -.PP -When gridded geometry management is enabled then all the dimensions specified -in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands -are treated as grid units rather than pixel units. -Interactive resizing is also carried out in even numbers of grid units -rather than pixels. -.SH BUGS -.PP -Most existing window managers appear to have bugs that affect the -operation of the \fBwm\fR command. For example, some changes will not -take effect if the window is already active: the window will have -to be withdrawn and de-iconified in order to make the change happen. -.SH EXAMPLES -.PP -A fixed-size window that says that it is fixed-size too: -.CS -toplevel .fixed -\fBwm title\fR .fixed "Fixed-size Window" -\fBwm resizable\fR .fixed 0 0 -.CE -.PP -A simple dialog-like window, centred on the screen: -.CS -# Create and arrange the dialog contents. -toplevel .msg -label .msg.l \-text "This is a very simple dialog demo." -button .msg.ok \-text OK \-default active \-command {destroy .msg} -pack .msg.ok \-side bottom \-fill x -pack .msg.l \-expand 1 \-fill both - -# Now set the widget up as a centred dialog. - -# But first, we need the geometry managers to finish setting -# up the interior of the dialog, for which we need to run the -# event loop with the widget hidden completely... -\fBwm withdraw\fR .msg -update -set x [expr {([winfo screenwidth .]\-[winfo width .msg])/2}] -set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] -\fBwm geometry\fR .msg +$x+$y -\fBwm transient\fR .msg . -\fBwm title\fR .msg "Dialog demo" -\fBwm deiconify\fR .msg -.CE -.SH "SEE ALSO" -toplevel(n), winfo(n) -.SH KEYWORDS -aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager -'\" Local Variables: -'\" mode: nroff -'\" End: |