diff options
Diffstat (limited to 'doc')
147 files changed, 8050 insertions, 3231 deletions
diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index 35bf666..01b359b 100644 --- a/doc/3DBorder.3 +++ b/doc/3DBorder.3 @@ -14,7 +14,6 @@ Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectang .nf \fB#include <tk.h>\fR .sp -.VS 8.1 Tk_3DBorder \fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp @@ -23,7 +22,6 @@ Tk_3DBorder .sp Tk_3DBorder \fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp void \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR @@ -46,7 +44,7 @@ void void \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR .sp -CONST char * +const char * \fBTk_NameOf3DBorder(\fIborder\fB)\fR .sp XColor * @@ -55,9 +53,7 @@ XColor * GC * \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR .sp -.VS 8.1 \fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp \fBTk_Free3DBorder(\fIborder\fB)\fR .SH ARGUMENTS @@ -68,14 +64,12 @@ Interpreter to use for error reporting. 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 -.VS 8.1 Pointer to object whose value describes color corresponding to background (flat areas). Illuminated edges will be brighter than this and shadowed edges will be darker than this. .AP char *colorName in Same as \fIobjPtr\fR except value is supplied as a string rather than an object. -.VE .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 @@ -98,26 +92,26 @@ given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means border is outside rectangle. .AP int relief in Indicates 3-D position of interior of object relative to exterior; -should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, -TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT +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 -isn't). +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 TK_RELIEF_GROOVE or -TK_RELIEF_RIDGE then the border is centered on the trajectory. +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. TK_RELIEF_RAISED -means left side should appear higher and TK_RELIEF_SUNKEN means right side +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; -TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. -For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to +\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things. +For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to indicate no difference in height. .AP int leftBevel in Non-zero means this bevel forms the left side of the object; zero means @@ -138,14 +132,13 @@ Non-zero means this bevel forms the top side of the object; zero means it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. -Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. +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. -.VS 8.1 \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 @@ -173,13 +166,12 @@ prevents \fBTk_Get3DBorder\fR from caching the return value, so .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 doesn't actually create the border; it must +\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. -.VE .PP Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be invoked to draw the border. @@ -197,10 +189,10 @@ within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero 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: -TK_RELIEF_RAISED means that the interior of the rectangle should appear raised -relative to the exterior of the rectangle, and -TK_RELIEF_SUNKEN means that the interior should appear depressed. -TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be +\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 @@ -209,7 +201,7 @@ that it first fills the rectangular area with the background color 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 (TK_RELIEF_FLAT means no border should be drawn; all that +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 @@ -228,7 +220,7 @@ it's not clear how useful this is. \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 TK_RELIEF_FLAT; in this case no +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 @@ -244,7 +236,9 @@ 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 ``inside'' of the object, and +position of the border relative to the +.QW inside +of the object, and \fIrelief\fR indicates the relief of the inside of the object relative to the outside. \fBTk_3DVerticalBevel\fR just draws a rectangular region. @@ -282,11 +276,10 @@ as long as \fIborder\fR exists. 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: -TK_3D_FLAT_GC returns the context used for flat surfaces, -TK_3D_LIGHT_GC returns the context for light shadows, -and TK_3D_DARK_GC returns the context for dark shadows. +\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 -.VS 8.1 When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR should be called to release the resources associated with it. @@ -297,7 +290,6 @@ 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. -.VE .SH KEYWORDS 3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect diff --git a/doc/AddOption.3 b/doc/AddOption.3 index 3de6c2f..09a6d9e 100644 --- a/doc/AddOption.3 +++ b/doc/AddOption.3 @@ -16,9 +16,9 @@ void .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. -.AP "CONST char" *name in +.AP "const char" *name in Multi-element name of option. -.AP "CONST char" *value in +.AP "const char" *value in Value of option. .AP int priority in Overall priority level to use for option. @@ -34,24 +34,19 @@ classes separated by asterisks or dots, in the usual X format. 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 TK_MAX_PRIO. Some +is returned. \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR. Some common priority values are: -.TP -20 +.IP 20 Used for default values hard-coded into widgets. -.TP -40 +.IP 40 Used for options specified in application-specific startup files. -.TP -60 +.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. -.TP -80 +.IP 80 Used for options specified interactively after the application starts running. -.PP .SH KEYWORDS class, name, option, add diff --git a/doc/BindTable.3 b/doc/BindTable.3 index 438e586..223c37b 100644 --- a/doc/BindTable.3 +++ b/doc/BindTable.3 @@ -25,7 +25,7 @@ unsigned long int \fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR .sp -CONST char * +const char * \fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR .sp \fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR @@ -43,7 +43,7 @@ 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 +.AP "const char" *eventString in String describing event sequence. .AP char *script in Tcl script to invoke when binding triggers. @@ -117,7 +117,7 @@ message is left in \fIinterp->result\fR. \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 TCL_OK. +\fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR. In some cases it may reset \fIinterp->result\fR to the default empty value. .PP diff --git a/doc/CanvPsY.3 b/doc/CanvPsY.3 index c0aff6d..08b17a4 100644 --- a/doc/CanvPsY.3 +++ b/doc/CanvPsY.3 @@ -83,15 +83,15 @@ transformation. of a bitmap. The Postscript is generated in proper image data format for Postscript, i.e., as data between angle brackets, one bit per pixel. -The Postscript is appended to \fIinterp->result\fR and TCL_OK is returned -unless an error occurs, in which case TCL_ERROR is returned and +The Postscript is appended to \fIinterp->result\fR and \fBTCL_OK\fR is returned +unless an error occurs, in which case \fBTCL_ERROR\fR is returned and \fIinterp->result\fR is overwritten with an error message. .PP \fBTk_CanvasPsColor\fR generates Postscript to set the current color to correspond to its \fIcolorPtr\fR argument, taking into account any color map specified in the \fBpostscript\fR command. It appends the Postscript to \fIinterp->result\fR and returns -TCL_OK unless an error occurs, in which case TCL_ERROR is returned and +\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is returned and \fIinterp->result\fR is overwritten with an error message. .PP \fBTk_CanvasPsFont\fR generates Postscript that sets the current font @@ -99,8 +99,8 @@ to match \fItkFont\fR as closely as possible. \fBTk_CanvasPsFont\fR takes into account any font map specified in the \fBpostscript\fR command, and it does the best it can at mapping X fonts to Postscript fonts. -It appends the Postscript to \fIinterp->result\fR and returns TCL_OK -unless an error occurs, in which case TCL_ERROR is returned and +It appends the Postscript to \fIinterp->result\fR and returns \fBTCL_OK\fR +unless an error occurs, in which case \fBTCL_ERROR\fR is returned and \fIinterp->result\fR is overwritten with an error message. .PP \fBTk_CanvasPsPath\fR generates Postscript to set the current path @@ -112,8 +112,8 @@ current path in stippled fashion. It uses \fIbitmap\fR as the stipple pattern and the current Postscript color; ones in the stipple bitmap are drawn in the current color, and zeroes are not drawn at all. -The Postscript is appended to \fIinterp->result\fR and TCL_OK is -returned, unless an error occurs, in which case TCL_ERROR is returned and +The Postscript is appended to \fIinterp->result\fR and \fBTCL_OK\fR is +returned, unless an error occurs, in which case \fBTCL_ERROR\fR is returned and \fIinterp->result\fR is overwritten with an error message. .SH KEYWORDS diff --git a/doc/CanvTkwin.3 b/doc/CanvTkwin.3 index fb8fff5..14db15e 100644 --- a/doc/CanvTkwin.3 +++ b/doc/CanvTkwin.3 @@ -36,7 +36,7 @@ Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; A token that identifies a canvas widget. .AP Tcl_Interp *interp in/out Interpreter to use for error reporting. -.AP "CONST char" *string in +.AP "const char" *string in Textual description of a canvas coordinate. .AP double *doublePtr out Points to place to store a converted coordinate. @@ -85,9 +85,9 @@ 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 TCL_OK. +and returns \fBTCL_OK\fR. Otherwise it stores an error message in \fIinterp->result\fR and -returns TCL_ERROR. +returns \fBTCL_ERROR\fR. .PP \fBTk_CanvasDrawableCoords\fR is called by type managers during redisplay to compute where to draw things. @@ -138,20 +138,20 @@ 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 won't call these procedures +The code of a canvas type manager will not call these procedures directly, but will use their addresses to create a \fBTk_CustomOption\fR structure for the \fB\-tags\fR option. The code typically looks like this: .CS static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, - Tk_CanvasTagsPrintProc, (ClientData) NULL + Tk_CanvasTagsPrintProc, (ClientData) NULL }; static Tk_ConfigSpec configSpecs[] = { - ... - {TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL, - (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, - ... + ... + {TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL, + (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, + ... }; .CE diff --git a/doc/CanvTxtInfo.3 b/doc/CanvTxtInfo.3 index 7ffa07b..58bf6e1 100644 --- a/doc/CanvTxtInfo.3 +++ b/doc/CanvTxtInfo.3 @@ -33,20 +33,20 @@ text. The structure has the following form: .CS typedef struct Tk_CanvasTextInfo { - Tk_3DBorder \fIselBorder\fR; - int \fIselBorderWidth\fR; - XColor *\fIselFgColorPtr\fR; - Tk_Item *\fIselItemPtr\fR; - int \fIselectFirst\fR; - int \fIselectLast\fR; - Tk_Item *\fIanchorItemPtr\fR; - int \fIselectAnchor\fR; - Tk_3DBorder \fIinsertBorder\fR; - int \fIinsertWidth\fR; - int \fIinsertBorderWidth\fR; - Tk_Item *\fIfocusItemPtr\fR; - int \fIgotFocus\fR; - int \fIcursorOn\fR; + Tk_3DBorder \fIselBorder\fR; + int \fIselBorderWidth\fR; + XColor *\fIselFgColorPtr\fR; + Tk_Item *\fIselItemPtr\fR; + int \fIselectFirst\fR; + int \fIselectLast\fR; + Tk_Item *\fIanchorItemPtr\fR; + int \fIselectAnchor\fR; + Tk_3DBorder \fIinsertBorder\fR; + int \fIinsertWidth\fR; + int \fIinsertBorderWidth\fR; + Tk_Item *\fIfocusItemPtr\fR; + int \fIgotFocus\fR; + int \fIcursorOn\fR; } Tk_CanvasTextInfo; .CE The \fBselBorder\fR field identifies a Tk_3DBorder that should be @@ -56,7 +56,7 @@ 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 doesn't have the +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 diff --git a/doc/Clipboard.3 b/doc/Clipboard.3 index 36c1726..6555290 100644 --- a/doc/Clipboard.3 +++ b/doc/Clipboard.3 @@ -44,8 +44,8 @@ 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 TCL_OK, but if an error occurs it returns -TCL_ERROR and leaves an error message in \fIinterp->result\fR. +It normally returns \fBTCL_OK\fR, but if an error occurs it returns +\fBTCL_ERROR\fR and leaves an error message in \fIinterp->result\fR. \fBTk_ClipboardClear\fR must be called before a sequence of \fBTk_ClipboardAppend\fR calls can be issued. .PP @@ -54,13 +54,13 @@ 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 TCL_OK if the buffer is +\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 TCL_ERROR and leaves an error message in +\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error message in \fIinterp->result\fR. .PP In order to guarantee atomicity, no event handling should occur diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 index c7a8c33..6a3e41a 100644 --- a/doc/ConfigWidg.3 +++ b/doc/ConfigWidg.3 @@ -35,7 +35,7 @@ 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 +.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 @@ -43,14 +43,14 @@ 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. -TK_CONFIG_ARGV_ONLY causes the option database and defaults to be -ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to +\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 +.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 @@ -61,12 +61,10 @@ Display containing widget whose record is being freed; needed in order to free up resources. .BE .SH DESCRIPTION -.VS 8.1 .PP -Note: \fBTk_ConfigureWidget\fP should be replaced with the new -\fBTcl_Obj\fP based API \fBTk_SetOptions\fP. The old interface is +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. -.VE .PP \fBTk_ConfigureWidget\fR is called to configure various aspects of a widget, such as colors, fonts, border width, etc. @@ -87,10 +85,10 @@ a table specifying the configuration options that are supported \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 TCL_OK; in this +\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this case it does not modify \fIinterp\fR. If an error -occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will +occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will leave an error message in \fIinterp->result\fR in the standard Tcl fashion. In the event of an error return, some of the fields of \fIwidgRec\fR @@ -104,23 +102,26 @@ expected by the widget. Each of its entries specifies one configuration option and has the following structure: .CS typedef struct { - int \fItype\fR; - char *\fIargvName\fR; - char *\fIdbName\fR; - char *\fIdbClass\fR; - char *\fIdefValue\fR; - int \fIoffset\fR; - int \fIspecFlags\fR; - Tk_CustomOption *\fIcustomPtr\fR; + int \fItype\fR; + char *\fIargvName\fR; + char *\fIdbName\fR; + char *\fIdbClass\fR; + char *\fIdefValue\fR; + int \fIoffset\fR; + int \fIspecFlags\fR; + Tk_CustomOption *\fIcustomPtr\fR; } Tk_ConfigSpec; .CE The \fItype\fR field indicates what type of configuration option this is -(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for +(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 ``\-font'' or ``\-bg'', +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 GROUPED ENTRIES below). The +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 @@ -130,7 +131,7 @@ 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 -TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. +\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 @@ -146,15 +147,15 @@ 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 TK_CONFIG_DONT_SET_DEFAULT bit is set in +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 TK_CONFIG_COLOR or an integer -if \fItype\fR is TK_CONFIG_INT. This value is then stored in the +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 @@ -162,7 +163,8 @@ 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 ``target'' +\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 @@ -177,11 +179,11 @@ 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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 -wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. +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 @@ -194,17 +196,27 @@ 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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 -wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. +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 ``true'', ``yes'', ``on'', or ``1'', +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 ``false'', ``no'', ``off'', or ``0'', or an abbreviation of -one of these values, means false. +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 @@ -213,10 +225,10 @@ 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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 -wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. +was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. .TP \fBTK_CONFIG_CAP_STYLE\fR The value must be @@ -231,10 +243,10 @@ 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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 -wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR. +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 @@ -244,7 +256,7 @@ that the new cursor is not made the active one for \fItkwin\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 CUSTOM OPTION TYPES below for details. +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 @@ -262,15 +274,18 @@ 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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 -wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR. +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. ``0'' -and ``0x'' prefixes may be used to specify octal or hexadecimal +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 @@ -310,29 +325,32 @@ is stored in the target. \fBTK_CONFIG_STRING\fR A copy of the value is made by allocating memory space with -\fBmalloc\fR and copying the value into the dynamically-allocated +\fBTcl_Alloc\fR and copying the value into the dynamically-allocated space. A pointer to the new string is stored in the target. -If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +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 wasn't NULL, then it is -freed by passing it to \fBfree\fR. +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 TK_CONFIG_SYNONYM entry, the entry isn't used +\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 TK_CONFIG_SYNONYM entry; this new entry is used just +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 ``\-background'' and ``\-bg''. +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 TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value +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 @@ -344,8 +362,8 @@ The value must be a window path name. It is translated to a 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 -TK_CONFIG_COLOR) and to generate a 3-D border to draw around the -widget (using TK_CONFIG_BORDER). In cases like this it is possible +\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, @@ -366,11 +384,11 @@ 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 TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0), +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 doesn't match a field in \fIargv\fR then nothing happens: -the corresponding target isn't modified. This feature is useful +\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. @@ -399,7 +417,7 @@ 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 isn't set then empty strings are processed as strings, +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 @@ -415,21 +433,23 @@ once, save the value, and provide it before calling \fBTk_ConfigureWidget\fR. .TP \fBTK_CONFIG_OPTION_SPECIFIED\fR -This bit is set and cleared by \fBTk_ConfigureWidget\fR. Whenever -\fBTk_ConfigureWidget\fR returns, this bit will be set in all the -entries where a value was specified in \fIargv\fR. -It will be zero in all other entries. -This bit provides a way for clients to determine which values -actually changed in a call to \fBTk_ConfigureWidget\fR. +This bit is +.VS 8.5 +deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR +so that callers could detect what entries were specified in +\fIargv\fR, but it was removed because it was inherently +thread-unsafe. Code that wishes to detect what options were specified +should use \fBTk_SetOptions\fR instead. +.VE 8.5 .PP -The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically +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 TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the +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 entry should have the value TK_CONFIG_COLOR_ONLY in +other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in its \fIspecFlags\fR and the appropriate \fIdefValue\fR for color displays. .PP @@ -441,7 +461,7 @@ 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 TK_CONFIG_USER_BIT) in \fIspecFlags\fR +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 @@ -473,7 +493,7 @@ a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, \fBTk_ConfigureInfo\fR generates a string describing all of the configuration options for the window. The string is placed in \fIinterp->result\fR. Under normal circumstances -it returns TCL_OK; if an error occurs then it returns TCL_ERROR +it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR and \fIinterp->result\fR contains an error message. .PP If \fIargvName\fR is NULL, then the value left in @@ -481,7 +501,7 @@ If \fIargvName\fR is NULL, then the value left in 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 TK_CONFIG_SYNONYM, then +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, @@ -503,10 +523,10 @@ the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; instead of returning a list of values, it just returns the current value of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). -The value is returned in \fIinterp->result\fR and TCL_OK is +The value is returned in \fIinterp->result\fR and \fBTCL_OK\fR is normally returned as the procedure's result. If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is -not a valid option name), TCL_ERROR is returned and an error message +not a valid option name), \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp->result\fR. This procedure is typically called to implement \fBcget\fR widget commands. @@ -517,8 +537,8 @@ 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 TK_CONFIG_COLOR), it frees the resource in the widget record. -If the field in the widget record doesn't refer to a resource (e.g. +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 @@ -531,25 +551,25 @@ configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures: .CS typedef struct Tk_CustomOption { - Tk_OptionParseProc *\fIparseProc\fR; - Tk_OptionPrintProc *\fIprintProc\fR; - ClientData \fIclientData\fR; + Tk_OptionParseProc *\fIparseProc\fR; + Tk_OptionPrintProc *\fIprintProc\fR; + ClientData \fIclientData\fR; } Tk_CustomOption; typedef int Tk_OptionParseProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tk_Window \fItkwin\fR, - char *\fIvalue\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR); + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tk_Window \fItkwin\fR, + char *\fIvalue\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR); typedef char *Tk_OptionPrintProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR, - Tcl_FreeProc **\fIfreeProcPtr\fR); + 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 @@ -577,8 +597,8 @@ 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 TCL_OK, but if an error occurs -in translating the string to a value then it should return TCL_ERROR +record. It should normally return \fBTCL_OK\fR, but if an error occurs +in translating the string to a value then it should return \fBTCL_ERROR\fR and store an error message in \fIinterp->result\fR. .PP The \fIprintProc\fR procedure is called @@ -600,7 +620,7 @@ need not do anything with the \fIfreeProcPtr\fR argument. 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 TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point +fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point to the Tk_CustomOption structure. .SH EXAMPLES diff --git a/doc/ConfigWind.3 b/doc/ConfigWind.3 index 7d77902..f19512a 100644 --- a/doc/ConfigWind.3 +++ b/doc/ConfigWind.3 @@ -79,7 +79,6 @@ 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 @@ -125,9 +124,8 @@ To change the stacking order, use the procedure \fBTk_RestackWindow\fR. 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 isn't already in +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 @@ -143,9 +141,7 @@ and \fIpixmap\fR has been passed to the X server. 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/doc/CrtCmHdlr.3 b/doc/CrtCmHdlr.3 index 21bc386..f8c72e5 100644 --- a/doc/CrtCmHdlr.3 +++ b/doc/CrtCmHdlr.3 @@ -25,7 +25,7 @@ Procedure to invoke whenever a ClientMessage X event occurs on any display. .PP \fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked -in the future whenever a ClientMessage X event occurs that isn't handled by +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. @@ -40,14 +40,14 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or type \fBTk_ClientMessageProc\fR: .CS typedef int Tk_ClientMessageProc( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\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 wasn't handled as a \fBWM_PROTOCOL\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 diff --git a/doc/CrtConsoleChan.3 b/doc/CrtConsoleChan.3 new file mode 100644 index 0000000..65feab7 --- /dev/null +++ b/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. +'\" +.so man.macros +.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_InitConsoleChannels \- Install the console channels as standard channels +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_InitConsoleChannels\fR(\fIinterp\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp in +.AP Tcl_Interp *interp in +Interpreter in which the console channels are created. +.BE +.SH DESCRIPTION +.PP +\fBTk_InitConsoleChannels\fR is invoked to create a set of console +channels and install them as the standard channels. All I/O on these +channels will be discarded until \fBTk_CreateConsoleWindow\fR is +called to attach the console to a text widget. +.PP +This function is for use by shell applications based on Tk, like +\fBwish\fR, on platforms which have no standard channels in graphical +mode, like Win32. +.PP +The \fIinterp\fR argument is the interpreter in which to create and +install the console channels. +.PP +\fBNOTE:\fR If this function is used it has to be called before the +first call to \fBTcl_RegisterChannel\fR, directly, or indirectly +through other channel functions. Because otherwise the standard +channels will be already initialized to the system defaults, which will +be nonsensical for the case \fBTk_InitConsoleChannels\fR is for. +.SH "SEE ALSO" +console(n) +.SH KEYWORDS +standard channels, console diff --git a/doc/CrtErrHdlr.3 b/doc/CrtErrHdlr.3 index f123211..a75414e 100644 --- a/doc/CrtErrHdlr.3 +++ b/doc/CrtErrHdlr.3 @@ -24,13 +24,13 @@ Tk_ErrorHandler 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. +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. +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. +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. @@ -41,14 +41,13 @@ Arbitrary one-word value to pass to \fIproc\fR. 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 doesn't exist. See the Xlib documentation for \fBXSetErrorHandler\fR +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: @@ -56,15 +55,15 @@ to handle a particular error, five things must occur: 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 +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 +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 +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 @@ -74,8 +73,8 @@ made when the handler was active (see below for more information). following type: .CS typedef int Tk_ErrorProc( - ClientData \fIclientData\fR, - XErrorEvent *\fIerrEventPtr\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 @@ -96,14 +95,13 @@ 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'es +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 ``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.'' +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 diff --git a/doc/CrtGenHdlr.3 b/doc/CrtGenHdlr.3 index 702ac30..a1bc637 100644 --- a/doc/CrtGenHdlr.3 +++ b/doc/CrtGenHdlr.3 @@ -46,8 +46,8 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or type \fBTk_GenericProc\fR: .CS typedef int Tk_GenericProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\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 diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3 index 65061b3..da083e0 100644 --- a/doc/CrtImgType.3 +++ b/doc/CrtImgType.3 @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures" +.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" .BS .SH NAME Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image @@ -16,7 +16,6 @@ Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind o .sp \fBTk_CreateImageType\fR(\fItypePtr\fR) .sp -.VS ClientData \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) .sp @@ -29,7 +28,7 @@ Must be static: a pointer to this structure is retained by the image code. .AP Tcl_Interp *interp in Interpreter in which image was created. -.AP "CONST char" *name in +.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 @@ -38,7 +37,6 @@ the given image, if it exists. Number of arguments .AP char ***argvPtr in/out Pointer to argument list -.VE .BE .SH DESCRIPTION @@ -61,12 +59,12 @@ the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: .CS typedef struct Tk_ImageType { - char *\fIname\fR; - Tk_ImageCreateProc *\fIcreateProc\fR; - Tk_ImageGetProc *\fIgetProc\fR; - Tk_ImageDisplayProc *\fIdisplayProc\fR; - Tk_ImageFreeProc *\fIfreeProc\fR; - Tk_ImageDeleteProc *\fIdeleteProc\fR; + char *\fIname\fR; + Tk_ImageCreateProc *\fIcreateProc\fR; + Tk_ImageGetProc *\fIgetProc\fR; + Tk_ImageDisplayProc *\fIdisplayProc\fR; + Tk_ImageFreeProc *\fIfreeProc\fR; + Tk_ImageDeleteProc *\fIdeleteProc\fR; } Tk_ImageType; .CE The fields of this structure will be described in later subsections @@ -95,7 +93,7 @@ option specified for a widget or canvas item. The following subsections describe the fields of a Tk_ImageType in more detail. -.SH NAME +.SS NAME .PP \fItypePtr->name\fR provides a name for the image type. Once \fBTk_CreateImageType\fR returns, this name may be used @@ -104,30 +102,20 @@ type. If there already existed an image type by this name then the new image type replaces the old one. -.SH PORTABILITY -.PP -In Tk 8.2 and earlier, the createProc below had a different -signature. If you want to compile an image type using the -old interface which should still run on all Tcl/Tk versions, -compile it with the flag -DUSE_OLD_IMAGE. Further on, if -you are using Stubs, you need to call the function -Tk_InitImageArgs(interp, argc, &argv) first in your -createProc. See below for a description of this function. - -.SH CREATEPROC +.SS CREATEPROC \fItypePtr->createProc\fR provides the address of a procedure for Tk to call whenever \fBimage create\fR is invoked to create an image of the new type. \fItypePtr->createProc\fR must match the following prototype: .CS typedef int Tk_ImageCreateProc( - Tcl_Interp *\fIinterp\fR, - char *\fIname\fR, - int \fIobjc\fR, - Tcl_Obj *CONST \fIobjv\fR[], - Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImaster\fR, - ClientData *\fImasterDataPtr\fR); + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the \fBimage\fR command was invoked, and \fIname\fR is the name for the new image, @@ -148,21 +136,21 @@ 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 \fIinterp->result\fR and return \fBTCL_ERROR\fR; otherwise +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. -.SH GETPROC +.SS GETPROC .PP \fItypePtr->getProc\fR is invoked by Tk whenever a widget calls \fBTk_GetImage\fR to use a particular image. This procedure must match the following prototype: .CS typedef ClientData Tk_ImageGetProc( - Tk_Window \fItkwin\fR, - ClientData \fImasterData\fR); + 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 @@ -175,22 +163,22 @@ 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. -.SH DISPLAYPROC +.SS DISPLAYPROC .PP \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). \fIdisplayProc\fR must match the following prototype: .CS typedef void Tk_ImageDisplayProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR, - Drawable \fIdrawable\fR, - int \fIimageX\fR, - int \fIimageY\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIdrawableX\fR, - int \fIdrawableY\fR); + 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. @@ -208,7 +196,7 @@ 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. -.SH FREEPROC +.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 @@ -219,8 +207,8 @@ canvas item is changed. \fIfreeProc\fR must match the following prototype: .CS typedef void Tk_ImageFreeProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\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 @@ -228,7 +216,7 @@ 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. -.SH DELETEPROC +.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 @@ -238,7 +226,7 @@ each of the image's instances. \fIdeleteProc\fR must match the following prototype: .CS typedef void Tk_ImageDeleteProc( - ClientData \fImasterData\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 @@ -247,7 +235,6 @@ image was created. the image. .SH TK_GETIMAGEMASTERDATA -.VS .PP The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve information about an image. For example, an image manager can use this @@ -260,19 +247,42 @@ 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. -.VE -.SH TK_INITIMAGEARGS -.VS +.SH "LEGACY INTERFACE SUPPORT" +In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR +was incompatibly different, with the following prototype: +.CS +typedef int Tk_ImageCreateProc( + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIargc\fR, + char **\fIargv\fR, + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); +.CE +Legacy programs and libraries dating from those days may still +contain code that defines extended Tk image types using the old +interface. The Tk header file will still support this legacy +interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR +defined. +.PP +When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may +see the routine \fBTk_InitImageArgs\fR in use. This was a migration +tool used to create stub-enabled extensions that could be loaded +into interps containing all versions of Tk 8.1 and later. Tk 8.5 no longer +provides this routine, but uses a macro to convert any attempted +calls of this routine into an empty comment. Any stub-enabled +extension providing an extended image type via the legacy interface +that is compiled against Tk 8.5 headers and linked against the +Tk 8.5 stub library will produce a file that can be loaded only +into interps with Tk 8.5 or later; that is, the normal stub-compatibility +rules. If a developer needs to generate from such code a file +that is loadable into interps with Tk 8.4 or earlier, they must +use Tk 8.4 headers and stub libraries to do so. .PP -The function \fBTk_InitImageArgs\fR converts the arguments of the -\fBcreateProc\fR from objects to strings when necessary. When -not using stubs, not using the old interface, or running -under an older (pre-8.3) Tk version, this function has no -effect. This function makes porting older image handlers to -the new interface a lot easier: After running this function, -the arguments are guaranteed to be in string format, no -matter how Tk deliverd them. +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 diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 index f035bc2..4f06438 100644 --- a/doc/CrtItemType.3 +++ b/doc/CrtItemType.3 @@ -22,7 +22,6 @@ Tk_ItemType * .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 @@ -52,7 +51,6 @@ for an existing type and modify it for the new type. 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 @@ -64,26 +62,26 @@ information such as the name of the type and pointers to the standard procedures implemented by the type manager: .CS typedef struct Tk_ItemType { - char *\fIname\fR; - int \fIitemSize\fR; - Tk_ItemCreateProc *\fIcreateProc\fR; - Tk_ConfigSpec *\fIconfigSpecs\fR; - Tk_ItemConfigureProc *\fIconfigProc\fR; - Tk_ItemCoordProc *\fIcoordProc\fR; - Tk_ItemDeleteProc *\fIdeleteProc\fR; - Tk_ItemDisplayProc *\fIdisplayProc\fR; - int \fIalwaysRedraw\fR; - Tk_ItemPointProc *\fIpointProc\fR; - Tk_ItemAreaProc *\fIareaProc\fR; - Tk_ItemPostscriptProc *\fIpostscriptProc\fR; - Tk_ItemScaleProc *\fIscaleProc\fR; - Tk_ItemTranslateProc *\fItranslateProc\fR; - Tk_ItemIndexProc *\fIindexProc\fR; - Tk_ItemCursorProc *\fIicursorProc\fR; - Tk_ItemSelectionProc *\fIselectionProc\fR; - Tk_ItemInsertProc *\fIinsertProc\fR; - Tk_ItemDCharsProc *\fIdCharsProc\fR; - Tk_ItemType *\fInextPtr\fR; + char *\fIname\fR; + int \fIitemSize\fR; + Tk_ItemCreateProc *\fIcreateProc\fR; + Tk_ConfigSpec *\fIconfigSpecs\fR; + Tk_ItemConfigureProc *\fIconfigProc\fR; + Tk_ItemCoordProc *\fIcoordProc\fR; + Tk_ItemDeleteProc *\fIdeleteProc\fR; + Tk_ItemDisplayProc *\fIdisplayProc\fR; + int \fIalwaysRedraw\fR; + Tk_ItemPointProc *\fIpointProc\fR; + Tk_ItemAreaProc *\fIareaProc\fR; + Tk_ItemPostscriptProc *\fIpostscriptProc\fR; + Tk_ItemScaleProc *\fIscaleProc\fR; + Tk_ItemTranslateProc *\fItranslateProc\fR; + Tk_ItemIndexProc *\fIindexProc\fR; + Tk_ItemCursorProc *\fIicursorProc\fR; + Tk_ItemSelectionProc *\fIselectionProc\fR; + Tk_ItemInsertProc *\fIinsertProc\fR; + Tk_ItemDCharsProc *\fIdCharsProc\fR; + Tk_ItemType *\fInextPtr\fR; } Tk_ItemType; .CE .PP @@ -111,13 +109,13 @@ the first field. For example, the item record for bitmap items is defined as follows: .CS typedef struct BitmapItem { - Tk_Item \fIheader\fR; - double \fIx\fR, \fIy\fR; - Tk_Anchor \fIanchor\fR; - Pixmap \fIbitmap\fR; - XColor *\fIfgColor\fR; - XColor *\fIbgColor\fR; - GC \fIgc\fR; + Tk_Item \fIheader\fR; + double \fIx\fR, \fIy\fR; + Tk_Anchor \fIanchor\fR; + Pixmap \fIbitmap\fR; + XColor *\fIfgColor\fR; + XColor *\fIbgColor\fR; + GC \fIgc\fR; } BitmapItem; .CE The \fIheader\fR substructure contains information used by Tk @@ -152,8 +150,7 @@ 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 NAME +.SS NAME .PP This section and the ones that follow describe each of the fields in a Tk_ItemType structure in detail. @@ -163,8 +160,7 @@ 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. - -.SH ITEMSIZE +.SS ITEMSIZE \fItypePtr->itemSize\fR gives the size in bytes of item records of this type, including the Tk_Item header. Tk uses this size to allocate memory space for items of the type. @@ -172,19 +168,18 @@ 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. - -.SH CREATEPROC +.SS CREATEPROC .PP \fItypePtr->createProc\fR points to a procedure for Tk to call whenever a new item of this type is created. \fItypePtr->createProc\fR must match the following prototype: .CS typedef int Tk_ItemCreateProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj* CONST \fIobjv\fR); + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj* const \fIobjv\fR[]); .CE The \fIinterp\fR argument is the interpreter in which the canvas's \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a @@ -212,8 +207,7 @@ 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). - -.SH CONFIGSPECS +.SS CONFIGSPECS .PP Each type manager must provide a standard table describing its configuration options, in a form suitable for use with @@ -227,8 +221,7 @@ 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. - -.SH CONFIGPROC +.SS CONFIGPROC .PP \fItypePtr->configProc\fR is called by Tk whenever the \fBitemconfigure\fR widget command is invoked to change the @@ -236,12 +229,12 @@ configuration options for a canvas item. This procedure must match the following prototype: .CS typedef int Tk_ItemConfigureProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj* CONST \fIobjv\fR, - int \fIflags\fR); + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj* const \fIobjv\fR[], + int \fIflags\fR); .CE The \fIinterp\fR objument identifies the interpreter in which the widget command was invoked, \fIcanvas\fR is a handle for the canvas @@ -255,7 +248,7 @@ example, if the following command is invoked: 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 TK_CONFIG_ARGV_ONLY when Tk +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 @@ -263,19 +256,18 @@ procedure will usually invoke \fIconfigProc\fR with different flag values. leaves an error message in \fIinterp->result\fR if an error occurs. It must update the item's bounding box to reflect the new configuration options. - -.SH COORDPROC +.SS COORDPROC .PP \fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR widget command for an item. It must match the following prototype: .CS typedef int Tk_ItemCoordProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj* CONST \fIobjv\fR); + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj* const \fIobjv\fR[]); .CE The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR all have the standard meanings, and \fIobjc\fR and \fIobjv\fR @@ -293,17 +285,16 @@ box in the item's header), and return a standard Tcl completion code. If an error occurs, \fIcoordProc\fR must leave an error message in \fIinterp->result\fR. - -.SH DELETEPROC +.SS DELETEPROC .PP \fItypePtr->deleteProc\fR is invoked by Tk to delete an item and free any resources allocated to it. It must match the following prototype: .CS typedef void Tk_ItemDeleteProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Display *\fIdisplay\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR); .CE The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual interpretations, and \fIdisplay\fR identifies the X display containing @@ -312,22 +303,21 @@ the canvas. 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. - -.SH "DISPLAYPROC AND ALWAYSREDRAW" +.SS "DISPLAYPROC AND ALWAYSREDRAW" .PP \fItypePtr->displayProc\fR is invoked by Tk to redraw an item on the screen. It must match the following prototype: .CS typedef void Tk_ItemDisplayProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Display *\fIdisplay\fR, - Drawable \fIdst\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR, + Drawable \fIdst\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR); .CE The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIdisplay\fR identifies the display containing the canvas, and @@ -352,12 +342,11 @@ Normally an item's \fIdisplayProc\fR is only invoked if the item overlaps the area being displayed. However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then \fIdisplayProc\fR is invoked during every redisplay operation, -even if the item doesn't overlap the area of redisplay. +even if the item does not overlap the area of redisplay. \fIalwaysRedraw\fR should normally be set to 0; it is only set to 1 in special cases such as window items that need to be unmapped when they are off-screen. - -.SH POINTPROC +.SS POINTPROC .PP \fItypePtr->pointProc\fR is invoked by Tk to find out how close a given point is to a canvas item. @@ -366,9 +355,9 @@ under the mouse or finding the closest item to a given point. The procedure must match the following prototype: .CS typedef double Tk_ItemPointProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIpointPtr\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIpointPtr\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIpointPtr\fR points to an array of two numbers giving @@ -376,17 +365,16 @@ 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. - -.SH AREAPROC +.SS AREAPROC .PP \fItypePtr->areaProc\fR is invoked by Tk to find out the relationship between an item and a rectangular area. It must match the following prototype: .CS typedef int Tk_ItemAreaProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIrectPtr\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIrectPtr\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIrectPtr\fR points to an array of four real numbers; @@ -396,30 +384,29 @@ 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. - -.SH POSTSCRIPTPROC +.SS POSTSCRIPTPROC .PP \fItypePtr->postscriptProc\fR is invoked by Tk to generate -Postcript for an item during the \fBpostscript\fR widget command. +Postscript for an item during the \fBpostscript\fR widget command. If the type manager is not capable of generating Postscript then \fItypePtr->postscriptProc\fR should be NULL. The procedure must match the following prototype: .CS typedef int Tk_ItemPostscriptProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIprepass\fR); + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIprepass\fR); .CE The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have standard meanings; \fIprepass\fR will be described below. If \fIpostscriptProc\fR completes successfully, it should append Postscript for the item to the information in \fIinterp->result\fR (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) -and return TCL_OK. +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 TCL_ERROR. +return \fBTCL_ERROR\fR. .PP Tk provides a collection of utility procedures to simplify \fIpostscriptProc\fR. @@ -447,19 +434,18 @@ 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. - -.SH SCALEPROC +.SS SCALEPROC \fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item during the \fBscale\fR widget command. The procedure must match the following prototype: .CS typedef void Tk_ItemScaleProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIoriginX\fR, - double \fIoriginY\fR, - double \fIscaleX\fR, - double \fIscaleY\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIoriginX\fR, + double \fIoriginY\fR, + double \fIscaleX\fR, + double \fIscaleY\fR); .CE The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which @@ -467,32 +453,30 @@ 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'\fR and \fIy'\fR, where +coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .CS -\fIx' = originX + scaleX*(x-originX) -y' = originY + scaleY*(y-originY)\fR +\fIx\(fm = originX + scaleX*(x-originX) +y\(fm = originY + scaleY*(y-originY)\fR .CE \fIscaleProc\fR must also update the bounding box in the item's header. - -.SH TRANSLATEPROC +.SS TRANSLATEPROC \fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item during the \fBmove\fR widget command. The procedure must match the following prototype: .CS typedef void Tk_ItemTranslateProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIdeltaX\fR, - double \fIdeltaY\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIdeltaX\fR, + double \fIdeltaY\fR); .CE The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be added to each x and y coordinate within the item. The type manager should adjust the item's coordinates and update the bounding box in the item's header. - -.SH INDEXPROC +.SS INDEXPROC \fItypePtr->indexProc\fR is invoked by Tk to translate a string index specification into a numerical index, for example during the \fBindex\fR widget command. @@ -502,11 +486,11 @@ item types. The procedure must match the following prototype: .CS typedef int Tk_ItemIndexProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - char \fIindexString\fR, - int *\fIindexPtr\fR); + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + char \fIindexString\fR, + int *\fIindexPtr\fR); .CE The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have the usual meaning. @@ -518,21 +502,20 @@ are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, \fBend\fR, etc.). \fIindexProc\fR should return a Tcl completion code and set \fIinterp->result\fR in the event of an error. - -.SH ICURSORPROC +.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 don't support an insertion cursor. +that do not support an insertion cursor. The procedure must match the following prototype: .CS typedef void Tk_ItemCursorProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and \fIindex\fR is an index into the item's text, as returned by a @@ -541,8 +524,7 @@ 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. - -.SH SELECTIONPROC +.SS SELECTIONPROC .PP \fItypePtr->selectionProc\fR is invoked by Tk during selection retrievals; it must return part or all of the selected text in @@ -553,11 +535,11 @@ item types. The procedure must match the following prototype: .CS typedef int Tk_ItemSelectionProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIoffset\fR is an offset in bytes into the selection where 0 refers @@ -569,10 +551,9 @@ 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 aren't \fIoffset+maxBytes\fR bytes +be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes in the selection. - -.SH INSERTPROC +.SS INSERTPROC .PP \fItypePtr->insertProc\fR is invoked by Tk during the \fBinsert\fR widget command to insert new text into a @@ -583,10 +564,10 @@ item types. The procedure must match the following prototype: .CS typedef void Tk_ItemInsertProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR, - char *\fIstring\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR, + char *\fIstring\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIindex\fR is an index into the item's text, as returned by a @@ -595,8 +576,7 @@ contains new text to insert just before the character given by \fIindex\fR. The type manager should insert the text and recompute the bounding box in the item's header. - -.SH DCHARSPROC +.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. @@ -606,19 +586,17 @@ item types. The procedure must match the following prototype: .CS typedef void Tk_ItemDCharsProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIfirst\fR, - int \fIlast\fR); + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIfirst\fR, + int \fIlast\fR); .CE \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIfirst\fR and \fIlast\fR give the indices of the first and last bytes to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR. The type manager should delete the specified characters and update the bounding box in the item's header. - .SH "SEE ALSO" Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin - .SH KEYWORDS canvas, focus, item type, selection, type manager diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 index fa50d86..0575d40 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -10,7 +10,7 @@ '\" Australian National University. '\" .so man.macros -.TH Tk_CreatePhotoImageFormat 3 8.3 Tk "Tk Library Procedures" +.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" .BS .SH NAME Tk_CreatePhotoImageFormat \- define new file format for photo images @@ -46,13 +46,13 @@ handler to deal with files and strings in this format. The Tk_PhotoImageFormat structure contains the following fields: .CS typedef struct Tk_PhotoImageFormat { - char *\fIname\fR; - Tk_ImageFileMatchProc *\fIfileMatchProc\fR; - Tk_ImageStringMatchProc *\fIstringMatchProc\fR; - Tk_ImageFileReadProc *\fIfileReadProc\fR; - Tk_ImageStringReadProc *\fIstringReadProc\fR; - Tk_ImageFileWriteProc *\fIfileWriteProc\fR; - Tk_ImageStringWriteProc *\fIstringWriteProc\fR; + char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; } Tk_PhotoImageFormat; .CE .PP @@ -66,14 +66,6 @@ structure should be set to NULL. The handler must provide the procedure, and the \fIstringMatchProc\fR procedure if it provides the \fIstringReadProc\fR procedure. -.SH PORTABILITY -.PP -In Tk 8.2 and earlier, a different interface was used. Tk 8.3 will -still support the old format handlers if the format name is in upper -case. If you still want to compile old format handlers with Tk8.3, -use the flag -DUSE_OLD_IMAGE. This will restore all function prototypes -to match the pre-8.3 situation. - .SH NAME .PP \fIformatPtr->name\fR provides a name for the image type. @@ -81,9 +73,10 @@ 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. For new format handlers, the name should -be in lower case. Pre-8.3 format handlers are assumed to be in -upper case. +the \fB\-format\fR option. The first character of \fIformatPtr->name\fR +must not be an uppercase character from the ASCII character set +(that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used +only for legacy interface support (see below). .SH FILEMATCHPROC \fIformatPtr->fileMatchProc\fR provides the address of a procedure for @@ -92,12 +85,12 @@ suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS typedef int Tk_ImageFileMatchProc( - Tcl_Channel \fIchan\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + 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 @@ -115,11 +108,11 @@ suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS typedef int Tk_ImageStringMatchProc( - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + 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 @@ -136,14 +129,14 @@ Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS typedef int Tk_ImageFileReadProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Channel \fIchan\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + 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. @@ -165,13 +158,13 @@ Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int Tk_ImageStringReadProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + 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. @@ -193,10 +186,10 @@ Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS typedef int Tk_ImageFileWriteProc( - Tcl_Interp *\fIinterp\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); + 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. @@ -218,9 +211,9 @@ Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int Tk_ImageStringWriteProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); + 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. @@ -236,6 +229,44 @@ after the name of the format. If appropriate, the characters to specify further details about the image file. The return value is a standard Tcl return value. +.SH "LEGACY INTERFACE SUPPORT" +In Tk 8.2 and earlier, the definition of all the function pointer +types stored in fields of a \fBTk_PhotoImageFormat\fR struct were +incompatibly different. Legacy programs and libraries dating from +those days may still contain code that defines extended Tk photo image +formats using the old interface. The Tk header file will still support +this legacy interface if the code is compiled with the +macro \fBUSE_OLD_IMAGE\fR defined. Alternatively, the legacy interfaces +are used if the first character of \fIformatPtr->name\fR is an +uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts +are used to forgive the type mismatch. For example, +.CS +static Tk_PhotoImageFormat myFormat = { + "MyFormat", + (Tk_ImageFileMatchProc *) FileMatch, + NULL, + (Tk_ImageFileReadProc *) FileRead, + NULL, + NULL, + NULL +}; +.CE +would define a minimal \fBTk_PhotoImageFormat\fR that operates provide +only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR +are written according to the legacy interfaces of Tk 8.2 or earlier. +.PP +Any stub-enabled extension providing an extended photo image format +via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro +that is compiled against Tk 8.5 headers and linked against the +Tk 8.5 stub library will produce a file that can be loaded only +into interps with Tk 8.5 or later; that is, the normal stub-compatibility +rules. If a developer needs to generate from such code a file +that is loadable into interps with Tk 8.4 or earlier, they must +use Tk 8.4 headers and stub libraries to do so. +.PP +Any new code written today should not make use of the legacy +interfaces. Expect their support to go away in Tk 9. + .SH "SEE ALSO" Tk_FindPhoto, Tk_PhotoPutBlock diff --git a/doc/CrtSelHdlr.3 b/doc/CrtSelHdlr.3 index 5a5c48b..c081c71 100644 --- a/doc/CrtSelHdlr.3 +++ b/doc/CrtSelHdlr.3 @@ -35,11 +35,10 @@ and the selection contents are requested in the format given by .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP Atom format in -If the selection requestor isn't in this process, \fIformat\fR determines +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 @@ -56,10 +55,10 @@ the selection. The most common form is STRING. type \fBTk_SelectionProc\fR: .CS typedef int Tk_SelectionProc( - ClientData \fIclientData\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\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. @@ -75,7 +74,7 @@ at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters 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. +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 diff --git a/doc/CrtWindow.3 b/doc/CrtWindow.3 index a156581..8e36cb0 100644 --- a/doc/CrtWindow.3 +++ b/doc/CrtWindow.3 @@ -30,41 +30,39 @@ Tk_Window .AS Tcl_Interp *topLevScreen .AP Tcl_Interp *interp out Tcl interpreter to use for error reporting. If no error occurs, -then \fI*interp\fR isn't modified. +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 +.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 +.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 (``'') then new -window is created as top-level window of \fIparent\fR's screen. +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 +.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, -.VS \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 couldn't be created successfully, then NULL +library. If the window could not be created successfully, then NULL is returned and \fIinterp->result\fR is modified to hold an error message. .PP Tk supports two different kinds of windows: internal windows and top-level windows. -.VE 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 @@ -104,7 +102,7 @@ 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 don't +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. @@ -117,7 +115,7 @@ 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 can't be, since X hasn't been +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 @@ -139,7 +137,7 @@ 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 hasn't been mapped, so no X window exists, it is +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. diff --git a/doc/DeleteImg.3 b/doc/DeleteImg.3 index 91bf63f..2b9288e 100644 --- a/doc/DeleteImg.3 +++ b/doc/DeleteImg.3 @@ -18,7 +18,7 @@ Tk_DeleteImage \- Destroy an image. .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter for which the image was created. -.AP "CONST char" *name in +.AP "const char" *name in Name of the image. .BE diff --git a/doc/EventHndlr.3 b/doc/EventHndlr.3 index 3d8bb12..2ea04ae 100644 --- a/doc/EventHndlr.3 +++ b/doc/EventHndlr.3 @@ -46,8 +46,8 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or type \fBTk_EventProc\fR: .CS typedef void Tk_EventProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\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 diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3 index 7e6ee5a..08e0221 100644 --- a/doc/FindPhoto.3 +++ b/doc/FindPhoto.3 @@ -17,19 +17,19 @@ Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_Pho .SH SYNOPSIS .nf \fB#include <tk.h>\fR -\fB#include <tkPhoto.h>\fR .sp Tk_PhotoHandle -.VS 8.0 br \fBTk_FindPhoto\fR(\fIinterp, imageName\fR) -.VE .sp -void -\fBTk_PhotoPutBlock\fR(\fIhandle, blockPtr, x, y, width, height, compRule\fR) +.VS 8.5 +int +\fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ +compRule\fR) .sp -void -\fBTk_PhotoPutZoomedBlock\fR(\fIhandle, blockPtr, x, y, width, height,\ +int +\fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ zoomX, zoomY, subsampleX, subsampleY, compRule\fR) +.VE 8.5 .sp int \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) @@ -37,21 +37,24 @@ int void \fBTk_PhotoBlank\fR(\fIhandle\fR) .sp -void -\fBTk_PhotoExpand\fR(\fIhandle, width, height\fR) +.VS 8.5 +int +\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) +.VE 8.5 .sp void \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) .sp -void -\fBTk_PhotoSetSize\fR(\fIhandle, width, height\fR) +.VS 8.5 +int +\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) +.VE 8.5 .SH ARGUMENTS .AS Tk_PhotoImageBlock window_path .AP Tcl_Interp *interp in -.VS -Interpreter in which image was created. -.VE -.AP "CONST char" *imageName 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. @@ -67,16 +70,14 @@ to be placed within the image. 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). -.VS 8.4 .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 -TK_PHOTO_COMPOSITE_OVERLAY (which puts the block of data over the top +\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 TK_PHOTO_COMPOSITE_SET (which +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.) -.VE 8.4 .AP int height in Specifies the height of the image area to be affected (for \fBTk_PhotoPutBlock\fR) or the desired image height (for @@ -122,12 +123,12 @@ The \fIblock\fR parameter is a pointer to a \fBTk_PhotoImageBlock\fR structure, defined as follows: .CS typedef struct { - unsigned char *\fIpixelPtr\fR; - int \fIwidth\fR; - int \fIheight\fR; - int \fIpitch\fR; - int \fIpixelSize\fR; - int \fIoffset[4]\fR; + unsigned char *\fIpixelPtr\fR; + int \fIwidth\fR; + int \fIheight\fR; + int \fIpitch\fR; + int \fIpixelSize\fR; + int \fIoffset[4]\fR; } Tk_PhotoImageBlock; .CE The \fIpixelPtr\fR field points to the first pixel, that is, the @@ -143,16 +144,14 @@ to the addresses of the bytes containing the red, green, blue and alpha have other values, e.g., for images that are stored as separate red, green and blue planes. .PP -.VS 8.4 The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a compositing rule that says what to do with transparent pixels. The -value TK_PHOTO_COMPOSITE_OVERLAY says that the previous contents of +value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of the photo image should show through, and the value -TK_PHOTO_COMPOSITE_SET says that the previous contents of the photo +\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 TK_PHOTO_COMPOSITE_OVERLAY as a compositing rule. -.VE 8.4 +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 @@ -162,6 +161,13 @@ given are replicated (in a tiled fashion) to fill the specified area. These rules operate independently in the horizontal and vertical directions. .PP +.VS 8.5 +\fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.VE 8.5 +.PP \fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that the image can be reduced or enlarged for display. The \fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the @@ -201,6 +207,13 @@ are being supplied in many small blocks, it is more efficient to use allowing the image to expand in many small increments as image blocks are supplied. .PP +.VS 8.5 +\fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.VE 8.5 +.PP \fBTk_PhotoSetSize\fR specifies the size of the image, as if the user had specified the given \fIwidth\fR and \fIheight\fR values to the \fB\-width\fR and \fB\-height\fR configuration options. A value of @@ -209,11 +222,17 @@ or height, but allows the width or height to be changed by subsequent calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or \fBTk_PhotoExpand\fR. .PP +.VS 8.5 +\fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot +allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is +returned instead and, if the \fIinterp\fR argument is non-NULL, an +error message is placed in the interpreter's result. +.VE 8.5 +.PP \fBTk_PhotoGetSize\fR returns the dimensions of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR. .SH PORTABILITY -.VS 8.4 .PP In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and \fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to @@ -221,7 +240,16 @@ 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. -.VE 8.4 +.PP +.VS 8.5 +In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an +\fIinterp\fR argument or return any result code. If insufficient +memory was available for an image, Tk would panic. This behaviour is +still supported if you compile your extension with the additional flag +-DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against +older versions of Tk will continue to work. +.VE 8.5 .SH CREDITS .PP diff --git a/doc/FontId.3 b/doc/FontId.3 index bed71c3..60905a7 100644 --- a/doc/FontId.3 +++ b/doc/FontId.3 @@ -17,12 +17,10 @@ fonts Font \fBTk_FontId(\fItkfont\fB)\fR .sp -void \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 @@ -30,12 +28,11 @@ 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. +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 @@ -51,10 +48,12 @@ 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 -Postcript font name that should be used when printing. The return value +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 ``reasonable'' Postscript printer, the +\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, @@ -65,18 +64,18 @@ following screen font families should print correctly: .PP Any other font families may not print correctly because the computed Postscript font name may be incorrect or not exist on the printer. -.VS 8.0 br .SH "DATA STRUCTURES" -The Tk_FontMetrics data structure is used by Tk_GetFontMetrics to return -information about a font and is defined as follows: +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 ascent; - int descent; - int linespace; + int \fIascent\fR; + int \fIdescent\fR; + int \fIlinespace\fR; } Tk_FontMetrics; .CE -The \fIlinespace\fR field is the amount in pixels that the tallest +.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 @@ -88,6 +87,7 @@ 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. -.VE +.SH "SEE ALSO" +font(n), MeasureChar(3) .SH KEYWORDS -font +font, measurement, Postscript diff --git a/doc/FreeXId.3 b/doc/FreeXId.3 index c4ad889..eb1da96 100644 --- a/doc/FreeXId.3 +++ b/doc/FreeXId.3 @@ -23,7 +23,6 @@ Display for which \fIid\fR was allocated. 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 @@ -42,9 +41,8 @@ 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 don't call \fBTk_FreeXId\fR then the resource identifier will +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/doc/GetAnchor.3 b/doc/GetAnchor.3 index 0b25cb0..8698353 100644 --- a/doc/GetAnchor.3 +++ b/doc/GetAnchor.3 @@ -14,39 +14,42 @@ Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings .nf \fB#include <tk.h>\fR .sp -.VS 8.1 int \fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR -.VE .sp int \fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR .sp -CONST char * +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. -.VS 8.1 br .AP Tcl_Obj *objPtr in/out -String value contains name of anchor point: \fBn\fR, \fBne\fR, -\fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR; +String value contains name of anchor point: +.QW n , +.QW ne , +.QW e , +.QW se , +.QW s , +.QW sw , +.QW w , +.QW nw , +or +.QW center ; internal rep will be modified to cache corresponding Tk_Anchor. -.AP "CONST char" *string in +.AP "const char" *string in Same as \fIobjPtr\fR except description of anchor point is passed as a string. -.VE .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 -.VS 8.1 \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 @@ -59,10 +62,10 @@ 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 doesn't contain a valid anchor position +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 isn't NULL. +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. @@ -72,13 +75,12 @@ 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. -.VE .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 isn't a legal anchor value, then -``unknown anchor position'' is returned. - +If \fIanchor\fR is not a legal anchor value, then +.QW "unknown anchor position" +is returned. .SH KEYWORDS anchor position diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3 index 69e319e..a9bd2c2 100644 --- a/doc/GetBitmap.3 +++ b/doc/GetBitmap.3 @@ -14,7 +14,6 @@ Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_Na .nf \fB#include <tk.h>\fR .sp -.VS 8.1 Pixmap \fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp @@ -23,19 +22,16 @@ Pixmap .sp Pixmap \fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp int \fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR .sp -CONST char * +const char * \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR .sp \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR .sp -.VS 8.1 \fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR .SH ARGUMENTS @@ -45,17 +41,15 @@ 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. -.VS 8.1 br .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 +.AP "const char" *info in Same as \fIobjPtr\fR except description of bitmap is passed as a string and -resulting Pixmap isn't cached. -.VE -.AP "CONST char" *name in +resulting Pixmap is not cached. +.AP "const char" *name in Name for new bitmap to be defined. -.AP "CONST char" *source in +.AP "const char" *source in Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. .AP "int" width in @@ -80,13 +74,11 @@ 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 -.VS 8.1 \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: -.VE .TP 20 \fB@\fIfileName\fR \fIFileName\fR must be the name of a file containing a bitmap @@ -99,21 +91,18 @@ by Tk: .RS .TP 12 \fBerror\fR -The international "don't" symbol: a circle with a diagonal line -across it. -.VS "" br +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. -.VE .TP 12 \fBgray50\fR 50% gray: a checkerboard pattern where every other bit is on. -.VS "" br .TP 12 \fBgray25\fR 25% gray: a checkerboard pattern where one out of every four bits is on. -.VE .TP 12 \fBgray12\fR 12.5% gray: a pattern where one-eighth of the bits are on, consisting of @@ -123,7 +112,8 @@ every fourth pixel in every other row. An hourglass symbol. .TP 12 \fBinfo\fR -A large letter ``i''. +A large letter +.QW i . .TP 12 \fBquesthead\fR The silhouette of a human head, with a question mark in it. @@ -180,18 +170,17 @@ A database document icon. A stop sign. .TP 12 \fBnote\fR -A face with ballon words. +A face with balloon words. .TP 12 \fBcaution\fR A triangle with an exclamation point. .RE .LP -.VS 8.1 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 isn't +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. @@ -204,13 +193,12 @@ return value, so \fBTk_GetBitmap\fR is less efficient than .PP \fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given the window and description used to create the bitmap. -\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; 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. -.VE .PP \fBTk_DefineBitmap\fR associates a name with in-memory bitmap data so that the name can be used in later @@ -219,12 +207,12 @@ 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 TCL_OK; if an error occurs +\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then -TCL_ERROR is returned and an error message is left in +\fBTCL_ERROR\fR is returned and an error message is left in \fIinterp->result\fR. Note: \fBTk_DefineBitmap\fR expects the memory pointed to by -\fIsource\fR to be static: \fBTk_DefineBitmap\fR doesn't make +\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. @@ -237,26 +225,22 @@ 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: -.VS .CS Pixmap bitmap; #include "stip.bitmap" Tk_DefineBitmap(interp, "foo", stip_bits, - stip_width, stip_height); + stip_width, stip_height); \&... bitmap = Tk_GetBitmap(interp, tkwin, "foo"); .CE -.VE 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: -.VS .CS Pixmap bitmap; bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); .CE -.VE 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 @@ -289,7 +273,6 @@ argument in the words pointed to by the \fIwidthPtr\fR and \fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP -.VS 8.1 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 @@ -299,7 +282,6 @@ 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. -.VE .SH BUGS In determining whether an existing bitmap can be used to satisfy diff --git a/doc/GetCapStyl.3 b/doc/GetCapStyl.3 index e9cce7b..5463f12 100644 --- a/doc/GetCapStyl.3 +++ b/doc/GetCapStyl.3 @@ -17,15 +17,18 @@ Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles int \fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR .sp -CONST char * +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 ```butt'', ``projecting'', -or ``round''. +.AP "const char" *string in +String containing name of cap style: one of +.QW butt , +.QW projecting , +or +.QW round . .AP int *capPtr out Pointer to location in which to store X cap style corresponding to \fIstring\fR. @@ -46,7 +49,7 @@ implies. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. -If \fIstring\fR doesn't contain a valid cap style +If \fIstring\fR does not contain a valid cap style or an abbreviation of one of these names, then an error message is stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and \fI*capPtr\fR is unmodified. @@ -54,8 +57,9 @@ stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and \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 isn't a legal cap style, then -``unknown cap style'' is returned. +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/doc/GetClrmap.3 b/doc/GetClrmap.3 index 3c288e9..13ad9b2 100644 --- a/doc/GetClrmap.3 +++ b/doc/GetClrmap.3 @@ -9,7 +9,7 @@ .TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps +Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -17,6 +17,8 @@ Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps 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 @@ -24,16 +26,15 @@ Colormap 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 +.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; must have been returned by a previous +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. @@ -42,16 +43,22 @@ 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 doesn't make sense, or if it refers to a window on +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->result\fR. +\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. +\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 @@ -66,6 +73,5 @@ If \fBTk_GetColormap\fR is called with a \fIstring\fR value of 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 +colormap, visual diff --git a/doc/GetColor.3 b/doc/GetColor.3 index abd1620..25fe16e 100644 --- a/doc/GetColor.3 +++ b/doc/GetColor.3 @@ -13,7 +13,6 @@ Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_Na .SH SYNOPSIS .nf \fB#include <tk.h>\fR -.VS 8.1 .sp XColor * \fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR @@ -23,20 +22,17 @@ XColor * .sp XColor * \fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp XColor * \fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR .sp -CONST char * +const char * \fBTk_NameOfColor(\fIcolorPtr\fB)\fR .sp GC \fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR .sp -.VS 8.1 \fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp \fBTk_FreeColor(\fIcolorPtr\fB)\fR .SH ARGUMENTS @@ -45,14 +41,12 @@ GC Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which color will be used. -.VS 8.1 br .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 *) isn't cached. -.VE +resulting (XColor *) is not cached. .AP XColor *prefPtr in Indicates red, green, and blue intensities of desired color. @@ -66,7 +60,6 @@ same screen and depth as the window for which the color was allocated. .BE .SH DESCRIPTION -.VS 8.1 .PP These procedures manage the colors being used by a Tk application. They allow colors to be shared whenever possible, so that colormap @@ -77,7 +70,6 @@ Given a textual description of a color, \fBTk_AllocColorFromObj\fR locates a pixel value that may be used to render the color in a particular window. The desired color is specified with an object whose string value must have one of the following forms: -.VE .TP 20 \fIcolorname\fR Any of the valid textual names for a color defined in the @@ -99,7 +91,6 @@ 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 -.VS 8.1 \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, @@ -107,7 +98,7 @@ 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 isn't NULL. +\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 @@ -122,13 +113,12 @@ return value, so \fBTk_GetColor\fR is less efficient than .PP \fBTk_GetColorFromObj\fR returns the token for an existing color, given the window and description used to create the color. -\fBTk_GetColorFromObj\fR doesn't actually create the color; 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. -.VE .PP \fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that the desired color is indicated with the \fIred\fR, \fIgreen\fR, and @@ -174,7 +164,6 @@ 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 -.VS 8.1 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 @@ -184,6 +173,5 @@ 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. -.VE .SH KEYWORDS color, intensity, object, pixel value diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 index daca323..953252b 100644 --- a/doc/GetCursor.3 +++ b/doc/GetCursor.3 @@ -14,7 +14,6 @@ Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, .nf \fB#include <tk.h>\fR .sp -.VS 8.1 Tk_Cursor \fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp @@ -23,17 +22,14 @@ Tk_Cursor .sp Tk_Cursor \fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp Tk_Cursor \fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR .sp -CONST char * +const char * \fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR .sp -.VS 8.1 \fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp \fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR .SH ARGUMENTS @@ -42,17 +38,15 @@ CONST char * Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which the cursor will be used. -.VS 8.1 br .AP Tcl_Obj *objPtr in/out Description of cursor; see below for possible values. Internal rep will be modified to cache pointer to corresponding Tk_Cursor. .AP char *name in Same as \fIobjPtr\fR except description of cursor is passed as a string and -resulting Tk_Cursor isn't cached. -.VE -.AP "CONST char" *source in +resulting Tk_Cursor is not cached. +.AP "const char" *source in Data for cursor cursor, in standard cursor format. -.AP "CONST char" *mask in +.AP "const char" *mask in Data for mask cursor, in standard cursor format. .AP "int" width in Width of \fIsource\fR and \fImask\fR. @@ -81,7 +75,6 @@ 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 -.VS 8.1 \fBTk_AllocCursorFromObj\fR takes as argument an object describing a cursor, and returns an opaque Tk identifier for a cursor corresponding to the description. It re-uses an existing cursor if possible and @@ -91,15 +84,15 @@ future calls to procedures such as \fBTk_AllocCursorFromObj\fR and \fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error message will be stored in \fIinterp\fR's result -if \fIinterp\fR isn't NULL. \fIObjPtr\fR must contain a standard Tcl +if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: -.VE .TP \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] \fIName\fR is the name of a cursor in the standard X cursor cursor, i.e., any of the names defined in \fBcursorcursor.h\fR, without the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, -or \fBleft_ptr\fR. Appendix B of ``The X Window System'' +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 @@ -116,7 +109,7 @@ will also accept any of the standard Mac cursors including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and \fBarrow\fR. In addition, Tk will load Macintosh cursor resources of the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the -name of the of the resource. The application and all its open +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. @@ -142,7 +135,6 @@ 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 -.VS 8.1 \fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except that the description of the cursor is specified with a string instead of an object. This prevents \fBTk_GetCursor\fR from caching the @@ -151,13 +143,12 @@ return value, so \fBTk_GetCursor\fR is less efficient than .PP \fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given the window and description used to create the cursor. -\fBTk_GetCursorFromObj\fR doesn't actually create the cursor; the cursor +\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. -.VE .PP \fBTk_GetCursorFromData\fR allows cursors to be created from in-memory descriptions of their source and mask cursors. \fISource\fR @@ -178,8 +169,8 @@ 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")); + 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 @@ -211,7 +202,6 @@ 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 -.VS 8.1 When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR is no longer needed, \fBTk_FreeCursorFromObj\fR or @@ -223,7 +213,6 @@ 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. -.VE .SH BUGS In determining whether an existing cursor can be used to satisfy diff --git a/doc/GetDash.3 b/doc/GetDash.3 index ce25b31..cc54c5a 100644 --- a/doc/GetDash.3 +++ b/doc/GetDash.3 @@ -20,7 +20,7 @@ int .AS Tk_Dash *dashPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. -.AP "CONST char *" string in +.AP "const char *" string in Textual value to be converted. .AP Tk_Dash *dashPtr out Points to place to store the dash pattern @@ -31,31 +31,41 @@ value converted from \fIstring\fR. .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 \fB[.,-_]\fR or spaces. If all -goes well, TCL_OK is returned. If \fIstring\fR doesn't have the -proper syntax then TCL_ERROR is returned, an error message is left +character string containing only +.QW \fB.,\-_\fR +or spaces. If all +goes well, \fBTCL_OK\fR is returned. If \fIstring\fR does not have the +proper syntax then \fBTCL_ERROR\fR is returned, an error message is left in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. .PP The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd -segments are drawn using the "outline" color. The other segments -are drawn transparent. +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 \fB[.,-_ ]\fR. The space can be used +5 possible characters +.QW "\fB.,\-_ \fR" . +The space can be used to enlarge the space between other line elements, and can not -occur as the first posibion in the string. Some examples: - -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} +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 -it shape-conserving. This means that all values in the dash +is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This -assures that "." will always be displayed as a dot and "-" +assures that +.QW . +will always be displayed as a dot and +.QW \- always as a dash regardless of the line width. .PP On systems where only a limited set of dash patterns, the dash diff --git a/doc/GetFont.3 b/doc/GetFont.3 index fbfa0e3..2ca1395 100644 --- a/doc/GetFont.3 +++ b/doc/GetFont.3 @@ -14,7 +14,6 @@ Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFr .nf \fB#include <tk.h>\fR .sp -.VS 8.1 Tk_Font \fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp @@ -23,15 +22,12 @@ Tk_Font .sp Tk_Font \fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp -CONST char * +const char * \fBTk_NameOfFont(\fItkfont\fB)\fR .sp -.VS 8.1 Tk_Font \fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp void \fBTk_FreeFont(\fItkfont\fB)\fR @@ -43,21 +39,18 @@ 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. -.VS 8.1 br .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 isn't cached. -.VE +resulting Tk_Font is not cached. .AP Tk_Font tkfont in Opaque font token. .BE .SH DESCRIPTION .PP -.VS 8.1 \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, @@ -69,7 +62,7 @@ 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 isn't \fBNULL\fR. \fBTk_AllocFontFromObj\fR caches +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. @@ -82,13 +75,12 @@ matching Tk_Font, so \fBTk_GetFont\fR is less efficient than .PP \fBTk_GetFontFromObj\fR returns the token for an existing font, given the window and description used to create the font. -\fBTk_GetFontFromObj\fR doesn't actually create the font; 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. -.VE .PP \fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain a database of all fonts they have allocated. If @@ -105,7 +97,6 @@ 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 -.VS 8.1 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 @@ -114,10 +105,8 @@ with the same information used to create it; for 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. -.VE .SH "SEE ALSO" Tk_FontId(3) - .SH KEYWORDS font diff --git a/doc/GetHINSTANCE.3 b/doc/GetHINSTANCE.3 index 4a13786..07c9ddd 100644 --- a/doc/GetHINSTANCE.3 +++ b/doc/GetHINSTANCE.3 @@ -9,16 +9,14 @@ Tk_GetHINSTANCE \- retrieve the global application instance handle .SH SYNOPSIS .nf -\fB#include <tk.h>\fR +\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/doc/GetImage.3 b/doc/GetImage.3 index aefd9b9..fb6e4c8 100644 --- a/doc/GetImage.3 +++ b/doc/GetImage.3 @@ -28,7 +28,7 @@ Tk_Image Place to leave error message. .AP Tk_Window tkwin in Window in which image will be used. -.AP "CONST char" *name in +.AP "const char" *name in Name of image. .AP Tk_ImageChangedProc *changeProc in Procedure for Tk to invoke whenever image content or size changes. @@ -73,7 +73,7 @@ display an image. 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 doesn't exist then \fBTk_GetImage\fR returns NULL +If the image does not exist then \fBTk_GetImage\fR returns NULL and leaves an error message in \fIinterp->result\fR. .PP When a widget wishes to actually display an image it must @@ -107,13 +107,13 @@ The \fIchangeProc\fR and \fIclientData\fR arguments to in the image; it must match the following prototype: .CS typedef void Tk_ImageChangedProc( - ClientData \fIclientData\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIimageWidth\fR, - int \fIimageHeight\fR); + 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. diff --git a/doc/GetJoinStl.3 b/doc/GetJoinStl.3 index d2e45dd..1af1a06 100644 --- a/doc/GetJoinStl.3 +++ b/doc/GetJoinStl.3 @@ -17,15 +17,18 @@ Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles int \fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR .sp -CONST char * +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 ``bevel'', ``miter'', -or ``round''. +.AP "const char" *string in +String containing name of join style: one of +.QW bevel , +.QW miter , +or +.QW round . .AP int *joinPtr out Pointer to location in which to store X join style corresponding to \fIstring\fR. @@ -45,7 +48,7 @@ implies. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. -If \fIstring\fR doesn't contain a valid join style +If \fIstring\fR does not contain a valid join style or an abbreviation of one of these names, then an error message is stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and \fI*joinPtr\fR is unmodified. @@ -53,8 +56,9 @@ stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and \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 isn't a legal join style, then -``unknown join style'' is returned. +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/doc/GetJustify.3 b/doc/GetJustify.3 index 5f60336..e8535e7 100644 --- a/doc/GetJustify.3 +++ b/doc/GetJustify.3 @@ -14,41 +14,38 @@ Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strin .nf \fB#include <tk.h>\fR .sp -.VS 8.1 int \fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR .sp int \fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR .sp -CONST char * +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. -.VS 8.1 br .AP Tcl_Obj *objPtr in/out -String value contains name of justification style (\fBleft\fR, \fBright\fR, or -\fBcenter\fR). The -internal rep will be modified to cache corresponding justify value. -.AP "CONST char" *string in +String value contains name of justification style, one of +.QW left , +.QW right , +or +.QW center . +The internal rep will be modified to cache corresponding justify value. +.AP "const char" *string in Same as \fIobjPtr\fR except description of justification style is passed as a string. -.VE .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 -.VS 8.1 \fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value corresponding to \fIobjPtr\fR's value. -.VE This value will be one of the following: .TP \fBTK_JUSTIFY_LEFT\fR @@ -63,13 +60,12 @@ the line; as a result, the left edges of lines may be ragged. 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 -.VS 8.1 Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. -If \fIobjPtr\fR doesn't contain a valid justification style +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 isn't NULL. +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. @@ -79,13 +75,13 @@ 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. -.VE .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 isn't a legal justify value, then -``unknown justification style'' is returned. +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/doc/GetOption.3 b/doc/GetOption.3 index de09f9b..79817b7 100644 --- a/doc/GetOption.3 +++ b/doc/GetOption.3 @@ -20,9 +20,9 @@ Tk_Uid .AS Tk_Window *class .AP Tk_Window tkwin in Token for window. -.AP "CONST char" *name in +.AP "const char" *name in Name of desired option. -.AP "CONST char" *class in +.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 diff --git a/doc/GetPixels.3 b/doc/GetPixels.3 index a89c8d1..814c4eb 100644 --- a/doc/GetPixels.3 +++ b/doc/GetPixels.3 @@ -14,18 +14,14 @@ Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate .nf \fB#include <tk.h>\fR .sp -.VS 8.1 int \fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR -.VE .sp int \fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR .sp -.VS 8.1 int \fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR -.VE .sp int \fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR @@ -36,14 +32,12 @@ Interpreter to use for error reporting. .AP Tk_Window tkwin in Window whose screen geometry determines the conversion between absolute units and pixels. -.VS 8.1 br .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 +.AP "const char" *string in Same as \fIobjPtr\fR except specification of distance is passed as a string. -.VE .AP int *intPtr out Pointer to location in which to store converted distance in pixels. .AP double *doublePtr out @@ -53,14 +47,10 @@ Pointer to location in which to store converted distance in millimeters. .SH DESCRIPTION .PP These procedures take as argument a specification of distance on -.VS 8.1 the screen (\fIobjPtr\fR or \fIstring\fR) and compute the -.VE corresponding distance either in integer pixels or floating-point millimeters. In either case, -.VS 8.1 \fIobjPtr\fR or \fIstring\fR -.VE specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: @@ -81,14 +71,13 @@ The number specifies a distance in millimeters on the screen. The number specifies a distance in printer's points (1/72 inch) on the screen. .PP -.VS 8.1 \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 isn't one of the ones above) then +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 isn't NULL. +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. @@ -103,7 +92,6 @@ return value, so \fBTk_GetAnchor\fR is less efficient than \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. -.VE .SH KEYWORDS centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/doc/GetRelief.3 b/doc/GetRelief.3 index 209fb67..b97a615 100644 --- a/doc/GetRelief.3 +++ b/doc/GetRelief.3 @@ -14,52 +14,53 @@ Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings .nf \fB#include <tk.h>\fR .sp -.VS 8.1 int \fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR -.VE .sp int \fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR .sp -CONST char * +const char * \fBTk_NameOfRelief(\fIrelief\fB)\fR .SH ARGUMENTS .AS "Tcl_Interp" *reliefPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. -.VS 8.1 br .AP Tcl_Obj *objPtr in/out -String value contains name of relief (one of \fBflat\fR, \fBgroove\fR, -\fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR); -internal rep will be modified to cache corresponding relief value. +String value contains name of relief, one of +.QW flat , +.QW groove , +.QW raised , +.QW ridge , +.QW solid , +or +.QW sunken ; +the internal rep will be modified to cache corresponding relief value. .AP char *string in Same as \fIobjPtr\fR except description of relief is passed as a string. -.VE .AP int *reliefPtr out Pointer to location in which to store relief value corresponding to \fIobjPtr\fR or \fIname\fR. -.AP "CONST char" *name +.AP "const char" *name Name of the relief. .AP int relief in -Relief value (one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, -TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE). +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 -.VS 8.1 \fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value corresponding to the value of \fIobjPtr\fR. This value will be one of -TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, -TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE. -Under normal circumstances the return value is TCL_OK and +\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 doesn't contain one of the valid relief names -or an abbreviation of one of them, then TCL_ERROR is returned, +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 isn't NULL. +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. @@ -69,13 +70,12 @@ 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. -.VE .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 isn't a legal relief value, then ``unknown relief'' +If \fIrelief\fR is not a legal relief value, then +.QW "unknown relief" is returned. - .SH KEYWORDS name, relief, string diff --git a/doc/GetRootCrd.3 b/doc/GetRootCrd.3 index 48d4d70..7c46b5f 100644 --- a/doc/GetRootCrd.3 +++ b/doc/GetRootCrd.3 @@ -26,7 +26,6 @@ corresponding to left edge of \fItkwin\fR's border. 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 @@ -34,8 +33,7 @@ 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 doesn't have to +\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/doc/GetScroll.3 b/doc/GetScroll.3 index 6ac19ce..43fbab8 100644 --- a/doc/GetScroll.3 +++ b/doc/GetScroll.3 @@ -25,13 +25,13 @@ int Interpreter to use for error reporting. .AP int argc in Number of strings in \fIargv\fR array. -.AP "CONST char" *argv[] in +.AP "const char" *argv[] in Argument strings. These represent the entire widget command, of which the first word is typically the widget name and the second word is typically \fBxview\fR or \fByview\fR. .AP int objc in Number of Tcl_Obj's in \fIobjv\fR array. -.AP "Tcl_Obj *CONST" objv[] in +.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. diff --git a/doc/GetSelect.3 b/doc/GetSelect.3 index a747869..4f8fa8d 100644 --- a/doc/GetSelect.3 +++ b/doc/GetSelect.3 @@ -44,9 +44,9 @@ should have arguments and result that match the type \fBTk_GetSelProc\fR: .CS typedef int Tk_GetSelProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIportion\fR); + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + char *\fIportion\fR); .CE The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR will be copies of the corresponding arguments to @@ -65,13 +65,13 @@ 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 didn't respond -promptly). \fBTk_GetSelection\fR normally returns TCL_OK; if -an error occurs, it returns TCL_ERROR and leaves an error message +fatal error has occurred (e.g. the selection owner did not respond +promptly). \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR; if +an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message in \fIinterp->result\fR. \fIProc\fR should also return either -TCL_OK or TCL_ERROR. If \fIproc\fR encounters an error in dealing with the +\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in dealing with the selection, it should leave an error message in \fIinterp->result\fR -and return TCL_ERROR; this will abort the selection retrieval. +and return \fBTCL_ERROR\fR; this will abort the selection retrieval. .SH KEYWORDS format, get, selection retrieval diff --git a/doc/GetUid.3 b/doc/GetUid.3 index 8865fc7..32d4cbf 100644 --- a/doc/GetUid.3 +++ b/doc/GetUid.3 @@ -29,7 +29,8 @@ 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 ``char *'' +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 diff --git a/doc/GetVRoot.3 b/doc/GetVRoot.3 index 84e3299..d95f3ee 100644 --- a/doc/GetVRoot.3 +++ b/doc/GetVRoot.3 @@ -31,15 +31,16 @@ Points to word in which to store height of virtual root. .SH DESCRIPTION .PP -\fBTkGetVRootGeometry\fR returns geometry information about the virtual -root window associated with \fItkwin\fR. The ``associated'' virtual -root is the one in which \fItkwin\fR's nearest top-level ancestor (or +\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 doesn't use virtual roots) then *\fIxPtr\fR and +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. diff --git a/doc/GetVisual.3 b/doc/GetVisual.3 index 01f87ba..2796660 100644 --- a/doc/GetVisual.3 +++ b/doc/GetVisual.3 @@ -22,7 +22,7 @@ Visual * 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 +.AP "const char" *string in String that identifies the desired visual. See below for valid formats. .AP int *depthPtr out @@ -31,7 +31,6 @@ Depth of returned visual gets stored here. 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 @@ -74,23 +73,28 @@ as \fItkwin\fR. Use the visual whose X identifier is \fInumber\fR. .TP 15 \fBbest\fR ?\fIdepth\fR? -Choose the ``best possible'' visual, using the following rules, in -decreasing order of priority: -(a) a visual that has exactly the desired depth is best, followed +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); -(b) if no \fIdepth\fR is specified, then the deepest available visual +.IP (b) +if no \fIdepth\fR is specified, then the deepest available visual is chosen; -(c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, +.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; -(d) the default visual for the screen is better than any other visual. - +.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 @@ -45,8 +45,8 @@ keyboard events intended for a windows within the same application 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 TCL_OK; if an error occurs -and the grab cannot be set, TCL_ERROR is returned and an error message +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 diff --git a/doc/HandleEvent.3 b/doc/HandleEvent.3 index 7909274..4d24c14 100644 --- a/doc/HandleEvent.3 +++ b/doc/HandleEvent.3 @@ -18,14 +18,15 @@ Tk_HandleEvent \- invoke event handlers for window system events .SH ARGUMENTS .AS XEvent *eventPtr .AP XEvent *eventPtr in -Pointer to X event to dispatch to relevant handler(s). +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. +\fBTcl_DoOneEvent\fR), and in a few other cases within Tk. It makes callbacks to any window event handlers (created by calls to \fBTk_CreateEventHandler\fR) that match \fIeventPtr\fR and then returns. In some cases diff --git a/doc/Inactive.3 b/doc/Inactive.3 new file mode 100644 index 0000000..8f37553 --- /dev/null +++ b/doc/Inactive.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +.so man.macros +.TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +long +\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR +.sp +\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR +.SH ARGUMENTS +.AS Display *display +.AP Display *display in +The display on which the user inactivity timer is to be queried or +reset. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetUserInactiveTime\fR returns the number of milliseconds that +have passed since the last user interaction (usually via keyboard or +mouse) with the respective display. On systems and displays that do not +support querying the user inactiviy time, \fB\-1\fR is returned. +\fBTk_GetUserInactiveTime\fR resets the user inactivity timer of the +given display to zero. On windowing systems that do not support +multiple displays \fIdisplay\fR can be passed as \fBNULL\fR. + +.SH KEYWORDS +idle, inactive diff --git a/doc/InternAtom.3 b/doc/InternAtom.3 index 79b3869..a4ca96c 100644 --- a/doc/InternAtom.3 +++ b/doc/InternAtom.3 @@ -17,13 +17,13 @@ Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms Atom \fBTk_InternAtom(\fItkwin, name\fR) .sp -CONST char * +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 +.AP "const char" *name in String name for which atom is desired. .AP Atom atom in Atom for which corresponding string name is desired. @@ -42,7 +42,8 @@ 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 ``?bad atom?''. +then \fBTk_GetAtomName\fR returns the string +.QW "?bad atom?" . .PP Tk caches the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR diff --git a/doc/MaintGeom.3 b/doc/MaintGeom.3 index d34e22e..c96a646 100644 --- a/doc/MaintGeom.3 +++ b/doc/MaintGeom.3 @@ -62,7 +62,7 @@ is unmapped, the slave is automatically removed by the screen by X. .PP \fBTk_MaintainGeometry\fR deals with these problems for slaves -whose masters aren't their parents, as well as handling the simpler +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 @@ -95,7 +95,6 @@ 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 isn't currently managed, the call has no effect. - +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/doc/ManageGeom.3 b/doc/ManageGeom.3 index 0ceff3a..5dcf688 100644 --- a/doc/ManageGeom.3 +++ b/doc/ManageGeom.3 @@ -19,16 +19,15 @@ Tk_ManageGeometry \- arrange to handle geometry requests for a window .AS Tk_GeometryProc clientData .AP Tk_Window tkwin in Token for window to be managed. -.AP Tk_GeomMgr *mgrPtr in +.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 -shouldn't be managed anymore. +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, @@ -43,9 +42,9 @@ The structure pointed to by \fImgrPtr\fR contains information about the geometry manager: .CS typedef struct { - char *\fIname\fR; - Tk_GeomRequestProc *\fIrequestProc\fR; - Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; + const char *\fIname\fR; + Tk_GeomRequestProc *\fIrequestProc\fR; + Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; } Tk_GeomMgr; .CE The \fIname\fR field is the textual name for the geometry manager, @@ -59,8 +58,8 @@ slave to change its desired geometry. type \fBTk_GeomRequestProc\fR: .CS typedef void Tk_GeomRequestProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\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. @@ -82,8 +81,8 @@ is the same as the window's current geometry manager. arguments and results that match the following prototype: .CS typedef void Tk_GeomLostSlaveProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\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. diff --git a/doc/MapWindow.3 b/doc/MapWindow.3 index bf54dea..25d7ff5 100644 --- a/doc/MapWindow.3 +++ b/doc/MapWindow.3 @@ -29,7 +29,7 @@ Token for window. 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 doesn't already exist. See the +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 @@ -37,7 +37,7 @@ 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 isn't an +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 diff --git a/doc/MeasureChar.3 b/doc/MeasureChar.3 index 059d8e8..c8164f3 100644 --- a/doc/MeasureChar.3 +++ b/doc/MeasureChar.3 @@ -19,10 +19,8 @@ int int \fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR .sp -void \fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR .sp -void \fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR .sp .SH ARGUMENTS @@ -35,24 +33,22 @@ 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. -.VS 8.1 .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. -.VE 8.1 .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: TK_PARTIAL_OK means include a character +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. -TK_WHOLE_WORDS means stop on a word boundary, if possible. If -TK_AT_LEAST_ONE is set, it means return at least one character even if no +\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 -TK_AT_LEAST_ONE is set and TK_WHOLE_WORDS is also set, it means that 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. @@ -69,7 +65,6 @@ 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. -.VS 8.1 .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. @@ -77,23 +72,19 @@ The index of the first byte of the first character to underline in the 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. -.VE 8.1 .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, +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. -.VS 8.1 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. -.VE 8.1 .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. @@ -125,11 +116,12 @@ space in pixels the given \fIstring\fR needs. given \fIdrawable\fR. .PP \fBTk_UnderlineChars\fR underlines the given range of characters in the -given \fIstring\fR. It doesn't draw the characters (which are assumed to +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 +font, measurement diff --git a/doc/MoveToplev.3 b/doc/MoveToplev.3 index 88accaf..24653ab 100644 --- a/doc/MoveToplev.3 +++ b/doc/MoveToplev.3 @@ -44,7 +44,7 @@ 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 doesn't immediately +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. @@ -28,7 +28,7 @@ Tk_Window Token for window. .AP Tcl_Interp *interp out Interpreter to use for error reporting. -.AP "CONST char" *pathName in +.AP "const char" *pathName in Character string containing path name of window. .BE @@ -53,9 +53,17 @@ 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 ``.''; its children have names like -``.a'' and ``.b''; their children have names like ``.a.aa'' and -``.b.bb''; and so on. A window is considered to be be a child of +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 diff --git a/doc/NameOfImg.3 b/doc/NameOfImg.3 index 3e05a14..a1a69a8 100644 --- a/doc/NameOfImg.3 +++ b/doc/NameOfImg.3 @@ -13,7 +13,7 @@ Tk_NameOfImage \- Return name of image. .nf \fB#include <tk.h>\fR .sp -CONST char * +const char * \fBTk_NameOfImage\fR(\fItypePtr\fR) .SH ARGUMENTS .AS Tk_ImageMaster *masterPtr diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 index 07c7551..b7592b7 100644 --- a/doc/ParseArgv.3 +++ b/doc/ParseArgv.3 @@ -26,17 +26,18 @@ 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 +.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 TK_ARGV_END. +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 TK_ARGV_DONT_SKIP_FIRST_ARG, -TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. +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 @@ -52,13 +53,13 @@ the caller. At the end of the call 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 doesn't match \fIargTable\fR and returned to the -caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in +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 TCL_OK. If an error -occurs while parsing the arguments, then TCL_ERROR is returned and +\fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error +occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and \fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR in the standard Tcl fashion. In the event of an error return, \fI*argvPtr\fR will not have been @@ -69,14 +70,17 @@ The \fIargTable\fR array specifies the kinds of arguments that are expected; each of its entries has the following structure: .CS typedef struct { - char *\fIkey\fR; - int \fItype\fR; - char *\fIsrc\fR; - char *\fIdst\fR; - char *\fIhelp\fR; + char *\fIkey\fR; + int \fItype\fR; + char *\fIsrc\fR; + char *\fIdst\fR; + char *\fIhelp\fR; } Tk_ArgvInfo; .CE -The \fIkey\fR field is a string such as ``\-display'' or ``\-bg'' +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 @@ -101,11 +105,13 @@ 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 ``the matching -argument'' in the descriptions below. As part of the processing, +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 ``the following -argument''. The legal values for \fItype\fR, and the processing +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 @@ -120,8 +126,11 @@ 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. ``0'' -and ``0x'' prefixes may be used to specify octal or hexadecimal +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 @@ -130,7 +139,7 @@ and following arguments are discarded from \fIargv\fR. \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 an double-precision +\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. @@ -142,7 +151,7 @@ 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 TK_ARGV_STRING, except that the argument +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 @@ -159,7 +168,7 @@ 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 TK_ARGV_CONST_OPTION, except that the +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 @@ -178,18 +187,18 @@ specifiers of this type are ignored (as if they did not exist). When this kind of option is encountered, \fBTk_ParseArgv\fR uses the \fIhelp\fR fields of \fIargTable\fR to format a message describing all the valid arguments. The message is placed in \fIinterp->result\fR -and \fBTk_ParseArgv\fR returns TCL_ERROR. When this happens, the +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 TK_ARGV_HELP specifier is NULL, then the specifier will +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 -TK_ARGV_HELP entry causes help information to be returned. +\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 doesn't process any +\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 @@ -206,16 +215,16 @@ The procedure should have the following structure: .CS int \fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) - char *\fIdst\fR; - char *\fIkey\fR; - char *\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 aren't any more arguments left in \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 @@ -232,11 +241,11 @@ form: .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; + char *\fIdst\fR; + Tcl_Interp *\fIinterp\fR; + char *\fIkey\fR; + int \fIargc\fR; + char **\fIargv\fR; { } .CE @@ -251,16 +260,15 @@ then return any that are left by compacting them to the beginning of should return a count of how many arguments are left in \fIargv\fR; \fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters an error then it should leave an error message in \fIinterp->result\fR, -in the usual Tcl fashion, and return -1; when this happens -\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR. +in the usual Tcl fashion, and return \-1; when this happens +\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. .RE - .SH "FLAGS" .TP \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR \fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program or command name, and returns it to the caller just as if it -hadn't matched \fIargTable\fR. If this flag is given, then +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 @@ -271,17 +279,16 @@ only exact matches will be acceptable. \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 doesn't +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 TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. +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 @@ -303,32 +310,32 @@ 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} + {"\-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[]; + int argc; + char *argv[]; { - \&... + \&... - if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { - fprintf(stderr, "%s\en", interp->result); - exit(1); - } + if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { + fprintf(stderr, "%s\en", interp->result); + exit(1); + } - /* - * Remainder of the program. - */ + /* + * Remainder of the program. + */ } .CE .PP @@ -337,13 +344,15 @@ Note that default values can be assigned to variables named in 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 +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 ``prog'', \fIargv\fR[1] will be ``infile'', +\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/doc/QWinEvent.3 b/doc/QWinEvent.3 index 8bd3099..5eada22 100644 --- a/doc/QWinEvent.3 +++ b/doc/QWinEvent.3 @@ -24,7 +24,8 @@ 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. +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. diff --git a/doc/RestrictEv.3 b/doc/RestrictEv.3 index b1cc9b8..da8b822 100644 --- a/doc/RestrictEv.3 +++ b/doc/RestrictEv.3 @@ -41,8 +41,8 @@ is a procedure with arguments and result that match the type \fBTk_RestrictProc\fR: .CS typedef Tk_RestrictAction Tk_RestrictProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR argument is a copy of the \fIclientData\fR passed to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with @@ -68,8 +68,9 @@ 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 don't -want to invoke any handlers for any other events). The ``obvious'' +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 diff --git a/doc/SetAppName.3 b/doc/SetAppName.3 index ef9b331..b2df656 100644 --- a/doc/SetAppName.3 +++ b/doc/SetAppName.3 @@ -9,19 +9,19 @@ .TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" .BS .SH NAME -Tk_SetAppName \- Set the name of an application for ``send'' commands +Tk_SetAppName \- Set the name of an application for 'send' commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp -CONST char * +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 +.AP "const char" *name in Name under which to register the application. .BE @@ -35,7 +35,8 @@ 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 -``\fB #2\fR'' to \fIname\fR; if this name is also in use, +.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. @@ -54,7 +55,7 @@ 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 don't normally need to call it explicitly. +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. diff --git a/doc/SetClassProcs.3 b/doc/SetClassProcs.3 index 1ab9a6c..e8820b6 100644 --- a/doc/SetClassProcs.3 +++ b/doc/SetClassProcs.3 @@ -34,10 +34,10 @@ are used as callbacks in different places. 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; + unsigned int \fIsize\fR; + Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; + Tk_ClassCreateProc *\fIcreateProc\fR; + Tk_ClassModalProc *\fImodalProc\fR; } Tk_ClassProcs; .CE The \fIsize\fR field is used to simplify future expansion of the @@ -51,10 +51,10 @@ accordingly. \fIworldChangedProc\fR should have arguments and results that match the type \fBTk_ClassWorldChangedProc\fR: .CS typedef void Tk_ClassWorldChangedProc( - ClientData \fIinstanceData\fR); + ClientData \fIinstanceData\fR); .CE The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR -will be identical to the \fIinstanceData\fR paramter passed to +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 @@ -62,9 +62,9 @@ invoked by \fBTk_MakeWindowExist\fR. \fIcreateProc\fR should have arguments and results that match the type \fBTk_ClassCreateProc\fR: .CS typedef Window Tk_ClassCreateProc( - Tk_Window \fItkwin\fR, - Window \fIparent\fR, - ClientData \fIinstanceData\fR); + 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 @@ -77,8 +77,8 @@ triggered in order to handle a modal loop. \fImodalProc\fR should have arguments and results that match the type \fBTk_ClassModalProc\fR: .CS typedef void Tk_ClassModalProc( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\fR); + 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 diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index 0679432..bd1d8ab 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -39,13 +39,13 @@ Tcl_Obj * int \fBTk_Offset(\fItype, field\fB)\fR .SH ARGUMENTS -.AS Tk_SavedOptions "*CONST objv[]" in/out +.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 +.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. @@ -63,7 +63,7 @@ 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 +.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 @@ -93,10 +93,12 @@ 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 ``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 ``widget -record'' is used to refer to the C-level structure in +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 @@ -250,10 +252,10 @@ one configuration option and has the following fields: .CS typedef struct { Tk_OptionType \fItype\fR; - char *\fIoptionName\fR; - char *\fIdbName\fR; - char *\fIdbClass\fR; - char *\fIdefValue\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; diff --git a/doc/SetVisual.3 b/doc/SetVisual.3 index f5c5890..2082220 100644 --- a/doc/SetVisual.3 +++ b/doc/SetVisual.3 @@ -40,7 +40,7 @@ actually been created in X (e.g. before \fBTk_MapWindow\fR or 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 doesn't make any changes; otherwise +is called then it returns 0 and does not make any changes; otherwise it returns 1 to signify that the operation completed successfully. .PP diff --git a/doc/StrictMotif.3 b/doc/StrictMotif.3 index d44991d..770b335 100644 --- a/doc/StrictMotif.3 +++ b/doc/StrictMotif.3 @@ -28,8 +28,9 @@ 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 ``Motif-like'' is good enough, and extra features -are welcome. +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 diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 index d6fa032..6c4da60 100644 --- a/doc/TextLayout.3 +++ b/doc/TextLayout.3 @@ -53,10 +53,8 @@ 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 -.VS 8.1 terminated and uses \fBTcl_NumUtfChars\fR to determine the length of \fIstring\fR. -.VE .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 @@ -67,15 +65,17 @@ 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 TK_JUSTIFY_LEFT, TK_JUSTIFY_CENTER, or TK_JUSTIFY_RIGHT. If the text -layout only occupies a single line, then \fIjustify\fR is irrelevant. +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. TK_IGNORE_TABS means that tab characters -should not be expanded to the next tab stop. TK_IGNORE_NEWLINES 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. +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 @@ -135,13 +135,11 @@ 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. -.VS 8.1 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. -.VE 8.1 .PP The routines described here are built on top of the programming interface described in the \fBTk_MeasureChars\fR documentation. Tab characters and @@ -216,7 +214,7 @@ 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 didn't hit the \fIlayout\fR +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 @@ -234,8 +232,7 @@ is the responsibility of the caller to take the Postscript array of strings and add some Postscript function operate on the array to render each of the lines. The code that represents the Postscript array of strings is appended to \fIinterp->result\fR. -.PP -.SH DISPLAY MODEL +.SH "DISPLAY MODEL" When measuring a text layout, space characters that occur at the end of a line are ignored. The space characters still exist and the insertion point can be positioned amongst them, but their additional width is ignored when diff --git a/doc/TkInitStubs.3 b/doc/TkInitStubs.3 index 421ed10..3806f95 100644 --- a/doc/TkInitStubs.3 +++ b/doc/TkInitStubs.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1999 Scriptics Corportation +'\" 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. @@ -13,7 +13,7 @@ Tk_InitStubs \- initialize the Tk stubs mechanism .nf \fB#include <tk.h>\fR .sp -CONST char * +const char * \fBTk_InitStubs\fR(\fIinterp, version, exact\fR) .SH ARGUMENTS .AS Tcl_Interp *interp in @@ -48,8 +48,8 @@ Tcl functions. Call \fBTk_InitStubs\fR if the extension before calling any other Tk functions. .IP 2) 5 -Define the USE_TCL_STUBS symbol. Typically, you would include the --DUSE_TCL_STUBS flag when compiling the extension. +Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the +\fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. .IP 3) 5 Link the extension with the Tcl and Tk stubs libraries instead of the standard Tcl and Tk libraries. On Unix platforms, the library @@ -67,7 +67,7 @@ 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 mechansim, or any other +acceptable, does not support the stubs mechanism, or any other error condition occurred. .SH "SEE ALSO" \fBTcl_InitStubs\fR diff --git a/doc/Tk_Init.3 b/doc/Tk_Init.3 index b217aff..65e2d0a 100644 --- a/doc/Tk_Init.3 +++ b/doc/Tk_Init.3 @@ -52,8 +52,9 @@ Continuous ringing of the bell is a nuisance. .TP \fBclipboard\fR A malicious script could replace the contents of the clipboard with -the string \fB"rm -r *"\fR and lead to surprises when the contents of -the clipboard are pasted. +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. diff --git a/doc/Tk_Main.3 b/doc/Tk_Main.3 index c247211..e67cf00 100644 --- a/doc/Tk_Main.3 +++ b/doc/Tk_Main.3 @@ -44,7 +44,8 @@ nothing but invoke \fBTk_Main\fR. .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 ``hook'' +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: diff --git a/doc/WindowId.3 b/doc/WindowId.3 index e588c8e..efa326d 100644 --- a/doc/WindowId.3 +++ b/doc/WindowId.3 @@ -9,7 +9,7 @@ .TH Tk_WindowId 3 "8.4" Tk "Tk Library Procedures" .BS .SH NAME -Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap \- retrieve information from Tk's local data structure +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 @@ -23,7 +23,7 @@ Tk_Window Display * \fBTk_Display\fR(\fItkwin\fR) .sp -CONST char * +const char * \fBTk_DisplayName\fR(\fItkwin\fR) .sp int @@ -94,6 +94,9 @@ int .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 @@ -116,6 +119,9 @@ yet. \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 @@ -144,15 +150,15 @@ 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 is not a free-standing window, but rather is embedded in some +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 isn't mapped. +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 isn't a top-level window. +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 @@ -15,7 +15,6 @@ 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. @@ -23,7 +22,9 @@ If all three arguments are specified, \fBbind\fR will arrange for \fIscript\fR (a Tcl script) to be evaluated whenever the event(s) given by \fIsequence\fR occur in the window(s) identified by \fItag\fR. -If \fIscript\fR is prefixed with a ``+'', then it is appended to +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 @@ -64,17 +65,15 @@ the binding applies to all windows in the application. .PP The \fIsequence\fR argument specifies a sequence of one or more event patterns, with optional white space between the patterns. Each -.VS event pattern may take one of three forms. In the simplest case it is a single -.VE 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 +\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 @@ -82,7 +81,6 @@ 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. -.VS .PP The third form of pattern is used to specify a user-defined, named virtual event. It has the following syntax: @@ -95,26 +93,26 @@ 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. +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. -.VE -.SH "MODIFIERS" +.SS "MODIFIERS" .PP Modifiers consist of any of the following values: .DS .ta 6c -\fBControl\fR \fBMod2, M2\fR -\fBShift\fR \fBMod3, M3\fR -\fBLock\fR \fBMod4, M4\fR -\fBButton1, B1\fR \fBMod5, M5\fR -\fBButton2, B2\fR \fBMeta, M\fR -\fBButton3, B3\fR \fBAlt\fR -\fBButton4, B4\fR \fBDouble\fR -\fBButton5, B5\fR \fBTriple\fR -\fBMod1, M1\fR \fBQuadruple\fR +\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. @@ -126,8 +124,8 @@ 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. +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 @@ -146,11 +144,24 @@ 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 +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. - -.SH "EVENT TYPES" +.PP +The \fBCommand\fR and \fBOption\fR modifiers are equivalents of \fBMod1\fR +resp. \fBMod2\fR, they correspond to Macintosh-specific modifier keys. +.PP +.VS 8.5 +The \fBExtended\fR modifier is, at present, specific to Windows. It +appears on events that are associated with the keys on the +.QW "extended keyboard" . +On a US keyboard, the extended keys include the \fBAlt\fR +and \fBControl\fR keys at the right of the keyboard, the cursor keys +in the cluster to the left of the numeric pad, the \fBNumLock\fR key, +the \fBBreak\fR key, the \fBPrintScreen\fR key, and the \fB/\fR and +\fBEnter\fR keys in the numeric keypad. +.VE 8.5 +.SS "EVENT TYPES" .PP The \fItype\fR field may be any of the standard X event types, with a few extra abbreviations. The \fItype\fR field will also accept a @@ -158,19 +169,18 @@ 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'ButtonPress, Button\0\0\0'u +\w'KeyPress, Key\0\0\0'u -\fBActivate Destroy Map -ButtonPress, Button Enter MapRequest -ButtonRelease Expose Motion -Circulate FocusIn MouseWheel -CirculateRequest FocusOut Property -Colormap Gravity Reparent -Configure KeyPress, Key ResizeRequest -ConfigureRequest KeyRelease Unmap -Create Leave Visibility -Deactivate\fR +.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 -.VS 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 @@ -189,165 +199,163 @@ 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 -Some mice on the Windows platform support a mouse wheel which is used +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. On Windows, the event is -always routed to the window that currently has focus (like \fBKey\fR -events.) On Mac OS X, -the event is routed to the window under the pointer. When the event +application can use to scroll. Like \fBKey\fR events the event is +always routed to the window that currently has focus. When the event is received you can use the \fB%D\fR substitution to get the \fIdelta\fR field for the event, which is a integer value describing how the mouse wheel has moved. The smallest value for which the system will report is defined by the OS. On Windows 95 & 98 machines this value is at least 120 before it is reported. However, higher -resolution devices may be available in the future. On Mac OS X, the value is -not scaled by 120, but a value of 1 corresponds to roughly one text line. -The sign of the value determines which direction your widget should scroll. -Positive values should scroll up and negative values should scroll down. -.VE -.IP "\fBKeyPress\fP, \fBKeyRelease\fP" 5 -The \fBKeyPress\fP and \fBKeyRelease\fP events are generated -whenever a key is pressed or released. \fBKeyPress\fP and \fBKeyRelease\fP +resolution devices may be available in the future. The sign of the +value determines which direction your widget should scroll. Positive +values should scroll up and negative values should scroll down. +.IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5 +The \fBKeyPress\fR and \fBKeyRelease\fR events are generated +whenever a key is pressed or released. \fBKeyPress\fR and \fBKeyRelease\fR events are sent to the window which currently has the keyboard focus. -.IP "\fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP" 5 -The \fBButtonPress\fP and \fBButtonRelease\fP events +.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\fP events are generated whenever the pointer is moved. -\fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP events are +\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\fP, \fBButtonRelease\fP, and \fBMotion\fP +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\fP 5 -A \fBConfigure\fP event is sent to a window whenever its +.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\fP, \fBUnmap\fP" 5 -The \fBMap\fP and \fBUnmap\fP events are generated whenever the mapping +.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\fP state, and are unmapped in the \fBwithdrawn\fP -and \fBiconic\fP states. +\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\fP or \fBgrid\fP). +of a geometry manager (for example \fBpack\fR or \fBgrid\fR). .PP -A window is \fIviewable\fP only if it and all of its ancestors are mapped. -Note that geometry managers typically do not map their children until +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\fP and \fBUnmap\fP +when they become unmapped; hence in Tk \fBMap\fR and \fBUnmap\fR events indicate whether or not a window is viewable. .RE -.IP \fBVisibility\fP 5 -A window is said to be \fIobscured\fP when another window +.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\fP events are generated whenever a window's -obscurity state changes; the \fIstate\fP field (\fB%s\fP) +\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\fP 5 -An \fBExpose\fP event is generated whenever all or part of a +.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\fP events, since Tk handles them internally. -.IP \fBDestroy\fP 5 -A \fBDestroy\fP event is delivered to a window when +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\fP event is delivered -to a widget, it is in a ``half-dead'' state: the widget still exists, -but most operations on it will fail. +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\fP, \fBFocusOut\fP" 5 -The \fBFocusIn\fP and \fBFocusOut\fP events are generated +.IP "\fBFocusIn\fR, \fBFocusOut\fR" 5 +The \fBFocusIn\fR and \fBFocusOut\fR events are generated whenever the keyboard focus changes. -A \fBFocusOut\fP event is sent to the old focus window, -and a \fBFocusIn\fP event is sent to the new one. +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, -``virtual crossing'' focus events are sent to the intermediate -windows in the hierarchy. -Thus a \fBFocusIn\fP event indicates +.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\fP event indicates that 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\fP, -or implicitly by the window manager. +The keyboard focus may be changed explicitly by a call to \fBfocus\fR, +or implicitly by the window manager. .RE -.IP "\fBEnter\fP, \fBLeave\fP" 5 -An \fBEnter\fP event is sent to a window when the pointer -enters that window, and a \fBLeave\fP event is sent when -the pointer leaves it. +.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\fP and \fBLeave\fP +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\fP and \fBLeave\fP -``virtual crossing'' events are sent to intermediate windows -in the hierarchy in the same manner as for \fBFocusIn\fP and -\fBFocusOut\fP events. +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\fP -A \fBProperty\fP event is sent to a window whenever an X property +.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\fP events are not normally delivered to Tk applications as +\fBProperty\fR events are not normally delivered to Tk applications as they are handled by the Tk core. -.IP \fBColormap\fP -A \fBColormap\fP event is generated whenever the colormap +.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\fP option; the window manager +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\fP, \fBCirculateRequest\fP, \fBResizeRequest\fP, \fBConfigureRequest\fP, \fBCreate\fP" 5 +.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\fP on a window; +selected \fBSubstructureRedirectMask\fR on a window; the Tk core does not use this mask.) -.IP "\fBGravity\fP, \fBReparent\fP, \fBCirculate\fP" 5 -The events \fBGravity\fP and \fBReparent\fP +.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\fP event indicates that the window has moved +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\fP protocol request. +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\fP event, and that -Tk does not use \fBXCirculateSubwindows()\fP internally. +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 -.SH "EVENT DETAILS" +.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 +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; @@ -356,17 +364,22 @@ 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. +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. ``a'' is -the keysym for the ASCII character ``a''), plus descriptions for -non-alphanumeric characters (``comma'' is the keysym for the comma -character), plus descriptions for all the non-ASCII keys on the -keyboard (``Shift_L'' is the keysym for the left shift key, and -``F1'' is the keysym for the F1 function key, if it exists). The +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. @@ -374,8 +387,8 @@ 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. +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, @@ -406,49 +419,58 @@ 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\fP if the receiving window is at the +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\fP pending \fBExpose\fP events which have not +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 field from the event. The \fB%d\fR is replaced by +The \fIdetail\fR +.VS 8.5 +or \fIuser_data\fR +.VE 8.5 +field from the event. The \fB%d\fR is replaced by a string identifying the detail. For \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, the string will be one of the following: .RS .DS .ta 6c -\fBNotifyAncestor NotifyNonlinearVirtual -NotifyDetailNone NotifyPointer -NotifyInferior NotifyPointerRoot -NotifyNonlinear NotifyVirtual\fR +\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 Opposite -Below None -BottomIf TopIf\fR +\fBAbove\fR \fBOpposite\fR +\fBBelow\fR \fBNone\fR +\fBBottomIf\fR \fBTopIf\fR .DE +.VS 8.5 +For virtual events, the string will be whatever value is stored in the +\fIuser_data\fR field when the event was created (typically with +\fBevent generate\fR), or the empty string if the field is NULL. +Virtual events corresponding to key sequence presses (see \fBevent +add\fR for details) set the \fIuser_data\fR to NULL. +.VE 8.5 For events other than these, the substituted string is undefined. .RE .IP \fB%f\fR 5 The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only -for \fBEnter\fR and \fBLeave\fR events. \fB1\fP if the receiving -window is the focus window or a descendant of the focus window, -\fB0\fP otherwise. +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 -.VS 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. -.VE .IP \fB%i\fR 5 The \fIwindow\fR field from the event, represented as a hexadecimal integer. Valid for all event types. @@ -458,10 +480,8 @@ 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 -.VS \fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR, \fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events. -.VE .IP \fB%o\fR 5 The \fIoverride_redirect\fR field from the event. Valid only for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. @@ -476,36 +496,34 @@ The \fIstate\fR field from the event. For \fBButtonPress\fR, is substituted. For \fBVisibility\fR, one of the strings \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, and \fBVisibilityFullyObscured\fR is substituted. -For \fBProperty\fP events, substituted with -either the string \fBNewValue\fP (indicating that the property -has been created or modified) or \fBDelete\fP (indicating that +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. +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 -.VS \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and \fBExpose\fR events. -.VE .IP "\fB%x\fR, \fB%y\fR" 5 The \fIx\fR and \fIy\fR fields from the event. -For \fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP, -\fBKeyPress\fP, \fBKeyRelease\fP, and \fBMouseWheel\fP events, -\fB%x\fP and \fB%y\fP indicate the position of the mouse pointer +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\fP and \fBLeave\fP events, the position where the +For \fBEnter\fR and \fBLeave\fR events, the position where the mouse pointer crossed the window, relative to the receiving window. -For \fBConfigure\fP and \fBCreate\fP requests, the \fIx\fP and \fIy\fP +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 doesn't correspond to a UNICODE character +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. @@ -514,18 +532,19 @@ Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. The \fIborder_width\fR field from the event. Valid only for \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events. .IP \fB%D\fR 5 -.VS This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The \fIdelta\fR value represents the rotation units the mouse wheel has been moved. On Windows 95 & 98 systems the smallest value for the delta is 120. Future systems may support higher resolution values for the delta. The sign of the value represents the direction the mouse wheel was scrolled. -.VE .IP \fB%E\fR 5 The \fIsend_event\fR field from the event. Valid for all event types. -\fB0\fP indicates that this is a ``normal'' event, \fB1\fP indicates -that it is a ``synthetic'' event generated by \fBSendEvent\fP. +\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. @@ -535,7 +554,7 @@ 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\fP events. +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. @@ -548,27 +567,19 @@ 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 5 -The \fIx_root\fR field from the event. +.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 -value is the corresponding x-coordinate in the virtual root. +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\fP, except relative to the (virtual) root window. -.IP \fB%Y\fR 5 -The \fIy_root\fR field from the event. -If a virtual-root window manager is being used then the substituted -value is the corresponding 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%y\fP, except relative to the (virtual) root window. +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 it will be surrounded with braces -if it contains spaces, or special characters such as \fB$\fR and +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. @@ -587,7 +598,7 @@ actually executed will be .CE This will cause the \fBinsert\fR to receive the original replacement string (open square bracket) as its first argument. -If the extra backslash hadn't been added, Tcl would not have been +If the extra backslash had not been added, Tcl would not have been able to parse the script correctly. .SH "MULTIPLE MATCHES" .PP @@ -615,36 +626,43 @@ 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: -(a) an event pattern that specifies a specific button or key is more specific -than one that doesn't; -(b) a longer sequence (in terms of number +.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; -(c) if the modifiers specified in one pattern are a subset of the +.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. -(d) a virtual event whose physical pattern matches the sequence is less -specific than the same physical pattern that is not associated with a +.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. -(e) given a sequence that matches two or more virtual events, one +.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 +(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: +be picked at random: .CS -event add <<Paste>> <Control-y> -event add <<Paste>> <Button-2> -event add <<Scroll>> <Button-2> +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 +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. @@ -658,12 +676,12 @@ 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 +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 +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. @@ -686,7 +704,7 @@ The \fBbgerror\fR command will be executed at global level 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> { +\fBbind\fR . <Double\-1> { puts "hi from (%x,%y)" } .CE @@ -695,14 +713,12 @@ 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] +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 diff --git a/doc/bindtags.n b/doc/bindtags.n index 8c6557a..c5cf71b 100644 --- a/doc/bindtags.n +++ b/doc/bindtags.n @@ -55,8 +55,9 @@ For example, the command .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 (``.''), followed by -class bindings, followed by bindings for \fB.b\fR. +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 @@ -94,7 +95,7 @@ proc setupBindtagsForTreeDelivery {widget} { .CE .SH "SEE ALSO" -bind +bind(n) .SH KEYWORDS binding, event, tag diff --git a/doc/button.n b/doc/button.n index 3ca4c4d..4b655a4 100644 --- a/doc/button.n +++ b/doc/button.n @@ -30,7 +30,6 @@ 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 -.VS 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 @@ -41,15 +40,13 @@ 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. -.VE .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 isn't specified, the button's desired height is computed +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. -.VS 8.4 .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 @@ -57,7 +54,6 @@ 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. -.VE 8.4 .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 @@ -72,9 +68,11 @@ In this state the \fBdisabledForeground\fR and .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 isn't specified, the button's desired width is computed +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 @@ -159,10 +157,8 @@ default behavior: .IP [1] A button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the button. -.VS Under Windows, this binding is only active when mouse button 1 has been pressed over the button. -.VE .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 @@ -181,5 +177,26 @@ actions occur: the button is completely non-responsive. The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. +.SH EXAMPLES +This is the classic Tk +.QW "Hello, World!" +demonstration: +.PP +.CS + \fBbutton\fR .b \-text "Hello, World!" \-command exit + pack .b +.CE +.PP +This example demonstrates how to handle button accelerators: +.PP +.CS + \fBbutton\fR .b1 \-text Hello \-underline 0 + \fBbutton\fR .b2 \-text World \-underline 0 + bind . <Key\-h> {.b1 flash; .b1 invoke} + bind . <Key\-w> {.b2 flash; .b2 invoke} + pack .b1 .b2 +.CE +.SH "SEE ALSO" +ttk::button(n) .SH KEYWORDS button, widget diff --git a/doc/canvas.n b/doc/canvas.n index 5ea3035..9338b8d 100755..100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -15,19 +15,19 @@ canvas \- Create and manipulate canvas widgets .SH SYNOPSIS \fBcanvas\fR \fIpathName \fR?\fIoptions\fR? .SO -\-background \-insertborderwidth \-selectborderwidth -\-borderwidth \-insertofftime \-selectforeground -\-cursor \-insertontime \-takefocus -\-highlightbackground \-insertwidth \-xscrollcommand -\-highlightcolor \-relief \-yscrollcommand -\-highlightthickness \-state -\-insertbackground \-selectbackground +\-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 ``inside'' the item. -Defaults to 1.0. +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 @@ -80,7 +80,6 @@ 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 @@ -110,8 +109,9 @@ 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 ``on top'' of earlier items. +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 @@ -134,11 +134,15 @@ canvas widget. 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, ``x123'' is OK but ``123'' isn't. +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 ``selected''. +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 @@ -147,7 +151,8 @@ all the items in the canvas. 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. +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 @@ -162,8 +167,12 @@ 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: '&&', '||', '^' '!', and parenthesized -subexpressions. For example: +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 @@ -171,7 +180,11 @@ or equivalently: .CS .c find withtag {a^b} .CE -will find only those items with either "a" or "b" tags, but not both. +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 @@ -193,12 +206,10 @@ 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. -.VS 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. -.VE -.SH TRANSFORMATIONS +.SS TRANSFORMATIONS .PP Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. @@ -238,7 +249,7 @@ 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 don't support the insertion cursor +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 @@ -267,11 +278,11 @@ 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 isn't in this item then this form is illegal. +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 isn't in this item then this form is illegal. +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 @@ -286,24 +297,32 @@ 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 "outline" color. The other segments -are drawn transparent. +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 \fB[.,-_ ]\fR. The space can be used -to enlarge the space between other line elements, and can not +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: - -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} +.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 "." will always be displayed as a dot and "-" +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 @@ -328,7 +347,7 @@ The following widget commands are possible for canvas widgets: 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 -isn't already present on that list. +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. @@ -391,7 +410,9 @@ Selects all the items given by \fItagOrId\fR. \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 ``\fIx1 y1 x2 y2\fR'' such that the drawn +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. @@ -414,8 +435,9 @@ 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 ``+'' then \fIcommand\fR -augments an existing binding rather than replacing it). +(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 @@ -428,8 +450,9 @@ defined for \fItagOrId\fR. 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 ITEM -IDS AND TAGS above. \fBEnter\fR and \fBLeave\fR events trigger for an +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 @@ -519,11 +542,11 @@ This command returns the id for the new item. \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 don't support +If some of the items given by \fItagOrId\fR do not support indexing operations then they ignore dchars. Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, line and polygon items interpret them indices to a coordinate (an x,y pair). -Indices are described in INDICES above. +Indices are described in \fBINDICES\fR above. If \fIlast\fR is omitted, it defaults to \fIfirst\fR. This command returns an empty string. .TP @@ -535,7 +558,7 @@ an empty string. 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 doesn't have the tag \fItagToDelete\fR then +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. @@ -554,8 +577,8 @@ Set the keyboard focus for the canvas widget to the item given by 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 doesn't refer to any items, or if none of them -support the insertion cursor, then the focus isn't changed. +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 @@ -568,12 +591,12 @@ 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 doesn't actually have the input focus unless (a) +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 wasn't there already). +the canvas (if it was not there already). .RE .TP \fIpathName \fBgettags\fR \fItagOrId\fR @@ -581,27 +604,27 @@ 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 doesn't refer to any items, or if the item +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 don't support +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 INDICES above for a description of the +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 widget command \fBfocus\fR, below), but the cursor position may -be set even when the item doesn't have the focus. +be set even when the item does not have the focus. This command returns an empty string. .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 INDICES above. +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 @@ -618,7 +641,7 @@ 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 INDICES above for information about the forms allowed +See \fBINDICES\fR above for information about the forms allowed for \fIbeforeThis\fR. This command returns an empty string. .TP @@ -691,7 +714,7 @@ 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 "update" command to wait for the canvas window +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 @@ -703,13 +726,14 @@ options are supported: \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. ``\fB1.0 1.0 0.0 setrgbcolor\fR''). +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 hasn't been specified, or if there isn't an entry +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 @@ -721,7 +745,7 @@ to black or white). .TP \fB\-file \fIfileName\fR Specifies the name of the file in which to write the Postscript. -If this option isn't specified then the Postscript is returned as the +If this option is not specified then the Postscript is returned as the result of the command instead of being written to a file. .TP \fB\-fontmap \fIvarName\fR @@ -792,9 +816,10 @@ Defaults to the center of the page. \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 (``portrait'' orientation); -in rotated output the x-axis runs along the long dimension of the -page (``landscape'' orientation). +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 @@ -875,7 +900,7 @@ 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 INDICES above. +within \fItagOrId\fR, as described in \fBINDICES\fR above. .RS .TP \fIpathName \fBselect adjust \fItagOrId index\fR @@ -885,14 +910,14 @@ 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 isn't currently in \fItagOrId\fR then +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 isn't in this widget then the command +If the selection is not in this widget then the command has no effect. Returns an empty string. .TP @@ -900,7 +925,7 @@ Returns an empty string. 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 doesn't change the selection; it just sets +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. @@ -920,7 +945,7 @@ 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 isn't currently in +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. @@ -931,7 +956,7 @@ 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 doesn't refer to any items at all then +If \fItagOrId\fR does not refer to any items at all then an empty string is returned. .TP \fIpathName \fBxview \fR?\fIargs\fR? @@ -1015,14 +1040,14 @@ 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 don't support indexing or selection or the 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. -.SH "COMMON ITEM OPTIONS" +.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. @@ -1037,12 +1062,12 @@ 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 "DASH PATTERNS" for more information. +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 +\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 @@ -1076,7 +1101,7 @@ Specifies the offset of stipples. The offset value can be of the form 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 +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. @@ -1091,13 +1116,24 @@ 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 hasn't been specified then this option +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. The +offset value can be of the form +.QW \fIx\fB,\fIy\fR +or the description of a side (one of \fBn\fR, \fBne\fR, \fBe\fR, +\fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR). This +option only has an effect when the outline is drawn as a stipple +pattern, and is only supported under X11. +.\" TODO: What does this actually do? What do the acceptable forms mean?! +.TP \fB\-stipple \fIbitmap\fR .TP \fB\-activestipple \fIbitmap\fR @@ -1107,7 +1143,7 @@ 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 hasn't been specified then this option +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. @@ -1156,8 +1192,10 @@ 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. -.br +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: .CS \-dash @@ -1171,6 +1209,7 @@ The following standard options are supported by arcs: \-outline \-activeoutline \-disabledoutline +\-outlineoffset \-outlinestipple \-activeoutlinestipple \-disabledoutlinestipple @@ -1190,7 +1229,7 @@ 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 +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 @@ -1219,15 +1258,17 @@ Bitmaps are created with widget commands of the following form: \fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR? \fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value option value ...\fR? .CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a +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 (see the \fB\-anchor\fR option below for more information on how bitmaps are 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. -.br +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: .CS \-state @@ -1249,10 +1290,11 @@ This option defaults to \fBcenter\fR. \fB\-activebackground \fIcolor\fR .TP \fB\-disabledbackground \fIcolor\fR -Specifies the color to use for each of the bitmap's '0' valued pixels -in its normal, active and disabled states. +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 isn't specified, or if it is specified as an empty +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 @@ -1270,8 +1312,9 @@ disabled states. \fB\-activeforeground \fIcolor\fR .TP \fB\-disabledforeground \fIcolor\fR -Specifies the color to use for each of the bitmap's '1' valued pixels -in its normal, active and disabled states. +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. .SH "IMAGE ITEMS" @@ -1290,8 +1333,9 @@ 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. -.br +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: .CS \-state @@ -1335,8 +1379,10 @@ 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. -.br +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: .CS \-dash @@ -1377,14 +1423,16 @@ 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 isn't specified then Tk picks a ``reasonable'' shape. +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 isn't specified then it defaults to \fBbutt\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 @@ -1392,27 +1440,38 @@ 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_GetCapStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option isn't specified then it defaults to \fBmiter\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 \fBbezier\fR is -supported in the core, but more can be added at runtime. If a boolean +\fBTcl_GetBoolean\fR or a line smoothing method. +.VS 8.5 +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 assume \fBbezier\fR smoothing. -It indicates whether or not the line should be drawn as a curve. -If so, the line is rendered as a set of parabolic splines: one spline +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. +.VE 8.5 .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. - +option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .SH "OVAL ITEMS" .PP Items of type \fBoval\fR appear as circular or oval regions on @@ -1434,8 +1493,10 @@ 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. -.br +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: .CS \-dash @@ -1449,6 +1510,7 @@ The following standard options are supported by ovals: \-outline \-activeoutline \-disabledoutline +\-outlineoffset \-outlinestipple \-activeoutlinestipple \-disabledoutlinestipple @@ -1481,8 +1543,10 @@ 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. -.br +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: .CS \-dash @@ -1515,25 +1579,41 @@ 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_GetCapStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option isn't specified then it defaults to \fBmiter\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. -It indicates whether or not the polygon should be drawn with a -curved perimeter. -If so, the outline of the polygon becomes a set of parabolic splines, -one spline for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated in a -smoothed polygon by duplicating the end-points of the desired line segment. +\fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR +.VS 8.5 +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). +.VE 8.5 .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. +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 ``inside'' a -polygon (e.g. for purposes of the \fBfind closest\fR and +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 @@ -1550,7 +1630,8 @@ following form: \fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? \fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value option value ...\fR? .CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give +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). @@ -1558,8 +1639,11 @@ 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. -.br +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: .CS \-dash @@ -1573,6 +1657,7 @@ The following standard options are supported by rectangles: \-outline \-activeoutline \-disabledoutline +\-outlineoffset \-outlinestipple \-activeoutlinestipple \-disabledoutlinestipple @@ -1599,15 +1684,17 @@ form: \fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR? \fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value option value ...\fR? .CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a +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. -.br +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: .CS \-fill @@ -1634,7 +1721,7 @@ This option defaults to \fBcenter\fR. \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 isn't specified, it defaults to a system-dependent +If this option is not specified, it defaults to a system-dependent font. .TP \fB\-justify \fIhow\fR @@ -1651,6 +1738,15 @@ 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. +.VS 8.5 +.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). +.VE 8.5 .TP \fB\-width \fIlineLength\fR Specifies a maximum line length for the text, in any of the forms @@ -1671,15 +1767,19 @@ Window items are created with widget commands of the following form: \fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR? \fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value option value ...\fR? .CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a +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 (see the \fB\-anchor\fR option below for more information on how bitmaps are 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. -.br +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: .CS \-state @@ -1688,6 +1788,7 @@ The following standard options are supported by window items: The following extra options are supported for window items: .TP \fB\-anchor \fIanchorPos\fR +. \fIAnchorPos\fR tells how to position the window 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 @@ -1697,20 +1798,23 @@ its top center point is at the positioning point. This option defaults to \fBcenter\fR. .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 isn't specified, or if it is specified as an empty -string, then the window is given whatever height it requests internally. +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 isn't specified, or if it is specified as an empty -string, then the window is given whatever width it requests internally. +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. @@ -1719,7 +1823,11 @@ the canvas widget or a child of some ancestor of the canvas widget. 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. +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 @@ -1728,7 +1836,7 @@ See the documentation for \fBTk_CreateItemType\fR. .SH BINDINGS .PP In the current implementation, new canvases are not given any -default behavior: you'll have to execute explicit Tcl commands +default behavior: you will have to execute explicit Tcl commands to give the canvas its behavior. .SH CREDITS .PP @@ -1737,9 +1845,7 @@ Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's 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 diff --git a/doc/checkbutton.n b/doc/checkbutton.n index f236de2..1e05c96 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.n @@ -34,31 +34,34 @@ 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 isn't specified, the button's desired height is computed +If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-indicatoron indicatorOn IndicatorOn Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the \fBrelief\fR option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. -.VS 8.4 .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 "raised". By setting this option -to "flat" and setting -indicatoron to false and -overrelief to raised, -the effect is achieved +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. -.VE 8.4 .OP \-offvalue offValue Value Specifies value to store in the button's associated variable whenever -this button is deselected. Defaults to ``0''. +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 ``1''. -.VS 8.4 +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 @@ -66,12 +69,10 @@ 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. -.VE 8.4 .OP \-selectcolor selectColor Background Specifies a background color to use when the button is selected. -If \fBindicatorOn\fR is true then the color applies to the indicator. -Under Windows, this color is used as the background for the indicator -regardless of the select state. +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. @@ -93,6 +94,19 @@ should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fBdisabledForeground\fR and \fBbackground\fR options determine how the checkbutton is displayed. +.OP \-tristateimage tristateImage TristateImage +.VS 8.5 +Specifies an image to display (in place of the \fBimage\fR option) +when the checkbutton is in tri-state mode. +This option is ignored unless the \fBimage\fR option has been +specified. +.VE 8.5 +.OP \-tristatevalue tristateValue Value +.VS 8.5 +Specifies the value that causes the checkbutton to display the multi-value +selection, also known as the tri-state mode. Defaults to +.QW "" . +.VE 8.5 .OP \-variable variable Variable Specifies the name of a global variable to set to indicate whether or not this button is selected. Defaults to the name of the @@ -103,10 +117,9 @@ 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 isn't specified, the button's desired width is computed +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 @@ -139,30 +152,45 @@ checkbutton. .PP In addition, checkbuttons can be \fIselected\fR. If a checkbutton is selected then the indicator is normally -.VS drawn with a selected appearance, and a Tcl variable associated with the checkbutton 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 check mark inside. +.VS 8.5 +The indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a check mark inside. -.VE +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 ``on'' and ``off'' values stored in it, -may be modified with options on the command line or in the option -database. +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 ``on'' value. +changes to and from the button's +.QW on , +.QW off +and +.QW tristate +values. +.VE 8.5 .SH "WIDGET COMMAND" .PP The \fBcheckbutton\fR command creates a new Tcl command whose @@ -197,7 +225,8 @@ this case the command returns an empty string. command. .TP \fIpathName \fBdeselect\fR -Deselects the checkbutton and sets the associated variable to its ``off'' +Deselects the checkbutton and sets the associated variable to its +.QW off value. .TP \fIpathName \fBflash\fR @@ -216,7 +245,8 @@ 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 ``on'' +Selects the checkbutton and sets the associated variable to its +.QW on value. .TP \fIpathName \fBtoggle\fR @@ -226,7 +256,6 @@ modifying its associated variable to reflect the new state. .PP Tk automatically creates class bindings for checkbuttons that give them the following default behavior: -.VS .IP [1] On Unix systems, a checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. On @@ -234,26 +263,32 @@ 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. -.VE .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). -.VS .IP [3] When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus -(+) and equal (=) select the button, and minus (-) deselects the button. -.VE +(+) and equal (=) select the button, and minus (\-) deselects the button. .PP If the checkbutton's state is \fBdisabled\fR then none of the above actions occur: the checkbutton is completely non-responsive. .PP The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. - +.SH EXAMPLE +This example shows a group of uncoupled checkbuttons. +.PP +.CS + labelframe .lbl \-text "Steps:" + \fBcheckbutton\fR .c1 \-text Lights \-variable lights + \fBcheckbutton\fR .c2 \-text Cameras \-variable cameras + \fBcheckbutton\fR .c3 \-text Action! \-variable action + pack .c1 .c2 .c3 \-in .lbl + pack .lbl +.CE .SH "SEE ALSO" -button(n), options(n), radiobutton(n) - +button(n), options(n), radiobutton(n), ttk::checkbutton(n) .SH KEYWORDS checkbutton, widget diff --git a/doc/chooseColor.n b/doc/chooseColor.n index 8bb8d83..565934c 100644 --- a/doc/chooseColor.n +++ b/doc/chooseColor.n @@ -10,7 +10,6 @@ '\" 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. -.PP .SH SYNOPSIS \fBtk_chooseColor \fR?\fIoption value ...\fR? .BE diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index c796f86..c380ccf 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -8,11 +8,9 @@ '\" 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. -.PP .SH SYNOPSIS \fBtk_chooseDirectory \fR?\fIoption value ...\fR? .BE - .SH DESCRIPTION .PP The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the @@ -24,31 +22,29 @@ Specifies that the directories in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, then the directories in the current working directory are displayed. If the parameter specifies a relative path, the return value will convert the -relative path to an absolute path. This option may not always work on -the Macintosh. This is not a bug. Rather, the \fIGeneral Controls\fR -control panel on the Mac allows the end user to override the -application default directory. +relative path to an absolute path. +.TP +\fB\-mustexist\fR \fIboolean\fR +Specifies whether the user may specify non-existent directories. If +this parameter is true, then the user may only select directories that +already exist. The default value is \fIfalse\fR. .TP \fB\-parent\fR \fIwindow\fR Makes \fIwindow\fR the logical parent of the dialog. The dialog -is displayed on top of its parent window. +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. -.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. .SH EXAMPLE .CS -set dir [\fBtk_chooseDirectory\fR \\ +set dir [\fBtk_chooseDirectory\fR \e \-initialdir ~ \-title "Choose a directory"] if {$dir eq ""} { - label .l -text "No directory selected" + label .l \-text "No directory selected" } else { - label .l -text "Selected $dir" + label .l \-text "Selected $dir" } .CE diff --git a/doc/clipboard.n b/doc/clipboard.n index 9fa858a..b689328 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.n @@ -19,7 +19,7 @@ clipboard \- Manipulate Tk clipboard .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). +(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 @@ -32,8 +32,9 @@ forms are currently supported: .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 ``.''. Returns an -empty string. +any previous contents. \fIWindow\fR defaults to +.QW . . +Returns an empty string. .TP \fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR Appends \fIdata\fR to the clipboard on \fIwindow\fR's @@ -43,7 +44,9 @@ display. .RS .PP \fIType\fR specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and +(the desired +.QW target +for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME; see the Inter-Client Communication Conventions Manual for complete details. \fIType\fR defaults to STRING. @@ -65,7 +68,7 @@ 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 don't use Tk. If the Tk toolkit is being +clipboard requesters that do not use Tk. If the Tk toolkit is being used to retrieve the CLIPBOARD selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. @@ -77,13 +80,19 @@ with a \fB\-\fR. .RE .TP \fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR? -.VS 8.4 Retrieve data from the clipboard on \fIwindow\fR's display. -\fIwindow\fR defaults to ".". \fIType\fR specifies the form in which +\fIWindow\fR defaults to +.QW . . +\fIType\fR specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. \fIType\fR defaults to STRING. This command is -equivalent to \fBselection get -selection CLIPBOARD\fR. -.VE 8.4 +equivalent to +.QW "\fBselection get \-selection CLIPBOARD\fR" . +.RS +.PP +Note that on modern X11 systems, the most useful type to retrieve for +transferred strings is not \fBSTRING\fR, but rather \fBUTF8_STRING\fR. +.RE .SH EXAMPLES Get the current contents of the clipboard. .CS @@ -97,9 +106,49 @@ Set the clipboard to contain a fixed string. \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" -selection(n) +interp(n), selection(n) .SH KEYWORDS clear, format, clipboard, append, selection, type diff --git a/doc/colors.n b/doc/colors.n index 604ac52..4b8cda1 100644 --- a/doc/colors.n +++ b/doc/colors.n @@ -2,12 +2,12 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" Copyright (c) 2003 ActiveState Corporation. '\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net> -'\" +'\" Copyright (c) 2008 Donal K. Fellows '\" .so man.macros .TH colors n 8.3 Tk "Tk Built-In Commands" .BS -'\" Note: do not modify the .SH NAME line immediately below! +.\" Note: do not modify the .SH NAME line immediately below! .SH NAME colors \- symbolic color names recognized by Tk .BE @@ -15,914 +15,932 @@ colors \- symbolic color names recognized by Tk .PP Tk recognizes many symbolic color names (e.g., \fBred\fR) when specifying colors. The symbolic names recognized by Tk and their -8-bit RGB values are: -.CS -\fIName\fR \fIRed\fR \fIGreen\fR \fIBlue\fR -alice blue 240 248 255 -AliceBlue 240 248 255 -antique white 250 235 215 -AntiqueWhite 250 235 215 -AntiqueWhite1 255 239 219 -AntiqueWhite2 238 223 204 -AntiqueWhite3 205 192 176 -AntiqueWhite4 139 131 120 -aquamarine 127 255 212 -aquamarine1 127 255 212 -aquamarine2 118 238 198 -aquamarine3 102 205 170 -aquamarine4 69 139 116 -azure 240 255 255 -azure1 240 255 255 -azure2 224 238 238 -azure3 193 205 205 -azure4 131 139 139 -beige 245 245 220 -bisque 255 228 196 -bisque1 255 228 196 -bisque2 238 213 183 -bisque3 205 183 158 -bisque4 139 125 107 -black 0 0 0 -blanched almond 255 235 205 -BlanchedAlmond 255 235 205 -blue 0 0 255 -blue violet 138 43 226 -blue1 0 0 255 -blue2 0 0 238 -blue3 0 0 205 -blue4 0 0 139 -BlueViolet 138 43 226 -brown 165 42 42 -brown1 255 64 64 -brown2 238 59 59 -brown3 205 51 51 -brown4 139 35 35 -burlywood 222 184 135 -burlywood1 255 211 155 -burlywood2 238 197 145 -burlywood3 205 170 125 -burlywood4 139 115 85 -cadet blue 95 158 160 -CadetBlue 95 158 160 -CadetBlue1 152 245 255 -CadetBlue2 142 229 238 -CadetBlue3 122 197 205 -CadetBlue4 83 134 139 -chartreuse 127 255 0 -chartreuse1 127 255 0 -chartreuse2 118 238 0 -chartreuse3 102 205 0 -chartreuse4 69 139 0 -chocolate 210 105 30 -chocolate1 255 127 36 -chocolate2 238 118 33 -chocolate3 205 102 29 -chocolate4 139 69 19 -coral 255 127 80 -coral1 255 114 86 -coral2 238 106 80 -coral3 205 91 69 -coral4 139 62 47 -cornflower blue 100 149 237 -CornflowerBlue 100 149 237 -cornsilk 255 248 220 -cornsilk1 255 248 220 -cornsilk2 238 232 205 -cornsilk3 205 200 177 -cornsilk4 139 136 120 -cyan 0 255 255 -cyan1 0 255 255 -cyan2 0 238 238 -cyan3 0 205 205 -cyan4 0 139 139 -dark blue 0 0 139 -dark cyan 0 139 139 -dark goldenrod 184 134 11 -dark gray 169 169 169 -dark green 0 100 0 -dark grey 169 169 169 -dark khaki 189 183 107 -dark magenta 139 0 139 -dark olive green 85 107 47 -dark orange 255 140 0 -dark orchid 153 50 204 -dark red 139 0 0 -dark salmon 233 150 122 -dark sea green 143 188 143 -dark slate blue 72 61 139 -dark slate gray 47 79 79 -dark slate grey 47 79 79 -dark turquoise 0 206 209 -dark violet 148 0 211 -DarkBlue 0 0 139 -DarkCyan 0 139 139 -DarkGoldenrod 184 134 11 -DarkGoldenrod1 255 185 15 -DarkGoldenrod2 238 173 14 -DarkGoldenrod3 205 149 12 -DarkGoldenrod4 139 101 8 -DarkGray 169 169 169 -DarkGreen 0 100 0 -DarkGrey 169 169 169 -DarkKhaki 189 183 107 -DarkMagenta 139 0 139 -DarkOliveGreen 85 107 47 -DarkOliveGreen1 202 255 112 -DarkOliveGreen2 188 238 104 -DarkOliveGreen3 162 205 90 -DarkOliveGreen4 110 139 61 -DarkOrange 255 140 0 -DarkOrange1 255 127 0 -DarkOrange2 238 118 0 -DarkOrange3 205 102 0 -DarkOrange4 139 69 0 -DarkOrchid 153 50 204 -DarkOrchid1 191 62 255 -DarkOrchid2 178 58 238 -DarkOrchid3 154 50 205 -DarkOrchid4 104 34 139 -DarkRed 139 0 0 -DarkSalmon 233 150 122 -DarkSeaGreen 143 188 143 -DarkSeaGreen1 193 255 193 -DarkSeaGreen2 180 238 180 -DarkSeaGreen3 155 205 155 -DarkSeaGreen4 105 139 105 -DarkSlateBlue 72 61 139 -DarkSlateGray 47 79 79 -DarkSlateGray1 151 255 255 -DarkSlateGray2 141 238 238 -DarkSlateGray3 121 205 205 -DarkSlateGray4 82 139 139 -DarkSlateGrey 47 79 79 -DarkTurquoise 0 206 209 -DarkViolet 148 0 211 -deep pink 255 20 147 -deep sky blue 0 191 255 -DeepPink 255 20 147 -DeepPink1 255 20 147 -DeepPink2 238 18 137 -DeepPink3 205 16 118 -DeepPink4 139 10 80 -DeepSkyBlue 0 191 255 -DeepSkyBlue1 0 191 255 -DeepSkyBlue2 0 178 238 -DeepSkyBlue3 0 154 205 -DeepSkyBlue4 0 104 139 -dim gray 105 105 105 -dim grey 105 105 105 -DimGray 105 105 105 -DimGrey 105 105 105 -dodger blue 30 144 255 -DodgerBlue 30 144 255 -DodgerBlue1 30 144 255 -DodgerBlue2 28 134 238 -DodgerBlue3 24 116 205 -DodgerBlue4 16 78 139 -firebrick 178 34 34 -firebrick1 255 48 48 -firebrick2 238 44 44 -firebrick3 205 38 38 -firebrick4 139 26 26 -floral white 255 250 240 -FloralWhite 255 250 240 -forest green 34 139 34 -ForestGreen 34 139 34 -gainsboro 220 220 220 -ghost white 248 248 255 -GhostWhite 248 248 255 -gold 255 215 0 -gold1 255 215 0 -gold2 238 201 0 -gold3 205 173 0 -gold4 139 117 0 -goldenrod 218 165 32 -goldenrod1 255 193 37 -goldenrod2 238 180 34 -goldenrod3 205 155 29 -goldenrod4 139 105 20 -gray 190 190 190 -gray0 0 0 0 -gray1 3 3 3 -gray2 5 5 5 -gray3 8 8 8 -gray4 10 10 10 -gray5 13 13 13 -gray6 15 15 15 -gray7 18 18 18 -gray8 20 20 20 -gray9 23 23 23 -gray10 26 26 26 -gray11 28 28 28 -gray12 31 31 31 -gray13 33 33 33 -gray14 36 36 36 -gray15 38 38 38 -.CE -.CS -gray16 41 41 41 -gray17 43 43 43 -gray18 46 46 46 -gray19 48 48 48 -gray20 51 51 51 -gray21 54 54 54 -gray22 56 56 56 -gray23 59 59 59 -gray24 61 61 61 -gray25 64 64 64 -gray26 66 66 66 -gray27 69 69 69 -gray28 71 71 71 -gray29 74 74 74 -gray30 77 77 77 -gray31 79 79 79 -gray32 82 82 82 -gray33 84 84 84 -gray34 87 87 87 -gray35 89 89 89 -gray36 92 92 92 -gray37 94 94 94 -gray38 97 97 97 -gray39 99 99 99 -gray40 102 102 102 -gray41 105 105 105 -gray42 107 107 107 -gray43 110 110 110 -gray44 112 112 112 -gray45 115 115 115 -gray46 117 117 117 -gray47 120 120 120 -gray48 122 122 122 -gray49 125 125 125 -gray50 127 127 127 -gray51 130 130 130 -gray52 133 133 133 -gray53 135 135 135 -gray54 138 138 138 -gray55 140 140 140 -gray56 143 143 143 -gray57 145 145 145 -gray58 148 148 148 -gray59 150 150 150 -gray60 153 153 153 -gray61 156 156 156 -gray62 158 158 158 -gray63 161 161 161 -gray64 163 163 163 -gray65 166 166 166 -gray66 168 168 168 -gray67 171 171 171 -gray68 173 173 173 -gray69 176 176 176 -gray70 179 179 179 -gray71 181 181 181 -gray72 184 184 184 -gray73 186 186 186 -gray74 189 189 189 -gray75 191 191 191 -gray76 194 194 194 -gray77 196 196 196 -gray78 199 199 199 -gray79 201 201 201 -gray80 204 204 204 -gray81 207 207 207 -gray82 209 209 209 -gray83 212 212 212 -gray84 214 214 214 -gray85 217 217 217 -gray86 219 219 219 -gray87 222 222 222 -gray88 224 224 224 -gray89 227 227 227 -gray90 229 229 229 -gray91 232 232 232 -gray92 235 235 235 -gray93 237 237 237 -gray94 240 240 240 -gray95 242 242 242 -gray96 245 245 245 -gray97 247 247 247 -gray98 250 250 250 -gray99 252 252 252 -gray100 255 255 255 -green 0 255 0 -green yellow 173 255 47 -green1 0 255 0 -green2 0 238 0 -green3 0 205 0 -green4 0 139 0 -GreenYellow 173 255 47 -grey 190 190 190 -grey0 0 0 0 -grey1 3 3 3 -grey2 5 5 5 -grey3 8 8 8 -grey4 10 10 10 -grey5 13 13 13 -grey6 15 15 15 -grey7 18 18 18 -grey8 20 20 20 -grey9 23 23 23 -grey10 26 26 26 -grey11 28 28 28 -grey12 31 31 31 -grey13 33 33 33 -grey14 36 36 36 -grey15 38 38 38 -grey16 41 41 41 -grey17 43 43 43 -grey18 46 46 46 -grey19 48 48 48 -grey20 51 51 51 -grey21 54 54 54 -grey22 56 56 56 -grey23 59 59 59 -grey24 61 61 61 -grey25 64 64 64 -grey26 66 66 66 -grey27 69 69 69 -grey28 71 71 71 -grey29 74 74 74 -grey30 77 77 77 -grey31 79 79 79 -grey32 82 82 82 -grey33 84 84 84 -grey34 87 87 87 -grey35 89 89 89 -grey36 92 92 92 -grey37 94 94 94 -grey38 97 97 97 -grey39 99 99 99 -grey40 102 102 102 -grey41 105 105 105 -grey42 107 107 107 -grey43 110 110 110 -grey44 112 112 112 -grey45 115 115 115 -grey46 117 117 117 -grey47 120 120 120 -grey48 122 122 122 -grey49 125 125 125 -grey50 127 127 127 -grey51 130 130 130 -grey52 133 133 133 -grey53 135 135 135 -grey54 138 138 138 -grey55 140 140 140 -grey56 143 143 143 -grey57 145 145 145 -grey58 148 148 148 -grey59 150 150 150 -grey60 153 153 153 -grey61 156 156 156 -grey62 158 158 158 -grey63 161 161 161 -grey64 163 163 163 -grey65 166 166 166 -grey66 168 168 168 -grey67 171 171 171 -grey68 173 173 173 -grey69 176 176 176 -grey70 179 179 179 -grey71 181 181 181 -grey72 184 184 184 -grey73 186 186 186 -grey74 189 189 189 -grey75 191 191 191 -grey76 194 194 194 -grey77 196 196 196 -grey78 199 199 199 -grey79 201 201 201 -grey80 204 204 204 -grey81 207 207 207 -grey82 209 209 209 -grey83 212 212 212 -grey84 214 214 214 -grey85 217 217 217 -grey86 219 219 219 -grey87 222 222 222 -grey88 224 224 224 -grey89 227 227 227 -grey90 229 229 229 -grey91 232 232 232 -grey92 235 235 235 -grey93 237 237 237 -grey94 240 240 240 -grey95 242 242 242 -grey96 245 245 245 -grey97 247 247 247 -grey98 250 250 250 -grey99 252 252 252 -grey100 255 255 255 -honeydew 240 255 240 -honeydew1 240 255 240 -honeydew2 224 238 224 -honeydew3 193 205 193 -honeydew4 131 139 131 -hot pink 255 105 180 -.CE -.CS -HotPink 255 105 180 -HotPink1 255 110 180 -HotPink2 238 106 167 -HotPink3 205 96 144 -HotPink4 139 58 98 -indian red 205 92 92 -IndianRed 205 92 92 -IndianRed1 255 106 106 -IndianRed2 238 99 99 -IndianRed3 205 85 85 -IndianRed4 139 58 58 -ivory 255 255 240 -ivory1 255 255 240 -ivory2 238 238 224 -ivory3 205 205 193 -ivory4 139 139 131 -khaki 240 230 140 -khaki1 255 246 143 -khaki2 238 230 133 -khaki3 205 198 115 -khaki4 139 134 78 -lavender 230 230 250 -lavender blush 255 240 245 -LavenderBlush 255 240 245 -LavenderBlush1 255 240 245 -LavenderBlush2 238 224 229 -LavenderBlush3 205 193 197 -LavenderBlush4 139 131 134 -lawn green 124 252 0 -LawnGreen 124 252 0 -lemon chiffon 255 250 205 -LemonChiffon 255 250 205 -LemonChiffon1 255 250 205 -LemonChiffon2 238 233 191 -LemonChiffon3 205 201 165 -LemonChiffon4 139 137 112 -light blue 173 216 230 -light coral 240 128 128 -light cyan 224 255 255 -light goldenrod 238 221 130 -light goldenrod yellow 250 250 210 -light gray 211 211 211 -light green 144 238 144 -light grey 211 211 211 -light pink 255 182 193 -light salmon 255 160 122 -light sea green 32 178 170 -light sky blue 135 206 250 -light slate blue 132 112 255 -light slate gray 119 136 153 -light slate grey 119 136 153 -light steel blue 176 196 222 -light yellow 255 255 224 -LightBlue 173 216 230 -LightBlue1 191 239 255 -LightBlue2 178 223 238 -LightBlue3 154 192 205 -LightBlue4 104 131 139 -LightCoral 240 128 128 -LightCyan 224 255 255 -LightCyan1 224 255 255 -LightCyan2 209 238 238 -LightCyan3 180 205 205 -LightCyan4 122 139 139 -LightGoldenrod 238 221 130 -LightGoldenrod1 255 236 139 -LightGoldenrod2 238 220 130 -LightGoldenrod3 205 190 112 -LightGoldenrod4 139 129 76 -LightGoldenrodYellow 250 250 210 -LightGray 211 211 211 -LightGreen 144 238 144 -LightGrey 211 211 211 -LightPink 255 182 193 -LightPink1 255 174 185 -LightPink2 238 162 173 -LightPink3 205 140 149 -LightPink4 139 95 101 -LightSalmon 255 160 122 -LightSalmon1 255 160 122 -LightSalmon2 238 149 114 -LightSalmon3 205 129 98 -LightSalmon4 139 87 66 -LightSeaGreen 32 178 170 -LightSkyBlue 135 206 250 -LightSkyBlue1 176 226 255 -LightSkyBlue2 164 211 238 -LightSkyBlue3 141 182 205 -LightSkyBlue4 96 123 139 -LightSlateBlue 132 112 255 -LightSlateGray 119 136 153 -LightSlateGrey 119 136 153 -LightSteelBlue 176 196 222 -LightSteelBlue1 202 225 255 -LightSteelBlue2 188 210 238 -LightSteelBlue3 162 181 205 -LightSteelBlue4 110 123 139 -LightYellow 255 255 224 -LightYellow1 255 255 224 -LightYellow2 238 238 209 -LightYellow3 205 205 180 -LightYellow4 139 139 122 -lime green 50 205 50 -LimeGreen 50 205 50 -linen 250 240 230 -magenta 255 0 255 -magenta1 255 0 255 -magenta2 238 0 238 -magenta3 205 0 205 -magenta4 139 0 139 -maroon 176 48 96 -maroon1 255 52 179 -maroon2 238 48 167 -maroon3 205 41 144 -maroon4 139 28 98 -medium aquamarine 102 205 170 -medium blue 0 0 205 -medium orchid 186 85 211 -medium purple 147 112 219 -medium sea green 60 179 113 -medium slate blue 123 104 238 -medium spring green 0 250 154 -medium turquoise 72 209 204 -medium violet red 199 21 133 -MediumAquamarine 102 205 170 -MediumBlue 0 0 205 -MediumOrchid 186 85 211 -MediumOrchid1 224 102 255 -MediumOrchid2 209 95 238 -MediumOrchid3 180 82 205 -MediumOrchid4 122 55 139 -MediumPurple 147 112 219 -MediumPurple1 171 130 255 -MediumPurple2 159 121 238 -MediumPurple3 137 104 205 -MediumPurple4 93 71 139 -MediumSeaGreen 60 179 113 -MediumSlateBlue 123 104 238 -MediumSpringGreen 0 250 154 -MediumTurquoise 72 209 204 -MediumVioletRed 199 21 133 -midnight blue 25 25 112 -MidnightBlue 25 25 112 -mint cream 245 255 250 -MintCream 245 255 250 -misty rose 255 228 225 -MistyRose 255 228 225 -MistyRose1 255 228 225 -MistyRose2 238 213 210 -MistyRose3 205 183 181 -MistyRose4 139 125 123 -moccasin 255 228 181 -navajo white 255 222 173 -NavajoWhite 255 222 173 -NavajoWhite1 255 222 173 -NavajoWhite2 238 207 161 -NavajoWhite3 205 179 139 -NavajoWhite4 139 121 94 -navy 0 0 128 -navy blue 0 0 128 -NavyBlue 0 0 128 -old lace 253 245 230 -OldLace 253 245 230 -olive drab 107 142 35 -OliveDrab 107 142 35 -OliveDrab1 192 255 62 -OliveDrab2 179 238 58 -OliveDrab3 154 205 50 -OliveDrab4 105 139 34 -orange 255 165 0 -orange red 255 69 0 -orange1 255 165 0 -orange2 238 154 0 -orange3 205 133 0 -orange4 139 90 0 -OrangeRed 255 69 0 -OrangeRed1 255 69 0 -OrangeRed2 238 64 0 -OrangeRed3 205 55 0 -OrangeRed4 139 37 0 -orchid 218 112 214 -orchid1 255 131 250 -orchid2 238 122 233 -orchid3 205 105 201 -orchid4 139 71 137 -pale goldenrod 238 232 170 -pale green 152 251 152 -pale turquoise 175 238 238 -pale violet red 219 112 147 -PaleGoldenrod 238 232 170 -PaleGreen 152 251 152 -PaleGreen1 154 255 154 -PaleGreen2 144 238 144 -PaleGreen3 124 205 124 -PaleGreen4 84 139 84 -PaleTurquoise 175 238 238 -PaleTurquoise1 187 255 255 -PaleTurquoise2 174 238 238 -PaleTurquoise3 150 205 205 -PaleTurquoise4 102 139 139 -.CE -.CS -PaleVioletRed 219 112 147 -PaleVioletRed1 255 130 171 -PaleVioletRed2 238 121 159 -PaleVioletRed3 205 104 127 -PaleVioletRed4 139 71 93 -papaya whip 255 239 213 -PapayaWhip 255 239 213 -peach puff 255 218 185 -PeachPuff 255 218 185 -PeachPuff1 255 218 185 -PeachPuff2 238 203 173 -PeachPuff3 205 175 149 -PeachPuff4 139 119 101 -peru 205 133 63 -pink 255 192 203 -pink1 255 181 197 -pink2 238 169 184 -pink3 205 145 158 -pink4 139 99 108 -plum 221 160 221 -plum1 255 187 255 -plum2 238 174 238 -plum3 205 150 205 -plum4 139 102 139 -powder blue 176 224 230 -PowderBlue 176 224 230 -purple 160 32 240 -purple1 155 48 255 -purple2 145 44 238 -purple3 125 38 205 -purple4 85 26 139 -red 255 0 0 -red1 255 0 0 -red2 238 0 0 -red3 205 0 0 -red4 139 0 0 -rosy brown 188 143 143 -RosyBrown 188 143 143 -RosyBrown1 255 193 193 -RosyBrown2 238 180 180 -RosyBrown3 205 155 155 -RosyBrown4 139 105 105 -royal blue 65 105 225 -RoyalBlue 65 105 225 -RoyalBlue1 72 118 255 -RoyalBlue2 67 110 238 -RoyalBlue3 58 95 205 -RoyalBlue4 39 64 139 -saddle brown 139 69 19 -SaddleBrown 139 69 19 -salmon 250 128 114 -salmon1 255 140 105 -salmon2 238 130 98 -salmon3 205 112 84 -salmon4 139 76 57 -sandy brown 244 164 96 -SandyBrown 244 164 96 -sea green 46 139 87 -SeaGreen 46 139 87 -SeaGreen1 84 255 159 -SeaGreen2 78 238 148 -SeaGreen3 67 205 128 -SeaGreen4 46 139 87 -seashell 255 245 238 -seashell1 255 245 238 -seashell2 238 229 222 -seashell3 205 197 191 -seashell4 139 134 130 -sienna 160 82 45 -sienna1 255 130 71 -sienna2 238 121 66 -sienna3 205 104 57 -sienna4 139 71 38 -sky blue 135 206 235 -SkyBlue 135 206 235 -SkyBlue1 135 206 255 -SkyBlue2 126 192 238 -SkyBlue3 108 166 205 -SkyBlue4 74 112 139 -slate blue 106 90 205 -slate gray 112 128 144 -slate grey 112 128 144 -SlateBlue 106 90 205 -SlateBlue1 131 111 255 -SlateBlue2 122 103 238 -SlateBlue3 105 89 205 -SlateBlue4 71 60 139 -SlateGray 112 128 144 -SlateGray1 198 226 255 -SlateGray2 185 211 238 -SlateGray3 159 182 205 -SlateGray4 108 123 139 -SlateGrey 112 128 144 -snow 255 250 250 -snow1 255 250 250 -snow2 238 233 233 -snow3 205 201 201 -snow4 139 137 137 -spring green 0 255 127 -SpringGreen 0 255 127 -SpringGreen1 0 255 127 -SpringGreen2 0 238 118 -SpringGreen3 0 205 102 -SpringGreen4 0 139 69 -steel blue 70 130 180 -SteelBlue 70 130 180 -SteelBlue1 99 184 255 -SteelBlue2 92 172 238 -SteelBlue3 79 148 205 -SteelBlue4 54 100 139 -tan 210 180 140 -tan1 255 165 79 -tan2 238 154 73 -tan3 205 133 63 -tan4 139 90 43 -thistle 216 191 216 -thistle1 255 225 255 -thistle2 238 210 238 -thistle3 205 181 205 -thistle4 139 123 139 -tomato 255 99 71 -tomato1 255 99 71 -tomato2 238 92 66 -tomato3 205 79 57 -tomato4 139 54 38 -turquoise 64 224 208 -turquoise1 0 245 255 -turquoise2 0 229 238 -turquoise3 0 197 205 -turquoise4 0 134 139 -violet 238 130 238 -violet red 208 32 144 -VioletRed 208 32 144 -VioletRed1 255 62 150 -VioletRed2 238 58 140 -VioletRed3 205 50 120 -VioletRed4 139 34 82 -wheat 245 222 179 -wheat1 255 231 186 -wheat2 238 216 174 -wheat3 205 186 150 -wheat4 139 126 102 -white 255 255 255 -white smoke 245 245 245 -WhiteSmoke 245 245 245 -yellow 255 255 0 -yellow green 154 205 50 -yellow1 255 255 0 -yellow2 238 238 0 -yellow3 205 205 0 -yellow4 139 139 0 -YellowGreen 154 205 50 -.CE - +8-bit-per-channel RGB values are: +.DS +.ta 7.2cR 9.5cR 11cR +\fBName\fR \fBRed\fR \fBGreen\fR \fBBlue\fR +alice blue 240 248 255 +AliceBlue 240 248 255 +antique white 250 235 215 +AntiqueWhite 250 235 215 +AntiqueWhite1 255 239 219 +AntiqueWhite2 238 223 204 +AntiqueWhite3 205 192 176 +AntiqueWhite4 139 131 120 +aquamarine 127 255 212 +aquamarine1 127 255 212 +aquamarine2 118 238 198 +aquamarine3 102 205 170 +aquamarine4 69 139 116 +azure 240 255 255 +azure1 240 255 255 +azure2 224 238 238 +azure3 193 205 205 +azure4 131 139 139 +beige 245 245 220 +bisque 255 228 196 +bisque1 255 228 196 +bisque2 238 213 183 +bisque3 205 183 158 +bisque4 139 125 107 +black 0 0 0 +blanched almond 255 235 205 +BlanchedAlmond 255 235 205 +blue 0 0 255 +blue violet 138 43 226 +blue1 0 0 255 +blue2 0 0 238 +blue3 0 0 205 +blue4 0 0 139 +BlueViolet 138 43 226 +brown 165 42 42 +brown1 255 64 64 +brown2 238 59 59 +brown3 205 51 51 +brown4 139 35 35 +burlywood 222 184 135 +burlywood1 255 211 155 +burlywood2 238 197 145 +burlywood3 205 170 125 +burlywood4 139 115 85 +cadet blue 95 158 160 +CadetBlue 95 158 160 +CadetBlue1 152 245 255 +CadetBlue2 142 229 238 +CadetBlue3 122 197 205 +CadetBlue4 83 134 139 +chartreuse 127 255 0 +chartreuse1 127 255 0 +chartreuse2 118 238 0 +chartreuse3 102 205 0 +chartreuse4 69 139 0 +chocolate 210 105 30 +chocolate1 255 127 36 +chocolate2 238 118 33 +chocolate3 205 102 29 +chocolate4 139 69 19 +coral 255 127 80 +coral1 255 114 86 +coral2 238 106 80 +coral3 205 91 69 +coral4 139 62 47 +cornflower blue 100 149 237 +CornflowerBlue 100 149 237 +cornsilk 255 248 220 +cornsilk1 255 248 220 +cornsilk2 238 232 205 +cornsilk3 205 200 177 +cornsilk4 139 136 120 +cyan 0 255 255 +cyan1 0 255 255 +cyan2 0 238 238 +cyan3 0 205 205 +cyan4 0 139 139 +dark blue 0 0 139 +dark cyan 0 139 139 +dark goldenrod 184 134 11 +dark gray 169 169 169 +dark green 0 100 0 +dark grey 169 169 169 +dark khaki 189 183 107 +dark magenta 139 0 139 +dark olive green 85 107 47 +dark orange 255 140 0 +dark orchid 153 50 204 +dark red 139 0 0 +dark salmon 233 150 122 +dark sea green 143 188 143 +dark slate blue 72 61 139 +dark slate gray 47 79 79 +dark slate grey 47 79 79 +dark turquoise 0 206 209 +dark violet 148 0 211 +DarkBlue 0 0 139 +DarkCyan 0 139 139 +DarkGoldenrod 184 134 11 +DarkGoldenrod1 255 185 15 +DarkGoldenrod2 238 173 14 +DarkGoldenrod3 205 149 12 +DarkGoldenrod4 139 101 8 +DarkGray 169 169 169 +DarkGreen 0 100 0 +DarkGrey 169 169 169 +DarkKhaki 189 183 107 +DarkMagenta 139 0 139 +DarkOliveGreen 85 107 47 +DarkOliveGreen1 202 255 112 +DarkOliveGreen2 188 238 104 +DarkOliveGreen3 162 205 90 +DarkOliveGreen4 110 139 61 +DarkOrange 255 140 0 +DarkOrange1 255 127 0 +DarkOrange2 238 118 0 +DarkOrange3 205 102 0 +DarkOrange4 139 69 0 +DarkOrchid 153 50 204 +DarkOrchid1 191 62 255 +DarkOrchid2 178 58 238 +DarkOrchid3 154 50 205 +DarkOrchid4 104 34 139 +DarkRed 139 0 0 +DarkSalmon 233 150 122 +DarkSeaGreen 143 188 143 +DarkSeaGreen1 193 255 193 +DarkSeaGreen2 180 238 180 +DarkSeaGreen3 155 205 155 +DarkSeaGreen4 105 139 105 +DarkSlateBlue 72 61 139 +DarkSlateGray 47 79 79 +DarkSlateGray1 151 255 255 +DarkSlateGray2 141 238 238 +DarkSlateGray3 121 205 205 +DarkSlateGray4 82 139 139 +DarkSlateGrey 47 79 79 +DarkTurquoise 0 206 209 +DarkViolet 148 0 211 +deep pink 255 20 147 +deep sky blue 0 191 255 +DeepPink 255 20 147 +DeepPink1 255 20 147 +DeepPink2 238 18 137 +DeepPink3 205 16 118 +DeepPink4 139 10 80 +DeepSkyBlue 0 191 255 +DeepSkyBlue1 0 191 255 +DeepSkyBlue2 0 178 238 +DeepSkyBlue3 0 154 205 +DeepSkyBlue4 0 104 139 +dim gray 105 105 105 +dim grey 105 105 105 +DimGray 105 105 105 +DimGrey 105 105 105 +dodger blue 30 144 255 +DodgerBlue 30 144 255 +DodgerBlue1 30 144 255 +DodgerBlue2 28 134 238 +DodgerBlue3 24 116 205 +DodgerBlue4 16 78 139 +firebrick 178 34 34 +firebrick1 255 48 48 +firebrick2 238 44 44 +firebrick3 205 38 38 +firebrick4 139 26 26 +floral white 255 250 240 +FloralWhite 255 250 240 +forest green 34 139 34 +ForestGreen 34 139 34 +gainsboro 220 220 220 +ghost white 248 248 255 +GhostWhite 248 248 255 +gold 255 215 0 +gold1 255 215 0 +gold2 238 201 0 +gold3 205 173 0 +gold4 139 117 0 +goldenrod 218 165 32 +goldenrod1 255 193 37 +goldenrod2 238 180 34 +goldenrod3 205 155 29 +goldenrod4 139 105 20 +gray 190 190 190 +gray0 0 0 0 +gray1 3 3 3 +gray2 5 5 5 +gray3 8 8 8 +gray4 10 10 10 +gray5 13 13 13 +gray6 15 15 15 +gray7 18 18 18 +gray8 20 20 20 +gray9 23 23 23 +gray10 26 26 26 +gray11 28 28 28 +gray12 31 31 31 +gray13 33 33 33 +gray14 36 36 36 +gray15 38 38 38 +gray16 41 41 41 +gray17 43 43 43 +gray18 46 46 46 +gray19 48 48 48 +gray20 51 51 51 +gray21 54 54 54 +gray22 56 56 56 +gray23 59 59 59 +gray24 61 61 61 +gray25 64 64 64 +gray26 66 66 66 +gray27 69 69 69 +gray28 71 71 71 +gray29 74 74 74 +gray30 77 77 77 +gray31 79 79 79 +gray32 82 82 82 +gray33 84 84 84 +gray34 87 87 87 +gray35 89 89 89 +gray36 92 92 92 +gray37 94 94 94 +gray38 97 97 97 +gray39 99 99 99 +gray40 102 102 102 +gray41 105 105 105 +gray42 107 107 107 +gray43 110 110 110 +gray44 112 112 112 +gray45 115 115 115 +gray46 117 117 117 +gray47 120 120 120 +gray48 122 122 122 +gray49 125 125 125 +gray50 127 127 127 +gray51 130 130 130 +gray52 133 133 133 +gray53 135 135 135 +gray54 138 138 138 +gray55 140 140 140 +gray56 143 143 143 +gray57 145 145 145 +gray58 148 148 148 +gray59 150 150 150 +gray60 153 153 153 +gray61 156 156 156 +gray62 158 158 158 +gray63 161 161 161 +gray64 163 163 163 +gray65 166 166 166 +gray66 168 168 168 +gray67 171 171 171 +gray68 173 173 173 +gray69 176 176 176 +gray70 179 179 179 +gray71 181 181 181 +gray72 184 184 184 +gray73 186 186 186 +gray74 189 189 189 +gray75 191 191 191 +gray76 194 194 194 +gray77 196 196 196 +gray78 199 199 199 +gray79 201 201 201 +gray80 204 204 204 +gray81 207 207 207 +gray82 209 209 209 +gray83 212 212 212 +gray84 214 214 214 +gray85 217 217 217 +gray86 219 219 219 +gray87 222 222 222 +gray88 224 224 224 +gray89 227 227 227 +gray90 229 229 229 +gray91 232 232 232 +gray92 235 235 235 +gray93 237 237 237 +gray94 240 240 240 +gray95 242 242 242 +gray96 245 245 245 +gray97 247 247 247 +gray98 250 250 250 +gray99 252 252 252 +gray100 255 255 255 +green 0 255 0 +green yellow 173 255 47 +green1 0 255 0 +green2 0 238 0 +green3 0 205 0 +green4 0 139 0 +GreenYellow 173 255 47 +grey 190 190 190 +grey0 0 0 0 +grey1 3 3 3 +grey2 5 5 5 +grey3 8 8 8 +grey4 10 10 10 +grey5 13 13 13 +grey6 15 15 15 +grey7 18 18 18 +grey8 20 20 20 +grey9 23 23 23 +grey10 26 26 26 +grey11 28 28 28 +grey12 31 31 31 +grey13 33 33 33 +grey14 36 36 36 +grey15 38 38 38 +grey16 41 41 41 +grey17 43 43 43 +grey18 46 46 46 +grey19 48 48 48 +grey20 51 51 51 +grey21 54 54 54 +grey22 56 56 56 +grey23 59 59 59 +grey24 61 61 61 +grey25 64 64 64 +grey26 66 66 66 +grey27 69 69 69 +grey28 71 71 71 +grey29 74 74 74 +grey30 77 77 77 +grey31 79 79 79 +grey32 82 82 82 +grey33 84 84 84 +grey34 87 87 87 +grey35 89 89 89 +grey36 92 92 92 +grey37 94 94 94 +grey38 97 97 97 +grey39 99 99 99 +grey40 102 102 102 +grey41 105 105 105 +grey42 107 107 107 +grey43 110 110 110 +grey44 112 112 112 +grey45 115 115 115 +grey46 117 117 117 +grey47 120 120 120 +grey48 122 122 122 +grey49 125 125 125 +grey50 127 127 127 +grey51 130 130 130 +grey52 133 133 133 +grey53 135 135 135 +grey54 138 138 138 +grey55 140 140 140 +grey56 143 143 143 +grey57 145 145 145 +grey58 148 148 148 +grey59 150 150 150 +grey60 153 153 153 +grey61 156 156 156 +grey62 158 158 158 +grey63 161 161 161 +grey64 163 163 163 +grey65 166 166 166 +grey66 168 168 168 +grey67 171 171 171 +grey68 173 173 173 +grey69 176 176 176 +grey70 179 179 179 +grey71 181 181 181 +grey72 184 184 184 +grey73 186 186 186 +grey74 189 189 189 +grey75 191 191 191 +grey76 194 194 194 +grey77 196 196 196 +grey78 199 199 199 +grey79 201 201 201 +grey80 204 204 204 +grey81 207 207 207 +grey82 209 209 209 +grey83 212 212 212 +grey84 214 214 214 +grey85 217 217 217 +grey86 219 219 219 +grey87 222 222 222 +grey88 224 224 224 +grey89 227 227 227 +grey90 229 229 229 +grey91 232 232 232 +grey92 235 235 235 +grey93 237 237 237 +grey94 240 240 240 +grey95 242 242 242 +grey96 245 245 245 +grey97 247 247 247 +grey98 250 250 250 +grey99 252 252 252 +grey100 255 255 255 +honeydew 240 255 240 +honeydew1 240 255 240 +honeydew2 224 238 224 +honeydew3 193 205 193 +honeydew4 131 139 131 +hot pink 255 105 180 +HotPink 255 105 180 +HotPink1 255 110 180 +HotPink2 238 106 167 +HotPink3 205 96 144 +HotPink4 139 58 98 +indian red 205 92 92 +IndianRed 205 92 92 +IndianRed1 255 106 106 +IndianRed2 238 99 99 +IndianRed3 205 85 85 +IndianRed4 139 58 58 +ivory 255 255 240 +ivory1 255 255 240 +ivory2 238 238 224 +ivory3 205 205 193 +ivory4 139 139 131 +khaki 240 230 140 +khaki1 255 246 143 +khaki2 238 230 133 +khaki3 205 198 115 +khaki4 139 134 78 +lavender 230 230 250 +lavender blush 255 240 245 +LavenderBlush 255 240 245 +LavenderBlush1 255 240 245 +LavenderBlush2 238 224 229 +LavenderBlush3 205 193 197 +LavenderBlush4 139 131 134 +lawn green 124 252 0 +LawnGreen 124 252 0 +lemon chiffon 255 250 205 +LemonChiffon 255 250 205 +LemonChiffon1 255 250 205 +LemonChiffon2 238 233 191 +LemonChiffon3 205 201 165 +LemonChiffon4 139 137 112 +light blue 173 216 230 +light coral 240 128 128 +light cyan 224 255 255 +light goldenrod 238 221 130 +light goldenrod yellow 250 250 210 +light gray 211 211 211 +light green 144 238 144 +light grey 211 211 211 +light pink 255 182 193 +light salmon 255 160 122 +light sea green 32 178 170 +light sky blue 135 206 250 +light slate blue 132 112 255 +light slate gray 119 136 153 +light slate grey 119 136 153 +light steel blue 176 196 222 +light yellow 255 255 224 +LightBlue 173 216 230 +LightBlue1 191 239 255 +LightBlue2 178 223 238 +LightBlue3 154 192 205 +LightBlue4 104 131 139 +LightCoral 240 128 128 +LightCyan 224 255 255 +LightCyan1 224 255 255 +LightCyan2 209 238 238 +LightCyan3 180 205 205 +LightCyan4 122 139 139 +LightGoldenrod 238 221 130 +LightGoldenrod1 255 236 139 +LightGoldenrod2 238 220 130 +LightGoldenrod3 205 190 112 +LightGoldenrod4 139 129 76 +LightGoldenrodYellow 250 250 210 +LightGray 211 211 211 +LightGreen 144 238 144 +LightGrey 211 211 211 +LightPink 255 182 193 +LightPink1 255 174 185 +LightPink2 238 162 173 +LightPink3 205 140 149 +LightPink4 139 95 101 +LightSalmon 255 160 122 +LightSalmon1 255 160 122 +LightSalmon2 238 149 114 +LightSalmon3 205 129 98 +LightSalmon4 139 87 66 +LightSeaGreen 32 178 170 +LightSkyBlue 135 206 250 +LightSkyBlue1 176 226 255 +LightSkyBlue2 164 211 238 +LightSkyBlue3 141 182 205 +LightSkyBlue4 96 123 139 +LightSlateBlue 132 112 255 +LightSlateGray 119 136 153 +LightSlateGrey 119 136 153 +LightSteelBlue 176 196 222 +LightSteelBlue1 202 225 255 +LightSteelBlue2 188 210 238 +LightSteelBlue3 162 181 205 +LightSteelBlue4 110 123 139 +LightYellow 255 255 224 +LightYellow1 255 255 224 +LightYellow2 238 238 209 +LightYellow3 205 205 180 +LightYellow4 139 139 122 +lime green 50 205 50 +LimeGreen 50 205 50 +linen 250 240 230 +magenta 255 0 255 +magenta1 255 0 255 +magenta2 238 0 238 +magenta3 205 0 205 +magenta4 139 0 139 +maroon 176 48 96 +maroon1 255 52 179 +maroon2 238 48 167 +maroon3 205 41 144 +maroon4 139 28 98 +medium aquamarine 102 205 170 +medium blue 0 0 205 +medium orchid 186 85 211 +medium purple 147 112 219 +medium sea green 60 179 113 +medium slate blue 123 104 238 +medium spring green 0 250 154 +medium turquoise 72 209 204 +medium violet red 199 21 133 +MediumAquamarine 102 205 170 +MediumBlue 0 0 205 +MediumOrchid 186 85 211 +MediumOrchid1 224 102 255 +MediumOrchid2 209 95 238 +MediumOrchid3 180 82 205 +MediumOrchid4 122 55 139 +MediumPurple 147 112 219 +MediumPurple1 171 130 255 +MediumPurple2 159 121 238 +MediumPurple3 137 104 205 +MediumPurple4 93 71 139 +MediumSeaGreen 60 179 113 +MediumSlateBlue 123 104 238 +MediumSpringGreen 0 250 154 +MediumTurquoise 72 209 204 +MediumVioletRed 199 21 133 +midnight blue 25 25 112 +MidnightBlue 25 25 112 +mint cream 245 255 250 +MintCream 245 255 250 +misty rose 255 228 225 +MistyRose 255 228 225 +MistyRose1 255 228 225 +MistyRose2 238 213 210 +MistyRose3 205 183 181 +MistyRose4 139 125 123 +moccasin 255 228 181 +navajo white 255 222 173 +NavajoWhite 255 222 173 +NavajoWhite1 255 222 173 +NavajoWhite2 238 207 161 +NavajoWhite3 205 179 139 +NavajoWhite4 139 121 94 +navy 0 0 128 +navy blue 0 0 128 +NavyBlue 0 0 128 +old lace 253 245 230 +OldLace 253 245 230 +olive drab 107 142 35 +OliveDrab 107 142 35 +OliveDrab1 192 255 62 +OliveDrab2 179 238 58 +OliveDrab3 154 205 50 +OliveDrab4 105 139 34 +orange 255 165 0 +orange red 255 69 0 +orange1 255 165 0 +orange2 238 154 0 +orange3 205 133 0 +orange4 139 90 0 +OrangeRed 255 69 0 +OrangeRed1 255 69 0 +OrangeRed2 238 64 0 +OrangeRed3 205 55 0 +OrangeRed4 139 37 0 +orchid 218 112 214 +orchid1 255 131 250 +orchid2 238 122 233 +orchid3 205 105 201 +orchid4 139 71 137 +pale goldenrod 238 232 170 +pale green 152 251 152 +pale turquoise 175 238 238 +pale violet red 219 112 147 +PaleGoldenrod 238 232 170 +PaleGreen 152 251 152 +PaleGreen1 154 255 154 +PaleGreen2 144 238 144 +PaleGreen3 124 205 124 +PaleGreen4 84 139 84 +PaleTurquoise 175 238 238 +PaleTurquoise1 187 255 255 +PaleTurquoise2 174 238 238 +PaleTurquoise3 150 205 205 +PaleTurquoise4 102 139 139 +PaleVioletRed 219 112 147 +PaleVioletRed1 255 130 171 +PaleVioletRed2 238 121 159 +PaleVioletRed3 205 104 127 +PaleVioletRed4 139 71 93 +papaya whip 255 239 213 +PapayaWhip 255 239 213 +peach puff 255 218 185 +PeachPuff 255 218 185 +PeachPuff1 255 218 185 +PeachPuff2 238 203 173 +PeachPuff3 205 175 149 +PeachPuff4 139 119 101 +peru 205 133 63 +pink 255 192 203 +pink1 255 181 197 +pink2 238 169 184 +pink3 205 145 158 +pink4 139 99 108 +plum 221 160 221 +plum1 255 187 255 +plum2 238 174 238 +plum3 205 150 205 +plum4 139 102 139 +powder blue 176 224 230 +PowderBlue 176 224 230 +purple 160 32 240 +purple1 155 48 255 +purple2 145 44 238 +purple3 125 38 205 +purple4 85 26 139 +red 255 0 0 +red1 255 0 0 +red2 238 0 0 +red3 205 0 0 +red4 139 0 0 +rosy brown 188 143 143 +RosyBrown 188 143 143 +RosyBrown1 255 193 193 +RosyBrown2 238 180 180 +RosyBrown3 205 155 155 +RosyBrown4 139 105 105 +royal blue 65 105 225 +RoyalBlue 65 105 225 +RoyalBlue1 72 118 255 +RoyalBlue2 67 110 238 +RoyalBlue3 58 95 205 +RoyalBlue4 39 64 139 +saddle brown 139 69 19 +SaddleBrown 139 69 19 +salmon 250 128 114 +salmon1 255 140 105 +salmon2 238 130 98 +salmon3 205 112 84 +salmon4 139 76 57 +sandy brown 244 164 96 +SandyBrown 244 164 96 +sea green 46 139 87 +SeaGreen 46 139 87 +SeaGreen1 84 255 159 +SeaGreen2 78 238 148 +SeaGreen3 67 205 128 +SeaGreen4 46 139 87 +seashell 255 245 238 +seashell1 255 245 238 +seashell2 238 229 222 +seashell3 205 197 191 +seashell4 139 134 130 +sienna 160 82 45 +sienna1 255 130 71 +sienna2 238 121 66 +sienna3 205 104 57 +sienna4 139 71 38 +sky blue 135 206 235 +SkyBlue 135 206 235 +SkyBlue1 135 206 255 +SkyBlue2 126 192 238 +SkyBlue3 108 166 205 +SkyBlue4 74 112 139 +slate blue 106 90 205 +slate gray 112 128 144 +slate grey 112 128 144 +SlateBlue 106 90 205 +SlateBlue1 131 111 255 +SlateBlue2 122 103 238 +SlateBlue3 105 89 205 +SlateBlue4 71 60 139 +SlateGray 112 128 144 +SlateGray1 198 226 255 +SlateGray2 185 211 238 +SlateGray3 159 182 205 +SlateGray4 108 123 139 +SlateGrey 112 128 144 +snow 255 250 250 +snow1 255 250 250 +snow2 238 233 233 +snow3 205 201 201 +snow4 139 137 137 +spring green 0 255 127 +SpringGreen 0 255 127 +SpringGreen1 0 255 127 +SpringGreen2 0 238 118 +SpringGreen3 0 205 102 +SpringGreen4 0 139 69 +steel blue 70 130 180 +SteelBlue 70 130 180 +SteelBlue1 99 184 255 +SteelBlue2 92 172 238 +SteelBlue3 79 148 205 +SteelBlue4 54 100 139 +tan 210 180 140 +tan1 255 165 79 +tan2 238 154 73 +tan3 205 133 63 +tan4 139 90 43 +thistle 216 191 216 +thistle1 255 225 255 +thistle2 238 210 238 +thistle3 205 181 205 +thistle4 139 123 139 +tomato 255 99 71 +tomato1 255 99 71 +tomato2 238 92 66 +tomato3 205 79 57 +tomato4 139 54 38 +turquoise 64 224 208 +turquoise1 0 245 255 +turquoise2 0 229 238 +turquoise3 0 197 205 +turquoise4 0 134 139 +violet 238 130 238 +violet red 208 32 144 +VioletRed 208 32 144 +VioletRed1 255 62 150 +VioletRed2 238 58 140 +VioletRed3 205 50 120 +VioletRed4 139 34 82 +wheat 245 222 179 +wheat1 255 231 186 +wheat2 238 216 174 +wheat3 205 186 150 +wheat4 139 126 102 +white 255 255 255 +white smoke 245 245 245 +WhiteSmoke 245 245 245 +yellow 255 255 0 +yellow green 154 205 50 +yellow1 255 255 0 +yellow2 238 238 0 +yellow3 205 205 0 +yellow4 139 139 0 +YellowGreen 154 205 50 +.DE .SH "PORTABILITY ISSUES" - .TP \fBMac OS X\fR +. On Mac OS X, the following additional system colors are available (note that the actual color values depend on the currently active OS theme, and typically many of these will in fact be patterns rather than pure colors): .RS -.CS -systemTransparent -systemBlack -systemWhite -systemHighlight -systemPrimaryHighlightColor -systemHighlightSecondary -systemSecondaryHighlightColor -systemHighlightAlternate -systemAlternatePrimaryHighlightColor -systemHighlightText -systemDialogBackgroundActive -systemDialogBackgroundInactive +.DS +systemActiveAreaFill +systemAlertActiveText systemAlertBackgroundActive systemAlertBackgroundInactive -systemModelessDialogBackgroundActive -systemModelessDialogBackgroundInactive -systemUtilityWindowBackgroundActive -systemUtilityWindowBackgroundInactive -systemListViewSortColumnBackground -systemListViewBackground -systemIconLabelBackground -systemListViewSeparator -systemChasingArrows -systemDragHilite -systemWindowBody -systemDocumentWindowBackground -systemFinderWindowBackground -systemScrollBarDelimiterActive -systemScrollBarDelimiterInactive -systemFocusHighlight -systemPopupArrowActive -systemPopupArrowPressed -systemPopupArrowInactive +systemAlertInactiveText +systemAlternatePrimaryHighlightColor systemAppleGuideCoachmark -systemIconLabelBackgroundSelected -systemStaticAreaFill -systemActiveAreaFill -systemButtonFrame -systemButtonFrameActive -systemButtonFrameInactive +systemBevelActiveDark +systemBevelActiveLight +systemBevelButtonActiveText +systemBevelButtonInactiveText +systemBevelButtonPressedText +systemBevelButtonStickyActiveText +systemBevelButtonStickyInactiveText +systemBevelInactiveDark +systemBevelInactiveLight +systemBlack +systemBlackText +systemButtonActiveDarkHighlight +systemButtonActiveDarkShadow +systemButtonActiveLightHighlight +systemButtonActiveLightShadow systemButtonFace systemButtonFaceActive systemButtonFaceInactive systemButtonFacePressed -systemButtonActiveDarkShadow -systemButtonActiveDarkHighlight -systemButtonActiveLightShadow -systemButtonActiveLightHighlight -systemButtonInactiveDarkShadow +systemButtonFrame +systemButtonFrameActive +systemButtonFrameInactive systemButtonInactiveDarkHighlight -systemButtonInactiveLightShadow +systemButtonInactiveDarkShadow systemButtonInactiveLightHighlight -systemButtonPressedDarkShadow +systemButtonInactiveLightShadow systemButtonPressedDarkHighlight -systemButtonPressedLightShadow +systemButtonPressedDarkShadow systemButtonPressedLightHighlight -systemBevelActiveLight -systemBevelActiveDark -systemBevelInactiveLight -systemBevelInactiveDark -systemNotificationWindowBackground -systemMovableModalBackground -systemSheetBackground -systemSheetBackgroundOpaque +systemButtonPressedLightShadow +systemButtonText +systemChasingArrows +systemDialogActiveText +systemDialogBackgroundActive +systemDialogBackgroundInactive +systemDialogInactiveText +systemDocumentWindowBackground +systemDocumentWindowTitleActiveText +systemDocumentWindowTitleInactiveText +systemDragHilite systemDrawerBackground -systemToolbarBackground -systemSheetBackgroundTransparent +systemFinderWindowBackground +systemFocusHighlight +systemHighlight +systemHighlightAlternate +systemHighlightSecondary +systemHighlightText +systemIconLabelBackground +systemIconLabelBackgroundSelected +systemIconLabelSelectedText +systemIconLabelText +systemListViewBackground +systemListViewColumnDivider +systemListViewEvenRowBackground +systemListViewOddRowBackground +systemListViewSeparator +systemListViewSortColumnBackground +systemListViewText +systemListViewWindowHeaderBackground systemMenu -systemMenuBackground systemMenuActive +systemMenuActiveText +systemMenuBackground systemMenuBackgroundSelected -systemListViewOddRowBackground -systemListViewEvenRowBackground -systemListViewColumnDivider -systemTabPaneBackground -systemPlacardBackground -systemWindowHeaderBackground -systemListViewWindowHeaderBackground -systemSecondaryGroupBoxBackground +systemMenuDisabled +systemMenuItemActiveText +systemMenuItemDisabledText +systemMenuItemSelectedText +systemMenuText systemMetalBackground -systemBlackText -systemWhiteText -systemDialogActiveText -systemDialogInactiveText -systemAlertActiveText -systemAlertInactiveText systemModelessDialogActiveText +systemModelessDialogBackgroundActive +systemModelessDialogBackgroundInactive systemModelessDialogInactiveText -systemWindowHeaderActiveText -systemWindowHeaderInactiveText +systemMovableModalBackground +systemMovableModalWindowTitleActiveText +systemMovableModalWindowTitleInactiveText +systemNotificationText +systemNotificationWindowBackground systemPlacardActiveText +systemPlacardBackground systemPlacardInactiveText systemPlacardPressedText -systemButtonText -systemPushButtonActiveText -systemPushButtonInactiveText -systemPushButtonPressedText -systemBevelButtonActiveText -systemBevelButtonInactiveText -systemBevelButtonPressedText +systemPopupArrowActive +systemPopupArrowInactive +systemPopupArrowPressed systemPopupButtonActiveText systemPopupButtonInactiveText systemPopupButtonPressedText -systemIconLabelText -systemListViewText -systemDocumentWindowTitleActiveText -systemDocumentWindowTitleInactiveText -systemMovableModalWindowTitleActiveText -systemMovableModalWindowTitleInactiveText -systemUtilityWindowTitleActiveText -systemUtilityWindowTitleInactiveText +systemPopupLabelActiveText +systemPopupLabelInactiveText systemPopupWindowTitleActiveText systemPopupWindowTitleInactiveText +systemPrimaryHighlightColor +systemPushButtonActiveText +systemPushButtonInactiveText +systemPushButtonPressedText systemRootMenuActiveText -systemRootMenuSelectedText systemRootMenuDisabledText -systemMenuText -systemMenuItemActiveText -systemMenuActiveText -systemMenuItemSelectedText -systemMenuDisabled -systemMenuItemDisabledText -systemPopupLabelActiveText -systemPopupLabelInactiveText +systemRootMenuSelectedText +systemScrollBarDelimiterActive +systemScrollBarDelimiterInactive +systemSecondaryGroupBoxBackground +systemSecondaryHighlightColor +systemSheetBackground +systemSheetBackgroundOpaque +systemSheetBackgroundTransparent +systemStaticAreaFill +systemSystemDetailText systemTabFrontActiveText -systemTabNonFrontActiveText -systemTabNonFrontPressedText systemTabFrontInactiveText +systemTabNonFrontActiveText systemTabNonFrontInactiveText -systemIconLabelSelectedText -systemBevelButtonStickyActiveText -systemBevelButtonStickyInactiveText -systemNotificationText -systemSystemDetailText -.CE +systemTabNonFrontPressedText +systemTabPaneBackground +systemToolbarBackground +systemTransparent +systemUtilityWindowBackgroundActive +systemUtilityWindowBackgroundInactive +systemUtilityWindowTitleActiveText +systemUtilityWindowTitleInactiveText +systemWhite +systemWhiteText +systemWindowBody +systemWindowHeaderActiveText +systemWindowHeaderBackground +systemWindowHeaderInactiveText +.DE +.RE +.TP +\fBWindows\fR +. +On Windows, the following additional system colors are available +(note that the actual color values depend on the currently active OS theme): +.RS +.DS +.ta 6c +3dDarkShadow Highlight +3dLight HighlightText +ActiveBorder InactiveBorder +ActiveCaption InactiveCaption +AppWorkspace InactiveCaptionText +Background InfoBackground +ButtonFace InfoText +ButtonHighlight Menu +ButtonShadow MenuText +ButtonText Scrollbar +CaptionText Window +DisabledText WindowFrame +GrayText WindowText +.DE .RE - +.SH "SEE ALSO" +options(n), Tk_GetColor(3) .SH KEYWORDS color, option diff --git a/doc/console.n b/doc/console.n index c6ea1d1..8e0691c 100644 --- a/doc/console.n +++ b/doc/console.n @@ -13,7 +13,6 @@ 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 @@ -22,7 +21,13 @@ 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 (or the \fIConsole\fR resource on Macintosh systems.) +the Tk library. Except for TkAqua, this command is not available when +Tk is loaded into a tclsh interpreter with +.QW "\fBpackage require Tk\fR" , +as a conventional terminal is expected to be present in that case. +In TkAqua, this command is ony available when stdin is \fB/dev/null\fR +(as is the case e.g. when the application embedding Tk is started +from the Mac OS X Finder). .PP .TP \fBconsole eval \fIscript\fR @@ -130,9 +135,7 @@ often has the following code fragment in it so output produced by .CS catch {\fBconsole show\fR} .CE - -.SH KEYWORDS -console, interpreter, window, interactive, output channels - .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 diff --git a/doc/cursors.n b/doc/cursors.n index 06a0208..8bc2a8f 100644 --- a/doc/cursors.n +++ b/doc/cursors.n @@ -11,10 +11,9 @@ .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 +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 @@ -61,6 +60,7 @@ lr_angle man middlebutton mouse +none pencil pirate plus @@ -96,9 +96,9 @@ 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: @@ -110,6 +110,7 @@ crosshair fleur ibeam icon +none sb_h_double_arrow sb_v_double_arrow watch @@ -127,9 +128,7 @@ size_we uparrow wait .CE -The \fBno\fR cursor can be specified to eliminate the cursor. .RE - .TP \fBMac OS X\fR On Mac OS X systems, the following cursors are mapped to native cursors: @@ -139,6 +138,7 @@ arrow cross crosshair ibeam +none plus watch xterm @@ -159,7 +159,6 @@ resizeleftright resizeup resizedown resizeupdown -none notallowed poof countinguphand @@ -168,6 +167,5 @@ countingupanddownhand spinning .CE .RE - .SH KEYWORDS cursor, option diff --git a/doc/destroy.n b/doc/destroy.n index 65b0caa..93aedd5 100644 --- a/doc/destroy.n +++ b/doc/destroy.n @@ -14,19 +14,18 @@ destroy \- Destroy one or more windows .SH SYNOPSIS \fBdestroy \fR?\fIwindow window ...\fR? .BE - .SH DESCRIPTION -.VS .PP This command deletes the windows given by the \fIwindow\fR arguments, plus all of their descendants. -If a \fIwindow\fR ``.'' is deleted then the entire application -will be destroyed. +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. -.VE .SH EXAMPLE Destroy all checkbuttons that are direct children of the given widget: .CS diff --git a/doc/dialog.n b/doc/dialog.n index 1f91b3f..e72cbac 100644 --- a/doc/dialog.n +++ b/doc/dialog.n @@ -39,7 +39,7 @@ If this is an empty string then no bitmap is displayed in the dialog. 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 won't be any default +If less than zero or an empty string then there will not be any default button. .TP \fIstring\fR @@ -53,14 +53,14 @@ 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. +of the buttons, then \-1 is returned. .PP While waiting for the user to respond, \fBtk_dialog\fR sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. .SH EXAMPLE .CS -set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \\ +set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \e questhead 0 Yes No "I'm not sure"] .CE diff --git a/doc/entry.n b/doc/entry.n index 5a34b47..58c5d64 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -25,37 +25,31 @@ entry \- Create and manipulate entry widgets \-highlightcolor \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" -.VS 8.4 .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. -.VE 8.4 -.VS 8.3 .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fBvalidateCommand\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. -.VE -.VS 8.4 .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. -.VE .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 ``*''. +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. -.VS 8.4 .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 @@ -65,9 +59,7 @@ 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. -.VE 8.4 -.VS 8.3 +\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. @@ -81,14 +73,12 @@ the valid Tcl boolean equivalent) then it means you reject the new edition and it will not occur and the \fBinvalidCommand\fR will be evaluated if it is set. If it returns 1, then the new edition occurs. See \fBValidation\fR below for more information. -.VE .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 @@ -122,7 +112,6 @@ the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). They also support scanning, as described below. .SH VALIDATION -.VS 8.3 .PP Validation works by setting the \fBvalidateCommand\fR option to a script which will be evaluated according to the \fBvalidate\fR @@ -149,9 +138,9 @@ 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. +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. +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 @@ -188,23 +177,23 @@ validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the \fBvalidate\fR option set, you should include the command .CS -after idle {%W config -validate %v} +after idle {%W config \-validate %v} .CE in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you were editing the entry widget from). It is also recommended to not set an associated \fBtextVariable\fR during validation, as that can cause the entry widget to become out of sync with the \fBtextVariable\fR. -.VE .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 option \fR?\fIarg arg ...\fR? +\fIpathName subcommand \fR?\fIarg arg ...\fR? .CE -\fIOption\fR and the \fIarg\fRs +\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 @@ -229,22 +218,27 @@ 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 isn't in the entry window. +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 isn't in the +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, ``\fB@0\fR'' indicates the left-most character in the -window. +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. ``\fBe\fR'' -or ``\fBsel.f\fR''. In general, out-of-range indices are automatically -rounded to the nearest legal value. +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 @@ -283,7 +277,7 @@ 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 isn't specified it defaults to \fIfirst\fR+1, +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 @@ -333,19 +327,19 @@ Locate the end of the selection nearest to the character given by (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 -isn't currently in the entry, then a new selection is created to +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 isn't in this widget then the command has no effect. +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. Doesn't change the selection. +given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR @@ -369,18 +363,16 @@ 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 isn't in this widget then a new selection is +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 -.VS 8.3 .TP \fIpathName \fBvalidate\fR This command is used to force an evaluation of the \fBvalidateCommand\fR independent of the conditions specified by the \fBvalidate\fR option. This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR. It returns 0 or 1. -.VE .TP \fIpathName \fBxview \fIargs\fR This command is used to query and change the horizontal position of the @@ -423,10 +415,11 @@ become visible. .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for entries that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. +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 @@ -487,7 +480,7 @@ 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 don't affect the current selection. +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. @@ -531,14 +524,13 @@ 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 -.VS 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. -.VE .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 diff --git a/doc/event.n b/doc/event.n index 49e04d3..69f336a 100644 --- a/doc/event.n +++ b/doc/event.n @@ -14,7 +14,6 @@ event \- Miscellaneous event facilities: define virtual events and generate even .SH SYNOPSIS \fBevent\fI option \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBevent\fR command provides several facilities for dealing with @@ -49,10 +48,8 @@ trigger anymore. 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 -.VS 8.3 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. -.VE \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 @@ -62,14 +59,14 @@ 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 -EVENT FIELDS below. If the \fB\-when\fR option is not specified, the +\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?<<\fIvirtual\fB>>\fR? +\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. @@ -77,11 +74,17 @@ 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 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 ``%'' expansions -allowed in binding scripts for the \fBbind\fR command. +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, @@ -105,6 +108,13 @@ Corresponds to the \fB%b\fR substitution for binding scripts. \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. +.VS 8.5 +.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. +.VE 8.5 .TP \fB\-delta\fI number\fR \fINumber\fR must be an integer; it specifies the \fIdelta\fR field @@ -112,7 +122,7 @@ 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 +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. @@ -123,10 +133,10 @@ and must be one of the following: .RS .DS .ta 6c -\fBNotifyAncestor NotifyNonlinearVirtual -NotifyDetailNone NotifyPointer -NotifyInferior NotifyPointerRoot -NotifyNonlinear NotifyVirtual\fR +\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. @@ -297,6 +307,74 @@ for binding scripts. 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" +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<<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<<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. +.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<<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<<PrevWindow>>\fR +Traverse to the previous window. +.TP +\fB<<Redo>>\fR +Redo one undone action. +.TP +\fB<<Undo>>\fR +Undo the last action. .SH "VIRTUAL EVENT EXAMPLES" .PP In order for a virtual event binding to trigger, two things must diff --git a/doc/focus.n b/doc/focus.n index d37697a..f37e1cd 100644 --- a/doc/focus.n +++ b/doc/focus.n @@ -67,7 +67,7 @@ displays. 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 doesn't currently have the input focus on +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. @@ -75,12 +75,12 @@ 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 isn't in this +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 doesn't currently have the input focus for the display. +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 @@ -97,7 +97,7 @@ 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 doesn't actually +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 @@ -110,11 +110,11 @@ 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 +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} { @@ -122,7 +122,7 @@ bind .before <Tab> { break } } -bind .after <Shift-Tab> { +bind .after <Shift\-Tab> { if {!$traverseToMiddle} { \fBfocus\fR .before break diff --git a/doc/focusNext.n b/doc/focusNext.n index 1279f20..ede496f 100644 --- a/doc/focusNext.n +++ b/doc/focusNext.n @@ -22,8 +22,9 @@ tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for manag .SH DESCRIPTION .PP \fBtk_focusNext\fR is a utility procedure used for keyboard traversal. -It returns the ``next'' window after \fIwindow\fR in focus order. -The focus order is determined by +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. @@ -50,7 +51,7 @@ 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'll have +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. @@ -21,28 +21,34 @@ 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? +\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 pointsizes. -\fIfont\fR is a font description; see FONT DESCRIPTIONS below. If the +\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 FONT OPTIONS below for a list of the possible attributes. +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? +\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 +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 FONT OPTIONS below for a list of the +new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? @@ -51,13 +57,13 @@ 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 FONT OPTIONS below for a list of the possible +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 won't actually be deleted until all the instances are +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 @@ -65,18 +71,21 @@ 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 +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 +\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 FONT DESCRIPTIONS below. If the \fIwindow\fR argument is omitted, it +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 ``f''. If the string contains newlines or tabs, +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 @@ -84,11 +93,12 @@ string. . 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 FONT DESCRIPTIONS below. If the \fIwindow\fR argument is +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 FONT METRICS below for a list -of the possible metrics. +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. @@ -98,7 +108,7 @@ 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 +[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 @@ -110,48 +120,56 @@ font will be substituted automatically. [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 ``\fB*\fR'' +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 PLATFORM-SPECIFIC issues for a list of the system fonts. -.VS 8.0 br +name. See \fBPLATFORM-SPECIFIC\fR issues 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 FONT OPTIONS below. Any additional optional +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 bold roman italic -underline overstrike\fR +\fBnormal\fR \fBbold\fR \fBroman\fR \fBitalic\fR +\fBunderline\fR \fBoverstrike\fR .DE .RE -.TP +.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 ``\fB*\fR'' character may be used to skip individual fields that the -user does not care about. There must be exactly one ``\fB*\fR'' for each -field skipped, except that a ``\fB*\fR'' at the end of the XLFD skips any -remaining fields; the shortest valid XLFD is simply ``\fB*\fR'', signifying -all fields as defaults. Any fields that were skipped are given default +\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 ``point'' +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. -.VE .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 FONT OPTIONS below. +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. @@ -161,22 +179,26 @@ 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. +an error is generated. .SH "FONT METRICS" . 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 ``baseline'' of a font is the -horizontal line where the bottom of most letters line up; certain letters, -such as lower-case ``g'' stick below the baseline. +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 +\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. @@ -190,29 +212,36 @@ above the baseline line plus the descent below the baseline. .TP \fB\-fixed \0\fR . -Returns a boolean flag that is ``\fB1\fR'' if this is a fixed-width font, +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 ``\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 +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" 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 +\fB\-family \fIname\fR . The case-insensitive font family name. Tk guarantees to support the font -families named \fBCourier\fR (a monospaced ``typewriter'' font), \fBTimes\fR -(a serifed ``newspaper'' font), and \fBHelvetica\fR (a sans-serif -``European'' font). The most closely matching native font family will +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 +display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. -.VS .TP \fB\-size \fIsize\fR . @@ -221,7 +250,7 @@ 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. +size will be chosen. .RS .PP Sizes should normally be specified in points so the application will remain @@ -232,9 +261,8 @@ 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 -.VE .TP -\fB\-weight \fIweight\fR +\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 @@ -244,7 +272,7 @@ be chosen. The default weight is \fBnormal\fR. \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 +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. @@ -253,46 +281,112 @@ The default slant is \fBroman\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 +\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 "PLATFORM-SPECIFIC ISSUES" +.SH "STANDARD FONTS" .LP -The following named system fonts are supported: -.RS -.TP -X Windows: +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 -MS Windows: +\fBMS Windows\fR +The following fonts are supported, and are mapped to the user's +style defaults. +.RS .DS .ta 3c 6c -\fBsystem ansi device -systemfixed ansifixed oemfixed\fR +\fBsystem\fR \fBansi\fR \fBdevice\fR +\fBsystemfixed\fR \fBansifixed\fR \fBoemfixed\fR .DE +.RE .TP -Mac OS X: +\fBMac OS X\fR +The following fonts are supported, and are mapped to the user's +style defaults. +.RS .DS .ta 3c 6c -\fBsystem application menu\fR +\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 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 +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 {} \\ - "This is a simple sampler\\n" f$count - set w [\fBfont measure\fR [.t cget -font] ${family}:] +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 + .t configure \-tabs $tabwidth } } .CE diff --git a/doc/frame.n b/doc/frame.n index ac03de9..208e414 100644 --- a/doc/frame.n +++ b/doc/frame.n @@ -52,11 +52,16 @@ 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. +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. @@ -66,11 +71,13 @@ The \fBvisual\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. +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 @@ -86,7 +93,6 @@ 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 @@ -120,14 +126,11 @@ 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) - +labelframe(n), toplevel(n), ttk::frame(n) .SH KEYWORDS frame, widget diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index b13194b..8162078 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -11,11 +11,11 @@ .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? -.br \fBtk_getSaveFile \fR?\fIoption value ...\fR? +.fi .BE - .SH DESCRIPTION .PP The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a @@ -35,16 +35,20 @@ whether the existing file should be overwritten or not. The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: .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 the Macintosh platform, which +any case. This option is ignored on Mac OS X, which does not require extensions to filenames, -.VS 8.4 and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. -.VE 8.4 .TP \fB\-filetypes\fR \fIfilePatternList\fR If a \fBFile types\fR listbox exists in the file dialog on the particular @@ -61,38 +65,42 @@ Specifies that the files in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, then the files in the current working directory are displayed. If the parameter specifies a relative path, the return value will convert the -relative path to an absolute path. This option may not always work on -the Macintosh. This is not a bug. Rather, the \fIGeneral Controls\fR -control panel on the Mac allows the end user to override the -application default directory. +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. This -option is ignored on the Macintosh platform. -.TP -\fB\-multiple\fR \fIboolean\fR -Allows the user to choose multiple files from the Open dialog. -On the Macintosh, this is only available when Navigation Services are -installed. +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 the Macintosh, and only when Navigation -Services are installed. +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. +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 @@ -111,8 +119,8 @@ 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 patterns for one -type of file is necessary on the Macintosh platform only. +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 @@ -122,7 +130,7 @@ 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 EITHER have a \fB\.gif\fR +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 @@ -131,20 +139,29 @@ 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 platforms, extensions are +glob-style pattern matching. On the Windows platform, extensions are matched by the underlying operating system. The types of possible -extensions are: (1) the special extension * matches any -file; (2) the special extension "" matches any files that -do not have an extension (i.e., the filename contains no full stop -character); (3) any character string that does not contain any wild -card characters (* and ?). +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 *. Extensions -without a full stop character (e.g. ~) are allowed but may not -work on all platforms. - +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 .CS set types { @@ -155,15 +172,13 @@ set types { {{GIF Files} {} GIFF} {{All Files} * } } -set filename [tk_getOpenFile -filetypes $types] +set filename [tk_getOpenFile \-filetypes $types] if {$filename != ""} { # Open the file ... } .CE - .SH "SEE ALSO" tk_chooseDirectory - .SH KEYWORDS file selection dialog @@ -30,8 +30,9 @@ 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 ``owns'' the pointer: +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 @@ -109,7 +110,7 @@ events and not providing any mechanism for releasing the grab). Take .PP It took an incredibly complex and gross implementation to produce the simple grab effect described above. -Given the current implementation, it isn't safe for applications +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, @@ -118,7 +119,7 @@ things will probably break. 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 doesn't exist. +processes, this restriction does not exist. .SH EXAMPLE 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 @@ -5,7 +5,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH grid n 8.4 Tk "Tk Built-In Commands" +.TH grid n 8.5 Tk "Tk Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -13,7 +13,6 @@ 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 @@ -25,9 +24,16 @@ on the \fIoption\fR argument: \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.\fP) or one of the characters \fBx\fP or \fB^\fP +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. +.VS 8.5 +.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. +.VE 8.5 .TP \fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? With no arguments, @@ -35,71 +41,77 @@ 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\fP and \fIrow\fP is specified on +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\fP and \fIrow\fP +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\fP column of the -geometry master, \fImaster\fP. -.VS 8.4 -The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP -and \fB-pad\fP. -.VE 8.4 -If one or more options are provided, then \fIindex\fP may be given as +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. -The \fB\-minsize\fP option sets the minimum size, in screen units, +.VS 8.5 +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. +.VE 8.5 +The \fB\-minsize\fR option sets the minimum size, in screen units, that will be permitted for this column. -The \fB\-weight\fP option (an integer value) +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. -.VS 8.4 -The \fB-uniform\fP option, when a non-empty value is supplied, places -the column in a \fIuniform group\fP with other columns that have the -same value for \fB-uniform\fP. The space for columns belonging to a +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\fP values. See +proportion to their \fB\-weight\fR values. See \fBTHE GRID ALGORITHM\fR below for further details. -.VE 8.4 -The \fB-pad\fP option specifies the number of screen units that will be +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 "-option value" pairs. +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\-\fP, \fBx\fP and \fB^\fP, +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\fP, as described in the \fBRELATIVE PLACEMENT\fR +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\fPth column in the grid. +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 \fIgrid\fP, or column "0" if it is the first slave. For each -\fBx\fP that immediately precedes the \fIslave\fP, the column position -is incremented by one. Thus the \fBx\fP represents a blank column +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\fP columns in the grid. +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\-\fP, in which case the columnspan is incremented once for each immediately -following \fB\-\fP. +\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 @@ -136,31 +148,34 @@ 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\fPth row in the grid. +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\fP, or the first unoccupied row if this is the first slave. +call to \fBgrid\fR, or the first unoccupied row if this is the first slave. .TP \fB\-rowspan \fIn\fR -Insert the slave so that it occupies \fIn\fP rows in the grid. -The default is one row. If the next \fBgrid\fP command contains -\fB^\fP characters instead of \fIslaves\fP that line up with the columns -of this \fIslave\fP, then the \fBrowspan\fP of this \fIslave\fP is +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\fP, \fBs\fP, \fBe\fP or \fBw\fP. +\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 "stick" to. If both \fBn\fP and \fBs\fP (or -\fBe\fP and \fBw\fP) are specified, the slave will be stretched to fill the entire -height (or width) of its cavity. The \fBsticky\fP option subsumes the -combination of \fB\-anchor\fP and \fB\-fill\fP that is used by \fBpack\fP. -The default is \fB{}\fP, which causes the slave to be centered in its cavity, -at its requested size. +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 \fBsticky\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 @@ -179,13 +194,15 @@ default settings are used. 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 ``\fB\-in \fImaster\fR'' where -\fImaster\fR is the slave's master. +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\fP and \fIy\fP values in screen units relative to the master window, -the column and row number at that \fIx\fP and \fIy\fP location is returned. -For locations that are above or to the left of the grid, \fB-1\fP is returned. +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 @@ -200,38 +217,42 @@ 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\fP row of the -geometry master, \fImaster\fP. -.VS 8.4 -The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP -and \fB-pad\fP. -.VE 8.4 -If one or more options are provided, then \fIindex\fP may be given as +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. -The \fB\-minsize\fP option sets the minimum size, in screen units, +.VS 8.5 +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. +.VE 8.5 +The \fB\-minsize\fR option sets the minimum size, in screen units, that will be permitted for this row. -The \fB\-weight\fP option (an integer value) +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. -.VS 8.4 -The \fB-uniform\fP option, when a non-empty value is supplied, places -the row in a \fIuniform group\fP with other rows that have the -same value for \fB-uniform\fP. The space for rows belonging to a +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\fP values. See +proportion to their \fB\-weight\fR values. See \fBTHE GRID ALGORITHM\fR below for further details. -.VE 8.4 -The \fB-pad\fP option specifies the number of screen units that will be +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 "-option value" pairs. +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 @@ -243,48 +264,48 @@ 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\fP. -The size is determined either by the \fIslave\fP occupying the largest -row or column, or the largest column or row with a \fBminsize\fP, -\fBweight\fP, or \fBpad\fP that is non-zero. +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 \fBminsize\fR, +\fBweight\fR, or \fBpad\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\fP can be either \fB\-row\fP or \fB\-column\fP which -causes only the slaves in the row (or column) specified by \fIvalue\fP +\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\fP command contains a limited set of capabilities that +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\fP, +When no column or row information is specified for a \fIslave\fR, default values are chosen for -\fBcolumn\fP, \fBrow\fP, \fBcolumnspan\fP and \fBrowspan\fP -at the time the \fIslave\fP is managed. The values are chosen -based upon the current layout of the grid, the position of the \fIslave\fP -relative to other \fIslave\fPs in the same grid command, and the presence -of the characters \fB\-\fP, \fBx\fP, and \fB^\fP in \fBgrid\fP -command where \fIslave\fP names are normally expected. +\fBcolumn\fR, \fBrow\fR, \fBcolumnspan\fR and \fBrowspan\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\-\fP -This increases the columnspan of the \fIslave\fP to the left. Several -\fB\-\fP's in a row will successively increase the columnspan. A \fB\-\fP -may not follow a \fB^\fP or a \fBx\fP, nor may it be the first \fIslave\fP +\fB\-\fR +This increases the columnspan of the \fIslave\fR to the left. Several +\fB\-\fR's in a row will successively increase the columnspan. 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\fP -This leaves an empty column between the \fIslave\fP on the left and -the \fIslave\fP on the right. +\fBx\fR +This leaves an empty column between the \fIslave\fR on the left and +the \fIslave\fR on the right. .TP -\fB^\fP -This extends the \fBrowspan\fP of the \fIslave\fP above the \fB^\fP's -in the grid. The number of \fB^\fP's in a row must match the number of -columns spanned by the \fIslave\fP above it. +\fB^\fR +This extends the \fBrowspan\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 @@ -296,46 +317,49 @@ 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\fP flag. +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 columnspan and rowspan values are one, and computes the nominal size of each row or column to be either the -\fIminsize\fP for that row or column, or the sum of the \fIpad\fPding +\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 rowspans or columnspans 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\fP. For 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\fP will have exactly the same -size as any other row or column configured with \fB-weight 1 -uniform -a\fP. 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\fP. +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\fP for some constant \fIk\fP. The constant -\fIk\fP is chosen so that no row or column becomes smaller than its +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 +.VS 8.5 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 centered within its master. +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 -clipped on the bottom and right. +placed and clipped according to the \fIanchor\fR value. +.VE 8.5 .SH "GEOMETRY PROPAGATION" .PP The grid geometry manager normally computes how large a master must be to @@ -357,19 +381,19 @@ The master for each slave must either be 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\fP must have the same master. +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 hasn't been managed correctly. +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\fP command is based on ideas taken from the \fIGridBag\fP +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 @@ -378,27 +402,30 @@ A toplevel window containing a text widget and two scrollbars: # 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 xview} +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 0 \-weight 1 -\fBgrid columnconfigure\fR .t 0 \-weight 1 +\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 "natural" widths: +Three widgets of equal width, despite their different +.QW natural +widths: .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 . {0 1 2} \-uniform allTheSame +\fBgrid columnconfigure\fR . "all" \-uniform allTheSame .CE - .SH "SEE ALSO" pack(n), place(n) - .SH KEYWORDS geometry manager, location, grid, cell, propagation, size, pack diff --git a/doc/image.n b/doc/image.n index a93ffc1..e536916 100644 --- a/doc/image.n +++ b/doc/image.n @@ -43,7 +43,7 @@ name wisely. It is recommended to use a separate namespace for image names \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 won't actually be deleted until all of the instances +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. diff --git a/doc/label.n b/doc/label.n index 1aa5ee1..ef121cb 100644 --- a/doc/label.n +++ b/doc/label.n @@ -29,7 +29,7 @@ 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 isn't specified, the label's desired height is computed +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, @@ -44,10 +44,9 @@ 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 isn't specified, the label's desired width is computed +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 @@ -69,7 +68,6 @@ one of the characters may optionally be underlined using the \fBunderline\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 @@ -102,11 +100,27 @@ 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 +.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 diff --git a/doc/labelframe.n b/doc/labelframe.n index 2654fe8..70d04cb 100644 --- a/doc/labelframe.n +++ b/doc/labelframe.n @@ -44,15 +44,6 @@ If the \fBcolormap\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. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. @@ -83,7 +74,6 @@ 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 @@ -131,14 +121,51 @@ 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 +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 -.SH "SEE ALSO" -frame(n), label(n) + 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 diff --git a/doc/listbox.n b/doc/listbox.n index e287b09..341ce9a 100644 --- a/doc/listbox.n +++ b/doc/listbox.n @@ -14,24 +14,20 @@ listbox \- Create and manipulate listbox widgets .SH SYNOPSIS \fBlistbox\fR \fIpathName \fR?\fIoptions\fR? .SO -\-activestyle \-height \-selectforeground -\-background \-highlightbackground \-setgrid -\-borderwidth \-highlightcolor \-state -\-cursor \-highlightthickness \-takefocus -\-disabledforeground \-relief \-width -\-exportselection \-selectbackground \-xscrollcommand -\-font \-selectborderwidth \-yscrollcommand -\-foreground +\-background \-borderwidth \-cursor +\-disabledforeground \-exportselection \-font +\-foreground \-highlightbackground \-highlightcolor +\-highlightthickness \-relief \-selectbackground +\-selectborderwidth \-selectforeground \-setgrid +\-takefocus \-xscrollcommand \-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" -.VS 8.4 .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. -.VS 8.4 +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 @@ -51,17 +47,16 @@ 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 +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 doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. +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 @@ -93,7 +88,6 @@ may be used to change the view in the window. Listboxes allow scrolling in both directions using the standard \fBxScrollCommand\fR and \fByScrollCommand\fR options. They also support scanning, as described below. - .SH "INDICES" .PP Many of the widget commands for listboxes take one or more indices @@ -117,11 +111,9 @@ Indicates the anchor point for the selection, which is set with the .TP 12 \fBend\fR Indicates the end of the listbox. -.VS 8.0 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. -.VE .TP 12 \fB@\fIx\fB,\fIy\fR Indicates the element that covers the point in the listbox window @@ -132,7 +124,6 @@ point is used. 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 @@ -148,10 +139,8 @@ commands are possible for listbox widgets: .TP \fIpathName \fBactivate\fR \fIindex\fR Sets the active element to the one indicated by \fIindex\fR. -.VS 8.0 If \fIindex\fR is outside the range of elements in the listbox then the closest element is activated. -.VE 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. @@ -165,9 +154,7 @@ of the upper-left corner of the screen area covered by the text 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, -.VS 8.0 or if \fIindex\fR refers to a non-existent element, -.VE 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. @@ -201,15 +188,13 @@ string is returned. \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 isn't specified it defaults to +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, -.VS 8.0 or an empty string if \fIfirst\fR refers to a non-existent element. -.VE 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. @@ -218,10 +203,8 @@ forms for indices. .TP \fIpathName \fBindex \fIindex\fR Returns the integer index value that corresponds to \fIindex\fR. -.VS 8.0 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). -.VE .TP \fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? Inserts zero or more new elements in the list just before the @@ -308,10 +291,8 @@ has several forms, depending on \fIoption\fR: .TP \fIpathName \fBselection anchor \fIindex\fR Sets the selection anchor to the element given by \fIindex\fR. -.VS 8.0 If \fIindex\fR refers to a non-existent element, then the closest element is used. -.VE 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 @@ -325,7 +306,7 @@ this range. .TP \fIpathName \fBselection includes \fIindex\fR Returns 1 if the element indicated by \fIindex\fR is currently -selected, 0 if it isn't. +selected, 0 if it is not. .TP \fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? Selects all of the elements in the range between @@ -418,7 +399,6 @@ 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 @@ -432,6 +412,10 @@ 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. +.VS 8.5 +On button 1, the listbox will also take focus if it has a \fBnormal\fR +state and \fB\-takefocus\fR is true. +.VE 8.5 .PP If the selection mode is \fBmultiple\fR or \fBextended\fR, any number of elements may be selected at once, including discontiguous @@ -464,7 +448,7 @@ the button down. 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 isn't changed. +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 @@ -545,10 +529,10 @@ Control-backslash deselects everything in the widget, except in 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 diff --git a/doc/loadTk.n b/doc/loadTk.n index 6c6a830..e1fecf6 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -13,15 +13,13 @@ loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS \fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? .BE - +.SH DESCRIPTION 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. - -.SH DESCRIPTION .PP The \fB::safe::loadTk\fR command initializes the required data structures in the named safe interpreter and then loads Tk into it. @@ -29,14 +27,17 @@ The interpreter must have been created with \fB::safe::interpCreate\fR or have been initialized with \fB::safe::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 ``.'' +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. \fB.x.y\fR) instead of its window Id (\fB[winfo id .x.y]\fR). When \fB\-use\fR is not specified, -a new toplevel window is created for the ``.'' window of +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. @@ -16,14 +16,12 @@ menu, tk_menuSetFocus \- Create and manipulate menu widgets \fBmenu\fR \fIpathName \fR?\fIoptions\fR? \fBtk_menuSetFocus\fR \fIpathName\fR .SO -\-activebackground \-borderwidth \-foreground -\-activeborderwidth \-cursor \-relief +\-activebackground \-borderwidth \-foreground +\-activeborderwidth \-cursor \-relief \-activeforeground \-disabledforeground \-takefocus \-background \-font - .SE .SH "WIDGET-SPECIFIC OPTIONS" -.VS .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 @@ -31,7 +29,6 @@ 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. -.VE .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 @@ -49,10 +46,12 @@ 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 is ``\fBa b\fR'' and menu \fB.x.y\fR is torn off to +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 -``\fBa b .x.y .x.tearoff1\fR'' will be invoked. -.VS +.QW "\fBa b .x.y .x.tearoff1\fR" +will be invoked. .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 @@ -65,9 +64,7 @@ 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. -.VE .BE - .SH INTRODUCTION .PP The \fBmenu\fR command creates a new top-level window (given @@ -81,14 +78,12 @@ The \fBmenu\fR command returns its there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP -.VS 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. -.VE .PP Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, @@ -117,28 +112,24 @@ 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. -.VS .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. -.VE - -.SH "COMMAND ENTRIES" +.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. - -.SH "SEPARATOR ENTRIES" +.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. - -.SH "CHECKBUTTON ENTRIES" +.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 @@ -155,8 +146,7 @@ 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. - -.SH "RADIOBUTTON ENTRIES" +.SS "RADIOBUTTON ENTRIES" .PP A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups of which only one @@ -179,8 +169,7 @@ 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. - -.SH "CASCADE ENTRIES" +.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 @@ -199,7 +188,6 @@ Tcl command of the form 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. -.VS On Unix, the lower-level menu is unposted by executing a Tcl command with the form .CS @@ -208,15 +196,11 @@ the form where \fImenu\fR is the name of the associated menu. On other platforms, the platform's native code takes care of unposting the menu. -.VE .PP -.VS 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. -.VE - -.SH "TEAR-OFF ENTRIES" +.SS "TEAR-OFF ENTRIES" .PP A tear-off entry appears at the top of the menu if enabled with the \fBtearOff\fR option. It is not like other menu entries in that @@ -226,8 +210,6 @@ 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. - -.VS .SH "MENUBARS" .PP Any menu can be set as a menubar for a toplevel window (see @@ -244,39 +226,29 @@ 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. -.VE - -.VS -.SH "SPECIAL MENUS IN MENUBARS" +.SS "SPECIAL MENUS IN MENUBARS" .PP -Certain menus in a menubar will be treated specially. On the Macintosh, -access to the special Apple 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 is provided. 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 and .menubar.help; on Windows, -the special menu would be .menubar.system; on X Windows, the help -menu would be .menubar.help. +Certain menus in a menubar will be treated specially. On the +Macintosh, access to the special Application 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 +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 an Apple menu on the Macintosh, that menu's contents make -up the first items of the Apple menu on the screen whenever the window -containing the menubar is in front. The menu is the -first one that the user sees and has a title which is an Apple logo. +When Tk sees a .menubar.apple menu 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 of the items in the user's Apple Menu Items folder. -Since the System uses a different menu definition procedure for -the Apple menu than Tk uses for its menus, and the system APIs do -not fully support everything Tk tries to do, the menu item will only -have its text displayed. No font attributes, images, bitmaps, or colors -will be displayed. In addition, a menu with a tearoff item will have -the tearoff item displayed as "(TearOff)". +followed by all standard Application menu items. .PP -When Tk see a Help menu on the Macintosh, the menu's contents are -appended to the standard help menu on the right of the user's menubar -whenever the user's menubar is in front. The first items in the menu -are provided by Apple. Similar to the Apple Menu, customization in this -menu is limited to what the system provides. +When Tk sees a Help menu on the Macintosh, the menu's contents are +appended to the standard Help menu on the right 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 has an icon @@ -285,11 +257,11 @@ 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 see a Help menu on X Windows, the menu is moved to be last in -the menubar and is right justified. -.VE - -.VS +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 @@ -299,9 +271,7 @@ 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. -.VE - +destroyed. .SH "WIDGET COMMAND" .PP The \fBmenu\fR command creates a new Tcl command whose @@ -338,7 +308,9 @@ This form may not be abbreviated. Same as \fBend\fR. .TP 12 \fBnone\fR -Indicates ``no entry at all''; this is used most commonly with +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. @@ -347,11 +319,12 @@ This form may not be abbreviated. \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, ``\fB@0\fR'' indicates the top-most entry in the -window. +For example, +.QW \fB@0\fR +indicates the top-most entry in the window. .TP 12 \fIpattern\fR -If the index doesn't satisfy one of the above forms then this +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 \fBTcl_StringMatch\fR @@ -417,16 +390,13 @@ If a \fB\-image\fR option has been specified, it overrides This option is not available for separator or tear-off entries. .TP \fB\-columnbreak \fIvalue\fR -.VS 8.0 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. -.VE 8.0 .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. -.VS 8.4 .TP \fB\-compound \fIvalue\fR Specifies whether the menu entry should display both an image and text, @@ -436,7 +406,6 @@ Valid values for this option are \fBbottom\fR, \fBcenter\fR, 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. -.VE .TP \fB\-font \fIvalue\fR Specifies the font to use when drawing the label or accelerator @@ -451,14 +420,12 @@ is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the \fBforeground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. -.VS .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. -.VE .TP \fB\-image \fIvalue\fR Specifies an image to display in the menu instead of a text string @@ -556,16 +523,14 @@ 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. -.VS .TP \fIpathName\fR \fBclone\fR \fInewPathname ?cloneType?\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 -propogated to the original menu and vice versa. \fIcloneType\fR can be +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. -.VE .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? Query or modify the configuration options of the widget. @@ -644,8 +609,8 @@ returned without posting the menu. \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 doesn't correspond to a cascade entry, -or if \fIpathName\fR isn't posted, +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 @@ -656,30 +621,31 @@ 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 -.VS 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. -.VE +.TP +\fIpathName \fBxposition \fIindex\fR +.VS 8.5 +Returns a decimal string giving the x-coordinate within the menu +window of the leftmost pixel in the entry specified by \fIindex\fR. +.VE 8.5 .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 CONFIGURATIONS" .PP The default bindings support four different ways of using menus: -.VS .TP \fBPulldown Menus in Menubar\fR -This is the most command case. You create a menu widget that will become the +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. -.VE .TP \fBPulldown Menus in Menu Buttons\fR This is the compatible way to do menu bars. You create one menubutton @@ -711,7 +677,6 @@ 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 @@ -763,23 +728,21 @@ 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 don't activate and +Disabled menu entries are non-responsive: they do not activate and they ignore mouse button presses and releases. .PP -.VS 8.4 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. -.VE .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 isn't possible to use the +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 diff --git a/doc/menubutton.n b/doc/menubutton.n index 22b1df6..ade9523 100644 --- a/doc/menubutton.n +++ b/doc/menubutton.n @@ -37,7 +37,7 @@ 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 isn't specified, the menubutton's desired height is computed +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 @@ -64,10 +64,9 @@ 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 isn't specified, the menubutton's desired width is computed +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 @@ -105,7 +104,6 @@ new menubutton is posted instead. 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 @@ -138,7 +136,6 @@ 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 @@ -178,7 +175,7 @@ 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 isn't disabled. +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. @@ -188,6 +185,7 @@ 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 diff --git a/doc/message.n b/doc/message.n index 94f93fe..92434f0 100644 --- a/doc/message.n +++ b/doc/message.n @@ -14,12 +14,11 @@ message \- Create and manipulate message widgets .SH SYNOPSIS \fBmessage\fR \fIpathName \fR?\fIoptions\fR? .SO -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-borderwidth \-highlightthickness \-textvariable -\-cursor \-padx \-width -\-font \-pady -\-foreground \-relief +\-anchor \-background \-borderwidth +\-cursor \-font \-foreground +\-highlightbackground \-highlightcolor \-highlightthickness +\-padx \-pady \-relief +\-takefocus \-text \-textvariable .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-aspect aspect Aspect @@ -30,7 +29,7 @@ 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 \fBwidth\fR option -isn't specified. +is not specified. Defaults to 150. .OP \-justify justify Justify Specifies how to justify lines of text. @@ -61,7 +60,6 @@ length. If this option has a value less than or equal to zero, then the \fBaspect\fR option determines the line length. .BE - .SH DESCRIPTION .PP The \fBmessage\fR command creates a new window (given by the @@ -96,10 +94,10 @@ are replaced with enough blank space to line up on the next 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 doesn't contain -all of the characters in ``0123456789abcdef\ex'' then control -characters and undefined characters are not displayed at all. - +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 @@ -132,16 +130,15 @@ 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 don't work very well with text that is centered or right-justified. +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 diff --git a/doc/messageBox.n b/doc/messageBox.n index 0079972..5cdd26e 100644 --- a/doc/messageBox.n +++ b/doc/messageBox.n @@ -27,10 +27,21 @@ The following option-value pairs are supported: .TP \fB\-default\fR \fIname\fR \fIName\fR gives the symbolic name of the default button for -this message window ('ok', 'cancel', and so on). See \fB\-type\fR +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 +.VS 8.5 +Specifies an auxiliary message to the main message given by the +\fB\-message\fR option. Where supported by the underlying OS, the +message detail will be presented in a less emphasized font than the +main message. +.VE 8.5 +.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 @@ -76,8 +87,10 @@ and \fBcancel\fR. .PP .SH EXAMPLE .CS -set answer [\fBtk_messageBox\fR \-message "Really quit?" \-type yesno \-icon question] -switch -- $answer { +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} diff --git a/doc/option.n b/doc/option.n index e731713..b7342e2 100644 --- a/doc/option.n +++ b/doc/option.n @@ -19,7 +19,6 @@ option \- Add/retrieve window options to/from the option database \fBoption readfile \fIfileName \fR?\fIpriority\fR? .fi .BE - .SH DESCRIPTION .PP The \fBoption\fR command allows you to add entries to the Tk option @@ -27,7 +26,8 @@ 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. \fIValue\fR +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 @@ -63,31 +63,60 @@ 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 isn't specified, it defaults to +starts running. If \fIpriority\fR is not specified, it defaults to this level. -.LP +.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 Instruct every button in the application to have red text on it unless -explicitly overridden: +explicitly overridden (note that on some platforms the option is ignored): .CS -\fBoption add\fR *button.foreground red startupFile +\fBoption add\fR *Button.foreground red startupFile .CE .PP Allow users to control what happens in an entry widget when the Return @@ -98,6 +127,10 @@ 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/doc/optionMenu.n b/doc/optionMenu.n index 3ffa1cb..1f9f831 100644 --- a/doc/optionMenu.n +++ b/doc/optionMenu.n @@ -12,12 +12,11 @@ .SH NAME tk_optionMenu \- Create an option menubutton and its menu .SH SYNOPSIS -\fBtk_optionMenu \fIw varName value \fR?\fIvalue value ...\fR? +\fBtk_optionMenu \fIpathName varName value \fR?\fIvalue value ...\fR? .BE - .SH DESCRIPTION .PP -This procedure creates an option menubutton whose name is \fIw\fR, +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. @@ -31,8 +30,12 @@ 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 \fIw\fR, so that the caller can change its configuration -options or manipulate it in other ways. - +associated with \fIpathName\fR, so that the caller can change its +configuration options or manipulate it in other ways. +.SH EXAMPLE +.CS +tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble +pack .foo +.CE .SH KEYWORDS option menu diff --git a/doc/options.n b/doc/options.n index 2710300..25b0c9d 100644 --- a/doc/options.n +++ b/doc/options.n @@ -21,7 +21,9 @@ 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, ``Command-Line Name'' refers to the +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 @@ -32,9 +34,10 @@ command 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. -``Database Name'' refers to the option's name in the option database (e.g. -in .Xdefaults files). ``Database Class'' refers to the option's class value -in the option database. +.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 @@ -43,10 +46,8 @@ 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. -.VS For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. -.VE .OP \-activeborderwidth activeBorderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for @@ -89,8 +90,9 @@ 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 -.VS 8.4 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, @@ -100,7 +102,6 @@ to the text. Must be one of the values \fBnone\fR, \fBbottom\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. -.VE 8.4 .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 @@ -119,7 +120,8 @@ 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 accepted by \fBTk_GetFont\fR. +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 @@ -153,12 +155,16 @@ 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 ``off'' in each blink cycle. -If this option is zero then the cursor doesn't blink: it is on +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 ``on'' in each blink cycle. +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. @@ -176,7 +182,9 @@ 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 ``jumps'' rather than changing smoothly). +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. @@ -292,7 +300,7 @@ particular widget and may be determined by other options, such as .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 doesn't recognize this option). +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 @@ -327,7 +335,11 @@ the information just after the last portion that is visible. The command is then passed to the Tcl interpreter for execution. Typically the \fBxScrollCommand\fR option consists of the path name of a scrollbar -widget followed by ``set'', e.g. ``.x.scrollbar set'': this will cause +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 diff --git a/doc/pack-old.n b/doc/pack-old.n index 66bdc18..532b4ae 100644 --- a/doc/pack-old.n +++ b/doc/pack-old.n @@ -61,7 +61,7 @@ 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 wasn't claimed by earlier children in +(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. @@ -25,14 +25,15 @@ 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 ``.''), then the command is processed in the same -way as \fBpack configure\fR. +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 ``THE PACKER ALGORITHM'' below for details on how the options +See \fBTHE PACKER ALGORITHM\fR below for details on how the options are used by the packer. The following options are supported: .RS @@ -134,13 +135,14 @@ The slaves will no longer be managed by the packer. 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 ``\fB\-in \fImaster\fR'' where -\fImaster\fR is the slave's master. +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 ``GEOMETRY PROPAGATION'' below). +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. @@ -182,7 +184,7 @@ 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 ``EXPANSION'' below) +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 @@ -206,7 +208,7 @@ slave and the edges of the parcel. 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 doesn't use all of its parcel, the unused space +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 @@ -214,7 +216,7 @@ 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. -.SH "EXPANSION" +.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 @@ -224,7 +226,7 @@ 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. -.SH "GEOMETRY PROPAGATION" +.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 @@ -250,7 +252,7 @@ visible without danger of the slave being clipped by its parent. 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 hasn't been packed correctly. +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. @@ -261,8 +263,8 @@ the stacking order of either the master or the slave. # 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\\nHand\\nSide" -label .r \-text "Right\\nHand\\nSide" +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 diff --git a/doc/palette.n b/doc/palette.n index 76c01c7..4b1dcff 100644 --- a/doc/palette.n +++ b/doc/palette.n @@ -32,15 +32,15 @@ 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 L +.DS .ta 4c 8c -\fBactiveBackground foreground selectColor -activeForeground highlightBackground selectBackground -background highlightColor selectForeground -disabledForeground insertBackground troughColor\fR +\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 don't specify. You can specify options other +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. @@ -64,7 +64,8 @@ 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 (``bisque'') +it restores the application's colors to the light brown +.PQ bisque color scheme used in Tk 3.6 and earlier versions. .SH KEYWORDS diff --git a/doc/panedwindow.n b/doc/panedwindow.n index 621767c..ccc87e7 100644 --- a/doc/panedwindow.n +++ b/doc/panedwindow.n @@ -14,9 +14,8 @@ panedwindow \- Create and manipulate panedwindow widgets .SH SYNOPSIS \fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR? .SO -\-background \-height \-width -\-borderwidth \-orient -\-cursor \-relief +\-background \-borderwidth \-cursor +\-orient \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-handlepad handlePad HandlePad @@ -26,6 +25,10 @@ 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). @@ -45,8 +48,11 @@ Specifies the width of each sash. May be any value accepted by .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 @@ -188,10 +194,17 @@ 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 +.VS 8.5 +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. +.VE 8.5 +.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 -- the x dimension for horizontal panedwindows, the y +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 @@ -209,13 +222,46 @@ have any of the forms accepted by \fBTk_GetPixels\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\fP, \fBs\fP, \fBe\fP or \fBw\fP. The string +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 "stick" to. If both \fBn\fP and \fBs\fP (or \fBe\fP and \fBw\fP) +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 +.VS 8.5 +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 +.VE 8.5 +.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 @@ -237,6 +283,7 @@ adjusted. 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. - +.SH "SEE ALSO" +ttk::panedwindow(n) .SH KEYWORDS panedwindow, widget, geometry management diff --git a/doc/photo.n b/doc/photo.n index 7f03fe7..c14abe3 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -30,10 +30,8 @@ C code through a procedural interface. At present, only 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 -.VS 8.4 or where it has been set transparent by the \fBtransparency set\fR subcommand. -.VE 8.4 .SH "CREATING PHOTOS" .PP Like all images, photos are created using the \fBimage create\fR @@ -188,7 +186,6 @@ 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 -.VS 8.4 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 @@ -197,7 +194,6 @@ 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. -.VE 8.4 .RE .TP \fIimageName \fBdata ?\fIoption value(s) ...\fR? @@ -214,9 +210,14 @@ the specified color. 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 read this image data. -If this option is not given, this subcommand uses the first -handler that has the capability to read the image data. +\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. @@ -259,8 +260,8 @@ 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 data from \fIfilename\fR -are to be read. The default is (0,0). If \fIx2\fR,\fIy2\fR is given +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 @@ -316,7 +317,6 @@ recalculate the dithered image in each window where the image is displayed. .TP \fIimageName \fBtransparency \fIsubcommand ?arg arg ...?\fR -.VS 8.4 Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS @@ -329,7 +329,6 @@ transparent. Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is true, and makes that pixel opaque otherwise. .RE -.VE 8.4 .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? Writes image data from \fIimageName\fR to a file named \fIfilename\fR. @@ -374,7 +373,7 @@ 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 doesn't, the +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 @@ -390,10 +389,8 @@ 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. -.VS 8.4 Note that not all image handlers may support writing transparency data to a file, even where the target image format does. -.VE 8.4 .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code @@ -433,7 +430,7 @@ Load an image from a file and tile it to the size of a window, which is useful for producing a tiled background: .CS # These lines should be called once -\fBimage create photo\fR untiled -file "theFile.ppm" +\fBimage create photo\fR untiled \-file "theFile.ppm" \fBimage create photo\fR tiled # These lines should be called whenever .someWidget changes diff --git a/doc/place.n b/doc/place.n index 017313f..fc7e0fb 100644 --- a/doc/place.n +++ b/doc/place.n @@ -102,7 +102,7 @@ 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 isn't specified then the master defaults to +If this option is not specified then the master defaults to \fIwindow\fR's parent. .TP \fB\-relheight \fIsize\fR @@ -180,7 +180,7 @@ the most recent option is used and the older one is ignored. \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 -doesn't appear on the screen. If \fIwindow\fR isn't currently managed +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 @@ -207,12 +207,15 @@ 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 ``real children'' of the parent (i.e. the windows that +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 ``real children'' -don't reflect the geometry-management hierarchy and users +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. @@ -230,7 +233,7 @@ 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 doesn't +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. @@ -238,7 +241,7 @@ frames and canvases that provide configuration options for this purpose. Make the label occupy the middle bit of the toplevel, no matter how it is resized: .CS -label .l \-text "In the\\nMiddle!" \-bg black \-fg white +label .l \-text "In the\enMiddle!" \-bg black \-fg white \fBplace\fR .l \-relwidth .3 \-relx .35 \-relheight .3 \-rely .35 .CE diff --git a/doc/radiobutton.n b/doc/radiobutton.n index ae9a857..29c2eec 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.n @@ -34,7 +34,7 @@ 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 isn't specified, the button's desired height is computed +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 @@ -52,25 +52,25 @@ 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 \-offrelief offRelief OffRelief -.VS 8.4 Specifies the relief for the checkbutton when the indicator is not drawn and -the checkbutton is off. The default value is "raised". By setting this option -to "flat" and setting -indicatoron to false and -overrelief to raised, +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. -.VE 8.4 .OP \-overrelief overRelief OverRelief -.VS 8.4 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. -.VE 8.4 .OP \-selectimage selectImage SelectImage Specifies an image to display (in place of the \fBimage\fR option) when the radiobutton is selected. @@ -87,6 +87,19 @@ should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fBdisabledForeground\fR and \fBbackground\fR options determine how the radiobutton is displayed. +.OP \-tristateimage tristateImage TristateImage +.VS 8.5 +Specifies an image to display (in place of the \fBimage\fR option) +when the radiobutton is selected. +This option is ignored unless the \fBimage\fR option has been +specified. +.VE 8.5 +.OP \-tristatevalue tristateValue Value +.VS 8.5 +Specifies the value that causes the radiobutton to display the multi-value +selection, also known as the tri-state mode. Defaults to +.QW "" . +.VE 8.5 .OP \-value value Value Specifies value to store in the button's associated variable whenever this button is selected. @@ -100,10 +113,9 @@ 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 isn't specified, the button's desired width is computed +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 @@ -117,10 +129,8 @@ text, and initial relief. The \fBradiobutton\fR command returns its there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP -.VS A radiobutton is a widget that displays a textual string, bitmap or image and a diamond or circle called an \fIindicator\fR. -.VE If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fBwrapLength\fR option) and @@ -135,7 +145,6 @@ check button. .PP In addition, radiobuttons can be \fIselected\fR. If a radiobutton is selected, the indicator is normally -.VS drawn with a selected appearance, and a Tcl variable associated with the radiobutton is set to a particular value (normally 1). @@ -144,15 +153,19 @@ 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). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a round mark inside. -.VE +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. +.VS 8.5 +If the variable's value matches the \fBtristateValue\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.) +.VE 8.5 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 @@ -225,14 +238,12 @@ value corresponding to this widget. Tk automatically creates class bindings for radiobuttons that give them the following default behavior: .IP [1] -.VS 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. -.VE .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 @@ -246,9 +257,7 @@ 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) - +checkbutton(n), labelframe(n), listbox(n), options(n), scale(n), ttk::radiobutton(n) .SH KEYWORDS radiobutton, widget diff --git a/doc/raise.n b/doc/raise.n index 643ec36..02f805f 100644 --- a/doc/raise.n +++ b/doc/raise.n @@ -34,11 +34,11 @@ 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"] +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 diff --git a/doc/scale.n b/doc/scale.n index 5b1b3b1..e750fdd 100644 --- a/doc/scale.n +++ b/doc/scale.n @@ -23,7 +23,8 @@ scale \- Create and manipulate scale widgets .SH "WIDGET-SPECIFIC OPTIONS" .OP \-bigincrement bigIncrement BigIncrement Some interactions with the scale cause its value to change by -``large'' increments; this option specifies the size of the +.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 @@ -71,7 +72,7 @@ or \fBsunken\fR. 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 -won't activate. +will not activate. If the scale is active, the slider is displayed using the color specified by the \fBactiveBackground\fR option. .OP \-tickinterval tickInterval TickInterval @@ -186,7 +187,7 @@ 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 isn't over one of these elements, an empty string +If the point is not over one of these elements, an empty string is returned. .TP \fIpathName \fBset\fR \fIvalue\fR diff --git a/doc/scrollbar.n b/doc/scrollbar.n index 7f4801a..a13574b 100644 --- a/doc/scrollbar.n +++ b/doc/scrollbar.n @@ -37,7 +37,7 @@ 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 SCROLLING COMMANDS below. +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 @@ -51,7 +51,6 @@ 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 @@ -280,7 +279,7 @@ 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 doesn't drag along +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 @@ -332,12 +331,13 @@ The End key adjusts the view to the bottom (right edge) of the document. 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 +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 diff --git a/doc/selection.n b/doc/selection.n index dcf12b2..8aee321 100644 --- a/doc/selection.n +++ b/doc/selection.n @@ -35,35 +35,44 @@ 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 PRIMARY or CLIPBOARD; see the Inter-Client Communication Conventions Manual for complete details. -\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to ``.''. +\fISelection\fR defaults to PRIMARY 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 PRIMARY and -\fIwindow\fR defaults to ``.''. +\fIwindow\fR defaults to +.QW . . \fIType\fR specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and +(the desired +.QW target +for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME; see the Inter-Client Communication Conventions Manual for complete details. \fIType\fR defaults to STRING. The selection owner may choose to return the selection in any of several different representation -formats, such as STRING, ATOM, INTEGER, etc. (this format is different +formats, such as STRING, UTF8_STRING, ATOM, INTEGER, 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 INTEGER or ATOM, 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 +UTF8_STRING format unless told to. .TP -\fBselection handle\fR ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-format\fR \fIformat\fR? \fIwindow command\fR +\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 \fIselection\fR is owned by \fIwindow\fR and -someone attempts to retrieve it in the form given by \fItype\fR -(e.g. \fItype\fR is specified in the \fBselection get\fR command). -\fISelection\fR defaults to PRIMARY, \fItype\fR defaults to STRING, and -\fIformat\fR defaults to STRING. If \fIcommand\fR is an empty string -then any existing handler for \fIwindow\fR, \fItype\fR, and -\fIselection\fR is removed. +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 PRIMARY, \fIt\fR defaults to STRING, and +\fIf\fR defaults to STRING. 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 STRING it is also +automatically handled as type UTF8_STRING as well. .RS .PP When \fIselection\fR is requested, \fIwindow\fR is the selection owner, @@ -71,7 +80,6 @@ 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 -.VS 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 @@ -85,16 +93,17 @@ include all of the remainder of the selection; if the length of \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). -.VE .PP If \fIcommand\fR returns an error then the selection retrieval is rejected -just as if the selection didn't exist at all. +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 STRING. If \fIformat\fR is STRING, the selection is transmitted as 8-bit ASCII characters (i.e. -just in the form returned by \fIcommand\fR). If \fIformat\fR is +just in the form returned by \fIcommand\fR, in the system \fBencoding\fR; +the UTF8_STRING format always uses UTF-8 as its encoding). +If \fIformat\fR is ATOM, 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. @@ -104,7 +113,7 @@ 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 don't use Tk. If Tk is being +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. @@ -117,7 +126,8 @@ 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 PRIMARY and -\fIwindow\fR defaults to ``.''. +\fIwindow\fR defaults to +.QW . . .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 @@ -160,9 +170,7 @@ proc lost {} { puts "Lost selection" } .CE - .SH "SEE ALSO" clipboard(n) - .SH KEYWORDS clear, format, handler, ICCCM, own, selection, target, type @@ -28,9 +28,9 @@ 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 ``\-'' -they are treated as options. The following options are -currently defined: +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 @@ -47,7 +47,8 @@ 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 ``\-'' +option is needed only if \fIapp\fR could contain a leading +.QW \- character. .SH "APPLICATION NAMES" @@ -85,16 +86,14 @@ 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. -.VS Under Windows, \fBsend\fR is currently disabled. Most of the functionality is provided by the \fBdde\fR command instead. -.VE .SH EXAMPLE 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 + \fBsend\fR \-async FoobarApp RemoteStart $argv exit } # The command that will be called remotely, which raises @@ -107,6 +106,4 @@ proc RemoteStart args { } .CE .SH KEYWORDS -.VS application, dde, name, remote execution, security, send -.VE diff --git a/doc/spinbox.n b/doc/spinbox.n index 700f001..dc98251 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -78,7 +78,7 @@ 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. +\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 @@ -112,7 +112,6 @@ size just large enough to hold its current text. 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 @@ -145,7 +144,6 @@ may be used to change the view in the window. Spinboxes use the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). They also support scanning, as described below. - .SH VALIDATION .PP Validation works by setting the \fBvalidateCommand\fR @@ -172,9 +170,9 @@ 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. +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. +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 @@ -212,13 +210,12 @@ validated. If you wish to edit the value of the widget during validation and still have the \fBvalidate\fR option set, you should include the command .CS - \fI%W config -validate %v\fR + \fI%W config \-validate %v\fR .CE in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated \fBtextVariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fBtextVariable\fR. - .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose @@ -229,6 +226,7 @@ operations on the widget. It has the following general form: .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 @@ -253,22 +251,27 @@ 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 isn't in the spinbox window. +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 isn't in the +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, ``\fB@0\fR'' indicates the left-most character in the -window. +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. ``\fBe\fR'' -or ``\fBsel.f\fR''. In general, out-of-range indices are automatically -rounded to the nearest legal value. +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 @@ -307,7 +310,7 @@ 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 isn't specified it defaults to \fIfirst\fR+1, +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 @@ -366,14 +369,14 @@ Locate the end of the selection nearest to the character given by (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 -isn't currently in the spinbox, then a new selection is created to +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 isn't in this widget then the command has no effect. +selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection element\fR ?\fIelement\fR? @@ -382,7 +385,7 @@ 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. Doesn't change the selection. +given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR @@ -406,7 +409,7 @@ 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 isn't in this widget then a new selection is +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 @@ -465,9 +468,11 @@ become visible. .PP Tk automatically creates class bindings for spinboxes that give them the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. +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 @@ -528,7 +533,7 @@ 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 don't affect the current selection. +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. @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH text n 8.4 Tk "Tk Built-In Commands" +.TH text n 8.5 Tk "Tk Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -14,11 +14,9 @@ text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widget .SH SYNOPSIS .nf \fBtext\fR \fIpathName \fR?\fIoptions\fR? -.VS 8.4 \fBtk_textCopy\fR \fIpathName\fR \fBtk_textCut\fR \fIpathName\fR \fBtk_textPaste\fR \fIpathName\fR -.VE 8.4 .SO \-background \-highlightthickness \-relief \-borderwidth \-insertbackground \-selectbackground @@ -31,20 +29,38 @@ text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widget .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-autoseparators autoSeparators AutoSeparators -.VS 8.4 Specifies a boolean that says whether separators are automatically inserted in the undo stack. Only meaningful when the \fB\-undo\fR option is true. -.VE 8.4 +.OP \-blockcursor blockCursor BlockCursor +.VS 8.5 +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. +.VE 8.5 +.OP \-endline endLine EndLine +.VS 8.5 +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. +.VE 8.5 .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 +.VS 8.5 +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. +.VE 8.5 .OP \-maxundo maxUndo MaxUndo -.VS 8.4 Specifies the maximum number of compound undo actions on the undo stack. A zero or a negative value imply an unlimited undo stack. -.VE 8.4 .OP \-spacing1 spacing1 Spacing1 Requests additional space above each text line in the widget, using any of the standard forms for screen distances. @@ -66,6 +82,15 @@ 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 +.VS 8.5 +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. +.VE 8.5 .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 @@ -89,36 +114,55 @@ 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, \fB\-tabs {2c left 4c 6c center}\fR creates three -tab stops at two-centimeter intervals; the first two use left +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 +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 \fBtabs\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. +(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 \fBtabstyle\fR option may be overridden +by \fB\-tabstyle\fR options in tags. .OP \-undo undo Undo -.VS 8.4 Specifies a boolean that says whether the undo mechanism is active or not. -.VE 8.4 .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 doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. +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 don't fit +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. @@ -149,7 +193,8 @@ 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 "marks". +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. @@ -162,10 +207,14 @@ The fourth form of annotation allows Tk images to be embedded in a text widget. See \fBEMBEDDED IMAGES\fR below for more details. .PP -.VS 8.4 The text widget also has a built-in undo/redo mechanism. See \fBTHE UNDO MECHANISM\fR below for more details. -.VE 8.4 +.PP +.VS 8.5 +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. +.VE 8.5 .SH INDICES .PP Many of the widget commands for texts take one or more indices @@ -181,6 +230,20 @@ 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. +.VS 8.5 +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" ). +.VE 8.5 .PP The \fIbase\fR for an index must have one of the following forms: .TP 12 @@ -227,82 +290,163 @@ Indicates the position of the embedded image whose name is This form generates an error if there is no embedded image by the given name. .PP -If the \fIbase\fP could match more than one of the above forms, such -as a \fImark\fP and \fIimageName\fP both having the same value, then +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\fB chars\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 character in the text. -Spaces on either side of \fIcount\fR are optional. -.TP -\fB\- \fIcount\fB chars\fR +\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR +.VS 8.5 +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. +.VE 8.5 +.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 character in the text. -Spaces on either side of \fIcount\fR are optional. -.TP -\fB+ \fIcount\fB lines\fR +characters in the text before the current index, then set the index to +.VS 8.5 +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 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. +.VE 8.5 +.TP +\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR +.VS 8.5 +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. +.VE 8.5 +.TP +\fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR +.VS 8.5 +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. +.VE 8.5 +.TP +\fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR +.VS 8.5 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 +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. -.TP -\fB\- \fIcount\fB lines\fR -Adjust the index backward by \fIcount\fR 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. -.TP -\fBlinestart\fR -Adjust the index to refer to the first character on the line. -.TP -\fBlineend\fR -Adjust the index to refer to the last character on the line (the newline). -.TP -\fBwordstart\fR +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. +.VE 8.5 +.TP +\fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR +.VS 8.5 +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. +.VE 8.5 +.TP +?\fIsubmodifier\fR? \fBlinestart\fR +.VS 8.5 +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. +.VE 8.5 +.TP +?\fIsubmodifier\fR? \fBlineend\fR +.VS 8.5 +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. +.VE 8.5 +.TP +?\fIsubmodifier\fR? \fBwordstart\fR +.VS 8.5 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. -.TP -\fBwordend\fR +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. +.VE 8.5 +.TP +?\fIsubmodifier\fR? \fBwordend\fR +.VS 8.5 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. +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 ``\fBend \- 1 chars\fR'' +left-to-right order. For example, the index +.QW "\fBend \- 1 chars\fR" refers to the next-to-last character in the text and -``\fBinsert wordstart \- 1 c\fR'' refers to the character just before +.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 ``\fB1.0 -1c +1c\fR'' refers to the -index ``\fB2.0\fR''. +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. +.VE 8.5 .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 `` '' (space), \fB+\fR, or \fB\-\fR: +avoid using the characters +.QW " " +(space), \fB+\fR, or \fB\-\fR: these characters have special meaning in indices, so tags containing -them can't be used as indices. +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 @@ -315,16 +459,20 @@ 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 -``\fIpathName \fBtag raise\fR'' and ``\fIpathName \fBtag lower\fR'' +.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 -\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for 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 ``\fIpathName \fBtag configure\fR'' widget command. +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: @@ -338,7 +486,7 @@ It may have any of the forms accepted by \fBTk_GetColor\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 hasn't been specified, or if it is specified +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 @@ -352,16 +500,17 @@ it is ignored unless the \fB\-background\fR option has been set for the tag. .TP \fB\-elide \fIboolean\fR -\fIElide\fR specifies whether the data should be elided. -Elided data is not displayed and takes no space on screen, but further -on behaves just as normal data. +\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 hasn't been specified, or if it is specified +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 @@ -374,15 +523,15 @@ 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 character of a display line has a tag for which this +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 character of that display line. +display is determined by the first non-elided character of that display line. .TP \fB\-lmargin1 \fIpixels\fR -If the first character of a text line has a tag for which this +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. @@ -393,7 +542,7 @@ first line on the display; the \fB\-lmargin2\fR option controls the indentation for subsequent lines. .TP \fB\-lmargin2 \fIpixels\fR -If the first character of a display line has a tag for which this +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 @@ -426,7 +575,7 @@ it is ignored unless the \fB\-background\fR option has been set for the tag. .TP \fB\-rmargin \fIpixels\fR -If the first character of a display line has a tag for which this +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. @@ -434,7 +583,7 @@ edge of the window. 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 character of that display +display is determined by the first non-elided character of that display line. .TP \fB\-spacing1 \fIpixels\fR @@ -461,14 +610,22 @@ line on the display. \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 character on that display line. +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 \fBtags\fR +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. @@ -485,7 +642,7 @@ for the text widget. 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 hasn't been specified for a +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. @@ -500,17 +657,29 @@ 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 \fBtag bind\fR widget -command below. +For details, see the description of the +.QW "\fIpathName \fBtag bind\fR" +widget command below. +.VS 8.5 +Tag bindings are shared between all peer widgets +(including any bindings for the special \fBsel\fR tag). +.VE 8.5 .PP The third use for tags is in managing the selection. See \fBTHE SELECTION\fR below. +.VS 8.5 +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). +.VE 8.5 .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 isn't associated +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 @@ -520,12 +689,15 @@ 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 ``\fIpathName \fBmark\fR'' widget +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 "gravity", which is either \fBleft\fR or -\fBright\fR. +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 @@ -549,6 +721,11 @@ 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. +.VS 8.5 +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. +.VE 8.5 .SH "EMBEDDED WINDOWS" .PP The third form of annotation in text widgets is an embedded window. @@ -562,17 +739,25 @@ parent). 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 character's worth of index space +Each embedded window occupies one +.VS 8.5 +unit's +.VE 8.5 +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. +.VS 8.5 +Similarly if the text widget as a whole is deleted, then the window is +destroyed. +.VE 8.5 .PP When an embedded window is added to a text widget with the -\fBwindow create\fR widget command, several configuration +\fIpathName \fBwindow create\fR widget command, several configuration options may be associated with it. -These options may be modified later with the \fBwindow configure\fR +These options may be modified later with the \fIpathName \fBwindow configure\fR widget command. The following options are currently supported: .TP @@ -594,6 +779,11 @@ 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. +.VS 8.5 +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. +.VE 8.5 If the annotation's window should ever be deleted, \fIscript\fR will be evaluated again the next time the annotation is displayed. .TP @@ -618,6 +808,14 @@ stretched. .TP \fB\-window \fIpathName\fR Specifies the name of a window to display in the annotation. +.VS 8.5 +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. +.VE 8.5 .SH "EMBEDDED IMAGES" .PP The final form of annotation in text widgets is an embedded image. @@ -628,30 +826,34 @@ and a particular image may be embedded in multiple places in the same text widget. The embedded image's position on the screen will be updated as the text is modified or scrolled. -Each embedded image occupies one character's worth of index space +Each embedded image occupies one +.VS 8.5 +unit's +.VE 8.5 +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 \fBimage create\fP. +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 -When an embedded image is added to a text widget with the \fBimage +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\fP option -(described below). If the \fB\-name\fP option is not provided, the -\fB\-image\fP name is used instead. If the \fIimageName\fP is already +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\fP, where \fInn\fP is an arbitrary integer. This insures -the \fIimageName\fP is unique. -Once this name is assigned to this instance of the image, it does not -change, even though the \fB\-image\fP or \fB\-name\fP values can be changed -with \fBimage configure\fP. +\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 -\fBimage create\fR widget command, several configuration +\fIpathName \fBimage create\fR widget command, several configuration options may be associated with it. -These options may be modified later with the \fBimage configure\fR +These options may be modified later with the \fIpathName \fBimage configure\fR widget command. The following options are currently supported: .TP @@ -667,13 +869,13 @@ of the line). .TP \fB\-image \fIimage\fR Specifies the name of the Tk image to display in the annotation. -If \fIimage\fP is not a valid Tk image, then an error is returned. +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\fP is not supplied, then the +the text widget. If \fIImageName\fR is not supplied, then the name of the Tk image is used instead. -If the \fIimageName\fP is already in use, \fI#nn\fP is appended to +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 @@ -702,23 +904,35 @@ 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 +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 ``\fIpathName \fBtag delete\fR'' +created, and it may not be deleted with the +.QW "\fIpathName \fBtag delete\fR" widget command. Furthermore, the \fBselectBackground\fR, \fBselectBorderWidth\fR, and \fBselectForeground\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. +.VS 8.5 +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. +.VE 8.5 .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 ``\fIpathName \fBmark unset\fR'' widget -command. +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. @@ -726,17 +940,18 @@ this point whenever the text widget has the input focus. 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 \fBedit modified\fR widget command for +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 -.VS 8.4 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 "separators") are inserted between edit actions. The +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 @@ -757,9 +972,70 @@ 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 \fBedit\fR widget command that controls the undo +See below for the \fIpathName \fBedit\fR widget command that controls the undo mechanism. -.VE 8.4 +.SH "PEER WIDGETS" +.PP +.VS 8.5 +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. +.VE 8.5 .SH "WIDGET COMMAND" .PP The \fBtext\fR command creates a new Tcl command whose @@ -795,7 +1071,7 @@ command. \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 isn't. +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 @@ -815,6 +1091,74 @@ 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. +.VS 8.5 +.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, +then all subsequent options ensure that any possible out of date +information is recalculated. This currently only has any effect for the +\fI\-ypixels\fR count (which, if \fB\-update\fR is not given, will use the text +widget's current cached value for each line). 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 +.VE 8.5 .TP \fIpathName \fBdebug \fR?\fIboolean\fR? If \fIboolean\fR is specified, then it must have one of the true or @@ -830,13 +1174,13 @@ 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 -.VS 8.4 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. -.VE 8.4 +.RE .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? Delete a range of characters from the text. @@ -844,23 +1188,21 @@ 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 doesn't specify a position later in the text +If \fIindex2\fR does not specify a position later in the text than \fIindex1\fR then no characters are deleted. -If \fIindex2\fR isn't specified then the single character at +If \fIindex2\fR is not specified then the single character at \fIindex1\fR is deleted. It is not allowable to delete characters in a way that would leave the text without a newline as the last character. The command returns an empty string. -.VS 8.4 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 to deleted text does not cause an undesired index shifting +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. -.VE 8.4 .TP \fIpathName \fBdlineinfo \fIindex\fR Returns a list with five elements describing the area occupied @@ -893,10 +1235,10 @@ in the following format: .RS \fIkey1 value1 index1 key2 value2 index2\fR ... .LP -The possible \fIkey\fP values are \fBtext\fP, \fBmark\fP, -\fBtagon\fP, \fBtagoff\fP, \fBimage\fP, and \fBwindow\fP. The corresponding -\fIvalue\fP is the text, mark name, tag name, image name, or window name. -The \fIindex\fP information is the index of the +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: @@ -909,7 +1251,7 @@ This is the default. 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\fP, \fIvalue\fP, and \fIindex\fP. +the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. .TP \fB\-image\fR Include information about images in the dump results. @@ -919,7 +1261,7 @@ 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\fP and \fBtagoff\fP elements that +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 @@ -939,7 +1281,6 @@ window by its index position to get more information. .RE .TP \fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? -.VS 8.4 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 @@ -972,9 +1313,8 @@ 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 -.VE 8.4 .TP -\fIpathName \fBget \fIindex1 \fR?\fIindex2 ...\fR? +\fIpathName \fBget\fR \fI?\-displaychars?\fR \fI\-\- index1\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 @@ -987,11 +1327,14 @@ 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. -.VS 8.4 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 \fBget\fR. -.VE 8.4 +the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. +.VS 8.5 +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. +.VE 8.5 .TP \fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? This command is used to manipulate embedded images. @@ -1058,7 +1401,7 @@ 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 \fBinsert\fR widget +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 @@ -1088,11 +1431,11 @@ 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\fP operation can be used to +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 \fBdump\fP operation. -If a mark has been set to the special \fBend\fP index, -then it appears to be \fIafter\fP \fBend\fP with respect to the \fBmark next\fP operation. +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 @@ -1103,25 +1446,61 @@ 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 \fBmark previous\fP operation can be used to +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 \fBdump\fP operation. +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 doesn't exist, a new mark is created. +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 ``\fIpathName \fBmark names\fR''. +returned by future calls to +.QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE .TP +\fIpathName \fBpeer\fR \fIoption args\fR +.VS 8.5 +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 \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 +.VE 8.5 +.TP \fIpathName \fBscan\fR \fIoption args\fR This command is used to implement scanning on texts. It has two forms, depending on \fIoption\fR: @@ -1129,14 +1508,14 @@ two forms, depending on \fIoption\fR: .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 \fBscan dragto\fR commands. +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 -\fBscan mark\fR command for the widget. +\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 @@ -1161,7 +1540,13 @@ This is the default. \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. +is before \fIindex\fR +.VS 8.5 +(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. +.VE 8.5 .TP \fB\-exact\fR Use exact matching: the characters in the matching range must be @@ -1172,6 +1557,23 @@ This is the default. Treat \fIpattern\fR as a regular expression and match it against the text using the rules for regular expressions (see the \fBregexp\fR command for details). +.VS 8.5 +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. +.VE 8.5 +.TP +\fB\-nolinestop\fR +.VS 8.5 +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" . +.VE 8.5 .TP \fB\-nocase\fR Ignore case differences between the pattern and the text. @@ -1185,6 +1587,55 @@ 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 +.VS 8.5 +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. +.VE 8.5 +.TP +\fB\-overlap\fR +.VS 8.5 +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. +.VE 8.5 +.TP +\fB\-strictlimits\fR +.VS 8.5 +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. +.VE 8.5 +.TP \fB\-elide\fR Find elided (hidden) text as well. By default only displayed text is searched. @@ -1193,12 +1644,15 @@ searched. 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. -.LP -The matching range must be entirely within a single line of text. -For regular expression matching the newlines are removed from the ends -of the lines before matching: use the \fB$\fR feature in regular -expressions to match the end of a line. -For exact matching the newlines are retained. +.PP +.VS 8.5 +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. +.VE 8.5 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 @@ -1207,6 +1661,10 @@ 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 @@ -1229,7 +1687,7 @@ supported: \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 isn't tagged). +\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 @@ -1251,8 +1709,9 @@ 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 ``+'' then \fIscript\fR -augments an existing binding rather than replacing it). +(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 @@ -1262,9 +1721,8 @@ returns a list of all the sequences for which bindings have been defined for \fItagName\fR. .RS .PP -.VS The only events for which bindings may be specified are those related -to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, +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 @@ -1277,7 +1735,6 @@ changed. Note that these events are different than \fBEnter\fR and 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. -.VE .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 @@ -1301,11 +1758,11 @@ for the window as a whole. \fIpathName \fBtag cget\fR \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 \fBtag configure\fR -widget command. +\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 \fBconfigure\fR widget command except +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 @@ -1339,10 +1796,11 @@ 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 ``\fIpathName \fBtag\fR'' widget -command but haven't been deleted by a ``\fIpathName \fBtag delete\fR'' -widget command, even if no characters are currently marked with -the tag). +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 @@ -1398,11 +1856,11 @@ empty string is returned. \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 isn't affected). +\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 single character at -\fIindex1\fR is tagged. +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. @@ -1481,15 +1939,24 @@ span of the text is off-screen to the left. \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. +\fIWhat\fR must be \fBunits\fR, \fBpages\fR or \fBpixels\fR. +.VS 8.5 +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 +.VE 8.5 +\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 \fI?args\fR? @@ -1501,37 +1968,56 @@ It can take any of the following forms: \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 character in the +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 character just after -the last one in the bottom line of the window, +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 character given by \fIfraction\fR -appears on the top line of the window. +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 -character in the text, 0.33 indicates the character one-third the -way through the text, and so on. +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. +.VS 8.5 +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. +.VE 8.5 .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. -\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 on the display; if it is \fBpages\fR then -the view adjusts by \fInumber\fR screenfuls. +\fIWhat\fR must be \fBunits\fR, \fBpages\fR or \fBpixels\fR. +.VS 8.5 +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. +.VE 8.5 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 isn't specified then \fIindex\fR will +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: @@ -1548,9 +2034,9 @@ it will be positioned at the bottom of the window. .IP [4] Otherwise, \fIindex\fR will be centered in the window. .LP -The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget -command (\fBsee\fR handles both x- and y-motion to make a location -visible, whereas \fB\-pickplace\fR only handles motion in y). +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 @@ -1563,8 +2049,10 @@ This command used to be used for scrolling, but now it is obsolete. .PP Tk automatically creates class bindings for texts that give them the following default behavior. -In the descriptions below, ``word'' is dependent on the value of -the \fBtcl_wordchars\fR variable. See tclvars(n). +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 @@ -1573,12 +2061,12 @@ 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. +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 end of the line. +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] @@ -1632,21 +2120,19 @@ 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. -Control-v moves the view down one screenful without moving the -insertion cursor or adjusting the selection. .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 line and clear any selection in the widget. -Shift-Home moves the insertion cursor to the beginning of the line +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 line and clear any selection in the widget. -Shift-End moves the cursor to the end of the line and extends the selection -to that point. +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. @@ -1659,7 +2145,7 @@ 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 don't affect the current selection. +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. @@ -1670,24 +2156,18 @@ 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. -.VS 8.4 This action is carried out by the command \fBtk_textCopy\fR. -.VE 8.4 .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. -.VS 8.4 This action is carried out by the command \fBtk_textCut\fR. -.VE 8.4 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. -.VS 8.4 This action is carried out by the command \fBtk_textPaste\fR. -.VE 8.4 .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 @@ -1716,16 +2196,14 @@ 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. +the insertion cursor. .IP [32] -.VS 8.4 Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is true) 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. -.VE 8.4 .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, @@ -1734,7 +2212,34 @@ take place. .PP The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings. -.SH "PERFORMANCE ISSUES" +.SH "KNOWN ISSUES" +.SS "ISSUES CONCERNING CHARS AND INDICES" +.VS 8.5 +.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" . +.VE 8.5 +.SS "PERFORMANCE ISSUES" .PP Text widgets should run efficiently under a variety of conditions. The text widget uses about 2-3 bytes of @@ -1766,10 +2271,64 @@ 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 \fBinsertOffTime\fP attribute to 0 avoid this. - +Set the \fBinsertOffTime\fR attribute to 0 avoid this. +.SS "KNOWN BUGS" +.VS 8.5 +.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 [text .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 [text .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. +.VE 8.5 .SH "SEE ALSO" entry(n), scrollbar(n) - .SH KEYWORDS text, widget, tkvars @@ -26,13 +26,17 @@ 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 isn't specified, this command returns the name +. +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 -``\fB #2\fR'' or ``\fB #3\fR'' is appended in order to make the name unique. +.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 @@ -41,7 +45,6 @@ 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. -.VS 8.4 .TP \fBtk caret window \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . @@ -54,7 +57,6 @@ the last values used for setting the caret are return in option-value pair format. \fI\-x\fR and \fI\-y\fR represent window-relative coordinates, and \fI\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. -.VE .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . @@ -66,7 +68,9 @@ 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 ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor +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 @@ -78,25 +82,41 @@ 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 -.VS 8.3 +.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 and +error if tried. +.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 (ie: Japanese, Korean), to handle special input devices. This +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. -.VE -.VS 8.4 .TP \fBtk windowingsystem\fR . Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), -\fBclassic\fR (Mac OS Classic), or \fBaqua\fR (Mac OS X Aqua). -.VE +or \fBaqua\fR (Mac OS X Aqua). +.SH "SEE ALSO" +send(n), winfo(n) .SH KEYWORDS application name, send diff --git a/doc/tkvars.n b/doc/tkvars.n index da7410e..9971698 100644 --- a/doc/tkvars.n +++ b/doc/tkvars.n @@ -29,7 +29,7 @@ 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 isn't set or doesn't refer to an appropriate +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 diff --git a/doc/toplevel.n b/doc/toplevel.n index c1f0081..e02eb35 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -72,7 +72,7 @@ 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 isn't an empty string, +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 diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 new file mode 100644 index 0000000..5a0ce4f --- /dev/null +++ b/doc/ttk_Geometry.3 @@ -0,0 +1,223 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH Geometry 3 8.5 Tk "Tk Themed Widget" +.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 pixles) 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 contsructs +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 contsructs +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/doc/ttk_Theme.3 b/doc/ttk_Theme.3 new file mode 100644 index 0000000..acd0e98 --- /dev/null +++ b/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. +'\" +.so man.macros +.TH Ttk_CreateTheme 3 8.5 Tk "Tk Themed Widget" +.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/doc/ttk_button.n b/doc/ttk_button.n new file mode 100644 index 0000000..c6f2308 --- /dev/null +++ b/doc/ttk_button.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. +'\" +.so man.macros +.TH ttk::button n 8.5 Tk "Tk Themed Widget" +.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 +.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. +Note that some themes may specify a non-zero \fB\-width\fR +in the style. +.\" Not documented -- may go away +.\" .OP \-padding padding Padding +.\" .OP \-foreground foreground Foreground +.\" .OP \-font font Font +.\" .OP \-anchor anchor Anchor +.\" .OP \-padding padding Padding +.\" .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 "COMPATIBILITY OPTIONS" +.OP \-state state State +May be set to \fBnormal\fR or \fBdisabled\fR to control the +\fBdisabled\fR state bit. This is a +.QW write-only +option: setting it changes the widget state, but the \fBstate\fR +widget command does not affect the state option. +.SH "SEE ALSO" +ttk::widget(n), button(n) +.SH "KEYWORDS" +widget, button, default, command +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n new file mode 100644 index 0000000..07b3205 --- /dev/null +++ b/doc/ttk_checkbutton.n @@ -0,0 +1,77 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::checkbutton n 8.5 Tk "Tk Themed Widget" +.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 "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/doc/ttk_combobox.n b/doc/ttk_combobox.n new file mode 100644 index 0000000..e01c6f6 --- /dev/null +++ b/doc/ttk_combobox.n @@ -0,0 +1,119 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::combobox n 8.5 Tk "Tk Themed Widget" +.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 "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/doc/ttk_entry.n b/doc/ttk_entry.n new file mode 100644 index 0000000..b42bd31 --- /dev/null +++ b/doc/ttk_entry.n @@ -0,0 +1,470 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::entry n 8.5 Tk "Tk Themed Widget" +.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 \fBvalidateCommand\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 \fBexportSelection\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 \fBxScrollCommand\fR mechanism for interacting with +scrollbars (see the description of the \fBxScrollCommand\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 "SEE ALSO" +ttk::widget(n), entry(n) +.SH KEYWORDS +entry, widget, text field +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n new file mode 100644 index 0000000..9dcf2dc --- /dev/null +++ b/doc/ttk_frame.n @@ -0,0 +1,56 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::frame n 8.5 Tk "Tk Themed Widget" +.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 \-takefocus +\-style +.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 \-padding padding Padding +Additional padding to include inside the border. +.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 "SEE ALSO" +ttk::widget(n), ttk::labelframe(n), frame(n) +.SH "KEYWORDS" +widget, frame, container +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_image.n b/doc/ttk_image.n new file mode 100644 index 0000000..3d8b13c --- /dev/null +++ b/doc/ttk_image.n @@ -0,0 +1,82 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk_image n 8.5 Tk "Tk Themed Widget" +.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. +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. 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/doc/ttk_intro.n b/doc/ttk_intro.n new file mode 100644 index 0000000..cb0c440 --- /dev/null +++ b/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. +'\" +.so man.macros +.TH ttk::intro n 8.5 Tk "Tk Themed Widget" +.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/doc/ttk_label.n b/doc/ttk_label.n new file mode 100644 index 0000000..66dafeb --- /dev/null +++ b/doc/ttk_label.n @@ -0,0 +1,78 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::label n 8.5 Tk "Tk Themed Widget" +.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 \-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 \-padding padding Padding +Specifies the amount of extra space to allocate 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. +.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 "SEE ALSO" +ttk::widget(n), label(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n new file mode 100644 index 0000000..e782f87 --- /dev/null +++ b/doc/ttk_labelframe.n @@ -0,0 +1,76 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::labelframe n 8.5 Tk "Tk Themed Widget" +.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 \-takefocus +\-style +.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 \-padding padding Padding +Additional padding to include inside the border. +.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 "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/doc/ttk_menubutton.n b/doc/ttk_menubutton.n new file mode 100644 index 0000000..99b7c4d --- /dev/null +++ b/doc/ttk_menubutton.n @@ -0,0 +1,54 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::menubutton n 8.5 Tk "Tk Themed Widget" +.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 "SEE ALSO" +ttk::widget(n), menu(n), menubutton(n) +.SH "KEYWORDS" +widget, button, menu +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n new file mode 100644 index 0000000..c0de39e --- /dev/null +++ b/doc/ttk_notebook.n @@ -0,0 +1,213 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::notebook n 8.5 Tk "Tk Themed Widget" +.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. +.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\fR \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\fR \fIoption\fR +See \fIttk::widget(n)\fR. +.TP +\fIpathname \fBforget\fR \fItabid\fR +Removes the tab specified by \fItabid\fR, +unmaps and unmanages the associated window. +.TP +\fIpathname \fBhide\fR \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\fR \fIcomponent\fR \fIx\fR \fIy\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\fR \fBelement\fR \fIx\fR \fIy\fR +Returns the name of the element at the specified location. +.TP +\fIpathname \fBidentify\fR \fBtab\fR \fIx\fR \fIy\fR +Returns the index of the tab at the specified location. +.RE +.TP +\fIpathname \fBindex\fR \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\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\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\fR \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\fR \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. +.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 +\fBShift-Control-Tab\fR selects the tab preceding the currently selected one. +.IP \(bu +\fBAlt-K\fR, where \fBK\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 "SEE ALSO" +ttk::widget(n), grid(n) +.SH "KEYWORDS" +pane, tab +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n new file mode 100644 index 0000000..c5851c3 --- /dev/null +++ b/doc/ttk_panedwindow.n @@ -0,0 +1,112 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::panedwindow n 8.5.9 Tk "Tk Themed Widget" +.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\fR \fBadd\fR \fIsubwindow\fR \fIoptions...\fR +Adds a new pane to the window. +See \fBPANE OPTIONS\fR for the list of available options. +.TP +\fIpathname\fR \fBforget\fR \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\fR \fBidentify\fR \fIcomponent\fR \fIx\fR \fIy\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\fR \fBidentify\fR \fBelement\fR \fIx\fR \fIy\fR +Returns the name of the element at the specified location. +.TP +\fIpathname\fR \fBidentify\fR \fBsash\fR \fIx\fR \fIy\fR +Returns the index of the sash at the specified location. +.RE +.TP +\fIpathname\fR \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\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\fR \fBpane\fR \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\fR \fBpanes\fR +Returns the list of all windows managed by the widget. +.TP +\fIpathname\fR \fBsashpos\fR \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. +.SH "SEE ALSO" +ttk::widget(n), ttk::notebook(n), panedwindow(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n new file mode 100644 index 0000000..9381c61 --- /dev/null +++ b/doc/ttk_progressbar.n @@ -0,0 +1,93 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::progressbar n 8.5 Tk "Tk Themed Widget" +.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 \-orient orient Orient +One of \fBhorizontal\fR or \fBvertical\fR. +Specifies the orientation of the progress bar. +.OP \-length length Length +Specifies the length of the long axis of the progress bar +(width if horizontal, height if vertical). +.OP \-mode mode Mode +One of \fBdeterminate\fR or \fBindeterminate\fR. +.OP \-maximum maximum Maximum +A floating point number specifying the maximum \fB\-value\fR. +Defaults to 100. +.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. +.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. +.SH "WIDGET COMMAND" +.PP +.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 \fBidentify\fR \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 "SEE ALSO" +ttk::widget(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n new file mode 100644 index 0000000..cbea359 --- /dev/null +++ b/doc/ttk_radiobutton.n @@ -0,0 +1,74 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::radiobutton n 8.5 Tk "Tk Themed Widget" +.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 \fI\-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 "SEE ALSO" +ttk::widget(n), ttk::checkbutton(n), radiobutton(n) +.SH "KEYWORDS" +widget, button, option +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_scale.n b/doc/ttk_scale.n new file mode 100644 index 0000000..2fd485b --- /dev/null +++ b/doc/ttk_scale.n @@ -0,0 +1,101 @@ +.\" +.\" 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. +.\" +.so man.macros +.TH ttk::scale n 8.5 Tk "Tk Themed Widget" +.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 \fBfrom\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\fR \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 "SEE ALSO" +ttk::widget(n), scale(n) +.SH KEYWORDS +scale, slider, trough, widget +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n new file mode 100644 index 0000000..ce9eeed --- /dev/null +++ b/doc/ttk_scrollbar.n @@ -0,0 +1,163 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::scrollbar n 8.5 Tk "Tk Themed Widget" +.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\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 \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\fR \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 \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 "SEE ALSO" +ttk::widget(n), scrollbar(n) +.SH KEYWORDS +scrollbar, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_separator.n b/doc/ttk_separator.n new file mode 100644 index 0000000..78114bd --- /dev/null +++ b/doc/ttk_separator.n @@ -0,0 +1,38 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::separator n 8.5 Tk "Tk Themed Widget" +.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 \-state +\-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. +.SH "SEE ALSO" +ttk::widget(n) +.SH "KEYWORDS" +widget, separator +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n new file mode 100644 index 0000000..38de1ed --- /dev/null +++ b/doc/ttk_sizegrip.n @@ -0,0 +1,69 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::sizegrip n 8.5 Tk "Tk Themed Widget" +.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 \-state +\-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 "SEE ALSO" +ttk::widget(n) +.SH "KEYWORDS" +widget, sizegrip, grow box +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n new file mode 100644 index 0000000..fefd287 --- /dev/null +++ b/doc/ttk_spinbox.n @@ -0,0 +1,86 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::spinbox n 8.5.9 Tk "Tk Themed Widget" +.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 \-style +\-takefocus \-xscrollcommand +.SE +.SO ttk_entry +\-validate \-validatecommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-from from From +A floating\-point value specifying the lowest value for the spinbox. This is +used in conjunction with \fI\-to\fR and \fI\-increment\fR to set a numerical +range. +.OP \-to to To +A floating\-point value specifying the highest permissible value for the +widget. See also \fI\-from\fR and \fI\-increment\fR. +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 \-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 \fI\-from\fR, \fI\-to\fR and +\fI\-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. +.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 \-command command Command +Specifies a Tcl command to be invoked whenever a spinbutton is invoked. +.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 +\fI\-validate\fR and \fI\-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 \fBcurrent \fIindex\fR +.TP +\fIpathName \fBget\fR +Returns the spinbox's current value. +.TP +\fIpathName \fBset \fIvalue\fR +Set the spinbox string to \fIvalue\fR. If a \fI\-format\fR option has +been configured then this format will be applied. If formatting fails +or is not set or the \fI\-values\fR option has been used then the value +is set directly. +.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/doc/ttk_style.n b/doc/ttk_style.n new file mode 100644 index 0000000..c32b028 --- /dev/null +++ b/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. +'\" +.so man.macros +.TH ttk::style n 8.5 Tk "Tk Themed Widget" +.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/doc/ttk_treeview.n b/doc/ttk_treeview.n new file mode 100644 index 0000000..33cca55 --- /dev/null +++ b/doc/ttk_treeview.n @@ -0,0 +1,484 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::treeview n 8.5.9 Tk "Tk Themed Widget" +.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 +.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 \-padding padding Padding +Specifies the internal padding for the widget. +The padding is a list of up to four length specifications; +see \fBTtk_GetPaddingFromObj()\fR for details. +.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\fR \fItag\fR \fIitems\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\fR \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 "SEE ALSO" +ttk::widget(n), listbox(n), image(n), bind(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n new file mode 100644 index 0000000..7506ec4 --- /dev/null +++ b/doc/ttk_vsapi.n @@ -0,0 +1,102 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk_vsapi n 8.5 Tk "Tk Themed Widget" +.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 \fIvsapi\fR element factory creates a new element +in the current theme whose visual appearance is drawn using the +Microsoft Visual Styles API which is reponsible 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\fR \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. +This option may not be mixed with any other options. +.TP +\fB\-margins\fR \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\fR \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 \fI-height\fR should +also be set. The \fI-width\fR and \fI-height\fR options cannot +be mixed with the \fI-padding\fR or \fI-margins\fR options. +.TP +\fB\-height\fR \fIheight\fR +Specifies the height of the element. See the comments for \fI-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 appearence 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 and +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 vsapi 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 appearence of a \fBttk::checkbutton\fR(n) to use the +Explorer pin part EBP_HEADERPIN. +.CS +ttk::style element create pin vsapi 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/doc/ttk_widget.n b/doc/ttk_widget.n new file mode 100644 index 0000000..98968ad --- /dev/null +++ b/doc/ttk_widget.n @@ -0,0 +1,262 @@ +'\" +'\" 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. +'\" +.so man.macros +.TH ttk::widget n 8.5.9 Tk "Tk Themed Widget" +.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 \fBxScrollCommand\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 \-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 \-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 \-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 \-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" +.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\fR \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\fR \fBelement\fR \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\fR \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 state disabled + +# Invoke the widget only if it is currently pressed and enabled: +$b instate {pressed !disabled} { .b invoke } + +# Reenable widget: +$b state !disabled +.CE +.SH "SEE ALSO" +ttk::intro(n), ttk::style(n) +.SH KEYWORDS +state, configure, option +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/winfo.n b/doc/winfo.n index fe62071..4b75eb9 100644 --- a/doc/winfo.n +++ b/doc/winfo.n @@ -55,9 +55,11 @@ 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 ``known'' to be full if the last +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 hasn't freed any colors in the colormap since the +application has not freed any colors in the colormap since the failed allocation. .TP \fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR @@ -88,7 +90,10 @@ window exists. 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 ``2.0c'' or ``1i''. +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 @@ -108,12 +113,10 @@ or use \fBwinfo reqheight\fR to get the window's requested height instead of its actual height. .TP \fBwinfo id \fIwindow\fR -.VS 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. -.VE .TP \fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? Returns a list whose members are the names of all Tcl interpreters @@ -128,7 +131,7 @@ Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. \fBwinfo manager \fIwindow\fR Returns the name of the geometry manager currently responsible for \fIwindow\fR, or an empty string if \fIwindow\fR -isn't managed by any geometry manager. +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 @@ -155,7 +158,10 @@ the display of the application's main window. 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 ``2.0c'' or ``1i''. +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 @@ -164,7 +170,7 @@ 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 isn't on the same screen as \fIwindow\fR then +If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. .TP \fBwinfo pointerxy \fIwindow\fR @@ -173,15 +179,15 @@ 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 isn't on the same screen as \fIwindow\fR then -both of the returned coordinates are -1. +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 isn't on the same screen as \fIwindow\fR then +If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. .TP \fBwinfo reqheight \fIwindow\fR @@ -252,14 +258,17 @@ in pixels. 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 ``\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR'' +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-level window containing \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 @@ -328,9 +337,8 @@ has no border). .SH EXAMPLE Print where the mouse pointer is and what window it is currently over: .CS -set x [\fBwinfo pointerx\fR .] -set y [\fBwinfo pointery\fR .] -puts -nonewline "Mouse pointer at ($x,$y) which is " +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" @@ -12,8 +12,13 @@ .SH NAME wish \- Simple windowing shell .SH SYNOPSIS -\fBwish\fR ?\fIfileName arg arg ...\fR? +\fBwish\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? .SH OPTIONS +.IP "\fB\-encoding \fIname\fR" 20 +.VS 8.5 +Specifies the encoding of the text stored in \fIfileName\fR. +This option is only recognized prior to the \fIfileName\fR argument. +.VE 8.5 .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. @@ -30,14 +35,17 @@ as the name of the interpreter for \fBsend\fR commands. 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. -.VS 8.0 br .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). -.VE +.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 @@ -48,47 +56,60 @@ 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 no arguments, or with a first argument -that starts with ``\-'', then it reads Tcl commands interactively from -standard input. +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 \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. +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 \fBwish\fR is invoked with an initial \fIfileName\fR argument, then +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 \fB.wishrc\fR when the name -of a script file is presented on the \fBwish\fR command line, +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. - -.SH "OPTIONS" +.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 ``/'' +\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 @@ -96,7 +117,6 @@ 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: @@ -107,8 +127,8 @@ 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 don't match any of the -options described in OPTIONS above, in order, or an empty string +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 @@ -126,7 +146,6 @@ window's geometry. 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 @@ -136,8 +155,8 @@ If you create a Tcl script in a file whose first line is 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's installed somewhere else -then you'll have to modify the above line to match. +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. @@ -150,7 +169,7 @@ following three lines: 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 doesn't have +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. @@ -168,27 +187,31 @@ 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 -.VS 8.4 The end of a script file may be marked either by the physical end of -the medium, or by the character, '\\032' ('\\u001a', control-Z). +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 -``\\032'', ``\\x1a'', or ``\\u001a''; or may generate it by use of commands -such as \fBformat\fR or \fBbinary\fR. -.VE +.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 ``\fB% \fR''. You can change the prompt by setting the +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 isn't yet complete; -if \fBtcl_prompt2\fR isn't set then no prompt is output for +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 KEYWORDS shell, toolkit @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH wm n 8.4 Tk "Tk Built-In Commands" +.TH wm n 8.5 Tk "Tk Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -14,7 +14,6 @@ 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 @@ -42,7 +41,6 @@ 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). -.VS 8.4 .TP \fBwm attributes \fIwindow\fR .TP @@ -54,66 +52,85 @@ 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: -.PP -On Windows, the following attributes may be set. .RS +.PP +All platforms support the following attributes (though X11 users +should see the notes below): .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). +\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\-alpha\fR +.VS 8.5 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. This is supported on Windows 2000/XP+. Where not supported, the \fB\-alpha\fR value remains at \fB1.0\fR. +.VE 8.5 +.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 +.VS 8.5 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. -.RE +.VE 8.5 .PP On Mac OS X, the following attributes may be set. -.RS +.TP +\fB\-alpha\fR +Specifies the alpha transparency level of the window. +It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque), +values outside that range will be constrained. .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\-alpha\fR -Specifies the alpha transparency level of the window. -It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque), -values outside that range will be constrained. -.TP -\fB\-topmost\fR -Specifies whether this is a topmost window (displays above all other windows). -.TP \fB\-transparent\fR Makes the window content area transparent and turns off the window shadow. For the transparency to be effecive, the toplevel background needs to be set to a -color with some alpha, e.g. "systemTransparent". -.TP -\fB\-fullscreen\fR -Places the window in a mode that takes up the entire main screen and hides -the dock and menu bar. -.RE +color with some alpha, e.g. +.QW systemTransparent . .PP -On X11, there are currently no special attribute values. -.VE 8.4 +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\-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 @@ -122,7 +139,7 @@ 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 isn't specified, the command returns the last name +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. @@ -131,7 +148,9 @@ If \fIname\fR is specified as an empty string, the command deletes the 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. -If \fIwindowList\fR isn't specified, the command returns a list +.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 @@ -140,6 +159,7 @@ 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. @@ -152,6 +172,7 @@ 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 @@ -159,7 +180,7 @@ If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's 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 isn't specified then the command returns the last value +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. @@ -179,6 +200,8 @@ 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 @@ -188,16 +211,22 @@ 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 -.VS 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 -hasn't been reparented by the window manager then the command returns +has not been reparented by the window manager then the command returns the platform specific window identifier for \fIwindow\fR. -.VE .TP \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR @@ -209,9 +238,12 @@ 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 GRIDDED GEOMETRY MANAGEMENT below) then the dimensions +is gridded (see \fBGRIDDED GEOMETRY MANAGEMENT\fR below) then the dimensions are specified in grid units; otherwise they are specified in pixel -units. \fIX\fR and \fIy\fR specify the desired location of +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 @@ -223,10 +255,12 @@ 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. +.RE .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? This command indicates that \fIwindow\fR is to be managed as a @@ -243,20 +277,25 @@ 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 @@ -266,7 +305,7 @@ 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 isn't part of any group. +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 @@ -280,7 +319,9 @@ 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: -\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?. +.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. @@ -291,9 +332,10 @@ 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 hasn't +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 @@ -315,11 +357,35 @@ returns the name of the current icon mask associated with 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 isn't specified +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). +.VS 8.5 +.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, this currently does nothing. +.VE 8.5 +.RE .TP \fBwm iconposition \fIwindow\fR ?\fIx y\fR? If \fIx\fR and \fIy\fR are specified, they are passed to the window @@ -342,10 +408,19 @@ 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 ``own'' those events. +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. @@ -400,7 +475,8 @@ 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 -``no source'' as equivalent to \fBprogram\fR. +.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. @@ -419,7 +495,7 @@ 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 isn't, then the current +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 @@ -432,8 +508,8 @@ are currently defined for \fIwindow\fR. .RS .PP Tk always defines a protocol handler for \fBWM_DELETE_WINDOW\fR, even if -you haven't asked for one with \fBwm protocol\fR. -If a \fBWM_DELETE_WINDOW\fR message arrives when you haven't defined +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 @@ -467,18 +543,19 @@ 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 -``no source'' as equivalent to \fBprogram\fR. +.QW "no source" +as equivalent to \fBprogram\fR. .TP -\fBwm stackorder \fIwindow\fR ?\fIisabove|isbelow window\fR? -The stackorder command returns a list of toplevel windows +\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 stackorder command can also be used to determine if one +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 \fIisabove\fR or -\fIisbelow\fR are passed, a boolean result indicates whether +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 @@ -497,7 +574,7 @@ iconwindow\fR command). The \fBicon\fR state cannot be set. 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 isn't +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 @@ -509,7 +586,7 @@ 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 isn't currently a transient window. +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. @@ -552,6 +629,21 @@ 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 @@ -588,7 +680,7 @@ 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 won't +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 @@ -622,9 +714,7 @@ set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] \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 |