diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 17:48:54 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 17:48:54 (GMT) |
commit | 8eb0f61e2e27ef6594eee8bcf68d574fb087fe66 (patch) | |
tree | fc0f3692516c8c3e8090df20223d342a1b64df93 /tk8.6/doc | |
parent | 5f5fd2864a3193a8d5da12fcb92ba7379084c286 (diff) | |
download | blt-8eb0f61e2e27ef6594eee8bcf68d574fb087fe66.zip blt-8eb0f61e2e27ef6594eee8bcf68d574fb087fe66.tar.gz blt-8eb0f61e2e27ef6594eee8bcf68d574fb087fe66.tar.bz2 |
update tcl/tk
Diffstat (limited to 'tk8.6/doc')
177 files changed, 34391 insertions, 0 deletions
diff --git a/tk8.6/doc/3DBorder.3 b/tk8.6/doc/3DBorder.3 new file mode 100644 index 0000000..f2f0eb8 --- /dev/null +++ b/tk8.6/doc/3DBorder.3 @@ -0,0 +1,294 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_3DBorder +\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Tk_3DBorder +\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR +.sp +Tk_3DBorder +\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR +.sp +void +\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +.sp +void +\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +.sp +void +\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +.sp +void +\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +.sp +void +\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR +.sp +void +\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR +.sp +void +\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR +.sp +const char * +\fBTk_NameOf3DBorder(\fIborder\fB)\fR +.sp +XColor * +\fBTk_3DBorderColor(\fIborder\fB)\fR +.sp +GC * +\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR +.sp +\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR +.sp +\fBTk_Free3DBorder(\fIborder\fB)\fR +.SH ARGUMENTS +.AS "Tk_3DBorder" borderWidth +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window (for all procedures except \fBTk_Get3DBorder\fR, +must be the window for which the border was allocated). +.AP Tcl_Obj *objPtr in +Pointer to value whose value describes color corresponding to +background (flat areas). Illuminated edges will be brighter than +this and shadowed edges will be darker than this. +.AP char *colorName in +Same as \fIobjPtr\fR except value is supplied as a string rather +than a value. +.AP Drawable drawable in +X token for window or pixmap; indicates where graphics are to be drawn. +Must either be the X window for \fItkwin\fR or a pixmap with the +same screen and depth as \fItkwin\fR. +.AP Tk_3DBorder border in +Token for border previously allocated in call to \fBTk_Get3DBorder\fR. +.AP int x in +X-coordinate of upper-left corner of rectangle describing border +or bevel, in pixels. +.AP int y in +Y-coordinate of upper-left corner of rectangle describing border or +bevel, in pixels. +.AP int width in +Width of rectangle describing border or bevel, in pixels. +.AP int height in +Height of rectangle describing border or bevel, in pixels. +.AP int borderWidth in +Width of border in pixels. Positive means border is inside rectangle +given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means +border is outside rectangle. +.AP int relief in +Indicates 3-D position of interior of value relative to exterior; +should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, +\fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR +for \fBTk_Fill3DRectangle\fR). +.AP XPoint *pointPtr in +Pointer to array of points describing the set of vertices in a polygon. +The polygon need not be closed (it will be closed automatically if it +is not). +.AP int numPoints in +Number of points at \fI*pointPtr\fR. +.AP int polyBorderWidth in +Width of border in pixels. If positive, border is drawn to left of +trajectory given by \fIpointPtr\fR; if negative, border is drawn to +right of trajectory. If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or +\fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory. +.AP int leftRelief in +Height of left side of polygon's path relative to right. \fBTK_RELIEF_RAISED\fR +means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side +should appear higher; +\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things. +For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to +indicate no difference in height. +.AP int leftBevel in +Non-zero means this bevel forms the left side of the value; zero means +it forms the right side. +.AP int leftIn in +Non-zero means that the left edge of the horizontal bevel angles in, +so that the bottom of the edge is farther to the right than +the top. +Zero means the edge angles out, so that the bottom is farther to the +left than the top. +.AP int rightIn in +Non-zero means that the right edge of the horizontal bevel angles in, +so that the bottom of the edge is farther to the left than the top. +Zero means the edge angles out, so that the bottom is farther to the +right than the top. +.AP int topBevel in +Non-zero means this bevel forms the top side of the value; zero means +it forms the bottom side. +.AP int which in +Specifies which of the border's graphics contexts is desired. +Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. +.BE +.SH DESCRIPTION +.PP +These procedures provide facilities for drawing window borders in a +way that produces a three-dimensional appearance. +\fBTk_Alloc3DBorderFromObj\fR +allocates colors and Pixmaps needed to draw a border in the window +given by the \fItkwin\fR argument. The value of \fIobjPtr\fR +is a standard Tk color name that determines the border colors. +The color indicated by \fIobjPtr\fR will not actually be used in +the border; it indicates the background color for the window +(i.e. a color for flat surfaces). +The illuminated portions of the border will appear brighter than indicated +by \fIobjPtr\fR, and the shadowed portions of the border will appear +darker than \fIobjPtr\fR. +.PP +\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls +to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information +for the border (e.g. a bogus color name was given) +then NULL is returned and an error message is left as the result of +interpreter \fIinterp\fR. +If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches +information about the return value in \fIobjPtr\fR, which speeds up +future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except +that the color is specified with a string instead of a value. This +prevents \fBTk_Get3DBorder\fR from caching the return value, so +\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. +.PP +\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given +the window and color name used to create the border. +\fBTk_Get3DBorderFromObj\fR does not actually create the border; it must +already have been created with a previous call to +\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be +invoked to draw the border. +The \fItkwin\fR argument specifies the +window for which the border was allocated, and \fIdrawable\fR +specifies a window or pixmap in which the border is to be drawn. +\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it +must refer to a compatible +pixmap or window: one associated with the same screen and with the +same depth as \fItkwin\fR. +The \fIx\fR, \fIy\fR, \fIwidth\fR, and +\fIheight\fR arguments define the bounding box of the border region +within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and +\fIwidth\fR and \fIheight\fR are the dimensions of the window), and +\fIborderWidth\fR specifies the number of pixels actually +occupied by the border. The \fIrelief\fR argument indicates +which of several three-dimensional effects is desired: +\fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should +appear raised relative to the exterior of the rectangle, and +\fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. +\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be +a groove or ridge around the exterior of the rectangle. +.PP +\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except +that it first fills the rectangular area with the background color +(one corresponding +to the color used to create \fIborder\fR). Then it calls +\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of +the rectangular area. The argument \fIrelief\fR indicates the desired +effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that +happens is to fill the rectangle with the background color). +.PP +The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex +shapes with a three-dimensional appearance. The \fIpointPtr\fR and +\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR +indicates how wide the border should be (and on which side of the +trajectory to draw it), and \fIleftRelief\fR indicates which side +of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR +draws a border around the given trajectory using the colors from +\fIborder\fR to produce a three-dimensional appearance. If the trajectory is +non-self-intersecting, the appearance will be a raised or sunken +polygon shape. The trajectory may be self-intersecting, although +it's not clear how useful this is. +.PP +\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what +\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills +the polygonal area with the background color from \fIborder\fR, +then calls \fBTk_Draw3DPolygon\fR to draw a border around the +area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no +border is drawn). +.PP +The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR +provide lower-level drawing primitives that are used by +procedures such as \fBTk_Draw3DRectangle\fR. +These procedures are also useful in their own right for drawing +rectilinear border shapes. +\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the +left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR +draws a horizontal beveled edge, such as the top or bottom of a +rectangle. +Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +arguments that describe the rectangular area of the beveled edge +(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). +The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the +position of the border relative to the +.QW inside +of the value, and +\fIrelief\fR indicates the relief of the inside of the value relative +to the outside. +\fBTk_3DVerticalBevel\fR just draws a rectangular region. +\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate +mitered corners; it should be called after \fBTk_3DVerticalBevel\fR +(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in +the corner). +The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR +describe the mitering at the corners; a value of 1 means that the bottom +edge of the trapezoid will be shorter than the top, 0 means it will +be longer. +For example, to draw a rectangular border the top bevel should be +drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the +bottom bevel should be drawn with 0 for both arguments. +.PP +The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background +pixel and/or pixmap of \fItkwin\fR to produce a result compatible +with \fIborder\fR. For color displays, the resulting background will +just be the color specified when \fIborder\fR was created; for monochrome +displays, the resulting background +will be a light stipple pattern, in order to distinguish the background from +the illuminated portion of the border. +.PP +Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR +will return the color name that was used to create the border. +.PP +The procedure \fBTk_3DBorderColor\fR returns the XColor structure +that will be used for flat surfaces drawn for its \fIborder\fR +argument by procedures like \fBTk_Fill3DRectangle\fR. +The return value corresponds to the color name that was used to +create the border. +The XColor, and its associated pixel value, will remain allocated +as long as \fIborder\fR exists. +.PP +The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts +that are used to draw the border. +The argument \fIwhich\fR selects which one of the three possible GC's: +\fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces, +\fBTK_3D_LIGHT_GC\fR returns the context for light shadows, +and \fBTK_3D_DARK_GC\fR returns the context for dark shadows. +.PP +When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR +or \fBTk_Free3DBorder\fR should +be called to release the resources associated with it. +For \fBTk_Free3DBorderFromObj\fR the border to release is specified +with the window and color name used to create the +border; for \fBTk_Free3DBorder\fR the border to release is specified +with the Tk_3DBorder token for the border. +There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or +\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR +or \fBTk_Get3DBorder\fR. +.SH KEYWORDS +3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect diff --git a/tk8.6/doc/AddOption.3 b/tk8.6/doc/AddOption.3 new file mode 100644 index 0000000..2368f09 --- /dev/null +++ b/tk8.6/doc/AddOption.3 @@ -0,0 +1,50 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH Tk_AddOption 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_AddOption \- Add an option to the option database +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +void +\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR) +.SH ARGUMENTS +.AP Tk_Window tkwin in +Token for window. +.AP "const char" *name in +Multi-element name of option. +.AP "const char" *value in +Value of option. +.AP int priority in +Overall priority level to use for option. +.BE +.SH DESCRIPTION +.PP +This procedure is invoked to add an option to the database +associated with \fItkwin\fR's main window. \fIName\fR +contains the option being specified and consists of names and/or +classes separated by asterisks or dots, in the usual X format. +\fIValue\fR contains the text string to associate with \fIname\fR; +this value will be returned in calls to \fBTk_GetOption\fR. +\fIPriority\fR specifies the priority of the value; when options are +queried using \fBTk_GetOption\fR, the value with the highest priority +is returned. \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR. Some +common priority values are: +.IP 20 +Used for default values hard-coded into widgets. +.IP 40 +Used for options specified in application-specific startup files. +.IP 60 +Used for options specified in user-specific defaults files, such as +\fB.Xdefaults\fR, resource databases loaded into the X server, or +user-specific startup files. +.IP 80 +Used for options specified interactively after the application starts +running. +.SH KEYWORDS +class, name, option, add diff --git a/tk8.6/doc/BindTable.3 b/tk8.6/doc/BindTable.3 new file mode 100644 index 0000000..5130bfc --- /dev/null +++ b/tk8.6/doc/BindTable.3 @@ -0,0 +1,153 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_BindingTable +\fBTk_CreateBindingTable(\fIinterp\fB)\fR +.sp +\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR +.sp +unsigned long +\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR +.sp +int +\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR +.sp +const char * +\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR +.sp +\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR +.sp +\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR +.sp +\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR +.SH ARGUMENTS +.AS Tk_BindingTable bindingTable +.AP Tcl_Interp *interp in +Interpreter to use when invoking bindings in binding table. Also +used for returning results and errors from binding procedures. +.AP Tk_BindingTable bindingTable in +Token for binding table; must have been returned by some previous +call to \fBTk_CreateBindingTable\fR. +.AP ClientData object in +Identifies object with which binding is associated. +.AP "const char" *eventString in +String describing event sequence. +.AP "const char" *script in +Tcl script to invoke when binding triggers. +.AP int append in +Non-zero means append \fIscript\fR to existing script for binding, +if any; zero means replace existing script with new one. +.AP XEvent *eventPtr in +X event to match against bindings in \fIbindingTable\fR. +.AP Tk_Window tkwin in +Identifier for any window on the display where the event occurred. +Used to find display-related information such as key maps. +.AP int numObjects in +Number of object identifiers pointed to by \fIobjectPtr\fR. +.AP ClientData *objectPtr in +Points to an array of object identifiers: bindings will be considered +for each of these objects in order from first to last. +.BE +.SH DESCRIPTION +.PP +These procedures provide a general-purpose mechanism for creating +and invoking bindings. +Bindings are organized in terms of \fIbinding tables\fR. +A binding table consists of a collection of bindings plus a history +of recent events. +Within a binding table, bindings are associated with \fIobjects\fR. +The meaning of an object is defined by clients of the binding package. +For example, Tk keeps uses one binding table to hold all of the bindings +created by the \fBbind\fR command. +For this table, objects are pointers to strings such as window names, class +names, or other binding tags such as \fBall\fR. +Tk also keeps a separate binding table for each canvas widget, which manages +bindings created by the canvas's \fBbind\fR widget command; within +this table, an object is either a pointer to the internal structure for a +canvas item or a Tk_Uid identifying a tag. +.PP +The procedure \fBTk_CreateBindingTable\fR creates a new binding +table and associates \fIinterp\fR with it (when bindings in the +table are invoked, the scripts will be evaluated in \fIinterp\fR). +\fBTk_CreateBindingTable\fR returns a token for the table, which +must be used in calls to other procedures such as \fBTk_CreateBinding\fR +or \fBTk_BindEvent\fR. +.PP +\fBTk_DeleteBindingTable\fR frees all of the state associated +with a binding table. +Once it returns the caller should not use the \fIbindingTable\fR +token again. +.PP +\fBTk_CreateBinding\fR adds a new binding to an existing table. +The \fIobject\fR argument identifies the object with which the +binding is to be associated, and it may be any one-word value. +Typically it is a pointer to a string or data structure. +The \fIeventString\fR argument identifies the event or sequence +of events for the binding; see the documentation for the +\fBbind\fR command for a description of its format. +\fIscript\fR is the Tcl script to be evaluated when the binding +triggers. +\fIappend\fR indicates what to do if there already +exists a binding for \fIobject\fR and \fIeventString\fR: if \fIappend\fR +is zero then \fIscript\fR replaces the old script; if \fIappend\fR +is non-zero then the new script is appended to the old one. +\fBTk_CreateBinding\fR returns an X event mask for all the events +associated with the bindings. +This information may be useful to invoke \fBXSelectInput\fR to +select relevant events, or to disallow the use of certain events +in bindings. +If an error occurred while creating the binding (e.g., \fIeventString\fR +refers to a non-existent event), then 0 is returned and an error +message is left as the result of interpreter \fIinterp\fR. +.PP +\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the +binding given by \fIobject\fR and \fIeventString\fR, if +such a binding exists. +\fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR. +In some cases it may reset the interpreter result to the default +empty value. +.PP +\fBTk_GetBinding\fR returns a pointer to the script associated +with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR. +If no such binding exists then NULL is returned and an error +message is left as the result of interpreter \fIinterp\fR. +.PP +\fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list +of all the event strings for which there are bindings in +\fIbindingTable\fR associated with \fIobject\fR. +If there are no bindings for \fIobject\fR, the result will be an empty +string. +.PP +\fBTk_DeleteAllBindings\fR deletes all of the bindings in +\fIbindingTable\fR that are associated with \fIobject\fR. +.PP +\fBTk_BindEvent\fR is called to process an event. +It makes a copy of the event in an internal history list associated +with the binding table, then it checks for bindings that match +the event. +\fBTk_BindEvent\fR processes each of the objects pointed to +by \fIobjectPtr\fR in turn. +For each object, it finds all the bindings that match the current +event history, selects the most specific binding using the priority +mechanism described in the documentation for \fBbind\fR, +and invokes the script for that binding. +If there are no matching bindings for a particular object, then +the object is skipped. +\fBTk_BindEvent\fR continues through all of the objects, handling +exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as +described in the documentation for \fBbind\fR. +.SH KEYWORDS +binding, event, object, script diff --git a/tk8.6/doc/CanvPsY.3 b/tk8.6/doc/CanvPsY.3 new file mode 100644 index 0000000..5e104ce --- /dev/null +++ b/tk8.6/doc/CanvPsY.3 @@ -0,0 +1,121 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +double +\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR) +.sp +int +\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR) +.sp +int +\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR) +.sp +int +\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR) +.sp +\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) +.sp +int +\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) +.SH ARGUMENTS +.AS "unsigned int" "numPoints" +.AP Tk_Canvas canvas in +A token that identifies a canvas widget for which Postscript is +being generated. +.AP double canvasY in +Y-coordinate in the space of the canvas. +.AP Tcl_Interp *interp in/out +A Tcl interpreter; Postscript is appended to its result, or the +result may be replaced with an error message. +.AP Pixmap bitmap in +Bitmap to use for generating Postscript. +.AP int x in +X-coordinate within \fIbitmap\fR of left edge of region to output. +.AP int y in +Y-coordinate within \fIbitmap\fR of top edge of region to output. +.AP "int" width in +Width of region of bitmap to output, in pixels. +.AP "int" height in +Height of region of bitmap to output, in pixels. +.AP XColor *colorPtr in +Information about color value to set in Postscript. +.AP Tk_Font tkFont in +Font for which Postscript is to be generated. +.AP double *coordPtr in +Pointer to an array of coordinates for one or more +points specified in canvas coordinates. +The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3, +and so on. +.AP int numPoints in +Number of points at \fIcoordPtr\fR. +.BE +.SH DESCRIPTION +.PP +These procedures are called by canvas type managers to carry out +common functions related to generating Postscript. +Most of the procedures take a \fIcanvas\fR argument, which +refers to a canvas widget for which Postscript is being +generated. +.PP +\fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of +a canvas and returns the value that should be used for that point +in the Postscript currently being generated for \fIcanvas\fR. +Y coordinates require transformation because Postscript uses an +origin at the lower-left corner whereas X uses an origin at the +upper-left corner. +Canvas x coordinates can be used directly in Postscript without +transformation. +.PP +\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region +of a bitmap. +The Postscript is generated in proper image data format for Postscript, +i.e., as data between angle brackets, one bit per pixel. +The Postscript is appended to the result of interpreter \fIinterp\fR +and \fBTCL_OK\fR is returned unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter result is overwritten +with an error message. +.PP +\fBTk_CanvasPsColor\fR generates Postscript to set the current color +to correspond to its \fIcolorPtr\fR argument, taking into account any +color map specified in the \fBpostscript\fR command. +It appends the Postscript to the interpreter \fIinterp\fR's result and returns +\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is +returned and the interpreter's result is overwritten with an error message. +.PP +\fBTk_CanvasPsFont\fR generates Postscript that sets the current font +to match \fItkFont\fR as closely as possible. +\fBTk_CanvasPsFont\fR takes into account any font map specified +in the \fBpostscript\fR command, and it does +the best it can at mapping X fonts to Postscript fonts. +It appends the Postscript to interpreter \fIinterp\fR's result and +returns \fBTCL_OK\fR unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter's result is +overwritten with an error message. +.PP +\fBTk_CanvasPsPath\fR generates Postscript to set the current path +to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR. +It appends the resulting Postscript to the result of interpreter \fIinterp\fR. +.PP +\fBTk_CanvasPsStipple\fR generates Postscript that will fill the +current path in stippled fashion. +It uses \fIbitmap\fR as the stipple pattern and the current Postscript +color; ones in the stipple bitmap are drawn in the current color, and +zeroes are not drawn at all. +The Postscript is appended to interpreter \fIinterp\fR's result and +\fBTCL_OK\fR is returned, unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter's result is +overwritten with an error message. +.SH KEYWORDS +bitmap, canvas, color, font, path, Postscript, stipple diff --git a/tk8.6/doc/CanvTkwin.3 b/tk8.6/doc/CanvTkwin.3 new file mode 100644 index 0000000..d53c5b1 --- /dev/null +++ b/tk8.6/doc/CanvTkwin.3 @@ -0,0 +1,158 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CanvasTkwin\fR(\fIcanvas\fR) +.sp +int +\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR) +.sp +\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR) +.sp +\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR) +.sp +\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) +.sp +\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) +.sp +Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; +.sp +Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; +.SH ARGUMENTS +.AS Tk_ItemType *drawableXPtr +.AP Tk_Canvas canvas in +A token that identifies a canvas widget. +.AP Tcl_Interp *interp in/out +Interpreter to use for error reporting. +.AP "const char" *string in +Textual description of a canvas coordinate. +.AP double *doublePtr out +Points to place to store a converted coordinate. +.AP double x in +An x coordinate in the space of the canvas. +.AP double y in +A y coordinate in the space of the canvas. +.AP short *drawableXPtr out +Pointer to a location in which to store an x coordinate in the space +of the drawable currently being used to redisplay the canvas. +.AP short *drawableYPtr out +Pointer to a location in which to store a y coordinate in the space +of the drawable currently being used to redisplay the canvas. +.AP GC gc out +Graphics context to modify. +.AP short *screenXPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIx\fR. +.AP short *screenYPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIy\fR. +.AP int x1 in +Left edge of the region that needs redisplay. Only pixels at or to +the right of this coordinate need to be redisplayed. +.AP int y1 in +Top edge of the region that needs redisplay. Only pixels at or below +this coordinate need to be redisplayed. +.AP int x2 in +Right edge of the region that needs redisplay. Only pixels to +the left of this coordinate need to be redisplayed. +.AP int y2 in +Bottom edge of the region that needs redisplay. Only pixels above +this coordinate need to be redisplayed. +.BE +.SH DESCRIPTION +.PP +These procedures are called by canvas type managers to perform various +utility functions. +.PP +\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular +canvas. +.PP +\fBTk_CanvasGetCoord\fR translates a string specification of a +coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision +canvas coordinate. +If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR +stores the corresponding canvas coordinate at *\fIdoublePtr\fR +and returns \fBTCL_OK\fR. +Otherwise it stores an error message in the interpreter result and +returns \fBTCL_ERROR\fR. +.PP +\fBTk_CanvasDrawableCoords\fR is called by type managers during +redisplay to compute where to draw things. +Given \fIx\fR and \fIy\fR coordinates in the space of the +canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding +pixel in the drawable that is currently being used for redisplay; +it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR. +This procedure should not be invoked except during redisplay. +.PP +\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay. +It sets the stipple origin in \fIgc\fR so that stipples drawn +with \fIgc\fR in the current offscreen pixmap will line up +with stipples drawn with origin (0,0) in the canvas's actual +window. +\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee +that stipple patterns line up properly when the canvas is +redisplayed in small pieces. +Redisplays are carried out in double-buffered fashion where a +piece of the canvas is redrawn in an offscreen pixmap and then +copied back onto the screen. +In this approach the stipple origins in graphics contexts need to +be adjusted during each redisplay to compensate for the position +of the off-screen pixmap relative to the window. +If an item is being drawn with stipples, its type manager typically +calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR +to draw something; after it is finished drawing, the type manager +calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0) +(the restore is needed because graphics contexts are shared, so +they cannot be modified permanently). +.PP +\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR +except that it returns coordinates in the canvas's window on the +screen, instead of coordinates in an off-screen pixmap. +.PP +\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager +to inform Tk that a portion of a canvas needs to be redrawn. +The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments +specify the region that needs to be redrawn, in canvas coordinates. +Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR, +since Tk can normally figure out when an item has changed and make +the redisplay request on its behalf (this happens, for example +whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR). +The only time that a type manager needs to call +\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own +without being invoked through one of the procedures in its Tk_ItemType; +this could happen, for example, in an image item if the image is +modified using image commands. +.PP +\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are +procedures that handle the \fB\-tags\fR option for canvas items. +The code of a canvas type manager will not call these procedures +directly, but will use their addresses to create a \fBTk_CustomOption\fR +structure for the \fB\-tags\fR option. The code typically looks +like this: +.PP +.CS +static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, + Tk_CanvasTagsPrintProc, (ClientData) NULL +}; + +static const Tk_ConfigSpec configSpecs[] = { + ... + {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL, + NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, + ... +}; +.CE +.SH KEYWORDS +canvas, focus, item type, redisplay, selection, type manager diff --git a/tk8.6/doc/CanvTxtInfo.3 b/tk8.6/doc/CanvTxtInfo.3 new file mode 100644 index 0000000..92a2bc3 --- /dev/null +++ b/tk8.6/doc/CanvTxtInfo.3 @@ -0,0 +1,100 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CanvasTextInfo \- additional information for managing text items in canvases +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_CanvasTextInfo * +\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) +.SH ARGUMENTS +.AS Tk_Canvas canvas +.AP Tk_Canvas canvas in +A token that identifies a particular canvas widget. +.BE +.SH DESCRIPTION +.PP +Textual canvas items are somewhat more complicated to manage than +other items, due to things like the selection and the input focus. +\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager +to obtain additional information needed for items that display text. +The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to +a structure that is shared between Tk and all the items that display +text. +The structure has the following form: +.CS +typedef struct Tk_CanvasTextInfo { + Tk_3DBorder \fIselBorder\fR; + int \fIselBorderWidth\fR; + XColor *\fIselFgColorPtr\fR; + Tk_Item *\fIselItemPtr\fR; + int \fIselectFirst\fR; + int \fIselectLast\fR; + Tk_Item *\fIanchorItemPtr\fR; + int \fIselectAnchor\fR; + Tk_3DBorder \fIinsertBorder\fR; + int \fIinsertWidth\fR; + int \fIinsertBorderWidth\fR; + Tk_Item *\fIfocusItemPtr\fR; + int \fIgotFocus\fR; + int \fIcursorOn\fR; +} \fBTk_CanvasTextInfo\fR; +.CE +The \fBselBorder\fR field identifies a Tk_3DBorder that should be +used for drawing the background under selected text. +\fIselBorderWidth\fR gives the width of the raised border around +selected text, in pixels. +\fIselFgColorPtr\fR points to an XColor that describes the foreground +color to be used when drawing selected text. +\fIselItemPtr\fR points to the item that is currently selected, or +NULL if there is no item selected or if the canvas does not have the +selection. +\fIselectFirst\fR and \fIselectLast\fR give the indices of the first +and last selected characters in \fIselItemPtr\fR, as returned by the +\fIindexProc\fR for that item. +\fIanchorItemPtr\fR points to the item that currently has the selection +anchor; this is not necessarily the same as \fIselItemPtr\fR. +\fIselectAnchor\fR is an index that identifies the anchor position +within \fIanchorItemPtr\fR. +\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the +insertion cursor; \fIinsertWidth\fR gives the total width of the +insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the +width of the raised border around the insertion cursor. +\fIfocusItemPtr\fR identifies the item that currently has the input +focus, or NULL if there is no such item. +\fIgotFocus\fR is 1 if the canvas widget has the input focus and +0 otherwise. +\fIcursorOn\fR is 1 if the insertion cursor should be drawn in +\fIfocusItemPtr\fR and 0 if it should not be drawn; this field +is toggled on and off by Tk to make the cursor blink. +.PP +The structure returned by \fBTk_CanvasGetTextInfo\fR +is shared between Tk and the type managers; typically the type manager +calls \fBTk_CanvasGetTextInfo\fR once when an item is created and +then saves the pointer in the item's record. +Tk will update information in the Tk_CanvasTextInfo; for example, +a \fBconfigure\fR widget command might change the \fIselBorder\fR +field, or a \fBselect\fR widget command might change the \fIselectFirst\fR +field, or Tk might change \fIcursorOn\fR in order to make the insertion +cursor flash on and off during successive redisplays. +.PP +Type managers should treat all of the fields of the Tk_CanvasTextInfo +structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR, +\fIselectLast\fR, and \fIselectAnchor\fR. +Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and +\fIselectAnchor\fR to adjust for insertions and deletions in the +item (but only if the item is the current owner of the selection or +anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR). +If all of the selected text in the item is deleted, the item should +set \fIselItemPtr\fR to NULL to indicate that there is no longer a +selection. +.SH KEYWORDS +canvas, focus, insertion cursor, selection, selection anchor, text diff --git a/tk8.6/doc/Clipboard.3 b/tk8.6/doc/Clipboard.3 new file mode 100644 index 0000000..3087777 --- /dev/null +++ b/tk8.6/doc/Clipboard.3 @@ -0,0 +1,77 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) +.sp +int +\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) +.SH ARGUMENTS +.AS Tk_ClipboardClear tkwin +.AP Tcl_Interp *interp in +Interpreter to use for reporting errors. +.AP Tk_Window tkwin in +Window that determines which display's clipboard to manipulate. +.AP Atom target in +Conversion type for this clipboard item; has same meaning as +\fItarget\fR argument to \fBTk_CreateSelHandler\fR. +.AP Atom format in +Representation to use when data is retrieved; has same meaning as +\fIformat\fR argument to \fBTk_CreateSelHandler\fR. +.AP "const char" *buffer in +Null terminated string containing the data to be appended to the clipboard. +.BE +.SH DESCRIPTION +.PP +These two procedures manage the clipboard for Tk. +The clipboard is typically managed by calling \fBTk_ClipboardClear\fR +once, then calling \fBTk_ClipboardAppend\fR to add data for any +number of targets. +.PP +\fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any +data items previously stored on the clipboard in this application. +It normally returns \fBTCL_OK\fR, but if an error occurs it returns +\fBTCL_ERROR\fR and leaves an error message in interpreter +\fIinterp\fR's result. +\fBTk_ClipboardClear\fR must be called before a sequence of +\fBTk_ClipboardAppend\fR calls can be issued. +.PP +\fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard. +The first buffer for a given \fItarget\fR determines the \fIformat\fR +for that \fItarget\fR. +Any successive appends for that \fItarget\fR must have +the same format or an error will be returned. +\fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is +successfully copied onto the clipboard. If the clipboard is not +currently owned by the application, either +because \fBTk_ClipboardClear\fR has not been called or because +ownership of the clipboard has changed since the last call to +\fBTk_ClipboardClear\fR, +\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error +message in the result of interpreter \fIinterp\fR. +.PP +In order to guarantee atomicity, no event handling should occur +between \fBTk_ClipboardClear\fR and the following +\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve +a partially completed clipboard or claim ownership away from +this application). +.PP +\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary +Tcl scripts, as a result of losing the CLIPBOARD selection, so +any calling function should take care to be re-entrant at the point +\fBTk_ClipboardClear\fR is invoked. +.SH KEYWORDS +append, clipboard, clear, format, type diff --git a/tk8.6/doc/ClrSelect.3 b/tk8.6/doc/ClrSelect.3 new file mode 100644 index 0000000..c56f63c --- /dev/null +++ b/tk8.6/doc/ClrSelect.3 @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1992-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ClearSelection \- Deselect a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ClearSelection\fR(\fItkwin, selection\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +The selection will be cleared from the display containing this +window. +.AP Atom selection in +The name of selection to be cleared. +.BE +.SH DESCRIPTION +.PP +\fBTk_ClearSelection\fR cancels the selection specified by the atom +\fIselection\fR for the display containing \fItkwin\fR. +The selection need not be in \fItkwin\fR itself or even in +\fItkwin\fR's application. +If there is a window anywhere on \fItkwin\fR's display that +owns \fIselection\fR, the window will be notified and the +selection will be cleared. +If there is no owner for \fIselection\fR on the display, then the +procedure has no effect. +.SH KEYWORDS +clear, selection diff --git a/tk8.6/doc/ConfigWidg.3 b/tk8.6/doc/ConfigWidg.3 new file mode 100644 index 0000000..92be073 --- /dev/null +++ b/tk8.6/doc/ConfigWidg.3 @@ -0,0 +1,631 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR +.sp +int +\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR +.sp +int +\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR +.sp +\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR +.SH ARGUMENTS +.AS char *widgRec in/out +.AP Tcl_Interp *interp in +Interpreter to use for returning error messages. +.AP Tk_Window tkwin in +Window used to represent widget (needed to set up X resources). +.AP "const Tk_ConfigSpec" *specs in +Pointer to table specifying legal configuration options for this +widget. +.AP int argc in +Number of arguments in \fIargv\fR. +.AP "const char" **argv in +Command-line options for configuring widget. +.AP char *widgRec in/out +Points to widget record structure. Fields in this structure get +modified by \fBTk_ConfigureWidget\fR to hold configuration information. +.AP int flags in +If non-zero, then it specifies an OR-ed combination of flags that +control the processing of configuration information. +\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be +ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to +selectively disable entries in \fIspecs\fR. +.AP "type name" type in +The name of the type of a widget record. +.AP "field name" field in +The name of a field in records of type \fItype\fR. +.AP "const char" *argvName in +The name used on Tcl command lines to refer to a particular option +(e.g. when creating a widget or invoking the \fBconfigure\fR widget +command). If non-NULL, then information is returned only for this +option. If NULL, then information is returned for all available +options. +.AP Display *display in +Display containing widget whose record is being freed; needed in +order to free up resources. +.BE +.SH DESCRIPTION +.PP +Note: \fBTk_ConfigureWidget\fR should be replaced with the new +\fBTcl_Obj\fR based API \fBTk_SetOptions\fR. The old interface is +retained for backward compatibility. +.PP +\fBTk_ConfigureWidget\fR is called to configure various aspects of a +widget, such as colors, fonts, border width, etc. +It is intended as a convenience procedure to reduce the amount +of code that must be written in individual widget managers to +handle configuration information. +It is typically +invoked when widgets are created, and again when the \fBconfigure\fR +command is invoked for a widget. +Although intended primarily for widgets, \fBTk_ConfigureWidget\fR +can be used in other situations where \fIargc-argv\fR information +is to be used to fill in a record structure, such as configuring +graphical elements for a canvas widget or entries of a menu. +.PP +\fBTk_ConfigureWidget\fR processes +a table specifying the configuration options that are supported +(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and +\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR). +It uses the option database and defaults specified in \fIspecs\fR +to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. +\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this +case it does not modify \fIinterp\fR. +If an error +occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will +leave an error message in interpreter \fIinterp\fR's result in the standard Tcl +fashion. +In the event of an error return, some of the fields of \fIwidgRec\fR +could already have been set, if configuration information for them +was successfully processed before the error occurred. +The other fields will be set to reasonable initial values so that +\fBTk_FreeOptions\fR can be called for cleanup. +.PP +The \fIspecs\fR array specifies the kinds of configuration options +expected by the widget. Each of its entries specifies one configuration +option and has the following structure: +.CS +typedef struct { + int \fItype\fR; + const char *\fIargvName\fR; + const char *\fIdbName\fR; + const char *\fIdbClass\fR; + const char *\fIdefValue\fR; + int \fIoffset\fR; + int \fIspecFlags\fR; + const Tk_CustomOption *\fIcustomPtr\fR; +} \fBTk_ConfigSpec\fR; +.CE +The \fItype\fR field indicates what type of configuration option this is +(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for +an integer value). The \fItype\fR field indicates how to use the +value of the option (more on this below). +The \fIargvName\fR field is a string such as +.QW \-font +or +.QW \-bg , +which is compared with the values in \fIargv\fR (if \fIargvName\fR is +NULL it means this is a grouped entry; see \fBGROUPED ENTRIES\fR below). The +\fIdbName\fR and \fIdbClass\fR fields are used to look up a value +for this option in the option database. The \fIdefValue\fR field +specifies a default value for this configuration option if no +value is specified in either \fIargv\fR or the option database. +\fIOffset\fR indicates where in \fIwidgRec\fR to store information +about this option, and \fIspecFlags\fR contains additional information +to control the processing of this configuration option (see FLAGS +below). +The last field, \fIcustomPtr\fR, is only used if \fItype\fR is +\fBTK_CONFIG_CUSTOM\fR; see CUSTOM OPTION TYPES below. +.PP +\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which +(if any) configuration options are specified there. \fIArgv\fR +must contain an even number of fields; the first of each pair +of fields must match the \fIargvName\fR of some entry in \fIspecs\fR +(unique abbreviations are acceptable), +and the second field of the pair contains the value for that +configuration option. If there are entries in \fIspec\fR for which +there were no matching entries in \fIargv\fR, +\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR +fields of the \fIspecs\fR entry to probe the option database; if +a value is found, then it is used as the value for the option. +Finally, if no entry is found in the option database, the +\fIdefValue\fR field of the \fIspecs\fR entry is used as the +value for the configuration option. If the \fIdefValue\fR is +NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in +\fIflags\fR, then there is no default value and this \fIspecs\fR entry +will be ignored if no value is specified in \fIargv\fR or the +option database. +.PP +Once a string value has been determined for a configuration option, +\fBTk_ConfigureWidget\fR translates the string value into a more useful +form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer +if \fItype\fR is \fBTK_CONFIG_INT\fR. This value is then stored in the +record pointed to by \fIwidgRec\fR. This record is assumed to +contain information relevant to the manager of the widget; its exact +type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field +of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store +the information about this configuration option. You should use the +\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for +a description of \fBTk_Offset\fR). The location indicated by +\fIwidgRec\fR and \fIoffset\fR will be referred to as the +.QW target +in the descriptions below. +.PP +The \fItype\fR field of each entry in \fIspecs\fR determines what +to do with the string value of that configuration option. The +legal values for \fItype\fR, and the corresponding actions, are: +.TP +\fBTK_CONFIG_ACTIVE_CURSOR\fR +The value +must be an ASCII string identifying a cursor in a form +suitable for passing to \fBTk_GetCursor\fR. +The value is converted to a \fBTk_Cursor\fR by calling +\fBTk_GetCursor\fR and the result is stored in the target. +In addition, the resulting cursor is made the active cursor +for \fItkwin\fR by calling \fBXDefineCursor\fR. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target and \fItkwin\fR's +active cursor will be set to \fBNone\fR. +If the previous value of the target +was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. +.TP +\fBTK_CONFIG_ANCHOR\fR +The value must be an ASCII string identifying an anchor point in one of the ways +accepted by \fBTk_GetAnchor\fR. +The string is converted to a \fBTk_Anchor\fR by calling +\fBTk_GetAnchor\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_BITMAP\fR +The value must be an ASCII string identifying a bitmap in a form +suitable for passing to \fBTk_GetBitmap\fR. The value is converted +to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result +is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target is set to \fBNone\fR. +If the previous value of the target +was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. +.TP +\fBTK_CONFIG_BOOLEAN\fR +The value must be an ASCII string specifying a boolean value. Any +of the values +.QW true , +.QW yes , +.QW on , +or +.QW 1 , +or an abbreviation of one of these values, means true; +any of the values +.QW false , +.QW no , +.QW off , +or +.QW 0 , +or an abbreviation of one of these values, means false. +The target is expected to be an integer; for true values it will +be set to 1 and for false values it will be set to 0. +.TP +\fBTK_CONFIG_BORDER\fR +The value must be an ASCII string identifying a border color in a form +suitable for passing to \fBTk_Get3DBorder\fR. The value is converted +to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result +is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target +was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. +.TP +\fBTK_CONFIG_CAP_STYLE\fR +The value must be +an ASCII string identifying a cap style in one of the ways +accepted by \fBTk_GetCapStyle\fR. +The string is converted to an integer value corresponding +to the cap style by calling +\fBTk_GetCapStyle\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_COLOR\fR +The value must be an ASCII string identifying a color in a form +suitable for passing to \fBTk_GetColor\fR. The value is converted +to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result +is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to \fBNone\fR. +If the previous value of the target +was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR. +.TP +\fBTK_CONFIG_CURSOR\fR +This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except +that the new cursor is not made the active one for \fItkwin\fR. +.TP +\fBTK_CONFIG_CUSTOM\fR +This option allows applications to define new option types. +The \fIcustomPtr\fR field of the entry points to a structure +defining the new option type. +See the section \fBCUSTOM OPTION TYPES\fR below for details. +.TP +\fBTK_CONFIG_DOUBLE\fR +The value must be an ASCII floating-point number in +the format accepted by \fBstrtol\fR. The string is converted +to a \fBdouble\fR value, and the value is stored in the +target. +.TP +\fBTK_CONFIG_END\fR +Marks the end of the table. The last entry in \fIspecs\fR +must have this type; all of its other fields are ignored and it +will never match any arguments. +.TP +\fBTK_CONFIG_FONT\fR +The value must be an ASCII string identifying a font in a form +suitable for passing to \fBTk_GetFont\fR. The value is converted +to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result +is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target +was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR. +.TP +\fBTK_CONFIG_INT\fR +The value must be an ASCII integer string +in the format accepted by \fBstrtol\fR (e.g. +.QW 0 +and +.QW 0x +prefixes may be used to specify octal or hexadecimal +numbers, respectively). The string is converted to an integer +value and the integer is stored in the target. +.TP +\fBTK_CONFIG_JOIN_STYLE\fR +The value must be +an ASCII string identifying a join style in one of the ways +accepted by \fBTk_GetJoinStyle\fR. +The string is converted to an integer value corresponding +to the join style by calling +\fBTk_GetJoinStyle\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_JUSTIFY\fR +The value must be +an ASCII string identifying a justification method in one of the +ways accepted by \fBTk_GetJustify\fR. +The string is converted to a \fBTk_Justify\fR by calling +\fBTk_GetJustify\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_MM\fR +The value must specify a screen distance in one of the forms acceptable +to \fBTk_GetScreenMM\fR. +The string is converted to double-precision floating-point distance +in millimeters and the value is stored in the target. +.TP +\fBTK_CONFIG_PIXELS\fR +The value must specify screen units in one of the forms acceptable +to \fBTk_GetPixels\fR. +The string is converted to an integer distance in pixels and the +value is stored in the target. +.TP +\fBTK_CONFIG_RELIEF\fR +The value must be an ASCII string identifying a relief in a form +suitable for passing to \fBTk_GetRelief\fR. The value is converted +to an integer relief value by calling \fBTk_GetRelief\fR and the result +is stored in the target. +.TP +\fBTK_CONFIG_STRING\fR +A copy +of the value is made by allocating memory space with +\fBTcl_Alloc\fR and copying the value into the dynamically-allocated +space. A pointer to the new string is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target was not NULL, then it is +freed by passing it to \fBTcl_Free\fR. +.TP +\fBTK_CONFIG_SYNONYM\fR +This \fItype\fR value identifies special entries in \fIspecs\fR that +are synonyms for other entries. If an \fIargv\fR value matches the +\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used +directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR +for another entry whose \fIargvName\fR is the same as the \fIdbName\fR +field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just +as if its \fIargvName\fR had matched the \fIargv\fR value. The +synonym mechanism allows multiple \fIargv\fR values to be used for +a single configuration option, such as +.QW \-background +and +.QW \-bg . +.TP +\fBTK_CONFIG_UID\fR +The value is translated to a \fBTk_Uid\fR +(by passing it to \fBTk_GetUid\fR). The resulting value +is stored in the target. +If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value +is an empty string then the target will be set to NULL. +.TP +\fBTK_CONFIG_WINDOW\fR +The value must be a window path name. It is translated to a +\fBTk_Window\fR token and the token is stored in the target. +.SH "GROUPED ENTRIES" +.PP +In some cases it is useful to generate multiple resources from +a single configuration value. For example, a color name might +be used both to generate the background color for a widget (using +\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the +widget (using \fBTK_CONFIG_BORDER\fR). In cases like this it is possible +to specify that several consecutive entries in \fIspecs\fR are to +be treated as a group. The first entry is used to determine a value +(using its \fIargvName\fR, \fIdbName\fR, +\fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed +several times (one for each entry in the group), generating multiple +different resources and modifying multiple targets within \fIwidgRec\fR. +Each of the entries after the first must have a NULL value in its +\fIargvName\fR field; this indicates that the entry is to be grouped +with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR +fields are used from these follow-on entries. +.SH "FLAGS" +.PP +The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used +in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR +to provide additional control over the processing of configuration +options. These values are used in three different ways as +described below. +.PP +First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has +the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0), +then the option database and +\fIdefValue\fR fields are not used. In this case, if an entry in +\fIspecs\fR does not match a field in \fIargv\fR then nothing happens: +the corresponding target is not modified. This feature is useful +when the goal is to modify certain configuration options while +leaving others in their current state, such as when a \fBconfigure\fR +widget command is being processed. +.PP +Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used +to control the processing of that entry. Each \fIspecFlags\fR +field may consists of an OR-ed combination of the following values: +.TP +\fBTK_CONFIG_COLOR_ONLY\fR +If this bit is set then the entry will only be considered if the +display for \fItkwin\fR has more than one bit plane. If the display +is monochromatic then this \fIspecs\fR entry will be ignored. +.TP +\fBTK_CONFIG_MONO_ONLY\fR +If this bit is set then the entry will only be considered if the +display for \fItkwin\fR has exactly one bit plane. If the display +is not monochromatic then this \fIspecs\fR entry will be ignored. +.TP +\fBTK_CONFIG_NULL_OK\fR +This bit is only relevant for some types of entries (see the +descriptions of the various entry types above). +If this bit is set, it indicates that an empty string value +for the field is acceptable and if it occurs then the +target should be set to NULL or \fBNone\fR, depending +on the type of the target. +This flag is typically used to allow a +feature to be turned off entirely, e.g. set a cursor value to +\fBNone\fR so that a window simply inherits its parent's cursor. +If this bit is not set then empty strings are processed as strings, +which generally results in an error. +.TP +\fBTK_CONFIG_DONT_SET_DEFAULT\fR +If this bit is one, it means that the \fIdefValue\fR field of the +entry should only be used for returning the default value in +\fBTk_ConfigureInfo\fR. +In calls to \fBTk_ConfigureWidget\fR no default will be supplied +for entries with this flag set; it is assumed that the +caller has already supplied a default value in the target location. +This flag provides a performance optimization where it is expensive +to process the default string: the client can compute the default +once, save the value, and provide it before calling +\fBTk_ConfigureWidget\fR. +.TP +\fBTK_CONFIG_OPTION_SPECIFIED\fR +This bit is +deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR +so that callers could detect what entries were specified in +\fIargv\fR, but it was removed because it was inherently +thread-unsafe. Code that wishes to detect what options were specified +should use \fBTk_SetOptions\fR instead. +.PP +The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically +used to specify different default values for +monochrome and color displays. This is done by creating two +entries in \fIspecs\fR that are identical except for their +\fIdefValue\fR and \fIspecFlags\fR fields. One entry should have +the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the +default value for monochrome displays in its \fIdefValue\fR; the +other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in +its \fIspecFlags\fR and the appropriate \fIdefValue\fR for +color displays. +.PP +Third, it is possible to use \fIflags\fR and \fIspecFlags\fR +together to selectively disable some entries. This feature is +not needed very often. It is useful in cases where several +similar kinds of widgets are implemented in one place. It allows +a single \fIspecs\fR table to be created with all the configuration +options for all the widget types. When processing a particular +widget type, only entries relevant to that type will be used. This +effect is achieved by setting the high-order bits (those in positions +equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR +values or in \fIflags\fR. In order for a particular entry in +\fIspecs\fR to be used, its high-order bits must match exactly +the high-order bits of the \fIflags\fR value passed to +\fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used +for N different widget types, then N of the high-order bits will +be used. Each \fIspecs\fR entry will have one of more of those +bits set in its \fIspecFlags\fR field to indicate the widget types +for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, +\fIflags\fR will have a single one of these bits set to select the +entries for the desired widget type. For a working example of +this feature, see the code in tkButton.c. +.SH TK_OFFSET +.PP +The \fBTk_Offset\fR macro is provided as a safe way of generating +the \fIoffset\fR values for entries in Tk_ConfigSpec structures. +It takes two arguments: the name of a type of record, and the +name of a field in that record. It returns the byte offset of +the named field in records of the given type. +.SH TK_CONFIGUREINFO +.PP +The \fBTk_ConfigureInfo\fR procedure may be used to obtain +information about one or all of the options for a given widget. +Given a token for a window (\fItkwin\fR), a table describing the +configuration options for a class of widgets (\fIspecs\fR), a +pointer to a widget record containing the current information for +a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, +\fBTk_ConfigureInfo\fR generates a string describing all of the +configuration options for the window. The string is placed +in interpreter \fIinterp\fR's result. Under normal circumstances +it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR +and the interpreter's result will contain an error message. +.PP +If \fIargvName\fR is NULL, then the value left in +the interpreter's result by \fBTk_ConfigureInfo\fR +consists of a list of one or more entries, each of which describes +one configuration option (i.e. one entry in \fIspecs\fR). Each +entry in the list will contain either two or five values. If the +corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then +the list will contain two values: the \fIargvName\fR for the entry +and the \fIdbName\fR (synonym name). Otherwise the list will contain +five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, +and current value. The current value is computed from the appropriate +field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. +.PP +If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, +then it indicates a single option, and information is returned only +for that option. The string placed in the interpreter's result will be +a list containing two or five values as described above; this will +be identical to the corresponding sublist that would have been returned +if \fIargvName\fR had been NULL. +.PP +The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict +the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. +.SH TK_CONFIGUREVALUE +.PP +\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; +instead of returning a list of values, it just returns the current value +of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). +The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is +normally returned as the procedure's result. +If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is +not a valid option name), \fBTCL_ERROR\fR is returned and an error message +is left in the interpreter's result. +This procedure is typically called to implement \fBcget\fR widget +commands. +.SH TK_FREEOPTIONS +.PP +The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup +to release all of the resources associated with configuration options. +It scans through \fIspecs\fR and for each entry corresponding to a +resource that must be explicitly freed (e.g. those with +type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record. +If the field in the widget record does not refer to a resource (e.g. +it contains a null pointer) then no resource is freed for that +entry. +After freeing a resource, \fBTk_FreeOptions\fR sets the +corresponding field of the widget record to null. +.SH "CUSTOM OPTION TYPES" +.PP +Applications can extend the built-in configuration types with additional +configuration types by writing procedures to parse and print options +of the a type and creating a structure pointing to those procedures: +.CS +typedef struct Tk_CustomOption { + Tk_OptionParseProc *\fIparseProc\fR; + Tk_OptionPrintProc *\fIprintProc\fR; + ClientData \fIclientData\fR; +} \fBTk_CustomOption\fR; + +typedef int \fBTk_OptionParseProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tk_Window \fItkwin\fR, + char *\fIvalue\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR); + +typedef const char *\fBTk_OptionPrintProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR, + Tcl_FreeProc **\fIfreeProcPtr\fR); +.CE +The Tk_CustomOption structure contains three fields, which are pointers +to the two procedures and a \fIclientData\fR value to be passed to those +procedures when they are invoked. The \fIclientData\fR value typically +points to a structure containing information that is needed by the +procedures when they are parsing and printing options. +.PP +The \fIparseProc\fR procedure is invoked by +\fBTk_ConfigureWidget\fR to parse a string and store the resulting +value in the widget record. +The \fIclientData\fR argument is a copy of the \fIclientData\fR +field in the Tk_CustomOption structure. +The \fIinterp\fR argument points to a Tcl interpreter used for +error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument +to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string +describing the value for the option; it could have been specified +explicitly in the call to \fBTk_ConfigureWidget\fR or it could +come from the option database or a default. +\fIValue\fR will never be a null pointer but it may point to +an empty string. +\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to +\fBTk_ConfigureWidget\fR; it points to the start of the widget +record to modify. +The last argument, \fIoffset\fR, gives the offset in bytes from the start +of the widget record to the location where the option value is to +be placed. The procedure should translate the string to whatever +form is appropriate for the option and store the value in the widget +record. It should normally return \fBTCL_OK\fR, but if an error occurs +in translating the string to a value then it should return \fBTCL_ERROR\fR +and store an error message in interpreter \fIinterp\fR's result. +.PP +The \fIprintProc\fR procedure is called +by \fBTk_ConfigureInfo\fR to produce a string value describing an +existing option. +Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR +arguments all have the same meaning as for Tk_OptionParseProc +procedures. +The \fIprintProc\fR procedure should examine the option whose value +is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing +that option, and return a pointer to the string. +If the string is stored in dynamically-allocated memory, then +the procedure must set \fI*freeProcPtr\fR to the address of +a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR +will call this procedure when it is finished with the string. +If the result string is stored in static memory then \fIprintProc\fR +need not do anything with the \fIfreeProcPtr\fR argument. +.PP +Once \fIparseProc\fR and \fIprintProc\fR have been defined and a +Tk_CustomOption structure has been created for them, options of this +new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR +fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point +to the Tk_CustomOption structure. +.SH EXAMPLES +.PP +Although the explanation of \fBTk_ConfigureWidget\fR is fairly +complicated, its actual use is pretty straightforward. +The easiest way to get started is to copy the code +from an existing widget. +The library implementation of frames +(tkFrame.c) has a simple configuration table, and the library +implementation of buttons (tkButton.c) has a much more complex +table that uses many of the fancy \fIspecFlags\fR mechanisms. +.SH "SEE ALSO" +Tk_SetOptions(3) +.SH KEYWORDS +anchor, bitmap, boolean, border, cap style, color, configuration options, +cursor, custom, double, font, integer, join style, justify, millimeters, +pixels, relief, synonym, uid diff --git a/tk8.6/doc/ConfigWind.3 b/tk8.6/doc/ConfigWind.3 new file mode 100644 index 0000000..7c7adab --- /dev/null +++ b/tk8.6/doc/ConfigWind.3 @@ -0,0 +1,147 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR) +.sp +\fBTk_MoveWindow\fR(\fItkwin, x, y\fR) +.sp +\fBTk_ResizeWindow\fR(\fItkwin, width, height\fR) +.sp +\fBTk_MoveResizeWindow\fR(\fItkwin, x, y, width, height\fR) +.sp +\fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR) +.sp +\fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR) +.sp +\fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR) +.sp +\fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR) +.sp +\fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR) +.sp +\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) +.sp +\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) +.sp +\fBTk_DefineCursor\fR(\fItkwin, cursor\fR) +.sp +\fBTk_UndefineCursor\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS XSetWindowAttributes borderWidth +.AP Tk_Window tkwin in +Token for window. +.AP "unsigned int" valueMask in +OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, +indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. +.AP XWindowChanges *valuePtr in +Points to a structure containing new values for the configuration +parameters selected by \fIvalueMask\fR. Fields not selected +by \fIvalueMask\fR are ignored. +.AP int x in +New x-coordinate for \fItkwin\fR's top left pixel (including +border, if any) within tkwin's parent. +.AP int y in +New y-coordinate for \fItkwin\fR's top left pixel (including +border, if any) within tkwin's parent. +.AP "int" width in +New width for \fItkwin\fR (interior, not including border). +.AP "int" height in +New height for \fItkwin\fR (interior, not including border). +.AP "int" borderWidth in +New width for \fItkwin\fR's border. +.AP XSetWindowAttributes *attsPtr in +Points to a structure containing new values for the attributes +given by the \fIvalueMask\fR argument. Attributes not selected +by \fIvalueMask\fR are ignored. +.AP "unsigned long" pixel in +New background or border color for window. +.AP Pixmap pixmap in +New pixmap to use for background or border of \fItkwin\fR. WARNING: +cannot necessarily be deleted immediately, as for Xlib calls. See +note below. +.AP Colormap colormap in +New colormap to use for \fItkwin\fR. +.AP Tk_Cursor cursor in +New cursor to use for \fItkwin\fR. If \fBNone\fR is specified, then +\fItkwin\fR will not have its own cursor; it will use the cursor +of its parent. +.BE +.SH DESCRIPTION +.PP +These procedures are analogous to the X library procedures +with similar names, such as \fBXConfigureWindow\fR. Each +one of the above procedures calls the corresponding X procedure +and also saves the configuration information in Tk's local +structure for the window. This allows the information to +be retrieved quickly by the application (using macros such +as \fBTk_X\fR and \fBTk_Height\fR) without having to contact +the X server. In addition, if no X window has actually been +created for \fItkwin\fR yet, these procedures do not issue +X operations or cause event handlers to be invoked; they save +the information in Tk's local +structure for the window; when the window is created later, +the saved information will be used to configure the window. +.PP +See the X library documentation for details on what these +procedures do and how they use their arguments. +.PP +In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR, +\fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and +\fBTk_SetWindowBorderWidth\fR, +if \fItkwin\fR is an internal window then event handlers interested +in configure events are invoked immediately, before the procedure +returns. If \fItkwin\fR is a top-level window +then the event handlers will be invoked later, after X has seen +the request and returned an event for it. +.PP +Applications using Tk should never call procedures like +\fBXConfigureWindow\fR directly; they should always use the +corresponding Tk procedures. +.PP +The size and location of a window should only be modified by the +appropriate geometry manager for that window and never by a window +itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level +window). +.PP +You may not use \fBTk_ConfigureWindow\fR to change the +stacking order of a window (\fIvalueMask\fR may not contain the +\fBCWSibling\fR or \fBCWStackMode\fR bits). +To change the stacking order, use the procedure \fBTk_RestackWindow\fR. +.PP +The procedure \fBTk_SetWindowColormap\fR will automatically add +\fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its +nearest top-level ancestor if the new colormap is different from +that of \fItkwin\fR's parent and \fItkwin\fR is not already in +the \fBTK_COLORMAP_WINDOWS\fR property. +.SH BUGS +.PP +\fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR +differ slightly from their Xlib counterparts in that the \fIpixmap\fR +argument may not necessarily be deleted immediately after calling +one of these procedures. This is because \fItkwin\fR's window +may not exist yet at the time of the call, in which case \fIpixmap\fR +is merely saved and used later when \fItkwin\fR's window is actually +created. If you wish to delete \fIpixmap\fR, then call +\fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists +and \fIpixmap\fR has been passed to the X server. +.PP +A similar problem occurs for the \fIcursor\fR argument passed to +\fBTk_DefineCursor\fR. The solution is the same as for pixmaps above: +call \fBTk_MakeWindowExist\fR before freeing the cursor. +.SH "SEE ALSO" +Tk_MoveToplevelWindow, Tk_RestackWindow +.SH KEYWORDS +attributes, border, color, configure, height, pixel, pixmap, width, window, x, y diff --git a/tk8.6/doc/CoordToWin.3 b/tk8.6/doc/CoordToWin.3 new file mode 100644 index 0000000..5fe96a6 --- /dev/null +++ b/tk8.6/doc/CoordToWin.3 @@ -0,0 +1,47 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CoordsToWindow \- Find window containing a point +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP int rootX in +X-coordinate (in root window coordinates). +.AP int rootY in +Y-coordinate (in root window coordinates). +.AP Tk_Window tkwin in +Token for window that identifies application. +.BE +.SH DESCRIPTION +.PP +\fBTk_CoordsToWindow\fR locates the window that contains a given point. +The point is specified in root coordinates with \fIrootX\fR and +\fIrootY\fR (if a virtual-root window manager is in use then +\fIrootX\fR and \fIrootY\fR are in the coordinate system of the +virtual root window). +The return value from the procedure is a token for the window that +contains the given point. +If the point is not in any window, or if the containing window +is not in the same application as \fItkwin\fR, then NULL is +returned. +.PP +The containing window is decided using the same rules that determine +which window contains the mouse cursor: if a parent and a child both +contain the point then the child gets preference, and if two siblings +both contain the point then the highest one in the stacking order +(i.e. the one that's visible on the screen) gets preference. +.SH KEYWORDS +containing, coordinates, root window diff --git a/tk8.6/doc/CrtCmHdlr.3 b/tk8.6/doc/CrtCmHdlr.3 new file mode 100644 index 0000000..98b93f7 --- /dev/null +++ b/tk8.6/doc/CrtCmHdlr.3 @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 2000 Ajuba Solutions. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateClientMessageHandler\fR(\fIproc\fR) +.sp +\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR) +.SH ARGUMENTS +.AP Tk_ClientMessageProc *proc in +Procedure to invoke whenever a ClientMessage X event occurs on any display. +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked +in the future whenever a ClientMessage X event occurs that is not handled by +\fBWM_PROTOCOL\fR. \fBTk_CreateClientMessageHandler\fR is intended for use +by applications which need to watch X ClientMessage events, such as drag and +drop applications. +.PP +The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; +this mechanism only works in programs that dispatch events +through \fBTk_HandleEvent\fR (or through other Tk procedures that +call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or +\fBTk_MainLoop\fR). +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_ClientMessageProc\fR: +.CS +typedef int \fBTk_ClientMessageProc\fR( + Tk_Window \fItkwin\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is +associated with this event. \fIEventPtr\fR is a pointer to the X event. +.PP +Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR, +the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR. +The return value from \fIproc\fR is normally 0. +A non-zero return value indicates that the event is not to be handled +further; that is, \fIproc\fR has done all processing that is to be +allowed for the event. +.PP +If there are multiple ClientMessage event handlers, each one is called +for each event, in the order in which they were established. +.PP +\fBTk_DeleteClientMessageHandler\fR may be called to delete a +previously-created ClientMessage event handler: it deletes each handler it +finds that matches the \fIproc\fR argument. If no such handler exists, +then \fBTk_DeleteClientMessageHandler\fR returns without doing anything. +Although Tk supports it, it's probably a bad idea to have more than one +callback with the same \fIproc\fR argument. +.SH KEYWORDS +bind, callback, event, handler diff --git a/tk8.6/doc/CrtConsoleChan.3 b/tk8.6/doc/CrtConsoleChan.3 new file mode 100644 index 0000000..7fd8a6a --- /dev/null +++ b/tk8.6/doc/CrtConsoleChan.3 @@ -0,0 +1,44 @@ +'\" +'\" Copyright (c) 2007 ActiveState Software Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_InitConsoleChannels \- Install the console channels as standard channels +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_InitConsoleChannels\fR(\fIinterp\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp in +.AP Tcl_Interp *interp in +Interpreter in which the console channels are created. +.BE +.SH DESCRIPTION +.PP +\fBTk_InitConsoleChannels\fR is invoked to create a set of console +channels and install them as the standard channels. All I/O on these +channels will be discarded until \fBTk_CreateConsoleWindow\fR is +called to attach the console to a text widget. +.PP +This function is for use by shell applications based on Tk, like +\fBwish\fR, on platforms which have no standard channels in graphical +mode, like Win32. +.PP +The \fIinterp\fR argument is the interpreter in which to create and +install the console channels. +.PP +\fBNOTE:\fR If this function is used it has to be called before the +first call to \fBTcl_RegisterChannel\fR, directly, or indirectly +through other channel functions. Because otherwise the standard +channels will be already initialized to the system defaults, which will +be nonsensical for the case \fBTk_InitConsoleChannels\fR is for. +.SH "SEE ALSO" +console(n) +.SH KEYWORDS +standard channels, console diff --git a/tk8.6/doc/CrtErrHdlr.3 b/tk8.6/doc/CrtErrHdlr.3 new file mode 100644 index 0000000..e506220 --- /dev/null +++ b/tk8.6/doc/CrtErrHdlr.3 @@ -0,0 +1,140 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_ErrorHandler +\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) +.sp +\fBTk_DeleteErrorHandler\fR(\fIhandler\fR) +.SH ARGUMENTS +.AS "Tk_ErrorHandler" clientData +.AP Display *display in +Display whose errors are to be handled. +.AP int error in +Match only error events with this value in the \fIerror_code\fR +field. If \-1, then match any \fIerror_code\fR value. +.AP int request in +Match only error events with this value in the \fIrequest_code\fR +field. If \-1, then match any \fIrequest_code\fR value. +.AP int minor in +Match only error events with this value in the \fIminor_code\fR +field. If \-1, then match any \fIminor_code\fR value. +.AP Tk_ErrorProc *proc in +Procedure to invoke whenever an error event is received for +\fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR. +NULL means ignore any matching errors. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.AP Tk_ErrorHandler handler in +Token for error handler to delete (return value from a previous +call to \fBTk_CreateErrorHandler\fR). +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateErrorHandler\fR arranges for a particular procedure +(\fIproc\fR) to be called whenever certain protocol errors occur on a +particular display (\fIdisplay\fR). Protocol errors occur when +the X protocol is used incorrectly, such as attempting to map a window +that does not exist. See the Xlib documentation for \fBXSetErrorHandler\fR +for more information on the kinds of errors that can occur. +For \fIproc\fR to be invoked +to handle a particular error, five things must occur: +.IP [1] +The error must pertain to \fIdisplay\fR. +.IP [2] +Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR +must have been \-1, or the \fIerror\fR argument must match +the \fIerror_code\fR field from the error event. +.IP [3] +Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR +must have been \-1, or the \fIrequest\fR argument must match +the \fIrequest_code\fR field from the error event. +.IP [4] +Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR +must have been \-1, or the \fIminor\fR argument must match +the \fIminor_code\fR field from the error event. +.IP [5] +The protocol request to which the error pertains must have been +made when the handler was active (see below for more information). +.PP +\fIProc\fR should have arguments and result that match the +following type: +.CS +typedef int \fBTk_ErrorProc\fR( + ClientData \fIclientData\fR, + XErrorEvent *\fIerrEventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTcl_CreateErrorHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information that is +needed to deal with the error. \fIErrEventPtr\fR is +a pointer to the X error event. +The procedure \fIproc\fR should return an integer value. If it +returns 0 it means that \fIproc\fR handled the error completely and there +is no need to take any other action for the error. If it returns +non-zero it means \fIproc\fR was unable to handle the error. +.PP +If a value of NULL is specified for \fIproc\fR, all matching errors +will be ignored: this will produce the same result as if a procedure +had been specified that always returns 0. +.PP +If more than more than one handler matches a particular error, then +they are invoked in turn. The handlers will be invoked in reverse +order of creation: most recently declared handler first. +If any handler returns 0, then subsequent (older) handlers will +not be invoked. If no handler returns 0, then Tk invokes X's +default error handler, which prints an error message and aborts the +program. If you wish to have a default handler that deals with errors +that no other handler can deal with, then declare it first. +.PP +The X documentation states that +.QW "the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events." +This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR; +disobey it at your own risk. +.PP +\fBTk_DeleteErrorHandler\fR may be called to delete a +previously-created error handler. The \fIhandler\fR argument +identifies the error handler, and should be a value returned by +a previous call to \fBTk_CreateEventHandler\fR. +.PP +A particular error handler applies to errors resulting +from protocol requests generated between +the call to \fBTk_CreateErrorHandler\fR and the call to +\fBTk_DeleteErrorHandler\fR. However, the actual callback +to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR +call, due to buffering in the client and server. +If an error event pertains to +a protocol request made just before calling \fBTk_DeleteErrorHandler\fR, +then the error event may not have been processed +before the \fBTk_DeleteErrorHandler\fR +call. When this situation arises, Tk will save information about +the handler and +invoke the handler's \fIproc\fR later when the error event +finally arrives. +If an application wishes to delete an error handler and know +for certain that all relevant errors have been processed, +it should first call \fBTk_DeleteErrorHandler\fR and then +call \fBXSync\fR; this will flush out any buffered requests and errors, +but will result in a performance penalty because +it requires communication to and from the X server. After the +\fBXSync\fR call Tk is guaranteed not to call any error +handlers deleted before the \fBXSync\fR call. +.PP +For the Tk error handling mechanism to work properly, it is essential +that application code never calls \fBXSetErrorHandler\fR directly; +applications should use only \fBTk_CreateErrorHandler\fR. +.SH KEYWORDS +callback, error, event, handler diff --git a/tk8.6/doc/CrtGenHdlr.3 b/tk8.6/doc/CrtGenHdlr.3 new file mode 100644 index 0000000..c2161d1 --- /dev/null +++ b/tk8.6/doc/CrtGenHdlr.3 @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1992-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) +.sp +\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) +.SH ARGUMENTS +.AS "Tk_GenericProc" clientData +.AP Tk_GenericProc *proc in +Procedure to invoke whenever any X event occurs on any display. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be +invoked in the future whenever any X event occurs. This mechanism is +\fInot\fR intended for dispatching X events on windows managed by Tk +(you should use \fBTk_CreateEventHandler\fR for this purpose). +\fBTk_CreateGenericHandler\fR is intended for other purposes, such +as tracing X events, monitoring events on windows not owned by Tk, +accessing X-related libraries that were not originally designed for +use with Tk, and so on. +.PP +The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; +this mechanism only works in programs that dispatch events +through \fBTk_HandleEvent\fR (or through other Tk procedures that +call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or +\fBTk_MainLoop\fR). +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_GenericProc\fR: +.CS +typedef int \fBTk_GenericProc\fR( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTk_CreateGenericHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +how to handle events. +\fIEventPtr\fR is a pointer to the X event. +.PP +Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR +is called. The return value from \fIproc\fR is normally 0. +A non-zero return value indicates that the event is not to be handled +further; that is, \fIproc\fR has done all processing that is to be +allowed for the event. +.PP +If there are multiple generic event handlers, each one is called +for each event, in the order in which they were established. +.PP +\fBTk_DeleteGenericHandler\fR may be called to delete a +previously-created generic event handler: it deletes each handler +it finds that matches the \fIproc\fR and \fIclientData\fR arguments. If +no such handler exists, then \fBTk_DeleteGenericHandler\fR returns +without doing anything. Although Tk supports it, it's probably +a bad idea to have more than one callback with the same +\fIproc\fR and \fIclientData\fR arguments. +.PP +Establishing a generic event handler does nothing to ensure that the +process will actually receive the X events that the handler wants to +process. +For example, it is the caller's responsibility to invoke +\fBXSelectInput\fR to select the desired events, if that is necessary. +.SH KEYWORDS +bind, callback, event, handler diff --git a/tk8.6/doc/CrtImgType.3 b/tk8.6/doc/CrtImgType.3 new file mode 100644 index 0000000..cbbc11e --- /dev/null +++ b/tk8.6/doc/CrtImgType.3 @@ -0,0 +1,283 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateImageType\fR(\fItypePtr\fR) +.sp +ClientData +\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) +.sp +\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR) +.SH ARGUMENTS +.AS "const Tk_ImageType" *typePtrPtr +.AP "const Tk_ImageType" *typePtr in +Structure that defines the new type of image. +For Tk 8.4 and earlier this must be static: a +pointer to this structure is retained by the image code. +In Tk 8.5, this limitation was relaxed. +.AP Tcl_Interp *interp in +Interpreter in which image was created. +.AP "const char" *name in +Name of existing image. +.AP Tk_ImageType **typePtrPtr out +Points to word in which to store a pointer to type information for +the given image, if it exists. +.AP int argc in +Number of arguments +.AP char ***argvPtr in/out +Pointer to argument list +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateImageType\fR is invoked to define a new kind of image. +An image type corresponds to a particular value of the \fItype\fR +argument for the \fBimage create\fR command. There may exist +any number of different image types, and new types may be defined +dynamically by calling \fBTk_CreateImageType\fR. +For example, there might be one type for 2-color bitmaps, +another for multi-color images, another for dithered images, +another for video, and so on. +.PP +The code that implements a new image type is called an +\fIimage manager\fR. +It consists of a collection of procedures plus three different +kinds of data structures. +The first data structure is a Tk_ImageType structure, which contains +the name of the image type and pointers to five procedures provided +by the image manager to deal with images of this type: +.CS +typedef struct Tk_ImageType { + const char *\fIname\fR; + Tk_ImageCreateProc *\fIcreateProc\fR; + Tk_ImageGetProc *\fIgetProc\fR; + Tk_ImageDisplayProc *\fIdisplayProc\fR; + Tk_ImageFreeProc *\fIfreeProc\fR; + Tk_ImageDeleteProc *\fIdeleteProc\fR; +} \fBTk_ImageType\fR; +.CE +The fields of this structure will be described in later subsections +of this entry. +.PP +The second major data structure manipulated by an image manager +is called an \fIimage master\fR; it contains overall information +about a particular image, such as the values of the configuration +options specified in an \fBimage create\fR command. +There will usually be one of these structures for each +invocation of the \fBimage create\fR command. +.PP +The third data structure related to images is an \fIimage instance\fR. +There will usually be one of these structures for each usage of an +image in a particular widget. +It is possible for a single image to appear simultaneously +in multiple widgets, or even multiple times in the same widget. +Furthermore, different instances may be on different screens +or displays. +The image instance data structure describes things that may +vary from instance to instance, such as colors and graphics +contexts for redisplay. +There is usually one instance structure for each \fB\-image\fR +option specified for a widget or canvas item. +.PP +The following subsections describe the fields of a Tk_ImageType +in more detail. +.SS NAME +.PP +\fItypePtr->name\fR provides a name for the image type. +Once \fBTk_CreateImageType\fR returns, this name may be used +in \fBimage create\fR commands to create images of the new +type. +If there already existed an image type by this name then +the new image type replaces the old one. +.SS CREATEPROC +.PP +\fItypePtr->createProc\fR provides the address of a procedure for +Tk to call whenever \fBimage create\fR is invoked to create +an image of the new type. +\fItypePtr->createProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIname\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + const Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the \fBimage\fR +command was invoked, and \fIname\fR is the name for the new image, +which was either specified explicitly in the \fBimage\fR command +or generated automatically by the \fBimage\fR command. +The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration +options for the new image (everything after the name argument to +\fBimage\fR). +The \fImaster\fR argument is a token that refers to Tk's information +about this image; the image manager must return this token to +Tk when invoking the \fBTk_ImageChanged\fR procedure. +Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR +and create an image master data structure for the new image. +\fIcreateProc\fR may store an arbitrary one-word value at +*\fImasterDataPtr\fR, which will be passed back to the +image manager when other callbacks are invoked. +Typically the value is a pointer to the master data +structure for the image. +.PP +If \fIcreateProc\fR encounters an error, it should leave an error +message in the interpreter result and return \fBTCL_ERROR\fR; otherwise +it should return \fBTCL_OK\fR. +.PP +\fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the +size of the image and request an initial redisplay. +.SS GETPROC +.PP +\fItypePtr->getProc\fR is invoked by Tk whenever a widget +calls \fBTk_GetImage\fR to use a particular image. +This procedure must match the following prototype: +.CS +typedef ClientData \fBTk_ImageGetProc\fR( + Tk_Window \fItkwin\fR, + ClientData \fImasterData\fR); +.CE +The \fItkwin\fR argument identifies the window in which the +image will be used and \fImasterData\fR is the value +returned by \fIcreateProc\fR when the image master was created. +\fIgetProc\fR will usually create a data structure for the new +instance, including such things as the resources needed to +display the image in the given window. +\fIgetProc\fR returns a one-word token for the instance, which +is typically the address of the instance data structure. +Tk will pass this value back to the image manager when invoking +its \fIdisplayProc\fR and \fIfreeProc\fR procedures. +.SS DISPLAYPROC +.PP +\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs +to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). +\fIdisplayProc\fR must match the following prototype: +.CS +typedef void \fBTk_ImageDisplayProc\fR( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR, + Drawable \fIdrawable\fR, + int \fIimageX\fR, + int \fIimageY\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIdrawableX\fR, + int \fIdrawableY\fR); +.CE +The \fIinstanceData\fR will be the same as the value returned by +\fIgetProc\fR when the instance was created. +\fIdisplay\fR and \fIdrawable\fR indicate where to display the +image; \fIdrawable\fR may be a pixmap rather than +the window specified to \fIgetProc\fR (this is usually the case, +since most widgets double-buffer their redisplay to get smoother +visual effects). +\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR +identify the region of the image that must be redisplayed. +This region will always be within the size of the image +as specified in the most recent call to \fBTk_ImageChanged\fR. +\fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR +the image should be displayed; \fIdisplayProc\fR should display +the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) +in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. +.SS FREEPROC +.PP +\fItypePtr->freeProc\fR contains the address of a procedure that +Tk will invoke when an image instance is released (i.e., when +\fBTk_FreeImage\fR is invoked). +This can happen, for example, when a widget is deleted or a image item +in a canvas is deleted, or when the image displayed in a widget or +canvas item is changed. +\fIfreeProc\fR must match the following prototype: +.CS +typedef void \fBTk_ImageFreeProc\fR( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR); +.CE +The \fIinstanceData\fR will be the same as the value returned by +\fIgetProc\fR when the instance was created, and \fIdisplay\fR +is the display containing the window for the instance. +\fIfreeProc\fR should release any resources associated with the +image instance, since the instance will never be used again. +.SS DELETEPROC +.PP +\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an +image is being deleted (i.e. when the \fBimage delete\fR command +is invoked). +Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for +each of the image's instances. +\fIdeleteProc\fR must match the following prototype: +.CS +typedef void \fBTk_ImageDeleteProc\fR( + ClientData \fImasterData\fR); +.CE +The \fImasterData\fR argument will be the same as the value +stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the +image was created. +\fIdeleteProc\fR should release any resources associated with +the image. +.SH TK_GETIMAGEMASTERDATA +.PP +The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve +information about an image. For example, an image manager can use this +procedure to locate its image master data for an image. +If there exists an image named \fIname\fR +in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is +filled in with type information for the image (the \fItypePtr\fR value +passed to \fBTk_CreateImageType\fR when the image type was registered) +and the return value is the ClientData value returned by the +\fIcreateProc\fR when the image was created (this is typically a +pointer to the image master data structure). If no such image exists +then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. +.SH "LEGACY INTERFACE SUPPORT" +.PP +In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR +was incompatibly different, with the following prototype: +.CS +typedef int \fBTk_ImageCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIargc\fR, + char **\fIargv\fR, + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); +.CE +Legacy programs and libraries dating from those days may still +contain code that defines extended Tk image types using the old +interface. The Tk header file will still support this legacy +interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR +defined. +.PP +When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may +see the routine \fBTk_InitImageArgs\fR in use. This was a migration +tool used to create stub-enabled extensions that could be loaded +into interps containing all versions of Tk 8.1 and later. Tk 8.5 no longer +provides this routine, but uses a macro to convert any attempted +calls of this routine into an empty comment. Any stub-enabled +extension providing an extended image type via the legacy interface +that is compiled against Tk 8.5 headers and linked against the +Tk 8.5 stub library will produce a file that can be loaded only +into interps with Tk 8.5 or later; that is, the normal stub-compatibility +rules. If a developer needs to generate from such code a file +that is loadable into interps with Tk 8.4 or earlier, they must +use Tk 8.4 headers and stub libraries to do so. +.PP +Any new code written today should not make use of the legacy +interfaces. Expect their support to go away in Tk 9. +.SH "SEE ALSO" +Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage +.SH KEYWORDS +image manager, image type, instance, master diff --git a/tk8.6/doc/CrtItemType.3 b/tk8.6/doc/CrtItemType.3 new file mode 100644 index 0000000..005d2e2 --- /dev/null +++ b/tk8.6/doc/CrtItemType.3 @@ -0,0 +1,695 @@ +'\" +'\" Copyright (c) 1994-1995 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateItemType\fR(\fItypePtr\fR) +.sp +Tk_ItemType * +\fBTk_GetItemTypes\fR() +.SH ARGUMENTS +.AS Tk_ItemType *typePtr +.AP Tk_ItemType *typePtr in +Structure that defines the new type of canvas item. +.BE +.SH INTRODUCTION +.PP +\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item +described by the \fItypePtr\fR argument. +An item type corresponds to a particular value of the \fItype\fR +argument to the \fBcreate\fR widget command for canvases, and +the code that implements a canvas item type is called a \fItype manager\fR. +Tk defines several built-in item types, such as \fBrectangle\fR +and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR +allows additional item types to be defined. +Once \fBTk_CreateItemType\fR returns, the new item type may be used +in new or existing canvas widgets just like the built-in item +types. +.PP +\fBTk_GetItemTypes\fR returns a pointer to the first in the list +of all item types currently defined for canvases. +The entries in the list are linked together through their +\fInextPtr\fR fields, with the end of the list marked by a +NULL \fInextPtr\fR. +.PP +You may find it easier to understand the rest of this manual entry +by looking at the code for an existing canvas item type such as +bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c). +The easiest way to create a new type manager is to copy the code +for an existing type and modify it for the new type. +.PP +Tk provides a number of utility procedures for the use of canvas +type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; +these are described in separate manual entries. +.SH "DATA STRUCTURES" +.PP +A type manager consists of a collection of procedures that provide a +standard set of operations on items of that type. +The type manager deals with three kinds of data +structures. +The first data structure is a Tk_ItemType; it contains +information such as the name of the type and pointers to +the standard procedures implemented by the type manager: +.PP +.CS +typedef struct Tk_ItemType { + const char *\fIname\fR; + int \fIitemSize\fR; + Tk_ItemCreateProc *\fIcreateProc\fR; + const Tk_ConfigSpec *\fIconfigSpecs\fR; + Tk_ItemConfigureProc *\fIconfigProc\fR; + Tk_ItemCoordProc *\fIcoordProc\fR; + Tk_ItemDeleteProc *\fIdeleteProc\fR; + Tk_ItemDisplayProc *\fIdisplayProc\fR; + int \fIalwaysRedraw\fR; + Tk_ItemPointProc *\fIpointProc\fR; + Tk_ItemAreaProc *\fIareaProc\fR; + Tk_ItemPostscriptProc *\fIpostscriptProc\fR; + Tk_ItemScaleProc *\fIscaleProc\fR; + Tk_ItemTranslateProc *\fItranslateProc\fR; + Tk_ItemIndexProc *\fIindexProc\fR; + Tk_ItemCursorProc *\fIicursorProc\fR; + Tk_ItemSelectionProc *\fIselectionProc\fR; + Tk_ItemInsertProc *\fIinsertProc\fR; + Tk_ItemDCharsProc *\fIdCharsProc\fR; + Tk_ItemType *\fInextPtr\fR; +} \fBTk_ItemType\fR; +.CE +.PP +The fields of a Tk_ItemType structure are described in more detail +later in this manual entry. +When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR +argument must point to a structure with all of the fields initialized +except \fInextPtr\fR, which Tk sets to link all the types together +into a list. +The structure must be in permanent memory (either statically +allocated or dynamically allocated but never freed); Tk retains +a pointer to this structure. +.PP +The second data structure manipulated by a type manager is an +\fIitem record\fR. +For each item in a canvas there exists one item record. +All of the items of a given type generally have item records with +the same structure, but different types usually have different +formats for their item records. +The first part of each item record is a header with a standard structure +defined by Tk via the type Tk_Item; the rest of the item +record is defined by the type manager. +A type manager must define its item records with a Tk_Item as +the first field. +For example, the item record for bitmap items is defined as follows: +.PP +.CS +typedef struct BitmapItem { + Tk_Item \fIheader\fR; + double \fIx\fR, \fIy\fR; + Tk_Anchor \fIanchor\fR; + Pixmap \fIbitmap\fR; + XColor *\fIfgColor\fR; + XColor *\fIbgColor\fR; + GC \fIgc\fR; +} \fBBitmapItem\fR; +.CE +.PP +The \fIheader\fR substructure contains information used by Tk +to manage the item, such as its identifier, its tags, its type, +and its bounding box. +The fields starting with \fIx\fR belong to the type manager: +Tk will never read or write them. +The type manager should not need to read or write any of the +fields in the header except for four fields +whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. +These fields give a bounding box for the items using integer +canvas coordinates: the item should not cover any pixels +with x-coordinate lower than \fIx1\fR or y-coordinate +lower than \fIy1\fR, nor should it cover any pixels with +x-coordinate greater than or equal to \fIx2\fR or y-coordinate +greater than or equal to \fIy2\fR. +It is up to the type manager to keep the bounding box up to +date as the item is moved and reconfigured. +.PP +Whenever Tk calls a procedure in a type manager it passes in a pointer +to an item record. +The argument is always passed as a pointer to a Tk_Item; the type +manager will typically cast this into a pointer to its own specific +type, such as BitmapItem. +.PP +The third data structure used by type managers has type +Tk_Canvas; it serves as an opaque handle for the canvas widget +as a whole. +Type managers need not know anything about the contents of this +structure. +A Tk_Canvas handle is typically passed in to the +procedures of a type manager, and the type manager can pass the +handle back to library procedures such as Tk_CanvasTkwin +to fetch information about the canvas. +.SH "TK_ITEMTYPE FIELDS" +.SS NAME +.PP +This section and the ones that follow describe each of the fields +in a Tk_ItemType structure in detail. +The \fIname\fR field provides a string name for the item type. +Once \fBTk_CreateImageType\fR returns, this name may be used +in \fBcreate\fR widget commands to create items of the new +type. +If there already existed an item type by this name then +the new item type replaces the old one. +.SS "FLAGS (IN ALWAYSREDRAW)" +.PP +The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons) +contains a collection of flag bits that modify how the canvas core interacts +with the item. The following bits are defined: +.TP +\fB1\fR +. +Indicates that the item should always be redrawn when any part of the canvas +is redrawn, rather than only when the bounding box of the item overlaps the +area being redrawn. This is used by window items, for example, which need to +unmap subwindows that are not on the screen. +.TP +\fBTK_CONFIG_OBJS\fR +. +Indicates that operations which would otherwise take a string (or array of +strings) actually take a Tcl_Obj reference (or an array of such references). +The operations to which this applies are the \fIconfigProc\fR, the +\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the +\fIinsertProc\fR. +.TP +\fBTK_MOVABLE_POINTS\fR +.VS 8.6 +Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and +\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon +types, and that hence individual coordinate points can be moved. Must not be +set if any of the above methods is NULL. +.VE 8.6 +.SS ITEMSIZE +.PP +\fItypePtr\->itemSize\fR gives the size in bytes of item records +of this type, including the Tk_Item header. +Tk uses this size to allocate memory space for items of the type. +All of the item records for a given type must have the same size. +If variable length fields are needed for an item (such as a list +of points for a polygon), the type manager can allocate a separate +object of variable length and keep a pointer to it in the item record. +.SS CREATEPROC +.PP +\fItypePtr\->createProc\fR points to a procedure for +Tk to call whenever a new item of this type is created. +\fItypePtr\->createProc\fR must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); +.CE +.PP +The \fIinterp\fR argument is the interpreter in which the canvas's +\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a +handle for the canvas widget. +\fIitemPtr\fR is a pointer to a newly-allocated item of +size \fItypePtr\->itemSize\fR. +Tk has already initialized the item's header (the first +\fBsizeof(Tk_ItemType)\fR bytes). +The \fIobjc\fR and \fIobjv\fR arguments describe all of the +arguments to the \fBcreate\fR command after the \fItype\fR +argument. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. +For example, in the widget command: +.PP +.CS +\fB\&.c create rectangle 10 20 50 50 \-fill black\fR +.CE +.PP +\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the +integer object \fB10\fR. +.PP +\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize +the type-specific parts of the item record and set an initial value +for the bounding box in the item's header. +It should return a standard Tcl completion code and leave an +error message in the interpreter result if an error occurs. +If an error occurs Tk will free the item record, so \fIcreateProc\fR +must be sure to leave the item record in a clean state if it returns an error +(e.g., it must free any additional memory that it allocated for +the item). +.SS CONFIGSPECS +.PP +Each type manager must provide a standard table describing its +configuration options, in a form suitable for use with +\fBTk_ConfigureWidget\fR. +This table will normally be used by \fItypePtr\->createProc\fR +and \fItypePtr\->configProc\fR, but Tk also uses it directly +to retrieve option information in the \fBitemcget\fR and +\fBitemconfigure\fR widget commands. +\fItypePtr\->configSpecs\fR must point to the configuration table +for this type. +Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR +for implementing the \fB\-tags\fR option; see an existing type +manager for an example of how to use it in \fIconfigSpecs\fR. +.SS CONFIGPROC +.PP +\fItypePtr\->configProc\fR is called by Tk whenever the +\fBitemconfigure\fR widget command is invoked to change the +configuration options for a canvas item. +This procedure must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemConfigureProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + int \fIflags\fR); +.CE +.PP +The \fIinterp\fR argument identifies the interpreter in which the +widget command was invoked, \fIcanvas\fR is a handle for the canvas +widget, and \fIitemPtr\fR is a pointer to the item being configured. +\fIobjc\fR and \fIobjv\fR contain the configuration options. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. +For example, if the following command is invoked: +.PP +.CS +\fB\&.c itemconfigure 2 \-fill red \-outline black\fR +.CE +.PP +\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR +through \fBblack\fR. +\fIobjc\fR will always be an even value. +The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; +currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk +invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR +procedure will usually invoke \fIconfigProc\fR with different flag values. +.PP +\fItypePtr\->configProc\fR returns a standard Tcl completion code and +leaves an error message in the interpreter result if an error occurs. +It must update the item's bounding box to reflect the new configuration +options. +.SS COORDPROC +.PP +\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR +widget command for an item. +It must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemCoordProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); +.CE +.PP +The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR +all have the standard meanings, and \fIobjc\fR and \fIobjv\fR +describe the coordinate arguments. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. +For example, if the following widget command is invoked: +.PP +.CS +\fB\&.c coords 2 30 90\fR +.CE +.PP +\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects +\fB30\fR and \fB90\fR. +.PP +The \fIcoordProc\fR procedure should process the new coordinates, +update the item appropriately (e.g., it must reset the bounding +box in the item's header), and return a standard Tcl completion +code. +If an error occurs, \fIcoordProc\fR must leave an error message in +the interpreter result. +.SS DELETEPROC +.PP +\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item +and free any resources allocated to it. +It must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemDeleteProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR); +.CE +.PP +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual +interpretations, and \fIdisplay\fR identifies the X display containing +the canvas. +\fIdeleteProc\fR must free up any resources allocated for the item, +so that Tk can free the item record. +\fIdeleteProc\fR should not actually free the item record; this will +be done by Tk when \fIdeleteProc\fR returns. +.SS "DISPLAYPROC" +.PP +\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item +on the screen. +It must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemDisplayProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR, + Drawable \fIdst\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR); +.CE +.PP +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. +\fIdisplay\fR identifies the display containing the canvas, and +\fIdst\fR specifies a drawable in which the item should be rendered; +typically this is an off-screen pixmap, which Tk will copy into +the canvas's window once all relevant items have been drawn. +\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular +region in canvas coordinates, which is the area to be redrawn; +only information that overlaps this area needs to be redrawn. +Tk will not call \fIdisplayProc\fR unless the item's bounding box +overlaps the redraw area, but the type manager may wish to use +the redraw area to optimize the redisplay of the item. +.PP +Because of scrolling and the use of off-screen pixmaps for +double-buffered redisplay, the item's coordinates in \fIdst\fR +will not necessarily be the same as those in the canvas. +\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR +to transform coordinates from those of the canvas to those +of \fIdst\fR. +.PP +Normally an item's \fIdisplayProc\fR is only invoked if the item +overlaps the area being displayed. +However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1, +(i.e.\| +.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" ) +then \fIdisplayProc\fR is invoked during every redisplay operation, +even if the item does not overlap the area of redisplay; this is useful for +cases such as window items, where the subwindow needs to be unmapped when it +is off the screen. +.SS POINTPROC +.PP +\fItypePtr\->pointProc\fR is invoked by Tk to find out how close +a given point is to a canvas item. +Tk uses this procedure for purposes such as locating the item +under the mouse or finding the closest item to a given point. +The procedure must match the following prototype: +.PP +.CS +typedef double \fBTk_ItemPointProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIpointPtr\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. +\fIpointPtr\fR points to an array of two numbers giving +the x and y coordinates of a point. +\fIpointProc\fR must return a real value giving the distance +from the point to the item, or 0 if the point lies inside +the item. +.SS AREAPROC +.PP +\fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship +between an item and a rectangular area. +It must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemAreaProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIrectPtr\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. +\fIrectPtr\fR points to an array of four real numbers; +the first two give the x and y coordinates of the upper left +corner of a rectangle, and the second two give the x and y +coordinates of the lower right corner. +\fIareaProc\fR must return \-1 if the item lies entirely outside +the given area, 0 if it lies partially inside and partially +outside the area, and 1 if it lies entirely inside the area. +.SS POSTSCRIPTPROC +.PP +\fItypePtr\->postscriptProc\fR is invoked by Tk to generate +Postscript for an item during the \fBpostscript\fR widget command. +If the type manager is not capable of generating Postscript then +\fItypePtr\->postscriptProc\fR should be NULL. +The procedure must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemPostscriptProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIprepass\fR); +.CE +.PP +The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have +standard meanings; \fIprepass\fR will be described below. +If \fIpostscriptProc\fR completes successfully, it should append +Postscript for the item to the information in the interpreter result +(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) +and return \fBTCL_OK\fR. +If an error occurs, \fIpostscriptProc\fR should clear the result +and replace its contents with an error message; then it should +return \fBTCL_ERROR\fR. +.PP +Tk provides a collection of utility procedures to simplify +\fIpostscriptProc\fR. +For example, \fBTk_CanvasPsColor\fR will generate Postscript to set +the current color to a given Tk color and \fBTk_CanvasPsFont\fR will +set up font information. +When generating Postscript, the type manager is free to change the +graphics state of the Postscript interpreter, since Tk places +\fBgsave\fR and \fBgrestore\fR commands around the Postscript for +the item. +The type manager can use canvas x coordinates directly in its Postscript, +but it must call \fBTk_CanvasPsY\fR to convert y coordinates from +the space of the canvas (where the origin is at the +upper left) to the space of Postscript (where the origin is at the +lower left). +.PP +In order to generate Postscript that complies with the Adobe Document +Structuring Conventions, Tk actually generates Postscript in two passes. +It calls each item's \fIpostscriptProc\fR in each pass. +The only purpose of the first pass is to collect font information +(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is +discarded. +Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 +during the first pass; the type manager can use \fIprepass\fR to skip +all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. +During the second pass \fIprepass\fR will be 0, so the type manager +must generate complete Postscript. +.SS SCALEPROC +.PP +\fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item +during the \fBscale\fR widget command. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemScaleProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIoriginX\fR, + double \fIoriginY\fR, + double \fIscaleX\fR, + double \fIscaleY\fR); +.CE +.PP +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. +\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which +the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the +x and y scale factors. +The item should adjust its coordinates so that a point in the item +that used to have coordinates \fIx\fR and \fIy\fR will have new +coordinates \fIx\(fm\fR and \fIy\(fm\fR, where +.PP +.CS +\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR) +\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR) +.CE +.PP +\fIscaleProc\fR must also update the bounding box in the item's +header. +.SS TRANSLATEPROC +.PP +\fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item +during the \fBmove\fR widget command. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemTranslateProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIdeltaX\fR, + double \fIdeltaY\fR); +.CE +.PP +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, +and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be +added to each x and y coordinate within the item. +The type manager should adjust the item's coordinates and +update the bounding box in the item's header. +.SS INDEXPROC +.PP +\fItypePtr\->indexProc\fR is invoked by Tk to translate a string +index specification into a numerical index, for example during the +\fBindex\fR widget command. +It is only relevant for item types that support indexable text or coordinates; +\fItypePtr\->indexProc\fR may be specified as NULL for non-textual +item types if they do not support detailed coordinate addressing. +The procedure must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemIndexProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Tcl_Obj *\fIindexObj\fR, + int *\fIindexPtr\fR); +.CE +.PP +The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all +have the usual meaning. +\fIindexObj\fR contains a textual description of an index, +and \fIindexPtr\fR points to an integer value that should be +filled in with a numerical index. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will +actually contain a pointer to a constant string. +It is up to the type manager to decide what forms of index +are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, +\fBend\fR, etc.). +\fIindexProc\fR should return a Tcl completion code and set +the interpreter result in the event of an error. +.SS ICURSORPROC +.PP +\fItypePtr\->icursorProc\fR is invoked by Tk during +the \fBicursor\fR widget command to set the position of the +insertion cursor in a textual item. +It is only relevant for item types that support an insertion cursor; +\fItypePtr\->icursorProc\fR may be specified as NULL for item types +that do not support an insertion cursor. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemCursorProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and +\fIindex\fR is an index into the item's text, as returned by a +previous call to \fItypePtr\->insertProc\fR. +The type manager should position the insertion cursor in the +item just before the character given by \fIindex\fR. +Whether or not to actually display the insertion cursor is +determined by other information provided by \fBTk_CanvasGetTextInfo\fR. +.SS SELECTIONPROC +.PP +\fItypePtr\->selectionProc\fR is invoked by Tk during selection +retrievals; it must return part or all of the selected text in +the item (if any). +It is only relevant for item types that support text; +\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual +item types. +The procedure must match the following prototype: +.PP +.CS +typedef int \fBTk_ItemSelectionProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIoffset\fR is an offset in bytes into the selection where 0 refers +to the first byte of the selection; it identifies +the first character that is to be returned in this call. +\fIbuffer\fR points to an area of memory in which to store the +requested bytes, and \fImaxBytes\fR specifies the maximum number +of bytes to return. +\fIselectionProc\fR should extract up to \fImaxBytes\fR characters +from the selection and copy them to \fImaxBytes\fR; it should +return a count of the number of bytes actually copied, which may +be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes +in the selection. +.SS INSERTPROC +.PP +\fItypePtr\->insertProc\fR is invoked by Tk during +the \fBinsert\fR widget command to insert new text or coordinates into a +canvas item. +It is only relevant for item types that support the \fBinsert\fR method; +\fItypePtr\->insertProc\fR may be specified as NULL for other +item types. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemInsertProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR, + Tcl_Obj *\fIobj\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIindex\fR is an index into the item's text, as returned by a +previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR +contains new text to insert just before the character given +by \fIindex\fR. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will +actually contain a pointer to a constant string to be inserted. +If the item supports modification of the coordinates list by this +.PP +The type manager should insert the text and recompute the bounding +box in the item's header. +.SS DCHARSPROC +.PP +\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR +widget command to delete a range of text from a canvas item or a range of +coordinates from a pathed item. +It is only relevant for item types that support text; +\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual +item types that do not want to support coordinate deletion. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemDCharsProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIfirst\fR, + int \fIlast\fR); +.CE +.PP +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes +to be deleted, as returned by previous calls to \fItypePtr\->indexProc\fR. +The type manager should delete the specified characters and update +the bounding box in the item's header. +.SH "SEE ALSO" +Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin +.SH KEYWORDS +canvas, focus, item type, selection, type manager diff --git a/tk8.6/doc/CrtPhImgFmt.3 b/tk8.6/doc/CrtPhImgFmt.3 new file mode 100644 index 0000000..c7e792a --- /dev/null +++ b/tk8.6/doc/CrtPhImgFmt.3 @@ -0,0 +1,270 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreatePhotoImageFormat \- define new file format for photo images +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) +.SH ARGUMENTS +.AS "const Tk_PhotoImageFormat" *formatPtr +.AP "const Tk_PhotoImageFormat" *formatPtr in +Structure that defines the new file format. +.BE +.SH DESCRIPTION +.PP +\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format +for image data for use with photo images. The code that implements an +image file format is called an image file format handler, or +handler for short. The photo image code +maintains a list of handlers that can be used to read and +write data to or from a file. Some handlers may also +support reading image data from a string or converting image data to a +string format. +The user can specify which handler to use with the \fB\-format\fR +image configuration option or the \fB\-format\fR option to the +\fBread\fR and \fBwrite\fR photo image subcommands. +.PP +An image file format handler consists of a collection of procedures +plus a Tk_PhotoImageFormat structure, which contains the name of the +image file format and pointers to six procedures provided by the +handler to deal with files and strings in this format. The +Tk_PhotoImageFormat structure contains the following fields: +.CS +typedef struct Tk_PhotoImageFormat { + const char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; +} \fBTk_PhotoImageFormat\fR; +.CE +.PP +The handler need not provide implementations of all six procedures. +For example, the procedures that handle string data would not be +provided for a format in which the image data are stored in binary, +and could therefore contain null characters. If any procedure is not +implemented, the corresponding pointer in the Tk_PhotoImageFormat +structure should be set to NULL. The handler must provide the +\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR +procedure, and the \fIstringMatchProc\fR procedure if it provides the +\fIstringReadProc\fR procedure. +.SS NAME +.PP +\fIformatPtr->name\fR provides a name for the image type. +Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used +in the \fB\-format\fR photo image configuration and subcommand option. +The manual page for the photo image (photo(n)) describes how image +file formats are chosen based on their names and the value given to +the \fB\-format\fR option. The first character of \fIformatPtr->name\fR +must not be an uppercase character from the ASCII character set +(that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used +only for legacy interface support (see below). +.SS FILEMATCHPROC +.PP +\fIformatPtr->fileMatchProc\fR provides the address of a procedure for +Tk to call when it is searching for an image file format handler +suitable for reading data in a given file. +\fIformatPtr->fileMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileMatchProc\fR( + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +The \fIfileName\fR argument is the name of the file containing the +image data, which is open for reading as \fIchan\fR. The +\fIformat\fR argument contains the value given for the +\fB\-format\fR option, or NULL if the option was not specified. +If the data in the file appears to be in the format supported by this +handler, the \fIformatPtr->fileMatchProc\fR procedure should store the +width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR +respectively, and return 1. Otherwise it should return 0. +.SS STRINGMATCHPROC +.PP +\fIformatPtr->stringMatchProc\fR provides the address of a procedure for +Tk to call when it is searching for an image file format handler for +suitable for reading data from a given string. +\fIformatPtr->stringMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringMatchProc\fR( + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +The \fIdata\fR argument points to the object containing the image +data. The \fIformat\fR argument contains the value given for +the \fB\-format\fR option, or NULL if the option was not specified. +If the data in the string appears to be in the format supported by +this handler, the \fIformatPtr->stringMatchProc\fR procedure should +store the width and height of the image in *\fIwidthPtr\fR and +*\fIheightPtr\fR respectively, and return 1. Otherwise it should +return 0. +.SS FILEREADPROC +.PP +\fIformatPtr->fileReadProc\fR provides the address of a procedure for +Tk to call to read data from an image file into a photo image. +\fIformatPtr->fileReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to read the image; it should be used for reporting errors. +The image data is in the file named \fIfileName\fR, which is open for +reading as \fIchan\fR. The \fIformat\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The image data in the file, or a subimage of it, is to +be read into the photo image identified by the handle +\fIimageHandle\fR. The subimage of the data in the file is of +dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at +coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo +image with its top-left corner at coordinates +(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +The return value is a standard Tcl return value. +.SS STRINGREADPROC +.PP +\fIformatPtr->stringReadProc\fR provides the address of a procedure for +Tk to call to read data from a string into a photo image. +\fIformatPtr->stringReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to read the image; it should be used for reporting errors. +The \fIdata\fR argument points to the image data in object form. +The \fIformat\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The image data in the string, or a subimage of it, is to +be read into the photo image identified by the handle +\fIimageHandle\fR. The subimage of the data in the string is of +dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at +coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo +image with its top-left corner at coordinates +(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +The return value is a standard Tcl return value. +.SS FILEWRITEPROC +.PP +\fIformatPtr->fileWriteProc\fR provides the address of a procedure for +Tk to call to write data from a photo image to a file. +\fIformatPtr->fileWriteProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to write the image; it should be used for reporting errors. +The image data to be written are in memory and are described by the +Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the +manual page FindPhoto(3) for details. The \fIfileName\fR argument +points to the string giving the name of the file in which to write the +image data. The \fIformat\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The format string can contain extra characters +after the name of the format. If appropriate, the +\fIformatPtr->fileWriteProc\fR procedure may interpret these +characters to specify further details about the image file. +The return value is a standard Tcl return value. +.SS STRINGWRITEPROC +.PP +\fIformatPtr->stringWriteProc\fR provides the address of a procedure for +Tk to call to translate image data from a photo image into a string. +\fIformatPtr->stringWriteProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to convert the image; it should be used for reporting errors. +The image data to be converted are in memory and are described by the +Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the +manual page FindPhoto(3) for details. The data for the string +should be put in the interpreter \fIinterp\fR result. +The \fIformat\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The format string can contain extra characters +after the name of the format. If appropriate, the +\fIformatPtr->stringWriteProc\fR procedure may interpret these +characters to specify further details about the image file. +The return value is a standard Tcl return value. +.SH "LEGACY INTERFACE SUPPORT" +.PP +In Tk 8.2 and earlier, the definition of all the function pointer +types stored in fields of a \fBTk_PhotoImageFormat\fR struct were +incompatibly different. Legacy programs and libraries dating from +those days may still contain code that defines extended Tk photo image +formats using the old interface. The Tk header file will still support +this legacy interface if the code is compiled with the +macro \fBUSE_OLD_IMAGE\fR defined. Alternatively, the legacy interfaces +are used if the first character of \fIformatPtr->name\fR is an +uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts +are used to forgive the type mismatch. For example, +.CS +static Tk_PhotoImageFormat myFormat = { + "MyFormat", + (Tk_ImageFileMatchProc *) FileMatch, + NULL, + (Tk_ImageFileReadProc *) FileRead, + NULL, + NULL, + NULL +}; +.CE +would define a minimal \fBTk_PhotoImageFormat\fR that operates provide +only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR +are written according to the legacy interfaces of Tk 8.2 or earlier. +.PP +Any stub-enabled extension providing an extended photo image format +via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro +that is compiled against Tk 8.5 headers and linked against the +Tk 8.5 stub library will produce a file that can be loaded only +into interps with Tk 8.5 or later; that is, the normal stub-compatibility +rules. If a developer needs to generate from such code a file +that is loadable into interps with Tk 8.4 or earlier, they must +use Tk 8.4 headers and stub libraries to do so. +.PP +Any new code written today should not make use of the legacy +interfaces. Expect their support to go away in Tk 9. +.SH "SEE ALSO" +Tk_FindPhoto, Tk_PhotoPutBlock +.SH KEYWORDS +photo image, image file diff --git a/tk8.6/doc/CrtSelHdlr.3 b/tk8.6/doc/CrtSelHdlr.3 new file mode 100644 index 0000000..2292ccc --- /dev/null +++ b/tk8.6/doc/CrtSelHdlr.3 @@ -0,0 +1,116 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) +.sp +\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) +.SH ARGUMENTS +.AS Tk_SelectionProc clientData +.AP Tk_Window tkwin in +Window for which \fIproc\fR will provide selection information. +.AP Atom selection in +The name of the selection for which \fIproc\fR will provide +selection information. +.AP Atom target in +Form in which \fIproc\fR can provide the selection (e.g. STRING +or FILE_NAME). Corresponds to \fItype\fR arguments in \fBselection\fR +commands. +.AP Tk_SelectionProc *proc in +Procedure to invoke whenever the selection is owned by \fItkwin\fR +and the selection contents are requested in the format given by +\fItarget\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.AP Atom format in +If the selection requestor is not in this process, \fIformat\fR determines +the representation used to transmit the selection to its +requestor. +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateSelHandler\fR arranges for a particular procedure +(\fIproc\fR) to be called whenever \fIselection\fR is owned by +\fItkwin\fR and the selection contents are requested in the +form given by \fItarget\fR. +\fITarget\fR should be one of +the entries defined in the left column of Table 2 of the +X Inter-Client Communication Conventions Manual (ICCCM) or +any other form in which an application is willing to present +the selection. The most common form is STRING. +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_SelectionProc\fR: +.CS +typedef int \fBTk_SelectionProc\fR( + ClientData \fIclientData\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the +\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR. +Typically, \fIclientData\fR points to a data +structure containing application-specific information that is +needed to retrieve the selection. \fIOffset\fR specifies an +offset position into the selection, \fIbuffer\fR specifies a +location at which to copy information about the selection, and +\fImaxBytes\fR specifies the amount of space available at +\fIbuffer\fR. \fIProc\fR should place a NULL-terminated string +at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters +(not including the terminating NULL), and it should return a +count of the number of non-NULL characters stored at +\fIbuffer\fR. If the selection no longer exists (e.g. it once +existed but the user deleted the range of characters containing +it), then \fIproc\fR should return \-1. +.PP +When transferring large selections, Tk will break them up into +smaller pieces (typically a few thousand bytes each) for more +efficient transmission. It will do this by calling \fIproc\fR +one or more times, using successively higher values of \fIoffset\fR +to retrieve successive portions of the selection. If \fIproc\fR +returns a count less than \fImaxBytes\fR it means that the entire +remainder of the selection has been returned. If \fIproc\fR's return +value is \fImaxBytes\fR it means there may be additional information +in the selection, so Tk must make another call to \fIproc\fR to +retrieve the next portion. +.PP +\fIProc\fR always returns selection information in the form of a +character string. However, the ICCCM allows for information to +be transmitted from the selection owner to the selection requestor +in any of several formats, such as a string, an array of atoms, an +array of integers, etc. The \fIformat\fR argument to +\fBTk_CreateSelHandler\fR indicates what format should be used to +transmit the selection to its requestor (see the middle column of +Table 2 of the ICCCM for examples). If \fIformat\fR is not +STRING, then Tk will take the value returned by \fIproc\fR and divided +it into fields separated by white space. If \fIformat\fR is ATOM, +then Tk will return the selection as an array of atoms, with each +field in \fIproc\fR's result treated as the name of one atom. For +any other value of \fIformat\fR, Tk will return the selection as an +array of 32-bit values where each field of \fIproc\fR's result is +treated as a number and translated to a 32-bit value. In any event, +the \fIformat\fR atom is returned to the selection requestor along +with the contents of the selection. +.PP +If \fBTk_CreateSelHandler\fR is called when there already exists a +handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the +existing handler is replaced with a new one. +.PP +\fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR, +\fIselection\fR, and \fItarget\fR, if such a handler exists. +If there is no such handler then it has no effect. +.SH KEYWORDS +format, handler, selection, target diff --git a/tk8.6/doc/CrtWindow.3 b/tk8.6/doc/CrtWindow.3 new file mode 100644 index 0000000..b254460 --- /dev/null +++ b/tk8.6/doc/CrtWindow.3 @@ -0,0 +1,146 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR) +.sp +Tk_Window +\fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR) +.sp +Tk_Window +\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) +.sp +\fBTk_DestroyWindow\fR(\fItkwin\fR) +.sp +\fBTk_MakeWindowExist\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tcl_Interp *topLevScreen +.AP Tcl_Interp *interp out +Tcl interpreter to use for error reporting. If no error occurs, +then \fI*interp\fR is not modified. +.AP Tk_Window parent in +Token for the window that is to serve as the logical parent of +the new window. +.AP "const char" *name in +Name to use for this window. Must be unique among all children of +the same \fIparent\fR. +.AP "const char" *topLevScreen in +Has same format as \fIscreenName\fR. If NULL, then new window is +created as an internal window. If non-NULL, new window is created as +a top-level window on screen \fItopLevScreen\fR. If \fItopLevScreen\fR +is an empty string +.PQ "" +then new window is created as top-level window of \fIparent\fR's screen. +.AP Tk_Window tkwin in +Token for window. +.AP "const char" *pathName in +Name of new window, specified as path name within application +(e.g. \fB.a.b.c\fR). +.BE +.SH DESCRIPTION +.PP +The procedures \fBTk_CreateWindow\fR, +\fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR +are used to create new windows for +use in Tk-based applications. Each of the procedures returns a token +that can be used to manipulate the window in other calls to the Tk +library. If the window could not be created successfully, then NULL +is returned and the result of interpreter \fIinterp\fR is modified to +hold an error message. +.PP +Tk supports two different kinds of windows: internal +windows and top-level windows. +An internal window is an interior window of a Tk application, such as a +scrollbar or menu bar or button. A top-level window is one that is +created as a child of a screen's root window, rather than as an +interior window, but which is logically part of some existing main +window. Examples of top-level windows are pop-up menus and dialog boxes. +.PP +New windows may be created by calling +\fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is +NULL, then the new window will be an internal window. If +\fItopLevScreen\fR is non-NULL, then the new window will be a +top-level window: \fItopLevScreen\fR indicates the name of +a screen and the new window will be created as a child of the +root window of \fItopLevScreen\fR. In either case Tk will +consider the new window to be the logical child of \fIparent\fR: +the new window's path name will reflect this fact, options may +be specified for the new window under this assumption, and so on. +The only difference is that new X window for a top-level window +will not be a child of \fIparent\fR's X window. For example, a pull-down +menu's \fIparent\fR would be the button-like window used to invoke it, +which would in turn be a child of the menu bar window. A dialog box might +have the application's main window as its parent. +.PP +\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in +that it creates an unnamed window. This window will be manipulatable +only using C interfaces, and will not be visible to Tcl scripts. Both +interior windows and top-level windows may be created with +\fBTk_CreateAnonymousWindow\fR. +.PP +\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying +new windows. In \fBTk_CreateWindowFromPath\fR the new +window is specified with a token for any window in the target +application (\fItkwin\fR), plus a path name for the new window. +It produces the same effect as \fBTk_CreateWindow\fR and allows +both top-level and internal windows to be created, depending on +the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR, +as in calls to \fBTk_CreateWindow\fR, the parent of the new window +must exist at the time of the call, but the new window must not +already exist. +.PP +The window creation procedures do not +actually issue the command to X to create a window. +Instead, they create a local data structure associated with +the window and defer the creation of the X window. +The window will actually be created by the first call to +\fBTk_MapWindow\fR. Deferred window creation allows various +aspects of the window (such as its size, background color, +etc.) to be modified after its creation without incurring +any overhead in the X server. When the window is finally +mapped all of the window attributes can be set while creating +the window. +.PP +The value returned by a window-creation procedure is not the +X token for the window (it cannot be, since X has not been +asked to create the window yet). Instead, it is a token +for Tk's local data structure for the window. Most +of the Tk library procedures take Tk_Window tokens, rather +than X identifiers. The actual +X window identifier can be retrieved from the local +data structure using the \fBTk_WindowId\fR macro; see +the manual entry for \fBTk_WindowId\fR for details. +.PP +\fBTk_DestroyWindow\fR deletes a window and all the data +structures associated with it, including any event handlers +created with \fBTk_CreateEventHandler\fR. In addition, +\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR +recursively (where children are defined in the Tk sense, consisting +of all windows that were created with the given window as \fIparent\fR). +If \fItkwin\fR is an internal window, then event +handlers interested in destroy events +are invoked immediately. If \fItkwin\fR is a top-level or main window, +then the event handlers will be invoked later, after X has seen +the request and returned an event for it. +.PP +If a window has been created +but has not been mapped, so no X window exists, it is +possible to force the creation of the X window by +calling \fBTk_MakeWindowExist\fR. This procedure issues +the X commands to instantiate the window given by \fItkwin\fR. +.SH KEYWORDS +create, deferred creation, destroy, display, internal window, +screen, top-level window, window diff --git a/tk8.6/doc/DeleteImg.3 b/tk8.6/doc/DeleteImg.3 new file mode 100644 index 0000000..507be72 --- /dev/null +++ b/tk8.6/doc/DeleteImg.3 @@ -0,0 +1,31 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_DeleteImage \- Destroy an image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_DeleteImage\fR(\fIinterp, name\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Interpreter for which the image was created. +.AP "const char" *name in +Name of the image. +.BE +.SH DESCRIPTION +.PP +\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR +and \fIname\fR, if there is one. All instances of that image +will redisplay as empty regions. If the given image does not +exist then the procedure has no effect. +.SH KEYWORDS +delete image, image manager diff --git a/tk8.6/doc/DrawFocHlt.3 b/tk8.6/doc/DrawFocHlt.3 new file mode 100644 index 0000000..e2d1578 --- /dev/null +++ b/tk8.6/doc/DrawFocHlt.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tk_Window tkwin in +Window for which the highlight is being drawn. Used to retrieve +the window's dimensions, among other things. +.AP GC gc in +Graphics context to use for drawing the highlight. +.AP int width in +Width of the highlight ring, in pixels. +.AP Drawable drawable in +Drawable in which to draw the highlight; usually an offscreen +pixmap for double buffering. +.BE +.SH DESCRIPTION +.PP +\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the +traversal highlight ring for a widget. +It is typically invoked by widgets during redisplay. +.SH KEYWORDS +focus, traversal highlight diff --git a/tk8.6/doc/EventHndlr.3 b/tk8.6/doc/EventHndlr.3 new file mode 100644 index 0000000..97857fb --- /dev/null +++ b/tk8.6/doc/EventHndlr.3 @@ -0,0 +1,75 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) +.sp +\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) +.SH ARGUMENTS +.AS "unsigned long" clientData +.AP Tk_Window tkwin in +Token for window in which events may occur. +.AP "unsigned long" mask in +Bit-mask of events (such as \fBButtonPressMask\fR) +for which \fIproc\fR should be called. +.AP Tk_EventProc *proc in +Procedure to invoke whenever an event in \fImask\fR occurs +in the window given by \fItkwin\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be +invoked in the future whenever one of the event types specified +by \fImask\fR occurs in the window specified by \fItkwin\fR. +The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; +this mechanism only works in programs that dispatch events +through \fBTk_HandleEvent\fR (or through other Tk procedures that +call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or +\fBTk_MainLoop\fR). +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_EventProc\fR: +.CS +typedef void \fBTk_EventProc\fR( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTk_CreateEventHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +the window in which the event occurred. \fIEventPtr\fR is +a pointer to the X event, which will be one of the ones +specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR. +.PP +\fBTk_DeleteEventHandler\fR may be called to delete a +previously-created event handler: it deletes the first handler +it finds that is associated with \fItkwin\fR and matches the +\fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. If +no such handler exists, then \fBTk_HandleEvent\fR returns +without doing anything. Although Tk supports it, it's probably +a bad idea to have more than one callback with the same \fImask\fR, +\fIproc\fR, and \fIclientData\fR arguments. +When a window is deleted all of its handlers will be deleted +automatically; in this case there is no need to call +\fBTk_DeleteEventHandler\fR. +.PP +If multiple handlers are declared for the same type of X event +on the same window, then the handlers will be invoked in the +order they were created. +.SH KEYWORDS +bind, callback, event, handler diff --git a/tk8.6/doc/FindPhoto.3 b/tk8.6/doc/FindPhoto.3 new file mode 100644 index 0000000..dc218bf --- /dev/null +++ b/tk8.6/doc/FindPhoto.3 @@ -0,0 +1,283 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_PhotoHandle +\fBTk_FindPhoto\fR(\fIinterp, imageName\fR) +.sp +int +\fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ +compRule\fR) +.sp +int +\fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ +zoomX, zoomY, subsampleX, subsampleY, compRule\fR) +.sp +int +\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) +.sp +void +\fBTk_PhotoBlank\fR(\fIhandle\fR) +.sp +int +\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) +.sp +void +\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) +.sp +int +\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) +.SH ARGUMENTS +.AS Tk_PhotoImageBlock window_path +.AP Tcl_Interp *interp in +Interpreter in which image was created and in which error reporting is +to be done. +.AP "const char" *imageName in +Name of the photo image. +.AP Tk_PhotoHandle handle in +Opaque handle identifying the photo image to be affected. +.AP Tk_PhotoImageBlock *blockPtr in +Specifies the address and storage layout of image data. +.AP int x in +Specifies the X coordinate where the top-left corner of the block is +to be placed within the image. +.AP int y in +Specifies the Y coordinate where the top-left corner of the block is +to be placed within the image. +.AP int width in +Specifies the width of the image area to be affected (for +\fBTk_PhotoPutBlock\fR) or the desired image width (for +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). +.AP int compRule in +Specifies the compositing rule used when combining transparent pixels +in a block of data with a photo image. Must be one of +\fBTK_PHOTO_COMPOSITE_OVERLAY\fR (which puts the block of data over the top +of the existing photo image, with the previous contents showing +through in the transparent bits) or \fBTK_PHOTO_COMPOSITE_SET\fR (which +discards the existing photo image contents in the rectangle covered by +the data block.) +.AP int height in +Specifies the height of the image area to be affected (for +\fBTk_PhotoPutBlock\fR) or the desired image height (for +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). +.AP int *widthPtr out +Pointer to location in which to store the image width. +.AP int *heightPtr out +Pointer to location in which to store the image height. +.AP int subsampleX in +Specifies the subsampling factor in the X direction for input +image data. +.AP int subsampleY in +Specifies the subsampling factor in the Y direction for input +image data. +.AP int zoomX in +Specifies the zoom factor to be applied in the X direction to pixels +being written to the photo image. +.AP int zoomY in +Specifies the zoom factor to be applied in the Y direction to pixels +being written to the photo image. +.BE +.SH DESCRIPTION +.PP +\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a +particular photo image to the other procedures. The parameter is the +name of the image, that is, the name specified to the \fBimage create +photo\fR command, or assigned by that command if no name was specified. +If \fIimageName\fR does not exist or is not a photo image, +\fBTk_FindPhoto\fR returns NULL. +.PP +\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be +displayed. The call affects an area of the image of size +\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at +coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR, +\fIx\fR, and \fIy\fR must be non-negative. +If part of this area lies outside the +current bounds of the image, the image will be expanded to include the +area, unless the user has specified an explicit image size with the +\fB\-width\fR and/or \fB\-height\fR widget configuration options +(see photo(n)); in that +case the area is silently clipped to the image boundaries. +.PP +The \fIblock\fR parameter is a pointer to a +\fBTk_PhotoImageBlock\fR structure, defined as follows: +.CS +typedef struct { + unsigned char *\fIpixelPtr\fR; + int \fIwidth\fR; + int \fIheight\fR; + int \fIpitch\fR; + int \fIpixelSize\fR; + int \fIoffset\fR[4]; +} \fBTk_PhotoImageBlock\fR; +.CE +The \fIpixelPtr\fR field points to the first pixel, that is, the +top-left pixel in the block. +The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the +block of pixels. The \fIpixelSize\fR field specifies the address +difference between two horizontally adjacent pixels. It should be 4 for +RGB and 2 for grayscale image data. Other values are possible, if the +offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for +red, green and blue data stored in different planes). Using such a +layout is strongly discouraged, though. Due to a bug, it might not work +correctly if an alpha channel is provided. (see the \fBBUGS\fR section +below). The \fIpitch\fR field specifies the +address difference between two vertically adjacent pixels. The +\fIoffset\fR array contains the offsets from the address of a pixel +to the addresses of the bytes containing the red, green, blue and alpha +(transparency) components. If the offsets for red, green and blue are +equal, the image is interpreted as grayscale. If they differ, RGB data +is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data +and 0, 0, 0, 1 for grayscale. It is possible to provide image data +without an alpha channel by setting the offset for alpha to a negative +value and adjusting the \fIpixelSize\fR field accordingly. This use is +discouraged, though (see the \fBBUGS\fR section below). +.PP +The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a +compositing rule that says what to do with transparent pixels. The +value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of +the photo image should show through, and the value +\fBTK_PHOTO_COMPOSITE_SET\fR says that the previous contents of the photo +image should be completely ignored, and the values from the block be +copied directly across. The behavior in Tk8.3 and earlier was +equivalent to having \fBTK_PHOTO_COMPOSITE_OVERLAY\fR as a compositing rule. +.PP +The value given for the \fIwidth\fR and \fIheight\fR parameters to +\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified +in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a +sub-block from the image data supplied. If they are larger, the data +given are replicated (in a tiled fashion) to fill the specified area. +These rules operate independently in the horizontal and vertical +directions. +.PP +\fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.PP +\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that +the image can be reduced or enlarged for display. The +\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the +image to be reduced by subsampling. +\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image +whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y +coordinates are multiples of \fIsubsampleY\fR. For example, an image +of 512x512 pixels can be reduced to 256x256 by setting +\fIsubsampleX\fR and \fIsubsampleY\fR to 2. +.PP +The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be +enlarged by pixel replication. Each pixel of the (possibly subsampled) +input image will be written to a block \fIzoomX\fR pixels wide and +\fIzoomY\fR pixels high of the displayed image. Subsampling and +zooming can be used together for special effects. +.PP +\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo +image. \fBTk_PhotoGetImage\fR fills +in the structure pointed to by the \fIblockPtr\fR parameter with values +that describe the address and layout of the image data that the +photo image has stored internally. The values are valid +until the image is destroyed or its size is changed. +.PP +It is possible to modify an image by writing directly to the data +the \fIpixelPtr\fR field points to. The size of the image cannot be +changed this way, though. +Also, changes made by writing directly to \fIpixelPtr\fR will not be +immediately visible, but only after a call to +\fBTk_ImageChanged\fR or after an event that causes the interested +widgets to redraw themselves. +For these reasons usually it is preferable to make changes to +a copy of the image data and write it back with +\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. +.PP +\fBTk_PhotoGetImage\fR returns 1 for compatibility with the +corresponding procedure in the old photo widget. +.PP +\fBTk_PhotoBlank\fR blanks the entire area of the +photo image. Blank areas of a photo image are transparent. +.PP +\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be +at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or +height are unchanged if the user has specified an explicit image width +or height with the \fB\-width\fR and/or \fB\-height\fR configuration +options, respectively. +If the image data +are being supplied in many small blocks, it is more efficient to use +\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than +allowing the image to expand in many small increments as image blocks +are supplied. +.PP +\fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.PP +\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user +had specified the given \fIwidth\fR and \fIheight\fR values to the +\fB\-width\fR and \fB\-height\fR configuration options. A value of +zero for \fIwidth\fR or \fIheight\fR does not change the image's width +or height, but allows the width or height to be changed by subsequent +calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or +\fBTk_PhotoExpand\fR. +.PP +\fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.PP +\fBTk_PhotoGetSize\fR returns the dimensions of the image in +*\fIwidthPtr\fR and *\fIheightPtr\fR. +.SH PORTABILITY +.PP +In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and +\fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to +compile code that uses the old interface against 8.4 without updating +your code, compile it with the flag +-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against +older versions of Tk will continue to work. +.PP +In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an +\fIinterp\fR argument or return any result code. If insufficient +memory was available for an image, Tk would panic. This behaviour is +still supported if you compile your extension with the additional flag +-DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against +older versions of Tk will continue to work. +.SH BUGS +The \fBTk_PhotoImageBlock\fR structure used to provide image data to +\fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the +data (e.g. separate planes for the red, green, blue and alpha +channels). Unfortunately, the implementation fails to hold this +promise. The problem is that the \fIpixelSize\fR field is +(incorrectly) used to determine whether the image has an alpha channel. +Currently, if the offset for the alpha channel is greater or equal than +\fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is +present and makes the image fully opaque. This means that for layouts +where the channels are separate (or any other exotic layout where +\fIpixelSize\fR has to be smaller than the alpha offset), the alpha +channel will not be read correctly. In order to be on the safe side +if this issue will be corrected in a future release, it is strongly +recommended you always provide alpha data - even if the image has no +transparency - and only use the "standard" layout with a +\fIpixelSize\fR of 2 for grayscale and 4 for RGB data with +\fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively. +.SH CREDITS +.PP +The code for the photo image type was developed by Paul Mackerras, +based on his earlier photo widget code. +.SH KEYWORDS +photo, image diff --git a/tk8.6/doc/FontId.3 b/tk8.6/doc/FontId.3 new file mode 100644 index 0000000..9d35ae6 --- /dev/null +++ b/tk8.6/doc/FontId.3 @@ -0,0 +1,94 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for +fonts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Font +\fBTk_FontId(\fItkfont\fB)\fR +.sp +\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR +.sp +int +\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR +.SH ARGUMENTS +.AS Tk_FontMetrics *dsPtr +.AP Tk_Font tkfont in +Opaque font token being queried. Must have been returned by a previous +call to \fBTk_GetFont\fR. +.AP Tk_FontMetrics *fmPtr out +Pointer to structure in which the font metrics for \fItkfont\fR will +be stored. See \fBDATA STRUCTURES\fR below for details. +.AP Tcl_DString *dsPtr out +Pointer to an initialized \fBTcl_DString\fR to which the name of the +Postscript font that corresponds to \fItkfont\fR will be appended. +.BE +.SH DESCRIPTION +.PP +Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be +selected into an XGCValues structure in order to construct a graphics +context that can be used to draw text in the specified font. +.PP +\fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the +\fItkfont\fR in pixels and stores those values in the structure pointer to by +\fIfmPtr\fR. These values can be used in computations such as to space +multiple lines of text, to align the baselines of text in different +fonts, and to vertically align text in a given region. See the +documentation for the \fBfont\fR command for definitions of the terms +ascent, descent, and linespace, used in font metrics. +.PP +\fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding +Postscript font name that should be used when printing. The return value +is the size in points of the \fItkfont\fR and the Postscript font name is +appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized +\fBTcl_DString\fR. Given a +.QW reasonable +Postscript printer, the +following screen font families should print correctly: +.IP +\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, +\fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, +\fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, +\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and +\fBZapf Dingbats\fR. +.PP +Any other font families may not print correctly because the computed +Postscript font name may be incorrect or not exist on the printer. +.SH "DATA STRUCTURES" +.PP +The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to +return information about a font and is defined as follows: +.CS +typedef struct Tk_FontMetrics { + int \fIascent\fR; + int \fIdescent\fR; + int \fIlinespace\fR; +} \fBTk_FontMetrics\fR; +.CE +.PP +The \fIascent\fR field is the amount in pixels that the tallest +letter sticks up above the baseline, plus any extra blank space added +by the designer of the font. +.PP +The \fIdescent\fR is the largest amount in pixels that any letter +sticks below the baseline, plus any extra blank space added by the +designer of the font. +.PP +The \fIlinespace\fR is the sum of the ascent and descent. How far +apart two lines of text in the same font should be placed so that none +of the characters in one line overlap any of the characters in the +other line. +.SH "SEE ALSO" +font(n), MeasureChar(3) +.SH KEYWORDS +font, measurement, Postscript diff --git a/tk8.6/doc/FreeXId.3 b/tk8.6/doc/FreeXId.3 new file mode 100644 index 0000000..dd1d141 --- /dev/null +++ b/tk8.6/doc/FreeXId.3 @@ -0,0 +1,48 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_FreeXId \- make X resource identifier available for reuse +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_FreeXId(\fIdisplay, id\fB)\fR +.SH ARGUMENTS +.AS Display *display out +.AP Display *display in +Display for which \fIid\fR was allocated. +.AP XID id in +Identifier of X resource (window, font, pixmap, cursor, graphics +context, or colormap) that is no longer in use. +.BE +.SH DESCRIPTION +.PP +The default allocator for resource identifiers provided by Xlib is very +simple-minded and does not allow resource identifiers to be re-used. +If a long-running application reaches the end of the resource id +space, it will generate an X protocol error and crash. +Tk replaces the default id allocator with its own allocator, which +allows identifiers to be reused. +In order for this to work, \fBTk_FreeXId\fR must be called to +tell the allocator about resources that have been freed. +Tk automatically calls \fBTk_FreeXId\fR whenever it frees a +resource, so if you use procedures like \fBTk_GetFont\fR, +\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call +\fBTk_FreeXId\fR. +However, if you allocate resources directly from Xlib, for example +by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR +when you call the corresponding Xlib free procedure, such as +\fBXFreePixmap\fR. +If you do not call \fBTk_FreeXId\fR then the resource identifier will +be lost, which could cause problems if the application runs long enough +to lose all of the available identifiers. +.SH KEYWORDS +resource identifier diff --git a/tk8.6/doc/GeomReq.3 b/tk8.6/doc/GeomReq.3 new file mode 100644 index 0000000..895f683 --- /dev/null +++ b/tk8.6/doc/GeomReq.3 @@ -0,0 +1,92 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \- specify desired geometry or internal border for a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) +.sp +\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) +.sp +\fBTk_SetInternalBorder\fR(\fItkwin, width\fR) +.sp +\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) +.SH ARGUMENTS +.AS baseHeight clientData +.AP Tk_Window tkwin in +Window for which geometry is being requested. +.AP int reqWidth in +Desired width for \fItkwin\fR, in pixel units. +.AP int reqHeight in +Desired height for \fItkwin\fR, in pixel units. +.AP int minWidth in +Desired minimum requested width for \fItkwin\fR, in pixel units. +.AP int minHeight in +Desired minimum requested height for \fItkwin\fR, in pixel units. +.AP int width in +Space to leave for internal border for \fItkwin\fR, in pixel units. +.AP int left in +Space to leave for left side of internal border for \fItkwin\fR, in pixel units. +.AP int right in +Space to leave for right side of internal border for \fItkwin\fR, in pixel units. +.AP int top in +Space to leave for top side of internal border for \fItkwin\fR, in pixel units. +.AP int bottom in +Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. +.BE +.SH DESCRIPTION +.PP +\fBTk_GeometryRequest\fR is called by widget code to indicate its +preference for the dimensions of a particular window. The arguments +to \fBTk_GeometryRequest\fR are made available to the geometry +manager for the window, which then decides on the actual geometry +for the window. Although geometry managers generally try to satisfy +requests made to \fBTk_GeometryRequest\fR, there is no guarantee that +this will always be possible. Widget code should not assume that +a geometry request will be satisfied until it receives a +\fBConfigureNotify\fR event indicating that the geometry change has +occurred. Widget code should never call procedures like +\fBTk_ResizeWindow\fR directly. Instead, it should invoke +\fBTk_GeometryRequest\fR and leave the final geometry decisions to +the geometry manager. +.PP +If \fItkwin\fR is a top-level window, then the geometry information +will be passed to the window manager using the standard ICCCM protocol. +.PP +\fBTk_SetInternalBorder\fR is called by widget code to indicate that +the widget has an internal border. This means that the widget draws +a decorative border inside the window instead of using the standard +X borders, which are external to the window's area. For example, +internal borders are used to draw 3-D effects. \fIWidth\fR +specifies the width of the border in pixels. Geometry managers will +use this information to avoid placing any children of \fItkwin\fR +overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area. +.PP +\fBTk_SetInternalBorderEx\fR works like \fBTk_SetInternalBorder\fR +but lets you specify different widths for different sides of the window. +.PP +\fBTk_SetMinimumRequestSize\fR is called by widget code to indicate +that a geometry manager should request at least this size for the +widget. This allows a widget to have some control over its size when +a propagating geometry manager is used inside it. +.PP +The information specified in calls to \fBTk_GeometryRequest\fR, +\fBTk_SetMinimumRequestSize\fR, \fBTk_SetInternalBorder\fR and +\fBTk_SetInternalBorderEx\fR can be retrieved using the macros +\fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, \fBTk_MinReqWidth\fR, +\fBTk_MinReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_InternalBorderLeft\fR, +\fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and +\fBTk_InternalBorderBottom\fR. +See the \fBTk_WindowId\fR manual entry for details. +.SH KEYWORDS +geometry, request diff --git a/tk8.6/doc/GetAnchor.3 b/tk8.6/doc/GetAnchor.3 new file mode 100644 index 0000000..6526772 --- /dev/null +++ b/tk8.6/doc/GetAnchor.3 @@ -0,0 +1,89 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR +.sp +int +\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR +.sp +const char * +\fBTk_NameOfAnchor(\fIanchor\fB)\fR +.SH ARGUMENTS +.AS "Tk_Anchor" *anchorPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting, or NULL. +.AP Tcl_Obj *objPtr in/out +String value contains name of anchor point: +.QW \fBn\fR , +.QW \fBne\fR , +.QW \fBe\fR , +.QW \fBse\fR , +.QW \fBs\fR , +.QW \fBsw\fR , +.QW \fBw\fR , +.QW \fBnw\fR , +or +.QW \fBcenter\fR ; +internal rep will be modified to cache corresponding Tk_Anchor. In the +case of +.QW \fBcenter\fR +on input, a non-empty abbreviation of it may also be used on input. +.AP "const char" *string in +Same as \fIobjPtr\fR except description of anchor point is passed as +a string. +.AP int *anchorPtr out +Pointer to location in which to store anchor position corresponding to +\fIobjPtr\fR or \fIstring\fR. +.AP Tk_Anchor anchor in +Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position +(enumerated type \fBTk_Anchor\fR) +corresponding to \fIobjPtr\fR's value. The result will be one of +\fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR, +\fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR, +or \fBTK_ANCHOR_CENTER\fR. +Anchor positions are typically used for indicating a point on an object +that will be used to position the object, e.g. \fBTK_ANCHOR_N\fR means +position the top center point of the object at a particular place. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR does not contain a valid anchor position +or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, +\fI*anchorPtr\fR is unmodified, and an error message is +stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. +\fBTk_GetAnchorFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except +that the description of the anchor is specified with a string instead +of an object. This prevents \fBTk_GetAnchor\fR from caching the +return value, so \fBTk_GetAnchor\fR is less efficient than +\fBTk_GetAnchorFromObj\fR. +.PP +\fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR. +Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a +statically-allocated string corresponding to \fIanchor\fR. +If \fIanchor\fR is not a legal anchor value, then +.QW "unknown anchor position" +is returned. +.SH KEYWORDS +anchor position diff --git a/tk8.6/doc/GetBitmap.3 b/tk8.6/doc/GetBitmap.3 new file mode 100644 index 0000000..c4ac44e --- /dev/null +++ b/tk8.6/doc/GetBitmap.3 @@ -0,0 +1,296 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Pixmap +\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Pixmap +\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR +.sp +Pixmap +\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR +.sp +int +\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR +.sp +const char * +\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR +.sp +\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR +.sp +\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR +.sp +\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR +.SH ARGUMENTS +.AS "unsigned long" *pixelPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting; if NULL then no error message +is left after errors. +.AP Tk_Window tkwin in +Token for window in which the bitmap will be used. +.AP Tcl_Obj *objPtr in/out +String value describes desired bitmap; internal rep will be +modified to cache pointer to corresponding Pixmap. +.AP "const char" *info in +Same as \fIobjPtr\fR except description of bitmap is passed as a string and +resulting Pixmap is not cached. +.AP "const char" *name in +Name for new bitmap to be defined. +.AP "const void" *source in +Data for bitmap, in standard bitmap format. +Must be stored in static memory whose value will never change. +.AP "int" width in +Width of bitmap. +.AP "int" height in +Height of bitmap. +.AP "int" *widthPtr out +Pointer to word to fill in with \fIbitmap\fR's width. +.AP "int" *heightPtr out +Pointer to word to fill in with \fIbitmap\fR's height. +.AP Display *display in +Display for which \fIbitmap\fR was allocated. +.AP Pixmap bitmap in +Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. +.BE +.SH DESCRIPTION +.PP +These procedures manage a collection of bitmaps (one-plane pixmaps) +being used by an application. The procedures allow bitmaps to be +re-used efficiently, thereby avoiding server overhead, and also +allow bitmaps to be named with character strings. +.PP +\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap +that matches the description in \fIobjPtr\fR and is suitable for use +in \fItkwin\fR. It re-uses an existing bitmap, if possible, and +creates a new one otherwise. \fIObjPtr\fR's value must have one +of the following forms: +.TP 20 +\fB@\fIfileName\fR +\fIFileName\fR must be the name of a file containing a bitmap +description in the standard X11 format. +.TP 20 +\fIname\fR +\fIName\fR must be the name of a bitmap defined previously with +a call to \fBTk_DefineBitmap\fR. The following names are pre-defined +by Tk: +.RS +.TP 12 +\fBerror\fR +The international +.QW don't +symbol: a circle with a diagonal line across it. +.TP 12 +\fBgray75\fR +75% gray: a checkerboard pattern where three out of four bits are on. +.TP 12 +\fBgray50\fR +50% gray: a checkerboard pattern where every other bit is on. +.TP 12 +\fBgray25\fR +25% gray: a checkerboard pattern where one out of every four bits is on. +.TP 12 +\fBgray12\fR +12.5% gray: a pattern where one-eighth of the bits are on, consisting of +every fourth pixel in every other row. +.TP 12 +\fBhourglass\fR +An hourglass symbol. +.TP 12 +\fBinfo\fR +A large letter +.QW i . +.TP 12 +\fBquesthead\fR +The silhouette of a human head, with a question mark in it. +.TP 12 +\fBquestion\fR +A large question-mark. +.TP 12 +\fBwarning\fR +A large exclamation point. +.PP +In addition, the following pre-defined names are available only on the +\fBMacintosh\fR platform: +.TP 12 +\fBdocument\fR +A generic document. +.TP 12 +\fBstationery\fR +Document stationery. +.TP 12 +\fBedition\fR +The \fIedition\fR symbol. +.TP 12 +\fBapplication\fR +Generic application icon. +.TP 12 +\fBaccessory\fR +A desk accessory. +.TP 12 +\fBfolder\fR +Generic folder icon. +.TP 12 +\fBpfolder\fR +A locked folder. +.TP 12 +\fBtrash\fR +A trash can. +.TP 12 +\fBfloppy\fR +A floppy disk. +.TP 12 +\fBramdisk\fR +A floppy disk with chip. +.TP 12 +\fBcdrom\fR +A cd disk icon. +.TP 12 +\fBpreferences\fR +A folder with prefs symbol. +.TP 12 +\fBquerydoc\fR +A database document icon. +.TP 12 +\fBstop\fR +A stop sign. +.TP 12 +\fBnote\fR +A face with balloon words. +.TP 12 +\fBcaution\fR +A triangle with an exclamation point. +.RE +.LP +Under normal conditions, \fBTk_AllocBitmapFromObj\fR +returns an identifier for the requested bitmap. If an error +occurs in creating the bitmap, such as when \fIobjPtr\fR refers +to a non-existent file, then \fBNone\fR is returned and an error +message is left in \fIinterp\fR's result if \fIinterp\fR is not +NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR. +.PP +\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except +that the description of the bitmap is specified with a string instead +of an object. This prevents \fBTk_GetBitmap\fR from caching the +return value, so \fBTk_GetBitmap\fR is less efficient than +\fBTk_AllocBitmapFromObj\fR. +.PP +\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given +the window and description used to create the bitmap. +\fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap +must already have been created with a previous call to +\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_DefineBitmap\fR associates a name with +in-memory bitmap data so that the name can be used in later +calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The \fInameId\fR +argument gives a name for the bitmap; it must not previously +have been used in a call to \fBTk_DefineBitmap\fR. +The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR +describe the bitmap. +\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs +(e.g. a bitmap named \fInameId\fR has already been defined) then +\fBTCL_ERROR\fR is returned and an error message is left in +interpreter \fIinterp\fR's result. +Note: \fBTk_DefineBitmap\fR expects the memory pointed to by +\fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make +a private copy of this memory, but uses the bytes pointed to +by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. +.PP +Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a +bitmap file directly into a C program and then referencing +the variables defined by the file. +For example, suppose there exists a file \fBstip.bitmap\fR, +which was created by the \fBbitmap\fR program and contains +a stipple pattern. +The following code uses \fBTk_DefineBitmap\fR to define a +new bitmap named \fBfoo\fR: +.CS +Pixmap bitmap; +#include "stip.bitmap" +Tk_DefineBitmap(interp, "foo", stip_bits, + stip_width, stip_height); +\&... +bitmap = Tk_GetBitmap(interp, tkwin, "foo"); +.CE +This code causes the bitmap file to be read +at compile-time and incorporates the bitmap information into +the program's executable image. The same bitmap file could be +read at run-time using \fBTk_GetBitmap\fR: +.CS +Pixmap bitmap; +bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); +.CE +The second form is a bit more flexible (the file could be modified +after the program has been compiled, or a different string could be +provided to read a different file), but it is a little slower and +requires the bitmap file to exist separately from the program. +.PP +Tk maintains a database of all the bitmaps that are currently in use. +Whenever possible, it will return an existing bitmap rather +than creating a new one. +When a bitmap is no longer used, Tk will release it automatically. +This approach can substantially reduce server overhead, so +\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally +be used in preference to Xlib procedures like \fBXReadBitmapFile\fR. +.PP +The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR +are shared, so callers should never modify them. +If a bitmap must be modified dynamically, then it should be +created by calling Xlib procedures such as \fBXReadBitmapFile\fR +or \fBXCreatePixmap\fR directly. +.PP +The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of +\fBTk_GetBitmap\fR. +Given an X Pixmap argument, it returns the textual description that was +passed to \fBTk_GetBitmap\fR when the bitmap was created. +\fIBitmap\fR must have been the return value from a previous +call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. +.PP +\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR +argument in the words pointed to by the \fIwidthPtr\fR and +\fIheightPtr\fR arguments. As with \fBTk_NameOfBitmap\fR, +\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. +.PP +When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or +\fBTk_FreeBitmap\fR should be called to release it. +For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified +with the same information used to create it; for +\fBTk_FreeBitmap\fR the bitmap to release is specified +with its Pixmap token. +There should be exactly one call to \fBTk_FreeBitmapFromObj\fR +or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. +.SH BUGS +.PP +In determining whether an existing bitmap can be used to satisfy +a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR +consider only the immediate value of the string description. For +example, when a file name is passed to \fBTk_GetBitmap\fR, +\fBTk_GetBitmap\fR will assume it is safe to re-use an existing +bitmap created from the same file name: it will not check to +see whether the file itself has changed, or whether the current +directory has changed, thereby causing the name to refer to +a different file. +.SH KEYWORDS +bitmap, pixmap diff --git a/tk8.6/doc/GetCapStyl.3 b/tk8.6/doc/GetCapStyl.3 new file mode 100644 index 0000000..28f1a1c --- /dev/null +++ b/tk8.6/doc/GetCapStyl.3 @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR +.sp +const char * +\fBTk_NameOfCapStyle(\fIcap\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *capPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP "const char" *string in +String containing name of cap style \- one of +.QW \fBbutt\fR , +.QW \fBprojecting\fR , +or +.QW \fBround\fR +\- or a unique abbreviation of one. +.AP int *capPtr out +Pointer to location in which to store X cap style corresponding to +\fIstring\fR. +.AP int cap in +Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style +corresponding to \fIstring\fR. +This will be one of the values +\fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. +Cap styles are typically used in X graphics contexts to indicate +how the end-points of lines should be capped. +See the X documentation for information on what each style +implies. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR does not contain a valid cap style +or an abbreviation of one of these names, then an error message is +stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and +\fI*capPtr\fR is unmodified. +.PP +\fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. +Given a cap style such as \fBCapButt\fR it returns a +statically-allocated string corresponding to \fIcap\fR. +If \fIcap\fR is not a legal cap style, then +.QW "unknown cap style" +is returned. +.SH KEYWORDS +butt, cap style, projecting, round diff --git a/tk8.6/doc/GetClrmap.3 b/tk8.6/doc/GetClrmap.3 new file mode 100644 index 0000000..9e6da12 --- /dev/null +++ b/tk8.6/doc/GetClrmap.3 @@ -0,0 +1,77 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Colormap +\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR +.sp +\fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR +.sp +\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR +.SH ARGUMENTS +.AS "Colormap" colormap +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which colormap will be used. +.AP "const char" *string in +Selects a colormap: either \fBnew\fR or the name of a window +with the same screen and visual as \fItkwin\fR. +.AP Display *display in +Display for which \fIcolormap\fR was allocated. +.AP Colormap colormap in +Colormap to free or preserve; must have been returned by a previous +call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR. +.BE +.SH DESCRIPTION +.PP +These procedures are used to manage colormaps. +\fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR. +If its \fIstring\fR argument is \fBnew\fR then a new colormap is +created; otherwise \fIstring\fR must be the name of another window +with the same screen and visual as \fItkwin\fR, and the colormap from that +window is returned. +If \fIstring\fR does not make sense, or if it refers to a window on +a different screen from \fItkwin\fR or with +a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns +\fBNone\fR and leaves an error message in \fIinterp\fR's result. +.PP +\fBTk_PreserveColormap\fR increases the internal reference count for a +colormap previously returned by \fBTk_GetColormap\fR, which allows the +colormap to be stored in several locations without knowing which order +they will be released. +.PP +\fBTk_FreeColormap\fR should be called when a colormap returned by +\fBTk_GetColormap\fR is no longer needed. +Tk maintains a reference count for each colormap returned by +\fBTk_GetColormap\fR, so there should eventually be one call to +\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each +call to \fBTk_PreserveColormap\fR. +When a colormap's reference count becomes zero, Tk releases the +X colormap. +.PP +\fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that +a new colormap created by \fBTk_GetVisual\fR may later be returned +by \fBTk_GetColormap\fR. +The reference counting mechanism for colormaps includes both procedures, +so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR +to release the colormap. +If \fBTk_GetColormap\fR is called with a \fIstring\fR value of +\fBnew\fR then the resulting colormap will never +be returned by \fBTk_GetVisual\fR; however, it can be used in other +windows by calling \fBTk_GetColormap\fR with the original window's +name as \fIstring\fR. +.SH KEYWORDS +colormap, visual diff --git a/tk8.6/doc/GetColor.3 b/tk8.6/doc/GetColor.3 new file mode 100644 index 0000000..15254aa --- /dev/null +++ b/tk8.6/doc/GetColor.3 @@ -0,0 +1,176 @@ +'\" +'\" Copyright (c) 1990-1991 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +XColor * +\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +XColor * +\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR +.sp +XColor * +\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR +.sp +XColor * +\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR +.sp +const char * +\fBTk_NameOfColor(\fIcolorPtr\fB)\fR +.sp +GC +\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR +.sp +\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR +.sp +\fBTk_FreeColor(\fIcolorPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *colorPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which color will be used. +.AP Tcl_Obj *objPtr in/out +String value describes desired color; internal rep will be +modified to cache pointer to corresponding (XColor *). +.AP char *name in +Same as \fIobjPtr\fR except description of color is passed as a string and +resulting (XColor *) is not cached. +.AP XColor *prefPtr in +Indicates red, green, and blue intensities of desired +color. +.AP XColor *colorPtr in +Pointer to X color information. Must have been allocated by previous +call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or +\fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR. +.AP Drawable drawable in +Drawable in which the result graphics context will be used. Must have +same screen and depth as the window for which the color was allocated. +.BE +.SH DESCRIPTION +.PP +These procedures manage the colors being used by a Tk application. +They allow colors to be shared whenever possible, so that colormap +space is preserved, and they pick closest available colors when +colormap space is exhausted. +.PP +Given a textual description of a color, \fBTk_AllocColorFromObj\fR +locates a pixel value that may be used to render the color +in a particular window. The desired color is specified with a +value whose string value must have one of the following forms: +.TP 20 +\fIcolorname\fR +Any of the valid textual names for a color defined in the +server's color database file, such as \fBred\fR or \fBPeachPuff\fR. +.TP 20 +\fB#\fIRGB\fR +.TP 20 +\fB#\fIRRGGBB\fR +.TP 20 +\fB#\fIRRRGGGBBB\fR +.TP 20 +\fB#\fIRRRRGGGGBBBB\fR +A numeric specification of the red, green, and blue intensities +to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR +represents a single hexadecimal digit. The four forms permit +colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. +When fewer than 16 bits are provided for each color, they represent +the most significant bits of the color, while the lower unfilled +bits will be repeatedly replicated from the available higher bits. +For example, #3a7 is the same as #3333aaaa7777. +.PP +\fBTk_AllocColorFromObj\fR returns a pointer to +an XColor structure; the structure indicates the exact intensities of +the allocated color (which may differ slightly from those requested, +depending on the limitations of the screen) and a pixel value +that may be used to draw with the color in \fItkwin\fR. +If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown +color name) then NULL is returned and an error message is stored in +\fIinterp\fR's result if \fIinterp\fR is not NULL. +If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR +will use the closest existing color in the colormap. +\fBTk_AllocColorFromObj\fR caches information about +the return value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR. +.PP +\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except +that the description of the color is specified with a string instead +of a value. This prevents \fBTk_GetColor\fR from caching the +return value, so \fBTk_GetColor\fR is less efficient than +\fBTk_AllocColorFromObj\fR. +.PP +\fBTk_GetColorFromObj\fR returns the token for an existing color, given +the window and description used to create the color. +\fBTk_GetColorFromObj\fR does not actually create the color; the color +must already have been created with a previous call to +\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that +the desired color is indicated with the \fIred\fR, \fIgreen\fR, and +\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR. +.PP +This package maintains a database +of all the colors currently in use. +If the same color is requested multiple times from +\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different +windows), or if the +same intensities are requested multiple times from +\fBTk_GetColorByValue\fR, then existing pixel values will +be re-used. Re-using an existing pixel avoids any interaction +with the window server, which makes the allocation much more +efficient. These procedures also provide a portable interface that +works across all platforms. For this reason, you should generally use +\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR +instead of lower level procedures like \fBXAllocColor\fR. +.PP +Since different calls to this package +may return the same shared +pixel value, callers should never change the color of a pixel +returned by the procedures. +If you need to change a color value dynamically, you should use +\fBXAllocColorCells\fR to allocate the pixel value for the color. +.PP +The procedure \fBTk_NameOfColor\fR is roughly the inverse of +\fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created +by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value +is the string that was used to create the +color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR, +or by any other mechanism, then the return value is a string +that could be passed to \fBTk_GetColor\fR to return the same +color. Note: the string returned by \fBTk_NameOfColor\fR is +only guaranteed to persist until the next call to +\fBTk_NameOfColor\fR. +.PP +\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR +field is the pixel allocated for \fIcolorPtr\fR and whose other fields +all have default values. +This provides an easy way to do basic drawing with a color. +The graphics context is cached with the color and will exist only as +long as \fIcolorPtr\fR exists; it is freed when the last reference +to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR. +.PP +When a color is no longer needed \fBTk_FreeColorFromObj\fR or +\fBTk_FreeColor\fR should be called to release it. +For \fBTk_FreeColorFromObj\fR the color to release is specified +with the same information used to create it; for +\fBTk_FreeColor\fR the color to release is specified +with a pointer to its XColor structure. +There should be exactly one call to \fBTk_FreeColorFromObj\fR +or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR, +\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR. +.SH KEYWORDS +color, intensity, value, pixel value diff --git a/tk8.6/doc/GetCursor.3 b/tk8.6/doc/GetCursor.3 new file mode 100644 index 0000000..403c05e --- /dev/null +++ b/tk8.6/doc/GetCursor.3 @@ -0,0 +1,231 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Cursor +\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR +.sp +const char * +\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR +.sp +\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR +.sp +\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR +.SH ARGUMENTS +.AS "unsigned long" *pixelPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which the cursor will be used. +.AP Tcl_Obj *objPtr in/out +Description of cursor; see below for possible values. Internal rep will be +modified to cache pointer to corresponding Tk_Cursor. +.AP char *name in +Same as \fIobjPtr\fR except description of cursor is passed as a string and +resulting Tk_Cursor is not cached. +.AP "const char" *source in +Data for cursor cursor, in standard cursor format. +.AP "const char" *mask in +Data for mask cursor, in standard cursor format. +.AP "int" width in +Width of \fIsource\fR and \fImask\fR. +.AP "int" height in +Height of \fIsource\fR and \fImask\fR. +.AP "int" xHot in +X-location of cursor hot-spot. +.AP "int" yHot in +Y-location of cursor hot-spot. +.AP Tk_Uid fg in +Textual description of foreground color for cursor. +.AP Tk_Uid bg in +Textual description of background color for cursor. +.AP Display *display in +Display for which \fIcursor\fR was allocated. +.AP Tk_Cursor cursor in +Opaque Tk identifier for cursor. If passed to \fBTk_FreeCursor\fR, must +have been returned by some previous call to \fBTk_GetCursor\fR or +\fBTk_GetCursorFromData\fR. +.BE +.SH DESCRIPTION +.PP +These procedures manage a collection of cursors +being used by an application. The procedures allow cursors to be +re-used efficiently, thereby avoiding server overhead, and also +allow cursors to be named with character strings. +.PP +\fBTk_AllocCursorFromObj\fR takes as argument an object describing a +cursor, and returns an opaque Tk identifier for a cursor corresponding +to the description. It re-uses an existing cursor if possible and +creates a new one otherwise. \fBTk_AllocCursorFromObj\fR caches +information about the return value in \fIobjPtr\fR, which speeds up +future calls to procedures such as \fBTk_AllocCursorFromObj\fR and +\fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, +such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR +is returned and an error message will be stored in \fIinterp\fR's result +if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl +list with one of the following forms: +.TP +\fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] +\fIName\fR is the name of a cursor in the standard X cursor cursor, +i.e., any of the names defined in \fBcursorcursor.h\fR, without +the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, +or \fBleft_ptr\fR. Appendix B of +.QW "The X Window System" +by Scheifler & Gettys has illustrations showing what each of these +cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both +specified, they give the foreground and background colors to use +for the cursor (any of the forms acceptable to \fBTk_GetColor\fR +may be used). If only \fIfgColor\fR is specified, then there +will be no background color: the background will be transparent. +If no colors are specified, then the cursor +will use black for its foreground color and white for its background +color. +.RS +.PP +The Macintosh version of Tk supports all of the X cursors and +will also accept any of the standard Mac cursors +including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and +\fBarrow\fR. In addition, Tk will load Macintosh cursor resources of +the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the +name of the resource. The application and all its open +dynamic library's resource files will be searched for the named +cursor. If there are conflicts color cursors will always be loaded +in preference to black and white cursors. +.RE +.TP +\fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR +In this form, \fIsourceName\fR and \fImaskName\fR are the names of +files describing cursors for the cursor's source bits and mask. +Each file must be in standard X11 cursor format. +\fIFgColor\fR and \fIbgColor\fR +indicate the colors to use for the +cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This +form of the command will not work on Macintosh or Windows computers. +.TP +\fB@\fIsourceName\0fgColor\fR +This form is similar to the one above, except that the source is +used as mask also. This means that the cursor's background is +transparent. This form of the command will not work on Macintosh +or Windows computers. +.TP +\fB@\fIsourceName\fR +This form only works on Windows, and will load a Windows system +cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in +\fIsourceName\fR. +.PP +\fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except +that the description of the cursor is specified with a string instead +of an object. This prevents \fBTk_GetCursor\fR from caching the +return value, so \fBTk_GetCursor\fR is less efficient than +\fBTk_AllocCursorFromObj\fR. +.PP +\fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given +the window and description used to create the cursor. +\fBTk_GetCursorFromObj\fR does not actually create the cursor; the cursor +must already have been created with a previous call to +\fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_GetCursorFromData\fR allows cursors to be created from +in-memory descriptions of their source and mask cursors. \fISource\fR +points to standard cursor data for the cursor's source bits, and +\fImask\fR points to standard cursor data describing +which pixels of \fIsource\fR are to be drawn and which are to be +considered transparent. \fIWidth\fR and \fIheight\fR give the +dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the +location of the cursor's hot-spot (the point that is reported when +an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's +foreground and background colors textually (any of the forms +suitable for \fBTk_GetColor\fR may be used). Typically, the +arguments to \fBTk_GetCursorFromData\fR are created by including +a cursor file directly into the source code for a program, as in +the following example: +.CS +Tk_Cursor cursor; +#include "source.cursor" +#include "mask.cursor" +cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, + mask_bits, source_width, source_height, source_x_hot, + source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue")); +.CE +.PP +Under normal conditions \fBTk_GetCursorFromData\fR +will return an identifier for the requested cursor. If an error +occurs in creating the cursor then \fBNone\fR is returned and an error +message will be stored in \fIinterp\fR's result. +.PP +\fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and +\fBTk_GetCursorFromData\fR maintain a +database of all the cursors they have created. Whenever possible, +a call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or +\fBTk_GetCursorFromData\fR will +return an existing cursor rather than creating a new one. This +approach can substantially reduce server overhead, so the Tk +procedures should generally be used in preference to Xlib procedures +like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which +create a new cursor on each call. The Tk procedures are also more +portable than the lower-level X procedures. +.PP +The procedure \fBTk_NameOfCursor\fR is roughly the inverse of +\fBTk_GetCursor\fR. If its \fIcursor\fR argument was created +by \fBTk_GetCursor\fR, then the return value is the \fIname\fR +argument that was passed to \fBTk_GetCursor\fR to create the +cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, +or by any other mechanism, then the return value is a hexadecimal string +giving the X identifier for the cursor. +Note: the string returned by \fBTk_NameOfCursor\fR is +only guaranteed to persist until the next call to +\fBTk_NameOfCursor\fR. Also, this call is not portable except for +cursors returned by \fBTk_GetCursor\fR. +.PP +When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, +or \fBTk_GetCursorFromData\fR +is no longer needed, \fBTk_FreeCursorFromObj\fR or +\fBTk_FreeCursor\fR should be called to release it. +For \fBTk_FreeCursorFromObj\fR the cursor to release is specified +with the same information used to create it; for +\fBTk_FreeCursor\fR the cursor to release is specified +with its Tk_Cursor token. +There should be exactly one call to \fBTk_FreeCursor\fR for +each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, +or \fBTk_GetCursorFromData\fR. +.SH BUGS +.PP +In determining whether an existing cursor can be used to satisfy +a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, +and \fBTk_GetCursorFromData\fR +consider only the immediate values of their arguments. For +example, when a file name is passed to \fBTk_GetCursor\fR, +\fBTk_GetCursor\fR will assume it is safe to re-use an existing +cursor created from the same file name: it will not check to +see whether the file itself has changed, or whether the current +directory has changed, thereby causing the name to refer to +a different file. Similarly, \fBTk_GetCursorFromData\fR assumes +that if the same \fIsource\fR pointer is used in two different calls, +then the pointers refer to the same data; it does not check to +see if the actual data values have changed. +.SH KEYWORDS +cursor diff --git a/tk8.6/doc/GetDash.3 b/tk8.6/doc/GetDash.3 new file mode 100644 index 0000000..d1eeb70 --- /dev/null +++ b/tk8.6/doc/GetDash.3 @@ -0,0 +1,82 @@ +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetDash \- convert from string to valid dash structure. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR + +int +\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR) +.fi +.SH ARGUMENTS +.AS Tk_Dash *dashPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP "const char" *string in +Textual value to be converted. +.AP Tk_Dash *dashPtr out +Points to place to store the dash pattern +value converted from \fIstring\fR. Must not be NULL. +.BE +.SH DESCRIPTION +.PP +These procedure parses the string and fills in the result in the +Tk_Dash structure. The string can be a list of integers or a +character string containing only +.QW \fB.,-_\fR +and spaces. If all +goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored +in the variable pointed to by \fIdashPtr\fR. +If \fIstring\fR does not have the +proper syntax then \fBTCL_ERROR\fR is returned, an error message is left +in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. +.PP +The first possible syntax is a list of integers. Each element +represents the number of pixels of a line segment. Only the odd +segments are drawn using the +.QW outline +color. The other segments are drawn transparent. +.PP +The second possible syntax is a character list containing only +5 possible characters +.QW "\fB.,-_ \fR" . +The space can be used +to enlarge the space between other line elements, and can not +occur in the first position of the string. Some examples: +.PP +.CS + \-dash . = \-dash {2 4} + \-dash - = \-dash {6 4} + \-dash -. = \-dash {6 4 2 4} + \-dash -.. = \-dash {6 4 2 4 2 4} + \-dash {. } = \-dash {2 8} + \-dash , = \-dash {4 4} +.CE +.PP +The main difference between this syntax and the numeric is that it +is shape-conserving. This means that all values in the dash +list will be multiplied by the line width before display. This +ensures that +.QW . +will always be displayed as a dot and +.QW - +always as a dash regardless of the line width. +.PP +On systems where only a limited set of dash patterns, the dash +pattern will be displayed as the most close dash pattern that +is available. For example, on Windows only the first 4 of the +above examples are available; the last 2 examples will be +displayed identically to the first one. +.SH "SEE ALSO" +canvas(n), Tk_CreateItemType(3) +.SH KEYWORDS +dash, conversion diff --git a/tk8.6/doc/GetFont.3 b/tk8.6/doc/GetFont.3 new file mode 100644 index 0000000..0504916 --- /dev/null +++ b/tk8.6/doc/GetFont.3 @@ -0,0 +1,110 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Font +\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Tk_Font +\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR +.sp +Tk_Font +\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR +.sp +const char * +\fBTk_NameOfFont(\fItkfont\fB)\fR +.sp +Tk_Font +\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR +.sp +void +\fBTk_FreeFont(\fItkfont\fB)\fR +.SH ARGUMENTS +.AS "const char" *tkfont +.AP "Tcl_Interp" *interp in +Interpreter to use for error reporting. If \fBNULL\fR, then no error +messages are left after errors. +.AP Tk_Window tkwin in +Token for window in which font will be used. +.AP Tcl_Obj *objPtr in/out +Gives name or description of font. See documentation +for the \fBfont\fR command for details on acceptable formats. +Internal rep will be modified to cache corresponding Tk_Font. +.AP "const char" *string in +Same as \fIobjPtr\fR except description of font is passed as a string and +resulting Tk_Font is not cached. +.AP Tk_Font tkfont in +Opaque font token. +.BE +.SH DESCRIPTION +.PP +\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and +returns a token that represents the font. The return value can be used +in subsequent calls to procedures such as \fBTk_GetFontMetrics\fR, +\fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR. The Tk_Font token +will remain valid until +\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. +\fIObjPtr\fR can contain either a symbolic name or a font description; see +the documentation for the \fBfont\fR command for a description of the +valid formats. If \fBTk_AllocFontFromObj\fR is unsuccessful (because, +for example, \fIobjPtr\fR did not contain a valid font specification) then it +returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result +if \fIinterp\fR is not \fBNULL\fR. \fBTk_AllocFontFromObj\fR caches +information about the return +value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR. +.PP +\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except +that the description of the font is specified with a string instead +of an object. This prevents \fBTk_GetFont\fR from caching the +matching Tk_Font, so \fBTk_GetFont\fR is less efficient than +\fBTk_AllocFontFromObj\fR. +.PP +\fBTk_GetFontFromObj\fR returns the token for an existing font, given +the window and description used to create the font. +\fBTk_GetFontFromObj\fR does not actually create the font; the font +must already have been created with a previous call to +\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain +a database of all fonts they have allocated. If +the same font is requested multiple times (e.g. by different +windows or for different purposes), then a single Tk_Font will be +shared for all uses. The underlying resources will be freed automatically +when no-one is using the font anymore. +.PP +The procedure \fBTk_NameOfFont\fR is roughly the inverse of +\fBTk_GetFont\fR. Given a \fItkfont\fR that was created by +\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is +the \fIstring\fR argument that was +passed to \fBTk_GetFont\fR to create the font. The string returned by +\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR +is deleted. The caller must not modify this string. +.PP +When a font is no longer needed, +\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to +release it. For \fBTk_FreeFontFromObj\fR the font to release is specified +with the same information used to create it; for +\fBTk_FreeFont\fR the font to release is specified +with its Tk_Font token. There should be +exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR +for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. +.SH "SEE ALSO" +Tk_FontId(3) +.SH KEYWORDS +font diff --git a/tk8.6/doc/GetGC.3 b/tk8.6/doc/GetGC.3 new file mode 100644 index 0000000..44e06fb --- /dev/null +++ b/tk8.6/doc/GetGC.3 @@ -0,0 +1,70 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetGC 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +GC +\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) +.sp +\fBTk_FreeGC(\fIdisplay, gc\fR) +.SH ARGUMENTS +.AS "unsigned long" valueMask +.AP Tk_Window tkwin in +Token for window in which the graphics context will be used. +.AP "unsigned long" valueMask in +Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) +indicating which fields of \fI*valuePtr\fR are valid. +.AP XGCValues *valuePtr in +Pointer to structure describing the desired values for the +graphics context. +.AP Display *display in +Display for which \fIgc\fR was allocated. +.AP GC gc in +X identifier for graphics context that is no longer needed. +Must have been allocated by \fBTk_GetGC\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts +being used by an application. The procedures allow graphics contexts to be +shared, thereby avoiding the server overhead that would be incurred +if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments +describing the desired graphics context and returns an X identifier +for a GC that fits the description. The graphics context that is returned +will have default values in all of the fields not specified explicitly +by \fIvalueMask\fR and \fIvaluePtr\fR. +.PP +\fBTk_GetGC\fR maintains a +database of all the graphics contexts it has created. Whenever possible, +a call to \fBTk_GetGC\fR will +return an existing graphics context rather than creating a new one. This +approach can substantially reduce server overhead, so \fBTk_GetGC\fR +should generally be used in preference to the Xlib procedure +\fBXCreateGC\fR, which creates a new graphics context on each call. +.PP +Since the return values of \fBTk_GetGC\fR +are shared, callers should never modify the graphics contexts +returned by \fBTk_GetGC\fR. +If a graphics context must be modified dynamically, then it should be +created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR. +.PP +When a graphics context +is no longer needed, \fBTk_FreeGC\fR should be called to release it. +There should be exactly one call to \fBTk_FreeGC\fR for +each call to \fBTk_GetGC\fR. +When a graphics context is no longer in use anywhere (i.e. it has +been freed as many times as it has been gotten) \fBTk_FreeGC\fR +will release it to the X server and delete it from the database. +.SH KEYWORDS +graphics context diff --git a/tk8.6/doc/GetHINSTANCE.3 b/tk8.6/doc/GetHINSTANCE.3 new file mode 100644 index 0000000..de38051 --- /dev/null +++ b/tk8.6/doc/GetHINSTANCE.3 @@ -0,0 +1,22 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetHINSTANCE \- retrieve the global application instance handle +.SH SYNOPSIS +.nf +\fB#include <tkPlatDecls.h>\fR +.sp +HINSTANCE +\fBTk_GetHINSTANCE\fR() +.BE +.SH DESCRIPTION +.PP +\fBTk_GetHINSTANCE\fR returns the Windows application instance handle +for the Tk application. This function is only available on Windows platforms. +.SH KEYWORDS +identifier, instance diff --git a/tk8.6/doc/GetHWND.3 b/tk8.6/doc/GetHWND.3 new file mode 100644 index 0000000..1a5ec2d --- /dev/null +++ b/tk8.6/doc/GetHWND.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH HWND 3 8.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetHWND, Tk_AttachHWND \- manage interactions between the Windows handle and an X window +.SH SYNOPSIS +.nf +\fB#include <tkPlatDecls.h>\fR +.sp +HWND +\fBTk_GetHWND\fR(\fIwindow\fR) +.sp +Window +\fBTk_AttachHWND\fR(\fItkwin, hwnd\fR) +.SH ARGUMENTS +.AP Window window in +X token for window. +.AP Tk_Window tkwin in +Tk window for window. +.AP HWND hwnd in +Windows HWND for window. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetHWND\fR returns the Windows HWND identifier for X Windows +window given by \fIwindow\fR. +.PP +\fBTk_AttachHWND\fR binds the Windows HWND identifier to the +specified Tk_Window given by \fItkwin\fR. It returns an X Windows +window that encapsulates the HWND. +.SH KEYWORDS +identifier, window diff --git a/tk8.6/doc/GetImage.3 b/tk8.6/doc/GetImage.3 new file mode 100644 index 0000000..f2407bc --- /dev/null +++ b/tk8.6/doc/GetImage.3 @@ -0,0 +1,130 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Image +\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) +.sp +\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) +.sp +\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) +.sp +\fBTk_FreeImage\fR(\fIimage\fR) +.SH ARGUMENTS +.AS Tk_ImageChangedProc *changeProc +.AP Tcl_Interp *interp in +Place to leave error message. +.AP Tk_Window tkwin in +Window in which image will be used. +.AP "const char" *name in +Name of image. +.AP Tk_ImageChangedProc *changeProc in +Procedure for Tk to invoke whenever image content or size changes. +.AP ClientData clientData in +One-word value for Tk to pass to \fIchangeProc\fR. +.AP Tk_Image image in +Token for image instance; must have been returned by a previous +call to \fBTk_GetImage\fR. +.AP int imageX in +X-coordinate of upper-left corner of region of image to redisplay +(measured in pixels from the image's upper-left corner). +.AP int imageY in +Y-coordinate of upper-left corner of region of image to redisplay +(measured in pixels from the image's upper-left corner). +.AP "int" width (in) +Width of region of image to redisplay. +.AP "int" height (in) +Height of region of image to redisplay. +.AP Drawable drawable in +Where to display image. Must either be window specified to +\fBTk_GetImage\fR or a pixmap compatible with that window. +.AP int drawableX in +Where to display image in \fIdrawable\fR: this is the x-coordinate +in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image +should be displayed. +.AP int drawableY in +Where to display image in \fIdrawable\fR: this is the y-coordinate +in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image +should be displayed. +.AP "int" widthPtr out +Store width of \fIimage\fR (in pixels) here. +.AP "int" heightPtr out +Store height of \fIimage\fR (in pixels) here. +.BE +.SH DESCRIPTION +.PP +These procedures are invoked by widgets that wish to display images. +\fBTk_GetImage\fR is invoked by a widget when it first decides to +display an image. +\fIname\fR gives the name of the desired image and \fItkwin\fR +identifies the window where the image will be displayed. +\fBTk_GetImage\fR looks up the image in the table of existing +images and returns a token for a new instance of the image. +If the image does not exist then \fBTk_GetImage\fR returns NULL +and leaves an error message in interpreter \fIinterp\fR's result. +.PP +When a widget wishes to actually display an image it must +call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR), +a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR, +\fIwidth\fR, and \fIheight\fR), and a place to display the +image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR). +Tk will then invoke the appropriate image manager, which will +display the requested portion of the image before returning. +.PP +A widget can find out the dimensions of an image by calling +\fBTk_SizeOfImage\fR: the width and height will be stored +in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR, +respectively. +.PP +When a widget is finished with an image (e.g., the widget is +being deleted or it is going to use a different image instead +of the current one), it must call \fBTk_FreeImage\fR to +release the image instance. +The widget should never again use the image token after passing +it to \fBTk_FreeImage\fR. +There must be exactly one call to \fBTk_FreeImage\fR for each +call to \fBTk_GetImage\fR. +.PP +If the contents or size of an image changes, then any widgets +using the image will need to find out about the changes so that +they can redisplay themselves. +The \fIchangeProc\fR and \fIclientData\fR arguments to +\fBTk_GetImage\fR are used for this purpose. +\fIchangeProc\fR will be called by Tk whenever a change occurs +in the image; it must match the following prototype: +.CS +typedef void \fBTk_ImageChangedProc\fR( + ClientData \fIclientData\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIimageWidth\fR, + int \fIimageHeight\fR); +.CE +The \fIclientData\fR argument to \fIchangeProc\fR is the same as the +\fIclientData\fR argument to \fBTk_GetImage\fR. +It is usually a pointer to the widget record for the widget or +some other data structure managed by the widget. +The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +identify a region within the image that must be redisplayed; +they are specified in pixels measured from the upper-left +corner of the image. +The arguments \fIimageWidth\fR and \fIimageHeight\fR give +the image's (new) size. +.SH "SEE ALSO" +Tk_CreateImageType +.SH KEYWORDS +images, redisplay diff --git a/tk8.6/doc/GetJoinStl.3 b/tk8.6/doc/GetJoinStl.3 new file mode 100644 index 0000000..a717b72 --- /dev/null +++ b/tk8.6/doc/GetJoinStl.3 @@ -0,0 +1,63 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR +.sp +const char * +\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP "const char" *string in +String containing name of join style \- one of +.QW \fBbevel\fR , +.QW \fBmiter\fR , +or +.QW \fBround\fR +\- or a unique abbreviation of one. +.AP int *joinPtr out +Pointer to location in which to store X join style corresponding to +\fIstring\fR. +.AP int join in +Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style +corresponding to \fIstring\fR, which will be one of +\fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR. +Join styles are typically used in X graphics contexts to indicate +how adjacent line segments should be joined together. +See the X documentation for information on what each style +implies. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR does not contain a valid join style +or an abbreviation of one of these names, then an error message is +stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and +\fI*joinPtr\fR is unmodified. +.PP +\fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. +Given a join style such as \fBJoinBevel\fR it returns a +statically-allocated string corresponding to \fIjoin\fR. +If \fIjoin\fR is not a legal join style, then +.QW "unknown join style" +is returned. +.SH KEYWORDS +bevel, join style, miter, round diff --git a/tk8.6/doc/GetJustify.3 b/tk8.6/doc/GetJustify.3 new file mode 100644 index 0000000..b51cb8d --- /dev/null +++ b/tk8.6/doc/GetJustify.3 @@ -0,0 +1,87 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR +.sp +int +\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR +.sp +const char * +\fBTk_NameOfJustify(\fIjustify\fB)\fR +.SH ARGUMENTS +.AS "Tk_Justify" *justifyPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting, or NULL. +.AP Tcl_Obj *objPtr in/out +String value contains name of justification style \- one of +.QW \fBleft\fR , +.QW \fBright\fR , +or +.QW \fBcenter\fR +\- or a unique abbreviation of one. +The internal rep will be modified to cache corresponding justify value. +.AP "const char" *string in +Same as \fIobjPtr\fR except description of justification style is passed as +a string. +.AP int *justifyPtr out +Pointer to location in which to store justify value corresponding to +\fIobjPtr\fR or \fIstring\fR. +.AP Tk_Justify justify in +Justification style (one of the values listed below). +.BE +.SH DESCRIPTION +.PP +\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value +corresponding to \fIobjPtr\fR's value. +This value will be one of the following: +.TP +\fBTK_JUSTIFY_LEFT\fR +Means that the text on each line should start at the left edge of +the line; as a result, the right edges of lines may be ragged. +.TP +\fBTK_JUSTIFY_RIGHT\fR +Means that the text on each line should end at the right edge of +the line; as a result, the left edges of lines may be ragged. +.TP +\fBTK_JUSTIFY_CENTER\fR +Means that the text on each line should be centered; as a result, +both the left and right edges of lines may be ragged. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIobjPtr\fR does not contain a valid justification style +or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, +\fI*justifyPtr\fR is unmodified, and an error message is +stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. +\fBTk_GetJustifyFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except +that the description of the justification is specified with a string instead +of an object. This prevents \fBTk_GetJustify\fR from caching the +return value, so \fBTk_GetJustify\fR is less efficient than +\fBTk_GetJustifyFromObj\fR. +.PP +\fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR. +Given a justify value it returns a statically-allocated string +corresponding to \fIjustify\fR. +If \fIjustify\fR is not a legal justify value, then +.QW "unknown justification style" +is returned. +.SH KEYWORDS +center, fill, justification, string diff --git a/tk8.6/doc/GetOption.3 b/tk8.6/doc/GetOption.3 new file mode 100644 index 0000000..81846ad --- /dev/null +++ b/tk8.6/doc/GetOption.3 @@ -0,0 +1,42 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetOption 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetOption \- retrieve an option from the option database +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Uid +\fBTk_GetOption\fR(\fItkwin, name, class\fR) +.SH ARGUMENTS +.AS Tk_Window *class +.AP Tk_Window tkwin in +Token for window. +.AP "const char" *name in +Name of desired option. +.AP "const char" *class in +Class of desired option. Null means there is no class for +this option; do lookup based on name only. +.BE +.SH DESCRIPTION +.PP +This procedure is invoked to retrieve an option from the database +associated with \fItkwin\fR's main window. If there is an option +for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR, +then it is returned in the form of a Tk_Uid. If multiple options +match \fIname\fR and \fIclass\fR, then the highest-priority one +is returned. If no option matches, then NULL is returned. +.PP +\fBTk_GetOption\fR caches options related to \fItkwin\fR so that +successive calls for the same \fItkwin\fR will execute much more +quickly than successive calls for different windows. +.SH KEYWORDS +class, name, option, retrieve diff --git a/tk8.6/doc/GetPixels.3 b/tk8.6/doc/GetPixels.3 new file mode 100644 index 0000000..e7a9043 --- /dev/null +++ b/tk8.6/doc/GetPixels.3 @@ -0,0 +1,95 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR +.sp +int +\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR +.sp +int +\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR +.sp +int +\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Window whose screen geometry determines the conversion between absolute +units and pixels. +.AP Tcl_Obj *objPtr in/out +String value specifies a distance on the screen; +internal rep will be modified to cache converted distance. +.AP "const char" *string in +Same as \fIobjPtr\fR except specification of distance is passed as +a string. +.AP int *intPtr out +Pointer to location in which to store converted distance in pixels. +.AP double *doublePtr out +Pointer to location in which to store converted distance in millimeters. +.BE +.SH DESCRIPTION +.PP +These procedures take as argument a specification of distance on +the screen (\fIobjPtr\fR or \fIstring\fR) and compute the +corresponding distance either in integer pixels or floating-point millimeters. +In either case, +\fIobjPtr\fR or \fIstring\fR +specifies a screen distance as a +floating-point number followed by one of the following characters +that indicates units: +.TP +<none> +The number specifies a distance in pixels. +.TP +\fBc\fR +The number specifies a distance in centimeters on the screen. +.TP +\fBi\fR +The number specifies a distance in inches on the screen. +.TP +\fBm\fR +The number specifies a distance in millimeters on the screen. +.TP +\fBp\fR +The number specifies a distance in printer's points (1/72 inch) +on the screen. +.PP +\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the +nearest even number of pixels and stores that value at \fI*intPtr\fR. +It returns \fBTCL_OK\fR under normal circumstances. +If an error occurs (e.g. \fIobjPtr\fR contains a number followed +by a character that is not one of the ones above) then +\fBTCL_ERROR\fR is returned and an error message is left +in \fIinterp\fR's result if \fIinterp\fR is not NULL. +\fBTk_GetPixelsFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except +that the screen distance is specified with a string instead +of an object. This prevents \fBTk_GetPixels\fR from caching the +return value, so \fBTk_GetPixels\fR is less efficient than +\fBTk_GetPixelsFromObj\fR. +.PP +\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to +\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except +that they convert the screen distance to millimeters and +store a double-precision floating-point result at \fI*doublePtr\fR. +.SH KEYWORDS +centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/tk8.6/doc/GetPixmap.3 b/tk8.6/doc/GetPixmap.3 new file mode 100644 index 0000000..927c75c --- /dev/null +++ b/tk8.6/doc/GetPixmap.3 @@ -0,0 +1,52 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Pixmap +\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR +.sp +\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR +.SH ARGUMENTS +.AS "Drawable" *pixelPtr +.AP Display *display in +X display for the pixmap. +.AP Drawable d in +Pixmap or window where the new pixmap will be used for drawing. +.AP "int" width in +Width of pixmap. +.AP "int" height in +Height of pixmap. +.AP "int" depth in +Number of bits per pixel in pixmap. +.AP Pixmap pixmap in +Pixmap to destroy. +.BE +.SH DESCRIPTION +.PP +These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR +and \fBXFreePixmap\fR, except that they have extra code to manage X +resource identifiers so that identifiers for deleted pixmaps can be +reused in the future. +It is important for Tk applications to use these procedures rather +than \fBXCreatePixmap\fR and \fBXFreePixmap\fR; otherwise long-running +applications may run out of resource identifiers. +.PP +\fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR, +with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, +and returns its identifier. +\fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes +its resource identifier available for reuse. +.SH KEYWORDS +pixmap, resource identifier diff --git a/tk8.6/doc/GetRelief.3 b/tk8.6/doc/GetRelief.3 new file mode 100644 index 0000000..6e8681a --- /dev/null +++ b/tk8.6/doc/GetRelief.3 @@ -0,0 +1,82 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR +.sp +int +\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR +.sp +const char * +\fBTk_NameOfRelief(\fIrelief\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *reliefPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tcl_Obj *objPtr in/out +String value contains name of relief, one of +.QW \fBflat\fR , +.QW \fBgroove\fR , +.QW \fBraised\fR , +.QW \fBridge\fR , +.QW \fBsolid\fR , +or +.QW \fBsunken\fR +(or any unique abbreviation thereof on input); +the internal rep will be modified to cache corresponding relief value. +.AP char *string in +Same as \fIobjPtr\fR except description of relief is passed as +a string. +.AP int *reliefPtr out +Pointer to location in which to store relief value corresponding to +\fIobjPtr\fR or \fIname\fR. +.AP "const char" *name +Name of the relief. +.AP int relief in +Relief value (one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, +\fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, +or \fBTK_RELIEF_RIDGE\fR). +.BE +.SH DESCRIPTION +.PP +\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value +corresponding to the value of \fIobjPtr\fR. This value will be one of +\fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, +\fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR. +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIobjPtr\fR does not contain one of the valid relief names +or an abbreviation of one of them, then \fBTCL_ERROR\fR is returned, +\fI*reliefPtr\fR is unmodified, and an error message +is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. +\fBTk_GetReliefFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except +that the description of the relief is specified with a string instead +of an object. This prevents \fBTk_GetRelief\fR from caching the +return value, so \fBTk_GetRelief\fR is less efficient than +\fBTk_GetReliefFromObj\fR. +.PP +\fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR. +Given a relief value it returns the corresponding string (\fBflat\fR, +\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR). +If \fIrelief\fR is not a legal relief value, then +.QW "unknown relief" +is returned. +.SH KEYWORDS +name, relief, string diff --git a/tk8.6/doc/GetRootCrd.3 b/tk8.6/doc/GetRootCrd.3 new file mode 100644 index 0000000..a9d2cd9 --- /dev/null +++ b/tk8.6/doc/GetRootCrd.3 @@ -0,0 +1,39 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetRootCoords \- Compute root-window coordinates of window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for window. +.AP int *xPtr out +Pointer to location in which to store root-window x-coordinate +corresponding to left edge of \fItkwin\fR's border. +.AP int *yPtr out +Pointer to location in which to store root-window y-coordinate +corresponding to top edge of \fItkwin\fR's border. +.BE +.SH DESCRIPTION +.PP +This procedure scans through the structural information maintained +by Tk to compute the root-window coordinates corresponding to +the upper-left corner of \fItkwin\fR's border. If \fItkwin\fR has +no border, then \fBTk_GetRootCoords\fR returns the root-window +coordinates corresponding to location (0,0) in \fItkwin\fR. +\fBTk_GetRootCoords\fR is relatively efficient, since it does not have to +communicate with the X server. +.SH KEYWORDS +coordinates, root window diff --git a/tk8.6/doc/GetScroll.3 b/tk8.6/doc/GetScroll.3 new file mode 100644 index 0000000..abd0880 --- /dev/null +++ b/tk8.6/doc/GetScroll.3 @@ -0,0 +1,75 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR +.sp +int +\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *fractionPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP int objc in +Number of Tcl_Obj's in \fIobjv\fR array. +.AP "Tcl_Obj *const" objv[] in +Argument objects. These represent the entire widget command, of +which the first word is typically the widget name and the second +word is typically \fBxview\fR or \fByview\fR. +.AP int argc in +Number of strings in \fIargv\fR array. +.AP "const char" *argv[] in +Argument strings. These represent the entire widget command, of +which the first word is typically the widget name and the second +word is typically \fBxview\fR or \fByview\fR. +.AP double *fractionPtr out +Filled in with fraction from \fBmoveto\fR option, if any. +.AP int *stepsPtr out +Filled in with line or page count from \fBscroll\fR option, if any. +The value may be negative. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetScrollInfoObj\fR parses the arguments expected by widget +scrolling commands such as \fBxview\fR and \fByview\fR. +It receives the entire list of words that make up a widget command +and parses the words starting with \fIobjv\fR[2]. +The words starting with \fIobjv\fR[2] must have one of the following forms: +.CS +\fBmoveto \fIfraction\fR +\fBscroll \fInumber\fB units\fR +\fBscroll \fInumber\fB pages\fR +.CE +.LP +Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR +keywords may be abbreviated. +If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR +is returned as result and \fI*fractionPtr\fR is filled in with the +\fIfraction\fR argument to the command, which must be a proper real +value. +If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR +or \fBTK_SCROLL_PAGES\fR is returned and \fI*stepsPtr\fR is filled +in with the \fInumber\fR value, which must be a proper integer. +If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR +is returned and an error message is left in interpreter +\fIinterp\fR's result. +.PP +\fBTk_GetScrollInfo\fR is identical in function to +\fBTk_GetScrollInfoObj\fR. However, \fBTk_GetScrollInfo\fR accepts +string arguments, making it more appropriate for use with legacy +widgets. +.SH KEYWORDS +parse, scrollbar, scrolling command, xview, yview diff --git a/tk8.6/doc/GetSelect.3 b/tk8.6/doc/GetSelect.3 new file mode 100644 index 0000000..8c30a2b --- /dev/null +++ b/tk8.6/doc/GetSelect.3 @@ -0,0 +1,78 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetSelection \- retrieve the contents of a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) +.SH ARGUMENTS +.AS Tk_GetSelProc clientData +.AP Tcl_Interp *interp in +Interpreter to use for reporting errors. +.AP Tk_Window tkwin in +Window on whose behalf to retrieve the selection (determines +display from which to retrieve). +.AP Atom selection in +The name of the selection to be retrieved. +.AP Atom target in +Form in which to retrieve selection. +.AP Tk_GetSelProc *proc in +Procedure to invoke to process pieces of the selection as they +are retrieved. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetSelection\fR retrieves the selection specified by the atom +\fIselection\fR in the format specified by \fItarget\fR. The +selection may actually be retrieved in several pieces; as each piece +is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR +should have arguments and result that match the type +\fBTk_GetSelProc\fR: +.PP +.CS +typedef int \fBTk_GetSelProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + char *\fIportion\fR); +.CE +.PP +The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR +will be copies of the corresponding arguments to +\fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to +a string containing part or all of the selection. For large +selections, \fIproc\fR will be called several times with successive +portions of the selection. The X Inter-Client Communication +Conventions Manual allows a selection to be returned in formats +other than strings, e.g. as an array of atoms or integers. If +this happens, Tk converts the selection back into a string +before calling \fIproc\fR. If a selection is returned as an +array of atoms, Tk converts it to a string containing the atom names +separated by white space. For any other format besides string, +Tk converts a selection to a string containing hexadecimal +values separated by white space. +.PP +\fBTk_GetSelection\fR returns to its caller when the selection has +been completely retrieved and processed by \fIproc\fR, or when a +fatal error has occurred (e.g. the selection owner did not respond +promptly). \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR; if +an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message +in interpreter \fIinterp\fR's result. \fIProc\fR should also return either +\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in +dealing with the selection, it should leave an error message in the +interpreter result and return \fBTCL_ERROR\fR; this will abort the +selection retrieval. +.SH KEYWORDS +format, get, selection retrieval diff --git a/tk8.6/doc/GetUid.3 b/tk8.6/doc/GetUid.3 new file mode 100644 index 0000000..06b466a --- /dev/null +++ b/tk8.6/doc/GetUid.3 @@ -0,0 +1,45 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetUid 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetUid, Tk_Uid \- convert from string to unique identifier +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Uid +\fBTk_GetUid\fR(\fIstring\fR) +.SH ARGUMENTS +.AP char *string in +String for which the corresponding unique identifier is +desired. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetUid\fR returns the unique identifier corresponding +to \fIstring\fR. +Unique identifiers are similar to atoms in Lisp, and are used +in Tk to speed up comparisons and +searches. A unique identifier (type Tk_Uid) is a string pointer +and may be used anywhere that a variable of type +.QW "char *" +could be used. However, there is guaranteed to be exactly +one unique identifier for any given string value. If \fBTk_GetUid\fR +is called twice, once with string \fIa\fR and once with string +\fIb\fR, and if \fIa\fR and \fIb\fR have the same string value +(strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly +the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). +This means that variables of type +Tk_Uid may be compared directly (x == y) without having to call +\fBstrcmp\fR. +In addition, the return value from \fBTk_GetUid\fR will have the +same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). +.SH KEYWORDS +atom, unique identifier diff --git a/tk8.6/doc/GetVRoot.3 b/tk8.6/doc/GetVRoot.3 new file mode 100644 index 0000000..a65ef78 --- /dev/null +++ b/tk8.6/doc/GetVRoot.3 @@ -0,0 +1,46 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetVRootGeometry \- Get location and size of virtual root for window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR +.SH ARGUMENTS +.AS Tk_Window heightPtr +.AP Tk_Window tkwin in +Token for window whose virtual root is to be queried. +.AP int xPtr out +Points to word in which to store x-offset of virtual root. +.AP int yPtr out +Points to word in which to store y-offset of virtual root. +.AP "int" widthPtr out +Points to word in which to store width of virtual root. +.AP "int" heightPtr out +Points to word in which to store height of virtual root. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetVRootGeometry\fR returns geometry information about the virtual +root window associated with \fItkwin\fR. The +.QW associated +virtual root is the one in which \fItkwin\fR's nearest top-level ancestor (or +\fItkwin\fR itself if it is a top-level window) has +been reparented by the window manager. This window is identified by +a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level +window by the window manager. +If \fItkwin\fR is not associated with a virtual root (e.g. +because the window manager does not use virtual roots) then *\fIxPtr\fR and +*\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR +will be set to the dimensions of the screen containing \fItkwin\fR. +.SH KEYWORDS +geometry, height, location, virtual root, width, window manager diff --git a/tk8.6/doc/GetVisual.3 b/tk8.6/doc/GetVisual.3 new file mode 100644 index 0000000..fe3d50c --- /dev/null +++ b/tk8.6/doc/GetVisual.3 @@ -0,0 +1,100 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetVisual \- translate from string to visual +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Visual * +\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *colormapPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which the visual will be used. +.AP "const char" *string in +String that identifies the desired visual. See below for +valid formats. +.AP int *depthPtr out +Depth of returned visual gets stored here. +.AP Colormap *colormapPtr out +If non-NULL then a suitable colormap for visual is found and its +identifier is stored here. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetVisual\fR takes a string description of a visual and +finds a suitable X Visual for use in \fItkwin\fR, if there is one. +It returns a pointer to the X Visual structure for the visual +and stores the number of bits per pixel for it at \fI*depthPtr\fR. +If \fIstring\fR is unrecognizable or if no suitable visual could +be found, then NULL is returned and \fBTk_GetVisual\fR leaves +an error message in interpreter \fIinterp\fR's result. +If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR +also locates an appropriate colormap for use with the result visual +and stores its X identifier at \fI*colormapPtr\fR. +.PP +The \fIstring\fR argument specifies the desired visual in one +of the following ways: +.TP 15 +\fIclass depth\fR +The string consists of a class name followed by an integer depth, +with any amount of white space (including none) in between. +\fIclass\fR selects what sort of visual is desired and must be one of +\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, +\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or +\fBtruecolor\fR, or a unique abbreviation. +\fIdepth\fR specifies how many bits per pixel are needed for the +visual. +If possible, \fBTk_GetVisual\fR will return a visual with this depth; +if there is no visual of the desired depth then \fBTk_GetVisual\fR +looks first for a visual with greater depth, then one with less +depth. +.TP 15 +\fBdefault\fR +Use the default visual for \fItkwin\fR's screen. +.TP 15 +\fIpathName\fR +Use the visual for the window given by \fIpathName\fR. +\fIpathName\fR must be the name of a window on the same screen +as \fItkwin\fR. +.TP 15 +\fInumber\fR +Use the visual whose X identifier is \fInumber\fR. +.TP 15 +\fBbest\fR ?\fIdepth\fR? +Choose the +.QW "best possible" +visual, using the following rules, in decreasing order of priority: +.RS +.IP (a) +a visual that has exactly the desired depth is best, followed +by a visual with greater depth than requested (but as little extra +as possible), followed by a visual with less depth than requested +(but as great a depth as possible); +.IP (b) +if no \fIdepth\fR is specified, then the deepest available visual +is chosen; +.IP (c) +\fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, +which are better than \fBstaticcolor\fR, which is better than +\fBstaticgray\fR or \fBgrayscale\fR; +.IP (d) +the default visual for the screen is better than any other visual. +.RE +.SH CREDITS +.PP +The idea for \fBTk_GetVisual\fR, and the first implementation, came +from Paul Mackerras. +.SH KEYWORDS +colormap, screen, visual diff --git a/tk8.6/doc/Grab.3 b/tk8.6/doc/Grab.3 new file mode 100644 index 0000000..1dba2df --- /dev/null +++ b/tk8.6/doc/Grab.3 @@ -0,0 +1,58 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH Tk_Grab 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_Grab, Tk_Ungrab \- manipulate grab state in an application +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) +.sp +void +\fBTk_Ungrab\fR(\fItkwin\fR) +.SH ARGUMENTS +.AP Tcl_Interp *interp in +Interpreter to use for error reporting +.AP Tk_Window tkwin in +Window on whose behalf the pointer is to be grabbed or released +.AP int grabGlobal in +Boolean indicating whether the grab is global or application local +.BE +.SH DESCRIPTION +.PP +These functions are used to set or release a global or +application local grab. When a grab is set on a particular window +in a Tk application, mouse and keyboard events can only be received by +that window and its descendants. Mouse and keyboard events for +windows outside the tree rooted at \fItkwin\fR will be redirected to +\fItkwin\fR. If the grab is global, then all mouse and keyboard +events for windows outside the tree rooted at \fItkwin\fR (even those +intended for windows in other applications) will be redirected to +\fItkwin\fR. If the grab is application local, only mouse and +keyboard events intended for a windows within the same application +(but outside the tree rooted at \fItkwin\fR) will be redirected. +.PP +\fBTk_Grab\fR sets a grab on a particular window. \fITkwin\fR +specifies the window on whose behalf the pointer is to be grabbed. +\fIGrabGlobal\fR indicates whether the grab should be global or +application local; if it is non-zero, it means the grab should be +global. Normally, \fBTk_Grab\fR returns \fBTCL_OK\fR; if an error occurs +and the grab cannot be set, \fBTCL_ERROR\fR is returned and an error message +is left if \fIinterp\fR's result. Once this call completes +successfully, no window outside the tree rooted at \fItkwin\fR will +receive pointer- or keyboard-related events until the next call to +Tk_Ungrab. If a previous grab was in effect within the application, +then it is replaced with a new one. +.PP +\fBTk_Ungrab\fR releases a grab on the mouse pointer and keyboard, if +there is one set on the window given by \fItkwin\fR. Once a grab is +released, pointer and keyboard events will start being delivered to +other windows again. +.SH KEYWORDS +grab, window diff --git a/tk8.6/doc/HWNDToWindow.3 b/tk8.6/doc/HWNDToWindow.3 new file mode 100644 index 0000000..9795099 --- /dev/null +++ b/tk8.6/doc/HWNDToWindow.3 @@ -0,0 +1,26 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_HWNDToWindow \- Find Tk's window information for a Windows window +.SH SYNOPSIS +.nf +\fB#include <tkPlatDecls.h>\fR +.sp +Tk_Window +\fBTk_HWNDToWindow\fR(\fIhwnd\fR) +.SH ARGUMENTS +.AP HWND hwnd in +Windows handle for the window. +.BE +.SH DESCRIPTION +.PP +Given a Windows HWND window identifier, this procedure returns the +corresponding Tk_Window handle. If there is no Tk_Window corresponding +to \fIhwnd\fR then NULL is returned. +.SH KEYWORDS +Windows window id diff --git a/tk8.6/doc/HandleEvent.3 b/tk8.6/doc/HandleEvent.3 new file mode 100644 index 0000000..bc293b6 --- /dev/null +++ b/tk8.6/doc/HandleEvent.3 @@ -0,0 +1,46 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_HandleEvent \- invoke event handlers for window system events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_HandleEvent\fR(\fIeventPtr\fR) +.SH ARGUMENTS +.AS XEvent *eventPtr +.AP XEvent *eventPtr in +Pointer to X event to dispatch to relevant handler(s). It is important +that all unused fields of the structure be set to zero. +.BE +.SH DESCRIPTION +.PP +\fBTk_HandleEvent\fR is a lower-level procedure that deals with window +events. It is called by \fBTcl_ServiceEvent\fR (and indirectly by +\fBTk_DoOneEvent\fR), and in a few other cases within Tk. +It makes callbacks to any window event +handlers (created by calls to \fBTk_CreateEventHandler\fR) +that match \fIeventPtr\fR and then returns. In some cases +it may be useful for an application to bypass the Tk event +queue and call \fBTk_HandleEvent\fR directly instead of +calling \fBTcl_QueueEvent\fR followed by +\fBTcl_ServiceEvent\fR. +.PP +This procedure may be invoked recursively. For example, +it is possible to invoke \fBTk_HandleEvent\fR recursively +from a handler called by \fBTk_HandleEvent\fR. This sort +of operation is useful in some modal situations, such +as when a +notifier has been popped up and an application wishes to +wait for the user to click a button in the notifier before +doing anything else. +.SH KEYWORDS +callback, event, handler, window diff --git a/tk8.6/doc/IdToWindow.3 b/tk8.6/doc/IdToWindow.3 new file mode 100644 index 0000000..f6e397d --- /dev/null +++ b/tk8.6/doc/IdToWindow.3 @@ -0,0 +1,32 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_IdToWindow \- Find Tk's window information for an X window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_IdToWindow\fR(\fIdisplay, window\fR) +.SH ARGUMENTS +.AS Tk_Window display +.AP Display *display in +X display containing the window. +.AP Window window in +X id for window. +.BE +.SH DESCRIPTION +.PP +Given an X window identifier and the X display it corresponds to, +this procedure returns the corresponding Tk_Window handle. +If there is no Tk_Window corresponding to \fIwindow\fR then +NULL is returned. +.SH KEYWORDS +X window id diff --git a/tk8.6/doc/ImgChanged.3 b/tk8.6/doc/ImgChanged.3 new file mode 100644 index 0000000..f4d2c04 --- /dev/null +++ b/tk8.6/doc/ImgChanged.3 @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ImageChanged \- notify widgets that image needs to be redrawn +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ImageChanged\fR(\fIimageMaster, x, y, width, height, imageWidth, imageHeight\fR) +.SH ARGUMENTS +.AS Tk_ImageMaster imageHeight +.AP Tk_ImageMaster imageMaster in +Token for image, which was passed to image's \fIcreateProc\fR when +the image was created. +.AP int x in +X-coordinate of upper-left corner of region that needs redisplay (measured +from upper-left corner of image). +.AP int y in +Y-coordinate of upper-left corner of region that needs redisplay (measured +from upper-left corner of image). +.AP "int" width in +Width of region that needs to be redrawn, in pixels. +.AP "int" height in +Height of region that needs to be redrawn, in pixels. +.AP "int" imageWidth in +Current width of image, in pixels. +.AP "int" imageHeight in +Current height of image, in pixels. +.BE +.SH DESCRIPTION +.PP +An image manager calls \fBTk_ImageChanged\fR for an image +whenever anything happens that requires the image to be redrawn. +As a result of calling \fBTk_ImageChanged\fR, any widgets using +the image are notified so that they can redisplay themselves +appropriately. +The \fIimageMaster\fR argument identifies the image, and +\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +specify a rectangular region within the image that needs to +be redrawn. +\fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. +.PP +An image manager should call \fBTk_ImageChanged\fR during +its \fIcreateProc\fR to specify the image's initial size and to +force redisplay if there are existing instances for the image. +If any of the pixel values in the image should change later on, +\fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR, +\fIwidth\fR, and \fIheight\fR values that cover all the pixels +that changed. +If the size of the image should change, then \fBTk_ImageChanged\fR +must be called to indicate the new size, even if no pixels +need to be redisplayed. +.SH "SEE ALSO" +Tk_CreateImageType +.SH KEYWORDS +images, redisplay, image size changes diff --git a/tk8.6/doc/Inactive.3 b/tk8.6/doc/Inactive.3 new file mode 100644 index 0000000..0d2a1b7 --- /dev/null +++ b/tk8.6/doc/Inactive.3 @@ -0,0 +1,34 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +long +\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR +.sp +\fBTk_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 new file mode 100644 index 0000000..a16eee1 --- /dev/null +++ b/tk8.6/doc/InternAtom.3 @@ -0,0 +1,55 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Atom +\fBTk_InternAtom(\fItkwin, name\fR) +.sp +const char * +\fBTk_GetAtomName(\fItkwin, atom\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. Used to map atom or name relative to a particular display. +.AP "const char" *name in +String name for which atom is desired. +.AP Atom atom in +Atom for which corresponding string name is desired. +.BE +.SH DESCRIPTION +.PP +These procedures are similar to the Xlib procedures +\fBXInternAtom\fR and \fBXGetAtomName\fR. \fBTk_InternAtom\fR +returns the atom identifier associated with string given by +\fIname\fR; the atom identifier is only valid for the display +associated with \fItkwin\fR. +\fBTk_GetAtomName\fR returns the string associated +with \fIatom\fR on \fItkwin\fR's display. The string returned +by \fBTk_GetAtomName\fR is in Tk's storage: the caller need +not free this space when finished with the string, and the caller +should not modify the contents of the returned string. +If there is no atom \fIatom\fR on \fItkwin\fR's display, +then \fBTk_GetAtomName\fR returns the string +.QW "?bad atom?" . +.PP +Tk caches +the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR +so that future calls +for the same information can be serviced from the cache without +contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR +are generally much faster than their Xlib counterparts, and they +should be used in place of the Xlib procedures. +.SH KEYWORDS +atom, cache, display diff --git a/tk8.6/doc/MainLoop.3 b/tk8.6/doc/MainLoop.3 new file mode 100644 index 0000000..ed4d0ea --- /dev/null +++ b/tk8.6/doc/MainLoop.3 @@ -0,0 +1,28 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MainLoop \- loop for events until all windows are deleted +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MainLoop\fR() +.BE +.SH DESCRIPTION +.PP +\fBTk_MainLoop\fR is a procedure that loops repeatedly calling +\fBTcl_DoOneEvent\fR. It returns only when there are no applications +left in this process (i.e. no main windows exist anymore). Most +windowing applications will call \fBTk_MainLoop\fR after +initialization; the main execution of the application will consist +entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. +.SH KEYWORDS +application, event, main loop diff --git a/tk8.6/doc/MainWin.3 b/tk8.6/doc/MainWin.3 new file mode 100644 index 0000000..c3af3e7 --- /dev/null +++ b/tk8.6/doc/MainWin.3 @@ -0,0 +1,40 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window information +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_MainWindow\fR(\fIinterp\fR) +.sp +int +\fBTk_GetNumMainWindows\fR() +.SH ARGUMENTS +.AS Tcl_Interp *pathName +.AP Tcl_Interp *interp in/out +Interpreter associated with the application. +.BE +.SH DESCRIPTION +.PP +A main window is a special kind of toplevel window used as the +outermost window in an application. +.PP +If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR +returns the application's main window. If there is no Tk application +associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and +leaves an error message in interpreter \fIinterp\fR's result. +.PP +\fBTk_GetNumMainWindows\fR returns a count of the number of main +windows currently open in the current thread. +.SH KEYWORDS +application, main window diff --git a/tk8.6/doc/MaintGeom.3 b/tk8.6/doc/MaintGeom.3 new file mode 100644 index 0000000..d1c2d1c --- /dev/null +++ b/tk8.6/doc/MaintGeom.3 @@ -0,0 +1,99 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MaintainGeometry\fR(\fIslave, master, x, y, width, height\fR) +.sp +\fBTk_UnmaintainGeometry\fR(\fIslave, master\fR) +.SH ARGUMENTS +.AS Tk_Window master +.AP Tk_Window slave in +Window whose geometry is to be controlled. +.AP Tk_Window master in +Window relative to which \fIslave\fR's geometry will be controlled. +.AP int x in +Desired x-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels +from the inside of \fImaster\fR's left border to the outside of +\fIslave\fR's left border. +.AP int y in +Desired y-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels +from the inside of \fImaster\fR's top border to the outside of +\fIslave\fR's top border. +.AP int width in +Desired width for \fIslave\fR, in pixels. +.AP int height in +Desired height for \fIslave\fR, in pixels. +.BE +.SH DESCRIPTION +.PP +\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it +easier for geometry managers to deal with slaves whose masters are not +their parents. +Three problems arise if the master for a slave is not its parent: +.IP [1] +The x- and y-position of the slave must be translated from the +coordinate system of the master to that of the parent before +positioning the slave. +.IP [2] +If the master window, or any of its ancestors up to the slave's +parent, is moved, then the slave must be repositioned within its +parent in order to maintain the correct position relative to the +master. +.IP [3] +If the master or one of its ancestors is mapped or unmapped, then +the slave must be mapped or unmapped to correspond. +.LP +None of these problems is an issue if the parent and master are +the same. For example, if the master or one of its ancestors +is unmapped, the slave is automatically removed by the screen +by X. +.PP +\fBTk_MaintainGeometry\fR deals with these problems for slaves +whose masters are not their parents, as well as handling the simpler +case of slaves whose masters are their parents. +\fBTk_MaintainGeometry\fR is typically called by a window manager +once it has decided where a slave should be positioned relative +to its master. +\fBTk_MaintainGeometry\fR translates the coordinates to the +coordinate system of \fIslave\fR's parent and then moves and +resizes the slave appropriately. +Furthermore, it remembers the desired position and creates event +handlers to monitor the master and all of its ancestors up +to (but not including) the slave's parent. +If any of these windows is moved, mapped, or unmapped, +the slave will be adjusted so that it is mapped only when the +master is mapped and its geometry relative to the master +remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and +\fIheight\fR. +.PP +When a window manager relinquishes control over a window, or +if it decides that it does not want the window to appear on the +screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR. +\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any +previous calls to \fBTk_MaintainGeometry\fR for the +\fImaster\fR\-\fIslave\fR pair, so that the slave's +geometry and mapped state are no longer maintained +automatically. +\fBTk_UnmaintainGeometry\fR need not be called by a geometry +manager if the slave, the master, or any of the master's ancestors +is destroyed: Tk will call it automatically. +.PP +If \fBTk_MaintainGeometry\fR is called repeatedly for the same +\fImaster\fR\-\fIslave\fR pair, the information from the most +recent call supersedes any older information. +If \fBTk_UnmaintainGeometry\fR is called for a \fImaster\fR\-\fIslave\fR +pair that is is not currently managed, the call has no effect. +.SH KEYWORDS +geometry manager, map, master, parent, position, slave, unmap diff --git a/tk8.6/doc/ManageGeom.3 b/tk8.6/doc/ManageGeom.3 new file mode 100644 index 0000000..520546f --- /dev/null +++ b/tk8.6/doc/ManageGeom.3 @@ -0,0 +1,90 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ManageGeometry \- arrange to handle geometry requests for a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) +.SH ARGUMENTS +.AS Tk_GeometryProc clientData +.AP Tk_Window tkwin in +Token for window to be managed. +.AP "const Tk_GeomMgr" *mgrPtr in +Pointer to data structure containing information about the +geometry manager, or NULL to indicate that \fItkwin\fR's geometry +should not be managed anymore. +The data structure pointed to by \fImgrPtr\fR must be static: +Tk keeps a reference to it as long as the window is managed. +.AP ClientData clientData in +Arbitrary one-word value to pass to geometry manager callbacks. +.BE +.SH DESCRIPTION +.PP +\fBTk_ManageGeometry\fR arranges for a particular geometry manager, +described by the \fImgrPtr\fR argument, to control the geometry +of a particular slave window, given by \fItkwin\fR. +If \fItkwin\fR was previously managed by some other geometry manager, +the previous manager loses control in favor of the new one. +If \fImgrPtr\fR is NULL, geometry management is cancelled for +\fItkwin\fR. +.PP +The structure pointed to by \fImgrPtr\fR contains information about +the geometry manager: +.CS +typedef struct { + const char *\fIname\fR; + Tk_GeomRequestProc *\fIrequestProc\fR; + Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; +} \fBTk_GeomMgr\fR; +.CE +The \fIname\fR field is the textual name for the geometry manager, +such as \fBpack\fR or \fBplace\fR; this value will be returned +by the command \fBwinfo manager\fR. +.PP +\fIrequestProc\fR is a procedure in the geometry manager that +will be invoked whenever \fBTk_GeometryRequest\fR is called by the +slave to change its desired geometry. +\fIrequestProc\fR should have arguments and results that match the +type \fBTk_GeomRequestProc\fR: +.CS +typedef void \fBTk_GeomRequestProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); +.CE +The parameters to \fIrequestProc\fR will be identical to the +corresponding parameters passed to \fBTk_ManageGeometry\fR. +\fIclientData\fR usually points to a data +structure containing application-specific information about +how to manage \fItkwin\fR's geometry. +.PP +The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another +procedure in the geometry manager. +Tk will invoke \fIlostSlaveProc\fR if some other manager +calls \fBTk_ManageGeometry\fR to claim +\fItkwin\fR away from the current geometry manager. +\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is +called with a NULL value for \fImgrPtr\fR (presumably the current +geometry manager has made this call, so it already knows that the +window is no longer managed), nor is it called if \fImgrPtr\fR +is the same as the window's current geometry manager. +\fIlostSlaveProc\fR should have +arguments and results that match the following prototype: +.CS +typedef void \fBTk_GeomLostSlaveProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); +.CE +The parameters to \fIlostSlaveProc\fR will be identical to the +corresponding parameters passed to \fBTk_ManageGeometry\fR. +.SH KEYWORDS +callback, geometry, managed, request, unmanaged diff --git a/tk8.6/doc/MapWindow.3 b/tk8.6/doc/MapWindow.3 new file mode 100644 index 0000000..a3c6296 --- /dev/null +++ b/tk8.6/doc/MapWindow.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_MapWindow\fR(\fItkwin\fR) +.sp +\fBTk_UnmapWindow\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. +.BE +.SH DESCRIPTION +.PP +These procedures may be used to map and unmap windows +managed by Tk. \fBTk_MapWindow\fR maps the window given +by \fItkwin\fR, and also creates an X window corresponding +to \fItkwin\fR if it does not already exist. See the +\fBTk_CreateWindow\fR manual entry for information on +deferred window creation. +\fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window +from the screen. +.PP +If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was +used to create a child window), then event handlers interested in map +and unmap events are invoked immediately. If \fItkwin\fR is not an +internal window, then the event handlers will be invoked later, after +X has seen the request and returned an event for it. +.PP +These procedures should be used in place of the X procedures +\fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update +Tk's local data structure for \fItkwin\fR. Applications +using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR +directly. +.SH KEYWORDS +map, unmap, window diff --git a/tk8.6/doc/MeasureChar.3 b/tk8.6/doc/MeasureChar.3 new file mode 100644 index 0000000..3959978 --- /dev/null +++ b/tk8.6/doc/MeasureChar.3 @@ -0,0 +1,127 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR +.sp +int +\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR +.sp +\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR +.sp +\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR +.sp +.SH ARGUMENTS +.AS "const char" firstChar +.AP Tk_Font tkfont in +Token for font in which text is to be drawn or measured. Must have been +returned by a previous call to \fBTk_GetFont\fR. +.AP "const char" *string in +Text to be measured or displayed. Need not be null terminated. Any +non-printing meta-characters in the string (such as tabs, newlines, and +other control characters) will be measured or displayed in a +platform-dependent manner. +.AP int numBytes in +The maximum number of bytes to consider when measuring or drawing +\fIstring\fR. Must be greater than or equal to 0. +.AP int maxPixels in +If \fImaxPixels\fR is >= 0, it specifies the longest permissible +line length in pixels. Characters from \fIstring\fR are processed only +until this many pixels have been covered. If \fImaxPixels\fR is < 0, then +the line length is unbounded and the \fIflags\fR argument is ignored. +.AP int flags in +Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character +as long as any part of it fits in the length given by \fImaxPixels\fR; +otherwise, a character must fit completely to be considered. +\fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible. If +\fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no +characters could fit in the length given by \fImaxPixels\fR. If +\fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if +not even one word fits on the line, return the first few letters of the +word that did fit; if not even one letter of the word fit, then the first +letter will still be returned. +.AP int *lengthPtr out +Filled with the number of pixels occupied by the number of characters +returned as the result of \fBTk_MeasureChars\fR. +.AP Display *display in +Display on which to draw. +.AP Drawable drawable in +Window or pixmap in which to draw. +.AP GC gc in +Graphics context for drawing characters. The font selected into this GC +must be the same as the \fItkfont\fR. +.AP int "x, y" in +Coordinates at which to place the left edge of the baseline when displaying +\fIstring\fR. +.AP int firstByte in +The index of the first byte of the first character to underline in the +\fIstring\fR. Underlining begins at the left edge of this character. +.AP int lastByte in +The index of the first byte of the last character up to which the +underline will be drawn. The character specified by \fIlastByte\fR +will not itself be underlined. +.BE +.SH DESCRIPTION +.PP +These routines are for measuring and displaying simple single-font, +single-line strings. To measure and display single-font, multi-line, +justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR. +There is no programming interface in the core of Tk that supports +multi-font, multi-line text; support for that behavior must be built on +top of simpler layers. +Note that the interfaces described here are +byte-oriented not character-oriented, so index values coming from Tcl +scripts need to be converted to byte offsets using the +\fBTcl_UtfAtIndex\fR and related routines. +.PP +A glyph is the displayable picture of a letter, number, or some other +symbol. Not all character codes in a given font have a glyph. +Characters such as tabs, newlines/returns, and control characters that +have no glyph are measured and displayed by these procedures in a +platform-dependent manner; under X, they are replaced with backslashed +escape sequences, while under Windows and Macintosh hollow or solid boxes +may be substituted. Refer to the documentation for +\fBTk_ComputeTextLayout\fR for a programming interface that supports the +platform-independent expansion of tab characters into columns and +newlines/returns into multi-line text. +.PP +\fBTk_MeasureChars\fR is used both to compute the length of a given +string and to compute how many characters from a string fit in a given +amount of space. The return value is the number of bytes from +\fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to +the conditions described by \fIflags\fR. If all characters fit, the return +value will be \fInumBytes\fR. \fI*lengthPtr\fR is filled with the computed +width, in pixels, of the portion of the string that was measured. For +example, if the return value is 5, then \fI*lengthPtr\fR is filled with the +distance between the left edge of \fIstring\fR[0] and the right edge of +\fIstring\fR[4]. +.PP +\fBTk_TextWidth\fR is a wrapper function that provides a simpler interface +to the \fBTk_MeasureChars\fR function. The return value is how much +space in pixels the given \fIstring\fR needs. +.PP +\fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the +given \fIdrawable\fR. +.PP +\fBTk_UnderlineChars\fR underlines the given range of characters in the +given \fIstring\fR. It does not draw the characters (which are assumed to +have been displayed previously by \fBTk_DrawChars\fR); it just draws the +underline. This procedure is used to underline a few characters without +having to construct an underlined font. To produce natively underlined +text, the appropriate underlined font should be constructed and used. +.SH "SEE ALSO" +font(n), FontId(3) +.SH KEYWORDS +font, measurement diff --git a/tk8.6/doc/MoveToplev.3 b/tk8.6/doc/MoveToplev.3 new file mode 100644 index 0000000..effed29 --- /dev/null +++ b/tk8.6/doc/MoveToplev.3 @@ -0,0 +1,51 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_MoveToplevelWindow \- Adjust the position of a top-level window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for top-level window to move. +.AP int x in +New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the +top-left pixel of the decorative border supplied for \fItkwin\fR by the +window manager, if there is one. +.AP int y in +New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the +top-left pixel of the decorative border supplied for \fItkwin\fR by the +window manager, if there is one. +.BE +.SH DESCRIPTION +.PP +In general, a window should never set its own position; this should be +done only by the geometry manger that is responsible for the window. +For top-level windows the window manager is effectively the geometry +manager; Tk provides interface code between the application and the +window manager to convey the application's desires to the geometry +manager. The desired size for a top-level window is conveyed using +the usual \fBTk_GeometryRequest\fR mechanism. The procedure +\fBTk_MoveToplevelWindow\fR may be used by an application to request +a particular position for a top-level window; this procedure is +similar in function to the \fBwm geometry\fR Tcl command except that +negative offsets cannot be specified. It is invoked by widgets such as +menus that want to appear at a particular place on the screen. +.PP +When \fBTk_MoveToplevelWindow\fR is called it does not immediately +pass on the new desired location to the window manager; it defers +this action until all other outstanding work has been completed, +using the \fBTk_DoWhenIdle\fR mechanism. +.SH KEYWORDS +position, top-level window, window manager diff --git a/tk8.6/doc/Name.3 b/tk8.6/doc/Name.3 new file mode 100644 index 0000000..4b9c5bc --- /dev/null +++ b/tk8.6/doc/Name.3 @@ -0,0 +1,86 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_Name 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Uid +\fBTk_Name\fR(\fItkwin\fR) +.sp +char * +\fBTk_PathName\fR(\fItkwin\fR) +.sp +Tk_Window +\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) +.SH ARGUMENTS +.AS Tcl_Interp *pathName +.AP Tk_Window tkwin in +Token for window. +.AP Tcl_Interp *interp out +Interpreter to use for error reporting. +.AP "const char" *pathName in +Character string containing path name of window. +.BE +.SH DESCRIPTION +.PP +Each window managed by Tk has two names, a short name that identifies +a window among children of the same parent, and a path name that +identifies the window uniquely among all the windows belonging to the +same main window. The path name is used more often in Tk than the +short name; many commands, like \fBbind\fR, expect path names as +arguments. +.PP +The \fBTk_Name\fR macro returns a window's +short name, which is the same as the \fIname\fR argument +passed to \fBTk_CreateWindow\fR when +the window was created. The value is returned +as a Tk_Uid, which may be used just like a string pointer but also has +the properties of a unique identifier (see the manual entry for +\fBTk_GetUid\fR for details). +.PP +The \fBTk_PathName\fR macro returns a hierarchical name for \fItkwin\fR. +Path names have a structure similar to file names in Unix but with +dots between elements instead of slashes: the main window for +an application has the path name +.QW . ; +its children have names like +.QW .a +and +.QW .b ; +their children have names like +.QW .a.aa +and +.QW .b.bb ; +and so on. A window is considered to be a child of +another window for naming purposes if the second window was named +as the first window's \fIparent\fR when the first window was created. +This is not always the same as the X window hierarchy. For +example, a pop-up +is created as a child of the root window, but its logical parent will +usually be a window within the application. +.PP +The procedure \fBTk_NameToWindow\fR returns the token for a window +given its path name (the \fIpathName\fR argument) and another window +belonging to the same main window (\fItkwin\fR). It normally +returns a token for the named window, but if no such window exists +\fBTk_NameToWindow\fR leaves an error message in interpreter +\fIinterp\fR's result +and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR +is needed because path names are only unique within a single +application hierarchy. If, for example, a single process has opened +two main windows, each will have a separate naming hierarchy and the +same path name might appear in each of the hierarchies. Normally +\fItkwin\fR is the main window of the desired hierarchy, but this +need not be the case: any window in the desired hierarchy may be used. +.SH KEYWORDS +name, path name, token, window diff --git a/tk8.6/doc/NameOfImg.3 b/tk8.6/doc/NameOfImg.3 new file mode 100644 index 0000000..78332db --- /dev/null +++ b/tk8.6/doc/NameOfImg.3 @@ -0,0 +1,30 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_NameOfImage \- Return name of image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +const char * +\fBTk_NameOfImage\fR(\fItypePtr\fR) +.SH ARGUMENTS +.AS Tk_ImageMaster *masterPtr +.AP Tk_ImageMaster *masterPtr in +Token for image, which was passed to image manager's \fIcreateProc\fR when +the image was created. +.BE +.SH DESCRIPTION +.PP +This procedure is invoked by image managers to find out the name +of an image. Given the token for the image, it returns the +string name for the image. +.SH KEYWORDS +image manager, image name diff --git a/tk8.6/doc/OwnSelect.3 b/tk8.6/doc/OwnSelect.3 new file mode 100644 index 0000000..ed9bcab --- /dev/null +++ b/tk8.6/doc/OwnSelect.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_OwnSelection \- make a window the owner of the primary selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) +.SH ARGUMENTS +.AS Tk_LostSelProc clientData +.AP Tk_Window tkwin in +Window that is to become new selection owner. +.AP Atom selection in +The name of the selection to be owned, such as XA_PRIMARY. +.AP Tk_LostSelProc *proc in +Procedure to invoke when \fItkwin\fR loses selection ownership later. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the +new owner of the selection specified by the atom +\fIselection\fR. After this call completes, future requests +for the selection will be directed to handlers created for +\fItkwin\fR using \fBTk_CreateSelHandler\fR. When \fItkwin\fR +eventually loses the selection ownership, \fIproc\fR will be +invoked so that the window can clean itself up (e.g. by +unhighlighting the selection). \fIProc\fR should have arguments and +result that match the type \fBTk_LostSelProc\fR: +.CS +typedef void \fBTk_LostSelProc\fR( + ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the +\fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is +usually a pointer to a data structure containing application-specific +information about \fItkwin\fR. +.SH KEYWORDS +own, selection owner diff --git a/tk8.6/doc/ParseArgv.3 b/tk8.6/doc/ParseArgv.3 new file mode 100644 index 0000000..3a9bd49 --- /dev/null +++ b/tk8.6/doc/ParseArgv.3 @@ -0,0 +1,360 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ParseArgv \- process command-line options +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) +.SH ARGUMENTS +.AS Tk_ArgvInfo *argTable +.AP Tcl_Interp *interp in +Interpreter to use for returning error messages. +.AP Tk_Window tkwin in +Window to use when arguments specify Tk options. If NULL, then +no Tk options will be processed. +.AP int argcPtr in/out +Pointer to number of arguments in argv; gets modified to hold +number of unprocessed arguments that remain after the call. +.AP "const char" **argv in/out +Command line arguments passed to main program. Modified to +hold unprocessed arguments that remain after the call. +.AP Tk_ArgvInfo *argTable in +Array of argument descriptors, terminated by element with +type \fBTK_ARGV_END\fR. +.AP int flags in +If non-zero, then it specifies one or more flags that control the +parsing of arguments. Different flags may be OR'ed together. +The flags currently defined are \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR, +\fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and +\fBTK_ARGV_NO_DEFAULTS\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_ParseArgv\fR processes an array of command-line arguments according +to a table describing the kinds of arguments that are expected. +Each of the arguments in \fIargv\fR is processed in turn: if it matches +one of the entries in \fIargTable\fR, the argument is processed +according to that entry and discarded. The arguments that do not +match anything in \fIargTable\fR are copied down to the beginning +of \fIargv\fR (retaining their original order) and returned to +the caller. At the end of the call +\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of +arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR +will hold the value NULL. Normally, \fBTk_ParseArgv\fR +assumes that \fIargv[0]\fR is a command name, so it is treated like +an argument that does not match \fIargTable\fR and returned to the +caller; however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR bit is set in +\fIflags\fR then \fIargv[0]\fR will be processed just like the other +elements of \fIargv\fR. +.PP +\fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error +occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and +\fBTk_ParseArgv\fR will leave an error message in the result of +interpreter \fIinterp\fR in the standard Tcl fashion. In +the event of an error return, \fI*argvPtr\fR will not have been +modified, but \fIargv\fR could have been partially modified. The +possible causes of errors are explained below. +.PP +The \fIargTable\fR array specifies the kinds of arguments that are +expected; each of its entries has the following structure: +.CS +typedef struct { + const char *\fIkey\fR; + int \fItype\fR; + char *\fIsrc\fR; + char *\fIdst\fR; + const char *\fIhelp\fR; +} \fBTk_ArgvInfo\fR; +.CE +The \fIkey\fR field is a string such as +.QW \-display +or +.QW \-bg +that is compared with the values in \fIargv\fR. \fIType\fR +indicates how to process an argument that matches \fIkey\fR +(more on this below). \fISrc\fR and \fIdst\fR are additional +values used in processing the argument. Their exact usage +depends on \fItype\fR, but typically \fIsrc\fR indicates +a value and \fIdst\fR indicates where to store the +value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR +are placeholders: the actual types may be different. Lastly, +\fIhelp\fR is a string giving a brief description +of this option; this string is printed when users ask for help +about command-line options. +.PP +When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR +compares the argument to each of the \fIkey\fR's in \fIargTable\fR. +\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches +the argument exactly, if such a specifier exists. Otherwise +\fBTk_ParseArgv\fR selects a specifier for which the argument +is a unique abbreviation. If the argument is a unique abbreviation +for more than one specifier, then an error is returned. If there +is no matching entry in \fIargTable\fR, then the argument is +skipped and returned to the caller. +.PP +Once a matching argument specifier is found, \fBTk_ParseArgv\fR +processes the argument according to the \fItype\fR field of the +specifier. The argument that matched \fIkey\fR is called +.QW "the matching argument" +in the descriptions below. As part of the processing, +\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR +after the matching argument, which is called +.QW "the following argument" . +The legal values for \fItype\fR, and the processing +that they cause, are as follows: +.TP +\fBTK_ARGV_END\fR +Marks the end of the table. The last entry in \fIargTable\fR +must have this type; all of its other fields are ignored and it +will never match any arguments. +.TP +\fBTK_ARGV_CONSTANT\fR +\fISrc\fR is treated as an integer and \fIdst\fR is treated +as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. +The matching argument is discarded. +.TP +\fBTK_ARGV_INT\fR +The following argument must contain an +integer string in the format accepted by \fBstrtol\fR (e.g. +.QW 0 +and +.QW 0x +prefixes may be used to specify octal or hexadecimal +numbers, respectively). \fIDst\fR is treated as a pointer to an +integer; the following argument is converted to an integer value +and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching +and following arguments are discarded from \fIargv\fR. +.TP +\fBTK_ARGV_FLOAT\fR +The following argument must contain a floating-point number in +the format accepted by \fBstrtol\fR. +\fIDst\fR is treated as the address of a double-precision +floating point value; the following argument is converted to a +double-precision value and stored at \fI*dst\fR. The matching +and following arguments are discarded from \fIargv\fR. +.TP +\fBTK_ARGV_STRING\fR +In this form, \fIdst\fR is treated as a pointer to a (char *); +\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following +argument, and discards the matching and following arguments from +\fIargv\fR. \fISrc\fR is ignored. +.TP +\fBTK_ARGV_UID\fR +This form is similar to \fBTK_ARGV_STRING\fR, except that the argument +is turned into a Tk_Uid by calling \fBTk_GetUid\fR. +\fIDst\fR is treated as a pointer to a +Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid +corresponding to the following +argument, and discards the matching and following arguments from +\fIargv\fR. \fISrc\fR is ignored. +.TP +\fBTK_ARGV_CONST_OPTION\fR +This form causes a Tk option to be set (as if the \fBoption\fR +command had been invoked). The \fIsrc\fR field is treated as a +pointer to a string giving the value of an option, and \fIdst\fR +is treated as a pointer to the name of the option. The matching +argument is discarded. If \fItkwin\fR is NULL, then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_OPTION_VALUE\fR +This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the +value of the option is taken from the following argument instead +of from \fIsrc\fR. \fIDst\fR is used as the name of the option. +\fISrc\fR is ignored. The matching and following arguments +are discarded. If \fItkwin\fR is NULL, then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_OPTION_NAME_VALUE\fR +In this case the following argument is taken as the name of a Tk +option and the argument after that is taken as the value for that +option. Both \fIsrc\fR and \fIdst\fR are ignored. All three +arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, +then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_HELP\fR +When this kind of option is encountered, \fBTk_ParseArgv\fR uses the +\fIhelp\fR fields of \fIargTable\fR to format a message describing +all the valid arguments. The message is placed in interpreter +\fIinterp\fR's result +and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the +caller normally prints the help message and aborts. If the \fIkey\fR +field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will +never match any arguments; in this case the specifier simply provides +extra documentation, which will be included when some other +\fBTK_ARGV_HELP\fR entry causes help information to be returned. +.TP +\fBTK_ARGV_REST\fR +This option is used by programs or commands that allow the last +several of their options to be the name and/or options for some +other program. If a \fBTK_ARGV_REST\fR argument is found, then +\fBTk_ParseArgv\fR does not process any +of the remaining arguments; it returns them all at +the beginning of \fIargv\fR (along with any other unprocessed arguments). +In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an +integer value, and stores at \fI*dst\fR the index of the first of the +\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the +program to distinguish the \fBTK_ARGV_REST\fR options from other +unprocessed options that preceded the \fBTK_ARGV_REST\fR. +.TP +\fBTK_ARGV_FUNC\fR +For this kind of argument, \fIsrc\fR is treated as the address of +a procedure, which is invoked to process the following argument. +The procedure should have the following structure: +.RS +.CS +int +\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) + char *\fIdst\fR; + char *\fIkey\fR; + char *\fInextArg\fR; +{ +} +.CE +The \fIdst\fR and \fIkey\fR parameters will contain the +corresponding fields from the \fIargTable\fR entry, and +\fInextArg\fR will point to the following argument from \fIargv\fR +(or NULL if there are not any more arguments left in \fIargv\fR). +If \fIfunc\fR uses \fInextArg\fR (so that +\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it +should return 0 and \fBTkParseArgv\fR will process the following +argument in the normal fashion. In either event the matching argument +is discarded. +.RE +.TP +\fBTK_ARGV_GENFUNC\fR +This form provides a more general procedural escape. It treats +\fIsrc\fR as the address of a procedure, and passes that procedure +all of the remaining arguments. The procedure should have the following +form: +.RS +.CS +int +\fIgenfunc\fR(dst, interp, key, argc, argv) + char *\fIdst\fR; + Tcl_Interp *\fIinterp\fR; + char *\fIkey\fR; + int \fIargc\fR; + char **\fIargv\fR; +{ +} +.CE +The \fIdst\fR and \fIkey\fR parameters will contain the +corresponding fields from the \fIargTable\fR entry. \fIInterp\fR +will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. +\fIArgc\fR and \fIargv\fR refer to all of the options after the +matching one. \fIGenfunc\fR should behave in a fashion similar +to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, +then return any that are left by compacting them to the beginning of +\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR +should return a count of how many arguments are left in \fIargv\fR; +\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters +an error then it should leave an error message in interpreter +\fIinterp\fR's result, +in the usual Tcl fashion, and return \-1; when this happens +\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. +.RE +.SS "FLAGS" +.TP +\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR +\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program +or command name, and returns it to the caller just as if it +had not matched \fIargTable\fR. If this flag is given, then +\fIargv[0]\fR is not given special treatment. +.TP +\fBTK_ARGV_NO_ABBREV\fR +Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for +\fIkey\fR values in \fIargTable\fR. If this flag is given then +only exact matches will be acceptable. +.TP +\fBTK_ARGV_NO_LEFTOVERS\fR +Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the +caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR +will return an error if it encounters any argument that does not +match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, +which will be returned to the caller with no errors as +long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified. +.TP +\fBTK_ARGV_NO_DEFAULTS\fR +Normally, \fBTk_ParseArgv\fR searches an internal table of +standard argument specifiers in addition to \fIargTable\fR. If +this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will +use only \fIargTable\fR and not its default table. +.SH EXAMPLE +.PP +Here is an example definition of an \fIargTable\fR and +some sample command lines that use the options. Note the effect +on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR +are eliminated from \fIargv\fR, and \fIargc\fR +is updated to reflect reduced number of arguments. +.CS +/* + * Define and set default values for globals. + */ +int debugFlag = 0; +int numReps = 100; +char defaultFileName[] = "out"; +char *fileName = defaultFileName; +Boolean exec = FALSE; + +/* + * Define option descriptions. + */ +Tk_ArgvInfo argTable[] = { + {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, + "Turn on debugging printfs"}, + {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, + "Number of repetitions"}, + {"\-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, + "Name of file for output"}, + {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, + "File to exec, followed by any arguments (must be last argument)."}, + {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, + (char *) NULL} +}; + +main(argc, argv) + int argc; + char *argv[]; +{ + \&... + + if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { + fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp))); + exit(1); + } + + /* + * Remainder of the program. + */ +} +.CE +.PP +Note that default values can be assigned to variables named in +\fIargTable\fR: the variables will only be overwritten if the +particular arguments are present in \fIargv\fR. +Here are some example command lines and their effects. +.CS +prog \-N 200 infile # just sets the numReps variable to 200 +prog \-of out200 infile # sets fileName to reference "out200" +prog \-XN 10 infile # sets the debug flag, also sets numReps +.CE +In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, +\fIargv\fR[0] will be +.QW prog , +\fIargv\fR[1] will be +.QW infile , +and \fIargv\fR[2] will be NULL. +.SH KEYWORDS +arguments, command line, options diff --git a/tk8.6/doc/QWinEvent.3 b/tk8.6/doc/QWinEvent.3 new file mode 100644 index 0000000..caa5026 --- /dev/null +++ b/tk8.6/doc/QWinEvent.3 @@ -0,0 +1,50 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CollapseMotionEvents, Tk_QueueWindowEvent \- Add a window event to the Tcl event queue +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) +.sp +\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) +.SH ARGUMENTS +.AS Tcl_QueuePosition position +.AP Display *display in +Display for which to control motion event collapsing. +.AP int collapse in +Indicates whether motion events should be collapsed or not. +.AP XEvent *eventPtr in +An event to add to the event queue. It is important +that all unused fields of the structure be set to zero. +.AP Tcl_QueuePosition position in +Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, +\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. +.BE +.SH DESCRIPTION +.PP +\fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event +queue for eventual servicing. It creates a Tcl_Event structure, copies the +event into that structure, and calls \fBTcl_QueueEvent\fR to add the event +to the queue. When the event is eventually removed from the queue it is +processed just like all window events. +.PP +When multiple motion events are received for the same window in rapid +succession, they are collapsed by default. This behavior can be controlled +with \fBTk_CollapseMotionEvents\fR. \fBTk_CollapseMotionEvents\fR always +returns the previous value for collapse behavior on the \fIdisplay\fR. +.PP +The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has +the same significance as for \fBTcl_QueueEvent\fR; see the +documentation for \fBTcl_QueueEvent\fR for details. +.SH KEYWORDS +callback, clock, handler, modal timeout, events diff --git a/tk8.6/doc/Restack.3 b/tk8.6/doc/Restack.3 new file mode 100644 index 0000000..2b9097f --- /dev/null +++ b/tk8.6/doc/Restack.3 @@ -0,0 +1,45 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_RestackWindow \- Change a window's position in the stacking order +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) +.SH ARGUMENTS +.AS Tk_Window aboveBelow +.AP Tk_Window tkwin in +Token for window to restack. +.AP int aboveBelow in +Indicates new position of \fItkwin\fR relative to \fIother\fR; +must be \fBAbove\fR or \fBBelow\fR. +.AP Tk_Window other in +\fITkwin\fR will be repositioned just above or below this window. +Must be a sibling of \fItkwin\fR or a descendant of a sibling. +If NULL then \fItkwin\fR is restacked above or below all siblings. +.BE +.SH DESCRIPTION +.PP +\fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative +to its siblings. +If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned +at the top or bottom of its stacking order, depending on whether +\fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR. +If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned +just above or below \fIother\fR. +.PP +The \fIaboveBelow\fR argument must have one of the symbolic values +\fBAbove\fR or \fBBelow\fR. +Both of these values are defined by the include file <X11/Xlib.h>. +.SH KEYWORDS +above, below, obscure, stacking order diff --git a/tk8.6/doc/RestrictEv.3 b/tk8.6/doc/RestrictEv.3 new file mode 100644 index 0000000..eb1f040 --- /dev/null +++ b/tk8.6/doc/RestrictEv.3 @@ -0,0 +1,79 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_RestrictEvents \- filter and selectively delay X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_RestrictProc * +\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) +.SH ARGUMENTS +.AS Tk_RestrictProc **prevArgPtr +.AP Tk_RestrictProc *proc in +Predicate procedure to call to filter incoming X events. +NULL means do not restrict events at all. +.AP ClientData arg in +Arbitrary argument to pass to \fIproc\fR. +.AP ClientData *prevArgPtr out +Pointer to place to save argument to previous restrict procedure. +.BE +.SH DESCRIPTION +.PP +This procedure is useful in certain situations where applications +are only prepared to receive certain X events. After +\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and +hence \fBTk_MainLoop\fR) will filter X input events through +\fIproc\fR. \fIProc\fR indicates whether a +given event is to be processed immediately, deferred until some +later time (e.g. when the event restriction is lifted), or discarded. +\fIProc\fR +is a procedure with arguments and result that match +the type \fBTk_RestrictProc\fR: +.CS +typedef Tk_RestrictAction \fBTk_RestrictProc\fR( + ClientData \fIarg\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIarg\fR argument is a copy of the \fIarg\fR passed +to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with +information it needs to filter events. The \fIeventPtr\fR points to +an event under consideration. \fIProc\fR returns a restrict action +(enumerated type \fBTk_RestrictAction\fR) that indicates what +\fBTk_DoOneEvent\fR should do with the event. If the return value is +\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. +If the return value is \fBTK_DEFER_EVENT\fR, then the event will be +left on the event queue for later processing. If the return value is +\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event +queue and discarded without being processed. +.PP +\fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR +to return information about the current event restriction procedure +(a NULL return value means there are currently no restrictions). +These values may be used to restore the previous restriction state +when there is no longer any need for the current restriction. +.PP +There are very few places where \fBTk_RestrictEvents\fR is needed. +In most cases, the best way to restrict events is by changing the +bindings with the \fBbind\fR Tcl command or by calling +\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. +The main place where \fBTk_RestrictEvents\fR must be used is when +performing synchronous actions (for example, if you need to wait +for a particular event to occur on a particular window but you do not +want to invoke any handlers for any other events). The +.QW obvious +solution in these situations is to call \fBXNextEvent\fR or +\fBXWindowEvent\fR, but these procedures cannot be used because +Tk keeps its own event queue that is separate from the X event +queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, +then call \fBTk_DoOneEvent\fR to retrieve the desired event(s). +.SH KEYWORDS +delay, event, filter, restriction diff --git a/tk8.6/doc/SetAppName.3 b/tk8.6/doc/SetAppName.3 new file mode 100644 index 0000000..3978850 --- /dev/null +++ b/tk8.6/doc/SetAppName.3 @@ -0,0 +1,62 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetAppName \- Set the name of an application for 'send' commands +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +const char * +\fBTk_SetAppName\fR(\fItkwin, name\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window in application. Used only to select a particular +application. +.AP "const char" *name in +Name under which to register the application. +.BE +.SH DESCRIPTION +.PP +\fBTk_SetAppName\fR associates a name with a given application and +records that association on the display containing with the application's +main window. +After this procedure has been invoked, other applications on the +display will be able to use the \fBsend\fR command to invoke operations +in the application. +If \fIname\fR is already in use by some other application on the +display, then a new name will be generated by appending +.QW "\fB #2\fR" +to \fIname\fR; if this name is also in use, +the number will be incremented until an unused name is found. +The return value from the procedure is a pointer to the name actually +used. +.PP +If the application already has a name when \fBTk_SetAppName\fR is +called, then the new name replaces the old name. +.PP +\fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's +interpreter, which can be used to send commands from this application +to others on any of the displays where the application has windows. +.PP +The application's name registration persists until the interpreter is +deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which +point the name is automatically unregistered and the application +becomes inaccessible via \fBsend\fR. +The application can be made accessible again by calling \fBTk_SetAppName\fR. +.PP +\fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR, +so applications do not normally need to call it explicitly. +.PP +The command \fBtk appname\fR provides Tcl-level access to the +functionality of \fBTk_SetAppName\fR. +.SH KEYWORDS +application, name, register, send command diff --git a/tk8.6/doc/SetCaret.3 b/tk8.6/doc/SetCaret.3 new file mode 100644 index 0000000..fd63f18 --- /dev/null +++ b/tk8.6/doc/SetCaret.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 2002 ActiveState Corporation. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetCaretPos \- set the display caret location +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) +.SH ARGUMENTS +.AP Tk_Window tkwin in +Token for window. +.AP int x in +Window-relative x coordinate. +.AP int y in +Window-relative y coordinate. +.AP int h in +Height of the caret in the window. +.BE +.SH DESCRIPTION +.PP +\fBTk_SetCaretPos\fR sets the caret location for the display of the +specified Tk_Window \fItkwin\fR. The caret is the per-display cursor +location used for indicating global focus (e.g. to comply with Microsoft +Accessibility guidelines), as well as for location of the over-the-spot XIM +(X Input Methods) or Windows IME windows. +.SH KEYWORDS +caret, cursor diff --git a/tk8.6/doc/SetClass.3 b/tk8.6/doc/SetClass.3 new file mode 100644 index 0000000..707975d --- /dev/null +++ b/tk8.6/doc/SetClass.3 @@ -0,0 +1,57 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetClass 3 "" Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetClass, Tk_Class \- set or retrieve a window's class +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_SetClass\fR(\fItkwin, class\fR) +.sp +Tk_Uid +\fBTk_Class\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. +.AP char *class in +New class name for window. +.BE +.SH DESCRIPTION +.PP +\fBTk_SetClass\fR is called to associate a class with a particular +window. The \fIclass\fR string identifies the type of the +window; all windows with the same general class of behavior +(button, menu, etc.) should have the same class. By +convention all class names start with a capital letter, and +there exists a Tcl command with the same name as +each class (except all in lower-case) which can be used to +create and manipulate windows of that class. +A window's class string is initialized to NULL +when the window is created. +.PP +For main windows, Tk automatically propagates the name and class +to the WM_CLASS property used by window managers. This happens +either when a main window is actually created (e.g. in +\fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR +is called, whichever occurs later. If a main window has not been +assigned a class then Tk will not set the WM_CLASS property for +the window. +.PP +\fBTk_Class\fR is a macro that returns the +current value of \fItkwin\fR's class. The value is returned +as a Tk_Uid, which may be used just like a string pointer but also has +the properties of a unique identifier (see the manual entry for +\fBTk_GetUid\fR for details). +If \fItkwin\fR has not yet been given a class, then +\fBTk_Class\fR will return NULL. +.SH KEYWORDS +class, unique identifier, window, window manager diff --git a/tk8.6/doc/SetClassProcs.3 b/tk8.6/doc/SetClassProcs.3 new file mode 100644 index 0000000..58618da --- /dev/null +++ b/tk8.6/doc/SetClassProcs.3 @@ -0,0 +1,87 @@ +'\" +'\" Copyright (c) 2000 Ajuba Solutions. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetClassProcs \- register widget specific procedures +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) +.SH ARGUMENTS +.AS Tk_ClassProc instanceData +.AP Tk_Window tkwin in +Token for window to modify. +.AP "const Tk_ClassProcs" *procs in +Pointer to data structure containing widget specific procedures. +The data structure pointed to by \fIprocs\fR must be static: +Tk keeps a reference to it as long as the window exists. +.AP ClientData instanceData in +Arbitrary one-word value to pass to widget callbacks. +.BE +.SH DESCRIPTION +.PP +\fBTk_SetClassProcs\fR is called to register a set of procedures that +are used as callbacks in different places. +.PP +The structure pointed to by \fIprocs\fR contains the following: +.CS +typedef struct Tk_ClassProcs { + unsigned int \fIsize\fR; + Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; + Tk_ClassCreateProc *\fIcreateProc\fR; + Tk_ClassModalProc *\fImodalProc\fR; +} \fBTk_ClassProcs\fR; +.CE +The \fIsize\fR field is used to simplify future expansion of the +structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR. +.PP +\fIworldChangedProc\fR is invoked when the system has altered +in some way that requires some reaction from the widget. For example, +when a font alias (see the \fBfont\fR manual entry) is reconfigured, +widgets configured to use that font alias must update their display +accordingly. \fIworldChangedProc\fR should have arguments and results +that match the type \fBTk_ClassWorldChangedProc\fR: +.CS +typedef void \fBTk_ClassWorldChangedProc\fR( + ClientData \fIinstanceData\fR); +.CE +The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR +will be identical to the \fIinstanceData\fR parameter passed to +\fBTk_SetClassProcs\fR. +.PP +\fIcreateProc\fR is used to create platform-dependant windows. It is +invoked by \fBTk_MakeWindowExist\fR. \fIcreateProc\fR should have +arguments and results that match the type \fBTk_ClassCreateProc\fR: +.CS +typedef Window \fBTk_ClassCreateProc\fR( + Tk_Window \fItkwin\fR, + Window \fIparent\fR, + ClientData \fIinstanceData\fR); +.CE +The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to +the \fItkwin\fR and \fIinstanceData\fR parameters passed to +\fBTk_SetClassProcs\fR. The \fIparent\fR parameter will be the parent +of the window to be created. The \fIcreateProc\fR should return the +created window. +.PP +\fImodalProc\fR is invoked after all bindings on a widget have been +triggered in order to handle a modal loop. \fImodalProc\fR should +have arguments and results that match the type \fBTk_ClassModalProc\fR: +.CS +typedef void \fBTk_ClassModalProc\fR( + Tk_Window \fItkwin\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the +\fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR. The +\fIeventPtr\fR parameter will be a pointer to an XEvent structure +describing the event being processed. +.SH KEYWORDS +callback, class diff --git a/tk8.6/doc/SetGrid.3 b/tk8.6/doc/SetGrid.3 new file mode 100644 index 0000000..28e428b --- /dev/null +++ b/tk8.6/doc/SetGrid.3 @@ -0,0 +1,63 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) +.sp +\fBTk_UnsetGrid\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window heightInc +.AP Tk_Window tkwin in +Token for window. +.AP int reqWidth in +Width in grid units that corresponds to the pixel dimension \fItkwin\fR +has requested via \fBTk_GeometryRequest\fR. +.AP int reqHeight in +Height in grid units that corresponds to the pixel dimension \fItkwin\fR +has requested via \fBTk_GeometryRequest\fR. +.AP int widthInc in +Width of one grid unit, in pixels. +.AP int heightInc in +Height of one grid unit, in pixels. +.BE +.SH DESCRIPTION +.PP +\fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's +toplevel window and specifies the geometry of the grid. +\fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR +option is true. +It restricts interactive resizing of \fItkwin\fR's toplevel window so +that the space allocated to the toplevel is equal to its requested +size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR. +Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are +passed to the window manager so that it can report the window's +size in grid units during interactive resizes. +If \fItkwin\fR's configuration changes (e.g., the size of a grid unit +changes) then the widget should invoke \fBTk_SetGrid\fR again with the new +information. +.PP +\fBTk_UnsetGrid\fR cancels gridded geometry management for +\fItkwin\fR's toplevel window. +.PP +For each toplevel window there can be at most one internal window +with gridding enabled. +If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some +other window is already controlling gridding for \fItkwin\fR's +toplevel, the calls for the new window have no effect. +.PP +See the \fBwm\fR manual entry for additional information on gridded geometry +management. +.SH KEYWORDS +grid, window, window manager diff --git a/tk8.6/doc/SetOptions.3 b/tk8.6/doc/SetOptions.3 new file mode 100644 index 0000000..b5f0782 --- /dev/null +++ b/tk8.6/doc/SetOptions.3 @@ -0,0 +1,656 @@ +'\" +'\" Copyright (c) 1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_OptionTable +\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR +.sp +\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR +.sp +int +\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR +.sp +int +\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR +.sp +\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR +.sp +\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR +.sp +Tcl_Obj * +\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +.sp +Tcl_Obj * +\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +.sp +\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR +.sp +int +\fBTk_Offset(\fItype, field\fB)\fR +.SH ARGUMENTS +.AS Tk_SavedOptions "*const objv[]" in/out +.AP Tcl_Interp *interp in +A Tcl interpreter. Most procedures use this only for returning error +messages; if it is NULL then no error messages are returned. For +\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the +interpreter in which the option table will be used. +.AP "const Tk_OptionSpec" *templatePtr in +Points to an array of static information that describes the configuration +options that are supported. Used to build a Tk_OptionTable. The information +pointed to by this argument must exist for the lifetime of the Tk_OptionTable. +.AP Tk_OptionTable optionTable in +Token for an option table. Must have been returned by a previous call +to \fBTk_CreateOptionTable\fR. +.AP char *recordPtr in/out +Points to structure in which values of configuration options are stored; +fields of this record are modified by procedures such as \fBTk_SetOptions\fR +and read by procedures such as \fBTk_GetOptionValue\fR. +.AP Tk_Window tkwin in +For options such as \fBTK_OPTION_COLOR\fR, this argument indicates +the window in which the option will be used. If \fIoptionTable\fR uses +no window-dependent options, then a NULL value may be supplied for +this argument. +.AP int objc in +Number of values in \fIobjv\fR. +.AP Tcl_Obj "*const objv[]" in +Command-line arguments for setting configuring options. +.AP Tk_SavedOptions *savePtr out +If not NULL, the structure pointed to by this argument is filled +in with the old values of any options that were modified and old +values are restored automatically if an error occurs in \fBTk_SetOptions\fR. +.AP int *maskPtr out +If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the +bit-wise OR of the \fItypeMask\fR fields for the options that +were modified. +.AP Tk_SavedOptions *savedPtr in/out +Points to a structure previously filled in by \fBTk_SetOptions\fR with +old values of modified options. +.AP Tcl_Obj *namePtr in +The value of this object is the name of a particular option. If NULL +is passed to \fBTk_GetOptionInfo\fR then information is returned for +all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. +.AP "type name" type in +The name of the type of a record. +.AP "field name" field in +The name of a field in records of type \fItype\fR. +.BE +.SH DESCRIPTION +.PP +These procedures handle most of the details of parsing configuration +options such as those for Tk widgets. Given a description of what +options are supported, these procedures handle all the details of +parsing options and storing their values into a C structure associated +with the widget or object. The procedures were designed primarily for +widgets in Tk, but they can also be used for other kinds of objects that +have configuration options. In the rest of this manual page +.QW widget +will be used to refer to the object whose options are being managed; in +practice the object may not actually be a widget. The term +.QW "widget record" +is used to refer to the C-level structure in +which information about a particular widget or object is stored. +.PP +Note: the easiest way to learn how to use these procedures is to +look at a working example. In Tk, the simplest example is the code +that implements the button family of widgets, which is in \fBtkButton.c\fR. +Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. +.PP +In order to use these procedures, the code that implements the widget +must contain a static array of Tk_OptionSpec structures. This is a +template that describes the various options supported by that class of +widget; there is a separate template for each kind of widget. The +template contains information such as the name of each option, its type, +its default value, and where the value of the option is stored in the +widget record. See TEMPLATES below for more detail. +.PP +In order to process configuration options efficiently, the static +template must be augmented with additional information that is available +only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this +dynamic information from the template and returns a Tk_OptionTable token +that describes both the static and dynamic information. All of the +other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable +token as argument. Typically, \fBTk_CreateOptionTable\fR is called the +first time that a widget of a particular class is created and the +resulting Tk_OptionTable is used in the future for all widgets of that +class. A Tk_OptionTable may be used only in a single interpreter, given +by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an +option table is no longer needed \fBTk_DeleteOptionTable\fR should be +called to free all of its resources. All of the option tables +for a Tcl interpreter are freed automatically if the interpreter is deleted. +.PP +\fBTk_InitOptions\fR is invoked when a new widget is created to set the +default values for all of the widget's configuration options that do not +have \fBTK_OPTION_DONT_SET_DEFAULT\fR set in their \fIflags\fR field. +\fBTk_InitOptions\fR is passed a token for an option table +(\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR), +which is the C structure that holds information about this widget. +\fBTk_InitOptions\fR uses the information in the option table to choose an +appropriate default for each option, except those having +\fBTK_OPTION_DONT_SET_DEFAULT\fR set, then it stores the default value +directly into the widget record, overwriting any information that was +already present in the widget record. \fBTk_InitOptions\fR normally +returns \fBTCL_OK\fR. If an error occurred while setting the default +values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR +is returned and an error message is left in \fIinterp\fR's result if +\fIinterp\fR is not NULL. +.PP +\fBTk_SetOptions\fR is invoked to modify configuration options based +on information specified in a Tcl command. The command might be one that +creates a new widget, or a command that modifies options on an existing +widget. The \fIobjc\fR and \fIobjv\fR arguments describe the +values of the arguments from the Tcl command. \fIObjv\fR must contain +an even number of objects: the first object of each pair gives the name of +an option and the second object gives the new value for that option. +\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that +the new value of the option conforms to the type in \fIoptionTable\fR, +and stores the value of the option into the widget record given by +\fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR. If +an error occurred (such as an unknown option name or an illegal option +value) then \fBTCL_ERROR\fR is returned and an error message is left in +\fIinterp\fR's result if \fIinterp\fR is not NULL. +.PP +\fBTk_SetOptions\fR has two additional features. First, if the +\fImaskPtr\fR argument is not NULL then it points to an integer +value that is filled in with information about the options that were +modified. For each option in the template passed to +\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The +bits of this field are defined by the code that implements the widget; +for example, each bit might correspond to a particular configuration option. +Alternatively, bits might be used functionally. For example, one bit might +be used for redisplay: all options that affect the widget's display, such +that changing the option requires the widget to be redisplayed, might have +that bit set. Another bit might indicate that the geometry of the widget +must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the +\fItypeMask\fR fields from all the options that were modified and returns +this value at *\fImaskPtr\fR; the caller can then use this information +to optimize itself so that, for example, it does not redisplay the widget +if the modified options do not affect the widget's appearance. +.PP +The second additional feature of \fBTk_SetOptions\fR has to do with error +recovery. If an error occurs while processing configuration options, this +feature makes it possible to restore all the configuration options to their +previous values. Errors can occur either while processing options in +\fBTk_SetOptions\fR or later in the caller. In many cases the caller does +additional processing after \fBTk_SetOptions\fR returns; for example, it +might use an option value to set a trace on a variable and may detect +an error if the variable is an array instead of a scalar. Error recovery +is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument +to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized +Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR +overwrites the structure pointed to by \fIsavePtr\fR with information +about the old values of any options modified by the procedure. +If \fBTk_SetOptions\fR returns successfully, the +caller uses the structure in one of two ways. If the caller completes +its processing of the new options without any errors, then it must pass +the structure to \fBTk_FreeSavedOptions\fR so that the old values can be +freed. If the caller detects an error in its processing of the new +options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, +which will copy the old values back into the widget record and free +the new values. +If \fBTk_SetOptions\fR detects an error then it automatically restores +any options that had already been modified and leaves *\fIsavePtr\fR in +an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or +\fBTk_RestoreSavedOptions\fR. +If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then +\fBTk_SetOptions\fR frees each old option value immediately when it sets a new +value for the option. In this case, if an error occurs in the third +option, the old values for the first two options cannot be restored. +.PP +\fBTk_GetOptionValue\fR returns the current value of a configuration option +for a particular widget. The \fInamePtr\fR argument contains the name of +an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR +to lookup the option and extract its value from the widget record +pointed to by \fIrecordPtr\fR, then it returns an object containing +that value. If an error occurs (e.g., because \fInamePtr\fR contains an +unknown option name) then NULL is returned and an error message is left +in \fIinterp\fR's result unless \fIinterp\fR is NULL. +.PP +\fBTk_GetOptionInfo\fR returns information about configuration options in +a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR +argument is not NULL, it points to an object that gives the name of a +configuration option; \fBTk_GetOptionInfo\fR returns an object containing +a list with five elements, which are the name of the option, the name and +class used for the option in the option database, the default value for +the option, and the current value for the option. If the \fInamePtr\fR +argument is NULL, then \fBTk_GetOptionInfo\fR returns information about +all options in the form of a list of lists; each sublist describes one +option. Synonym options are handled differently depending on whether +\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for +each synonym option has only two elements, which are the name of the +option and the name of the other option that it refers to; if \fInamePtr\fR +is non-NULL and names a synonym option then the object returned +is the five-element list +for the other option that the synonym refers to. If an error occurs +(e.g., because \fInamePtr\fR contains an unknown option name) then NULL +is returned and an error message is left in \fIinterp\fR's result unless +\fIinterp\fR is NULL. +.PP +\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. +It frees all of the resources associated with any of the configuration +options defined in \fIrecordPtr\fR by \fIoptionTable\fR. +.PP +The \fBTk_Offset\fR macro is provided as a safe way of generating the +\fIobjOffset\fR and \fIinternalOffset\fR values for entries in +Tk_OptionSpec structures. It takes two arguments: the name of a type +of record, and the name of a field in that record. It returns the byte +offset of the named field in records of the given type. +.SH "TEMPLATES" +.PP +The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR +via its \fItemplatePtr\fR argument describes the configuration options +supported by a particular class of widgets. Each structure specifies +one configuration option and has the following fields: +.CS +typedef struct { + Tk_OptionType \fItype\fR; + const char *\fIoptionName\fR; + const char *\fIdbName\fR; + const char *\fIdbClass\fR; + const char *\fIdefValue\fR; + int \fIobjOffset\fR; + int \fIinternalOffset\fR; + int \fIflags\fR; + const void *\fIclientData\fR; + int \fItypeMask\fR; +} \fBTk_OptionSpec\fR; +.CE +The \fItype\fR field indicates what kind of configuration option this is +(e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for +an integer value). \fIType\fR determines how the +value of the option is parsed (more on this below). +The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; +it is the name used for the option in Tcl commands and passed to +procedures via the \fIobjc\fR or \fInamePtr\fR arguments. +The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR +to look up a default value for this option in the option database; if +\fIdbName\fR is NULL then the option database is not used by +\fBTk_InitOptions\fR for this option. The \fIdefValue\fR field +specifies a default value for this configuration option if no +value is specified in the option database. The \fIobjOffset\fR and +\fIinternalOffset\fR fields indicate where to store the value of this +option in widget records (more on this below); values for the \fIobjOffset\fR +and \fIinternalOffset\fR fields should always be generated with the +\fBTk_Offset\fR macro. +The \fIflags\fR field contains additional information +to control the processing of this configuration option (see below +for details). +\fIClientData\fR provides additional type-specific data needed +by certain types. For instance, for \fBTK_OPTION_COLOR\fR types, +\fIclientData\fR is a string giving the default value to use on +monochrome displays. See the descriptions of the different types +below for details. +The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to +return information about which options were modified; see the description +of \fBTk_SetOptions\fR above for details. +.PP +When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an +option into the widget record, they can do it in either of two ways. +If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than +or equal to zero, then the value of the option is stored as a +(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. +If the \fIinternalOffset\fR field of the Tk_OptionSpec is +greater than or equal to zero, then the value of the option is stored +in a type-specific internal form at the location in the widget record +given by \fIinternalOffset\fR. For example, if the option's type is +\fBTK_OPTION_INT\fR then the internal form is an integer. If the +\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the +value is not stored in that form. At least one of the offsets must be +greater than or equal to zero. +.PP +The \fIflags\fR field consists of one or more bits ORed together. The +following flags are supported: +.TP +\fBTK_OPTION_NULL_OK\fR +If this bit is set for an option then an empty string will be accepted as +the value for the option and the resulting internal form will be a NULL +pointer, a zero value, or \fBNone\fR, depending on the type of the option. +If the flag is not set then empty strings will result in errors. +\fBTK_OPTION_NULL_OK\fR is typically used to allow a +feature to be turned off entirely, e.g. set a cursor value to +\fBNone\fR so that a window simply inherits its parent's cursor. +Not all option types support the \fBTK_OPTION_NULL_OK\fR +flag; for those that do, there is an explicit indication of that fact +in the descriptions below. +.TP +\fBTK_OPTION_DONT_SET_DEFAULT\fR +If this bit is set for an option then no default value will be set in +\fBTk_InitOptions\fR for this option. Neither the option database, nor any +system default value, nor \fIoptionTable\fR are used to give a default +value to this option. Instead it is assumed that the caller has already +supplied a default value in the widget code. +.PP +The \fItype\fR field of each Tk_OptionSpec structure determines +how to parse the value of that configuration option. The +legal value for \fItype\fR, and the corresponding actions, are +described below. If the type requires a \fItkwin\fR value to be +passed into procedures like \fBTk_SetOptions\fR, or if it uses +the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated +explicitly; if not mentioned, the type requires neither \fItkwin\fR +nor \fIclientData\fR. +.TP +\fBTK_OPTION_ANCHOR\fR +The value must be a standard anchor position such as \fBne\fR or +\fBcenter\fR. The internal form is a Tk_Anchor value like the ones +returned by \fBTk_GetAnchorFromObj\fR. +.TP +\fBTK_OPTION_BITMAP\fR +The value must be a standard Tk bitmap name. The internal form is a +Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_BOOLEAN\fR +The value must be a standard boolean value such as \fBtrue\fR or +\fBno\fR. The internal form is an integer with value 0 or 1. +.TP +\fBTK_OPTION_BORDER\fR +The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. +The internal form is a Tk_3DBorder token like the ones returned +by \fBTk_Alloc3DBorderFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_COLOR\fR +The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. +The internal form is an (XColor *) token like the ones returned by +\fBTk_AllocColorFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_CURSOR\fR +The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. +The internal form is a Tk_Cursor token like the ones returned by +\fBTk_AllocCursorFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and when the option is set the cursor +for the window is changed by calling \fBXDefineCursor\fR. This +option type also supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_CUSTOM\fR +This option allows applications to define new option types. The +clientData field of the entry points to a structure defining the new +option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. +.TP +\fBTK_OPTION_DOUBLE\fR +The string value must be a floating-point number in +the format accepted by \fBstrtol\fR. The internal form is a C +\fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR +flag; if a NULL value is set, the internal representation is set to zero. +.TP +\fBTK_OPTION_END\fR +Marks the end of the template. There must be a Tk_OptionSpec structure +with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the +\fIclientData\fR field of this structure is not NULL, then it points to +an additional array of Tk_OptionSpec's, which is itself terminated by +another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily +deeply. This feature allows common options to be shared by several +widget classes. +.TP +\fBTK_OPTION_FONT\fR +The value must be a standard font name such as \fBTimes 16\fR. +The internal form is a Tk_Font handle like the ones returned by +\fBTk_AllocFontFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_INT\fR +The string value must be an integer in the format accepted by +\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to +specify octal or hexadecimal numbers, respectively). The internal +form is a C \fBint\fR value. +.TP +\fBTK_OPTION_JUSTIFY\fR +The value must be a standard justification value such as \fBleft\fR. +The internal form is a Tk_Justify like the values returned by +\fBTk_GetJustifyFromObj\fR. +.TP +\fBTK_OPTION_PIXELS\fR +The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. +The internal form is an integer value giving a +distance in pixels, like the values returned by +\fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field is not +used then information about the original value of this option will be lost. +See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option +type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the +internal representation is set to zero. +.TP +\fBTK_OPTION_RELIEF\fR +The value must be standard relief such as \fBraised\fR. +The internal form is an integer relief value such as +\fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR +flag; if the empty string is specified as the value for the option, +the integer relief value is set to \fBTK_RELIEF_NULL\fR. +.TP +\fBTK_OPTION_STRING\fR +The value may be any string. The internal form is a (char *) pointer +that points to a dynamically allocated copy of the value. +This option type supports the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fBTK_OPTION_STRING_TABLE\fR +For this type, \fIclientData\fR is a pointer to an array of strings +suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must +be one of the strings in the table, or a unique abbreviation of +one of the strings. The internal form is an integer giving the index +into the table of the matching string, like the return value +from \fBTcl_GetStringFromObj\fR. +.TP +\fBTK_OPTION_SYNONYM\fR +This type is used to provide alternative names for an option (for +example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). +The \fBclientData\fR field is a string that gives the name of another +option in the same table. Whenever the synonym option is used, the +information from the other option will be used instead. +.TP +\fBTK_OPTION_WINDOW\fR +The value must be a window path name. The internal form is a +\fBTk_Window\fR token for the window. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR (in order to identify the application), +and it supports the \fBTK_OPTION_NULL_OK\fR flag. +.SH "STORAGE MANAGEMENT ISSUES" +.PP +If a field of a widget record has its offset stored in the \fIobjOffset\fR +or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the +procedures described here will handle all of the storage allocation and +resource management issues associated with the field. When the value +of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR) +will automatically free any resources associated with the old value, such as +Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for +\fBTK_OPTION_STRING\fR options. For an option stored as an object using the +\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the +object pointed to by the \fIobjv\fR value from the call to +\fBTk_SetOptions\fR. The reference count for this object is incremented +when a pointer to it is stored in the widget record and decremented when +the option is modified. When the widget is deleted +\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources +associated with all options and decrement reference counts for any +objects. +.PP +However, the widget code is responsible for storing NULL or \fBNone\fR in +all pointer and token fields before invoking \fBTk_InitOptions\fR. +This is needed to allow proper cleanup in the rare case where +an error occurs in \fBTk_InitOptions\fR. +.SH "OBJOFFSET VS. INTERNALOFFSET" +.PP +In most cases it is simplest to use the \fIinternalOffset\fR field of +a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This +makes the internal form of the value immediately available to the +widget code so the value does not have to be extracted from an object +each time it is used. However, there are two cases where the +\fIobjOffset\fR field is useful. The first case is for +\fBTK_OPTION_PIXELS\fR options. In this case, the internal form is +an integer pixel value that is valid only for a particular screen. +If the value of the option is retrieved, it will be returned as a simple +number. For example, after the command \fB.b configure \-borderwidth 2m\fR, +the command \fB.b configure \-borderwidth\fR might return 7, which is the +integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses +the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options +it is better to use the \fIobjOffset\fR field. In this case the original +value of the option is retained in the object and can be returned when +the option is retrieved. In most cases it is convenient to use the +\fIinternalOffset\fR field as well, so that the integer value is +immediately available for use in the widget code (alternatively, +\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from +the object whenever it is needed). Note: the problem of losing information +on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. +.PP +The second reason to use the \fIobjOffset\fR field is in order to +implement new types of options not supported by these procedures. +To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as +the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field +but not the \fIinternalOffset\fR field. Then, after calling +\fBTk_SetOptions\fR, convert the object to internal form yourself. +.SH "CUSTOM OPTION TYPES" +.PP +Applications can extend the built-in configuration types with +additional configuration types by writing procedures to parse, print, +free, and restore saved copies of the type and creating a structure +pointing to those procedures: +.CS +typedef struct Tk_ObjCustomOption { + char *name; + Tk_CustomOptionSetProc *\fIsetProc\fR; + Tk_CustomOptionGetProc *\fIgetProc\fR; + Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; + Tk_CustomOptionFreeProc *\fIfreeProc\fR; + ClientData \fIclientData\fR; +} \fBTk_ObjCustomOption\fR; + +typedef int \fBTk_CustomOptionSetProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tk_Window \fItkwin\fR, + Tcl_Obj **\fIvaluePtr\fR, + char *\fIrecordPtr\fR, + int \fIinternalOffset\fR, + char *\fIsaveInternalPtr\fR, + int \fIflags\fR); + +typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIrecordPtr\fR, + int \fIinternalOffset\fR); + +typedef void \fBTk_CustomOptionRestoreProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIinternalPtr\fR, + char *\fIsaveInternalPtr\fR); + +typedef void \fBTk_CustomOptionFreeProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIinternalPtr\fR); +.CE +.PP +The Tk_ObjCustomOption structure contains six fields: a name +for the custom option type; pointers to the four procedures; and a +\fIclientData\fR value to be passed to those procedures when they are +invoked. The \fIclientData\fR value typically points to a structure +containing information that is needed by the procedures when they are +parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR +may be NULL, indicating that no function should be called for those +operations. +.PP +The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to +convert a Tcl_Obj into an internal representation and store the +resulting value in the widget record. The arguments are: +.RS +.TP +\fIclientData\fR +A copy of the \fIclientData\fR field in the Tk_ObjCustomOption +structure. +.TP +\fIinterp\fR +A pointer to a Tcl interpreter, used for error reporting. +.TP +\fITkwin\fR +A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR +.TP +\fIvaluePtr\fR +A pointer to a reference to a Tcl_Obj describing the new value for the +option; it could have been specified explicitly in the call to +\fBTk_SetOptions\fR or it could come from the option database or a +default. If the objOffset for the option is non-negative (the option +value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj +pointer referenced by \fIvaluePtr\fR is the pointer that will be +stored at the objOffset for the option. \fISetProc\fR may modify the +value if necessary; for example, \fIsetProc\fR may change the value to +NULL to support the \fBTK_OPTION_NULL_OK\fR flag. +.TP +\fIrecordPtr\fR +A pointer to the start of the widget record to modify. +.TP +\fIinternalOffset\fR +Offset in bytes from the start of the widget record to the location +where the internal representation of the option value is to be placed. +.TP +\fIsaveInternalPtr\fR +A pointer to storage allocated in a Tk_SavedOptions structure for the +internal representation of the original option value. Before setting +the option to its new value, \fIsetProc\fR should set the value +referenced by \fIsaveInternalPtr\fR to the original value of the +option in order to support \fBTk_RestoreSavedOptions\fR. +.TP +\fIflags\fR +A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the +option +.RE +.PP +\fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful +processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error +message may be left in the Tcl interpreter given by \fIinterp\fR in +the case of an error. +.PP +The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and +\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the +internal representation of an option. The \fIclientData\fR argument +is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption +structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to +\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR +is a pointer to the beginning of the widget record to query. +\fIInternalOffset\fR is the offset in bytes from the beginning of the +widget record to the location where the internal representation of the +option value is stored. \fIGetProc\fR must return a pointer to a +Tcl_Obj representing the value of the option. +.PP +The \fIrestoreProc\fR procedure is invoked by +\fBTk_RestoreSavedOptions\fR to restore a previously saved internal +representation of a custom option value. The \fIclientData\fR argument +is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption +structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to +\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR +is a pointer to the location where internal representation of the +option value is stored. +\fISaveInternalPtr\fR is a pointer to the saved value. +\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to +\fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not +free any memory associated with either \fIinternalPtr\fR or +\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that +memory if necessary. \fIRestoreProc\fR has no return value. +.PP +The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and +\fBTk_FreeSavedOptions\fR to free any storage allocated for the +internal representation of a custom option. The \fIclientData\fR argument +is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption +structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to +\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR +is a pointer to the location where the internal representation of the +option value is stored. The \fIfreeProc\fR must free any storage +associated with the option. \fIFreeProc\fR has no return value. +.SH KEYWORDS +anchor, bitmap, boolean, border, color, configuration option, +cursor, double, font, integer, justify, +pixels, relief, screen distance, synonym diff --git a/tk8.6/doc/SetVisual.3 b/tk8.6/doc/SetVisual.3 new file mode 100644 index 0000000..6d3fd83 --- /dev/null +++ b/tk8.6/doc/SetVisual.3 @@ -0,0 +1,50 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_SetWindowVisual \- change visual characteristics of window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) +.SH ARGUMENTS +.AS "Tk_Window int" colormap +.AP Tk_Window tkwin in +Token for window. +.AP Visual *visual in +New visual type to use for \fItkwin\fR. +.AP "int" depth in +Number of bits per pixel desired for \fItkwin\fR. +.AP Colormap colormap in +New colormap for \fItkwin\fR, which must be compatible with +\fIvisual\fR and \fIdepth\fR. +.BE +.SH DESCRIPTION +.PP +When Tk creates a new window it assigns it the default visual +characteristics (visual, depth, and colormap) for its screen. +\fBTk_SetWindowVisual\fR may be called to change them. +\fBTk_SetWindowVisual\fR must be called before the window has +actually been created in X (e.g. before \fBTk_MapWindow\fR or +\fBTk_MakeWindowExist\fR has been invoked for the window). +The safest thing is to call \fBTk_SetWindowVisual\fR immediately +after calling \fBTk_CreateWindow\fR. +If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR +is called then it returns 0 and does not make any changes; otherwise +it returns 1 to signify that the operation +completed successfully. +.PP +Note: \fBTk_SetWindowVisual\fR should not be called if you just want +to change a window's colormap without changing its visual or depth; +call \fBTk_SetWindowColormap\fR instead. +.SH KEYWORDS +colormap, depth, visual diff --git a/tk8.6/doc/StrictMotif.3 b/tk8.6/doc/StrictMotif.3 new file mode 100644 index 0000000..4319d53 --- /dev/null +++ b/tk8.6/doc/StrictMotif.3 @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_StrictMotif \- Return value of tk_strictMotif variable +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_StrictMotif\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for window. +.BE +.SH DESCRIPTION +.PP +This procedure returns the current value of the \fBtk_strictMotif\fR +variable in the interpreter associated with \fItkwin\fR's application. +The value is returned as an integer that is either 0 or 1. +1 means that strict Motif compliance has been requested, so anything +that is not part of the Motif specification should be avoided. +0 means that +.QW Motif-like +is good enough, and extra features are welcome. +.PP +This procedure uses a link to the Tcl variable to provide much +faster access to the variable's value than could be had by calling +\fBTcl_GetVar\fR. +.SH KEYWORDS +Motif compliance, tk_strictMotif variable diff --git a/tk8.6/doc/TextLayout.3 b/tk8.6/doc/TextLayout.3 new file mode 100644 index 0000000..5729a44 --- /dev/null +++ b/tk8.6/doc/TextLayout.3 @@ -0,0 +1,276 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_TextLayout +\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR +.sp +void +\fBTk_FreeTextLayout(\fIlayout\fB)\fR +.sp +void +\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR +.sp +void +\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR +.sp +int +\fBTk_PointToChar(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR +.sp +int +\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR +.sp +void +\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR +.SH ARGUMENTS +.AS Tk_TextLayout "*xPtr, *yPtr" +.AP Tk_Font tkfont in +Font to use when constructing and displaying a text layout. The +\fItkfont\fR must remain valid for the lifetime of the text layout. Must +have been returned by a previous call to \fBTk_GetFont\fR. +.AP "const char" *string in +Potentially multi-line string whose dimensions are to be computed and +stored in the text layout. The \fIstring\fR must remain valid for the +lifetime of the text layout. +.AP int numChars in +The number of characters to consider from \fIstring\fR. If +\fInumChars\fR is less than 0, then assumes \fIstring\fR is null +terminated and uses \fBTcl_NumUtfChars\fR to determine the length of +\fIstring\fR. +.AP int wrapLength in +Longest permissible line length, in pixels. Lines in \fIstring\fR will +automatically be broken at word boundaries and wrapped when they reach +this length. If \fIwrapLength\fR is too small for even a single +character to fit on a line, it will be expanded to allow one character to +fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic +wrapping; lines will get as long as they need to be and only wrap if a +newline/return character is encountered. +.AP Tk_Justify justify in +How to justify the lines in a multi-line text layout. Possible values +are \fBTK_JUSTIFY_LEFT\fR, \fBTK_JUSTIFY_CENTER\fR, or +\fBTK_JUSTIFY_RIGHT\fR. If the text layout only occupies a single +line, then \fIjustify\fR is irrelevant. +.AP int flags in +Various flag bits OR-ed together. \fBTK_IGNORE_TABS\fR means that tab +characters should not be expanded to the next tab stop. +\fBTK_IGNORE_NEWLINES\fR means that newline/return characters should +not cause a line break. If either tabs or newlines/returns are +ignored, then they will be treated as regular characters, being +measured and displayed in a platform-dependent manner as described in +\fBTk_MeasureChars\fR, and will not have any special behaviors. +.AP int *widthPtr out +If non-NULL, filled with either the width, in pixels, of the widest +line in the text layout, or the width, in pixels, of the bounding box for the +character specified by \fIindex\fR. +.AP int *heightPtr out +If non-NULL, filled with either the total height, in pixels, of all +the lines in the text layout, or the height, in pixels, of the bounding +box for the character specified by \fIindex\fR. +.AP Tk_TextLayout layout in +A token that represents the cached layout information about the single-font, +multi-line, justified piece of text. This token is returned by +\fBTk_ComputeTextLayout\fR. +.AP Display *display in +Display on which to draw. +.AP Drawable drawable in +Window or pixmap in which to draw. +.AP GC gc in +Graphics context to use for drawing text layout. The font selected in +this GC must correspond to the \fItkfont\fR used when constructing the +text layout. +.AP int "x, y" in +Point, in pixels, at which to place the upper-left hand corner of the +text layout when it is being drawn, or the coordinates of a point (with +respect to the upper-left hand corner of the text layout) to check +against the text layout. +.AP int firstChar in +The index of the first character to draw from the given text layout. +The number 0 means to draw from the beginning. +.AP int lastChar in +The index of the last character up to which to draw. The character +specified by \fIlastChar\fR itself will not be drawn. A number less +than 0 means to draw all characters in the text layout. +.AP int underline in +Index of the single character to underline in the text layout, or a number +less than 0 for no underline. +.AP int index in +The index of the character whose bounding box is desired. The bounding +box is computed with respect to the upper-left hand corner of the text layout. +.AP int "*xPtr, *yPtr" out +Filled with the upper-left hand corner, in pixels, of the bounding box +for the character specified by \fIindex\fR. Either or both \fIxPtr\fR +and \fIyPtr\fR may be NULL, in which case the corresponding value +is not calculated. +.AP int "width, height" in +Specifies the width and height, in pixels, of the rectangular area to +compare for intersection against the text layout. +.AP Tcl_Interp *interp out +Postscript code that will print the text layout is appended to +the result of interpreter \fIinterp\fR. +.BE +.SH DESCRIPTION +.PP +These routines are for measuring and displaying single-font, multi-line, +justified text. To measure and display simple single-font, single-line +strings, refer to the documentation for \fBTk_MeasureChars\fR. There is +no programming interface in the core of Tk that supports multi-font, +multi-line text; support for that behavior must be built on top of +simpler layers. +Note that unlike the lower level text display routines, the functions +described here all operate on character-oriented lengths and indices +rather than byte-oriented values. See the description of +\fBTcl_UtfAtIndex\fR for more details on converting between character +and byte offsets. +.PP +The routines described here are built on top of the programming interface +described in the \fBTk_MeasureChars\fR documentation. Tab characters and +newline/return characters may be treated specially by these procedures, +but all other characters are passed through to the lower level. +.PP +\fBTk_ComputeTextLayout\fR computes the layout information needed to +display a single-font, multi-line, justified \fIstring\fR of text and +returns a Tk_TextLayout token that holds this information. This token is +used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, +\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The +\fIstring\fR and \fItkfont\fR used when computing the layout must remain +valid for the lifetime of this token. +.PP +\fBTk_FreeTextLayout\fR is called to release the storage associated with +\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used +in any other text layout procedures once it has been released. +.PP +\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a +single-font, multi-line, justified string of text at the specified location. +.PP +\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to +display an underline below an individual character. This procedure does +not draw the text, just the underline. To produce natively underlined +text, an underlined font should be constructed and used. All characters, +including tabs, newline/return characters, and spaces at the ends of +lines, can be underlined using this method. However, the underline will +never be drawn outside of the computed width of \fIlayout\fR; the +underline will stop at the edge for any character that would extend +partially outside of \fIlayout\fR, and the underline will not be visible +at all for any character that would be located completely outside of the +layout. +.PP +\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the +character closest to the given point. The point is specified with respect +to the upper-left hand corner of the \fIlayout\fR, which is considered to be +located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be +considered closest to the first character in the text layout; any point +whose \fIy\fR-value is greater than the height of the text layout will be +considered closest to the last character in the text layout. Any point +whose \fIx\fR-value is less than 0 will be considered closest to the first +character on that line; any point whose \fIx\fR-value is greater than the +width of the text layout will be considered closest to the last character on +that line. The return value is the index of the character that was closest +to the point, or one more than the index of any character (to indicate that +the point was after the end of the string and that the corresponding caret +would be at the end of the string). Given a \fIlayout\fR with no characters, +the value 0 will always be returned, referring to a hypothetical zero-width +placeholder character. +.PP +\fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the +bounding box for the character specified by \fIindex\fR. The width of the +bounding box is the advance width of the character, and does not include any +left or right bearing. Any character that extends partially outside of +\fIlayout\fR is considered to be truncated at the edge. Any character +that would be located completely outside of \fIlayout\fR is considered to +be zero-width and pegged against the edge. The height of the bounding +box is the line height for this font, extending from the top of the +ascent to the bottom of the descent; information about the actual height +of individual letters is not available. For measurement purposes, a +\fIlayout\fR that contains no characters is considered to contain a +single zero-width placeholder character at index 0. If \fIindex\fR was +not a valid character index, the return value is 0 and \fI*xPtr\fR, +\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. +Otherwise, if \fIindex\fR did specify a valid, the return value is +non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and +\fI*heightPtr\fR are filled with the bounding box information for the +character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or +\fIheightPtr\fR are NULL, the corresponding value is not calculated or +stored. +.PP +\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from +the given point (\fIx, y\fR) to the characters in \fIlayout\fR. +Newline/return characters and non-displaying space characters that occur at +the end of individual lines in the text layout are ignored for hit detection +purposes, but tab characters are not. The return value is 0 if the point +actually hits the \fIlayout\fR. If the point did not hit the \fIlayout\fR +then the return value is the distance in pixels from the point to the +\fIlayout\fR. +.PP +\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies +entirely inside, entirely outside, or overlaps a given rectangle. +Newline/return characters and non-displaying space characters that occur +at the end of individual lines in the \fIlayout\fR are ignored for +intersection calculations. The return value is \-1 if the \fIlayout\fR is +entirely outside of the rectangle, 0 if it overlaps, and 1 if it is +entirely inside of the rectangle. +.PP +\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript +array of strings that represent the individual lines in \fIlayout\fR. It +is the responsibility of the caller to take the Postscript array of +strings and add some Postscript function operate on the array to render +each of the lines. The code that represents the Postscript array of +strings is appended to interpreter \fIinterp\fR's result. +.SH "DISPLAY MODEL" +.PP +When measuring a text layout, space characters that occur at the end of a +line are ignored. The space characters still exist and the insertion point +can be positioned amongst them, but their additional width is ignored when +justifying lines or returning the total width of a text layout. All +end-of-line space characters are considered to be attached to the right edge +of the line; this behavior is logical for left-justified text and reasonable +for center-justified text, but not very useful when editing right-justified +text. Spaces are considered variable width characters; the first space that +extends past the edge of the text layout is clipped to the edge, and any +subsequent spaces on the line are considered zero width and pegged against +the edge. Space characters that occur in the middle of a line of text are +not suppressed and occupy their normal space width. +.PP +Tab characters are not ignored for measurement calculations. If wrapping +is turned on and there are enough tabs on a line, the next tab will wrap +to the beginning of the next line. There are some possible strange +interactions between tabs and justification; tab positions are calculated +and the line length computed in a left-justified world, and then the +whole resulting line is shifted so it is centered or right-justified, +causing the tab columns not to align any more. +.PP +When wrapping is turned on, lines may wrap at word breaks (space or tab +characters) or newline/returns. A dash or hyphen character in the middle +of a word is not considered a word break. \fBTk_ComputeTextLayout\fR +always attempts to place at least one word on each line. If it cannot +because the \fIwrapLength\fR is too small, the word will be broken and as +much as fits placed on the line and the rest on subsequent line(s). If +\fIwrapLength\fR is so small that not even one character can fit on a +given line, the \fIwrapLength\fR is ignored for that line and one +character will be placed on the line anyhow. When wrapping is turned +off, only newline/return characters may cause a line break. +.PP +When a text layout has been created using an underlined \fItkfont\fR, +then any space characters that occur at the end of individual lines, +newlines/returns, and tabs will not be displayed underlined when +\fBTk_DrawTextLayout\fR is called, because those characters are never +actually drawn \- they are merely placeholders maintained in the +\fIlayout\fR. +.SH KEYWORDS +font diff --git a/tk8.6/doc/TkInitStubs.3 b/tk8.6/doc/TkInitStubs.3 new file mode 100644 index 0000000..04f5611 --- /dev/null +++ b/tk8.6/doc/TkInitStubs.3 @@ -0,0 +1,79 @@ +'\" +'\" 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 new file mode 100644 index 0000000..7bc46dd --- /dev/null +++ b/tk8.6/doc/Tk_Init.3 @@ -0,0 +1,85 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ea5f771 --- /dev/null +++ b/tk8.6/doc/Tk_Main.3 @@ -0,0 +1,70 @@ +'\" +'\" 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 new file mode 100644 index 0000000..f937963 --- /dev/null +++ b/tk8.6/doc/WindowId.3 @@ -0,0 +1,188 @@ +'\" +'\" 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 new file mode 100644 index 0000000..21c4f1b --- /dev/null +++ b/tk8.6/doc/bell.n @@ -0,0 +1,34 @@ +'\" +'\" 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 new file mode 100644 index 0000000..c260bce --- /dev/null +++ b/tk8.6/doc/bind.n @@ -0,0 +1,730 @@ +'\" +'\" 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 new file mode 100644 index 0000000..dc3973b --- /dev/null +++ b/tk8.6/doc/bindtags.n @@ -0,0 +1,102 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ead3311 --- /dev/null +++ b/tk8.6/doc/bitmap.n @@ -0,0 +1,124 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ab2fd8a --- /dev/null +++ b/tk8.6/doc/busy.n @@ -0,0 +1,275 @@ +'\" +'\" 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 new file mode 100644 index 0000000..233feb6 --- /dev/null +++ b/tk8.6/doc/button.n @@ -0,0 +1,210 @@ +'\" +'\" 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 new file mode 100644 index 0000000..5b65283 --- /dev/null +++ b/tk8.6/doc/canvas.n @@ -0,0 +1,1923 @@ +'\" +'\" 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 new file mode 100644 index 0000000..bfefca4 --- /dev/null +++ b/tk8.6/doc/checkbutton.n @@ -0,0 +1,293 @@ +'\" +'\" 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 new file mode 100644 index 0000000..015b17d --- /dev/null +++ b/tk8.6/doc/chooseColor.n @@ -0,0 +1,48 @@ +'\" +'\" 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 new file mode 100644 index 0000000..e441d78 --- /dev/null +++ b/tk8.6/doc/chooseDirectory.n @@ -0,0 +1,71 @@ +'\" +'\" 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 new file mode 100644 index 0000000..6f047dd --- /dev/null +++ b/tk8.6/doc/clipboard.n @@ -0,0 +1,157 @@ +'\" +'\" 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 new file mode 100644 index 0000000..dc7007b --- /dev/null +++ b/tk8.6/doc/colors.n @@ -0,0 +1,957 @@ +'\" +'\" 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 new file mode 100644 index 0000000..1313d3a --- /dev/null +++ b/tk8.6/doc/console.n @@ -0,0 +1,145 @@ +'\" +'\" 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 new file mode 100644 index 0000000..1662de4 --- /dev/null +++ b/tk8.6/doc/cursors.n @@ -0,0 +1,191 @@ +'\" +'\" 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 new file mode 100644 index 0000000..3d4743a --- /dev/null +++ b/tk8.6/doc/destroy.n @@ -0,0 +1,45 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH 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 new file mode 100644 index 0000000..d2031d3 --- /dev/null +++ b/tk8.6/doc/dialog.n @@ -0,0 +1,74 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ccfcd24 --- /dev/null +++ b/tk8.6/doc/entry.n @@ -0,0 +1,539 @@ +'\" +'\" 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 new file mode 100644 index 0000000..5109794 --- /dev/null +++ b/tk8.6/doc/event.n @@ -0,0 +1,604 @@ +'\" +'\" 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 new file mode 100644 index 0000000..4b8bb2a --- /dev/null +++ b/tk8.6/doc/focus.n @@ -0,0 +1,137 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ffcf971 --- /dev/null +++ b/tk8.6/doc/focusNext.n @@ -0,0 +1,60 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.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 new file mode 100644 index 0000000..72f9270 --- /dev/null +++ b/tk8.6/doc/font.n @@ -0,0 +1,409 @@ +'\" +'\" 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 new file mode 100644 index 0000000..bdd51c7 --- /dev/null +++ b/tk8.6/doc/fontchooser.n @@ -0,0 +1,181 @@ +'\" +'\" 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 new file mode 100644 index 0000000..72a22db --- /dev/null +++ b/tk8.6/doc/frame.n @@ -0,0 +1,139 @@ +'\" +'\" 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 new file mode 100644 index 0000000..d2323de --- /dev/null +++ b/tk8.6/doc/getOpenFile.n @@ -0,0 +1,207 @@ +'\" +'\" 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 new file mode 100644 index 0000000..a6d0d19 --- /dev/null +++ b/tk8.6/doc/grab.n @@ -0,0 +1,140 @@ +'\" +'\" 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 new file mode 100644 index 0000000..c558071 --- /dev/null +++ b/tk8.6/doc/grid.n @@ -0,0 +1,456 @@ +'\" +'\" 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 new file mode 100644 index 0000000..fd51cc0 --- /dev/null +++ b/tk8.6/doc/image.n @@ -0,0 +1,102 @@ +'\" +'\" 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 new file mode 100644 index 0000000..512c1a6 --- /dev/null +++ b/tk8.6/doc/keysyms.n @@ -0,0 +1,937 @@ +'\" +'\" 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 new file mode 100644 index 0000000..f2ba88c --- /dev/null +++ b/tk8.6/doc/label.n @@ -0,0 +1,130 @@ +'\" +'\" 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 new file mode 100644 index 0000000..857208e --- /dev/null +++ b/tk8.6/doc/labelframe.n @@ -0,0 +1,175 @@ +'\" +'\" 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 new file mode 100644 index 0000000..0126435 --- /dev/null +++ b/tk8.6/doc/license.terms @@ -0,0 +1,40 @@ +This software is copyrighted by the Regents of the University of +California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState +Corporation, Apple Inc. and other parties. The following terms apply to +all files associated with the software unless explicitly disclaimed in +individual files. + +The authors hereby grant permission to use, copy, modify, distribute, +and license this software and its documentation for any purpose, provided +that existing copyright notices are retained in all copies and that this +notice is included verbatim in any distributions. No written agreement, +license, or royalty fee is required for any of the authorized uses. +Modifications to this software may be copyrighted by their authors +and need not follow the licensing terms described here, provided that +the new terms are clearly indicated on the first page of each file where +they apply. + +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE +IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE +NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR +MODIFICATIONS. + +GOVERNMENT USE: If you are acquiring this software on behalf of the +U.S. government, the Government shall have only "Restricted Rights" +in the software and related documentation as defined in the Federal +Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you +are acquiring the software on behalf of the Department of Defense, the +software shall be classified as "Commercial Computer Software" and the +Government shall have only "Restricted Rights" as defined in Clause +252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the +authors grant the U.S. Government and others acting in its behalf +permission to use and distribute the software in accordance with the +terms specified in this license. diff --git a/tk8.6/doc/listbox.n b/tk8.6/doc/listbox.n new file mode 100644 index 0000000..66b75b9 --- /dev/null +++ b/tk8.6/doc/listbox.n @@ -0,0 +1,582 @@ +'\" +'\" 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 new file mode 100644 index 0000000..3673e98 --- /dev/null +++ b/tk8.6/doc/loadTk.n @@ -0,0 +1,69 @@ +'\" +'\" 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 new file mode 100644 index 0000000..8159a8b --- /dev/null +++ b/tk8.6/doc/lower.n @@ -0,0 +1,40 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH 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 new file mode 100644 index 0000000..ddd073d --- /dev/null +++ b/tk8.6/doc/man.macros @@ -0,0 +1,267 @@ +.\" 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 new file mode 100644 index 0000000..5742e23 --- /dev/null +++ b/tk8.6/doc/menu.n @@ -0,0 +1,837 @@ +'\" +'\" 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 new file mode 100644 index 0000000..023bf37 --- /dev/null +++ b/tk8.6/doc/menubar.n @@ -0,0 +1,38 @@ +'\" +'\" 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 new file mode 100644 index 0000000..08b52a0 --- /dev/null +++ b/tk8.6/doc/menubutton.n @@ -0,0 +1,202 @@ +'\" +'\" 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 new file mode 100644 index 0000000..bd635ac --- /dev/null +++ b/tk8.6/doc/message.n @@ -0,0 +1,150 @@ +'\" +'\" 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 new file mode 100644 index 0000000..6bcbc09 --- /dev/null +++ b/tk8.6/doc/messageBox.n @@ -0,0 +1,122 @@ +'\" +'\" 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 new file mode 100644 index 0000000..2763d64 --- /dev/null +++ b/tk8.6/doc/option.n @@ -0,0 +1,140 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH 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 new file mode 100644 index 0000000..42275ce --- /dev/null +++ b/tk8.6/doc/optionMenu.n @@ -0,0 +1,45 @@ +'\" +'\" 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 new file mode 100644 index 0000000..738a1c6 --- /dev/null +++ b/tk8.6/doc/options.n @@ -0,0 +1,358 @@ +'\" +'\" 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 new file mode 100644 index 0000000..217dba9 --- /dev/null +++ b/tk8.6/doc/pack-old.n @@ -0,0 +1,195 @@ +'\" +'\" 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 new file mode 100644 index 0000000..538af62 --- /dev/null +++ b/tk8.6/doc/pack.n @@ -0,0 +1,283 @@ +'\" +'\" 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 new file mode 100644 index 0000000..085c4c6 --- /dev/null +++ b/tk8.6/doc/palette.n @@ -0,0 +1,73 @@ +'\" +'\" 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 new file mode 100644 index 0000000..40997a9 --- /dev/null +++ b/tk8.6/doc/panedwindow.n @@ -0,0 +1,347 @@ +'\" +'\" 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 new file mode 100644 index 0000000..0fe0c61 --- /dev/null +++ b/tk8.6/doc/photo.n @@ -0,0 +1,543 @@ +'\" +'\" 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 new file mode 100644 index 0000000..3a092c2 --- /dev/null +++ b/tk8.6/doc/place.n @@ -0,0 +1,255 @@ +'\" +'\" 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 new file mode 100644 index 0000000..0d32362 --- /dev/null +++ b/tk8.6/doc/popup.n @@ -0,0 +1,49 @@ +'\" +'\" 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 new file mode 100644 index 0000000..fceb1ec --- /dev/null +++ b/tk8.6/doc/radiobutton.n @@ -0,0 +1,265 @@ +'\" +'\" 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 new file mode 100644 index 0000000..c8feb71 --- /dev/null +++ b/tk8.6/doc/raise.n @@ -0,0 +1,57 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH 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 new file mode 100644 index 0000000..6b960ce --- /dev/null +++ b/tk8.6/doc/scale.n @@ -0,0 +1,253 @@ +'\" +'\" 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 new file mode 100644 index 0000000..4d148af --- /dev/null +++ b/tk8.6/doc/scrollbar.n @@ -0,0 +1,360 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ec678fa --- /dev/null +++ b/tk8.6/doc/selection.n @@ -0,0 +1,206 @@ +'\" +'\" 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 new file mode 100644 index 0000000..2a683d5 --- /dev/null +++ b/tk8.6/doc/send.n @@ -0,0 +1,109 @@ +'\" +'\" 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 new file mode 100644 index 0000000..acf06d6 --- /dev/null +++ b/tk8.6/doc/spinbox.n @@ -0,0 +1,602 @@ +'\" +'\" 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 new file mode 100644 index 0000000..2a161e6 --- /dev/null +++ b/tk8.6/doc/text.n @@ -0,0 +1,2285 @@ +'\" +'\" 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 new file mode 100644 index 0000000..1165b67 --- /dev/null +++ b/tk8.6/doc/tk.n @@ -0,0 +1,135 @@ +'\" +'\" 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 new file mode 100644 index 0000000..f29ef2f --- /dev/null +++ b/tk8.6/doc/tk_mac.n @@ -0,0 +1,237 @@ +'\" +'\" 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 new file mode 100644 index 0000000..53cb0d1 --- /dev/null +++ b/tk8.6/doc/tkerror.n @@ -0,0 +1,37 @@ +'\" +'\" 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 new file mode 100644 index 0000000..a80fd54 --- /dev/null +++ b/tk8.6/doc/tkvars.n @@ -0,0 +1,110 @@ +'\" +'\" 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 new file mode 100644 index 0000000..a31aee7 --- /dev/null +++ b/tk8.6/doc/tkwait.n @@ -0,0 +1,52 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.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 new file mode 100644 index 0000000..271d9f1 --- /dev/null +++ b/tk8.6/doc/toplevel.n @@ -0,0 +1,157 @@ +'\" +'\" 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 new file mode 100644 index 0000000..61015c5 --- /dev/null +++ b/tk8.6/doc/ttk_Geometry.3 @@ -0,0 +1,223 @@ +'\" +'\" 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 new file mode 100644 index 0000000..8031b8a --- /dev/null +++ b/tk8.6/doc/ttk_Theme.3 @@ -0,0 +1,32 @@ +'\" +'\" 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 new file mode 100644 index 0000000..cf47a1a --- /dev/null +++ b/tk8.6/doc/ttk_button.n @@ -0,0 +1,109 @@ +'\" +'\" 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 new file mode 100644 index 0000000..a18a886 --- /dev/null +++ b/tk8.6/doc/ttk_checkbutton.n @@ -0,0 +1,105 @@ +'\" +'\" 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 new file mode 100644 index 0000000..9c01409 --- /dev/null +++ b/tk8.6/doc/ttk_combobox.n @@ -0,0 +1,196 @@ +'\" +'\" 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 new file mode 100644 index 0000000..d752670 --- /dev/null +++ b/tk8.6/doc/ttk_entry.n @@ -0,0 +1,511 @@ +'\" +'\" 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 new file mode 100644 index 0000000..8702592 --- /dev/null +++ b/tk8.6/doc/ttk_frame.n @@ -0,0 +1,67 @@ +'\" +'\" 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 new file mode 100644 index 0000000..bc1dd3f --- /dev/null +++ b/tk8.6/doc/ttk_image.n @@ -0,0 +1,98 @@ +'\" +'\" 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 new file mode 100644 index 0000000..bc3cd69 --- /dev/null +++ b/tk8.6/doc/ttk_intro.n @@ -0,0 +1,177 @@ +'\" +'\" 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 new file mode 100644 index 0000000..aae95e6 --- /dev/null +++ b/tk8.6/doc/ttk_label.n @@ -0,0 +1,89 @@ +'\" +'\" 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 new file mode 100644 index 0000000..12f0b89 --- /dev/null +++ b/tk8.6/doc/ttk_labelframe.n @@ -0,0 +1,114 @@ +'\" +'\" 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 new file mode 100644 index 0000000..76d3829 --- /dev/null +++ b/tk8.6/doc/ttk_menubutton.n @@ -0,0 +1,81 @@ +'\" +'\" 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 new file mode 100644 index 0000000..19416b5 --- /dev/null +++ b/tk8.6/doc/ttk_notebook.n @@ -0,0 +1,267 @@ +'\" +'\" 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 new file mode 100644 index 0000000..d6b3ea3 --- /dev/null +++ b/tk8.6/doc/ttk_panedwindow.n @@ -0,0 +1,162 @@ +'\" +'\" 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 new file mode 100644 index 0000000..1687123 --- /dev/null +++ b/tk8.6/doc/ttk_progressbar.n @@ -0,0 +1,122 @@ +'\" +'\" 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 new file mode 100644 index 0000000..1344ae2 --- /dev/null +++ b/tk8.6/doc/ttk_radiobutton.n @@ -0,0 +1,102 @@ +'\" +'\" 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 new file mode 100644 index 0000000..4e16999 --- /dev/null +++ b/tk8.6/doc/ttk_scale.n @@ -0,0 +1,130 @@ +.\" +.\" 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 new file mode 100644 index 0000000..49681a1 --- /dev/null +++ b/tk8.6/doc/ttk_scrollbar.n @@ -0,0 +1,190 @@ +'\" +'\" 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 new file mode 100644 index 0000000..4befb0a --- /dev/null +++ b/tk8.6/doc/ttk_separator.n @@ -0,0 +1,52 @@ +'\" +'\" 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 new file mode 100644 index 0000000..707a17e --- /dev/null +++ b/tk8.6/doc/ttk_sizegrip.n @@ -0,0 +1,82 @@ +'\" +'\" 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 new file mode 100644 index 0000000..325d4d8 --- /dev/null +++ b/tk8.6/doc/ttk_spinbox.n @@ -0,0 +1,128 @@ +'\" +'\" 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 new file mode 100644 index 0000000..985e3cd --- /dev/null +++ b/tk8.6/doc/ttk_style.n @@ -0,0 +1,131 @@ +'\" +'\" 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 new file mode 100644 index 0000000..b81bc62 --- /dev/null +++ b/tk8.6/doc/ttk_treeview.n @@ -0,0 +1,547 @@ +'\" +'\" 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 new file mode 100644 index 0000000..af63c39 --- /dev/null +++ b/tk8.6/doc/ttk_vsapi.n @@ -0,0 +1,113 @@ +'\" +'\" 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 new file mode 100644 index 0000000..ad90e99 --- /dev/null +++ b/tk8.6/doc/ttk_widget.n @@ -0,0 +1,291 @@ +'\" +'\" 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 new file mode 100644 index 0000000..5008448 --- /dev/null +++ b/tk8.6/doc/winfo.n @@ -0,0 +1,354 @@ +'\" +'\" 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 new file mode 100644 index 0000000..93ade0d --- /dev/null +++ b/tk8.6/doc/wish.1 @@ -0,0 +1,218 @@ +'\" +'\" 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 new file mode 100644 index 0000000..e7aedf7 --- /dev/null +++ b/tk8.6/doc/wm.n @@ -0,0 +1,859 @@ +'\" +'\" 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: |