diff options
Diffstat (limited to 'doc')
153 files changed, 4669 insertions, 3651 deletions
diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index b41b84f..f2f0eb8 100644 --- a/doc/3DBorder.3 +++ b/doc/3DBorder.3 @@ -64,12 +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 -Pointer to object whose value describes color corresponding to +Pointer to value whose value describes color corresponding to background (flat areas). Illuminated edges will be brighter than this and shadowed edges will be darker than this. .AP char *colorName in Same as \fIobjPtr\fR except value is supplied as a string rather -than an object. +than a value. .AP Drawable drawable in X token for window or pixmap; indicates where graphics are to be drawn. Must either be the X window for \fItkwin\fR or a pixmap with the @@ -91,7 +91,7 @@ Width of border in pixels. Positive means border is inside rectangle given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means border is outside rectangle. .AP int relief in -Indicates 3-D position of interior of object relative to exterior; +Indicates 3-D position of interior of value relative to exterior; should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR for \fBTk_Fill3DRectangle\fR). @@ -114,7 +114,7 @@ should appear higher; 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 +Non-zero means this bevel forms the left side of the value; zero means it forms the right side. .AP int leftIn in Non-zero means that the left edge of the horizontal bevel angles in, @@ -128,13 +128,12 @@ so that the bottom of the edge is farther to the left than the top. Zero means the edge angles out, so that the bottom is farther to the right than the top. .AP int topBevel in -Non-zero means this bevel forms the top side of the object; zero means +Non-zero means this bevel forms the top side of the value; zero means it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. .BE - .SH DESCRIPTION .PP These procedures provide facilities for drawing window borders in a @@ -153,14 +152,15 @@ darker than \fIobjPtr\fR. \fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information for the border (e.g. a bogus color name was given) -then NULL is returned and an error message is left in \fIinterp->result\fR. +then NULL is returned and an error message is left as the result of +interpreter \fIinterp\fR. If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except -that the color is specified with a string instead of an object. This +that the color is specified with a string instead of a value. This prevents \fBTk_Get3DBorder\fR from caching the return value, so \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. .PP @@ -238,8 +238,8 @@ arguments that describe the rectangular area of the beveled edge The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the position of the border relative to the .QW inside -of the object, and -\fIrelief\fR indicates the relief of the inside of the object relative +of the value, and +\fIrelief\fR indicates the relief of the inside of the value relative to the outside. \fBTk_3DVerticalBevel\fR just draws a rectangular region. \fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate @@ -290,6 +290,5 @@ with the Tk_3DBorder token for the border. There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. - .SH KEYWORDS -3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect +3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect diff --git a/doc/AddOption.3 b/doc/AddOption.3 index 8b921e2..2368f09 100644 --- a/doc/AddOption.3 +++ b/doc/AddOption.3 @@ -23,7 +23,6 @@ Value of option. .AP int priority in Overall priority level to use for option. .BE - .SH DESCRIPTION .PP This procedure is invoked to add an option to the database @@ -47,6 +46,5 @@ user-specific startup files. .IP 80 Used for options specified interactively after the application starts running. - .SH KEYWORDS class, name, option, add diff --git a/doc/BindTable.3 b/doc/BindTable.3 index 34a2101..5130bfc 100644 --- a/doc/BindTable.3 +++ b/doc/BindTable.3 @@ -45,7 +45,7 @@ call to \fBTk_CreateBindingTable\fR. Identifies object with which binding is associated. .AP "const char" *eventString in String describing event sequence. -.AP char *script in +.AP "const char" *script in Tcl script to invoke when binding triggers. .AP int append in Non-zero means append \fIscript\fR to existing script for binding, @@ -61,7 +61,6 @@ Number of object identifiers pointed to by \fIobjectPtr\fR. Points to an array of object identifiers: bindings will be considered for each of these objects in order from first to last. .BE - .SH DESCRIPTION .PP These procedures provide a general-purpose mechanism for creating @@ -112,25 +111,25 @@ select relevant events, or to disallow the use of certain events in bindings. If an error occurred while creating the binding (e.g., \fIeventString\fR refers to a non-existent event), then 0 is returned and an error -message is left in \fIinterp->result\fR. +message is left as the result of interpreter \fIinterp\fR. .PP \fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the binding given by \fIobject\fR and \fIeventString\fR, if such a binding exists. \fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR. -In some cases it may reset \fIinterp->result\fR to the default +In some cases it may reset the interpreter result to the default empty value. .PP \fBTk_GetBinding\fR returns a pointer to the script associated with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR. If no such binding exists then NULL is returned and an error -message is left in \fIinterp->result\fR. +message is left as the result of interpreter \fIinterp\fR. .PP -\fBTk_GetAllBindings\fR returns in \fIinterp->result\fR a list +\fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list of all the event strings for which there are bindings in \fIbindingTable\fR associated with \fIobject\fR. -If there are no bindings for \fIobject\fR then an empty -string is returned in \fIinterp->result\fR. +If there are no bindings for \fIobject\fR, the result will be an empty +string. .PP \fBTk_DeleteAllBindings\fR deletes all of the bindings in \fIbindingTable\fR that are associated with \fIobject\fR. @@ -150,6 +149,5 @@ the object is skipped. \fBTk_BindEvent\fR continues through all of the objects, handling exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as described in the documentation for \fBbind\fR. - .SH KEYWORDS binding, event, object, script diff --git a/doc/CanvPsY.3 b/doc/CanvPsY.3 index 91109ea..5e104ce 100644 --- a/doc/CanvPsY.3 +++ b/doc/CanvPsY.3 @@ -61,7 +61,6 @@ and so on. .AP int numPoints in Number of points at \fIcoordPtr\fR. .BE - .SH DESCRIPTION .PP These procedures are called by canvas type managers to carry out @@ -83,38 +82,40 @@ 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 \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. +The Postscript is appended to the result of interpreter \fIinterp\fR +and \fBTCL_OK\fR is returned unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter result is overwritten +with an error message. .PP \fBTk_CanvasPsColor\fR generates Postscript to set the current color to correspond to its \fIcolorPtr\fR argument, taking into account any color map specified in the \fBpostscript\fR command. -It appends the Postscript to \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. +It appends the Postscript to the interpreter \fIinterp\fR's result and returns +\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is +returned and the interpreter's result is overwritten with an error message. .PP \fBTk_CanvasPsFont\fR generates Postscript that sets the current font to match \fItkFont\fR as closely as possible. \fBTk_CanvasPsFont\fR takes into account any font map specified in the \fBpostscript\fR command, and it does the best it can at mapping X fonts to Postscript fonts. -It appends the Postscript to \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. +It appends the Postscript to interpreter \fIinterp\fR's result and +returns \fBTCL_OK\fR unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter's result is +overwritten with an error message. .PP \fBTk_CanvasPsPath\fR generates Postscript to set the current path to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR. -It appends the resulting Postscript to \fIinterp->result\fR. +It appends the resulting Postscript to the result of interpreter \fIinterp\fR. .PP \fBTk_CanvasPsStipple\fR generates Postscript that will fill the current path in stippled fashion. It uses \fIbitmap\fR as the stipple pattern and the current Postscript color; ones in the stipple bitmap are drawn in the current color, and zeroes are not drawn at all. -The Postscript is appended to \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. - +The Postscript is appended to interpreter \fIinterp\fR's result and +\fBTCL_OK\fR is returned, unless an error occurs, in which case +\fBTCL_ERROR\fR is returned and the interpreter's result is +overwritten with an error message. .SH KEYWORDS bitmap, canvas, color, font, path, Postscript, stipple diff --git a/doc/CanvTkwin.3 b/doc/CanvTkwin.3 index 05ffca2..d53c5b1 100644 --- a/doc/CanvTkwin.3 +++ b/doc/CanvTkwin.3 @@ -71,7 +71,6 @@ the left of this coordinate need to be redisplayed. Bottom edge of the region that needs redisplay. Only pixels above this coordinate need to be redisplayed. .BE - .SH DESCRIPTION .PP These procedures are called by canvas type managers to perform various @@ -86,7 +85,7 @@ canvas coordinate. If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR stores the corresponding canvas coordinate at *\fIdoublePtr\fR and returns \fBTCL_OK\fR. -Otherwise it stores an error message in \fIinterp->result\fR and +Otherwise it stores an error message in the interpreter result and returns \fBTCL_ERROR\fR. .PP \fBTk_CanvasDrawableCoords\fR is called by type managers during @@ -142,18 +141,18 @@ The code of a canvas type manager will not call these procedures directly, but will use their addresses to create a \fBTk_CustomOption\fR structure for the \fB\-tags\fR option. The code typically looks like this: +.PP .CS -static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, +static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, Tk_CanvasTagsPrintProc, (ClientData) NULL }; -static Tk_ConfigSpec configSpecs[] = { +static const Tk_ConfigSpec configSpecs[] = { ... - {TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL, - (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, + {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL, + NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, ... }; .CE - .SH KEYWORDS canvas, focus, item type, redisplay, selection, type manager diff --git a/doc/CanvTxtInfo.3 b/doc/CanvTxtInfo.3 index a4c0d3b..92a2bc3 100644 --- a/doc/CanvTxtInfo.3 +++ b/doc/CanvTxtInfo.3 @@ -20,7 +20,6 @@ Tk_CanvasTextInfo * .AP Tk_Canvas canvas in A token that identifies a particular canvas widget. .BE - .SH DESCRIPTION .PP Textual canvas items are somewhat more complicated to manage than @@ -47,7 +46,7 @@ typedef struct Tk_CanvasTextInfo { Tk_Item *\fIfocusItemPtr\fR; int \fIgotFocus\fR; int \fIcursorOn\fR; -} Tk_CanvasTextInfo; +} \fBTk_CanvasTextInfo\fR; .CE The \fBselBorder\fR field identifies a Tk_3DBorder that should be used for drawing the background under selected text. @@ -97,6 +96,5 @@ anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR). If all of the selected text in the item is deleted, the item should set \fIselItemPtr\fR to NULL to indicate that there is no longer a selection. - .SH KEYWORDS canvas, focus, insertion cursor, selection, selection anchor, text diff --git a/doc/Clipboard.3 b/doc/Clipboard.3 index 769b63b..3087777 100644 --- a/doc/Clipboard.3 +++ b/doc/Clipboard.3 @@ -31,10 +31,9 @@ Conversion type for this clipboard item; has same meaning as .AP Atom format in Representation to use when data is retrieved; has same meaning as \fIformat\fR argument to \fBTk_CreateSelHandler\fR. -.AP char *buffer in +.AP "const char" *buffer in Null terminated string containing the data to be appended to the clipboard. .BE - .SH DESCRIPTION .PP These two procedures manage the clipboard for Tk. @@ -43,9 +42,10 @@ once, then calling \fBTk_ClipboardAppend\fR to add data for any number of targets. .PP \fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any -data items previously stored on the clipboard in this application. +data items previously stored on the clipboard in this application. It normally returns \fBTCL_OK\fR, but if an error occurs it returns -\fBTCL_ERROR\fR and leaves an error message in \fIinterp->result\fR. +\fBTCL_ERROR\fR and leaves an error message in interpreter +\fIinterp\fR's result. \fBTk_ClipboardClear\fR must be called before a sequence of \fBTk_ClipboardAppend\fR calls can be issued. .PP @@ -60,8 +60,8 @@ currently owned by the application, either because \fBTk_ClipboardClear\fR has not been called or because ownership of the clipboard has changed since the last call to \fBTk_ClipboardClear\fR, -\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error message in -\fIinterp->result\fR. +\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error +message in the result of interpreter \fIinterp\fR. .PP In order to guarantee atomicity, no event handling should occur between \fBTk_ClipboardClear\fR and the following @@ -71,8 +71,7 @@ this application). .PP \fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary Tcl scripts, as a result of losing the CLIPBOARD selection, so -any calling function should take care to be reentrant at the point +any calling function should take care to be re-entrant at the point \fBTk_ClipboardClear\fR is invoked. - .SH KEYWORDS append, clipboard, clear, format, type diff --git a/doc/ClrSelect.3 b/doc/ClrSelect.3 index 963260e..c56f63c 100644 --- a/doc/ClrSelect.3 +++ b/doc/ClrSelect.3 @@ -23,10 +23,9 @@ window. .AP Atom selection in The name of selection to be cleared. .BE - .SH DESCRIPTION .PP -\fBTk_ClearSelection\fR cancels the selection specified by the atom +\fBTk_ClearSelection\fR cancels the selection specified by the atom \fIselection\fR for the display containing \fItkwin\fR. The selection need not be in \fItkwin\fR itself or even in \fItkwin\fR's application. @@ -35,6 +34,5 @@ owns \fIselection\fR, the window will be notified and the selection will be cleared. If there is no owner for \fIselection\fR on the display, then the procedure has no effect. - .SH KEYWORDS clear, selection diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 index 3abb4f5..ddc1030 100644 --- a/doc/ConfigWidg.3 +++ b/doc/ConfigWidg.3 @@ -25,12 +25,12 @@ int .sp \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR .SH ARGUMENTS -.AS Tk_ConfigSpec *widgRec in/out +.AS char *widgRec in/out .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window used to represent widget (needed to set up X resources). -.AP Tk_ConfigSpec *specs in +.AP "const Tk_ConfigSpec" *specs in Pointer to table specifying legal configuration options for this widget. .AP int argc in @@ -61,7 +61,7 @@ Display containing widget whose record is being freed; needed in order to free up resources. .BE .SH DESCRIPTION -.PP +.PP Note: \fBTk_ConfigureWidget\fR should be replaced with the new \fBTcl_Obj\fR based API \fBTk_SetOptions\fR. The old interface is retained for backward compatibility. @@ -89,7 +89,7 @@ to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. case it does not modify \fIinterp\fR. If an error occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will -leave an error message in \fIinterp->result\fR in the standard Tcl +leave an error message in interpreter \fIinterp\fR's result in the standard Tcl fashion. In the event of an error return, some of the fields of \fIwidgRec\fR could already have been set, if configuration information for them @@ -103,14 +103,14 @@ option and has the following structure: .CS typedef struct { int \fItype\fR; - char *\fIargvName\fR; - char *\fIdbName\fR; - char *\fIdbClass\fR; - char *\fIdefValue\fR; + const char *\fIargvName\fR; + const char *\fIdbName\fR; + const char *\fIdbClass\fR; + const char *\fIdefValue\fR; int \fIoffset\fR; int \fIspecFlags\fR; - Tk_CustomOption *\fIcustomPtr\fR; -} Tk_ConfigSpec; + const Tk_CustomOption *\fIcustomPtr\fR; +} \fBTk_ConfigSpec\fR; .CE The \fItype\fR field indicates what type of configuration option this is (e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for @@ -356,7 +356,6 @@ is an empty string then the target will be set to NULL. \fBTK_CONFIG_WINDOW\fR The value must be a window path name. It is translated to a \fBTk_Window\fR token and the token is stored in the target. - .SH "GROUPED ENTRIES" .PP In some cases it is useful to generate multiple resources from @@ -374,7 +373,6 @@ Each of the entries after the first must have a NULL value in its \fIargvName\fR field; this indicates that the entry is to be grouped with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR fields are used from these follow-on entries. - .SH "FLAGS" .PP The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used @@ -434,13 +432,11 @@ once, save the value, and provide it before calling .TP \fBTK_CONFIG_OPTION_SPECIFIED\fR This bit is -.VS 8.5 deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR so that callers could detect what entries were specified in \fIargv\fR, but it was removed because it was inherently thread-unsafe. Code that wishes to detect what options were specified should use \fBTk_SetOptions\fR instead. -.VE 8.5 .PP The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically used to specify different default values for @@ -473,7 +469,6 @@ for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, \fIflags\fR will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c. - .SH TK_OFFSET .PP The \fBTk_Offset\fR macro is provided as a safe way of generating @@ -481,7 +476,6 @@ the \fIoffset\fR values for entries in Tk_ConfigSpec structures. It takes two arguments: the name of a type of record, and the name of a field in that record. It returns the byte offset of the named field in records of the given type. - .SH TK_CONFIGUREINFO .PP The \fBTk_ConfigureInfo\fR procedure may be used to obtain @@ -492,12 +486,12 @@ pointer to a widget record containing the current information for a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, \fBTk_ConfigureInfo\fR generates a string describing all of the configuration options for the window. The string is placed -in \fIinterp->result\fR. Under normal circumstances +in interpreter \fIinterp\fR's result. Under normal circumstances it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR -and \fIinterp->result\fR contains an error message. +and the interpreter's result will contain an error message. .PP If \fIargvName\fR is NULL, then the value left in -\fIinterp->result\fR by \fBTk_ConfigureInfo\fR +the interpreter's result by \fBTk_ConfigureInfo\fR consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in \fIspecs\fR). Each entry in the list will contain either two or five values. If the @@ -510,27 +504,25 @@ field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. .PP If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, then it indicates a single option, and information is returned only -for that option. The string placed in \fIinterp->result\fR will be +for that option. The string placed in the interpreter's result will be a list containing two or five values as described above; this will be identical to the corresponding sublist that would have been returned if \fIargvName\fR had been NULL. .PP The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. - .SH TK_CONFIGUREVALUE .PP \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; instead of returning a list of values, it just returns the current value of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). -The value is returned in \fIinterp->result\fR and \fBTCL_OK\fR is +The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is normally returned as the procedure's result. If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is not a valid option name), \fBTCL_ERROR\fR is returned and an error message -is left in \fIinterp->result\fR. +is left in the interpreter's result. This procedure is typically called to implement \fBcget\fR widget commands. - .SH TK_FREEOPTIONS .PP The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup @@ -543,7 +535,6 @@ it contains a null pointer) then no resource is freed for that entry. After freeing a resource, \fBTk_FreeOptions\fR sets the corresponding field of the widget record to null. - .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with additional @@ -554,22 +545,22 @@ typedef struct Tk_CustomOption { Tk_OptionParseProc *\fIparseProc\fR; Tk_OptionPrintProc *\fIprintProc\fR; ClientData \fIclientData\fR; -} Tk_CustomOption; +} \fBTk_CustomOption\fR; -typedef int Tk_OptionParseProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tk_Window \fItkwin\fR, - char *\fIvalue\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR); +typedef int \fBTk_OptionParseProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tk_Window \fItkwin\fR, + char *\fIvalue\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR); -typedef char *Tk_OptionPrintProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIwidgRec\fR, - int \fIoffset\fR, - Tcl_FreeProc **\fIfreeProcPtr\fR); +typedef const char *\fBTk_OptionPrintProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR, + Tcl_FreeProc **\fIfreeProcPtr\fR); .CE The Tk_CustomOption structure contains three fields, which are pointers to the two procedures and a \fIclientData\fR value to be passed to those @@ -599,7 +590,7 @@ be placed. The procedure should translate the string to whatever form is appropriate for the option and store the value in the widget record. It should normally return \fBTCL_OK\fR, but if an error occurs in translating the string to a value then it should return \fBTCL_ERROR\fR -and store an error message in \fIinterp->result\fR. +and store an error message in interpreter \fIinterp\fR's result. .PP The \fIprintProc\fR procedure is called by \fBTk_ConfigureInfo\fR to produce a string value describing an @@ -622,7 +613,6 @@ Tk_CustomOption structure has been created for them, options of this new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point to the Tk_CustomOption structure. - .SH EXAMPLES .PP Although the explanation of \fBTk_ConfigureWidget\fR is fairly @@ -633,10 +623,8 @@ The library implementation of frames (tkFrame.c) has a simple configuration table, and the library implementation of buttons (tkButton.c) has a much more complex table that uses many of the fancy \fIspecFlags\fR mechanisms. - .SH "SEE ALSO" Tk_SetOptions(3) - .SH KEYWORDS anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, diff --git a/doc/CoordToWin.3 b/doc/CoordToWin.3 index f0a9837..5fe96a6 100644 --- a/doc/CoordToWin.3 +++ b/doc/CoordToWin.3 @@ -25,7 +25,6 @@ Y-coordinate (in root window coordinates). .AP Tk_Window tkwin in Token for window that identifies application. .BE - .SH DESCRIPTION .PP \fBTk_CoordsToWindow\fR locates the window that contains a given point. @@ -44,6 +43,5 @@ which window contains the mouse cursor: if a parent and a child both contain the point then the child gets preference, and if two siblings both contain the point then the highest one in the stacking order (i.e. the one that's visible on the screen) gets preference. - .SH KEYWORDS containing, coordinates, root window diff --git a/doc/CrtCmHdlr.3 b/doc/CrtCmHdlr.3 index 54cee95..98b93f7 100644 --- a/doc/CrtCmHdlr.3 +++ b/doc/CrtCmHdlr.3 @@ -20,10 +20,8 @@ Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate proced .AP Tk_ClientMessageProc *proc in Procedure to invoke whenever a ClientMessage X event occurs on any display. .BE - .SH DESCRIPTION .PP - \fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked in the future whenever a ClientMessage X event occurs that is not handled by \fBWM_PROTOCOL\fR. \fBTk_CreateClientMessageHandler\fR is intended for use @@ -39,9 +37,9 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or \fIProc\fR should have arguments and result that match the type \fBTk_ClientMessageProc\fR: .CS -typedef int Tk_ClientMessageProc( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\fR); +typedef int \fBTk_ClientMessageProc\fR( + Tk_Window \fItkwin\fR, + XEvent *\fIeventPtr\fR); .CE The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is associated with this event. \fIEventPtr\fR is a pointer to the X event. @@ -62,6 +60,5 @@ finds that matches the \fIproc\fR argument. If no such handler exists, then \fBTk_DeleteClientMessageHandler\fR returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same \fIproc\fR argument. - .SH KEYWORDS bind, callback, event, handler diff --git a/doc/CrtErrHdlr.3 b/doc/CrtErrHdlr.3 index f30ceb2..e506220 100644 --- a/doc/CrtErrHdlr.3 +++ b/doc/CrtErrHdlr.3 @@ -72,9 +72,9 @@ made when the handler was active (see below for more information). \fIProc\fR should have arguments and result that match the following type: .CS -typedef int Tk_ErrorProc( - ClientData \fIclientData\fR, - XErrorEvent *\fIerrEventPtr\fR); +typedef int \fBTk_ErrorProc\fR( + ClientData \fIclientData\fR, + XErrorEvent *\fIerrEventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateErrorHandler\fR when the callback @@ -136,6 +136,5 @@ handlers deleted before the \fBXSync\fR call. For the Tk error handling mechanism to work properly, it is essential that application code never calls \fBXSetErrorHandler\fR directly; applications should use only \fBTk_CreateErrorHandler\fR. - .SH KEYWORDS callback, error, event, handler diff --git a/doc/CrtGenHdlr.3 b/doc/CrtGenHdlr.3 index 1e4f10c..c2161d1 100644 --- a/doc/CrtGenHdlr.3 +++ b/doc/CrtGenHdlr.3 @@ -24,7 +24,6 @@ Procedure to invoke whenever any X event occurs on any display. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP \fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be @@ -45,9 +44,9 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or \fIProc\fR should have arguments and result that match the type \fBTk_GenericProc\fR: .CS -typedef int Tk_GenericProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); +typedef int \fBTk_GenericProc\fR( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateGenericHandler\fR when the callback diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3 index b7c3bb6..cbbc11e 100644 --- a/doc/CrtImgType.3 +++ b/doc/CrtImgType.3 @@ -21,11 +21,12 @@ ClientData .sp \fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR) .SH ARGUMENTS -.AS Tk_ImageType *typePtrPtr -.AP Tk_ImageType *typePtr in +.AS "const Tk_ImageType" *typePtrPtr +.AP "const Tk_ImageType" *typePtr in Structure that defines the new type of image. -Must be static: a +For Tk 8.4 and earlier this must be static: a pointer to this structure is retained by the image code. +In Tk 8.5, this limitation was relaxed. .AP Tcl_Interp *interp in Interpreter in which image was created. .AP "const char" *name in @@ -38,7 +39,6 @@ Number of arguments .AP char ***argvPtr in/out Pointer to argument list .BE - .SH DESCRIPTION .PP \fBTk_CreateImageType\fR is invoked to define a new kind of image. @@ -59,13 +59,13 @@ 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; + const 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; +} \fBTk_ImageType\fR; .CE The fields of this structure will be described in later subsections of this entry. @@ -92,7 +92,6 @@ option specified for a widget or canvas item. .PP The following subsections describe the fields of a Tk_ImageType in more detail. - .SS NAME .PP \fItypePtr->name\fR provides a name for the image type. @@ -101,21 +100,21 @@ in \fBimage create\fR commands to create images of the new type. If there already existed an image type by this name then the new image type replaces the old one. - .SS CREATEPROC +.PP \fItypePtr->createProc\fR provides the address of a procedure for Tk to call whenever \fBimage create\fR is invoked to create an image of the new type. \fItypePtr->createProc\fR must match the following prototype: .CS -typedef int 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); +typedef int \fBTk_ImageCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIname\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + const Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the \fBimage\fR command was invoked, and \fIname\fR is the name for the new image, @@ -141,16 +140,15 @@ it should return \fBTCL_OK\fR. .PP \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the size of the image and request an initial redisplay. - .SS GETPROC .PP \fItypePtr->getProc\fR is invoked by Tk whenever a widget calls \fBTk_GetImage\fR to use a particular image. This procedure must match the following prototype: .CS -typedef ClientData Tk_ImageGetProc( - Tk_Window \fItkwin\fR, - ClientData \fImasterData\fR); +typedef ClientData \fBTk_ImageGetProc\fR( + Tk_Window \fItkwin\fR, + ClientData \fImasterData\fR); .CE The \fItkwin\fR argument identifies the window in which the image will be used and \fImasterData\fR is the value @@ -162,23 +160,22 @@ display the image in the given window. is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its \fIdisplayProc\fR and \fIfreeProc\fR procedures. - .SS DISPLAYPROC .PP \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). \fIdisplayProc\fR must match the following prototype: .CS -typedef void Tk_ImageDisplayProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR, - Drawable \fIdrawable\fR, - int \fIimageX\fR, - int \fIimageY\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIdrawableX\fR, - int \fIdrawableY\fR); +typedef void \fBTk_ImageDisplayProc\fR( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR, + Drawable \fIdrawable\fR, + int \fIimageX\fR, + int \fIimageY\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIdrawableX\fR, + int \fIdrawableY\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created. @@ -195,7 +192,6 @@ as specified in the most recent call to \fBTk_ImageChanged\fR. the image should be displayed; \fIdisplayProc\fR should display the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. - .SS FREEPROC .PP \fItypePtr->freeProc\fR contains the address of a procedure that @@ -206,16 +202,15 @@ in a canvas is deleted, or when the image displayed in a widget or canvas item is changed. \fIfreeProc\fR must match the following prototype: .CS -typedef void Tk_ImageFreeProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR); +typedef void \fBTk_ImageFreeProc\fR( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created, and \fIdisplay\fR is the display containing the window for the instance. \fIfreeProc\fR should release any resources associated with the image instance, since the instance will never be used again. - .SS DELETEPROC .PP \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an @@ -225,15 +220,14 @@ Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for each of the image's instances. \fIdeleteProc\fR must match the following prototype: .CS -typedef void Tk_ImageDeleteProc( - ClientData \fImasterData\fR); +typedef void \fBTk_ImageDeleteProc\fR( + ClientData \fImasterData\fR); .CE The \fImasterData\fR argument will be the same as the value stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the image was created. \fIdeleteProc\fR should release any resources associated with the image. - .SH TK_GETIMAGEMASTERDATA .PP The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve @@ -247,19 +241,19 @@ and the return value is the ClientData value returned by the \fIcreateProc\fR when the image was created (this is typically a pointer to the image master data structure). If no such image exists then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. - .SH "LEGACY INTERFACE SUPPORT" +.PP In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR was incompatibly different, with the following prototype: .CS -typedef int 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); +typedef int \fBTk_ImageCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIargc\fR, + char **\fIargv\fR, + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); .CE Legacy programs and libraries dating from those days may still contain code that defines extended Tk image types using the old @@ -283,9 +277,7 @@ use Tk 8.4 headers and stub libraries to do so. .PP Any new code written today should not make use of the legacy interfaces. Expect their support to go away in Tk 9. - .SH "SEE ALSO" Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage - .SH KEYWORDS image manager, image type, instance, master diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 index 10b1cc0..005d2e2 100644 --- a/doc/CrtItemType.3 +++ b/doc/CrtItemType.3 @@ -44,7 +44,7 @@ NULL \fInextPtr\fR. .PP You may find it easier to understand the rest of this manual entry by looking at the code for an existing canvas item type such as -bitmap (file tkCanvBmap.c) or text (tkCanvText.c). +bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c). The easiest way to create a new type manager is to copy the code for an existing type and modify it for the new type. .PP @@ -60,12 +60,13 @@ structures. The first data structure is a Tk_ItemType; it contains information such as the name of the type and pointers to the standard procedures implemented by the type manager: +.PP .CS typedef struct Tk_ItemType { - char *\fIname\fR; + const char *\fIname\fR; int \fIitemSize\fR; Tk_ItemCreateProc *\fIcreateProc\fR; - Tk_ConfigSpec *\fIconfigSpecs\fR; + const Tk_ConfigSpec *\fIconfigSpecs\fR; Tk_ItemConfigureProc *\fIconfigProc\fR; Tk_ItemCoordProc *\fIcoordProc\fR; Tk_ItemDeleteProc *\fIdeleteProc\fR; @@ -82,7 +83,7 @@ typedef struct Tk_ItemType { Tk_ItemInsertProc *\fIinsertProc\fR; Tk_ItemDCharsProc *\fIdCharsProc\fR; Tk_ItemType *\fInextPtr\fR; -} Tk_ItemType; +} \fBTk_ItemType\fR; .CE .PP The fields of a Tk_ItemType structure are described in more detail @@ -92,7 +93,7 @@ argument must point to a structure with all of the fields initialized except \fInextPtr\fR, which Tk sets to link all the types together into a list. The structure must be in permanent memory (either statically -allocated or dynamically allocated but never freed); Tk retains +allocated or dynamically allocated but never freed); Tk retains a pointer to this structure. .PP The second data structure manipulated by a type manager is an @@ -102,11 +103,12 @@ All of the items of a given type generally have item records with the same structure, but different types usually have different formats for their item records. The first part of each item record is a header with a standard structure -defined by Tk via the type Tk_Item; the rest of the item +defined by Tk via the type Tk_Item; the rest of the item record is defined by the type manager. A type manager must define its item records with a Tk_Item as the first field. For example, the item record for bitmap items is defined as follows: +.PP .CS typedef struct BitmapItem { Tk_Item \fIheader\fR; @@ -116,8 +118,9 @@ typedef struct BitmapItem { XColor *\fIfgColor\fR; XColor *\fIbgColor\fR; GC \fIgc\fR; -} BitmapItem; +} \fBBitmapItem\fR; .CE +.PP The \fIheader\fR substructure contains information used by Tk to manage the item, such as its identifier, its tags, its type, and its bounding box. @@ -127,7 +130,7 @@ The type manager should not need to read or write any of the fields in the header except for four fields whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. These fields give a bounding box for the items using integer -canvas coordinates: the item should not cover any pixels +canvas coordinates: the item should not cover any pixels with x-coordinate lower than \fIx1\fR or y-coordinate lower than \fIy1\fR, nor should it cover any pixels with x-coordinate greater than or equal to \fIx2\fR or y-coordinate @@ -137,12 +140,12 @@ date as the item is moved and reconfigured. .PP Whenever Tk calls a procedure in a type manager it passes in a pointer to an item record. -The argument is always passed as a pointer to a Tk_Item; the type +The argument is always passed as a pointer to a Tk_Item; the type manager will typically cast this into a pointer to its own specific type, such as BitmapItem. .PP The third data structure used by type managers has type -Tk_Canvas; it serves as an opaque handle for the canvas widget +Tk_Canvas; it serves as an opaque handle for the canvas widget as a whole. Type managers need not know anything about the contents of this structure. @@ -150,6 +153,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 "TK_ITEMTYPE FIELDS" .SS NAME .PP This section and the ones that follow describe each of the fields @@ -160,8 +164,37 @@ in \fBcreate\fR widget commands to create items of the new type. If there already existed an item type by this name then the new item type replaces the old one. +.SS "FLAGS (IN ALWAYSREDRAW)" +.PP +The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons) +contains a collection of flag bits that modify how the canvas core interacts +with the item. The following bits are defined: +.TP +\fB1\fR +. +Indicates that the item should always be redrawn when any part of the canvas +is redrawn, rather than only when the bounding box of the item overlaps the +area being redrawn. This is used by window items, for example, which need to +unmap subwindows that are not on the screen. +.TP +\fBTK_CONFIG_OBJS\fR +. +Indicates that operations which would otherwise take a string (or array of +strings) actually take a Tcl_Obj reference (or an array of such references). +The operations to which this applies are the \fIconfigProc\fR, the +\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the +\fIinsertProc\fR. +.TP +\fBTK_MOVABLE_POINTS\fR +.VS 8.6 +Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and +\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon +types, and that hence individual coordinate points can be moved. Must not be +set if any of the above methods is NULL. +.VE 8.6 .SS ITEMSIZE -\fItypePtr->itemSize\fR gives the size in bytes of item records +.PP +\fItypePtr\->itemSize\fR gives the size in bytes of item records of this type, including the Tk_Item header. Tk uses this size to allocate memory space for items of the type. All of the item records for a given type must have the same size. @@ -170,31 +203,38 @@ of points for a polygon), the type manager can allocate a separate object of variable length and keep a pointer to it in the item record. .SS CREATEPROC .PP -\fItypePtr->createProc\fR points to a procedure for +\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: +\fItypePtr\->createProc\fR must match the following prototype: +.PP .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[]); +typedef int \fBTk_ItemCreateProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); .CE +.PP The \fIinterp\fR argument is the interpreter in which the canvas's \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a handle for the canvas widget. \fIitemPtr\fR is a pointer to a newly-allocated item of -size \fItypePtr->itemSize\fR. +size \fItypePtr\->itemSize\fR. Tk has already initialized the item's header (the first \fBsizeof(Tk_ItemType)\fR bytes). The \fIobjc\fR and \fIobjv\fR arguments describe all of the arguments to the \fBcreate\fR command after the \fItype\fR argument. -For example, in the widget command +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. +For example, in the widget command: +.PP .CS \fB\&.c create rectangle 10 20 50 50 \-fill black\fR .CE +.PP \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the integer object \fB10\fR. .PP @@ -202,7 +242,7 @@ integer object \fB10\fR. the type-specific parts of the item record and set an initial value for the bounding box in the item's header. It should return a standard Tcl completion code and leave an -error message in \fIinterp->result\fR if an error occurs. +error message in the interpreter result if an error occurs. If an error occurs Tk will free the item record, so \fIcreateProc\fR must be sure to leave the item record in a clean state if it returns an error (e.g., it must free any additional memory that it allocated for @@ -212,70 +252,84 @@ the item). Each type manager must provide a standard table describing its configuration options, in a form suitable for use with \fBTk_ConfigureWidget\fR. -This table will normally be used by \fItypePtr->createProc\fR -and \fItypePtr->configProc\fR, but Tk also uses it directly +This table will normally be used by \fItypePtr\->createProc\fR +and \fItypePtr\->configProc\fR, but Tk also uses it directly to retrieve option information in the \fBitemcget\fR and \fBitemconfigure\fR widget commands. -\fItypePtr->configSpecs\fR must point to the configuration table +\fItypePtr\->configSpecs\fR must point to the configuration table for this type. Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR -for implementing the \fB\-tags\fR option; see an existing type +for implementing the \fB\-tags\fR option; see an existing type manager for an example of how to use it in \fIconfigSpecs\fR. .SS CONFIGPROC .PP -\fItypePtr->configProc\fR is called by Tk whenever the +\fItypePtr\->configProc\fR is called by Tk whenever the \fBitemconfigure\fR widget command is invoked to change the configuration options for a canvas item. This procedure must match the following prototype: +.PP .CS -typedef int 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); +typedef int \fBTk_ItemConfigureProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + int \fIflags\fR); .CE -The \fIinterp\fR objument identifies the interpreter in which the -widget command was invoked, \fIcanvas\fR is a handle for the canvas +.PP +The \fIinterp\fR argument identifies the interpreter in which the +widget command was invoked, \fIcanvas\fR is a handle for the canvas widget, and \fIitemPtr\fR is a pointer to the item being configured. -\fIobjc\fR and \fIobjv\fR contain the configuration options. For -example, if the following command is invoked: +\fIobjc\fR and \fIobjv\fR contain the configuration options. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. +For example, if the following command is invoked: +.PP .CS \fB\&.c itemconfigure 2 \-fill red \-outline black\fR .CE +.PP \fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR through \fBblack\fR. \fIobjc\fR will always be an even value. -The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; +The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk -invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR +invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR procedure will usually invoke \fIconfigProc\fR with different flag values. .PP -\fItypePtr->configProc\fR returns a standard Tcl completion code and -leaves an error message in \fIinterp->result\fR if an error occurs. +\fItypePtr\->configProc\fR returns a standard Tcl completion code and +leaves an error message in the interpreter result if an error occurs. It must update the item's bounding box to reflect the new configuration options. .SS COORDPROC .PP -\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR +\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR widget command for an item. It must match the following prototype: +.PP .CS -typedef int Tk_ItemCoordProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIobjc\fR, - Tcl_Obj* const \fIobjv\fR[]); +typedef int \fBTk_ItemCoordProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); .CE +.PP The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR all have the standard meanings, and \fIobjc\fR and \fIobjv\fR describe the coordinate arguments. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually +contain a pointer to an array of constant strings. For example, if the following widget command is invoked: +.PP .CS \fB\&.c coords 2 30 90\fR .CE +.PP \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects \fB30\fR and \fB90\fR. .PP @@ -284,41 +338,45 @@ update the item appropriately (e.g., it must reset the bounding box in the item's header), and return a standard Tcl completion code. If an error occurs, \fIcoordProc\fR must leave an error message in -\fIinterp->result\fR. +the interpreter result. .SS DELETEPROC .PP -\fItypePtr->deleteProc\fR is invoked by Tk to delete an item +\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item and free any resources allocated to it. It must match the following prototype: +.PP .CS -typedef void Tk_ItemDeleteProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - Display *\fIdisplay\fR); +typedef void \fBTk_ItemDeleteProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR); .CE +.PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual interpretations, and \fIdisplay\fR identifies the X display containing the canvas. \fIdeleteProc\fR must free up any resources allocated for the item, so that Tk can free the item record. -\fIdeleteProc\fR should not actually free the item record; this will +\fIdeleteProc\fR should not actually free the item record; this will be done by Tk when \fIdeleteProc\fR returns. -.SS "DISPLAYPROC AND ALWAYSREDRAW" +.SS "DISPLAYPROC" .PP -\fItypePtr->displayProc\fR is invoked by Tk to redraw an item +\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item on the screen. It must match the following prototype: +.PP .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); +typedef void \fBTk_ItemDisplayProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR, + Drawable \fIdst\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR); .CE +.PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIdisplay\fR identifies the display containing the canvas, and \fIdst\fR specifies a drawable in which the item should be rendered; @@ -340,25 +398,28 @@ of \fIdst\fR. .PP Normally an item's \fIdisplayProc\fR is only invoked if the item overlaps the area being displayed. -However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then -\fIdisplayProc\fR is invoked during every redisplay operation, -even if the item does not overlap the area of redisplay. -\fIalwaysRedraw\fR should normally be set to 0; it is only -set to 1 in special cases such as window items that need to be -unmapped when they are off-screen. +However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1, +(i.e.\| +.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" ) +then \fIdisplayProc\fR is invoked during every redisplay operation, +even if the item does not overlap the area of redisplay; this is useful for +cases such as window items, where the subwindow needs to be unmapped when it +is off the screen. .SS POINTPROC .PP -\fItypePtr->pointProc\fR is invoked by Tk to find out how close +\fItypePtr\->pointProc\fR is invoked by Tk to find out how close a given point is to a canvas item. Tk uses this procedure for purposes such as locating the item under the mouse or finding the closest item to a given point. The procedure must match the following prototype: +.PP .CS -typedef double Tk_ItemPointProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIpointPtr\fR); +typedef double \fBTk_ItemPointProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIpointPtr\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIpointPtr\fR points to an array of two numbers giving the x and y coordinates of a point. @@ -367,15 +428,17 @@ from the point to the item, or 0 if the point lies inside the item. .SS AREAPROC .PP -\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship +\fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship between an item and a rectangular area. It must match the following prototype: +.PP .CS -typedef int Tk_ItemAreaProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double *\fIrectPtr\fR); +typedef int \fBTk_ItemAreaProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIrectPtr\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIrectPtr\fR points to an array of four real numbers; the first two give the x and y coordinates of the upper left @@ -386,26 +449,28 @@ the given area, 0 if it lies partially inside and partially outside the area, and 1 if it lies entirely inside the area. .SS POSTSCRIPTPROC .PP -\fItypePtr->postscriptProc\fR is invoked by Tk to generate +\fItypePtr\->postscriptProc\fR is invoked by Tk to generate Postscript for an item during the \fBpostscript\fR widget command. If the type manager is not capable of generating Postscript then -\fItypePtr->postscriptProc\fR should be NULL. +\fItypePtr\->postscriptProc\fR should be NULL. The procedure must match the following prototype: +.PP .CS -typedef int Tk_ItemPostscriptProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIprepass\fR); +typedef int \fBTk_ItemPostscriptProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIprepass\fR); .CE +.PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have -standard meanings; \fIprepass\fR will be described below. +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 +Postscript for the item to the information in the interpreter result (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) and return \fBTCL_OK\fR. If an error occurs, \fIpostscriptProc\fR should clear the result -and replace its contents with an error message; then it should +and replace its contents with an error message; then it should return \fBTCL_ERROR\fR. .PP Tk provides a collection of utility procedures to simplify @@ -427,26 +492,29 @@ In order to generate Postscript that complies with the Adobe Document Structuring Conventions, Tk actually generates Postscript in two passes. It calls each item's \fIpostscriptProc\fR in each pass. The only purpose of the first pass is to collect font information -(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is +(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is discarded. Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 -during the first pass; the type manager can use \fIprepass\fR to skip +during the first pass; the type manager can use \fIprepass\fR to skip all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. During the second pass \fIprepass\fR will be 0, so the type manager must generate complete Postscript. .SS SCALEPROC -\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item +.PP +\fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item during the \fBscale\fR widget command. The procedure must match the following prototype: +.PP .CS -typedef void Tk_ItemScaleProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIoriginX\fR, - double \fIoriginY\fR, - double \fIscaleX\fR, - double \fIscaleY\fR); +typedef void \fBTk_ItemScaleProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIoriginX\fR, + double \fIoriginY\fR, + double \fIscaleX\fR, + double \fIscaleY\fR); .CE +.PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the @@ -454,146 +522,171 @@ x and y scale factors. The item should adjust its coordinates so that a point in the item that used to have coordinates \fIx\fR and \fIy\fR will have new coordinates \fIx\(fm\fR and \fIy\(fm\fR, where +.PP .CS -\fIx\(fm = originX + scaleX*(x-originX) -y\(fm = originY + scaleY*(y-originY)\fR +\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR) +\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR) .CE +.PP \fIscaleProc\fR must also update the bounding box in the item's header. .SS TRANSLATEPROC -\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item +.PP +\fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item during the \fBmove\fR widget command. The procedure must match the following prototype: +.PP .CS -typedef void Tk_ItemTranslateProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - double \fIdeltaX\fR, - double \fIdeltaY\fR); +typedef void \fBTk_ItemTranslateProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIdeltaX\fR, + double \fIdeltaY\fR); .CE +.PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be added to each x and y coordinate within the item. The type manager should adjust the item's coordinates and update the bounding box in the item's header. .SS INDEXPROC -\fItypePtr->indexProc\fR is invoked by Tk to translate a string +.PP +\fItypePtr\->indexProc\fR is invoked by Tk to translate a string index specification into a numerical index, for example during the \fBindex\fR widget command. -It is only relevant for item types that support indexable text; -\fItypePtr->indexProc\fR may be specified as NULL for non-textual -item types. +It is only relevant for item types that support indexable text or coordinates; +\fItypePtr\->indexProc\fR may be specified as NULL for non-textual +item types if they do not support detailed coordinate addressing. The procedure must match the following prototype: +.PP .CS -typedef int Tk_ItemIndexProc( - Tcl_Interp *\fIinterp\fR, - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - char \fIindexString\fR, - int *\fIindexPtr\fR); +typedef int \fBTk_ItemIndexProc\fR( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Tcl_Obj *\fIindexObj\fR, + int *\fIindexPtr\fR); .CE +.PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have the usual meaning. -\fIindexString\fR contains a textual description of an index, +\fIindexObj\fR contains a textual description of an index, and \fIindexPtr\fR points to an integer value that should be filled in with a numerical index. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will +actually contain a pointer to a constant string. It is up to the type manager to decide what forms of index -are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, +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. +the interpreter result in the event of an error. .SS ICURSORPROC .PP -\fItypePtr->icursorProc\fR is invoked by Tk during +\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 +\fItypePtr\->icursorProc\fR may be specified as NULL for item types that do not support an insertion cursor. The procedure must match the following prototype: +.PP .CS -typedef void Tk_ItemCursorProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR); +typedef void \fBTk_ItemCursorProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and \fIindex\fR is an index into the item's text, as returned by a -previous call to \fItypePtr->insertProc\fR. +previous call to \fItypePtr\->insertProc\fR. The type manager should position the insertion cursor in the item just before the character given by \fIindex\fR. Whether or not to actually display the insertion cursor is determined by other information provided by \fBTk_CanvasGetTextInfo\fR. .SS SELECTIONPROC .PP -\fItypePtr->selectionProc\fR is invoked by Tk during selection -retrievals; it must return part or all of the selected text in +\fItypePtr\->selectionProc\fR is invoked by Tk during selection +retrievals; it must return part or all of the selected text in the item (if any). It is only relevant for item types that support text; -\fItypePtr->selectionProc\fR may be specified as NULL for non-textual +\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual item types. The procedure must match the following prototype: +.PP .CS -typedef int Tk_ItemSelectionProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\fR); +typedef int \fBTk_ItemSelectionProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIoffset\fR is an offset in bytes into the selection where 0 refers -to the first byte of the selection; it identifies +to the first byte of the selection; it identifies the first character that is to be returned in this call. \fIbuffer\fR points to an area of memory in which to store the requested bytes, and \fImaxBytes\fR specifies the maximum number of bytes to return. \fIselectionProc\fR should extract up to \fImaxBytes\fR characters -from the selection and copy them to \fImaxBytes\fR; it should +from the selection and copy them to \fImaxBytes\fR; it should return a count of the number of bytes actually copied, which may be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes in the selection. .SS INSERTPROC .PP -\fItypePtr->insertProc\fR is invoked by Tk during -the \fBinsert\fR widget command to insert new text into a +\fItypePtr\->insertProc\fR is invoked by Tk during +the \fBinsert\fR widget command to insert new text or coordinates into a canvas item. -It is only relevant for item types that support text; -\fItypePtr->insertProc\fR may be specified as NULL for non-textual +It is only relevant for item types that support the \fBinsert\fR method; +\fItypePtr\->insertProc\fR may be specified as NULL for other item types. The procedure must match the following prototype: +.PP .CS -typedef void Tk_ItemInsertProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIindex\fR, - char *\fIstring\fR); +typedef void \fBTk_ItemInsertProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR, + Tcl_Obj *\fIobj\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIindex\fR is an index into the item's text, as returned by a -previous call to \fItypePtr->insertProc\fR, and \fIstring\fR +previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR contains new text to insert just before the character given by \fIindex\fR. +Note that if \fBTK_CONFIG_OBJS\fR is not set in the +\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will +actually contain a pointer to a constant string to be inserted. +If the item supports modification of the coordinates list by this +.PP The type manager should insert the text and recompute the bounding box in the item's header. .SS DCHARSPROC .PP -\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR -widget command to delete a range of text from a canvas item. +\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR +widget command to delete a range of text from a canvas item or a range of +coordinates from a pathed item. It is only relevant for item types that support text; -\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual -item types. +\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual +item types that do not want to support coordinate deletion. The procedure must match the following prototype: +.PP .CS -typedef void Tk_ItemDCharsProc( - Tk_Canvas \fIcanvas\fR, - Tk_Item *\fIitemPtr\fR, - int \fIfirst\fR, - int \fIlast\fR); +typedef void \fBTk_ItemDCharsProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIfirst\fR, + int \fIlast\fR); .CE +.PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIfirst\fR and \fIlast\fR give the indices of the first and last bytes -to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR. +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" diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 index b5559c8..c7e792a 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -20,11 +20,10 @@ Tk_CreatePhotoImageFormat \- define new file format for photo images .sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SH ARGUMENTS -.AS Tk_PhotoImageFormat *formatPtr -.AP Tk_PhotoImageFormat *formatPtr in +.AS "const Tk_PhotoImageFormat" *formatPtr +.AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE - .SH DESCRIPTION .PP \fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format @@ -46,14 +45,14 @@ 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; + const char *\fIname\fR; Tk_ImageFileMatchProc *\fIfileMatchProc\fR; Tk_ImageStringMatchProc *\fIstringMatchProc\fR; Tk_ImageFileReadProc *\fIfileReadProc\fR; Tk_ImageStringReadProc *\fIstringReadProc\fR; Tk_ImageFileWriteProc *\fIfileWriteProc\fR; Tk_ImageStringWriteProc *\fIstringWriteProc\fR; -} Tk_PhotoImageFormat; +} \fBTk_PhotoImageFormat\fR; .CE .PP The handler need not provide implementations of all six procedures. @@ -65,8 +64,7 @@ structure should be set to NULL. The handler must provide the \fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR procedure, and the \fIstringMatchProc\fR procedure if it provides the \fIstringReadProc\fR procedure. - -.SH NAME +.SS NAME .PP \fIformatPtr->name\fR provides a name for the image type. Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used @@ -77,20 +75,20 @@ 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 +.SS FILEMATCHPROC +.PP \fIformatPtr->fileMatchProc\fR provides the address of a procedure for Tk to call when it is searching for an image file format handler suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS -typedef int Tk_ImageFileMatchProc( - Tcl_Channel \fIchan\fR, - const char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); +typedef int \fBTk_ImageFileMatchProc\fR( + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); .CE The \fIfileName\fR argument is the name of the file containing the image data, which is open for reading as \fIchan\fR. The @@ -100,19 +98,19 @@ If the data in the file appears to be in the format supported by this handler, the \fIformatPtr->fileMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. - -.SH STRINGMATCHPROC +.SS STRINGMATCHPROC +.PP \fIformatPtr->stringMatchProc\fR provides the address of a procedure for Tk to call when it is searching for an image file format handler for suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS -typedef int Tk_ImageStringMatchProc( - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); +typedef int \fBTk_ImageStringMatchProc\fR( + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); .CE The \fIdata\fR argument points to the object containing the image data. The \fIformat\fR argument contains the value given for @@ -122,21 +120,21 @@ this handler, the \fIformatPtr->stringMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. - -.SH FILEREADPROC +.SS FILEREADPROC +.PP \fIformatPtr->fileReadProc\fR provides the address of a procedure for Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS -typedef int 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); +typedef int \fBTk_ImageFileReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -151,20 +149,20 @@ coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. The return value is a standard Tcl return value. - -.SH STRINGREADPROC +.SS STRINGREADPROC +.PP \fIformatPtr->stringReadProc\fR provides the address of a procedure for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS -typedef int 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); +typedef int \fBTk_ImageStringReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -179,17 +177,17 @@ coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. The return value is a standard Tcl return value. - -.SH FILEWRITEPROC +.SS FILEWRITEPROC +.PP \fIformatPtr->fileWriteProc\fR provides the address of a procedure for Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS -typedef int Tk_ImageFileWriteProc( - Tcl_Interp *\fIinterp\fR, - const char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); +typedef int \fBTk_ImageFileWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to write the image; it should be used for reporting errors. @@ -204,16 +202,16 @@ after the name of the format. If appropriate, the \fIformatPtr->fileWriteProc\fR procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value. - -.SH STRINGWRITEPROC +.SS STRINGWRITEPROC +.PP \fIformatPtr->stringWriteProc\fR provides the address of a procedure for Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS -typedef int Tk_ImageStringWriteProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); +typedef int \fBTk_ImageStringWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. @@ -228,8 +226,8 @@ after the name of the format. If appropriate, the \fIformatPtr->stringWriteProc\fR procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value. - .SH "LEGACY INTERFACE SUPPORT" +.PP In Tk 8.2 and earlier, the definition of all the function pointer types stored in fields of a \fBTk_PhotoImageFormat\fR struct were incompatibly different. Legacy programs and libraries dating from @@ -266,9 +264,7 @@ use Tk 8.4 headers and stub libraries to do so. .PP Any new code written today should not make use of the legacy interfaces. Expect their support to go away in Tk 9. - .SH "SEE ALSO" Tk_FindPhoto, Tk_PhotoPutBlock - .SH KEYWORDS photo image, image file diff --git a/doc/CrtSelHdlr.3 b/doc/CrtSelHdlr.3 index b5eb841..2aeffa9 100644 --- a/doc/CrtSelHdlr.3 +++ b/doc/CrtSelHdlr.3 @@ -54,11 +54,11 @@ the selection. The most common form is STRING. \fIProc\fR should have arguments and result that match the type \fBTk_SelectionProc\fR: .CS -typedef int Tk_SelectionProc( - ClientData \fIclientData\fR, - int \fIoffset\fR, - char *\fIbuffer\fR, - int \fImaxBytes\fR); +typedef int \fBTk_SelectionProc\fR( + ClientData \fIclientData\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateSelHandler\fR. @@ -112,6 +112,5 @@ existing handler is replaced with a new one. \fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR, \fIselection\fR, and \fItarget\fR, if such a handler exists. If there is no such handler then it has no effect. - .SH KEYWORDS format, handler, selection, target diff --git a/doc/CrtWindow.3 b/doc/CrtWindow.3 index 82a5c80..8f44545 100644 --- a/doc/CrtWindow.3 +++ b/doc/CrtWindow.3 @@ -58,8 +58,8 @@ are used to create new windows for use in Tk-based applications. Each of the procedures returns a token that can be used to manipulate the window in other calls to the Tk library. If the window could not be created successfully, then NULL -is returned and \fIinterp->result\fR is modified to hold an error -message. +is returned and the result of interpreter \fIinterp\fR is modified to +hold an error message. .PP Tk supports two different kinds of windows: internal windows and top-level windows. @@ -86,7 +86,7 @@ which would in turn be a child of the menu bar window. A dialog box might have the application's main window as its parent. .PP \fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in -that it creates an unnamed window. This window will be manipulable +that it creates an unnamed window. This window will be manipulatable only using C interfaces, and will not be visible to Tcl scripts. Both interior windows and top-level windows may be created with \fBTk_CreateAnonymousWindow\fR. @@ -141,7 +141,6 @@ but has not been mapped, so no X window exists, it is possible to force the creation of the X window by calling \fBTk_MakeWindowExist\fR. This procedure issues the X commands to instantiate the window given by \fItkwin\fR. - .SH KEYWORDS create, deferred creation, destroy, display, internal window, screen, top-level window, window diff --git a/doc/DeleteImg.3 b/doc/DeleteImg.3 index 2d3d83c..507be72 100644 --- a/doc/DeleteImg.3 +++ b/doc/DeleteImg.3 @@ -21,13 +21,11 @@ Interpreter for which the image was created. .AP "const char" *name in Name of the image. .BE - .SH DESCRIPTION .PP \fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR and \fIname\fR, if there is one. All instances of that image will redisplay as empty regions. If the given image does not exist then the procedure has no effect. - .SH KEYWORDS delete image, image manager diff --git a/doc/DrawFocHlt.3 b/doc/DrawFocHlt.3 index ed29857..e2d1578 100644 --- a/doc/DrawFocHlt.3 +++ b/doc/DrawFocHlt.3 @@ -27,12 +27,10 @@ Width of the highlight ring, in pixels. Drawable in which to draw the highlight; usually an offscreen pixmap for double buffering. .BE - .SH DESCRIPTION .PP \fBTk_DrawFocusHighlight\fR is a utility procedure that draws the traversal highlight ring for a widget. It is typically invoked by widgets during redisplay. - .SH KEYWORDS focus, traversal highlight diff --git a/doc/EventHndlr.3 b/doc/EventHndlr.3 index 80003d8..97857fb 100644 --- a/doc/EventHndlr.3 +++ b/doc/EventHndlr.3 @@ -30,7 +30,6 @@ in the window given by \fItkwin\fR. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP \fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be @@ -45,9 +44,9 @@ call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or \fIProc\fR should have arguments and result that match the type \fBTk_EventProc\fR: .CS -typedef void Tk_EventProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); +typedef void \fBTk_EventProc\fR( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateEventHandler\fR when the callback @@ -72,6 +71,5 @@ automatically; in this case there is no need to call If multiple handlers are declared for the same type of X event on the same window, then the handlers will be invoked in the order they were created. - .SH KEYWORDS bind, callback, event, handler diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3 index 30df3a2..d6ccb5b 100644 --- a/doc/FindPhoto.3 +++ b/doc/FindPhoto.3 @@ -21,7 +21,6 @@ Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_Pho Tk_PhotoHandle \fBTk_FindPhoto\fR(\fIinterp, imageName\fR) .sp -.VS 8.5 int \fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ compRule\fR) @@ -29,7 +28,6 @@ compRule\fR) 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,18 +35,14 @@ int void \fBTk_PhotoBlank\fR(\fIhandle\fR) .sp -.VS 8.5 int \fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) -.VE 8.5 .sp void \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) .sp -.VS 8.5 int \fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) -.VE 8.5 .SH ARGUMENTS .AS Tk_PhotoImageBlock window_path .AP Tcl_Interp *interp in @@ -99,7 +93,6 @@ being written to the photo image. Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image. .BE - .SH DESCRIPTION .PP \fBTk_FindPhoto\fR returns an opaque handle that is used to identify a @@ -128,8 +121,8 @@ typedef struct { int \fIheight\fR; int \fIpitch\fR; int \fIpixelSize\fR; - int \fIoffset[4]\fR; -} Tk_PhotoImageBlock; + int \fIoffset\fR[4]; +} \fBTk_PhotoImageBlock\fR; .CE The \fIpixelPtr\fR field points to the first pixel, that is, the top-left pixel in the block. @@ -161,12 +154,10 @@ 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 @@ -207,12 +198,10 @@ 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 @@ -222,16 +211,13 @@ or height, but allows the width or height to be changed by subsequent calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or \fBTk_PhotoExpand\fR. .PP -.VS 8.5 \fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. -.VE 8.5 .PP \fBTk_PhotoGetSize\fR returns the dimensions of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR. - .SH PORTABILITY .PP In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and @@ -241,7 +227,6 @@ your code, compile it with the flag -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against older versions of Tk will continue to work. .PP -.VS 8.5 In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an \fIinterp\fR argument or return any result code. If insufficient @@ -249,12 +234,9 @@ memory was available for an image, Tk would panic. This behaviour is still supported if you compile your extension with the additional flag -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against older versions of Tk will continue to work. -.VE 8.5 - .SH CREDITS .PP The code for the photo image type was developed by Paul Mackerras, based on his earlier photo widget code. - .SH KEYWORDS photo, image diff --git a/doc/FontId.3 b/doc/FontId.3 index 4c0d8d4..c79b89f 100644 --- a/doc/FontId.3 +++ b/doc/FontId.3 @@ -65,6 +65,7 @@ following screen font families should print correctly: Any other font families may not print correctly because the computed Postscript font name may be incorrect or not exist on the printer. .SH "DATA STRUCTURES" +.PP The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to return information about a font and is defined as follows: .CS @@ -72,7 +73,7 @@ typedef struct Tk_FontMetrics { int \fIascent\fR; int \fIdescent\fR; int \fIlinespace\fR; -} Tk_FontMetrics; +} \fBTk_FontMetrics\fR; .CE .PP The \fIascent\fR field is the amount in pixels that the tallest diff --git a/doc/GeomReq.3 b/doc/GeomReq.3 index 0296132..895f683 100644 --- a/doc/GeomReq.3 +++ b/doc/GeomReq.3 @@ -44,7 +44,6 @@ Space to leave for top side of internal border for \fItkwin\fR, in pixel units. .AP int bottom in Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. .BE - .SH DESCRIPTION .PP \fBTk_GeometryRequest\fR is called by widget code to indicate its @@ -89,6 +88,5 @@ The information specified in calls to \fBTk_GeometryRequest\fR, \fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR. See the \fBTk_WindowId\fR manual entry for details. - .SH KEYWORDS geometry, request diff --git a/doc/GetAnchor.3 b/doc/GetAnchor.3 index 032d838..6526772 100644 --- a/doc/GetAnchor.3 +++ b/doc/GetAnchor.3 @@ -28,17 +28,20 @@ const char * Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out String value contains name of anchor point: -.QW n , -.QW ne , -.QW e , -.QW se , -.QW s , -.QW sw , -.QW w , -.QW nw , +.QW \fBn\fR , +.QW \fBne\fR , +.QW \fBe\fR , +.QW \fBse\fR , +.QW \fBs\fR , +.QW \fBsw\fR , +.QW \fBw\fR , +.QW \fBnw\fR , or -.QW center ; -internal rep will be modified to cache corresponding Tk_Anchor. +.QW \fBcenter\fR ; +internal rep will be modified to cache corresponding Tk_Anchor. In the +case of +.QW \fBcenter\fR +on input, a non-empty abbreviation of it may also be used on input. .AP "const char" *string in Same as \fIobjPtr\fR except description of anchor point is passed as a string. diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3 index f1ab120..c4ac44e 100644 --- a/doc/GetBitmap.3 +++ b/doc/GetBitmap.3 @@ -49,7 +49,7 @@ Same as \fIobjPtr\fR except description of bitmap is passed as a string and resulting Pixmap is not cached. .AP "const char" *name in Name for new bitmap to be defined. -.AP "const char" *source in +.AP "const void" *source in Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. .AP "int" width in @@ -66,7 +66,6 @@ Display for which \fIbitmap\fR was allocated. Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .BE - .SH DESCRIPTION .PP These procedures manage a collection of bitmaps (one-plane pixmaps) @@ -82,7 +81,7 @@ of the following forms: .TP 20 \fB@\fIfileName\fR \fIFileName\fR must be the name of a file containing a bitmap -description in the standard X11 or X10 format. +description in the standard X11 format. .TP 20 \fIname\fR \fIName\fR must be the name of a bitmap defined previously with @@ -210,7 +209,7 @@ describe the bitmap. \fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then \fBTCL_ERROR\fR is returned and an error message is left in -\fIinterp->result\fR. +interpreter \fIinterp\fR's result. Note: \fBTk_DefineBitmap\fR expects the memory pointed to by \fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make a private copy of this memory, but uses the bytes pointed to @@ -282,8 +281,8 @@ with its Pixmap token. There should be exactly one call to \fBTk_FreeBitmapFromObj\fR or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. - .SH BUGS +.PP In determining whether an existing bitmap can be used to satisfy a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR consider only the immediate value of the string description. For @@ -293,6 +292,5 @@ bitmap created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. - .SH KEYWORDS bitmap, pixmap diff --git a/doc/GetCapStyl.3 b/doc/GetCapStyl.3 index e26ed31..28f1a1c 100644 --- a/doc/GetCapStyl.3 +++ b/doc/GetCapStyl.3 @@ -24,18 +24,18 @@ const char * .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in -String containing name of cap style: one of -.QW butt , -.QW projecting , +String containing name of cap style \- one of +.QW \fBbutt\fR , +.QW \fBprojecting\fR , or -.QW round . +.QW \fBround\fR +\- or a unique abbreviation of one. .AP int *capPtr out Pointer to location in which to store X cap style corresponding to \fIstring\fR. .AP int cap in Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. .BE - .SH DESCRIPTION .PP \fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style @@ -51,7 +51,7 @@ Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIstring\fR does not contain a valid cap style or an abbreviation of one of these names, then an error message is -stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and \fI*capPtr\fR is unmodified. .PP \fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. @@ -60,6 +60,5 @@ statically-allocated string corresponding to \fIcap\fR. If \fIcap\fR is not a legal cap style, then .QW "unknown cap style" is returned. - .SH KEYWORDS butt, cap style, projecting, round diff --git a/doc/GetColor.3 b/doc/GetColor.3 index c1bd0dc..9d07d95 100644 --- a/doc/GetColor.3 +++ b/doc/GetColor.3 @@ -58,7 +58,6 @@ call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or Drawable in which the result graphics context will be used. Must have same screen and depth as the window for which the color was allocated. .BE - .SH DESCRIPTION .PP These procedures manage the colors being used by a Tk application. @@ -68,8 +67,8 @@ colormap space is exhausted. .PP Given a textual description of a color, \fBTk_AllocColorFromObj\fR locates a pixel value that may be used to render the color -in a particular window. The desired color is specified with an -object whose string value must have one of the following forms: +in a particular window. The desired color is specified with a +value whose string value must have one of the following forms: .TP 20 \fIcolorname\fR Any of the valid textual names for a color defined in the @@ -107,7 +106,7 @@ such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR. .PP \fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except that the description of the color is specified with a string instead -of an object. This prevents \fBTk_GetColor\fR from caching the +of a value. This prevents \fBTk_GetColor\fR from caching the return value, so \fBTk_GetColor\fR is less efficient than \fBTk_AllocColorFromObj\fR. .PP @@ -174,4 +173,4 @@ There should be exactly one call to \fBTk_FreeColorFromObj\fR or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR. .SH KEYWORDS -color, intensity, object, pixel value +color, intensity, value, pixel value diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 index 5784792..8526a47 100644 --- a/doc/GetCursor.3 +++ b/doc/GetCursor.3 @@ -67,7 +67,6 @@ Opaque Tk identifier for cursor. If passed to \fBTk_FreeCursor\fR, must have been returned by some previous call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR. .BE - .SH DESCRIPTION .PP These procedures manage a collection of cursors @@ -118,7 +117,7 @@ in preference to black and white cursors. \fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR In this form, \fIsourceName\fR and \fImaskName\fR are the names of files describing cursors for the cursor's source bits and mask. -Each file must be in standard X11 or X10 cursor format. +Each file must be in standard X11 cursor format. \fIFgColor\fR and \fIbgColor\fR indicate the colors to use for the cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This @@ -213,8 +212,8 @@ with its Tk_Cursor token. There should be exactly one call to \fBTk_FreeCursor\fR for each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR. - .SH BUGS +.PP In determining whether an existing cursor can be used to satisfy a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and \fBTk_GetCursorFromData\fR @@ -228,6 +227,5 @@ a different file. Similarly, \fBTk_GetCursorFromData\fR assumes that if the same \fIsource\fR pointer is used in two different calls, then the pointers refer to the same data; it does not check to see if the actual data values have changed. - .SH KEYWORDS cursor diff --git a/doc/GetDash.3 b/doc/GetDash.3 index 8acc660..d1eeb70 100644 --- a/doc/GetDash.3 +++ b/doc/GetDash.3 @@ -13,28 +13,30 @@ Tk_GetDash \- convert from string to valid dash structure. .SH SYNOPSIS .nf \fB#include <tk.h>\fR -.sp + int \fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR) +.fi .SH ARGUMENTS .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 -value converted from \fIstring\fR. +value converted from \fIstring\fR. Must not be NULL. .BE - .SH DESCRIPTION .PP These procedure parses the string and fills in the result in the Tk_Dash structure. The string can be a list of integers or a character string containing only -.QW \fB.,\-_\fR -or spaces. If all -goes well, \fBTCL_OK\fR is returned. If \fIstring\fR does not have the +.QW \fB.,-_\fR +and spaces. If all +goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored +in the variable pointed to by \fIdashPtr\fR. +If \fIstring\fR does not have the proper syntax then \fBTCL_ERROR\fR is returned, an error message is left in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. .PP @@ -46,33 +48,35 @@ color. The other segments are drawn transparent. .PP The second possible syntax is a character list containing only 5 possible characters -.QW "\fB.,\-_ \fR" . +.QW "\fB.,-_ \fR" . The space can be used to enlarge the space between other line elements, and can not -occur as the first position in the string. Some examples: +occur in the first position of the string. Some examples: +.PP .CS \-dash . = \-dash {2 4} - \-dash \- = \-dash {6 4} - \-dash \-. = \-dash {6 4 2 4} - \-dash \-.. = \-dash {6 4 2 4 2 4} + \-dash - = \-dash {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 +The main difference between this syntax and the numeric is that it is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This -assures that +ensures that .QW . will always be displayed as a dot and -.QW \- +.QW - always as a dash regardless of the line width. .PP On systems where only a limited set of dash patterns, the dash pattern will be displayed as the most close dash pattern that is available. For example, on Windows only the first 4 of the -above examples are available. The last 2 examples will be -displayed identically as the first one. - +above examples are available; the last 2 examples will be +displayed identically to the first one. +.SH "SEE ALSO" +canvas(n), Tk_CreateItemType(3) .SH KEYWORDS dash, conversion diff --git a/doc/GetFont.3 b/doc/GetFont.3 index 23dcf25..cf02f00 100644 --- a/doc/GetFont.3 +++ b/doc/GetFont.3 @@ -31,7 +31,6 @@ Tk_Font .sp void \fBTk_FreeFont(\fItkfont\fB)\fR - .SH ARGUMENTS .AS "const char" *tkfont .AP "Tcl_Interp" *interp in @@ -105,7 +104,6 @@ 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. - .SH "SEE ALSO" Tk_FontId(3) .SH KEYWORDS diff --git a/doc/GetGC.3 b/doc/GetGC.3 index 621e109..44e06fb 100644 --- a/doc/GetGC.3 +++ b/doc/GetGC.3 @@ -34,7 +34,6 @@ Display for which \fIgc\fR was allocated. X identifier for graphics context that is no longer needed. Must have been allocated by \fBTk_GetGC\fR. .BE - .SH DESCRIPTION .PP \fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts @@ -67,6 +66,5 @@ each call to \fBTk_GetGC\fR. When a graphics context is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) \fBTk_FreeGC\fR will release it to the X server and delete it from the database. - .SH KEYWORDS graphics context diff --git a/doc/GetHWND.3 b/doc/GetHWND.3 index 54e7351..1a5ec2d 100644 --- a/doc/GetHWND.3 +++ b/doc/GetHWND.3 @@ -32,6 +32,5 @@ window given by \fIwindow\fR. \fBTk_AttachHWND\fR binds the Windows HWND identifier to the specified Tk_Window given by \fItkwin\fR. It returns an X Windows window that encapsulates the HWND. - .SH KEYWORDS identifier, window diff --git a/doc/GetImage.3 b/doc/GetImage.3 index 2d481f8..f2407bc 100644 --- a/doc/GetImage.3 +++ b/doc/GetImage.3 @@ -63,7 +63,6 @@ Store width of \fIimage\fR (in pixels) here. .AP "int" heightPtr out Store height of \fIimage\fR (in pixels) here. .BE - .SH DESCRIPTION .PP These procedures are invoked by widgets that wish to display images. @@ -74,7 +73,7 @@ identifies the window where the image will be displayed. \fBTk_GetImage\fR looks up the image in the table of existing images and returns a token for a new instance of the image. If the image does not exist then \fBTk_GetImage\fR returns NULL -and leaves an error message in \fIinterp->result\fR. +and leaves an error message in interpreter \fIinterp\fR's result. .PP When a widget wishes to actually display an image it must call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR), @@ -106,14 +105,14 @@ The \fIchangeProc\fR and \fIclientData\fR arguments to \fIchangeProc\fR will be called by Tk whenever a change occurs in the image; it must match the following prototype: .CS -typedef void Tk_ImageChangedProc( - ClientData \fIclientData\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIimageWidth\fR, - int \fIimageHeight\fR); +typedef void \fBTk_ImageChangedProc\fR( + ClientData \fIclientData\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIimageWidth\fR, + int \fIimageHeight\fR); .CE The \fIclientData\fR argument to \fIchangeProc\fR is the same as the \fIclientData\fR argument to \fBTk_GetImage\fR. @@ -125,9 +124,7 @@ they are specified in pixels measured from the upper-left corner of the image. The arguments \fIimageWidth\fR and \fIimageHeight\fR give the image's (new) size. - .SH "SEE ALSO" Tk_CreateImageType - .SH KEYWORDS images, redisplay diff --git a/doc/GetJoinStl.3 b/doc/GetJoinStl.3 index 81b5e9a..a717b72 100644 --- a/doc/GetJoinStl.3 +++ b/doc/GetJoinStl.3 @@ -24,18 +24,18 @@ const char * .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in -String containing name of join style: one of -.QW bevel , -.QW miter , +String containing name of join style \- one of +.QW \fBbevel\fR , +.QW \fBmiter\fR , or -.QW round . +.QW \fBround\fR +\- or a unique abbreviation of one. .AP int *joinPtr out Pointer to location in which to store X join style corresponding to \fIstring\fR. .AP int join in Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. .BE - .SH DESCRIPTION .PP \fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style @@ -50,7 +50,7 @@ Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIstring\fR does not contain a valid join style or an abbreviation of one of these names, then an error message is -stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and \fI*joinPtr\fR is unmodified. .PP \fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. @@ -59,6 +59,5 @@ statically-allocated string corresponding to \fIjoin\fR. If \fIjoin\fR is not a legal join style, then .QW "unknown join style" is returned. - .SH KEYWORDS bevel, join style, miter, round diff --git a/doc/GetJustify.3 b/doc/GetJustify.3 index 7e879db..b51cb8d 100644 --- a/doc/GetJustify.3 +++ b/doc/GetJustify.3 @@ -27,11 +27,12 @@ const char * .AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out -String value contains name of justification style, one of -.QW left , -.QW right , +String value contains name of justification style \- one of +.QW \fBleft\fR , +.QW \fBright\fR , or -.QW center . +.QW \fBcenter\fR +\- or a unique abbreviation of one. The internal rep will be modified to cache corresponding justify value. .AP "const char" *string in Same as \fIobjPtr\fR except description of justification style is passed as @@ -82,6 +83,5 @@ corresponding to \fIjustify\fR. If \fIjustify\fR is not a legal justify value, then .QW "unknown justification style" is returned. - .SH KEYWORDS center, fill, justification, string diff --git a/doc/GetOption.3 b/doc/GetOption.3 index 432e18b..81846ad 100644 --- a/doc/GetOption.3 +++ b/doc/GetOption.3 @@ -26,7 +26,6 @@ Name of desired option. Class of desired option. Null means there is no class for this option; do lookup based on name only. .BE - .SH DESCRIPTION .PP This procedure is invoked to retrieve an option from the database @@ -39,6 +38,5 @@ is returned. If no option matches, then NULL is returned. \fBTk_GetOption\fR caches options related to \fItkwin\fR so that successive calls for the same \fItkwin\fR will execute much more quickly than successive calls for different windows. - .SH KEYWORDS class, name, option, retrieve diff --git a/doc/GetPixels.3 b/doc/GetPixels.3 index 2e6cc57..e7a9043 100644 --- a/doc/GetPixels.3 +++ b/doc/GetPixels.3 @@ -43,7 +43,6 @@ Pointer to location in which to store converted distance in pixels. .AP double *doublePtr out Pointer to location in which to store converted distance in millimeters. .BE - .SH DESCRIPTION .PP These procedures take as argument a specification of distance on @@ -85,13 +84,12 @@ value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except that the screen distance is specified with a string instead of an object. This prevents \fBTk_GetPixels\fR from caching the -return value, so \fBTk_GetAnchor\fR is less efficient than +return value, so \fBTk_GetPixels\fR is less efficient than \fBTk_GetPixelsFromObj\fR. .PP \fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to \fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except that they convert the screen distance to millimeters and store a double-precision floating-point result at \fI*doublePtr\fR. - .SH KEYWORDS centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/doc/GetPixmap.3 b/doc/GetPixmap.3 index 4bcab61..927c75c 100644 --- a/doc/GetPixmap.3 +++ b/doc/GetPixmap.3 @@ -33,7 +33,6 @@ Number of bits per pixel in pixmap. .AP Pixmap pixmap in Pixmap to destroy. .BE - .SH DESCRIPTION .PP These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR @@ -49,6 +48,5 @@ with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, and returns its identifier. \fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes its resource identifier available for reuse. - .SH KEYWORDS pixmap, resource identifier diff --git a/doc/GetRelief.3 b/doc/GetRelief.3 index a65baf7..6e8681a 100644 --- a/doc/GetRelief.3 +++ b/doc/GetRelief.3 @@ -28,13 +28,14 @@ const char * Interpreter to use for error reporting. .AP Tcl_Obj *objPtr in/out String value contains name of relief, one of -.QW flat , -.QW groove , -.QW raised , -.QW ridge , -.QW solid , +.QW \fBflat\fR , +.QW \fBgroove\fR , +.QW \fBraised\fR , +.QW \fBridge\fR , +.QW \fBsolid\fR , or -.QW sunken ; +.QW \fBsunken\fR +(or any unique abbreviation thereof on input); the internal rep will be modified to cache corresponding relief value. .AP char *string in Same as \fIobjPtr\fR except description of relief is passed as diff --git a/doc/GetScroll.3 b/doc/GetScroll.3 index 2c98403..abd0880 100644 --- a/doc/GetScroll.3 +++ b/doc/GetScroll.3 @@ -9,46 +9,45 @@ .so man.macros .BS .SH NAME -Tk_GetScrollInfo, Tk_GetScrollInfoObj \- parse arguments for scrolling commands +Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int -\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR +\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR .sp int -\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR +\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR .SH ARGUMENTS -.AS "Tcl_Interp" *dblPtr +.AS "Tcl_Interp" *fractionPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. -.AP int argc in -Number of strings in \fIargv\fR array. -.AP "const char" *argv[] in -Argument strings. These represent the entire widget command, of -which the first word is typically the widget name and the second -word is typically \fBxview\fR or \fByview\fR. .AP int objc in Number of Tcl_Obj's in \fIobjv\fR array. .AP "Tcl_Obj *const" objv[] in Argument objects. These represent the entire widget command, of which the first word is typically the widget name and the second word is typically \fBxview\fR or \fByview\fR. -.AP double *dblPtr out +.AP int argc in +Number of strings in \fIargv\fR array. +.AP "const char" *argv[] in +Argument strings. These represent the entire widget command, of +which the first word is typically the widget name and the second +word is typically \fBxview\fR or \fByview\fR. +.AP double *fractionPtr out Filled in with fraction from \fBmoveto\fR option, if any. -.AP int *intPtr out +.AP int *stepsPtr out Filled in with line or page count from \fBscroll\fR option, if any. The value may be negative. .BE - .SH DESCRIPTION .PP -\fBTk_GetScrollInfo\fR parses the arguments expected by widget +\fBTk_GetScrollInfoObj\fR parses the arguments expected by widget scrolling commands such as \fBxview\fR and \fByview\fR. It receives the entire list of words that make up a widget command -and parses the words starting with \fIargv\fR[2]. -The words starting with \fIargv\fR[2] must have one of the following forms: +and parses the words starting with \fIobjv\fR[2]. +The words starting with \fIobjv\fR[2] must have one of the following forms: .CS \fBmoveto \fIfraction\fR \fBscroll \fInumber\fB units\fR @@ -57,20 +56,20 @@ The words starting with \fIargv\fR[2] must have one of the following forms: .LP Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR keywords may be abbreviated. -If \fIargv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR -is returned as result and \fI*dblPtr\fR is filled in with the +If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR +is returned as result and \fI*fractionPtr\fR is filled in with the \fIfraction\fR argument to the command, which must be a proper real value. -If \fIargv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR -or \fBTK_SCROLL_PAGES\fR is returned and \fI*intPtr\fR is filled +If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR +or \fBTK_SCROLL_PAGES\fR is returned and \fI*stepsPtr\fR is filled in with the \fInumber\fR value, which must be a proper integer. If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR -is returned and an error message is left in \fIinterp->result\fR. +is returned and an error message is left in interpreter +\fIinterp\fR's result. .PP -\fBTk_GetScrollInfoObj\fR is identical in function to -\fBTk_GetScrollInfo\fR. However, \fBTk_GetScrollInfoObj\fR accepts -Tcl_Obj style arguments, making it more appropriate for use with new -development. - +\fBTk_GetScrollInfo\fR is identical in function to +\fBTk_GetScrollInfoObj\fR. However, \fBTk_GetScrollInfo\fR accepts +string arguments, making it more appropriate for use with legacy +widgets. .SH KEYWORDS parse, scrollbar, scrolling command, xview, yview diff --git a/doc/GetSelect.3 b/doc/GetSelect.3 index 47e2b60..8c30a2b 100644 --- a/doc/GetSelect.3 +++ b/doc/GetSelect.3 @@ -33,7 +33,6 @@ are retrieved. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP \fBTk_GetSelection\fR retrieves the selection specified by the atom @@ -42,13 +41,15 @@ selection may actually be retrieved in several pieces; as each piece is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR should have arguments and result that match the type \fBTk_GetSelProc\fR: +.PP .CS -typedef int Tk_GetSelProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIportion\fR); +typedef int \fBTk_GetSelProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + char *\fIportion\fR); .CE -The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR +.PP +The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR will be copies of the corresponding arguments to \fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to a string containing part or all of the selection. For large @@ -68,10 +69,10 @@ been completely retrieved and processed by \fIproc\fR, or when a fatal error has occurred (e.g. the selection owner did not respond promptly). \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR; if an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message -in \fIinterp->result\fR. \fIProc\fR should also return either -\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in dealing with the -selection, it should leave an error message in \fIinterp->result\fR -and return \fBTCL_ERROR\fR; this will abort the selection retrieval. - +in interpreter \fIinterp\fR's result. \fIProc\fR should also return either +\fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in +dealing with the selection, it should leave an error message in the +interpreter result and return \fBTCL_ERROR\fR; this will abort the +selection retrieval. .SH KEYWORDS format, get, selection retrieval diff --git a/doc/GetUid.3 b/doc/GetUid.3 index 18300cc..06b466a 100644 --- a/doc/GetUid.3 +++ b/doc/GetUid.3 @@ -21,7 +21,6 @@ Tk_Uid String for which the corresponding unique identifier is desired. .BE - .SH DESCRIPTION .PP \fBTk_GetUid\fR returns the unique identifier corresponding @@ -42,6 +41,5 @@ Tk_Uid may be compared directly (x == y) without having to call \fBstrcmp\fR. In addition, the return value from \fBTk_GetUid\fR will have the same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). - .SH KEYWORDS atom, unique identifier diff --git a/doc/GetVRoot.3 b/doc/GetVRoot.3 index 18214b9..a65ef78 100644 --- a/doc/GetVRoot.3 +++ b/doc/GetVRoot.3 @@ -28,7 +28,6 @@ Points to word in which to store width of virtual root. .AP "int" heightPtr out Points to word in which to store height of virtual root. .BE - .SH DESCRIPTION .PP \fBTk_GetVRootGeometry\fR returns geometry information about the virtual @@ -43,6 +42,5 @@ If \fItkwin\fR is not associated with a virtual root (e.g. because the window manager does not use virtual roots) then *\fIxPtr\fR and *\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR will be set to the dimensions of the screen containing \fItkwin\fR. - .SH KEYWORDS geometry, height, location, virtual root, width, window manager diff --git a/doc/GetVisual.3 b/doc/GetVisual.3 index d0d95e8..fe3d50c 100644 --- a/doc/GetVisual.3 +++ b/doc/GetVisual.3 @@ -39,7 +39,7 @@ It returns a pointer to the X Visual structure for the visual and stores the number of bits per pixel for it at \fI*depthPtr\fR. If \fIstring\fR is unrecognizable or if no suitable visual could be found, then NULL is returned and \fBTk_GetVisual\fR leaves -an error message in \fIinterp->result\fR. +an error message in interpreter \fIinterp\fR's result. If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR also locates an appropriate colormap for use with the result visual and stores its X identifier at \fI*colormapPtr\fR. @@ -16,7 +16,6 @@ int .sp void \fBTk_Ungrab\fR(\fItkwin\fR) - .SH ARGUMENTS .AP Tcl_Interp *interp in Interpreter to use for error reporting @@ -25,7 +24,6 @@ Window on whose behalf the pointer is to be grabbed or released .AP int grabGlobal in Boolean indicating whether the grab is global or application local .BE - .SH DESCRIPTION .PP These functions are used to set or release a global or @@ -39,7 +37,6 @@ intended for windows in other applications) will be redirected to \fItkwin\fR. If the grab is application local, only mouse and keyboard events intended for a windows within the same application (but outside the tree rooted at \fItkwin\fR) will be redirected. - .PP \fBTk_Grab\fR sets a grab on a particular window. \fITkwin\fR specifies the window on whose behalf the pointer is to be grabbed. @@ -52,12 +49,10 @@ successfully, no window outside the tree rooted at \fItkwin\fR will receive pointer- or keyboard-related events until the next call to Tk_Ungrab. If a previous grab was in effect within the application, then it is replaced with a new one. - .PP -\fBTcl_Ungrab\fR releases a grab on the mouse pointer and keyboard, if +\fBTk_Ungrab\fR releases a grab on the mouse pointer and keyboard, if there is one set on the window given by \fItkwin\fR. Once a grab is released, pointer and keyboard events will start being delivered to other windows again. - .SH KEYWORDS grab, window diff --git a/doc/HWNDToWindow.3 b/doc/HWNDToWindow.3 index e58a2cd..9795099 100644 --- a/doc/HWNDToWindow.3 +++ b/doc/HWNDToWindow.3 @@ -17,12 +17,10 @@ Tk_Window .AP HWND hwnd in Windows handle for the window. .BE - .SH DESCRIPTION .PP Given a Windows HWND window identifier, this procedure returns the corresponding Tk_Window handle. If there is no Tk_Window corresponding to \fIhwnd\fR then NULL is returned. - .SH KEYWORDS Windows window id diff --git a/doc/HandleEvent.3 b/doc/HandleEvent.3 index 91a76aa..bc293b6 100644 --- a/doc/HandleEvent.3 +++ b/doc/HandleEvent.3 @@ -21,12 +21,11 @@ Tk_HandleEvent \- invoke event handlers for window system events Pointer to X event to dispatch to relevant handler(s). It is important that all unused fields of the structure be set to zero. .BE - .SH DESCRIPTION .PP \fBTk_HandleEvent\fR is a lower-level procedure that deals with window events. It is called by \fBTcl_ServiceEvent\fR (and indirectly by -\fBTcl_DoOneEvent\fR), and in a few other cases within Tk. +\fBTk_DoOneEvent\fR), and in a few other cases within Tk. It makes callbacks to any window event handlers (created by calls to \fBTk_CreateEventHandler\fR) that match \fIeventPtr\fR and then returns. In some cases @@ -43,6 +42,5 @@ as when a notifier has been popped up and an application wishes to wait for the user to click a button in the notifier before doing anything else. - .SH KEYWORDS callback, event, handler, window diff --git a/doc/IdToWindow.3 b/doc/IdToWindow.3 index 7d83a4c..f6e397d 100644 --- a/doc/IdToWindow.3 +++ b/doc/IdToWindow.3 @@ -22,13 +22,11 @@ X display containing the window. .AP Window window in X id for window. .BE - .SH DESCRIPTION .PP Given an X window identifier and the X display it corresponds to, this procedure returns the corresponding Tk_Window handle. If there is no Tk_Window corresponding to \fIwindow\fR then NULL is returned. - .SH KEYWORDS X window id diff --git a/doc/ImgChanged.3 b/doc/ImgChanged.3 index 3049e63..f4d2c04 100644 --- a/doc/ImgChanged.3 +++ b/doc/ImgChanged.3 @@ -35,7 +35,6 @@ Current width of image, in pixels. .AP "int" imageHeight in Current height of image, in pixels. .BE - .SH DESCRIPTION .PP An image manager calls \fBTk_ImageChanged\fR for an image @@ -59,9 +58,7 @@ that changed. If the size of the image should change, then \fBTk_ImageChanged\fR must be called to indicate the new size, even if no pixels need to be redisplayed. - .SH "SEE ALSO" Tk_CreateImageType - .SH KEYWORDS images, redisplay, image size changes diff --git a/doc/Inactive.3 b/doc/Inactive.3 index 7338676..5528fa5 100644 --- a/doc/Inactive.3 +++ b/doc/Inactive.3 @@ -21,7 +21,6 @@ long 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 @@ -31,6 +30,5 @@ 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 8e5e866..a16eee1 100644 --- a/doc/InternAtom.3 +++ b/doc/InternAtom.3 @@ -28,7 +28,6 @@ String name for which atom is desired. .AP Atom atom in Atom for which corresponding string name is desired. .BE - .SH DESCRIPTION .PP These procedures are similar to the Xlib procedures @@ -52,6 +51,5 @@ for the same information can be serviced from the cache without contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR are generally much faster than their Xlib counterparts, and they should be used in place of the Xlib procedures. - .SH KEYWORDS atom, cache, display diff --git a/doc/MainLoop.3 b/doc/MainLoop.3 index 6588713..ed4d0ea 100644 --- a/doc/MainLoop.3 +++ b/doc/MainLoop.3 @@ -16,7 +16,6 @@ Tk_MainLoop \- loop for events until all windows are deleted .sp \fBTk_MainLoop\fR() .BE - .SH DESCRIPTION .PP \fBTk_MainLoop\fR is a procedure that loops repeatedly calling @@ -25,6 +24,5 @@ left in this process (i.e. no main windows exist anymore). Most windowing applications will call \fBTk_MainLoop\fR after initialization; the main execution of the application will consist entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. - .SH KEYWORDS application, event, main loop diff --git a/doc/MainWin.3 b/doc/MainWin.3 index 495e799..c3af3e7 100644 --- a/doc/MainWin.3 +++ b/doc/MainWin.3 @@ -9,8 +9,7 @@ .so man.macros .BS .SH NAME -Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main -window information +Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window information .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -20,13 +19,11 @@ Tk_Window .sp int \fBTk_GetNumMainWindows\fR() - .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tcl_Interp *interp in/out Interpreter associated with the application. .BE - .SH DESCRIPTION .PP A main window is a special kind of toplevel window used as the @@ -35,10 +32,9 @@ outermost window in an application. If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR returns the application's main window. If there is no Tk application associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and -leaves an error message in \fIinterp->result\fR. +leaves an error message in interpreter \fIinterp\fR's result. .PP \fBTk_GetNumMainWindows\fR returns a count of the number of main -windows currently open in the process. - +windows currently open in the current thread. .SH KEYWORDS application, main window diff --git a/doc/MaintGeom.3 b/doc/MaintGeom.3 index b052ba1..d1c2d1c 100644 --- a/doc/MaintGeom.3 +++ b/doc/MaintGeom.3 @@ -36,7 +36,6 @@ Desired width for \fIslave\fR, in pixels. .AP int height in Desired height for \fIslave\fR, in pixels. .BE - .SH DESCRIPTION .PP \fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it diff --git a/doc/ManageGeom.3 b/doc/ManageGeom.3 index 371b896..520546f 100644 --- a/doc/ManageGeom.3 +++ b/doc/ManageGeom.3 @@ -45,7 +45,7 @@ typedef struct { const char *\fIname\fR; Tk_GeomRequestProc *\fIrequestProc\fR; Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; -} Tk_GeomMgr; +} \fBTk_GeomMgr\fR; .CE The \fIname\fR field is the textual name for the geometry manager, such as \fBpack\fR or \fBplace\fR; this value will be returned @@ -57,9 +57,9 @@ slave to change its desired geometry. \fIrequestProc\fR should have arguments and results that match the type \fBTk_GeomRequestProc\fR: .CS -typedef void Tk_GeomRequestProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); +typedef void \fBTk_GeomRequestProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); .CE The parameters to \fIrequestProc\fR will be identical to the corresponding parameters passed to \fBTk_ManageGeometry\fR. @@ -80,12 +80,11 @@ is the same as the window's current geometry manager. \fIlostSlaveProc\fR should have arguments and results that match the following prototype: .CS -typedef void Tk_GeomLostSlaveProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); +typedef void \fBTk_GeomLostSlaveProc\fR( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); .CE The parameters to \fIlostSlaveProc\fR will be identical to the corresponding parameters passed to \fBTk_ManageGeometry\fR. - .SH KEYWORDS callback, geometry, managed, request, unmanaged diff --git a/doc/MapWindow.3 b/doc/MapWindow.3 index ead9cd5..8abce64 100644 --- a/doc/MapWindow.3 +++ b/doc/MapWindow.3 @@ -23,7 +23,6 @@ Tk_Window .AP Tk_Window tkwin in Token for window. .BE - .SH DESCRIPTION .PP These procedures may be used to map and unmap windows @@ -46,6 +45,5 @@ These procedures should be used in place of the X procedures Tk's local data structure for \fItkwin\fR. Applications using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR directly. - .SH KEYWORDS map, unmap, window diff --git a/doc/MoveToplev.3 b/doc/MoveToplev.3 index 18436a3..effed29 100644 --- a/doc/MoveToplev.3 +++ b/doc/MoveToplev.3 @@ -28,7 +28,6 @@ New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the top-left pixel of the decorative border supplied for \fItkwin\fR by the window manager, if there is one. .BE - .SH DESCRIPTION .PP In general, a window should never set its own position; this should be @@ -48,6 +47,5 @@ When \fBTk_MoveToplevelWindow\fR is called it does not immediately pass on the new desired location to the window manager; it defers this action until all other outstanding work has been completed, using the \fBTk_DoWhenIdle\fR mechanism. - .SH KEYWORDS position, top-level window, window manager @@ -31,7 +31,6 @@ Interpreter to use for error reporting. .AP "const char" *pathName in Character string containing path name of window. .BE - .SH DESCRIPTION .PP Each window managed by Tk has two names, a short name that identifies @@ -49,8 +48,7 @@ as a Tk_Uid, which may be used just like a string pointer but also has the properties of a unique identifier (see the manual entry for \fBTk_GetUid\fR for details). .PP -The \fBTk_PathName\fR macro returns a -hierarchical name for \fItkwin\fR. +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 @@ -75,7 +73,8 @@ The procedure \fBTk_NameToWindow\fR returns the token for a window given its path name (the \fIpathName\fR argument) and another window belonging to the same main window (\fItkwin\fR). It normally returns a token for the named window, but if no such window exists -\fBTk_NameToWindow\fR leaves an error message in \fIinterp->result\fR +\fBTk_NameToWindow\fR leaves an error message in interpreter +\fIinterp\fR's result and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR is needed because path names are only unique within a single application hierarchy. If, for example, a single process has opened @@ -83,6 +82,5 @@ two main windows, each will have a separate naming hierarchy and the same path name might appear in each of the hierarchies. Normally \fItkwin\fR is the main window of the desired hierarchy, but this need not be the case: any window in the desired hierarchy may be used. - .SH KEYWORDS name, path name, token, window diff --git a/doc/NameOfImg.3 b/doc/NameOfImg.3 index 049b94c..78332db 100644 --- a/doc/NameOfImg.3 +++ b/doc/NameOfImg.3 @@ -21,12 +21,10 @@ const char * Token for image, which was passed to image manager's \fIcreateProc\fR when the image was created. .BE - .SH DESCRIPTION .PP This procedure is invoked by image managers to find out the name of an image. Given the token for the image, it returns the string name for the image. - .SH KEYWORDS image manager, image name diff --git a/doc/OwnSelect.3 b/doc/OwnSelect.3 index 2977fcd..ed9bcab 100644 --- a/doc/OwnSelect.3 +++ b/doc/OwnSelect.3 @@ -26,7 +26,6 @@ Procedure to invoke when \fItkwin\fR loses selection ownership later. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP \fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the @@ -39,12 +38,12 @@ invoked so that the window can clean itself up (e.g. by unhighlighting the selection). \fIProc\fR should have arguments and result that match the type \fBTk_LostSelProc\fR: .CS -typedef void Tk_LostSelProc(ClientData \fIclientData\fR); +typedef void \fBTk_LostSelProc\fR( + ClientData \fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is usually a pointer to a data structure containing application-specific information about \fItkwin\fR. - .SH KEYWORDS own, selection owner diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 index 65f184b..3a9bd49 100644 --- a/doc/ParseArgv.3 +++ b/doc/ParseArgv.3 @@ -60,8 +60,8 @@ elements of \fIargv\fR. .PP \fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and -\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR -in the standard Tcl fashion. In +\fBTk_ParseArgv\fR will leave an error message in the result of +interpreter \fIinterp\fR in the standard Tcl fashion. In the event of an error return, \fI*argvPtr\fR will not have been modified, but \fIargv\fR could have been partially modified. The possible causes of errors are explained below. @@ -70,12 +70,12 @@ 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; + const char *\fIkey\fR; int \fItype\fR; char *\fIsrc\fR; char *\fIdst\fR; - char *\fIhelp\fR; -} Tk_ArgvInfo; + const char *\fIhelp\fR; +} \fBTk_ArgvInfo\fR; .CE The \fIkey\fR field is a string such as .QW \-display @@ -186,7 +186,8 @@ specifiers of this type are ignored (as if they did not exist). \fBTK_ARGV_HELP\fR When this kind of option is encountered, \fBTk_ParseArgv\fR uses the \fIhelp\fR fields of \fIargTable\fR to format a message describing -all the valid arguments. The message is placed in \fIinterp->result\fR +all the valid arguments. The message is placed in interpreter +\fIinterp\fR's result and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the caller normally prints the help message and aborts. If the \fIkey\fR field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will @@ -259,11 +260,12 @@ then return any that are left by compacting them to the beginning of \fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR should return a count of how many arguments are left in \fIargv\fR; \fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters -an error then it should leave an error message in \fIinterp->result\fR, +an error then it should leave an error message in interpreter +\fIinterp\fR's result, in the usual Tcl fashion, and return \-1; when this happens \fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. .RE -.SH "FLAGS" +.SS "FLAGS" .TP \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR \fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program @@ -329,7 +331,7 @@ main(argc, argv) \&... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { - fprintf(stderr, "%s\en", interp->result); + fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp))); exit(1); } diff --git a/doc/QWinEvent.3 b/doc/QWinEvent.3 index e801fbc..caa5026 100644 --- a/doc/QWinEvent.3 +++ b/doc/QWinEvent.3 @@ -30,7 +30,6 @@ that all unused fields of the structure be set to zero. Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. .BE - .SH DESCRIPTION .PP \fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event @@ -47,6 +46,5 @@ returns the previous value for collapse behavior on the \fIdisplay\fR. The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has the same significance as for \fBTcl_QueueEvent\fR; see the documentation for \fBTcl_QueueEvent\fR for details. - .SH KEYWORDS callback, clock, handler, modal timeout, events diff --git a/doc/Restack.3 b/doc/Restack.3 index f026aeb..2b9097f 100644 --- a/doc/Restack.3 +++ b/doc/Restack.3 @@ -28,7 +28,6 @@ must be \fBAbove\fR or \fBBelow\fR. Must be a sibling of \fItkwin\fR or a descendant of a sibling. If NULL then \fItkwin\fR is restacked above or below all siblings. .BE - .SH DESCRIPTION .PP \fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative @@ -42,6 +41,5 @@ just above or below \fIother\fR. The \fIaboveBelow\fR argument must have one of the symbolic values \fBAbove\fR or \fBBelow\fR. Both of these values are defined by the include file <X11/Xlib.h>. - .SH KEYWORDS above, below, obscure, stacking order diff --git a/doc/RestrictEv.3 b/doc/RestrictEv.3 index 0d17806..eb1f040 100644 --- a/doc/RestrictEv.3 +++ b/doc/RestrictEv.3 @@ -15,18 +15,17 @@ Tk_RestrictEvents \- filter and selectively delay X events \fB#include <tk.h>\fR .sp Tk_RestrictProc * -\fBTk_RestrictEvents\fR(\fIproc, clientData, prevClientDataPtr\fR) +\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) .SH ARGUMENTS -.AS Tk_RestrictProc **prevClientDataPtr +.AS Tk_RestrictProc **prevArgPtr .AP Tk_RestrictProc *proc in Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. -.AP ClientData clientData in +.AP ClientData arg in Arbitrary argument to pass to \fIproc\fR. -.AP ClientData *prevClientDataPtr out +.AP ClientData *prevArgPtr out Pointer to place to save argument to previous restrict procedure. .BE - .SH DESCRIPTION .PP This procedure is useful in certain situations where applications @@ -40,11 +39,11 @@ later time (e.g. when the event restriction is lifted), or discarded. 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); +typedef Tk_RestrictAction \fBTk_RestrictProc\fR( + ClientData \fIarg\fR, + XEvent *\fIeventPtr\fR); .CE -The \fIclientData\fR argument is a copy of the \fIclientData\fR passed +The \fIarg\fR argument is a copy of the \fIarg\fR passed to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with information it needs to filter events. The \fIeventPtr\fR points to an event under consideration. \fIProc\fR returns a restrict action @@ -56,7 +55,7 @@ left on the event queue for later processing. If the return value is \fBTK_DISCARD_EVENT\fR, then the event will be removed from the event queue and discarded without being processed. .PP -\fBTk_RestrictEvents\fR uses its return value and \fIprevClientDataPtr\fR +\fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR to return information about the current event restriction procedure (a NULL return value means there are currently no restrictions). These values may be used to restore the previous restriction state diff --git a/doc/SetAppName.3 b/doc/SetAppName.3 index f69f920..3978850 100644 --- a/doc/SetAppName.3 +++ b/doc/SetAppName.3 @@ -24,7 +24,6 @@ application. .AP "const char" *name in Name under which to register the application. .BE - .SH DESCRIPTION .PP \fBTk_SetAppName\fR associates a name with a given application and @@ -59,6 +58,5 @@ so applications do not normally need to call it explicitly. .PP The command \fBtk appname\fR provides Tcl-level access to the functionality of \fBTk_SetAppName\fR. - .SH KEYWORDS application, name, register, send command diff --git a/doc/SetCaret.3 b/doc/SetCaret.3 index 571cf55..fd63f18 100644 --- a/doc/SetCaret.3 +++ b/doc/SetCaret.3 @@ -25,7 +25,6 @@ Window-relative y coordinate. .AP int h in Height of the caret in the window. .BE - .SH DESCRIPTION .PP \fBTk_SetCaretPos\fR sets the caret location for the display of the @@ -33,6 +32,5 @@ specified Tk_Window \fItkwin\fR. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. - .SH KEYWORDS caret, cursor diff --git a/doc/SetClass.3 b/doc/SetClass.3 index b485b7d..707975d 100644 --- a/doc/SetClass.3 +++ b/doc/SetClass.3 @@ -25,7 +25,6 @@ Token for window. .AP char *class in New class name for window. .BE - .SH DESCRIPTION .PP \fBTk_SetClass\fR is called to associate a class with a particular @@ -54,6 +53,5 @@ the properties of a unique identifier (see the manual entry for \fBTk_GetUid\fR for details). If \fItkwin\fR has not yet been given a class, then \fBTk_Class\fR will return NULL. - .SH KEYWORDS class, unique identifier, window, window manager diff --git a/doc/SetClassProcs.3 b/doc/SetClassProcs.3 index 8e6004a..58618da 100644 --- a/doc/SetClassProcs.3 +++ b/doc/SetClassProcs.3 @@ -18,14 +18,13 @@ Tk_SetClassProcs \- register widget specific procedures .AS Tk_ClassProc instanceData .AP Tk_Window tkwin in Token for window to modify. -.AP Tk_ClassProcs *procs in +.AP "const Tk_ClassProcs" *procs in Pointer to data structure containing widget specific procedures. The data structure pointed to by \fIprocs\fR must be static: Tk keeps a reference to it as long as the window exists. .AP ClientData instanceData in Arbitrary one-word value to pass to widget callbacks. .BE - .SH DESCRIPTION .PP \fBTk_SetClassProcs\fR is called to register a set of procedures that @@ -38,7 +37,7 @@ typedef struct Tk_ClassProcs { Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; Tk_ClassCreateProc *\fIcreateProc\fR; Tk_ClassModalProc *\fImodalProc\fR; -} Tk_ClassProcs; +} \fBTk_ClassProcs\fR; .CE The \fIsize\fR field is used to simplify future expansion of the structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR. @@ -50,8 +49,8 @@ widgets configured to use that font alias must update their display accordingly. \fIworldChangedProc\fR should have arguments and results that match the type \fBTk_ClassWorldChangedProc\fR: .CS -typedef void Tk_ClassWorldChangedProc( - ClientData \fIinstanceData\fR); +typedef void \fBTk_ClassWorldChangedProc\fR( + ClientData \fIinstanceData\fR); .CE The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR will be identical to the \fIinstanceData\fR parameter passed to @@ -61,10 +60,10 @@ will be identical to the \fIinstanceData\fR parameter passed to 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); +typedef Window \fBTk_ClassCreateProc\fR( + Tk_Window \fItkwin\fR, + Window \fIparent\fR, + ClientData \fIinstanceData\fR); .CE The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to the \fItkwin\fR and \fIinstanceData\fR parameters passed to @@ -76,14 +75,13 @@ created window. 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); +typedef void \fBTk_ClassModalProc\fR( + Tk_Window \fItkwin\fR, + XEvent *\fIeventPtr\fR); .CE The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the \fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR. The \fIeventPtr\fR parameter will be a pointer to an XEvent structure describing the event being processed. - .SH KEYWORDS callback, class diff --git a/doc/SetGrid.3 b/doc/SetGrid.3 index 385c920..28e428b 100644 --- a/doc/SetGrid.3 +++ b/doc/SetGrid.3 @@ -32,7 +32,6 @@ Width of one grid unit, in pixels. .AP int heightInc in Height of one grid unit, in pixels. .BE - .SH DESCRIPTION .PP \fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's @@ -60,6 +59,5 @@ toplevel, the calls for the new window have no effect. .PP See the \fBwm\fR manual entry for additional information on gridded geometry management. - .SH KEYWORDS grid, window, window manager diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index 028467a..ebd6f6a 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -259,7 +259,7 @@ typedef struct { int \fIobjOffset\fR; int \fIinternalOffset\fR; int \fIflags\fR; - ClientData \fIclientData\fR; + const void *\fIclientData\fR; int \fItypeMask\fR; } \fBTk_OptionSpec\fR; .CE diff --git a/doc/SetVisual.3 b/doc/SetVisual.3 index 11d6e76..6d3fd83 100644 --- a/doc/SetVisual.3 +++ b/doc/SetVisual.3 @@ -28,7 +28,6 @@ Number of bits per pixel desired for \fItkwin\fR. New colormap for \fItkwin\fR, which must be compatible with \fIvisual\fR and \fIdepth\fR. .BE - .SH DESCRIPTION .PP When Tk creates a new window it assigns it the default visual @@ -47,6 +46,5 @@ completed successfully. Note: \fBTk_SetWindowVisual\fR should not be called if you just want to change a window's colormap without changing its visual or depth; call \fBTk_SetWindowColormap\fR instead. - .SH KEYWORDS colormap, depth, visual diff --git a/doc/StrictMotif.3 b/doc/StrictMotif.3 index 6d1e049..4319d53 100644 --- a/doc/StrictMotif.3 +++ b/doc/StrictMotif.3 @@ -20,7 +20,6 @@ int .AP Tk_Window tkwin in Token for window. .BE - .SH DESCRIPTION .PP This procedure returns the current value of the \fBtk_strictMotif\fR @@ -35,6 +34,5 @@ is good enough, and extra features are welcome. This procedure uses a link to the Tcl variable to provide much faster access to the variable's value than could be had by calling \fBTcl_GetVar\fR. - .SH KEYWORDS Motif compliance, tk_strictMotif variable diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 index cd4a938..3863ee7 100644 --- a/doc/TextLayout.3 +++ b/doc/TextLayout.3 @@ -39,7 +39,6 @@ int .sp void \fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR - .SH ARGUMENTS .AS Tk_TextLayout "*xPtr, *yPtr" .AP Tk_Font tkfont in @@ -124,9 +123,8 @@ Specifies the width and height, in pixels, of the rectangular area to compare for intersection against the text layout. .AP Tcl_Interp *interp out Postscript code that will print the text layout is appended to -\fIinterp->result\fR. +the result of interpreter \fIinterp\fR. .BE - .SH DESCRIPTION .PP These routines are for measuring and displaying single-font, multi-line, @@ -184,9 +182,11 @@ whose \fIx\fR-value is less than 0 will be considered closest to the first character on that line; any point whose \fIx\fR-value is greater than the width of the text layout will be considered closest to the last character on that line. The return value is the index of the character that was closest -to the point. Given a \fIlayout\fR with no characters, the value 0 will -always be returned, referring to a hypothetical zero-width placeholder -character. +to the point, or one more than the index of any character (to indicate that +the point was after the end of the string and that the corresponding caret +would be at the end of the string). Given a \fIlayout\fR with no characters, +the value 0 will always be returned, referring to a hypothetical zero-width +placeholder character. .PP \fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the bounding box for the character specified by \fIindex\fR. The width of the @@ -231,8 +231,9 @@ array of strings that represent the individual lines in \fIlayout\fR. It is the responsibility of the caller to take the Postscript array of strings and add some Postscript function operate on the array to render each of the lines. The code that represents the Postscript array of -strings is appended to \fIinterp->result\fR. +strings is appended to interpreter \fIinterp\fR's result. .SH "DISPLAY MODEL" +.PP When measuring a text layout, space characters that occur at the end of a line are ignored. The space characters still exist and the insertion point can be positioned amongst them, but their additional width is ignored when diff --git a/doc/TkInitStubs.3 b/doc/TkInitStubs.3 index 69c0fb2..04f5611 100644 --- a/doc/TkInitStubs.3 +++ b/doc/TkInitStubs.3 @@ -34,7 +34,7 @@ as \fIversion\fR. The Tcl stubs mechanism defines a way to dynamically bind extensions to a particular Tcl implementation at run time. the stubs mechanism requires no changes to applications -incoporating Tcl/Tk interpreters. Only developers creating +incorporating Tcl/Tk interpreters. Only developers creating C-based Tcl/Tk extensions need to take steps to use the stubs mechanism with their extensions. See the \fBTcl_InitStubs\fR page for more information. @@ -48,15 +48,19 @@ Tcl functions. Call \fBTk_InitStubs\fR if the extension before calling any other Tk functions. .IP 2) 5 -Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the -\fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. +Define the \fBUSE_TCL_STUBS\fR and the \fBUSE_TK_STUBS\fR +symbols. Typically, you would include the \fB\-DUSE_TCL_STUBS\fR and +the \fB\-DUSE_TK_STUBS\fR flags when compiling the extension. .IP 3) 5 -Link the extension with the Tcl and Tk stubs libraries instead of -the standard Tcl and Tk libraries. On Unix platforms, the library -names are \fIlibtclstub8.4.a\fR and \fIlibtkstub8.4.a\fR; on Windows -platforms, the library names are \fItclstub84.lib\fR and \fItkstub84.lib\fR -(adjust names with appropriate version number). +Link the extension with the Tcl and Tk stubs libraries instead of the +standard Tcl and Tk libraries. On Unix platforms, the library names +are \fIlibtclstub8.4.a\fR and \fIlibtkstub8.4.a\fR; on Windows +platforms, the library names are \fItclstub84.lib\fR and +\fItkstub84.lib\fR. Adjust the library names with appropriate version +number but note that the extension may only be used with versions of +Tcl/Tk that have that version number or higher. .SH DESCRIPTION +.PP \fBTk_InitStubs\fR attempts to initialize the Tk stub table pointers and ensure that the correct version of Tk is loaded. In addition to an interpreter handle, it accepts as arguments a version number diff --git a/doc/Tk_Init.3 b/doc/Tk_Init.3 index 8682c7d..7bc46dd 100644 --- a/doc/Tk_Init.3 +++ b/doc/Tk_Init.3 @@ -23,7 +23,6 @@ int Interpreter in which to load Tk. Tk should not already be loaded in this interpreter. .BE - .SH DESCRIPTION .PP \fBTk_Init\fR is the package initialization procedure for Tk. @@ -34,7 +33,7 @@ and creates a new Tk application, including its main window. If the initialization is successful \fBTk_Init\fR returns \fBTCL_OK\fR; if there is an error it returns \fBTCL_ERROR\fR. \fBTk_Init\fR also leaves a result or error message -in \fIinterp->result\fR. +in interpreter \fIinterp\fR's result. .PP If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR treats the contents of this variable as a list of options for the @@ -82,6 +81,5 @@ from the user. \fBwm\fR If toplevels are ever allowed, wm can be used to remove decorations, move windows around, etc. - .SH KEYWORDS safe, application, initialization, load, main window diff --git a/doc/Tk_Main.3 b/doc/Tk_Main.3 index e45d597..a1bb149 100644 --- a/doc/Tk_Main.3 +++ b/doc/Tk_Main.3 @@ -20,12 +20,12 @@ Tk_Main \- main program for Tk-based applications .AP int argc in Number of elements in \fIargv\fR. .AP char *argv[] in -Array of strings containing command-line arguments. +Array of strings containing command-line arguments. On Windows, when +using -DUNICODE, the parameter type changes to wchar_t *. .AP Tcl_AppInitProc *appInitProc in Address of an application-specific initialization procedure. The value for this argument is usually \fBTcl_AppInit\fR. .BE - .SH DESCRIPTION .PP \fBTk_Main\fR acts as the main program for most Tk-based applications. @@ -50,11 +50,21 @@ for the application to perform its own initialization, such as defining application-specific commands. The procedure must have an interface that matches the type \fBTcl_AppInitProc\fR: .CS -typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_AppInitProc\fR( + Tcl_Interp *\fIinterp\fR); .CE \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more details on this procedure, see the documentation for \fBTcl_AppInit\fR. - +.PP +\fBTk_Main\fR functions much the same as \fBTcl_Main\fR. In particular, +\fBTk_Main\fR supports both an interactive mode and a startup script +mode, with the file name and encoding of a startup script under the +control of the \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR +routines. However it calls \fBTk_MainLoop\fR after processing any +supplied script, and in interactive uses events registered with +\fBTcl_CreateFileHandler\fR to process user input. +.SH "SEE ALSO" +Tcl_DoOneEvent(3) .SH KEYWORDS application-specific initialization, command-line arguments, main program diff --git a/doc/WindowId.3 b/doc/WindowId.3 index a6050a2..6d55dc0 100644 --- a/doc/WindowId.3 +++ b/doc/WindowId.3 @@ -102,7 +102,6 @@ Tcl_Interp * .AP Tk_Window tkwin in Token for window. .BE - .SH DESCRIPTION .PP \fBTk_WindowId\fR and the other names listed above are @@ -183,7 +182,6 @@ and \fBTk_Colormap\fR returns the current colormap for the window. The visual characteristics are normally set from the defaults for the window's screen, but they may be overridden by calling \fBTk_SetWindowVisual\fR. - .SH KEYWORDS attributes, colormap, depth, display, height, geometry manager, identifier, mapped, requested size, screen, top-level, @@ -15,7 +15,6 @@ bell \- Ring a display's bell .SH SYNOPSIS \fBbell \fR?\fB\-displayof \fIwindow\fR? ?\fB\-nice\fR? .BE - .SH DESCRIPTION .PP This command rings the bell on the display for \fIwindow\fR and @@ -28,6 +27,8 @@ may be modified with programs such as \fBxset\fR. If \fB\-nice\fR is not specified, this command also resets the screen saver for the screen. Some screen savers will ignore this, but others will reset so that the screen becomes visible again. - .SH KEYWORDS beep, bell, ring +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -151,7 +151,6 @@ requirement. 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" . @@ -160,7 +159,6 @@ 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 @@ -207,9 +205,7 @@ always routed to the window that currently has focus. When the event is received you can use the \fB%D\fR substitution to get the \fIdelta\fR field for the event, which is a integer value describing how the mouse wheel has moved. The smallest value for which the -system will report is defined by the OS. On Windows 95 & 98 machines -this value is at least 120 before it is reported. However, higher -resolution devices may be available in the future. The sign of the +system will report is defined by the OS. The sign of the value determines which direction your widget should scroll. Positive values should scroll up and negative values should scroll down. .IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5 @@ -429,10 +425,7 @@ The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. Indicates that there are \fIcount\fR pending \fBExpose\fR events which have not yet been delivered to the window. .IP \fB%d\fR 5 -The \fIdetail\fR -.VS 8.5 -or \fIuser_data\fR -.VE 8.5 +The \fIdetail\fR or \fIuser_data\fR field from the event. The \fB%d\fR is replaced by a string identifying the detail. For \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, @@ -452,13 +445,11 @@ For \fBConfigureRequest\fR events, the string will be one of: \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 @@ -534,9 +525,7 @@ The \fIborder_width\fR field from the event. Valid only for .IP \fB%D\fR 5 This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The \fIdelta\fR value represents the rotation units the mouse wheel has -been moved. On Windows 95 & 98 systems the smallest value for the -delta is 120. Future systems may support higher resolution values for -the delta. The sign of the value represents the direction the mouse +been moved. The sign of the value represents the direction the mouse wheel was scrolled. .IP \fB%E\fR 5 The \fIsend_event\fR field from the event. Valid for all event types. @@ -704,6 +693,7 @@ If an error occurs in executing the script for a binding then the The \fBbgerror\fR command will be executed at global level (outside the context of any Tcl procedure). .SH "EXAMPLES" +.PP Arrange for a string describing the motion of the mouse to be printed out when the mouse is double-clicked: .CS @@ -725,3 +715,6 @@ pack [label .l \-textvariable keysym \-padx 2m \-pady 1m] bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n) .SH KEYWORDS binding, event +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/bindtags.n b/doc/bindtags.n index 7db16f8..dc3973b 100644 --- a/doc/bindtags.n +++ b/doc/bindtags.n @@ -14,7 +14,6 @@ bindtags \- Determine which bindings apply to a window, and order of evaluation .SH SYNOPSIS \fBbindtags \fIwindow \fR?\fItagList\fR? .BE - .SH DESCRIPTION .PP When a binding is created with the \fBbind\fR command, it is @@ -73,6 +72,7 @@ associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR, but any bindings associated with \fBTrickyButton\fR (perhaps some new button behavior) will apply. .SH EXAMPLE +.PP If you have a set of nested \fBframe\fR widgets and you want events sent to a \fBbutton\fR widget to also be delivered to all the widgets up to the current \fBtoplevel\fR (in contrast to Tk's default @@ -93,9 +93,10 @@ proc setupBindtagsForTreeDelivery {widget} { \fBbindtags\fR $widget $tags } .CE - .SH "SEE ALSO" bind(n) - .SH KEYWORDS binding, event, tag +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/bitmap.n b/doc/bitmap.n index bcc44f8..ead3311 100644 --- a/doc/bitmap.n +++ b/doc/bitmap.n @@ -12,9 +12,13 @@ .SH NAME bitmap \- Images that display two colors .SH SYNOPSIS +.nf \fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? -.BE +\fIimageName \fBcget\fR \fIoption\fR +\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +.fi +.BE .SH DESCRIPTION .PP A bitmap is an image whose pixels can display either of two colors @@ -30,7 +34,6 @@ producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero. - .SH "CREATING BITMAPS" .PP Like all images, bitmaps are created using the \fBimage create\fR @@ -38,6 +41,7 @@ command. Bitmaps support the following \fIoptions\fR: .TP \fB\-background \fIcolor\fR +. Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect @@ -45,6 +49,7 @@ is achieved by using the source bitmap as the mask bitmap, ignoring any \fB\-maskdata\fR or \fB\-maskfile\fR options. .TP \fB\-data \fIstring\fR +. Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). @@ -52,16 +57,19 @@ If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-data\fR option takes precedence. .TP \fB\-file \fIname\fR +. \fIname\fR gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .TP \fB\-foreground \fIcolor\fR +. Specifies a foreground color for the image in any of the standard ways accepted by Tk. .TP \fB\-maskdata \fIstring\fR +. Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). @@ -69,11 +77,11 @@ If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, the \fB\-maskdata\fR option takes precedence. .TP \fB\-maskfile \fIname\fR +. \fIname\fR gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). - .SH "IMAGE COMMAND" .PP When a bitmap image is created, Tk also creates a new command @@ -89,12 +97,14 @@ determine the exact behavior of the command. The following commands are possible for bitmap images: .TP \fIimageName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the -\fBimage create bitmap\fR command. +\fBimage create\fR \fBbitmap\fR command. .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for @@ -106,7 +116,9 @@ one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the -\fBimage create bitmap\fR command. - +\fBimage create\fR \fBbitmap\fR command. .SH KEYWORDS bitmap, image +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/busy.n b/doc/busy.n new file mode 100644 index 0000000..e588275 --- /dev/null +++ b/doc/busy.n @@ -0,0 +1,267 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" Copyright (c) 2008 Jos Decoster +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that +'\" the copyright notice and warranty disclaimer appear in supporting +'\" documentation, and that the names of Lucent Technologies any of their +'\" entities not be used in advertising or publicity pertaining to +'\" distribution of the software without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no +'\" event shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of +'\" use, data or profits, whether in an action of contract, negligence or +'\" other tortuous action, arising out of or in connection with the use or +'\" performance of this software. +'\" +'\" BLT::busy command created by George Howlett. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH busy n "" Tk "Tk Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +busy \- confine pointer and keyboard events to a window sub-tree +.SH SYNOPSIS +\fBtk busy\fR \fIwindow \fR?\fIoptions\fR? +.sp +\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR? +.sp +\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... +.sp +\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?... +.sp +\fBtk busy current\fR ?\fIpattern\fR? +.sp +\fBtk busy status \fIwindow\fR +.BE +.SH DESCRIPTION +.PP +The \fBtk busy\fR command provides a simple means to block keyboard, button, +and pointer events from Tk widgets, while overriding the widget's cursor with +a configurable busy cursor. +.SH INTRODUCTION +.PP +There are many times in applications where you want to temporarily restrict +what actions the user can take. For example, an application could have a +.QW Run +button that when pressed causes some processing to occur. However, while the +application is busy processing, you probably don't want the user to be +able to click the +.QW Run +button again. You may also want restrict the user from other tasks such as +clicking a +.QW Print +button. +.PP +The \fBtk busy\fR command lets you make Tk widgets busy. This means that user +interactions such as button clicks, moving the mouse, typing at the keyboard, +etc.\0are ignored by the widget. You can set a special cursor (like a watch) +that overrides the widget's normal cursor, providing feedback that the +application (widget) is temporarily busy. +.PP +When a widget is made busy, the widget and all of its descendants will ignore +events. It's easy to make an entire panel of widgets busy. You can simply make +the toplevel widget (such as +.QW . ) +busy. This is easier and far much more efficient than recursively traversing +the widget hierarchy, disabling each widget and re-configuring its cursor. +.PP +Often, the \fBtk busy\fR command can be used instead of Tk's \fBgrab\fR +command. Unlike \fBgrab\fR which restricts all user interactions to one +widget, with the \fBtk busy\fR command you can have more than one widget +active (for example, a +.QW Cancel +dialog and a +.QW Help +button). +.SS EXAMPLE +.PP +You can make several widgets busy by simply making its ancestor widget busy +using the \fBhold\fR operation. +.PP +.CS +frame .top +button .top.button; canvas .top.canvas +pack .top.button .top.canvas +pack .top +# . . . +\fBtk busy\fR hold .top +update +.CE +.PP +All the widgets within \fB.top\fR (including \fB.top\fR) are now busy. Using +\fBupdate\fR insures that \fBtk busy\fR command will take effect before any +other user events can occur. +.PP +When the application is no longer busy processing, you can allow user +interactions again and free any resources it allocated by the \fBforget\fR +operation. +.PP +.CS +\fBtk busy\fR forget .top +.CE +.PP +The busy window has a configurable cursor. You can change the busy cursor +using the \fBconfigure\fR operation. +.PP +.CS +\fBtk busy\fR configure .top \-cursor "watch" +.CE +.PP +Destroying the widget will also clean up any resources allocated by the \fBtk +busy\fR command. +.PP +.SH OPERATIONS +.PP +The following operations are available for the \fBtk busy\fR command: +.TP +\fBtk busy \fIwindow\fR ?\fIoption value\fR?... +. +Shortcut for \fBtk busy hold\fR command. +.TP +\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... +. +Makes the specified \fIwindow\fR (and its descendants in the Tk window +hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. +A transparent window is put in front of the specified window. This transparent +window is mapped the next time idle tasks are processed, and the specified +window and its descendants will be blocked from user interactions. Normally +\fBupdate\fR should be called immediately afterward to insure that the hold +operation is in effect before the application starts its processing. The +following configuration options are valid: +.RS +.TP +\fB\-cursor \fIcursorName\fR +. +Specifies the cursor to be displayed when the widget is made busy. +\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The +default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. +.RE +.TP +\fBtk busy cget \fIwindow\fR \fIoption\fR +. +Queries the \fBtk busy\fR command configuration options for \fIwindow\fR. +\fIWindow\fR must be the path name of a widget previously made busy by the +\fBhold\fR operation. The command returns the present value of the specified +\fIoption\fR. \fIOption\fR may have any of the values accepted by the +\fBhold\fR operation. +.TP +\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... +. +Queries or modifies the \fBtk busy\fR command configuration options for +\fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made +busy by the \fBhold\fR operation. If no options are specified, a list +describing all of the available options for \fIwindow\fR (see +\fBTk_ConfigureInfo\fR for information on the format of this list) is +returned. If \fIoption\fR is specified with no \fIvalue\fR, then the command +returns a list describing the one named option (this list will be identical to +the corresponding sublist of the value returned if no \fIoption\fR is +specified). If one or more \fIoption\-value\fR pairs are specified, then the +command modifies the given widget option(s) to have the given value(s); in +this case the command returns the empty string. \fIOption\fR may have any of +the values accepted by the \fBhold\fR operation. +.RS +.PP +Please note that the option database is referenced through \fIwindow\fR. For +example, if the widget \fB.frame\fR is to be made busy, the busy cursor can be +specified for it by either \fBoption\fR command: +.PP +.CS +option add *frame.busyCursor gumby +option add *Frame.BusyCursor gumby +.CE +.RE +.TP +\fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... +. +Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR, +including the transparent window. User events will again be received by +\fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. +\fIWindow\fR must be the name of a widget specified in the \fBhold\fR +operation, otherwise an error is reported. +.TP +\fBtk busy current \fR?\fIpattern\fR? +. +Returns the pathnames of all widgets that are currently busy. If a +\fIpattern\fR is given, only the path names of busy widgets matching +\fIpattern\fR are returned. +.TP +\fBtk busy status \fIwindow\fR +. +Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not +receive user interactions, \fB1\fR is returned, otherwise \fB0\fR. +.SH "EVENT HANDLING" +.SS BINDINGS +.PP +The event blocking feature is implemented by creating and mapping a +transparent window that completely covers the widget. When the busy window is +mapped, it invisibly shields the widget and its hierarchy from all events that +may be sent. Like Tk widgets, busy windows have widget names in the Tk window +hierarchy. This means that you can use the \fBbind\fR command, to handle +events in the busy window. +.PP +.CS +\fBtk busy\fR hold .frame.canvas +bind .frame.canvas_Busy <Enter> { ... } +.CE +.PP +Normally the busy window is a sibling of the widget. The name of the busy +window is +.QW \fIwidget\fB_Busy\fR +where \fIwidget\fR is the name of the widget to be made busy. In the previous +example, the pathname of the busy window is +.QW \fB.frame.canvas_Busy\fR . +The exception is when the widget is a toplevel widget (such as +.QW . ) +where the busy window can't be made a sibling. The busy window is then a child +of the widget named +.QW \fIwidget\fB._Busy\fR +where \fIwidget\fR is the name of the toplevel widget. In the following +example, the pathname of the busy window is +.QW \fB._Busy\fR . +.PP +.CS +\fBtk busy\fR hold . +bind ._Busy <Enter> { ... } +.CE +.SS "ENTER/LEAVE EVENTS" +.PP +Mapping and unmapping busy windows generates Enter/Leave events for all +widgets they cover. Please note this if you are tracking Enter/Leave events in +widgets. +.SS "KEYBOARD EVENTS" +.PP +When a widget is made busy, the widget is prevented from gaining the keyboard +focus by the busy window. But if the widget already had focus, it still may +received keyboard events. To prevent this, you must move focus to another +window. +.PP +.CS +\fBtk busy\fR hold .frame +label .dummy +focus .dummy +update +.CE +.PP +The above example moves the focus from .frame immediately after invoking the +\fBhold\fR so that no keyboard events will be sent to \fB.frame\fR or any of +its descendants. +.SH PORTABILITY +.PP +Note that the \fBtk busy\fR command does not currently have any effect on OSX +when Tk is built using Aqua support. +.SH "SEE ALSO" +grab(n) +.SH KEYWORDS +busy, keyboard events, pointer events, window +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/button.n b/doc/button.n index 4acc05a..e9a45a3 100644 --- a/doc/button.n +++ b/doc/button.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -button \- Create and manipulate button widgets +button \- Create and manipulate 'button' action widgets .SH SYNOPSIS \fBbutton\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -57,14 +57,14 @@ The empty string is the default value. .OP \-state state State Specifies one of three states for the button: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the button is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is +\fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the button. In active state -the button is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the button +the button is displayed using the \fB\-activeforeground\fR and +\fB\-activebackground\fR options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the button is displayed. +In this state the \fB\-disabledforeground\fR and +\fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in @@ -75,7 +75,6 @@ If the width is negative then this specifies a minimum width. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE - .SH DESCRIPTION .PP The \fBbutton\fR command creates a new window (given by the @@ -92,18 +91,17 @@ there must not exist a window named \fIpathName\fR, but A button is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and +or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the -\fBunderline\fR option. +\fB\-underline\fR option. It can display itself in either of three different ways, according to -the \fBstate\fR option; +the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; and it can be made to flash. When a user invokes the button (by pressing mouse button 1 with the cursor over the button), then the Tcl command specified in the \fB\-command\fR option is invoked. - .SH "WIDGET COMMAND" .PP The \fBbutton\fR command creates a new Tcl command whose @@ -139,9 +137,9 @@ command. .TP \fIpathName \fBflash\fR Flash the button. This is accomplished by redisplaying the button -several times, alternating between active and normal colors. At -the end of the flash the button is left in the same normal/active -state as when the command was invoked. +several times, alternating between the configured activebackground +and background colors. At the end of the flash the button is left +in the same normal/active state as when the command was invoked. This command is ignored if the button's state is \fBdisabled\fR. .TP \fIpathName \fBinvoke\fR @@ -149,7 +147,6 @@ Invoke the Tcl command associated with the button, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the button. This command is ignored if the button's state is \fBdisabled\fR. - .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for buttons that give them @@ -176,27 +173,38 @@ actions occur: the button is completely non-responsive. .PP The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. - +.SH "PLATFORM NOTES" +.PP +On Aqua/Mac OS X, some configuration options are ignored for the purpose of +drawing of the widget because they would otherwise conflict with platform +guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still +manipulate the values, but do not cause any variation to the look of the +widget. The options affected notably include \fB\-background\fR and +\fB\-relief\fR. .SH EXAMPLES +.PP This is the classic Tk .QW "Hello, World!" demonstration: .PP .CS - \fBbutton\fR .b \-text "Hello, World!" \-command exit - pack .b +\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 +\fBbutton\fR .b1 \-text Hello \-underline 0 +\fBbutton\fR .b2 \-text World \-underline 0 +bind . <Key\-h> {.b1 flash; .b1 invoke} +bind . <Key\-w> {.b2 flash; .b2 invoke} +pack .b1 .b2 .CE .SH "SEE ALSO" ttk::button(n) .SH KEYWORDS button, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/canvas.n b/doc/canvas.n index 676c1cd..bc29cc3 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -11,7 +11,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -canvas \- Create and manipulate canvas widgets +canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets .SH SYNOPSIS \fBcanvas\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -36,7 +36,7 @@ Defaults to true, which means that the view will be constrained within the scroll region. .OP \-height height Height Specifies a desired window height that the canvas widget should request from -its geometry manager. The value may be specified in any +its geometry manager. The value may be specified in any of the forms described in the \fBCOORDINATES\fR section below. .OP \-scrollregion scrollRegion ScrollRegion Specifies a list with four coordinates describing the left, top, right, and @@ -49,34 +49,34 @@ in any of the forms given in the \fBCOORDINATES\fR section below. Modifies the default state of the canvas where \fIstate\fR may be set to one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas objects all have their own state option which may override the default -state. Many options can take separate specifications such that the +state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with \fBactive\fR control the appearance when the mouse pointer is over it, while the option starting with \fBdisabled\fR controls -the appearance when the state is disabled. Canvas items which are +the appearance when the state is disabled. Canvas items which are \fBdisabled\fR will not react to canvas bindings. .OP \-width width width Specifies a desired window width that the canvas widget should request from -its geometry manager. The value may be specified in any +its geometry manager. The value may be specified in any of the forms described in the \fBCOORDINATES\fR section below. .OP \-xscrollincrement xScrollIncrement ScrollIncrement Specifies an increment for horizontal scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater +permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even -multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling +multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar -are selected) will also be \fBxScrollIncrement\fR. If the value of +are selected) will also be \fBxScrollIncrement\fR. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained. .OP \-yscrollincrement yScrollIncrement ScrollIncrement Specifies an increment for vertical scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater +permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even -multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling +multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar -are selected) will also be \fByScrollIncrement\fR. If the value of +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 @@ -88,7 +88,7 @@ Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The \fBcanvas\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, +\fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP @@ -97,7 +97,7 @@ A canvas displays any number of \fIitems\fR, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the \fBbind\fR -command allows commands to be bound to widgets. For example, +command allows commands to be bound to widgets. For example, a particular command may be associated with the <Button-1> event so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. @@ -117,22 +117,22 @@ display list, on top of everything else. Widget commands may be used to re-arrange the order of the display list. .PP -Window items are an exception to the above rules. The underlying +Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas widget commands; you must use -the \fBraise\fR and \fBlower\fR Tk commands instead. +the Tk \fBraise\fR command and \fBlower\fR command instead. .SH "ITEM IDS AND TAGS" .PP Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number, which is assigned to -that item when it is created. The id of an item never changes +that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget. .PP Each item may also have any number of \fItags\fR associated -with it. A tag is just a string of characters, and it may +with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, .QW x123 @@ -141,11 +141,11 @@ is OK but 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 +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 +in the canvas; it may be used to invoke operations on all the items in the canvas. .PP The tag \fBcurrent\fR is managed automatically by Tk; @@ -172,7 +172,7 @@ tags by using operators: .QW \fB||\fR , .QW \fB^\fR , .QW \fB!\fR , -and parenthesized subexpressions. For example: +and parenthesized subexpressions. For example: .CS .c find withtag {(a&&!b)||(!a&&b)} .CE @@ -187,7 +187,7 @@ or 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 +time; if \fItagOrId\fR is specified in a way that names multiple items, then the normal behavior is for the command to use the first (lowest) of these items in the display list that is suitable for the command. @@ -202,9 +202,9 @@ which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is \fBm\fR then the distance is in millimeters on -the screen; if it is \fBc\fR then the distance is in centimeters; +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 +Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right. Coordinates can be specified either as an even number of parameters, or as a single list parameter containing an even number of x and y @@ -215,7 +215,7 @@ Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the -\fBxview\fR and \fByview\fR widget commands; this is typically used +\fBxview\fR and \fByview\fR widget commands; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. @@ -227,7 +227,7 @@ Note that the default origin of the canvas's visible area is coincident with the origin for the whole window as that makes bindings using the mouse position easier to work with; you only need to use the \fBcanvasx\fR and \fBcanvasy\fR widget commands if you adjust the -origin of the visible area. However, this also means that any focus +origin of the visible area. However, this also means that any focus ring (as controlled by the \fB\-highlightthickness\fR option) and window border (as controlled by the \fB\-borderwidth\fR option) must be taken into account before you get to the visible area of the @@ -243,17 +243,18 @@ a range of characters or coordinates, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices. -Text items support the following forms for an index; if you +Text items support the following forms for an index; if you define new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it is possible to refer to the character just after -the last one in the text item; this is necessary for such +the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. .TP 10 \fInumber\fR +. A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and @@ -268,23 +269,28 @@ the length until the result is between zero and the length, inclusive. .TP 10 \fBend\fR +. Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item). .TP 10 \fBinsert\fR +. Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. .TP 10 \fBsel.first\fR +. Refers to the first selected character in the item. If the selection is not in this item then this form is illegal. .TP 10 \fBsel.last\fR +. Refers to the last selected character in the item. If the selection is not in this item then this form is illegal. .TP 10 \fB@\fIx,y\fR +. Refers to the character or coordinate at the point given by \fIx\fR and \fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate system of the canvas. @@ -303,15 +309,15 @@ color. The other segments are drawn transparent. .PP The second possible syntax is a character list containing only 5 possible characters -.QW "\fB.,\-_ \fR" . +.QW "\fB.,-_ \fR" . The space can be used to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples: .CS \-dash . \(-> \-dash {2 4} -\-dash \- \(-> \-dash {6 4} -\-dash \-. \(-> \-dash {6 4 2 4} -\-dash \-.. \(-> \-dash {6 4 2 4 2 4} +\-dash - \(-> \-dash {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 @@ -322,20 +328,20 @@ list will be multiplied by the line width before display. This assures that .QW . will always be displayed as a dot and -.QW \- +.QW - always as a dash regardless of the line width. .PP On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only the first 4 of the above examples are -available. The last 2 examples will be displayed identically to the first +available. The last 2 examples will be displayed identically to the first one. .SH "WIDGET COMMAND" .PP The \fBcanvas\fR command creates a new Tcl command whose -name is \fIpathName\fR. This +name is \fIpathName\fR. This command may be used to invoke various -operations on the widget. It has the following general form: +operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg arg ...\fR? .CE @@ -344,6 +350,7 @@ determine the exact behavior of the command. The following widget commands are possible for canvas widgets: .TP \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR? +. For each item that meets the constraints specified by \fIsearchSpec\fR and the \fIarg\fRs, add \fItag\fR to the list of tags associated with the item if it @@ -357,21 +364,25 @@ forms: .RS .TP \fBabove \fItagOrId\fR +. Selects the item just after (above) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the last (topmost) of these items in the display list is used. .TP \fBall\fR +. Selects all the items in the canvas. .TP \fBbelow \fItagOrId\fR +. Selects the item just before (below) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the first (lowest) of these items in the display list is used. .TP \fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR? +. Selects the item closest to the point given by \fIx\fR and \fIy\fR. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the @@ -387,16 +398,18 @@ If \fIstart\fR is specified, it names an item using a tag or id the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below \fIstart\fR in -the display list; if no such item exists, then the selection +the display list; if no such item exists, then the selection behaves as if the \fIstart\fR argument had not been specified. .TP \fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +. Selects all the items completely enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP \fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +. Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. @@ -404,10 +417,12 @@ and \fIy2\fR. no greater than \fIy2\fR. .TP \fBwithtag \fItagOrId\fR +. Selects all the items given by \fItagOrId\fR. .RE .TP \fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? +. Returns a list with four elements giving an approximate bounding box for all the items named by the \fItagOrId\fR arguments. The list has the form @@ -424,6 +439,7 @@ to display) then an empty string is returned. .TP \fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? +. This command associates \fIcommand\fR with all the items given by \fItagOrId\fR such that whenever the event sequence given by \fIsequence\fR occurs for one of the items the command will @@ -451,13 +467,13 @@ The only events for which bindings may be specified are those related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. The handling of events in canvases uses the current item defined in -\fBITEM IDS AND TAGS\fR above. \fBEnter\fR and \fBLeave\fR events +\fBITEM IDS AND TAGS\fR above. \fBEnter\fR and \fBLeave\fR events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than \fBEnter\fR and \fBLeave\fR -events for windows. Mouse-related events are directed to the current -item, if any. Keyboard-related events are directed to the focus item, if -any (see the \fBfocus\fR widget command below for more on this). If a +events for windows. Mouse-related events are directed to the current +item, if any. Keyboard-related events are directed to the focus item, if +any (see the \fBfocus\fR widget command below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. @@ -484,33 +500,37 @@ for the window as a whole. .RE .TP \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? +. Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns the canvas x-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .TP \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? +. Given a window y-coordinate in the canvas \fIscreeny\fR this command returns the canvas y-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .TP \fIpathName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. .TP \fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified +information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If +sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in +modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. @@ -518,6 +538,7 @@ command. \fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? .TP \fIpathName\fR \fBcoords \fItagOrId \fR?\fIcoordList\fR? +. Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list whose elements are the coordinates of the item named by @@ -530,9 +551,10 @@ the first one in the display list is used. \fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? .TP \fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR? +. Create a new item in \fIpathName\fR of type \fItype\fR. -The exact format of the arguments after \fBtype\fR depends -on \fBtype\fR, but usually they consist of the coordinates for +The exact format of the arguments after \fItype\fR depends +on \fItype\fR, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more @@ -540,21 +562,24 @@ on the syntax of this command. This command returns the id for the new item. .TP \fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? +. For each item given by \fItagOrId\fR, delete the characters, or coordinates, in the range given by \fIfirst\fR and \fIlast\fR, inclusive. If some of the items given by \fItagOrId\fR do not support -indexing operations then they ignore dchars. +indexing operations then they ignore this operation. Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, -line and polygon items interpret them indices to a coordinate (an x,y pair). +line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in \fBINDICES\fR above. If \fIlast\fR is omitted, it defaults to \fIfirst\fR. This command returns an empty string. .TP \fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? +. Delete each of the items given by each \fItagOrId\fR, and return an empty string. .TP \fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? +. For each of the items given by \fItagOrId\fR, delete the tag given by \fItagToDelete\fR from the list of those associated with the item. @@ -564,6 +589,7 @@ If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. This command returns an empty string. .TP \fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR? +. This command returns a list consisting of all the items that meet the constraints specified by \fIsearchCommand\fR and \fIarg\fR's. @@ -572,6 +598,7 @@ accepted by the \fBaddtag\fR command. The items are returned in stacking order, with the lowest item first. .TP \fIpathName \fBfocus \fR?\fItagOrId\fR? +. Set the keyboard focus for the canvas widget to the item given by \fItagOrId\fR. If \fItagOrId\fR refers to several items, then the focus is set @@ -600,6 +627,7 @@ the canvas (if it was not there already). .RE .TP \fIpathName \fBgettags\fR \fItagOrId\fR +. Return a list whose elements are the tags associated with the item given by \fItagOrId\fR. If \fItagOrId\fR refers to more than one item, then the tags @@ -608,24 +636,35 @@ If \fItagOrId\fR does not refer to any items, or if the item contains no tags, then an empty string is returned. .TP \fIpathName \fBicursor \fItagOrId index\fR +. Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR to just before the character whose position is given by \fIindex\fR. If some or all of the items given by \fItagOrId\fR do not support an insertion cursor then this command has no effect on them. See \fBINDICES\fR above for a description of the legal forms for \fIindex\fR. -Note: the insertion cursor is only displayed in an item if -that item currently has the keyboard focus (see the widget -command \fBfocus\fR, below), but the cursor position may +Note: the insertion cursor is only displayed in an item if +that item currently has the keyboard focus (see the \fBfocus\fR widget +command, above), but the cursor position may be set even when the item does not have the focus. This command returns an empty string. .TP +\fIpathName \fBimove \fItagOrId index x y\fR +.VS 8.6 +This command causes the \fIindex\fR'th coordinate of each of the items +indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). +Each item interprets \fIindex\fR independently according to the rules +described in \fBINDICES\fR above. Out of the standard set of items, only line +and polygon items may have their coordinates relocated this way. +.VE 8.6 +.TP \fIpathName \fBindex \fItagOrId index\fR +. This command returns a decimal string giving the numerical index within \fItagOrId\fR corresponding to \fIindex\fR. \fIIndex\fR gives a textual description of the desired position as described in \fBINDICES\fR above. -Text items interpret \fIindex\fR as an index to a character, +Text items interpret \fIindex\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. @@ -634,10 +673,11 @@ is processed in the first of these items that supports indexing operations (in display list order). .TP \fIpathName \fBinsert \fItagOrId beforeThis string\fR +. For each of the items given by \fItagOrId\fR, if the item supports text or coordinate, insertion then \fIstring\fR is inserted into the item's text just before the character, or coordinate, whose index is \fIbeforeThis\fR. -Text items interpret \fIbeforeThis\fR as an index to a character, +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. @@ -646,6 +686,7 @@ for \fIbeforeThis\fR. This command returns an empty string. .TP \fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR +. Returns the current value of the configuration option for the item given by \fItagOrId\fR whose name is \fIoption\fR. This command is similar to the \fBcget\fR widget command except that @@ -656,6 +697,7 @@ If \fItagOrId\fR is a tag that refers to more than one item, the first (lowest) such item is used. .TP \fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +. This command is similar to the \fBconfigure\fR widget command except that it modifies item-specific options for the items given by \fItagOrId\fR instead of modifying options for the overall @@ -663,13 +705,13 @@ canvas widget. If no \fIoption\fR is specified, returns a list describing all of the available options for the first item given by \fItagOrId\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified +information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If +sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in -each of the items given by \fItagOrId\fR; in +each of the items given by \fItagOrId\fR; in this case the command returns an empty string. The \fIoption\fRs and \fIvalue\fRs are the same as those permissible in the \fBcreate\fR widget command when the item(s) were created; @@ -677,30 +719,45 @@ see the sections describing individual item types below for details on the legal options. .TP \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? +. Move all of the items given by \fItagOrId\fR to a new position in the display list just before the item given by \fIbelowThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. -\fIBelowThis\fR is a tag or id; if it refers to more than one +\fIBelowThis\fR is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. -Note: this command has no effect on window items. Window items always +Note: this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR and \fBlower\fR commands, not the -\fBraise\fR and \fBlower\fR widget commands for canvases. +determined by the \fBraise\fR command and \fBlower\fR command, not the +\fBraise\fR widget command and \fBlower\fR widget command for canvases. This command returns an empty string. .TP \fIpathName \fBmove \fItagOrId xAmount yAmount\fR +. Move each of the items given by \fItagOrId\fR in the canvas coordinate space by adding \fIxAmount\fR to the x-coordinate of each point associated with the item and \fIyAmount\fR to the y-coordinate of each point associated with the item. This command returns an empty string. .TP +\fIpathName \fBmoveto \fItagOrId xPos yPos\fR +.VS 8.6 +Move the items given by \fItagOrId\fR in the canvas coordinate +space so that the first coordinate pair of the bottommost item with +tag \fItagOrId\fR is located at +position (\fIxPos\fR,\fIyPos\fR). \fIxPos\fR and \fIyPos\fR may be +the empty string, in which case the corresponding coordinate +will be unchanged. All items matching +\fItagOrId\fR remain in the same positions relative to each other. +This command returns an empty string. +.VE 8.6 +.TP \fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? +. Generate a Postscript representation for part or all of the canvas. If the \fB\-file\fR option is specified then the Postscript is written -to a file and an empty string is returned; otherwise the Postscript +to a file and an empty string is returned; otherwise the Postscript is returned as the result of the command. If the interpreter that owns the canvas is marked as safe, the operation will fail because safe interpreters are not allowed to write files. @@ -711,18 +768,26 @@ of the operation. The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions. Note: by default Postscript is only generated for information that -appears in the canvas's window on the screen. If the canvas is +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 +so nothing will appear in the Postscript. To get around this problem either invoke the \fBupdate\fR command to wait for the canvas window to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR options to specify the area of the canvas to print. The \fIoption\fR\-\fIvalue\fR argument pairs provide additional -information to control the generation of Postscript. The following +information to control the generation of Postscript. The following options are supported: .RS .TP +\fB\-channel \fIchannelName\fR +. +Specifies the name of the channel to which to write the Postscript. +If this option and the \fB\-file\fR option are +not specified then the Postscript is returned as the +result of the command. +.TP \fB\-colormap \fIvarName\fR +. \fIVarName\fR must be the name of an array variable that specifies a color mapping to use in the Postscript. Each element of \fIvarName\fR must consist of Postscript @@ -738,17 +803,21 @@ in \fIvarName\fR for a given color, then Tk uses the red, green, and blue intensities from the X color. .TP \fB\-colormode \fImode\fR -Specifies how to output color information. \fIMode\fR must be either +. +Specifies how to output color information. \fIMode\fR must be either \fBcolor\fR (for full color output), \fBgray\fR (convert all colors to their gray-scale equivalents) or \fBmono\fR (convert all colors to black or white). .TP \fB\-file \fIfileName\fR +. Specifies the name of the file in which to write the Postscript. -If this option is not specified then the Postscript is returned as the -result of the command instead of being written to a file. +If this option and the \fB\-channel\fR option are +not specified then the Postscript is returned as the +result of the command. .TP \fB\-fontmap \fIvarName\fR +. \fIVarName\fR must be the name of an array variable that specifies a font mapping to use in the Postscript. Each element of \fIvarName\fR must consist of a Tcl list with @@ -763,14 +832,16 @@ Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but -\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to +\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to parse the font name). .TP \fB\-height \fIsize\fR +. Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. .TP \fB\-pageanchor \fIanchor\fR +. Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the \fB\-pagex\fR and \fB\-pagey\fR options). @@ -779,6 +850,7 @@ area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to \fBcenter\fR. .TP \fB\-pageheight \fIsize\fR +. Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR high on the Postscript page. \fISize\fR consists of a floating-point number followed by @@ -790,15 +862,17 @@ the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .TP \fB\-pagewidth \fIsize\fR +. Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR wide on the Postscript page. \fISize\fR has the same form as for \fB\-pageheight\fR. Defaults to the width of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then -the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling +the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .TP \fB\-pagex \fIposition\fR +. \fIPosition\fR gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options @@ -806,6 +880,7 @@ to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .TP \fB\-pagey \fIposition\fR +. \fIPosition\fR gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options @@ -813,26 +888,30 @@ to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .TP \fB\-rotate \fIboolean\fR +. \fIBoolean\fR specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page -.PQ portrait orientation ; +.PQ portrait " orientation" ; in rotated output the x-axis runs along the long dimension of the page -.PQ landscape orientation . +.PQ landscape " orientation" . Defaults to non-rotated. .TP \fB\-width \fIsize\fR +. Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. .TP \fB\-x \fIposition\fR +. Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. .TP \fB\-y \fIposition\fR +. Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. @@ -840,22 +919,39 @@ Defaults to the coordinate of the top edge of the window. .RE .TP \fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? +. Move all of the items given by \fItagOrId\fR to a new position in the display list just after the item given by \fIaboveThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. -\fIAboveThis\fR is a tag or id; if it refers to more than one +\fIAboveThis\fR is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. -Note: this command has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR and \fBlower\fR commands, not the -\fBraise\fR and \fBlower\fR widget commands for canvases. This command returns an empty string. +.RS +.PP +Note: this command has no effect on window items. Window items always +obscure other item types, and the stacking order of window items is +determined by the \fBraise\fR command and \fBlower\fR command, not the +\fBraise\fR widget command and \fBlower\fR widget command for canvases. +.RE +.TP +\fIpathName \fBrchars \fItagOrId first last string\fR +.VS 8.6 +This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR +for each of the items indicated by \fItagOrId\fR to be replaced by +\fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently +according to the rules described in \fBINDICES\fR above. Out of the standard +set of items, text items support this operation by altering their text as +directed, and line and polygon items support this operation by altering their +coordinate list (in which case \fIstring\fR should be a list of coordinates to +use as a replacement). The other items ignore this operation. +.VE 8.6 .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR -Rescale all of the items given by \fItagOrId\fR in canvas coordinate -space. +. +Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas +coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling operation and \fIxScale\fR and \fIyScale\fR identify the scale factors for x- and y-coordinates, respectively (a scale factor of @@ -866,20 +962,29 @@ of \fIxScale\fR. Similarly, each y-coordinate is adjusted to change the distance from \fIyOrigin\fR by a factor of \fIyScale\fR. This command returns an empty string. +.RS +.PP +Note that some items have only a single pair of coordinates (e.g., text, +images and windows) and so scaling of them by this command can only move them +around. +.RE .TP \fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on canvases. It has +. +This command is used to implement scanning on canvases. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR -Records \fIx\fR and \fIy\fR and the canvas's current view; used +. +Records \fIx\fR and \fIy\fR and the canvas's current view; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget and \fIx\fR and \fIy\fR are the coordinates of the -mouse. It returns an empty string. +mouse. It returns an empty string. .TP -\fIpathName \fBscan dragto \fIx y ?gain?\fR. +\fIpathName \fBscan dragto \fIx y ?gain?\fR +. This command computes the difference between its \fIx\fR and \fIy\fR arguments (which are typically mouse coordinates) and the \fIx\fR and \fIy\fR arguments to the last \fBscan mark\fR command for the widget. @@ -887,16 +992,17 @@ It then adjusts the view by \fIgain\fR times the difference in coordinates, where \fIgain\fR defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of -dragging the canvas at high speed through its window. The return +dragging the canvas at high speed through its window. The return value is an empty string. .RE .TP \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? +. Manipulates the selection in one of several ways, depending on \fIoption\fR. The command may take any of the forms described below. In all of the descriptions below, \fItagOrId\fR must refer to -an item that supports indexing and selection; if it refers to +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 @@ -904,6 +1010,7 @@ within \fItagOrId\fR, as described in \fBINDICES\fR above. .RS .TP \fIpathName \fBselect adjust \fItagOrId index\fR +. Locate the end of the selection in \fItagOrId\fR nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including @@ -916,27 +1023,31 @@ command. Returns an empty string. .TP \fIpathName \fBselect clear\fR +. Clear the selection if it is in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselect from \fItagOrId index\fR +. Set the selection anchor point for the widget to be just before the character given by \fIindex\fR in the item given by \fItagOrId\fR. -This command does not change the selection; it just sets +This command does not change the selection; it just sets the fixed end of the selection for future \fBselect to\fR commands. Returns an empty string. .TP \fIpathName \fBselect item\fR +. Returns the id of the selected item, if the selection is in an item in this canvas. If the selection is not in this canvas then an empty string is returned. .TP \fIpathName \fBselect to \fItagOrId index\fR +. Set the selection to consist of those characters of \fItagOrId\fR between the selection anchor point and \fIindex\fR. @@ -952,6 +1063,7 @@ Returns an empty string. .RE .TP \fIpathName \fBtype\fI tagOrId\fR +. Returns the type of the item given by \fItagOrId\fR, such as \fBrectangle\fR or \fBtext\fR. If \fItagOrId\fR refers to more than one item, then the type @@ -959,15 +1071,17 @@ of the first item in the display list is returned. If \fItagOrId\fR does not refer to any items at all then an empty string is returned. .TP -\fIpathName \fBxview \fR?\fIargs\fR? +\fIpathName \fBxview \fR?\fIargs\fR? +. This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR +. Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe +Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the canvas's area (as defined by the \fB\-scrollregion\fR option) @@ -977,11 +1091,13 @@ These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview moveto\fI fraction\fR +. Adjusts the view in the window so that \fIfraction\fR of the total width of the canvas is off-screen to the left. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. @@ -993,19 +1109,21 @@ or in units of one-tenth the window's width otherwise. If \fIwhat is \fBpages\fR then the view adjusts in units of nine-tenths the window's width. If \fInumber\fR is negative then information farther to the left -becomes visible; if it is positive then information farther to the right +becomes visible; if it is positive then information farther to the right becomes visible. .RE .TP \fIpathName \fByview \fI?args\fR? +. This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR +. Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe +Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the \fB\-scrollregion\fR @@ -1014,11 +1132,13 @@ These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP \fIpathName \fByview moveto\fI fraction\fR +. Adjusts the view in the window so that \fIfraction\fR of the canvas's area is off-screen to the top. \fIFraction\fR is a fraction between 0 and 1. .TP \fIpathName \fByview scroll \fInumber what\fR +. This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. @@ -1029,15 +1149,15 @@ or in units of one-tenth the window's height otherwise. If \fIwhat\fR is \fBpages\fR then the view adjusts in units of nine-tenths the window's height. If \fInumber\fR is negative then higher information becomes -visible; if it is positive then lower information +visible; if it is positive then lower information becomes visible. .RE .SH "OVERVIEW OF ITEM TYPES" .PP The sections below describe the various types of items supported -by canvas widgets. Each item type is characterized by two things: +by canvas widgets. Each item type is characterized by two things: first, the form of the \fBcreate\fR command used to create -instances of the type; and second, a set of configuration options +instances of the type; and second, a set of configuration options for items of that type, which may be used in the \fBcreate\fR and \fBitemconfigure\fR widget commands. Most items do not support indexing or selection or the commands @@ -1049,15 +1169,25 @@ For lines and polygons the indexing facility is used to manipulate the coordinates of the item. .SS "COMMON ITEM OPTIONS" .PP -Many items share a common set of options. These options are +Many items share a common set of options. These options are explained here, and then referred to be each widget type for brevity. -.PP +.TP +\fB\-anchor \fIanchorPos\fR +. +\fIAnchorPos\fR tells how to position the item relative to the +positioning point for the item; it may have any of the forms +accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR +is \fBcenter\fR then the item is centered on the point; if +\fIanchorPos\fR is \fBn\fR then the item will be drawn so that +its top center point is at the positioning point. +This option defaults to \fBcenter\fR. .TP \fB\-dash \fIpattern\fR .TP \fB\-activedash \fIpattern\fR .TP \fB\-disableddash \fIpattern\fR +. This option specifies dash patterns for the normal, active state, and disabled state of an item. \fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR. @@ -1065,9 +1195,10 @@ If the dash options are omitted then the default is a solid outline. See \fBDASH PATTERNS\fR for more information. .TP \fB\-dashoffset \fIoffset\fR +. The starting \fIoffset\fR in pixels into the pattern provided by the -\fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no -\fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described +\fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no +\fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described in the \fBCOORDINATES\fR section above. .TP \fB\-fill \fIcolor\fR @@ -1075,6 +1206,7 @@ in the \fBCOORDINATES\fR section above. \fB\-activefill \fIcolor\fR .TP \fB\-disabledfill \fIcolor\fR +. Specifies the color to be used to fill item's area. in its normal, active, and disabled states, \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. @@ -1088,29 +1220,33 @@ For the text item, it specifies the foreground color of the text. \fB\-activeoutline \fIcolor\fR .TP \fB\-disabledoutline \fIcolor\fR +. This option specifies the color that should be used to draw the outline of the item in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -This option defaults to \fBblack\fR. If \fIcolor\fR is specified +This option defaults to \fBblack\fR. If \fIcolor\fR is specified as an empty string then no outline is drawn for the item. .TP \fB\-offset \fIoffset\fR -Specifies the offset of stipples. The offset value can be of the form -\fBx,y\fR or \fBside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, +. +Specifies the offset of stipples. The offset value can be of the form +\fBx,y\fR or \fIside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting \fB#\fR in front of the coordinate pair indicates using the toplevel origin instead. For canvas objects, the \fB\-offset\fR option is -used for stippling as well. For the line and polygon canvas items you can +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. +of the coordinate points of the line/polygon. Note that stipple offsets are +\fIonly supported on X11\fR; they are silently ignored on other platforms. .TP \fB\-outlinestipple \fIbitmap\fR .TP \fB\-activeoutlinestipple \fIbitmap\fR .TP \fB\-disabledoutlinestipple \fIbitmap\fR +. This option specifies stipple patterns that should be used to draw the outline of the item in its normal, active and disabled states. Indicates that the outline for the item should be drawn with a stipple pattern; @@ -1125,20 +1261,16 @@ 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?! +Specifies the offset of the stipple pattern used for outlines, in the same way +that the \fB\-outline\fR option controls fill stipples. (See the +\fB\-outline\fR option for a description of the syntax of \fIoffset\fR.) .TP \fB\-stipple \fIbitmap\fR .TP \fB\-activestipple \fIbitmap\fR .TP \fB\-disabledstipple \fIbitmap\fR +. This option specifies stipple patterns that should be used to fill the item in its normal, active and disabled states. \fIbitmap\fR specifies the stipple pattern to use, in any of the @@ -1152,29 +1284,33 @@ For the text item, it affects the actual text. use X11 as their drawing API.\fR .TP \fB\-state \fIstate\fR +. This allows an item to override the canvas widget's global \fIstate\fR -option. It takes the same values: +option. It takes the same values: \fInormal\fR, \fIdisabled\fR or \fIhidden\fR. .TP \fB\-tags \fItagList\fR +. Specifies a set of tags to apply to the item. \fITagList\fR consists of a list of tag names, which replace any -existing tags for the item. \fITagList\fR may be an empty list. +existing tags for the item. \fITagList\fR may be an empty list. .TP \fB\-width \fIoutlineWidth\fR .TP \fB\-activewidth \fIoutlineWidth\fR .TP \fB\-disabledwidth \fIoutlineWidth\fR +. Specifies the width of the outline to be drawn around the item's region, in its normal, active and disabled states. \fIoutlineWidth\fR may be in any of the forms described in the \fBCOORDINATES\fR section above. If the \fB\-outline\fR option has been specified as an empty string then -this option has no effect. This option defaults to 1.0. +this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region. -.SH "ARC ITEMS" +.SH "STANDARD ITEM TYPES" +.SS "ARC ITEMS" .PP Items of type \fBarc\fR appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified @@ -1182,46 +1318,36 @@ by the \fB\-start\fR and \fB\-extent\fR options) and displayed in one of several ways (specified by the \fB\-style\fR option). Arcs are created with widget commands of the following form: .CS -\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? +\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval that defines the arc. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An arc item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. .PP The following standard options are supported by arcs: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlineoffset -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE +.DS +.ta 3i +\fB\-dash\fR \fB\-activedash\fR +\fB\-disableddash\fR \fB\-dashoffset\fR +\fB\-fill\fR \fB\-activefill\fR +\fB\-disabledfill\fR \fB\-offset\fR +\fB\-outline\fR \fB\-activeoutline\fR +\fB\-disabledoutline\fR \fB\-outlineoffset\fR +\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR +\fB\-disabledoutlinestipple\fR \fB\-stipple\fR +\fB\-activestipple\fR \fB\-disabledstipple\fR +\fB\-state\fR \fB\-tags\fR +\fB\-width\fR \fB\-activewidth\fR +\fB\-disabledwidth\fR +.DE The following extra options are supported for arcs: .TP \fB\-extent \fIdegrees\fR @@ -1236,10 +1362,10 @@ modulo 360 is used as the extent. Specifies the beginning of the angular range occupied by the arc. \fIDegrees\fR is given in units of degrees measured counter-clockwise -from the 3-o'clock position; it may be either positive or negative. +from the 3-o'clock position; it may be either positive or negative. .TP \fB\-style \fItype\fR -Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR +Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. @@ -1249,42 +1375,34 @@ connecting the two end points of the perimeter section. If \fItype\fR is \fBarc\fR then the arc's region consists of a section of the perimeter alone. In this last case the \fB\-fill\fR option is ignored. -.SH "BITMAP ITEMS" +.SS "BITMAP ITEMS" .PP Items of type \fBbitmap\fR appear on the display as images with two colors, foreground and background. Bitmaps are created with widget commands of the following form: .CS -\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value ...\fR? +\fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a -point used to position the bitmap on the display (see the \fB\-anchor\fR -option below for more information on how bitmaps are displayed). +point used to position the bitmap on the display, as controlled by the +\fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A bitmap item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by bitmaps: -.CS -\-state -\-tags -.CE +.DS +.ta 3i +\fB\-anchor\fR \fB\-state\fR +\fB\-tags\fR +.DE The following extra options are supported for bitmaps: .TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the bitmap relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the bitmap is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the bitmap will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP \fB\-background \fIcolor\fR .TP \fB\-activebackground \fIcolor\fR @@ -1295,7 +1413,7 @@ Specifies the color to use for each of the bitmap's valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If this option is not specified, or if it is specified as an empty -string, then nothing is displayed where the bitmap pixels are 0; this +string, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. .TP \fB\-bitmap \fIbitmap\fR @@ -1317,41 +1435,33 @@ Specifies the color to use for each of the bitmap's 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" +.SS "IMAGE ITEMS" .PP Items of type \fBimage\fR are used to display images on a canvas. Images are created with widget commands of the following form: .CS -\fIpathName \fBcreate image \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate image \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate image \fIx y \fR?\fIoption value ...\fR? +\fIpathName \fBcreate image \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the image on the display (see the \fB\-anchor\fR -option below for more information). +point used to position the image on the display, as controlled by the +\fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An image item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by images: -.CS -\-state -\-tags -.CE +.DS +.ta 3i +\fB\-anchor\fR \fB\-state\fR +\fB\-tags\fR +.DE The following extra options are supported for images: .TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the image relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the image is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the image will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP \fB\-image \fIname\fR .TP \fB\-activeimage \fIname\fR @@ -1361,46 +1471,40 @@ Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the \fBimage create\fR command. -.SH "LINE ITEMS" +.SS "LINE ITEMS" .PP Items of type \fBline\fR appear on the display as one or more connected line segments or curves. -Line items support coordinate indexing operations using the canvas -widget commands: \fBdchars, index, insert.\fR +Line items support coordinate indexing operations using the \fBdchars\fR, +\fBindex\fR and \fBinsert\fR widget commands. Lines are created with widget commands of the following form: .CS -\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate line \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value ...\fR? +\fIpathName \fBcreate line \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR give the coordinates for a series of two or more points that describe a series of connected line segments. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A line item is the current item whenever the mouse pointer is over any segment of the line, whether drawn or not and whether or not the line is smoothed. .PP The following standard options are supported by lines: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE +.DS +.ta 3i +\fB\-dash\fR \fB\-activedash\fR +\fB\-disableddash\fR \fB\-dashoffset\fR +\fB\-fill\fR \fB\-activefill\fR +\fB\-disabledfill\fR \fB\-stipple\fR +\fB\-activestipple\fR \fB\-disabledstipple\fR +\fB\-state\fR \fB\-tags\fR +\fB\-width\fR \fB\-activewidth\fR +\fB\-disabledwidth\fR +.DE The following extra options are supported for lines: .TP \fB\-arrow \fIwhere\fR @@ -1438,7 +1542,7 @@ Where arrowheads are drawn the cap style is ignored. \fB\-joinstyle \fIstyle\fR Specifies the ways in which joints are to be drawn at the vertices of the line. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR +\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. If the line only contains two points then this option is @@ -1447,40 +1551,38 @@ irrelevant. \fB\-smooth \fIsmoothMethod\fR \fIsmoothMethod\fR must have one of the forms accepted by \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 +supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean +false value or empty string is given, no smoothing is applied. A boolean truth value assumes \fBtrue\fR smoothing. If the smoothing method is \fBtrue\fR, this indicates that the line should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated within +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 +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 +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 +Specifies the degree of smoothness desired for curves: each spline +will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. -.SH "OVAL ITEMS" +.SS "OVAL ITEMS" .PP Items of type \fBoval\fR appear as circular or oval regions on -the display. Each oval may have an outline, a fill, or -both. Ovals are created with widget commands of the +the display. Each oval may have an outline, a fill, or +both. Ovals are created with widget commands of the following form: .CS -\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate oval \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? +\fIpathName \fBcreate oval \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a @@ -1491,48 +1593,39 @@ If the region is square then the resulting oval is circular; otherwise it is elongated in shape. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An oval item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. .PP The following standard options are supported by ovals: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlineoffset -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE -.SH "POLYGON ITEMS" +.DS +.ta 3i +\fB\-dash\fR \fB\-activedash\fR +\fB\-disableddash\fR \fB\-dashoffset\fR +\fB\-fill\fR \fB\-activefill\fR +\fB\-disabledfill\fR \fB\-offset\fR +\fB\-outline\fR \fB\-activeoutline\fR +\fB\-disabledoutline\fR \fB\-outlineoffset\fR +\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR +\fB\-disabledoutlinestipple\fR \fB\-stipple\fR +\fB\-activestipple\fR \fB\-disabledstipple\fR +\fB\-state\fR \fB\-tags\fR +\fB\-width\fR \fB\-activewidth\fR +\fB\-disabledwidth\fR +.DE +There are no oval-specific options. +.SS "POLYGON ITEMS" .PP Items of type \fBpolygon\fR appear as polygonal or curved filled regions on the display. -Polygon items support coordinate indexing operations using the canvas -widget commands: \fBdchars, index, insert.\fR +Polygon items support coordinate indexing operations using the \fBdchars\fR, +\fBindex\fR and \fBinsert\fR widget commands. Polygons are created with widget commands of the following form: .CS -\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR? +\fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for three or more points that define a polygon. @@ -1541,73 +1634,62 @@ close the shape; Tk will automatically close the periphery between the first and last points. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A polygon item is the current item whenever the mouse pointer is over any part of the polygon, whether drawn or not and whether or not the outline is smoothed. .PP The following standard options are supported by polygons: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE +.DS +.ta 3i +\fB\-dash\fR \fB\-activedash\fR +\fB\-disableddash\fR \fB\-dashoffset\fR +\fB\-fill\fR \fB\-activefill\fR +\fB\-disabledfill\fR \fB\-offset\fR +\fB\-outline\fR \fB\-activeoutline\fR +\fB\-disabledoutline\fR \fB\-outlineoffset\fR +\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR +\fB\-disabledoutlinestipple\fR \fB\-stipple\fR +\fB\-activestipple\fR \fB\-disabledstipple\fR +\fB\-state\fR \fB\-tags\fR +\fB\-width\fR \fB\-activewidth\fR +\fB\-disabledwidth\fR +.DE The following extra options are supported for polygons: .TP \fB\-joinstyle \fIstyle\fR Specifies the ways in which joints are to be drawn at the vertices of the outline. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR +\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. .TP \fB\-smooth \fIboolean\fR \fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR -.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 +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 +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 +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 +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 +Specifies the degree of smoothness desired for curves: each spline +will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .PP Polygon items are different from other items such as rectangles, ovals @@ -1617,18 +1699,18 @@ a polygon (e.g. for purposes of the \fBfind closest\fR and \fBfind overlapping\fR widget commands) even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item -is filled or if it has neither a fill nor an outline. If you would +is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead. -.SH "RECTANGLE ITEMS" +.SS "RECTANGLE ITEMS" .PP Items of type \fBrectangle\fR appear as rectangular regions on -the display. Each rectangle may have an outline, a fill, or -both. Rectangles are created with widget commands of the +the display. Each rectangle may have an outline, a fill, or +both. Rectangles are created with widget commands of the following form: .CS -\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? +\fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR (which must have four elements) give @@ -1637,7 +1719,7 @@ the coordinates of two diagonally opposite corners of the rectangle its lower or right edges). After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A rectangle item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that @@ -1645,44 +1727,35 @@ 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 -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlineoffset -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE -.SH "TEXT ITEMS" +.DS +.ta 3i +\fB\-dash\fR \fB\-activedash\fR +\fB\-disableddash\fR \fB\-dashoffset\fR +\fB\-fill\fR \fB\-activefill\fR +\fB\-disabledfill\fR \fB\-offset\fR +\fB\-outline\fR \fB\-activeoutline\fR +\fB\-disabledoutline\fR \fB\-outlineoffset\fR +\fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR +\fB\-disabledoutlinestipple\fR \fB\-stipple\fR +\fB\-activestipple\fR \fB\-disabledstipple\fR +\fB\-state\fR \fB\-tags\fR +\fB\-width\fR \fB\-activewidth\fR +\fB\-disabledwidth\fR +.DE +There are no rectangle-specific options. +.SS "TEXT ITEMS" .PP A text item displays a string of characters on the screen in one or more lines. -Text items support indexing and selection, along with the -following text-related canvas widget commands: \fBdchars\fR, -\fBfocus\fR, \fBicursor\fR, \fBindex\fR, \fBinsert\fR, -\fBselect\fR. +Text items support indexing, editing and selection through the \fBdchars\fR +widget command, the \fBfocus\fR widget command, the \fBicursor\fR widget +command, the \fBindex\fR widget command, the \fBinsert\fR widget command, and +the \fBselect\fR widget command. Text items are created with widget commands of the following form: .CS -\fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate text \fIx y \fR?\fIoption value ...\fR? +\fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a @@ -1690,33 +1763,30 @@ 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 +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A text item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by text items: -.CS -\-fill -\-activefill -\-disabledfill -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -.CE +.DS +.ta 3i +\fB\-anchor\fR \fB\-fill\fR +\fB\-activefill\fR \fB\-disabledfill\fR +\fB\-stipple\fR \fB\-activestipple\fR +\fB\-disabledstipple\fR \fB\-state\fR +\fB\-tags\fR +.DE The following extra options are supported for text items: .TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the text relative to the -positioning point for the text; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the text is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the text will be drawn such that -the top center point of the rectangular region occupied by the -text will be at the positioning point. -This option defaults to \fBcenter\fR. +\fB\-angle \fIrotationDegrees\fR +.VS 8.6 +\fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise +about the positioning point for the text; it may have any floating-point value +from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the +text will be drawn vertically from bottom to top. +This option defaults to \fB0.0\fR. +.VE 8.6 .TP \fB\-font \fIfontName\fR Specifies the font to use for the text item. @@ -1738,7 +1808,6 @@ 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 @@ -1746,7 +1815,6 @@ 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 @@ -1755,25 +1823,25 @@ If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than \fIlineLength\fR is broken just before a space -character to make the line shorter than \fIlineLength\fR; the +character to make the line shorter than \fIlineLength\fR; the space character is treated as if it were a newline character. -.SH "WINDOW ITEMS" +.SS "WINDOW ITEMS" .PP Items of type \fBwindow\fR cause a particular window to be displayed at a given position on the canvas. Window items are created with widget commands of the following form: .CS -\fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value option value ...\fR? +\fIpathName \fBcreate window \fIx y \fR?\fIoption value ...\fR? +\fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a -point used to position the window on the display (see the \fB\-anchor\fR -option below for more information on how bitmaps are displayed). +point used to position the window on the display, as controlled by the +\fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be +for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. Theoretically, a window item becomes the current item when the mouse pointer is over any part of its bounding box, but in practice this @@ -1781,22 +1849,13 @@ 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 -\-tags -.CE +.DS +.ta 3i +\fB\-anchor\fR \fB\-state\fR +\fB\-tags\fR +.DE 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 -is \fBcenter\fR then the window is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the window will be drawn so that -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. @@ -1820,9 +1879,9 @@ The window specified by \fIpathName\fR must either be a child of the canvas widget or a child of some ancestor of the canvas widget. \fIPathName\fR may not refer to a top-level window. .PP -Note: due to restrictions in the ways that windows are managed, it is not +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 +of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. Also note that window items, unlike other canvas items, are not clipped for display by their containing canvas's border, and are instead clipped by the parent widget of @@ -1836,16 +1895,20 @@ See the documentation for \fBTk_CreateItemType\fR. .SH BINDINGS .PP In the current implementation, new canvases are not given any -default behavior: you will have to execute explicit Tcl commands +default behavior: you will have to execute explicit Tcl commands to give the canvas its behavior. .SH CREDITS .PP Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's -\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme -environment and preceded canvases by a year or two. Its simple +\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme +environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases. .SH "SEE ALSO" bind(n), font(n), image(n), scrollbar(n) .SH KEYWORDS canvas, widget +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/checkbutton.n b/doc/checkbutton.n index 34d230b..2e6f840 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -checkbutton \- Create and manipulate checkbutton widgets +checkbutton \- Create and manipulate 'checkbutton' boolean selection widgets .SH SYNOPSIS \fBcheckbutton\fI pathName \fR?\fIoptions\fR? .SO @@ -38,7 +38,7 @@ 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 +proper boolean value. If false, the \fB\-relief\fR option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. .OP \-offrelief offRelief OffRelief @@ -79,34 +79,30 @@ whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. .OP \-selectimage selectImage SelectImage -Specifies an image to display (in place of the \fBimage\fR option) +Specifies an image to display (in place of the \fB\-image\fR option) when the checkbutton is selected. -This option is ignored unless the \fBimage\fR option has been +This option is ignored unless the \fB\-image\fR option has been specified. .OP \-state state State Specifies one of three states for the checkbutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the checkbutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is +\fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the checkbutton. In active state -the checkbutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the checkbutton +the checkbutton is displayed using the \fB\-activeforeground\fR and +\fB\-activebackground\fR options. Disabled state means that the checkbutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the checkbutton is displayed. +In this state the \fB\-disabledforeground\fR and +\fB\-background\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) +Specifies an image to display (in place of the \fB\-image\fR option) when the checkbutton is in tri-state mode. -This option is ignored unless the \fBimage\fR option has been +This option is ignored unless the \fB\-image\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 +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 @@ -138,13 +134,13 @@ that displays a textual string, bitmap or image and a square called an \fIindicator\fR. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and +or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the -\fBunderline\fR option. +\fB\-underline\fR option. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different -ways, according to the \fBstate\fR option; +ways, according to the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the @@ -155,17 +151,16 @@ If a checkbutton is selected then the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). -.VS 8.5 The indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). -The indicator is drawn without a check mark inside. In the special case -where the variable (if specified) has a value that matches the tristatevalue, -the indicator is drawn with a tri-state appearance and is in the tri-state -mode indicating mixed or multiple values. (This is used when the check +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 +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. @@ -190,7 +185,6 @@ changes to and from the button's and .QW tristate values. -.VE 8.5 .SH "WIDGET COMMAND" .PP The \fBcheckbutton\fR command creates a new Tcl command whose @@ -270,7 +264,8 @@ invoked, if there is one). .IP [3] When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus -(+) and equal (=) select the button, and minus (\-) deselects the button. +(\fB+\fR) and equal (\fB=\fR) select the button, and minus (\fB\-\fR) +deselects the button. .PP If the checkbutton's state is \fBdisabled\fR then none of the above actions occur: the checkbutton is completely non-responsive. @@ -278,17 +273,21 @@ actions occur: the checkbutton is completely non-responsive. The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH EXAMPLE +.PP This example shows a group of uncoupled checkbuttons. .PP .CS - labelframe .lbl \-text "Steps:" - \fBcheckbutton\fR .c1 \-text Lights \-variable lights - \fBcheckbutton\fR .c2 \-text Cameras \-variable cameras - \fBcheckbutton\fR .c3 \-text Action! \-variable action - pack .c1 .c2 .c3 \-in .lbl - pack .lbl +labelframe .lbl \-text "Steps:" +\fBcheckbutton\fR .c1 \-text Lights \-variable lights +\fBcheckbutton\fR .c2 \-text Cameras \-variable cameras +\fBcheckbutton\fR .c3 \-text Action! \-variable action +pack .c1 .c2 .c3 \-in .lbl +pack .lbl .CE .SH "SEE ALSO" button(n), options(n), radiobutton(n), ttk::checkbutton(n) .SH KEYWORDS checkbutton, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/chooseColor.n b/doc/chooseColor.n index c71577b..015b17d 100644 --- a/doc/chooseColor.n +++ b/doc/chooseColor.n @@ -13,7 +13,6 @@ tk_chooseColor \- pops up a dialog box for the user to select a color. .SH SYNOPSIS \fBtk_chooseColor \fR?\fIoption value ...\fR? .BE - .SH DESCRIPTION .PP The procedure \fBtk_chooseColor\fR pops up a dialog box for the @@ -38,9 +37,12 @@ name of the color in a form acceptable to \fBTk_GetColor\fR. If the user cancels the operation, both commands will return the empty string. .SH EXAMPLE +.PP .CS button .b \-bg [tk_chooseColor \-initialcolor gray \-title "Choose color"] .CE - .SH KEYWORDS -color selection dialog +color, color selection, dialog +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index da21762..86c593d 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -19,8 +19,11 @@ possible as command line arguments: .TP \fB\-initialdir\fR \fIdirname\fR Specifies that the directories in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, then -the directories in the current working directory are displayed. If the +when the dialog pops up. If this parameter is not specified, +the initial directory defaults to the current working directory +on non-Windows systems and on Windows systems prior to Vista. +On Vista and later systems, the initial directory defaults to the last +user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .TP @@ -38,6 +41,7 @@ turns the file dialog into a sheet attached to the parent window. Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .SH EXAMPLE +.PP .CS set dir [\fBtk_chooseDirectory\fR \e \-initialdir ~ \-title "Choose a directory"] @@ -47,8 +51,10 @@ if {$dir eq ""} { label .l \-text "Selected $dir" } .CE - .SH "SEE ALSO" tk_getOpenFile(n), tk_getSaveFile(n) .SH KEYWORDS directory, selection, dialog, platform-specific +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/clipboard.n b/doc/clipboard.n index 442288d..374cbd1 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.n @@ -14,7 +14,6 @@ clipboard \- Manipulate Tk clipboard .SH SYNOPSIS \fBclipboard \fIoption\fR ?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command provides a Tcl interface to the Tk clipboard, @@ -28,15 +27,9 @@ appends should be completed before returning to the event loop. The first argument to \fBclipboard\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: -.PP -.TP -\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR? -Claims ownership of the clipboard on \fIwindow\fR's display and removes -any previous contents. \fIWindow\fR defaults to -.QW . . -Returns an empty string. .TP \fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR +. Appends \fIdata\fR to the clipboard on \fIwindow\fR's display in the form given by \fItype\fR with the representation given by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's @@ -47,15 +40,15 @@ display. (the desired .QW target for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the +should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR; see the Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to STRING. +\fIType\fR defaults to \fBSTRING\fR. .PP The \fIformat\fR argument specifies the representation that should be used to transmit the selection to the requester (the second column of -Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is -STRING, the selection is transmitted as 8-bit ASCII characters. If -\fIformat\fR is ATOM, then the \fIdata\fR is +Table 2 of the ICCCM), and defaults to \fBSTRING\fR. If \fIformat\fR is +\fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters. If +\fIformat\fR is \fBATOM\fR, then the \fIdata\fR is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other \fIformat\fR, \fIdata\fR is divided @@ -69,8 +62,8 @@ boundaries. All items appended to the clipboard with the same .PP The \fIformat\fR argument is needed only for compatibility with clipboard requesters that do not use Tk. If the Tk toolkit is being -used to retrieve the CLIPBOARD selection then the value is converted back to -a string at the requesting end, so \fIformat\fR is +used to retrieve the \fBCLIPBOARD\fR selection then the value is +converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .PP A \fB\-\|\-\fR argument may be specified to mark the end of options: the @@ -79,21 +72,30 @@ This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE .TP +\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR? +. +Claims ownership of the clipboard on \fIwindow\fR's display and removes +any previous contents. \fIWindow\fR defaults to +.QW . . +Returns an empty string. +.TP \fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR? +. Retrieve data from the clipboard on \fIwindow\fR's display. \fIWindow\fR defaults to .QW . . \fIType\fR specifies the form in which -the data is to be returned and should be an atom name such as STRING -or FILE_NAME. \fIType\fR defaults to STRING. This command is +the data is to be returned and should be an atom name such as \fBSTRING\fR +or \fBFILE_NAME\fR. \fIType\fR defaults to \fBSTRING\fR. This command is equivalent to -.QW "\fBselection get \-selection CLIPBOARD\fR" . +.QW "\fBselection get\fR \fB\-selection CLIPBOARD\fR" . .RS .PP Note that on modern X11 systems, the most useful type to retrieve for transferred strings is not \fBSTRING\fR, but rather \fBUTF8_STRING\fR. .RE .SH EXAMPLES +.PP Get the current contents of the clipboard. .CS if {[catch {\fBclipboard get\fR} contents]} { @@ -146,9 +148,10 @@ bind $c <<Paste>> { } } .CE - .SH "SEE ALSO" interp(n), selection(n) - .SH KEYWORDS clear, format, clipboard, append, selection, type +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/colors.n b/doc/colors.n index 46c35aa..d121248 100644 --- a/doc/colors.n +++ b/doc/colors.n @@ -205,7 +205,7 @@ goldenrod1 255 193 37 goldenrod2 238 180 34 goldenrod3 205 155 29 goldenrod4 139 105 20 -gray 190 190 190 +gray 128 128 128 gray0 0 0 0 gray1 3 3 3 gray2 5 5 5 @@ -307,14 +307,14 @@ gray97 247 247 247 gray98 250 250 250 gray99 252 252 252 gray100 255 255 255 -green 0 255 0 +green 0 128 0 green yellow 173 255 47 green1 0 255 0 green2 0 238 0 green3 0 205 0 green4 0 139 0 GreenYellow 173 255 47 -grey 190 190 190 +grey 128 128 128 grey0 0 0 0 grey1 3 3 3 grey2 5 5 5 @@ -534,7 +534,7 @@ magenta1 255 0 255 magenta2 238 0 238 magenta3 205 0 205 magenta4 139 0 139 -maroon 176 48 96 +maroon 128 0 0 maroon1 255 52 179 maroon2 238 48 167 maroon3 205 41 144 @@ -651,7 +651,7 @@ plum3 205 150 205 plum4 139 102 139 powder blue 176 224 230 PowderBlue 176 224 230 -purple 160 32 240 +purple 128 0 128 purple1 155 48 255 purple2 145 44 238 purple3 125 38 205 diff --git a/doc/console.n b/doc/console.n index bd98961..1313d3a 100644 --- a/doc/console.n +++ b/doc/console.n @@ -25,7 +25,7 @@ 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 +In TkAqua, this command is only available when stdin is \fB/dev/null\fR (as is the case e.g. when the application embedding Tk is started from the Mac OS X Finder). .PP @@ -129,6 +129,7 @@ Most other behaviour is the same as a conventional text widget except for the way that the \fI<<Cut>>\fR event is handled identically to the \fI<<Copy>>\fR event. .SH EXAMPLE +.PP Not all platforms have the \fBconsole\fR command, so debugging code often has the following code fragment in it so output produced by \fBputs\fR can be seen while during development: @@ -139,3 +140,6 @@ catch {\fBconsole show\fR} destroy(n), fconfigure(n), history(n), interp(n), puts(n), text(n), wm(n) .SH KEYWORDS console, interpreter, window, interactive, output channels +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/cursors.n b/doc/cursors.n index b36f537..1662de4 100644 --- a/doc/cursors.n +++ b/doc/cursors.n @@ -135,12 +135,13 @@ On Mac OS X systems, the following cursors are mapped to native cursors: .RS .CS arrow +top_left_arrow +left_ptr cross crosshair +tcross ibeam none -plus -watch xterm .CE And the following additional native cursors are available: @@ -148,24 +149,43 @@ And the following additional native cursors are available: copyarrow aliasarrow contextualmenuarrow +movearrow text cross-hair -closedhand +hand openhand +closedhand +fist pointinghand +resize resizeleft resizeright resizeleftright resizeup resizedown resizeupdown +resizebottomleft +resizetopleft +resizebottomright +resizetopright notallowed poof +wait countinguphand countingdownhand countingupanddownhand spinning +help +bucket +cancel +eyedrop +eyedrop-full +zoom-in +zoom-out .CE .RE .SH KEYWORDS cursor, option +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/destroy.n b/doc/destroy.n index 00da4a7..3d4743a 100644 --- a/doc/destroy.n +++ b/doc/destroy.n @@ -27,6 +27,7 @@ in destroying a window the command aborts without destroying the remaining windows. No error is returned if \fIwindow\fR does not exist. .SH EXAMPLE +.PP Destroy all checkbuttons that are direct children of the given widget: .CS proc killCheckbuttonChildren {parent} { @@ -37,6 +38,8 @@ proc killCheckbuttonChildren {parent} { } } .CE - .SH KEYWORDS application, destroy, window +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/dialog.n b/doc/dialog.n index e154a7f..d2031d3 100644 --- a/doc/dialog.n +++ b/doc/dialog.n @@ -14,10 +14,10 @@ tk_dialog \- Create modal dialog and wait for response .SH SYNOPSIS \fBtk_dialog \fIwindow title text bitmap default string string ...\fR .BE - .SH DESCRIPTION .PP This procedure is part of the Tk script library. +It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR. Its arguments describe a dialog box: .TP \fIwindow\fR @@ -31,7 +31,8 @@ Text to appear in the window manager's title bar for the dialog. Message to appear in the top portion of the dialog box. .TP \fIbitmap\fR -If non-empty, specifies a bitmap to display in the top portion of +If non-empty, specifies a bitmap (in a form suitable for Tk_GetBitmap) +to display in the top portion of the dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the dialog. .TP @@ -59,13 +60,15 @@ While waiting for the user to respond, \fBtk_dialog\fR sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. .SH EXAMPLE +.PP .CS set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \e questhead 0 Yes No "I'm not sure"] .CE - .SH "SEE ALSO" tk_messageBox(n) - .SH KEYWORDS bitmap, dialog, modal +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/entry.n b/doc/entry.n index 8015f1c..ccfcd24 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -11,7 +11,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -entry \- Create and manipulate entry widgets +entry \- Create and manipulate 'entry' one-line text entry widgets .SH SYNOPSIS \fBentry\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -32,9 +32,9 @@ this option is the empty string, the normal background color is used. Specifies the foreground color to use when the entry is disabled. If this option is the empty string, the normal foreground color is used. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fBvalidateCommand\fR returns 0. +Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to {} disables this feature (the default). The best use -of this option is to set it to \fIbell\fR. See \fBValidation\fR +of this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for more information. .OP \-readonlybackground readonlyBackground ReadonlyBackground Specifies the background color to use when the entry is readonly. If @@ -64,15 +64,15 @@ be displayed in a different color, depending on the values of the Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBValidation\fR below for more. +state which mode you wish to use. See \fBVALIDATION\fR below for more. .OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand Specifies a script to eval when you want to validate the input into the entry widget. Setting it to {} disables this feature (the default). This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then it means you reject the new edition -and it will not occur and the \fBinvalidCommand\fR will be evaluated if it +and it will not occur and the \fB\-invalidcommand\fR will be evaluated if it is set. If it returns 1, then the new edition occurs. -See \fBValidation\fR below for more information. +See \fBVALIDATION\fR below for more information. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. @@ -96,7 +96,7 @@ allows that string to be edited using widget commands described below, which are typically bound to keystrokes and mouse actions. When first created, an entry's string is empty. A portion of the entry may be selected as described below. -If an entry is exporting its selection (see the \fBexportSelection\fR +If an entry is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type \fBSTRING\fR. Entries also observe the standard Tk rules for dealing with the @@ -108,31 +108,31 @@ 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 +the standard \fB\-xscrollcommand\fR mechanism for interacting with +scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). They also support scanning, as described below. .SH VALIDATION .PP -Validation works by setting the \fBvalidateCommand\fR -option to a script which will be evaluated according to the \fBvalidate\fR -option as follows: +Validation works by setting the \fB\-validatecommand\fR option to a +script (\fIvalidateCommand\fR) which will be evaluated according to +the \fB\-validate\fR option as follows: .PP .IP \fBnone\fR 10 Default. This means no validation will occur. .IP \fBfocus\fR 10 -\fBvalidateCommand\fR will be called when the entry receives or +\fIvalidateCommand\fR will be called when the entry receives or loses focus. .IP \fBfocusin\fR 10 -\fBvalidateCommand\fR will be called when the entry receives focus. +\fIvalidateCommand\fR will be called when the entry receives focus. .IP \fBfocusout\fR 10 -\fBvalidateCommand\fR will be called when the entry loses focus. +\fIvalidateCommand\fR will be called when the entry loses focus. .IP \fBkey\fR 10 -\fBvalidateCommand\fR will be called when the entry is edited. +\fIvalidateCommand\fR will be called when the entry is edited. .IP \fBall\fR 10 -\fBvalidateCommand\fR will be called for all above conditions. +\fIvalidateCommand\fR will be called for all above conditions. .PP -It is possible to perform percent substitutions on the \fBvalidateCommand\fR -and \fBinvalidCommand\fR, +It is possible to perform percent substitutions on the value of the +\fB\-validatecommand\fR and \fB\-invalidcommand\fR options, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP @@ -157,32 +157,32 @@ The type of validation that triggered the callback .IP \fB%W\fR 5 The name of the entry widget. .PP -In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be +In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR options can be dangerous to mix. Any problems have been overcome so that using the -\fBvalidateCommand\fR will not interfere with the traditional behavior of -the entry widget. Using the \fBtextVariable\fR for read-only purposes will +\fB\-validatecommand\fR will not interfere with the traditional behavior of +the entry widget. Using the \fB\-textvariable\fR for read-only purposes will never cause problems. The danger comes when you try set the -\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not -accept, which causes \fBvalidate\fR to become \fInone\fR (the -\fBinvalidCommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fBvalidateCommand\fR. +\fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not +accept, which causes \fB\-validate\fR to become \fInone\fR (the +\fB\-invalidcommand\fR will not be triggered). The same happens +when an error occurs evaluating the \fB\-validatecommand\fR. .PP -Primarily, an error will occur when the \fBvalidateCommand\fR or -\fBinvalidCommand\fR encounters an error in its script while evaluating or -\fBvalidateCommand\fR does not return a valid Tcl boolean value. The -\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the -entry widget from within either the \fBvalidateCommand\fR or the -\fBinvalidCommand\fR. Such editions will override the one that was being +Primarily, an error will occur when the \fB\-validatecommand\fR or +\fB\-invalidcommand\fR encounters an error in its script while evaluating or +\fB\-validatecommand\fR does not return a valid Tcl boolean value. The +\fB\-validate\fR option will also set itself to \fBnone\fR when you edit the +entry widget from within either the \fB\-validatecommand\fR or the +\fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the entry widget (for example set it to {}) -during validation and still have the \fBvalidate\fR option set, you should +during validation and still have the \fB\-validate\fR option set, you should include the command .CS after idle {%W config \-validate %v} .CE -in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you +in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the entry widget from). It is also recommended to not set an -associated \fBtextVariable\fR during validation, as that can cause the -entry widget to become out of sync with the \fBtextVariable\fR. +associated \fB\-textvariable\fR during validation, as that can cause the +entry widget to become out of sync with the \fB\-textvariable\fR. .SH "WIDGET COMMAND" .PP The \fBentry\fR command creates a new Tcl command whose @@ -369,9 +369,9 @@ Returns an empty string. .RE .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. +This command is used to force an evaluation of the \fB\-validatecommand\fR +independent of the conditions specified by the \fB\-validate\fR option. +This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .TP \fIpathName \fBxview \fIargs\fR @@ -534,3 +534,6 @@ individual widgets or by redefining the class bindings. ttk::entry(n) .SH KEYWORDS entry, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/event.n b/doc/event.n index 85033e9..7a3cfca 100644 --- a/doc/event.n +++ b/doc/event.n @@ -76,7 +76,7 @@ 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 +Note that virtual events that are not bound to physical event sequences are \fInot\fR returned by \fBevent info\fR. .RE .SH "EVENT FIELDS" @@ -108,13 +108,11 @@ 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 @@ -308,6 +306,7 @@ Any options that are not specified when generating an event are filled with the value 0, except for \fIserial\fR, which is filled with the next X event serial number. .SH "PREDEFINED VIRTUAL EVENTS" +.PP Tk defines the following virtual events for the purposes of notification: .TP @@ -366,6 +365,36 @@ Copy the currently selected widget contents to the clipboard. \fB<<Cut>>\fR Move the currently selected widget contents to the clipboard. .TP +\fB<<LineEnd>>\fR +. +Move to the end of the line in the current widget while deselecting any +selected contents. +.TP +\fB<<LineStart>>\fR +. +Move to the start of the line in the current widget while deselecting any +selected contents. +.TP +\fB<<NextChar>>\fR +. +Move to the next item (i.e., visible character) in the current widget while +deselecting any selected contents. +.TP +\fB<<NextLine>>\fR +. +Move to the next line in the current widget while deselecting any selected +contents. +.TP +\fB<<NextPara>>\fR +. +Move to the next paragraph in the current widget while deselecting any +selected contents. +.TP +\fB<<NextWord>>\fR +. +Move to the next group of items (i.e., visible word) in the current widget +while deselecting any selected contents. +.TP \fB<<Paste>>\fR Replace the currently selected widget contents with the contents of the clipboard. @@ -374,32 +403,123 @@ the clipboard. Insert the contents of the selection at the mouse location. (This event has meaningful \fB%x\fR and \fB%y\fR substitutions). .TP +\fB<<PrevChar>>\fR +. +Move to the previous item (i.e., visible character) in the current widget +while deselecting any selected contents. +.TP +\fB<<PrevLine>>\fR +. +Move to the previous line in the current widget while deselecting any selected +contents. +.TP +\fB<<PrevPara>>\fR +. +Move to the previous paragraph in the current widget while deselecting any +selected contents. +.TP \fB<<PrevWindow>>\fR Traverse to the previous window. .TP +\fB<<PrevWord>>\fR +. +Move to the previous group of items (i.e., visible word) in the current widget +while deselecting any selected contents. +.TP \fB<<Redo>>\fR Redo one undone action. .TP +\fB<<SelectAll>>\fR +. +Set the range of selected contents to the complete widget. +.TP +\fB<<SelectLineEnd>>\fR +. +Move to the end of the line in the current widget while extending the range +of selected contents. +.TP +\fB<<SelectLineStart>>\fR +. +Move to the start of the line in the current widget while extending the range +of selected contents. +.TP +\fB<<SelectNextChar>>\fR +. +Move to the next item (i.e., visible character) in the current widget while +extending the range of selected contents. +.TP +\fB<<SelectNextLine>>\fR +. +Move to the next line in the current widget while extending the range of +selected contents. +.TP +\fB<<SelectNextPara>>\fR +. +Move to the next paragraph in the current widget while extending the range +of selected contents. +.TP +\fB<<SelectNextWord>>\fR +. +Move to the next group of items (i.e., visible word) in the current widget +while extending the range of selected contents. +.TP +\fB<<SelectNone>>\fR +. +Reset the range of selected contents to be empty. +.TP +\fB<<SelectPrevChar>>\fR +. +Move to the previous item (i.e., visible character) in the current widget +while extending the range of selected contents. +.TP +\fB<<SelectPrevLine>>\fR +. +Move to the previous line in the current widget while extending the range of +selected contents. +.TP +\fB<<SelectPrevPara>>\fR +. +Move to the previous paragraph in the current widget while extending the +range of selected contents. +.TP +\fB<<SelectPrevWord>>\fR +. +Move to the previous group of items (i.e., visible word) in the current widget +while extending the range of selected contents. +.TP +\fB<<ToggleSelection>>\fR +. +Toggle the selection. +.TP \fB<<Undo>>\fR +. Undo the last action. -.SH "VIRTUAL EVENT EXAMPLES" +.SH EXAMPLES +.SS "MAPPING KEYS TO VIRTUAL EVENTS" .PP In order for a virtual event binding to trigger, two things must happen. First, the virtual event must be defined with the \fBevent add\fR command. Second, a binding must be created for the virtual event with the \fBbind\fR command. Consider the following virtual event definitions: +.PP .CS -event add <<Paste>> <Control-y> -event add <<Paste>> <Button-2> -event add <<Save>> <Control-X><Control-S> -event add <<Save>> <Shift-F12> +\fBevent add\fR <<Paste>> <Control-y> +\fBevent add\fR <<Paste>> <Button-2> +\fBevent add\fR <<Save>> <Control-X><Control-S> +\fBevent add\fR <<Save>> <Shift-F12> +if {[tk windowingsystem] eq "aqua"} { + \fBevent add\fR <<Save>> <Command-s> +} .CE +.PP In the \fBbind\fR command, a virtual event can be bound like any other builtin event type as follows: +.PP .CS bind Entry <<Paste>> {%W insert [selection get]} .CE +.PP The double angle brackets are used to specify that a virtual event is being bound. If the user types Control-y or presses button 2, or if a \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR, @@ -408,11 +528,13 @@ then the \fB<<Paste>>\fR binding will be invoked. If a virtual binding has the exact same sequence as a separate physical binding, then the physical binding will take precedence. Consider the following example: +.PP .CS -event add <<Paste>> <Control-y> <Meta-Control-y> +\fBevent add\fR <<Paste>> <Control-y> <Meta-Control-y> bind Entry <Control-y> {puts Control-y} bind Entry <<Paste>> {puts Paste} .CE +.PP When the user types Control-y the \fB<Control-y>\fR binding will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. @@ -430,18 +552,41 @@ ungeneratable. When a definition of a virtual event changes at run time, all windows will respond immediately to the new definition. Starting from the preceding example, if the following code is executed: +.PP .CS -bind <Entry> <Control-y> {} -event add <<Paste>> <Key-F6> +bind Entry <Control-y> {} +\fBevent add\fR <<Paste>> <Key-F6> .CE +.PP the behavior will change such in two ways. First, the shadowed \fB<<Paste>>\fR binding will emerge. Typing Control-y will no longer invoke the \fB<Control-y>\fR binding, but instead invoke the virtual event \fB<<Paste>>\fR. Second, pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding. - +.SS "MOVING THE MOUSE POINTER" +.PP +Sometimes it is useful to be able to really move the mouse pointer. For +example, if you have some software that is capable of demonstrating directly +to the user how to use the program. To do this, you need to +.QW warp +the mouse around by using \fBevent generate\fR, like this: +.PP +.CS +for {set xy 0} {$xy < 200} {incr xy} { + \fBevent generate\fR . <Motion> -x $xy -y $xy -warp 1 + update + after 50 +} +.CE +.PP +Note that it is usually considered bad style to move the mouse pointer for the +user because it removes control from them. Therefore this technique should be +used with caution. Also note that it is not guaranteed to function on all +platforms. .SH "SEE ALSO" bind(n) - .SH KEYWORDS event, binding, define, handle, virtual event +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/focus.n b/doc/focus.n index d4f29e8..4b8bb2a 100644 --- a/doc/focus.n +++ b/doc/focus.n @@ -18,7 +18,6 @@ focus \- Manage the input focus \fBfocus \fIoption\fR ?\fIarg arg ...\fR? .fi .BE - .SH DESCRIPTION .PP The \fBfocus\fR command is used to manage the Tk input focus. @@ -106,6 +105,7 @@ number of problems that would occur if the X focus were actually moved; the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. .SH "EXAMPLE" +.PP To make a window that only participates in the focus traversal ring when a variable is set, add the following bindings to the widgets \fIbefore\fR and \fIafter\fR it in that focus ring: @@ -130,6 +130,8 @@ bind .after <Shift\-Tab> { } \fBfocus\fR .before .CE - .SH KEYWORDS events, focus, keyboard, top-level, window manager +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/focusNext.n b/doc/focusNext.n index 11a3a49..ffcf971 100644 --- a/doc/focusNext.n +++ b/doc/focusNext.n @@ -18,7 +18,6 @@ tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for manag .sp \fBtk_focusFollowsMouse\fR .BE - .SH DESCRIPTION .PP \fBtk_focusNext\fR is a utility procedure used for keyboard traversal. @@ -54,6 +53,8 @@ Note: at present there is no built-in support for returning the application to an explicit focus model; to do this you will have to write a script that deletes the bindings created by \fBtk_focusFollowsMouse\fR. - .SH KEYWORDS focus, keyboard traversal, top-level +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -26,7 +26,7 @@ first argument. The following forms are currently supported: 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. +limitations, such as the availability of font families and point sizes. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that attribute; if it is @@ -50,6 +50,14 @@ then the command modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. +.RS +.PP +Note that on Aqua/Mac OS X, the system fonts (see +\fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they +are implemented by the system theme. To achieve the effect of modification, +use \fBfont actual\fR to get their configuration and \fBfont create\fR to +synthesize a copy of the font which can be modified. +.RE .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . @@ -102,7 +110,7 @@ below for a list of the possible metrics. .TP \fBfont names\fR The return value is a list of all the named fonts that are currently defined. -.SH "FONT DESCRIPTION" +.SH "FONT DESCRIPTIONS" .PP The following formats are accepted as a font description anywhere \fIfont\fR is specified as an argument above; these same forms are also @@ -123,7 +131,7 @@ The platform-specific name of a font, interpreted by the graphics server. This also includes, under X, an XLFD (see [4]) for which a single .QW \fB*\fR character was used to elide more than one field in the middle of the -name. See \fBPLATFORM-SPECIFIC\fR issues for a list of the system fonts. +name. See \fBPLATFORM SPECIFIC FONTS\fR for a list of the system fonts. .TP [3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? . @@ -181,7 +189,7 @@ a garbage value); in that case, some system-dependent default font is chosen. If the font description does not match any of the above patterns, an error is generated. .SH "FONT METRICS" -. +.PP The following options are used by the \fBfont metrics\fR command to query font-specific data determined when the font was created. These properties are for the whole font itself and not for individual characters drawn in that @@ -223,6 +231,7 @@ individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. .SH "FONT OPTIONS" +.PP The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: @@ -286,7 +295,7 @@ The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is \fBfalse\fR. .SH "STANDARD FONTS" -.LP +.PP The following named fonts are supported on all systems, and default to values that match appropriate system defaults. .TP @@ -329,7 +338,7 @@ This font should be used for tooltip windows (transient information windows). 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" +.SH "PLATFORM SPECIFIC FONTS" .PP The following system fonts are supported: .TP @@ -373,6 +382,7 @@ theme fonts: .DE .RE .SH EXAMPLE +.PP Fill a text widget with lots of font demonstrators, one for every font family installed on your system: .CS @@ -390,9 +400,10 @@ foreach family [lsort \-dictionary [\fBfont families\fR]] { } } .CE - .SH "SEE ALSO" options(n) - .SH KEYWORDS font +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/fontchooser.n b/doc/fontchooser.n new file mode 100644 index 0000000..bdd51c7 --- /dev/null +++ b/doc/fontchooser.n @@ -0,0 +1,181 @@ +'\" +'\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net> +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH fontchooser n "" Tk "Tk Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +fontchooser \- control font selection dialog +.SH SYNOPSIS +\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR? +.sp +\fBtk fontchooser\fR \fBshow\fR +.sp +\fBtk fontchooser\fR \fBhide\fR +.BE +.SH DESCRIPTION +.PP +The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses +the native platform font selection dialog where available, or a dialog +implemented in Tcl otherwise. +.PP +Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not +return an immediate result, as on some platforms (Mac OS X) the standard font +dialog is modeless while on others (Windows) it is modal. To accommodate this +difference, all user interaction with the dialog will be communicated to the +caller via callbacks or virtual events. +.PP +The \fBtk fontchooser\fR command can have one of the following forms: +.TP +\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR? +. +Set or query one or more of the configurations options below (analogous to Tk +widget configuration). +.TP +\fBtk fontchooser\fR \fBshow\fR +. +Show the font selection dialog. Depending on the platform, may return +immediately or only once the dialog has been withdrawn. +.TP +\fBtk fontchooser\fR \fBhide\fR +. +Hide the font selection dialog if it is visible and cause any pending +\fBtk fontchooser\fR \fBshow\fR command to return. +.PP +.SH "CONFIGURATION OPTIONS" +.TP +\fB\-parent\fR +Specifies/returns the logical parent window of the font selection dialog +(similar to the \fB\-parent\fR option to other dialogs). The font selection +dialog is hidden if it is visible when the parent window is destroyed. +.TP +\fB\-title\fR +Specifies/returns the title of the dialog. Has no effect on platforms where the +font selection dialog does not support titles. +.TP +\fB\-font\fR +Specifies/returns the font that is currently selected in the dialog if it is +visible, or that will be initially selected when the dialog is shown (if +supported by the platform). Can be set to the empty string to indicate that no +font should be selected. Fonts can be specified in any form given by the "FONT +DESCRIPTION" section in the \fBfont\fR manual page. +.TP +\fB\-command\fR +Specifies/returns the command prefix to be called when a font selection has +been made by the user. The command prefix is evaluated at the global level +after having the specification of the selected font appended. On platforms +where the font selection dialog offers the user control of further font +attributes (such as color), additional key/value pairs may be appended before +evaluation. Can be set to the empty string to indicate that no callback should +be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" +section in the \fBfont\fR manual page (i.e. a list of the form +\fI{family size style ?style ...?}\fR). +.TP +\fB\-visible\fR +Read-only option that returns a boolean indicating whether the font selection +dialog is currently visible. Attempting to set this option results in an error. + +.PP +.SH "VIRTUAL EVENTS" +.TP +\fB<<TkFontchooserVisibility>>\fR +Sent to the dialog parent whenever the visibility of the font selection dialog +changes, both as a result of user action (e.g. disposing of the dialog via +OK/Cancel button or close box) and of the \fBtk fontchooser\fR +\fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the +current visibility of the dialog by querying the \fB\-visible\fR configuration +option. +.TP +\fB<<TkFontchooserFontChanged>>\fR +Sent to the dialog parent whenever the font selection dialog is visible and the +selected font changes, both as a result of user action and of the \fB\-font\fR +configuration option being set. Binding scripts can determine the currently +selected font by querying the \fB\-font\fR configuration option. +.PP +.SH NOTES +.PP +Callers should not expect a result from \fBtk fontchooser\fR \fBshow\fR and may +not assume that the dialog has been withdrawn or closed when the command +returns. All user interaction with the dialog is communicated to the caller via +the \fB\-command\fR callback and the \fB<<TkFontchooser*>>\fR virtual events. +It is implementation dependent which exact user actions result in the callback +being called resp. the virtual events being sent. Where an Apply or OK button +is present in the dialog, that button will trigger the \fB\-command\fR callback +and \fB<<TkFontchooserFontChanged>>\fR virtual event. On some implementations +other user actions may also have that effect; on Mac OS X for instance, the +standard font selection dialog immediately reflects all user choices to the +caller. +.PP +In the presence of multiple widgets intended to be influenced by the font +selection dialog, care needs to be taken to correctly handle focus changes: the +font selected in the dialog should always match the current font of the widget +with the focus, and the \fB\-command\fR callback should only act on the widget +with the focus. The recommended practice is to set font dialog \fB\-font\fR and +\fB\-command\fR configuration options in per\-widget \fB<FocusIn>\fR handlers +(and if necessary to unset them \- i.e. set to the empty string \- in +corresponding \fB<FocusOut>\fR handlers). This is particularly important for +implementers of library code using the font selection dialog, to avoid +conflicting with application code that may also want to use the dialog. +.PP +Because the font selection dialog is application-global, in the presence of +multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR +callback set by the interpreter that most recently called \fBtk fontchooser\fR +\fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response +to user action and only the \fB\-parent\fR set by that interpreter will receive +\fB<<TkFontchooser*>>\fR virtual events. +.PP +The font dialog implementation may only store (and return) \fBfont\fR +\fBactual\fR data as the value of the \fB\-font\fR configuration option. This +can be an issue when \fB\-font\fR is set to a named font, if that font is +subsequently changed, the font dialog \fB\-font\fR option needs to be set again +to ensure its selected font matches the new value of the named font. +.PP +.SH EXAMPLE +.PP +.CS +proc fontchooserDemo {} { + wm title . "Font Chooser Demo" + \fBtk fontchooser\fR \fBconfigure\fR \-parent . + button .b \-command fontchooserToggle \-takefocus 0 + fontchooserVisibility .b + bind . \fB<<TkFontchooserVisibility>>\fR \\ + [list fontchooserVisibility .b] + foreach w {.t1 .t2} { + text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid + bind $w <FocusIn> [list fontchooserFocus $w] + $w insert end "Text Widget $w" + } + .t1 configure \-font {Courier 14} + .t2 configure \-font {Times 16} + pack .b .t1 .t2; focus .t1 +} +proc fontchooserToggle {} { + \fBtk fontchooser\fR [expr { + [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + "\fBhide\fR" : "\fBshow\fR"}] +} +proc fontchooserVisibility {w} { + $w configure \-text [expr { + [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + "Hide Font Dialog" : "Show Font Dialog"}] +} +proc fontchooserFocus {w} { + \fBtk fontchooser\fR \fBconfigure\fR \-font [$w cget \-font] \\ + \-command [list fontchooserFontSelection $w] +} +proc fontchooserFontSelection {w font args} { + $w configure \-font [font actual $font] +} +fontchooserDemo +.CE +.SH "SEE ALSO" +font(n), tk(n) +.SH KEYWORDS +dialog, font, font selection, font chooser, font panel +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/frame.n b/doc/frame.n index 7eaed62..72a22db 100644 --- a/doc/frame.n +++ b/doc/frame.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -frame \- Create and manipulate frame widgets +frame \- Create and manipulate 'frame' simple container widgets .SH SYNOPSIS \fBframe\fR \fIpathName\fR ?\fIoptions\fR? .SO @@ -20,7 +20,7 @@ frame \- Create and manipulate frame widgets .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background -This option is the same as the standard \fBbackground\fR option +This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background @@ -30,7 +30,7 @@ Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR +The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. @@ -39,7 +39,7 @@ created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. -If the \fBcolormap\fR option is not specified, the new window +If the \fB\-colormap\fR option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the \fBconfigure\fR widget command. @@ -52,7 +52,7 @@ 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 +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 @@ -67,7 +67,7 @@ Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the same visual as its parent. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR +The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms @@ -134,3 +134,6 @@ frames are not intended to be interactive. labelframe(n), toplevel(n), ttk::frame(n) .SH KEYWORDS frame, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index a57143e..f5e92ff 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -42,6 +42,7 @@ 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 @@ -51,6 +52,7 @@ and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. .TP \fB\-filetypes\fR \fIfilePatternList\fR +. If a \fBFile types\fR listbox exists in the file dialog on the particular platform, this option gives the \fIfiletype\fRs in this listbox. When the user choose a filetype in the listbox, only the files of that type @@ -61,32 +63,42 @@ types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. .TP \fB\-initialdir\fR \fIdirectory\fR +. Specifies that the files in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, then -the files in the current working directory are displayed. If the +when the dialog pops up. If this parameter is not specified, +the initial directory defaults to the current working directory +on non-Windows systems and on Windows systems prior to Vista. +On Vista and later systems, the initial directory defaults to the last +user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .TP \fB\-initialfile\fR \fIfilename\fR +. Specifies a filename to be displayed in the dialog when it pops up. .TP \fB\-message\fR \fIstring\fR +. Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. .TP \fB\-multiple\fR \fIboolean\fR +. Allows the user to choose multiple files from the Open dialog. .TP \fB\-parent\fR \fIwindow\fR +. Makes \fIwindow\fR the logical parent of the file dialog. The file dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. .TP \fB\-title\fR \fItitleString\fR +. Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed. .TP \fB\-typevariable\fR \fIvariableName\fR +. The global variable \fIvariableName\fR is used to preselect which filter is used from \fIfilterList\fR when the dialog box is opened and is updated when the dialog box is closed, to the last selected @@ -163,6 +175,7 @@ Extensions without a full stop character (e.g. .QW ~ ) are allowed but may not work on all platforms. .SH EXAMPLE +.PP .CS set types { {{Text Files} {.txt} } @@ -172,9 +185,9 @@ set types { {{GIF Files} {} GIFF} {{All Files} * } } -set filename [tk_getOpenFile \-filetypes $types] +set filename [\fBtk_getOpenFile\fR \-filetypes $types] -if {$filename != ""} { +if {$filename ne ""} { # Open the file ... } .CE @@ -182,3 +195,6 @@ if {$filename != ""} { tk_chooseDirectory .SH KEYWORDS file selection dialog +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -16,7 +16,6 @@ grab \- Confine pointer and keyboard events to a window sub-tree .sp \fBgrab \fIoption \fR?\fIarg arg \fR...? .BE - .SH DESCRIPTION .PP This command implements simple pointer and keyboard grabs for Tk. @@ -102,6 +101,7 @@ Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. .SH WARNING +.PP It is very easy to use global grabs to render a display completely unusable (e.g. by setting a grab on a widget which does not respond to events and not providing any mechanism for releasing the grab). Take @@ -121,6 +121,7 @@ only one of those applications can have a local grab for a given display at any given time. If the applications are in different processes, this restriction does not exist. .SH EXAMPLE +.PP Set a grab so that only one button may be clicked out of a group. The other buttons are unresponsive to the mouse until the middle button is clicked. @@ -130,6 +131,10 @@ pack [button .b2 \-text "Click me! #2" \-command {destroy .b2}] pack [button .b3 \-text "Click me! #3" \-command {destroy .b3}] \fBgrab\fR .b2 .CE - +.SH "SEE ALSO" +busy(n) .SH KEYWORDS grab, keyboard events, pointer events, window +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -22,44 +22,44 @@ The \fBgrid\fR command can have any of several forms, depending on the \fIoption\fR argument: .TP \fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +. If the first argument to \fBgrid\fR is suitable as the first slave argument to \fBgrid configure\fR, either a window name (any value -starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR +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, +. +With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the master window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, -also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on +also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR arguments are specified, then the bounding box spanning the rows and columns indicated is returned. .TP \fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR? -Query or set the column properties of the \fIindex\fR column of the +. +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 +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. -.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\fR option (an integer value) @@ -86,10 +86,11 @@ are returned in a list of pairs. .TP \fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +. The arguments consist of the names of one or more slave windows followed by pairs of arguments that specify how to manage the slaves. -The characters \fB\-\fR, \fBx\fR and \fB^\fR, +The characters \fB\-\fR, \fBx\fR and \fB^\fR, can be specified instead of a window name to alter the default location of a \fIslave\fR, as described in the \fBRELATIVE PLACEMENT\fR section, below. @@ -97,6 +98,7 @@ The following options are supported: .RS .TP \fB\-column \fIn\fR +. Insert the slave so that it occupies the \fIn\fRth column in the grid. Column numbers start with 0. If this option is not supplied, then the slave is arranged just to the right of previous slave specified on this @@ -108,17 +110,20 @@ is incremented by one. Thus the \fBx\fR represents a blank column for this row in the grid. .TP \fB\-columnspan \fIn\fR +. Insert the slave so that it occupies \fIn\fR columns in the grid. The default is one column, unless the window name is followed by a \fB\-\fR, in which case the columnspan is incremented once for each immediately following \fB\-\fR. .TP \fB\-in \fIother\fR +. Insert the slave(s) in the master window given by \fIother\fR. The default is the first slave's parent window. .TP \fB\-ipadx \fIamount\fR +. The \fIamount\fR specifies how much horizontal internal padding to leave on each side of the slave(s). This is space is added inside the slave(s) border. @@ -126,12 +131,14 @@ The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. It defaults to 0. .TP \fB\-ipady \fIamount\fR +. The \fIamount\fR specifies how much vertical internal padding to leave on the top and bottom of the slave(s). This space is added inside the slave(s) border. The \fIamount\fR defaults to 0. .TP \fB\-padx \fIamount\fR +. The \fIamount\fR specifies how much horizontal external padding to leave on each side of the slave(s), in screen units. \fIAmount\fR may be a list @@ -140,6 +147,7 @@ The \fIamount\fR defaults to 0. This space is added outside the slave(s) border. .TP \fB\-pady \fIamount\fR +. The \fIamount\fR specifies how much vertical external padding to leave on the top and bottom of the slave(s), in screen units. \fIAmount\fR may be a list @@ -148,12 +156,14 @@ The \fIamount\fR defaults to 0. This space is added outside the slave(s) border. .TP \fB\-row \fIn\fR +. Insert the slave so that it occupies the \fIn\fRth row in the grid. Row numbers start with 0. If this option is not supplied, then the slave is arranged on the same row as the previous slave specified on this call to \fBgrid\fR, or the first unoccupied row if this is the first slave. .TP \fB\-rowspan \fIn\fR +. Insert the slave so that it occupies \fIn\fR rows in the grid. The default is one row. If the next \fBgrid\fR command contains \fB^\fR characters instead of \fIslaves\fR that line up with the columns @@ -161,6 +171,7 @@ 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 @@ -171,7 +182,7 @@ 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 +height (or width) of its cavity. The \fB\-sticky\fR option subsumes the combination of \fB\-anchor\fR and \fB\-fill\fR that is used by \fBpack\fR. The default is .QW "" , @@ -183,6 +194,7 @@ than receiving default values. .RE .TP \fBgrid forget \fIslave \fR?\fIslave ...\fR? +. Removes each of the \fIslave\fRs from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. @@ -191,6 +203,7 @@ slave is managed once more by the grid geometry manager, the initial default settings are used. .TP \fBgrid info \fIslave\fR +. Returns a list whose elements are the current configuration state of the slave given by \fIslave\fR in the same option-value form that might be specified to \fBgrid configure\fR. @@ -199,12 +212,14 @@ The first two elements of the list are where \fImaster\fR is the slave's master. .TP \fBgrid location \fImaster x y\fR -Given \fIx\fR and \fIy\fR values in screen units relative to the master window, +. +Given \fIx\fR and \fIy\fR values in screen units relative to the master window, the column and row number at that \fIx\fR and \fIy\fR location is returned. For locations that are above or to the left of the grid, \fB\-1\fR is returned. .TP \fBgrid propagate \fImaster\fR ?\fIboolean\fR? +. If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fImaster\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). @@ -217,18 +232,17 @@ for \fImaster\fR. Propagation is enabled by default. .TP \fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR? -Query or set the row properties of the \fIindex\fR row of the +. +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 +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. -.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\fR option (an integer value) @@ -255,6 +269,7 @@ are returned in a list of pairs. .TP \fBgrid remove \fIslave \fR?\fIslave ...\fR? +. Removes each of the \fIslave\fRs from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. @@ -264,12 +279,14 @@ slave is managed once more by the grid geometry manager, the previous values are retained. .TP \fBgrid size \fImaster\fR +. Returns the size of the grid (in columns then rows) for \fImaster\fR. The size is determined either by the \fIslave\fR occupying the largest -row or column, or the largest column or row with a \fBminsize\fR, -\fBweight\fR, or \fBpad\fR that is non-zero. +row or column, or the largest column or row with a \fB\-minsize\fR, +\fB\-weight\fR, or \fB\-pad\fR that is non-zero. .TP \fBgrid slaves \fImaster\fR ?\fI\-option value\fR? +. If no options are supplied, a list of all of the slaves in \fImaster\fR are returned, most recently manages first. \fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which @@ -278,13 +295,13 @@ to be returned. .SH "RELATIVE PLACEMENT" .PP The \fBgrid\fR command contains a limited set of capabilities that -permit layouts to be created without specifying the row and column -information for each slave. This permits slaves to be rearranged, +permit layouts to be created without specifying the row and column +information for each slave. This permits slaves to be rearranged, added, or removed without the need to explicitly specify row and column information. -When no column or row information is specified for a \fIslave\fR, +When no column or row information is specified for a \fIslave\fR, default values are chosen for -\fBcolumn\fR, \fBrow\fR, \fBcolumnspan\fR and \fBrowspan\fR +\fB\-column\fR, \fB\-row\fR, \fB\-columnspan\fR and \fB\-rowspan\fR at the time the \fIslave\fR is managed. The values are chosen based upon the current layout of the grid, the position of the \fIslave\fR relative to other \fIslave\fRs in the same grid command, and the presence @@ -293,17 +310,20 @@ command where \fIslave\fR names are normally expected. .RS .TP \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 +. +This increases the \fB\-columnspan\fR of the \fIslave\fR to the left. Several +\fB\-\fR's in a row will successively increase the number of columns spanned. A \fB\-\fR may not follow a \fB^\fR or a \fBx\fR, nor may it be the first \fIslave\fR argument to \fBgrid configure\fR. .TP \fBx\fR +. This leaves an empty column between the \fIslave\fR on the left and the \fIslave\fR on the right. .TP \fB^\fR -This extends the \fBrowspan\fR of the \fIslave\fR above the \fB^\fR's +. +This extends the \fB\-rowspan\fR of the \fIslave\fR above the \fB^\fR's in the grid. The number of \fB^\fR's in a row must match the number of columns spanned by the \fIslave\fR above it. .RE @@ -320,12 +340,12 @@ For the final step, each slave is positioned in its row(s) and column(s) based on the setting of its \fIsticky\fR flag. .PP To compute the minimum size of a layout, the grid geometry manager -first looks at all slaves whose columnspan and rowspan values are one, +first looks at all slaves whose \fB\-columnspan\fR and \fB\-rowspan\fR values are one, and computes the nominal size of each row or column to be either the \fIminsize\fR for that row or column, or the sum of the \fIpad\fRding plus the size of the largest slave, whichever is greater. After that the rows or columns in each uniform group adapt to each other. Then -the slaves whose rowspans or columnspans are greater than one are +the slaves whose row-spans or column-spans are greater than one are examined. If a group of rows or columns need to be increased in size in order to accommodate these slaves, then extra space is added to each row or column in the group according to its \fIweight\fR. For each @@ -337,9 +357,9 @@ allocated to them is always in proportion to their weights. (A weight of zero is considered to be 1.) In other words, a row or column configured with \fB\-weight 1 \-uniform a\fR will have exactly the same size as any other row or column configured with \fB\-weight 1 \-uniform -a\fR. A row or column configured with \fB\-weight 2 \-uniform b\fR will +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. +\-uniform b\fR. .PP More technically, each row or column in the group will have a size equal to \fIk*weight\fR for some constant \fIk\fR. The constant @@ -348,18 +368,16 @@ 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 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 +away from columns and rows according to their weights. However, once a column or row shrinks to its minsize, its weight is taken to be zero. If more space needs to be removed from a layout than would be permitted, as when all the rows or columns are at their minimum sizes, the layout is placed and clipped according to the \fIanchor\fR value. -.VE 8.5 .SH "GEOMETRY PROPAGATION" .PP The grid geometry manager normally computes how large a master must be to @@ -397,7 +415,9 @@ The \fBgrid\fR command is based on ideas taken from the \fIGridBag\fR geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry manager, written by George Howlett. .SH EXAMPLES +.PP A toplevel window containing a text widget and two scrollbars: +.PP .CS # Make the widgets toplevel .t @@ -417,6 +437,7 @@ scrollbar .t.h \-orient horizontal \-command {.t.txt xview} Three widgets of equal width, despite their different .QW natural widths: +.PP .CS button .b \-text "Foo" entry .e \-variable foo @@ -429,3 +450,6 @@ label .l \-text "This is a fairly long piece of text" pack(n), place(n) .SH KEYWORDS geometry manager, location, grid, cell, propagation, size, pack +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/image.n b/doc/image.n index c4cfbfd..fd51cc0 100644 --- a/doc/image.n +++ b/doc/image.n @@ -14,7 +14,6 @@ image \- Create and manipulate images .SH SYNOPSIS \fBimage\fR \fIoption \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBimage\fR command is used to create, delete, and query images. @@ -94,9 +93,10 @@ See the \fBbitmap\fR manual entry for more information. Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. - .SH "SEE ALSO" bitmap(n), options(n), photo(n) - .SH KEYWORDS height, image, types of images, width +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/keysyms.n b/doc/keysyms.n index c599bca..bf81440 100644 --- a/doc/keysyms.n +++ b/doc/keysyms.n @@ -9,11 +9,11 @@ .SH NAME keysyms \- keysyms recognized by Tk .BE - .SH DESCRIPTION .PP -Tk recognizes many keysyms when specifying key bindings (e.g. -\fBbind . <Key-\fR\fIkeysym\fR\fB>\fR). The following list enumerates the +Tk recognizes many keysyms when specifying key bindings (e.g., +.QW "\fBbind\fR \fB. <Key-\fR\fIkeysym\fR\fB>\fR" ). +The following list enumerates the keysyms that will be recognized by Tk. Note that not all keysyms will be valid on all platforms. For example, on Unix systems, the presence of a particular keysym is dependant on the configuration of the @@ -919,9 +919,10 @@ Hyper_L 65517 0xffed Hyper_R 65518 0xffee Delete 65535 0xffff .CE - .SH "SEE ALSO" -bind - +bind(n), event(n) .SH KEYWORDS -keysym, bind, binding +bind, binding, event, keysym +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/label.n b/doc/label.n index 9bbc9e0..f2ba88c 100644 --- a/doc/label.n +++ b/doc/label.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -label \- Create and manipulate label widgets +label \- Create and manipulate 'label' non-interactive text or image widgets .SH SYNOPSIS \fBlabel\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -34,10 +34,10 @@ from the size of the image or bitmap or text being displayed in it. .OP \-state state State Specifies one of three states for the label: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the button is displayed using the -\fBforeground\fR and \fBbackground\fR options. In active state -the label is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. In the disabled state the -\fBdisabledForeground\fR and \fBbackground\fR options determine how +\fB\-foreground\fR and \fB\-background\fR options. In active state +the label is displayed using the \fB\-activeforeground\fR and +\fB\-activebackground\fR options. In the disabled state the +\fB\-disabledforeground\fR and \fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the label. @@ -63,9 +63,9 @@ there must not exist a window named \fIpathName\fR, but A label is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and +or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the -\fBunderline\fR option. +\fB\-underline\fR option. The label can be manipulated in a few simple ways, such as changing its relief or text, using the commands described below. .SH "WIDGET COMMAND" @@ -105,6 +105,7 @@ command. When a new label is created, it has no default event bindings: labels are not intended to be interactive. .SH EXAMPLE +.PP .CS # Make the widgets \fBlabel\fR .t \-text "This widget is at the top" \-bg red @@ -124,3 +125,6 @@ pack .mid \-expand 1 \-fill both labelframe(n), button(n), ttk::label(n) .SH KEYWORDS label, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/labelframe.n b/doc/labelframe.n index cea4804..857208e 100644 --- a/doc/labelframe.n +++ b/doc/labelframe.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -labelframe \- Create and manipulate labelframe widgets +labelframe \- Create and manipulate 'labelframe' labelled container widgets .SH SYNOPSIS \fBlabelframe\fR \fIpathName\fR ?\fIoptions\fR? .SO @@ -21,7 +21,7 @@ labelframe \- Create and manipulate labelframe widgets .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background -This option is the same as the standard \fBbackground\fR option +This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background @@ -31,7 +31,7 @@ Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR +The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. @@ -40,7 +40,7 @@ created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. -If the \fBcolormap\fR option is not specified, the new window +If the \fB\-colormap\fR option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the \fBconfigure\fR widget command. @@ -66,7 +66,7 @@ Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the same visual as its parent. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR +The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms @@ -126,6 +126,7 @@ command. When a new labelframe is created, it has no default event bindings: labelframes are not intended to be interactive. .SH EXAMPLE +.PP This shows how to build part of a GUI for a hamburger vendor. The \fBlabelframe\fR widgets are used to organize the available choices by the kinds of things that the choices are being made over. @@ -169,3 +170,6 @@ set pickle none frame(n), label(n), ttk::labelframe(n) .SH KEYWORDS labelframe, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/listbox.n b/doc/listbox.n index 642e1f0..9f34b5e 100644 --- a/doc/listbox.n +++ b/doc/listbox.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -listbox \- Create and manipulate listbox widgets +listbox \- Create and manipulate 'listbox' item list widgets .SH SYNOPSIS \fBlistbox\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -75,7 +75,7 @@ When first created, a new listbox has no elements. Elements may be added or deleted using widget commands described below. In addition, one or more elements may be selected as described below. -If a listbox is exporting its selection (see \fBexportSelection\fR +If a listbox is exporting its selection (see \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection. Listbox selections are available as type \fBSTRING\fR; @@ -85,8 +85,8 @@ newlines separating the elements. It is not necessary for all the elements to be displayed in the listbox window at once; commands described below may be used to change the view in the window. Listboxes allow -scrolling in both directions using the standard \fBxScrollCommand\fR -and \fByScrollCommand\fR options. +scrolling in both directions using the standard \fB\-xscrollcommand\fR +and \fB\-yscrollcommand\fR options. They also support scanning, as described below. .SH "INDICES" .PP @@ -96,20 +96,24 @@ An index specifies a particular element of the listbox, in any of the following ways: .TP 12 \fInumber\fR +. Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox. .TP 12 \fBactive\fR +. Indicates the element that has the location cursor. This element will be displayed as specified by \fB\-activestyle\fR when the listbox has the keyboard focus, and it is specified with the \fBactivate\fR widget command. .TP 12 \fBanchor\fR +. Indicates the anchor point for the selection, which is set with the \fBselection anchor\fR widget command. .TP 12 \fBend\fR +. Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as \fBindex\fR and \fBinsert\fR @@ -138,6 +142,7 @@ determine the exact behavior of the command. The following commands are possible for listbox widgets: .TP \fIpathName \fBactivate\fR \fIindex\fR +. Sets the active element to the one indicated by \fIindex\fR. If \fIindex\fR is outside the range of elements in the listbox then the closest element is activated. @@ -146,6 +151,7 @@ widget has the input focus, and its index may be retrieved with the index \fBactive\fR. .TP \fIpathName \fBbbox\fR \fIindex\fR +. Returns a list of four numbers describing the bounding box of the text in the element given by \fIindex\fR. The first two elements of the list give the x and y coordinates @@ -160,12 +166,14 @@ partially visible, the result gives the full area of the element, including any parts that are not visible. .TP \fIpathName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -180,18 +188,21 @@ this case the command returns an empty string. command. .TP \fIpathName \fBcurselection\fR +. Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +. Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR are indices specifying the first and last elements in the range to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR, i.e. a single element is deleted. .TP \fIpathName \fBget \fIfirst\fR ?\fIlast\fR? +. If \fIlast\fR is omitted, returns the contents of the listbox element indicated by \fIfirst\fR, or an empty string if \fIfirst\fR refers to a non-existent element. @@ -202,22 +213,26 @@ Both \fIfirst\fR and \fIlast\fR may have any of the standard forms for indices. .TP \fIpathName \fBindex \fIindex\fR +. Returns the integer index value that corresponds to \fIindex\fR. If \fIindex\fR is \fBend\fR the return value is a count of the number of elements in the listbox (not the index of the last element). .TP \fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? +. Inserts zero or more new elements in the list just before the element given by \fIindex\fR. If \fIindex\fR is specified as \fBend\fR then the new elements are added to the end of the list. Returns an empty string. .TP \fIpathName \fBitemcget \fIindex option\fR +. Returns the current value of the item configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted -by the \fBlistbox itemconfigure\fR command. +by the \fBitemconfigure\fR command. .TP \fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +. Query or modify the configuration options of an item in the listbox. If no \fIoption\fR is specified, returns a list describing all of the available options for the item (see \fBTk_ConfigureInfo\fR for @@ -232,40 +247,48 @@ are currently supported for items: .RS .TP \fB\-background \fIcolor\fR +. \fIColor\fR specifies the background color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-foreground \fIcolor\fR +. \fIColor\fR specifies the foreground color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-selectbackground \fIcolor\fR +. \fIcolor\fR specifies the background color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-selectforeground \fIcolor\fR +. \fIcolor\fR specifies the foreground color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .RE .TP \fIpathName \fBnearest \fIy\fR +. Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. .TP \fIpathName \fBscan\fR \fIoption args\fR +. This command is used to implement scanning on listboxes. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR +. Records \fIx\fR and \fIy\fR and the current view in the listbox window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx y\fR. +. This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last \fBscan mark\fR command for the widget. @@ -277,6 +300,7 @@ value is an empty string. .RE .TP \fIpathName \fBsee \fIindex\fR +. Adjust the view in the listbox so that the element given by \fIindex\fR is visible. If the element is already visible then the command has no effect; @@ -285,11 +309,13 @@ scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. .TP \fIpathName \fBselection \fIoption arg\fR +. This command is used to adjust the selection within a listbox. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection anchor \fIindex\fR +. Sets the selection anchor to the element given by \fIindex\fR. If \fIindex\fR refers to a non-existent element, then the closest element is used. @@ -299,32 +325,38 @@ The index \fBanchor\fR may be used to refer to the anchor element. .TP \fIpathName \fBselection clear \fIfirst \fR?\fIlast\fR? +. If any of the elements between \fIfirst\fR and \fIlast\fR (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range. .TP \fIpathName \fBselection includes \fIindex\fR +. Returns 1 if the element indicated by \fIindex\fR is currently selected, 0 if it is not. .TP \fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? +. Selects all of the elements in the range between \fIfirst\fR and \fIlast\fR, inclusive, without affecting the selection state of elements outside that range. .RE .TP \fIpathName \fBsize\fR +. Returns a decimal string indicating the total number of elements in the listbox. .TP -\fIpathName \fBxview \fIargs\fR +\fIpathName \fBxview \fR?\fIargs\fR +. This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR +. Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. @@ -334,17 +366,20 @@ 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 +\fIpathName \fBxview \fIindex\fR +. Adjusts the view in the window so that the character position given by \fIindex\fR is displayed at the left edge of the window. Character positions are defined by the width of the character \fB0\fR. .TP \fIpathName \fBxview moveto\fI fraction\fR +. Adjusts the view in the window so that \fIfraction\fR of the total width of the listbox text is off-screen to the left. \fIfraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. @@ -359,7 +394,8 @@ become visible; if it is positive then characters farther to the right become visible. .RE .TP -\fIpathName \fByview \fI?args\fR? +\fIpathName \fByview \fR?\fIargs\fR? +. This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: @@ -376,11 +412,13 @@ the last one in the window, relative to the listbox as a whole. These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP -\fIpathName \fByview\fR \fIindex\fR +\fIpathName \fByview \fIindex\fR +. Adjusts the view in the window so that the element given by \fIindex\fR is displayed at the top of the window. .TP \fIpathName \fByview moveto\fI fraction\fR +. Adjusts the view in the window so that the element given by \fIfraction\fR appears at the top of the window. \fIFraction\fR is a fraction between 0 and 1; 0 indicates the first @@ -388,6 +426,7 @@ element in the listbox, 0.33 indicates the element one-third the way through the listbox, and so on. .TP \fIpathName \fByview scroll \fInumber what\fR +. This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. @@ -403,7 +442,7 @@ become visible. .PP Tk automatically creates class bindings for listboxes that give them Motif-like behavior. Much of the behavior of a listbox is determined -by its \fBselectMode\fR option, which selects one of four ways +by its \fB\-selectmode\fR option, which selects one of four ways of dealing with the selection. .PP If the selection mode is \fBsingle\fR or \fBbrowse\fR, at most one @@ -412,10 +451,8 @@ 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. -.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 @@ -431,9 +468,12 @@ Most people will probably want to use \fBbrowse\fR mode for single selections and \fBextended\fR mode for multiple selections; the other modes appear to be useful only in special situations. .PP -Any time the selection changes in the listbox, the virtual event -\fB<<ListboxSelect>>\fR will be generated. It is easiest to bind -to this event to be made aware of any changes to listbox selection. +Any time the set of selected item(s) in the listbox is updated by the +user through the keyboard or mouse, the virtual event +\fB<<ListboxSelect>>\fR will be generated. This virtual event will not +be generated when adjusting the selection with the \fIpathName +\fBselection\fR command. It is easiest to bind to this event to be +made aware of any user changes to listbox selection. .PP In addition to the above behavior, the following additional behavior is defined by the default bindings: @@ -533,6 +573,9 @@ a selection. 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) +ttk::treeview(n) .SH KEYWORDS listbox, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/loadTk.n b/doc/loadTk.n index 2b34cc0..d4ec51e 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -9,73 +9,61 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -loadTk \- Load Tk into a safe interpreter. +safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS -\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? +\fBsafe::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. .PP -The \fB::safe::loadTk\fR command initializes the required data structures -in the named safe interpreter and then loads Tk into it. -The interpreter must have been created with \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 +Safe Tk is based on Safe Tcl, which provides a mechanism that allows +restricted and mediated access to auto-loading and packages for safe +interpreters. Safe Tk adds the ability to configure the interpreter for safe +Tk operations and load Tk into safe interpreters. +.PP +The \fBsafe::loadTk\fR command initializes the required data structures in +the named safe interpreter and then loads Tk into it. The interpreter must +have been created with \fBsafe::interpCreate\fR or have been initialized +with \fBsafe::interpInit\fR. The command returns the name of the safe +interpreter. If \fB\-use\fR is specified, the window identified by the +specified system dependent identifier \fIwindowId\fR is used to contain the .QW . -window of the safe interpreter; it can be any valid id, eventually -referencing a window belonging to another application. As a convenience, -if the window you plan to use is a Tk Window of the application you -can use the window name (e.g. \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 the safe interpreter; it can be any valid id, eventually referencing +a window belonging to another application. As a convenience, if the window you +plan to use is a Tk Window of the application you can use the window name +(e.g., +.QW \fB.x.y\fR ) +instead of its window Id (e.g., from \fBwinfo id\fR \fB.x.y\fR). +When \fB\-use\fR is not specified, a new toplevel window is created for the .QW . -window of -the safe interpreter. On X11 if you want the embedded window -to use another display than the default one, specify it with -\fB\-display\fR. -See the \fBSECURITY ISSUES\fR section below for implementation details. - +window of the safe interpreter. On X11 if you want the embedded window to use +another display than the default one, specify it with \fB\-display\fR. See +the \fBSECURITY ISSUES\fR section below for implementation details. .SH "SECURITY ISSUES" .PP Please read the \fBsafe\fR manual page for Tcl to learn about the basic security considerations for Safe Tcl. .PP -\fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master +\fBsafe::loadTk\fR adds the value of \fBtk_library\fR taken from the master interpreter to the virtual access path of the safe interpreter so that auto-loading will work in the safe interpreter. .PP +Tk initialization is now safe with respect to not trusting the slave's state +for startup. \fBsafe::loadTk\fR registers the slave's name so when the Tk +initialization (\fBTk_SafeInit\fR) is called and in turn calls the master's +\fBsafe::InitTk\fR it will return the desired \fBargv\fR equivalent +(\fB\-use\fR \fIwindowId\fR, correct \fB\-display\fR, etc.) .PP -Tk initialization is now safe with respect to not trusting -the slave's state for startup. \fB::safe::loadTk\fR -registers the slave's name so -when the Tk initialization (\fBTk_SafeInit\fR) is called -and in turn calls the master's \fB::safe::InitTk\fR it will -return the desired \fBargv\fR equivalent (\fB\-use\fR -\fIwindowId\fR, correct \fB\-display\fR, etc.) -.PP -When \fB\-use\fR is not used, the new toplevel created is specially -decorated so the user is always aware that the user interface presented comes -from a potentially unsafe code and can easily delete the corresponding -interpreter. +When \fB\-use\fR is not used, the new toplevel created is specially decorated +so the user is always aware that the user interface presented comes from a +potentially unsafe code and can easily delete the corresponding interpreter. .PP -On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely -to generate a fatal X error. - +On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely to generate a +fatal X error. .SH "SEE ALSO" safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) - .SH KEYWORDS -alias, auto\-loading, auto_mkindex, load, master interpreter, safe +alias, auto-loading, auto_mkindex, load, master interpreter, safe interpreter, slave interpreter, source - '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/lower.n b/doc/lower.n index 3a47094..8159a8b 100644 --- a/doc/lower.n +++ b/doc/lower.n @@ -14,7 +14,6 @@ lower \- Change a window's position in the stacking order .SH SYNOPSIS \fBlower \fIwindow \fR?\fIbelowThis\fR? .BE - .SH DESCRIPTION .PP If the \fIbelowThis\fR argument is omitted then the command lowers @@ -28,9 +27,14 @@ In this case the \fBlower\fR command will insert \fIwindow\fR into the stacking order just below \fIbelowThis\fR (or the ancestor of \fIbelowThis\fR that is a sibling of \fIwindow\fR); this could end up either raising or lowering \fIwindow\fR. - +.PP +All \fBtoplevel\fR windows may be restacked with respect to each +other, whatever their relative path names, but the window manager is +not obligated to strictly honor requests to restack. .SH "SEE ALSO" raise - .SH KEYWORDS lower, obscure, stacking order +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -menu, tk_menuSetFocus \- Create and manipulate menu widgets +menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars .SH SYNOPSIS .nf \fBmenu\fR \fIpathName \fR?\fIoptions\fR? @@ -40,6 +40,8 @@ top. If so, it will exist as entry 0 of the menu and the other entries will number starting at 1. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. +This option is ignored under Aqua/Mac OS X, where menus cannot +be torn off. .OP \-tearoffcommand tearOffCommand TearOffCommand If this option has a non-empty value, then it specifies a Tcl command to invoke whenever the menu is torn off. The actual command will @@ -52,6 +54,8 @@ and menu \fB.x.y\fR is torn off to create a new menu \fB.x.tearoff1\fR, then the command .QW "\fBa b .x.y .x.tearoff1\fR" will be invoked. +This option is ignored under Aqua/Mac OS X, where menus cannot +be torn off. .OP \-title title Title The string will be used to title the window created when this menu is torn off. If the title is NULL, then the window will have the title @@ -69,6 +73,9 @@ library. .PP The \fBmenu\fR command creates a new top-level window (given by the \fIpathName\fR argument) and makes it into a menu widget. +That menu widget can either be used as a pop-up window or applied to a +\fBtoplevel\fR (with its \fB\-menu\fR option) to make it into the menubar for +that toplevel. Additional options, described above, may be specified on the command line or in the option database @@ -203,7 +210,7 @@ supported on Windows. .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 +\fB\-tearoff\fR option. It is not like other menu entries in that it cannot be created with the \fBadd\fR widget command and cannot be deleted with the \fBdelete\fR widget command. When a tear-off entry is created it appears as a dashed line at @@ -228,31 +235,43 @@ menubars, they may not be drawn with indicators on some platforms, due to system restrictions. .SS "SPECIAL MENUS IN MENUBARS" .PP -Certain menus in a menubar will be treated specially. On the -Macintosh, access to the special Application 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 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. +Certain menus in a menubar will be treated specially. On the Macintosh, +access to the special Application, Window and Help menus is provided. On +Windows, access to the Windows System menu in each window is provided. +On X Windows, a special right-justified help menu may be provided if +Motif menu compatibility is enabled. In all cases, these menus must be +created with the command name of the menubar menu concatenated with the +special name. So for a menubar named .menubar, on the Macintosh, the +special menus would be .menubar.apple, .menubar.window and .menubar.help; +on Windows, the special menu would be .menubar.system; on X Windows, +the help menu would be .menubar.help. +.PP +When Tk sees a .menubar.apple menu as the first menu in a menubar on the +Macintosh, that menu's contents make up the first items of the +Application menu whenever the window containing the menubar is in front. After all of the Tk-defined items, the menu will have a separator, followed by all standard Application menu items. -.PP -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 +Such a .apple menu must be present in a menu when that menu is first +configured as a toplevel's menubar, otherwise a default application menu +(hidden from Tk) will be inserted into the menubar at that time and +subsequent addition of a .apple menu will no longer result in it +becoming the Application menu. +.PP +When Tk sees a .menubar.window menu on the Macintosh, the menu's +contents are inserted into the standard Window menu of the user's +menubar whenever the window's menubar is in front. The first items in +the menu are provided by Mac OS X, and the names of the current +toplevels are automatically appended after all the Tk-defined items and +a separator. +.PP +When Tk sees a .menubar.help menu on the Macintosh, the menu's contents +are appended to the standard Help menu of the user's menubar whenever +the window's menubar is in front. The first items in the menu are provided by Mac OS X. .PP When Tk sees a System menu on Windows, its items are appended to the -system menu that the menubar is attached to. This menu has an icon -representing a spacebar, and can be invoked with the mouse or by typing +system menu that the menubar is attached to. This menu is tied to the +application icon and can be invoked with the mouse or by typing Alt+Spacebar. Due to limitations in the Windows API, any font changes, colors, images, bitmaps, or tearoff images will not appear in the system menu. @@ -290,19 +309,23 @@ indicators are called \fIindex\fRes and may be specified in any of the following forms: .TP 12 \fBactive\fR +. Indicates the entry that is currently active. If no entry is active then this form is equivalent to \fBnone\fR. This form may not be abbreviated. .TP 12 \fBend\fR +. Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to \fBnone\fR. This form may not be abbreviated. .TP 12 \fBlast\fR +. Same as \fBend\fR. .TP 12 \fBnone\fR +. Indicates .QW "no entry at all" ; this is used most commonly with @@ -312,6 +335,7 @@ nothing to happen in the widget command. This form may not be abbreviated. .TP 12 \fB@\fInumber\fR +. In this form, \fInumber\fR is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used. For example, @@ -319,15 +343,17 @@ For example, indicates the top-most entry in the window. .TP 12 \fInumber\fR +. Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. .TP 12 \fIpattern\fR +. If the index does not satisfy one of the above forms then this form is used. \fIPattern\fR is pattern-matched against the label of each entry in the menu, in order from the top down, until a -matching entry is found. The rules of \fBTcl_StringMatch\fR +matching entry is found. The rules of \fBstring match\fR are used. .PP If the index could match more than one of the above forms, then @@ -336,6 +362,7 @@ the form earlier in the above list takes precedence. The following widget commands are possible for menu widgets: .TP \fIpathName \fBactivate \fIindex\fR +. Change the state of the entry indicated by \fIindex\fR to \fBactive\fR and redisplay it using its active colors. Any previously-active entry is deactivated. If \fIindex\fR @@ -344,44 +371,185 @@ disabled, then the menu ends up with no active entry. Returns an empty string. .TP \fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR? +. Add a new entry to the bottom of the menu. The new entry's type is given by \fItype\fR and must be one of \fBcascade\fR, \fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, or a unique abbreviation of one of the above. If additional arguments -are present, they specify any of the following options: -.RS +are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR +section below. +The \fBadd\fR widget command returns an empty string. +.TP +\fIpathName \fBcget \fIoption\fR +. +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBmenu\fR +command. +.TP +\fIpathName \fBclone \fInewPathname\fR ?\fIcloneType\fR? +. +Makes a clone of the current menu named \fInewPathName\fR. This clone +is a menu in its own right, but any changes to the clone are +propagated to the original menu and vice versa. \fIcloneType\fR can be +\fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be +called outside of the Tk library. See the \fBCLONES\fR section for +more information. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). If +one or more \fIoption\-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \fBmenu\fR +command. +.TP +\fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? +. +Delete all of the menu entries between \fIindex1\fR and +\fIindex2\fR inclusive. +If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. +Attempts to delete a tear-off menu entry are ignored (instead, you +should change the \fB\-tearoff\fR option to remove the tear-off entry). +.TP +\fIpathName \fBentrycget \fIindex option\fR +. +Returns the current value of a configuration option for +the entry given by \fIindex\fR. +\fIOption\fR may have any of the names described in the +\fBMENU ENTRY OPTIONS\fR section below. +.TP +\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions...\fR? +. +This command is similar to the \fBconfigure\fR command, except that +it applies to the options for an individual entry, whereas \fBconfigure\fR +applies to the options for the menu as a whole. +\fIOptions\fR may have any of the values described in the +\fBMENU ENTRY OPTIONS\fR +section below. If \fIoptions\fR are specified, options are +modified as indicated in the command and the command returns an empty string. +If no \fIoptions\fR are specified, returns a list describing +the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). +.TP +\fIpathName \fBindex \fIindex\fR +. +Returns the numerical index corresponding to \fIindex\fR, or +\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. +.TP +\fIpathName \fBinsert \fIindex type \fR?\fIoption value option value ...\fR? +. +Same as the \fBadd\fR widget command except that it inserts the new +entry just before the entry given by \fIindex\fR, instead of appending +to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR +arguments have the same interpretation as for the \fBadd\fR widget +command. It is not possible to insert new menu entries before the +tear-off entry, if the menu has one. +.TP +\fIpathName \fBinvoke \fIindex\fR +. +Invoke the action of the menu entry. See the sections on the +individual entries above for details on what happens. If the +menu entry is disabled then nothing happens. If the +entry has a command associated with it then the result of that +command is returned as the result of the \fBinvoke\fR widget +command. Otherwise the result is an empty string. Note: invoking +a menu entry does not automatically unpost the menu; the default +bindings normally take care of this before invoking the \fBinvoke\fR +widget command. +.TP +\fIpathName \fBpost \fIx y\fR +. +Arrange for the menu to be displayed on the screen at the root-window +coordinates given by \fIx\fR and \fIy\fR. These coordinates are +adjusted if necessary to guarantee that the entire menu is visible on +the screen. This command normally returns an empty string. +If the \fB\-postcommand\fR option has been specified, then its value is +executed as a Tcl script before posting the menu and the result of +that script is returned as the result of the \fBpost\fR widget +command. +If an error returns while executing the command, then the error is +returned without posting the menu. +.TP +\fIpathName \fBpostcascade \fIindex\fR +. +Posts the submenu associated with the cascade entry given by +\fIindex\fR, and unposts any previously posted submenu. +If \fIindex\fR does not correspond to a cascade entry, +or if \fIpathName\fR is not posted, +the command has no effect except to unpost any currently posted +submenu. +.TP +\fIpathName \fBtype \fIindex\fR +. +Returns the type of the menu entry given by \fIindex\fR. +This is the \fItype\fR argument passed to the \fBadd\fR or \fBinsert\fR widget +command when the entry was created, such as \fBcommand\fR +or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. +.TP +\fIpathName \fBunpost\fR +. +Unmap the window so that it is no longer displayed. If a +lower-level cascaded menu is posted, unpost that menu. Returns an +empty string. This subcommand does not work on Windows and the +Macintosh, as those platforms have their own way of unposting menus. +.TP +\fIpathName \fBxposition \fIindex\fR +. +Returns a decimal string giving the x-coordinate within the menu +window of the leftmost pixel in the entry specified by \fIindex\fR. +.TP +\fIpathName \fByposition \fIindex\fR +. +Returns a decimal string giving the y-coordinate within the menu +window of the topmost pixel in the entry specified by \fIindex\fR. +.SH "MENU ENTRY OPTIONS" +The following options are allowed on menu entries. Most options are not +supported by all entry types. .TP \fB\-activebackground \fIvalue\fR +. Specifies a background color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the -\fBactiveBackground\fR option for the overall menu is used. +\fB\-activebackground\fR option for the overall menu is used. If the \fBtk_strictMotif\fR variable has been set to request strict Motif compliance, then this option is ignored and the \fB\-background\fR option is used in its place. This option is not available for separator or tear-off entries. .TP \fB\-activeforeground \fIvalue\fR +. Specifies a foreground color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the -\fBactiveForeground\fR option for the overall menu is used. +\fB\-activeforeground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .TP \fB\-accelerator \fIvalue\fR +. Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be typed to invoke the same function as the menu entry. This option is not available for separator or tear-off entries. .TP \fB\-background \fIvalue\fR +. Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the -\fBbackground\fR option for the overall menu is used. +\fB\-background\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .TP \fB\-bitmap \fIvalue\fR +. Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by \fBTk_GetBitmap\fR. This option overrides the \fB\-label\fR option @@ -393,15 +561,20 @@ 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 +. When this option is zero, the entry appears below the previous entry. When this option is one, the entry appears at the top of a new column in the menu. +This option is ignored on Aqua/Mac OS X, where menus are always a single +column. .TP \fB\-command \fIvalue\fR +. Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. .TP \fB\-compound \fIvalue\fR +. Specifies whether the menu entry should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are \fBbottom\fR, \fBcenter\fR, @@ -411,26 +584,30 @@ text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR options. .TP \fB\-font \fIvalue\fR +. Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then -the \fBfont\fR option for the overall menu is used. +the \fB\-font\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .TP \fB\-foreground \fIvalue\fR +. Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the -\fBforeground\fR option for the overall menu is used. +\fB\-foreground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .TP \fB\-hidemargin \fIvalue\fR +. Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used. .TP \fB\-image \fIvalue\fR +. Specifies an image to display in the menu instead of a text string or bitmap. The image must have been created by some previous invocation of @@ -442,36 +619,43 @@ bitmap label to be displayed. This option is not available for separator or tear-off entries. .TP \fB\-indicatoron \fIvalue\fR +. Available only for checkbutton and radiobutton entries. \fIValue\fR is a boolean that determines whether or not the indicator should be displayed. .TP \fB\-label \fIvalue\fR +. Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries. .TP \fB\-menu \fIvalue\fR +. Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu. .TP \fB\-offvalue \fIvalue\fR +. Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected. .TP \fB\-onvalue \fIvalue\fR +. Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. .TP \fB\-selectcolor \fIvalue\fR +. Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. -If the value is an empty string (the default) then the \fBselectColor\fR +If the value is an empty string (the default) then the \fB\-selectcolor\fR option for the menu determines the indicator color. .TP \fB\-selectimage \fIvalue\fR +. Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the \fB\-image\fR option) when it is selected. @@ -481,22 +665,24 @@ This option is ignored unless the \fB\-image\fR option has been specified. .TP \fB\-state \fIvalue\fR +. Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the entry is displayed using the -\fBforeground\fR option for the menu and the \fBbackground\fR +\fB\-foreground\fR option for the menu and the \fB\-background\fR option from the entry or the menu. The active state is typically used when the pointer is over the entry. -In active state the entry is displayed using the \fBactiveForeground\fR -option for the menu along with the \fBactivebackground\fR option from +In active state the entry is displayed using the \fB\-activeforeground\fR +option for the menu along with the \fB\-activebackground\fR option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the -\fBdisabledForeground\fR option for the menu and the -\fBbackground\fR option from the entry. +\fB\-disabledforeground\fR option for the menu and the +\fB\-background\fR option from the entry. This option is not available for separator entries. .TP \fB\-underline \fIvalue\fR +. Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. @@ -506,143 +692,32 @@ If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries. .TP \fB\-value \fIvalue\fR +. Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the \fB\-label\fR option for the entry as the value to store in the variable. .TP \fB\-variable \fIvalue\fR +. Available only for checkbutton and radiobutton entries. Specifies the name of a global variable to set when the entry is selected. For checkbutton entries the variable is also set when the entry is deselected. For radiobutton entries, changing the variable causes the currently-selected entry to deselect itself. -.LP -The \fBadd\fR widget command returns an empty string. +.RS +.PP +For checkbutton entries, the default value of this option is taken from the +\fB\-label\fR option, and for radiobutton entries a single fixed value is +used. It is recommended that you always set the \fB\-variable\fR option when +creating either a checkbutton or a radiobutton. .RE -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBmenu\fR -command. -.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 -propagated to the original menu and vice versa. \fIcloneType\fR can be -\fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be -called outside of the Tk library. See the \fBCLONES\fR section for -more information. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBmenu\fR -command. -.TP -\fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? -Delete all of the menu entries between \fIindex1\fR and -\fIindex2\fR inclusive. -If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. -Attempts to delete a tear-off menu entry are ignored (instead, you -should change the \fBtearOff\fR option to remove the tear-off entry). -.TP -\fIpathName \fBentrycget\fR \fIindex option\fR -Returns the current value of a configuration option for -the entry given by \fIindex\fR. -\fIOption\fR may have any of the values accepted by the \fBadd\fR -widget command. -.TP -\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions\fR? -This command is similar to the \fBconfigure\fR command, except that -it applies to the options for an individual entry, whereas \fBconfigure\fR -applies to the options for the menu as a whole. -\fIOptions\fR may have any of the values accepted by the \fBadd\fR -widget command. If \fIoptions\fR are specified, options are modified -as indicated -in the command and the command returns an empty string. -If no \fIoptions\fR are specified, returns a list describing -the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). -.TP -\fIpathName \fBindex \fIindex\fR -Returns the numerical index corresponding to \fIindex\fR, or -\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. -.TP -\fIpathName \fBinsert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR? -Same as the \fBadd\fR widget command except that it inserts the new -entry just before the entry given by \fIindex\fR, instead of appending -to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR -arguments have the same interpretation as for the \fBadd\fR widget -command. It is not possible to insert new menu entries before the -tear-off entry, if the menu has one. -.TP -\fIpathName \fBinvoke \fIindex\fR -Invoke the action of the menu entry. See the sections on the -individual entries above for details on what happens. If the -menu entry is disabled then nothing happens. If the -entry has a command associated with it then the result of that -command is returned as the result of the \fBinvoke\fR widget -command. Otherwise the result is an empty string. Note: invoking -a menu entry does not automatically unpost the menu; the default -bindings normally take care of this before invoking the \fBinvoke\fR -widget command. -.TP -\fIpathName \fBpost \fIx y\fR -Arrange for the menu to be displayed on the screen at the root-window -coordinates given by \fIx\fR and \fIy\fR. These coordinates are -adjusted if necessary to guarantee that the entire menu is visible on -the screen. This command normally returns an empty string. -If the \fBpostCommand\fR option has been specified, then its value is -executed as a Tcl script before posting the menu and the result of -that script is returned as the result of the \fBpost\fR widget -command. -If an error returns while executing the command, then the error is -returned without posting the menu. -.TP -\fIpathName \fBpostcascade \fIindex\fR -Posts the submenu associated with the cascade entry given by -\fIindex\fR, and unposts any previously posted submenu. -If \fIindex\fR does not correspond to a cascade entry, -or if \fIpathName\fR is not posted, -the command has no effect except to unpost any currently posted -submenu. -.TP -\fIpathName \fBtype \fIindex\fR -Returns the type of the menu entry given by \fIindex\fR. -This is the \fItype\fR argument passed to the \fBadd\fR widget -command when the entry was created, such as \fBcommand\fR -or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. -.TP -\fIpathName \fBunpost\fR -Unmap the window so that it is no longer displayed. If a -lower-level cascaded menu is posted, unpost that menu. Returns an -empty string. This subcommand does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. -.TP -\fIpathName \fBxposition \fIindex\fR -.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: .TP \fBPulldown Menus in Menubar\fR +. This is the most common case. You create a menu widget that will become the menu bar. You then add cascade entries to this menu, specifying the pull down menus you wish to use in your menu bar. You then create all @@ -651,6 +726,7 @@ of the pulldowns. Once you have done this, specify the menu using the \fBtoplevel\fR manual entry for details. .TP \fBPulldown Menus in Menu Buttons\fR +. This is the compatible way to do menu bars. You create one menubutton widget for each top-level menu, and typically you arrange a series of menubuttons in a row in a menubar window. You also create the top-level menus @@ -662,12 +738,14 @@ will allow users to traverse and invoke the tree of menus via its menubutton; see the \fBmenubutton\fR manual entry for details. .TP \fBPopup Menus\fR +. Popup menus typically post in response to a mouse button press or keystroke. You create the popup menus and any cascaded submenus, then you call the \fBtk_popup\fR procedure at the appropriate time to post the top-level menu. .TP \fBOption Menus\fR +. An option menu consists of a menubutton with an associated menu that allows you to select one of several values. The current value is displayed in the menubutton and is also stored in a global @@ -675,6 +753,7 @@ variable. Use the \fBtk_optionMenu\fR procedure to create option menubuttons and their menus. .TP \fBTorn-off Menus\fR +. You create a torn-off menu by invoking the tear-off entry at the top of an existing menu. The default bindings will create a new menu that is a copy of the original menu and leave it permanently @@ -749,3 +828,6 @@ entries. bind(n), menubutton(n), ttk::menubutton(n), toplevel(n) .SH KEYWORDS menu, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/menubar.n b/doc/menubar.n index b80a6e1..023bf37 100644 --- a/doc/menubar.n +++ b/doc/menubar.n @@ -16,7 +16,6 @@ tk_menuBar, tk_bindForTraversal \- Obsolete support for menu bars .sp \fBtk_bindForTraversal \fIarg arg ... \fR .BE - .SH DESCRIPTION .PP These procedures were used in Tk 3.6 and earlier releases to help @@ -30,9 +29,10 @@ procedures will go away. From Tk 8.0 onwards, you should instead construct your menubar as a normal \fBmenu\fR and then attach it to the \fBtoplevel\fR of your choice using the \fB\-menu\fR option of that widget. - .SH "SEE ALSO" menu(n), toplevel(n) - .SH KEYWORDS keyboard traversal, menu, menu bar, post +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/menubutton.n b/doc/menubutton.n index 3680abc..08b52a0 100644 --- a/doc/menubutton.n +++ b/doc/menubutton.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -menubutton \- Create and manipulate menubutton widgets +menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets .SH SYNOPSIS \fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -53,12 +53,12 @@ Specifies one of three states for the menubutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the menubutton is displayed using the \fBforeground\fR and \fBbackground\fR options. The active state is typically used when the pointer is over the menubutton. In active state -the menubutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the menubutton +the menubutton is displayed using the \fB\-activeforeground\fR and +\fB\-activebackground\fR options. Disabled state means that the menubutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the button is displayed. +In this state the \fB\-disabledforeground\fR and +\fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in @@ -84,22 +84,28 @@ A menubutton is a widget that displays a textual string, bitmap, or image and is associated with a menu widget. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and +or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the -\fBunderline\fR option. In normal usage, pressing +\fB\-underline\fR option. In normal usage, pressing mouse button 1 over the menubutton causes the associated menu to be posted just underneath the menubutton. If the mouse is moved over the menu before releasing the mouse button, the button release causes the underlying menu entry to be invoked. When the button is released, the menu is unposted. .PP -Menubuttons are typically organized into groups called menu bars +Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the +preferred mechanism for allowing a user to select one item from a list +on Mac OS X. +.PP +Menubuttons were also typically organized into groups called menu bars that allow scanning: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead. +\fIThis use is deprecated\fR in favor of setting a \fBmenu\fR directly as a +menubar; see the \fBtoplevel\fR's \fB\-menu\fR option for how to do that. .PP There are several interactions between menubuttons and menus; see the \fBmenu\fR manual entry for information on various menu configurations, @@ -117,13 +123,15 @@ operations on the widget. It has the following general form: determine the exact behavior of the command. The following commands are possible for menubutton widgets: .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -168,7 +176,7 @@ When a menubutton is posted, its associated menu claims the input focus to allow keyboard traversal of the menu and its submenus. See the \fBmenu\fR manual entry for details on these bindings. .IP [7] -If the \fBunderline\fR option has been specified for a menubutton +If the \fB\-underline\fR option has been specified for a menubutton then keyboard traversal may be used to post the menubutton: Alt+\fIx\fR, where \fIx\fR is the underlined character (or its lower-case or upper-case equivalent), may be typed in any window @@ -189,3 +197,6 @@ individual widgets or by redefining the class bindings. ttk::menubutton(n), menu(n) .SH KEYWORDS menubutton, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/message.n b/doc/message.n index 926f0cb..bd635ac 100644 --- a/doc/message.n +++ b/doc/message.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -message \- Create and manipulate message widgets +message \- Create and manipulate 'message' non-interactive text widgets .SH SYNOPSIS \fBmessage\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -28,37 +28,37 @@ aspect ratio for the text. The aspect ratio is specified as 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 +Used to choose line length for text if \fB\-width\fR option is not specified. Defaults to 150. .OP \-justify justify Justify Specifies how to justify lines of text. Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. Defaults to \fBleft\fR. -This option works together with the \fBanchor\fR, \fBaspect\fR, -\fBpadX\fR, \fBpadY\fR, and \fBwidth\fR options to provide a variety +This option works together with the \fB\-anchor\fR, \fB\-aspect\fR, +\fB\-padx\fR, \fB\-pady\fR, and \fB\-width\fR options to provide a variety of arrangements of the text within the window. -The \fBaspect\fR and \fBwidth\fR options determine the amount of +The \fB\-aspect\fR and \fB\-width\fR options determine the amount of screen space needed to display the text. -The \fBanchor\fR, \fBpadX\fR, and \fBpadY\fR options determine where this +The \fB\-anchor\fR, \fB\-padx\fR, and \fB\-pady\fR options determine where this rectangular area is displayed within the widget's window, and the -\fBjustify\fR option determines how each line is displayed within that +\fB\-justify\fR option determines how each line is displayed within that rectangular region. -For example, suppose \fBanchor\fR is \fBe\fR and \fBjustify\fR is +For example, suppose \fB\-anchor\fR is \fBe\fR and \fB\-justify\fR is \fBleft\fR, and that the message window is much larger than needed for the text. The text will be displayed so that the left edges of all the lines -line up and the right edge of the longest line is \fBpadX\fR from +line up and the right edge of the longest line is \fB\-padx\fR from the right side of the window; the entire text block will be centered in the vertical span of the window. .OP \-width width Width Specifies the length of lines in the window. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If this option has a value greater than zero then the \fBaspect\fR -option is ignored and the \fBwidth\fR option determines the line +If this option has a value greater than zero then the \fB\-aspect\fR +option is ignored and the \fB\-width\fR option determines the line length. If this option has a value less than or equal to zero, then -the \fBaspect\fR option determines the line length. +the \fB\-aspect\fR option determines the line length. .BE .SH DESCRIPTION .PP @@ -74,7 +74,8 @@ there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A message is a widget that displays a textual string. A message -widget has three special features. First, it breaks up +widget has three special features that differentiate it from a +\fBlabel\fR widget. First, it breaks up its string into lines in order to produce a given aspect ratio for the window. The line breaks are chosen at word boundaries wherever possible (if not even a single word would fit on a @@ -111,13 +112,15 @@ operations on the widget. It has the following general form: determine the exact behavior of the command. The following commands are possible for message widgets: .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -142,3 +145,6 @@ The most common result is that the line is justified wrong. label(n) .SH KEYWORDS message, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/option.n b/doc/option.n index dd1a644..8699c0d 100644 --- a/doc/option.n +++ b/doc/option.n @@ -26,8 +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 (see \fBPATTERN -FORMAT\fR). \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,22 +63,18 @@ The \fIpriority\fR arguments to the \fBoption\fR command are normally specified symbolically using one of the following values: .TP \fBwidgetDefault\fR -. Level 20. Used for default values hard-coded into widgets. .TP \fBstartupFile\fR -. Level 40. Used for options specified in application-specific startup files. .TP \fBuserDefault\fR -. Level 60. Used for options specified in user-specific defaults files, such as \fB.Xdefaults\fR, resource databases loaded into the X server, or user-specific startup files. .TP \fBinteractive\fR -. Level 80. Used for options specified interactively after the application starts running. If \fIpriority\fR is not specified, it defaults to this level. @@ -113,8 +109,10 @@ first word of the pattern is matched against the name and class of the .QW \fB.\fR \fBtoplevel\fR, which are usually set by options to \fBwish\fR. .SH EXAMPLES +.PP Instruct every button in the application to have red text on it unless -explicitly overridden (note that on some platforms the option is ignored): +explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR +class (note that on some platforms the option is ignored): .CS \fBoption add\fR *Button.foreground red startupFile .CE diff --git a/doc/optionMenu.n b/doc/optionMenu.n index db2c109..42275ce 100644 --- a/doc/optionMenu.n +++ b/doc/optionMenu.n @@ -33,9 +33,13 @@ The return value from \fBtk_optionMenu\fR is the name of the menu associated with \fIpathName\fR, so that the caller can change its configuration options or manipulate it in other ways. .SH EXAMPLE +.PP .CS tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble pack .foo .CE .SH KEYWORDS option menu +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/options.n b/doc/options.n index 2faca8c..36937b1 100644 --- a/doc/options.n +++ b/doc/options.n @@ -12,8 +12,8 @@ .SH NAME options \- Standard options supported by widgets .BE - .SH DESCRIPTION +.PP This manual entry describes the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every option (see the manual entries for individual widgets for a list @@ -72,18 +72,18 @@ widget. Specifies a bitmap to display in the widget, in any of the forms acceptable to \fBTk_GetBitmap\fR. The exact way in which the bitmap is displayed may be affected by -other options such as \fBanchor\fR or \fBjustify\fR. +other options such as \fB\-anchor\fR or \fB\-justify\fR. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget -but this is controlled by the \fBcompound\fR option; -the \fBbitmap\fR option may be reset to an empty string to re-enable +but this is controlled by the \fB\-compound\fR option; +the \fB\-bitmap\fR option may be reset to an empty string to re-enable a text display. -In widgets that support both \fBbitmap\fR and \fBimage\fR options, -\fBimage\fR will usually override \fBbitmap\fR. +In widgets that support both \fB\-bitmap\fR and \fB\-image\fR options, +\fB\-image\fR will usually override \fB\-bitmap\fR. .OP "\-borderwidth or \-bd" borderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a -border is being drawn; the \fBrelief\fR option typically determines +border is being drawn; the \fB\-relief\fR option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. @@ -139,10 +139,10 @@ If the value is zero, no focus highlight is drawn around the widget. .OP \-image image Image Specifies an image to display in the widget, which must have been created with the \fBimage create\fR command. -Typically, if the \fBimage\fR option is specified then it overrides other +Typically, if the \fB\-image\fR option is specified then it overrides other options that specify a bitmap or textual value to display in the -widget, though this is controlled by the \fBcompound\fR option; -the \fBimage\fR option may be reset to an empty string to re-enable +widget, though this is controlled by the \fB\-compound\fR option; +the \fB\-image\fR option may be reset to an empty string to re-enable a bitmap or text display. .OP \-insertbackground insertBackground Foreground Specifies the color to use as background in the area covered by the @@ -169,8 +169,8 @@ in each blink cycle. Specifies a value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If a border has been specified for the insertion -cursor (using the \fBinsertBorderWidth\fR option), the border -will be drawn inside the width specified by the \fBinsertWidth\fR +cursor (using the \fB\-insertborderwidth\fR option), the border +will be drawn inside the width specified by the \fB\-insertwidth\fR option. .OP \-jump jump Jump For widgets with a slider that can be dragged to adjust a value, @@ -235,7 +235,7 @@ Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. .OP \-repeatinterval repeatInterval RepeatInterval -Used in conjunction with \fBrepeatDelay\fR: once auto-repeat +Used in conjunction with \fB\-repeatdelay\fR: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats. .OP \-selectbackground selectBackground Foreground @@ -255,7 +255,7 @@ This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. -If the \fBsetGrid\fR option is set to true then the widget will +If the \fB\-setgrid\fR option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window @@ -266,7 +266,7 @@ entry for more details. Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts -consult the value of the \fBtakeFocus\fR option. +consult the value of the \fB\-takefocus\fR option. A value of \fB0\fR means that the window should be skipped entirely during keyboard traversal. \fB1\fR means that the window should receive the input @@ -289,14 +289,14 @@ redefine the keyboard traversal scripts. .OP \-text text Text Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be -determined by other options, such as \fBanchor\fR or \fBjustify\fR. +determined by other options, such as \fB\-anchor\fR or \fB\-justify\fR. .OP \-textvariable textVariable Variable Specifies the name of a global variable. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as -\fBanchor\fR or \fBjustify\fR. +\fB\-anchor\fR or \fB\-justify\fR. .OP \-troughcolor troughColor Background Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales. This option is ignored for @@ -334,7 +334,7 @@ that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. The command is then passed to the Tcl interpreter for execution. Typically the -\fBxScrollCommand\fR option consists of the path name of a scrollbar +\fB\-xscrollcommand\fR option consists of the path name of a scrollbar widget followed by .QW set , e.g. @@ -345,13 +345,14 @@ If this option is not specified, then no command will be executed. .OP \-yscrollcommand yScrollCommand ScrollCommand Specifies the prefix for a command used to communicate with vertical scrollbars. This option is treated in the same way as the -\fBxScrollCommand\fR option, except that it is used for vertical +\fB\-xscrollcommand\fR option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. -See the description of \fBxScrollCommand\fR for details +See the description of \fB\-xscrollcommand\fR for details on how this option is used. - .SH "SEE ALSO" colors, cursors, font - .SH KEYWORDS class, name, standard option, switch +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/pack-old.n b/doc/pack-old.n index f29c454..217dba9 100644 --- a/doc/pack-old.n +++ b/doc/pack-old.n @@ -20,7 +20,6 @@ pack-old \- Obsolete syntax for packer geometry manager .sp \fBpack unpack \fIwindow\fR .BE - .SH DESCRIPTION .PP \fINote: this manual entry describes the syntax for the \fBpack\fI @@ -189,6 +188,8 @@ The packer makes geometry requests on behalf of the parent windows it manages. For each parent window it requests a size large enough to accommodate all the options specified by all the packed children, such that zero space would be leftover for \fBexpand\fR options. - .SH KEYWORDS geometry manager, location, packer, parcel, size +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -14,7 +14,6 @@ pack \- Geometry manager that packs around edges of cavity .SH SYNOPSIS \fBpack \fIoption arg \fR?\fIarg ...\fR? .BE - .SH DESCRIPTION .PP The \fBpack\fR command is used to communicate with the packer, @@ -259,6 +258,7 @@ will be highest in the stacking order. Or, you can use the \fBraise\fR and \fBlower\fR commands to change the stacking order of either the master or the slave. .SH EXAMPLE +.PP .CS # Make the widgets label .t \-text "This widget is at the top" \-bg red @@ -274,9 +274,10 @@ text .mid \fBpack\fR .r \-side right \-fill y \fBpack\fR .mid \-expand 1 \-fill both .CE - .SH "SEE ALSO" grid(n), place(n) - .SH KEYWORDS geometry manager, location, packer, parcel, propagation, size +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/palette.n b/doc/palette.n index 27a6460..085c4c6 100644 --- a/doc/palette.n +++ b/doc/palette.n @@ -17,7 +17,6 @@ tk_setPalette, tk_bisque \- Modify the Tk color palette .sp \fBtk_bisque\fR .BE - .SH DESCRIPTION .PP The \fBtk_setPalette\fR procedure changes the color scheme for Tk. @@ -67,6 +66,8 @@ The procedure \fBtk_bisque\fR is provided for backward compatibility: it restores the application's colors to the light brown .PQ bisque color scheme used in Tk 3.6 and earlier versions. - .SH KEYWORDS bisque, color, palette +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/panedwindow.n b/doc/panedwindow.n index 33e1e12..e2c954a 100644 --- a/doc/panedwindow.n +++ b/doc/panedwindow.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -panedwindow \- Create and manipulate panedwindow widgets +panedwindow \- Create and manipulate 'panedwindow' split container widgets .SH SYNOPSIS \fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -91,7 +91,8 @@ the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for panedwindow widgets: .TP -\fIpathName \fBadd \fIwindow ?window ...? ?option value ...?\fR +\fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? +. Add one or more windows to the panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. @@ -99,11 +100,13 @@ followed by pairs of arguments that specify how to manage the windows. \fBconfigure\fR subcommand. .TP \fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .TP -\fIpathName \fBconfigure \fI?option? ?value option value ...?\fR +\fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -116,11 +119,13 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .TP -\fIpathName \fBforget \fIwindow ?window ...?\fR +\fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? +. Remove the pane containing \fIwindow\fR from the panedwindow. All geometry management options for \fIwindow\fR will be forgotten. .TP \fIpathName \fBidentify \fIx y\fR +. Identify the panedwindow component underneath the point given by \fIx\fR and \fIy\fR, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the @@ -128,53 +133,63 @@ index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. .TP -\fIpathName \fBproxy \fI?args?\fR +\fIpathName \fBproxy \fR?\fIargs\fR? +. This command is used to query and change the position of the sash proxy, used for rubberband-style pane resizing. It can take any of the following forms: .RS .TP \fIpathName \fBproxy coord\fR +. Return a list containing the x and y coordinates of the most recent proxy location. .TP \fIpathName \fBproxy forget\fR +. Remove the proxy from the display. .TP \fIpathName \fBproxy place \fIx y\fR +. Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE .TP -\fIpathName \fBsash \fI?args?\fR +\fIpathName \fBsash \fR?\fIargs\fR? This command is used to query and change the position of sashes in the panedwindow. It can take any of the following forms: .RS .TP \fIpathName \fBsash coord \fIindex\fR +. Return the current x and y coordinate pair for the sash given by \fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than the number of panes in the panedwindow. The coordinates given are those of the top left corner of the region containing the sash. .TP \fIpathName \fBsash dragto \fIindex x y\fR +. This command computes the difference between the given coordinates and the coordinates given to the last \fBsash mark\fR command for the given sash. It then moves that sash the computed difference. The return value is the empty string. .TP \fIpathName \fBsash mark \fIindex x y\fR +. Records \fIx\fR and \fIy\fR for the sash given by \fIindex\fR; used in conjunction with later \fBsash dragto\fR commands to move the sash. .TP \fIpathName \fBsash place \fIindex x y\fR +. Place the sash given by \fIindex\fR at the given coordinates. .RE .TP \fIpathName \fBpanecget \fIwindow option\fR +. Query a management option for \fIwindow\fR. \fIOption\fR may be any value allowed by the \fBpaneconfigure\fR subcommand. .TP -\fIpathName \fBpaneconfigure \fIwindow ?option? ?value option value ...?\fR +\fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the management options for \fIwindow\fR. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -189,14 +204,17 @@ are supported: .RS .TP \fB\-after \fIwindow\fR +. Insert the window after the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .TP \fB\-before \fIwindow\fR +. Insert the window before the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .TP \fB\-height \fIsize\fR +. Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-height\fR is not specified, then the @@ -205,13 +223,13 @@ 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 \(em the x dimension for horizontal panedwindows, the y @@ -219,16 +237,19 @@ dimension for vertical panedwindows. May be any value accepted by \fBTk_GetPixels\fR. .TP \fB\-padx \fIn\fR +. Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .TP \fB\-pady \fIn\fR +. Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .TP \fB\-sticky \fIstyle\fR +. If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. \fIStyle\fR is a string that contains zero or more @@ -242,7 +263,7 @@ 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. @@ -254,25 +275,30 @@ 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 +. +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 +. +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 is an empty string, or if \fB\-width\fR is not specified, then the @@ -282,8 +308,10 @@ panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .RE .TP \fIpathName \fBpanes\fR +. Returns an ordered list of the widgets managed by \fIpathName\fR. .SH "RESIZING PANES" +.PP A pane is resized by grabbing the sash (or sash handle if present) and dragging with the mouse. This is accomplished via mouse motion bindings on the widget. When a sash is moved, the sizes of the panes @@ -306,3 +334,6 @@ values, etc.). ttk::panedwindow(n) .SH KEYWORDS panedwindow, widget, geometry management +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/photo.n b/doc/photo.n index dc30f08..0fe0c61 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -16,9 +16,22 @@ .SH NAME photo \- Full-color images .SH SYNOPSIS +.nf \fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? -.BE +\fIimageName \fBblank\fR +\fIimageName \fBcget \fIoption\fR +\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +\fIimageName \fBcopy \fIsourceImage\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBget \fIx y\fR +\fIimageName \fBput \fIdata\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBread \fIfilename\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBredither\fR +\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? +\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? +.fi +.BE .SH DESCRIPTION .PP A photo is an image whose pixels can display any color or be @@ -26,7 +39,11 @@ transparent. A photo image is stored internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from -C code through a procedural interface. At present, only GIF and PPM/PGM +C code through a procedural interface. At present, only +.VS 8.6 +PNG, +.VE 8.6 +GIF and PPM/PGM formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is transparent in regions where no image data has been supplied @@ -39,24 +56,29 @@ command. Photos support the following \fIoptions\fR: .TP \fB\-data \fIstring\fR +. Specifies the contents of the image as a string. The string should contain binary data or, for some formats, base64-encoded data (this is -currently guaranteed to be supported for GIF images). The format of the +currently guaranteed to be supported for PNG and GIF images). The +format of the string must be one of those for which there is an image file format handler that will accept string data. If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-file\fR option takes precedence. .TP \fB\-format \fIformat-name\fR +. Specifies the name of the file format for the data specified with the \fB\-data\fR or \fB\-file\fR option. .TP \fB\-file \fIname\fR +. \fIname\fR gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data. .TP \fB\-gamma \fIvalue\fR +. Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most @@ -68,12 +90,14 @@ will make the image lighter, and values less than one will make it darker. .TP \fB\-height \fInumber\fR +. Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it. .TP \fB\-palette \fIpalette-spec\fR +. Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The @@ -85,6 +109,7 @@ number) is used, the image will be displayed in monochrome (i.e., grayscale). .TP \fB\-width \fInumber\fR +. Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the @@ -112,17 +137,20 @@ changed. The following commands are possible for photo images: .TP \fIimageName \fBblank\fR +. Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. .TP \fIimageName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the -\fBimage create photo\fR command. +\fBimage create\fR \fBphoto\fR command. .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for @@ -134,9 +162,10 @@ one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the -\fBimage create photo\fR command. +\fBimage create\fR \fBphoto\fR command. .TP \fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? +. Copies a region from the image called \fIsourceImage\fR (which must be a photo image) to the image called \fIimageName\fR, possibly with pixel zooming and/or subsampling. If no options are specified, this @@ -146,6 +175,7 @@ options may be specified: .RS .TP \fB\-from \fIx1 y1 x2 y2\fR +. Specifies a rectangular sub-region of the source image to be copied. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the @@ -155,6 +185,7 @@ rectangle but not the bottom or right edges. If the \fB\-from\fR option is not given, the default is the whole source image. .TP \fB\-to \fIx1 y1 x2 y2\fR +. Specifies a rectangular sub-region of the destination image to be affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, @@ -164,6 +195,7 @@ region (after subsampling and zooming, if specified). If \fIx2\fR and necessary to fill the destination region in a tiled fashion. .TP \fB\-shrink\fR +. Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height @@ -171,6 +203,7 @@ of the image if the user has specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .TP \fB\-zoom \fIx y\fR +. Specifies that the source region should be magnified by a factor of \fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR is not given, the default value is the same as \fIx\fR. With this @@ -179,6 +212,7 @@ of \fIx\fR x \fIy\fR pixels in the destination image, all the same color. \fIx\fR and \fIy\fR must be greater than 0. .TP \fB\-subsample \fIx y\fR +. Specifies that the source image should be reduced in size by using only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in the Y direction. Negative values will cause the image to be flipped @@ -186,6 +220,7 @@ about the Y or X axes, respectively. If \fIy\fR is not given, the default value is the same as \fIx\fR. .TP \fB\-compositingrule \fIrule\fR +. Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of \fIoverlay\fR is set, the old contents of the destination image are visible, as if the @@ -196,17 +231,20 @@ the source image is used as-is. The default compositing rule is \fIoverlay\fR. .RE .TP -\fIimageName \fBdata ?\fIoption value(s) ...\fR? +\fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? +. Returns image data in the form of a string. The following options may be specified: .RS .TP \fB\-background\fI color\fR +. If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .TP \fB\-format\fI format-name\fR +. Specifies the name of the image file format handler to be used. Specifically, this subcommand searches for the first handler whose name matches an initial substring of @@ -220,6 +258,7 @@ format (where \fIrr\fR is a pair of hexadecimal digits for the red channel, \fIgg\fR for green, and \fIbb\fR for blue). .TP \fB\-from \fIx1 y1 x2 y2\fR +. Specifies a rectangular region of \fIimageName\fR to be returned. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of @@ -229,16 +268,19 @@ and excluding x2,y2. The default, if this option is not given, is the whole image. .TP \fB\-grayscale\fR +. If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .RE .TP \fIimageName \fBget\fR \fIx y\fR +. Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively. .TP \fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR? +. Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. This command first searches the list of image file format handlers for a handler that can interpret the data in \fIdata\fR, and then reads @@ -253,12 +295,14 @@ that color. The following options may be specified: .RS .TP \fB\-format \fIformat-name\fR +. Specifies the format of the image data in \fIdata\fR. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? +. Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR) of the region of \fIimageName\fR into which the image data will be copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given @@ -270,6 +314,7 @@ represented by (\fIx2\fR,\fIy2\fR) will be filled with that color. .RE .TP \fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? +. Reads image data from the file named \fIfilename\fR into the image. This command first searches the list of image file format handlers for a handler that can interpret the data @@ -279,12 +324,14 @@ specified: .RS .TP \fB\-format \fIformat-name\fR +. Specifies the format of the image data in \fIfilename\fR. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. .TP \fB\-from \fIx1 y1 x2 y2\fR +. Specifies a rectangular sub-region of the image file data to be copied to the destination image. If only \fIx1\fR and \fIy1\fR are specified, the region extends from (\fIx1,y1\fR) to the bottom-right @@ -294,6 +341,7 @@ The default, if this option is not specified, is the whole of the image in the image file. .TP \fB\-shrink\fR +. If this option, the size of \fIimageName\fR will be reduced, if necessary, so that the region into which the image file data are read is at the bottom-right corner of the \fIimageName\fR. This option @@ -302,12 +350,14 @@ specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .TP \fB\-to \fIx y\fR +. Specifies the coordinates of the top-left corner of the region of \fIimageName\fR into which data from \fIfilename\fR are to be read. The default is (0,0). .RE .TP \fIimageName \fBredither\fR +. The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data for \fIimageName\fR is supplied in pieces, the @@ -316,39 +366,47 @@ not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. .TP -\fIimageName \fBtransparency \fIsubcommand ?arg arg ...?\fR +\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? +. Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS .TP \fIimageName \fBtransparency get \fIx y\fR +. Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is transparent. .TP \fIimageName \fBtransparency set \fIx y boolean\fR +. Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is true, and makes that pixel opaque otherwise. .RE .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? +. Writes image data from \fIimageName\fR to a file named \fIfilename\fR. The following options may be specified: .RS .TP \fB\-background\fI color\fR +. If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .TP \fB\-format\fI format-name\fR +. Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write an image -file. If this option is not given, this subcommand uses the first -handler that has the capability to write an image file. +file. If this option is not given, the format is guessed from +the file extension. If that cannot be determined, this subcommand +uses the first handler that has the capability to write an image file. .TP \fB\-from \fIx1 y1 x2 y2\fR +. Specifies a rectangular region of \fIimageName\fR to be written to the image file. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of @@ -357,6 +415,7 @@ diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image. .TP \fB\-grayscale\fR +. If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .RE @@ -366,8 +425,8 @@ The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The -standard Tk distribution comes with handlers for PPM/PGM and GIF formats, -which are automatically registered on initialization. +standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF +formats, which are automatically registered on initialization. .PP When reading an image file or processing string data specified with the \fB\-data\fR configuration option, the @@ -391,6 +450,27 @@ that, which the handler can use, for example, to specify which variant to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does. +.SS "FORMAT SUBOPTIONS" +.PP +.VS 8.6 +Some image formats support sub-options, which are specified at the time that +the image is loaded using additional words in the \fB\-format\fR option. At +the time of writing, the following are supported: +.TP +\fBgif \-index\fI indexValue\fR +. +When parsing a multi-part GIF image, Tk normally only accesses the first +image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value +may be used instead. The \fIindexValue\fR must be an integer from 0 up to the +number of image parts in the GIF data. +.TP +\fBpng \-alpha\fI alphaValue\fR +. +An additional alpha filtering for the overall image, which allows the +background on which the image is displayed to show through. This usually also +has the effect of desaturating the image. The \fIalphaValue\fR must be between +0.0 and 1.0. +.VE 8.6 .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code @@ -426,8 +506,10 @@ The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout. .SH EXAMPLE +.PP Load an image from a file and tile it to the size of a window, which is useful for producing a tiled background: +.PP .CS # These lines should be called once \fBimage create photo\fR untiled \-file "theFile.ppm" @@ -439,9 +521,23 @@ set width [winfo width .someWidget] set height [winfo height .someWidget] tiled \fBcopy\fR untiled \-to 0 0 $width $height \-shrink .CE - +.PP +.VS 8.6 +The PNG image loader allows the application of an additional alpha factor +during loading, which is useful for generating images suitable for disabled +buttons: +.PP +.CS +\fBimage create photo\fR icon \-file "icon.png" +\fBimage create photo\fR iconDisabled \-file "icon.png" \e + \-format "png \-alpha 0.5" +button .b \-image icon \-disabledimage iconDisabled +.CE +.VE 8.6 .SH "SEE ALSO" image(n) - .SH KEYWORDS photo, image, color +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/place.n b/doc/place.n index 81aaff1..3a092c2 100644 --- a/doc/place.n +++ b/doc/place.n @@ -14,7 +14,6 @@ place \- Geometry manager for fixed or rubber-sheet placement .SH SYNOPSIS \fBplace \fIoption arg \fR?\fIarg ...\fR? .BE - .SH DESCRIPTION .PP The placer is a geometry manager for Tk. @@ -48,9 +47,9 @@ sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. - -The following \fIoption\-value\fR pairs are supported: .RS +.PP +The following \fIoption\-value\fR pairs are supported: .TP \fB\-anchor \fIwhere\fR \fIWhere\fR specifies which point of \fIwindow\fR is to be positioned @@ -73,7 +72,8 @@ an option of \fB\-x 0\fR corresponds to an x-coordinate just inside the border and an option of \fB\-relwidth 1.0\fR means \fIwindow\fR will fill the area inside the master's border. - +.RS +.PP If \fImode\fR is \fBoutside\fR then the placer considers the area of the master to include its border; this mode is typically used when placing \fIwindow\fR @@ -83,6 +83,7 @@ case borders are ignored: the area of the master is considered to be its official X area, which includes any internal border but no external border. A bordermode of \fBignore\fR is probably not very useful. +.RE .TP \fB\-height \fIsize\fR \fISize\fR specifies the height for \fIwindow\fR in screen units @@ -238,15 +239,17 @@ set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. .SH EXAMPLE +.PP Make the label occupy the middle bit of the toplevel, no matter how it is resized: .CS label .l \-text "In the\enMiddle!" \-bg black \-fg white \fBplace\fR .l \-relwidth .3 \-relx .35 \-relheight .3 \-rely .35 .CE - .SH "SEE ALSO" grid(n), pack(n) - .SH KEYWORDS geometry manager, height, location, master, place, rubber sheet, slave, width +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/popup.n b/doc/popup.n index ddce3cb..0d32362 100644 --- a/doc/popup.n +++ b/doc/popup.n @@ -13,7 +13,6 @@ tk_popup \- Post a popup menu .SH SYNOPSIS \fBtk_popup \fImenu x y \fR?\fIentry\fR? .BE - .SH DESCRIPTION .PP This procedure posts a menu at a given position on the screen and @@ -27,6 +26,7 @@ Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and the menu will be positioned so that the entry is positioned over the given point. .SH EXAMPLE +.PP How to attach a simple popup menu to a widget. .CS # Create a menu @@ -40,9 +40,10 @@ pack [label .l \-text "Click me!"] # Arrange for the menu to pop up when the label is clicked bind .l <1> {\fBtk_popup\fR .popupMenu %X %Y} .CE - .SH "SEE ALSO" bind(n), menu(n), tk_optionMenu(n) - .SH KEYWORDS menu, popup +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/radiobutton.n b/doc/radiobutton.n index 565931c..557b42c 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -radiobutton \- Create and manipulate radiobutton widgets +radiobutton \- Create and manipulate 'radiobutton' pick-one widgets .SH SYNOPSIS \fBradiobutton\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -38,16 +38,16 @@ 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 +proper boolean value. If false, the \fB\-relief\fR option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. .OP \-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. +If \fB\-indicatoron\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 false, this color is used as the background -for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, +If \fB\-indicatoron\fR is false, this color is used as the background +for the entire widget, in place of \fB\-background\fR or \fB\-activeBackground\fR, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. @@ -72,34 +72,30 @@ raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the radiobutton. The empty string is the default value. .OP \-selectimage selectImage SelectImage -Specifies an image to display (in place of the \fBimage\fR option) +Specifies an image to display (in place of the \fB\-image\fR option) when the radiobutton is selected. -This option is ignored unless the \fBimage\fR option has been +This option is ignored unless the \fB\-image\fR option has been specified. .OP \-state state State Specifies one of three states for the radiobutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the radiobutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is +\fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the radiobutton. In active state -the radiobutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the radiobutton +the radiobutton is displayed using the \fB\-activeforeground\fR and +\fB\-activebackground\fR options. Disabled state means that the radiobutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the radiobutton is displayed. +In this state the \fB\-disabledforeground\fR and +\fB\-background\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) +Specifies an image to display (in place of the \fB\-image\fR option) when the radiobutton is selected. -This option is ignored unless the \fBimage\fR option has been +This option is ignored unless the \fB\-image\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 +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. @@ -133,11 +129,11 @@ A radiobutton is a widget that displays a textual string, bitmap or image and a diamond or circle called an \fIindicator\fR. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and +or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the -\fBunderline\fR option. A radiobutton has +\fB\-underline\fR option. A radiobutton has all of the behavior of a simple button: it can display itself in either -of three different ways, according to the \fBstate\fR option; +of three different ways, according to the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the @@ -160,12 +156,10 @@ 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 +If the variable's value matches the \fB\-tristatevalue\fR, then the radiobutton +is drawn using the tri-state mode. This mode is used to indicate mixed or +multiple values. (This is used when the radiobutton represents the state of multiple items.) -.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 @@ -190,12 +184,14 @@ determine the exact behavior of the command. The following commands are possible for radiobutton widgets: .TP \fIpathName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -210,12 +206,14 @@ this case the command returns an empty string. command. .TP \fIpathName \fBdeselect\fR +. Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect. .TP \fIpathName \fBflash\fR +. Flashes the radiobutton. This is accomplished by redisplaying the radiobutton several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active @@ -223,6 +221,7 @@ state as when the command was invoked. This command is ignored if the radiobutton's state is \fBdisabled\fR. .TP \fIpathName \fBinvoke\fR +. Does just what would have happened if the user invoked the radiobutton with the mouse: selects the button and invokes its associated Tcl command, if there is one. @@ -231,6 +230,7 @@ empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is \fBdisabled\fR. .TP \fIpathName \fBselect\fR +. Selects the radiobutton and sets the associated variable to the value corresponding to this widget. .SH BINDINGS @@ -261,3 +261,6 @@ individual widgets or by redefining the class bindings. checkbutton(n), labelframe(n), listbox(n), options(n), scale(n), ttk::radiobutton(n) .SH KEYWORDS radiobutton, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/raise.n b/doc/raise.n index b71a637..be20c74 100644 --- a/doc/raise.n +++ b/doc/raise.n @@ -14,7 +14,6 @@ raise \- Change a window's position in the stacking order .SH SYNOPSIS \fBraise \fIwindow \fR?\fIaboveThis\fR? .BE - .SH DESCRIPTION .PP If the \fIaboveThis\fR argument is omitted then the command raises @@ -28,7 +27,12 @@ In this case the \fBraise\fR command will insert \fIwindow\fR into the stacking order just above \fIaboveThis\fR (or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); this could end up either raising or lowering \fIwindow\fR. +.PP +All \fBtoplevel\fR windows may be restacked with respect to each +other, whatever their relative path names, but the window manager is +not obligated to strictly honor requests to restack. .SH EXAMPLE +.PP Make a button appear to be in a sibling frame that was created after it. This is is often necessary when building GUIs in the style where you create your activity widgets first before laying them out on the @@ -41,9 +45,10 @@ pack .b \-in .f pack [label .f.l2 \-text "This is below"] \fBraise\fR .b .CE - .SH "SEE ALSO" lower(n) - .SH KEYWORDS obscure, raise, stacking order +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/scale.n b/doc/scale.n index a9355a9..7bc5c59 100644 --- a/doc/scale.n +++ b/doc/scale.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -scale \- Create and manipulate scale widgets +scale \- Create and manipulate 'scale' value-controlled slider widgets .SH SYNOPSIS \fBscale\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -74,7 +74,7 @@ Specifies one of three states for the scale: \fBnormal\fR, If the scale is disabled then the value may not be changed and the scale will not activate. If the scale is active, the slider is displayed using the color -specified by the \fBactiveBackground\fR option. +specified by the \fB\-activebackground\fR option. .OP \-tickinterval tickInterval TickInterval Must be a real value. Determines the spacing between numerical @@ -83,7 +83,7 @@ If 0, no tick marks will be displayed. .OP \-to to To Specifies a real value corresponding to the right or bottom end of the scale. -This value may be either less than or greater than the \fBfrom\fR option. +This value may be either less than or greater than the \fB\-from\fR option. .OP \-variable variable Variable Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this @@ -96,7 +96,6 @@ Specifies the desired narrow dimension of the trough in screen units For vertical scales this is the trough's width; for horizontal scales this is the trough's height. .BE - .SH DESCRIPTION .PP The \fBscale\fR command creates a new window (given by the @@ -112,16 +111,16 @@ there must not exist a window named \fIpathName\fR, but .PP A scale is a widget that displays a rectangular \fItrough\fR and a small \fIslider\fR. The trough corresponds to a range -of real values (determined by the \fBfrom\fR, \fBto\fR, and -\fBresolution\fR options), +of real values (determined by the \fB\-from\fR, \fB\-to\fR, and +\fB\-resolution\fR options), and the position of the slider selects a particular real value. The slider's position (and hence the scale's value) may be adjusted with the mouse or keyboard as described in the \fBBINDINGS\fR section below. Whenever the scale's value is changed, a Tcl -command is invoked (using the \fBcommand\fR option) to notify +command is invoked (using the \fB\-command\fR option) to notify other interested widgets of the change. In addition, the value -of the scale can be linked to a Tcl variable (using the \fBvariable\fR +of the scale can be linked to a Tcl variable (using the \fB\-variable\fR option), so that changes in either are reflected in the other. .PP Three annotations may be displayed in a scale widget: a label @@ -146,12 +145,14 @@ determine the exact behavior of the command. The following commands are possible for scale widgets: .TP \fIpathName \fBcget\fR \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -166,12 +167,14 @@ this case the command returns an empty string. command. .TP \fIpathName \fBcoords \fR?\fIvalue\fR? +. Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to \fIvalue\fR. If \fIvalue\fR is omitted then the scale's current value is used. .TP \fIpathName \fBget\fR ?\fIx y\fR? +. If \fIx\fR and \fIy\fR are omitted, returns the current value of the scale. If \fIx\fR and \fIy\fR are specified, they give pixel coordinates within the widget; the command returns @@ -179,7 +182,8 @@ the scale value corresponding to the given pixel. Only one of \fIx\fR or \fIy\fR is used: for horizontal scales \fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. .TP -\fIpathName \fBidentify\fR \fIx y\fR +\fIpathName \fBidentify \fIx y\fR +. Returns a string indicating what part of the scale lies under the coordinates given by \fIx\fR and \fIy\fR. A return value of \fBslider\fR means that the point is over @@ -190,7 +194,8 @@ of the slider below or to the right of the slider. If the point is not over one of these elements, an empty string is returned. .TP -\fIpathName \fBset\fR \fIvalue\fR +\fIpathName \fBset \fIvalue\fR +. This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. \fIValue\fR gives the new value for the scale. @@ -203,7 +208,7 @@ Where the behavior is different for vertical and horizontal scales, the horizontal behavior is described in parentheses. .IP [1] If button 1 is pressed in the trough, the scale's value will -be incremented or decremented by the value of the \fBresolution\fR +be incremented or decremented by the value of the \fB\-resolution\fR option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats. .IP [2] @@ -219,26 +224,30 @@ position. If the mouse is dragged with button 2 down, the scale's value changes with the drag. .IP [5] The Up and Left keys move the slider up (left) by the value -of the \fBresolution\fR option. +of the \fB\-resolution\fR option. .IP [6] The Down and Right keys move the slider down (right) by the value -of the \fBresolution\fR option. +of the \fB\-resolution\fR option. .IP [7] Control-Up and Control-Left move the slider up (left) by the -value of the \fBbigIncrement\fR option. +value of the \fB\-bigincrement\fR option. .IP [8] Control-Down and Control-Right move the slider down (right) by the -value of the \fBbigIncrement\fR option. +value of the \fB\-bigincrement\fR option. .IP [9] Home moves the slider to the top (left) end of its range. .IP [10] End moves the slider to the bottom (right) end of its range. .PP -If the scale is disabled using the \fBstate\fR option then +If the scale is disabled using the \fB\-state\fR option then none of the above bindings have any effect. .PP The behavior of scales can be changed by defining new bindings for individual widgets or by redefining the class bindings. - +.SH "SEE ALSO" +ttk::scale(n) .SH KEYWORDS scale, slider, trough, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/scrollbar.n b/doc/scrollbar.n index b12b5dd..4d148af 100644 --- a/doc/scrollbar.n +++ b/doc/scrollbar.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -scrollbar \- Create and manipulate scrollbar widgets +scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets .SH SYNOPSIS \fBscrollbar\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -42,7 +42,7 @@ as described in \fBSCROLLING COMMANDS\fR below. Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider). The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If this value is less than zero, the value of the \fBborderWidth\fR +If this value is less than zero, the value of the \fB\-borderwidth\fR option is used in its place. .OP \-width width Width Specifies the desired narrow dimension of the scrollbar window, @@ -110,9 +110,10 @@ determine the exact behavior of the command. The following commands are possible for scrollbar widgets: .TP \fIpathName \fBactivate \fR?\fIelement\fR? +. Marks the element indicated by \fIelement\fR as active, which -causes it to be displayed as specified by the \fBactiveBackground\fR -and \fBactiveRelief\fR options. +causes it to be displayed as specified by the \fB\-activebackground\fR +and \fB\-activerelief\fR options. The only element values understood by this command are \fBarrow1\fR, \fBslider\fR, or \fBarrow2\fR. If any other value is specified then no element of the scrollbar @@ -121,13 +122,15 @@ If \fIelement\fR is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active. .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -142,6 +145,7 @@ this case the command returns an empty string. command. .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR +. Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, @@ -153,6 +157,7 @@ scrollbar setting must change to move the slider \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. .TP \fIpathName \fBfraction \fIx y\fR +. Returns a real number between 0 and 1 indicating where the point given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the @@ -164,17 +169,20 @@ If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. .TP \fIpathName \fBget\fR +. Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent \fBset\fR widget command. .TP -\fIpathName \fBidentify\fR \fIx y\fR +\fIpathName \fBidentify \fIx y\fR +. Returns the name of the element under the point given by \fIx\fR and \fIy\fR (such as \fBarrow1\fR), or an empty string if the point does not lie in any element of the scrollbar. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. .TP -\fIpathName \fBset\fR \fIfirst last\fR +\fIpathName \fBset \fIfirst last\fR +. This command is invoked by the scrollbar's associated widget to tell the scrollbar about the current view in the widget. The command takes two arguments, each of which is a real fraction @@ -194,9 +202,11 @@ 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 +\fB\-command\fR option, which usually has a form like +.QW \fB.t yview\fR . .TP \fIprefix \fBmoveto \fIfraction\fR +. \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. @@ -206,6 +216,7 @@ 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. @@ -214,6 +225,7 @@ 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 @@ -230,7 +242,7 @@ is deprecated. In the old command syntax, the \fBset\fR widget command has the following form: .TP -\fIpathName \fBset\fR \fItotalUnits windowUnits firstUnit lastUnit\fR +\fIpathName \fBset \fItotalUnits windowUnits firstUnit lastUnit\fR In this form the arguments are all integers. \fITotalUnits\fR gives the total size of the object being displayed in the associated widget. The meaning of one unit depends on the associated @@ -262,6 +274,7 @@ If it is given two real arguments then the new syntax will be used in the future, and if it is given four integer arguments then the old syntax will be used. .SH BINDINGS +.PP Tk automatically creates class bindings for scrollbars that give them the following default behavior. If the behavior is different for vertical and horizontal scrollbars, @@ -328,6 +341,7 @@ The Home key adjusts the view to the top (left edge) of the document. .IP [14] The End key adjusts the view to the bottom (right edge) of the document. .SH EXAMPLE +.PP Create a window with a scrollable \fBtext\fR widget: .CS toplevel .tl @@ -341,3 +355,6 @@ grid rowconfigure .tl 0 \-weight 1 ttk:scrollbar(n) .SH KEYWORDS scrollbar, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/selection.n b/doc/selection.n index 41d5d4b..e06a716 100644 --- a/doc/selection.n +++ b/doc/selection.n @@ -14,65 +14,66 @@ selection \- Manipulate the X selection .SH SYNOPSIS \fBselection \fIoption\fR ?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command provides a Tcl interface to the X selection mechanism and implements the full selection functionality described in the X Inter-Client Communication Conventions Manual (ICCCM). .PP -Note that for management of the CLIPBOARD selection (see below), the +Note that for management of the \fBCLIPBOARD\fR selection (see below), the \fBclipboard\fR command may also be used. .PP The first argument to \fBselection\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: -.PP .TP \fBselection clear\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? +. If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it so that no window owns the selection anymore. \fISelection\fR specifies the X selection that should be cleared, and should be an -atom name such as PRIMARY or CLIPBOARD; see the Inter-Client +atom name such as \fBPRIMARY\fR or \fBCLIPBOARD\fR; see the Inter-Client Communication Conventions Manual for complete details. -\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to +\fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . Returns an empty string. .TP \fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? +. Retrieves the value of \fIselection\fR from \fIwindow\fR's display and -returns it as a result. \fISelection\fR defaults to PRIMARY and +returns it as a result. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . \fIType\fR specifies the form in which the selection is to be returned (the desired .QW target for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the +should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR; see the Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to STRING. The selection owner may choose to +\fIType\fR defaults to \fBSTRING\fR. The selection owner may choose to return the selection in any of several different representation -formats, such as STRING, UTF8_STRING, ATOM, INTEGER, etc. (this format -is different +formats, such as \fBSTRING\fR, \fBUTF8_STRING\fR, \fBATOM\fR, +\fBINTEGER\fR, etc. (this format is different than the selection type; see the ICCCM for all the confusing details). -If the selection is returned in a non-string format, such as INTEGER -or ATOM, the \fBselection\fR command converts it to string format as a +If the selection is returned in a non-string format, such as \fBINTEGER\fR +or \fBATOM\fR, the \fBselection\fR command converts it to string format as a collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that \fBselection get\fR does not retrieve the selection in the -UTF8_STRING format unless told to. +\fBUTF8_STRING\fR format unless told to. .TP \fBselection handle\fR ?\fB\-selection\fR \fIs\fR? ?\fB\-type\fR \fIt\fR? ?\fB\-format\fR \fIf\fR? \fIwindow command\fR +. Creates a handler for selection requests, such that \fIcommand\fR will be executed whenever selection \fIs\fR is owned by \fIwindow\fR and someone attempts to retrieve it in the form given by type \fIt\fR (e.g. \fIt\fR is specified in the \fBselection get\fR command). -\fIS\fR defaults to PRIMARY, \fIt\fR defaults to STRING, and -\fIf\fR defaults to STRING. If \fIcommand\fR is an empty string +\fIS\fR defaults to \fBPRIMARY\fR, \fIt\fR defaults to \fBSTRING\fR, and +\fIf\fR defaults to \fBSTRING\fR. If \fIcommand\fR is an empty string then any existing handler for \fIwindow\fR, \fIt\fR, and \fIs\fR is removed. -Note that when the selection is handled as type STRING it is also -automatically handled as type UTF8_STRING as well. +Note that when the selection is handled as type \fBSTRING\fR it is also +automatically handled as type \fBUTF8_STRING\fR as well. .RS .PP When \fIselection\fR is requested, \fIwindow\fR is the selection owner, @@ -99,12 +100,12 @@ 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. +Table 2 of the ICCCM), and defaults to \fBSTRING\fR. If \fIformat\fR is +\fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters (i.e. just in the form returned by \fIcommand\fR, in the system \fBencoding\fR; -the UTF8_STRING format always uses UTF-8 as its encoding). +the \fBUTF8_STRING\fR format always uses UTF-8 as its encoding). If \fIformat\fR is -ATOM, then the return value from \fIcommand\fR is divided into fields +\fBATOM\fR, then the return value from \fIcommand\fR is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other \fIformat\fR, the return value from \fIcommand\fR is @@ -122,12 +123,14 @@ irrelevant. \fBselection own\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? .TP \fBselection own\fR ?\fB\-command\fR \fIcommand\fR? ?\fB\-selection\fR \fIselection\fR? \fIwindow\fR +. The first form of \fBselection own\fR returns the path name of the window in this application that owns \fIselection\fR on the display containing \fIwindow\fR, or an empty string if no window in this -application owns the selection. \fISelection\fR defaults to PRIMARY and +application owns the selection. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . +.RS .PP The second form of \fBselection own\fR causes \fIwindow\fR to become the new owner of \fIselection\fR on \fIwindow\fR's display, returning @@ -136,16 +139,20 @@ that it has lost the selection. If \fIcommand\fR is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from \fIwindow\fR. \fISelection\fR defaults to PRIMARY. +.RE .SH EXAMPLES +.PP On X11 platforms, one of the standard selections available is the -SECONDARY selection. Hardly anything uses it, but here is how to read +\fBSECONDARY\fR selection. Hardly anything uses it, but here is how to read it using Tk: +.PP .CS set selContents [\fBselection get\fR \-selection SECONDARY] .CE .PP Many different types of data may be available for a selection; the -special type TARGETS allows you to get a list of available types: +special type \fBTARGETS\fR allows you to get a list of available types: +.PP .CS foreach type [\fBselection get\fR \-type TARGETS] { puts "Selection PRIMARY supports type $type" @@ -153,14 +160,14 @@ foreach type [\fBselection get\fR \-type TARGETS] { .CE .PP To claim the selection, you must first set up a handler to supply the -data for the selection. Then you have to claim the selection... +data for the selection. Then you have to claim the selection... .CS # Set up the data handler ready for incoming requests set foo "This is a string with some data in it... blah blah" \fBselection handle\fR \-selection SECONDARY . getData proc getData {offset maxChars} { puts "Retrieving selection starting at $offset" - return [string range $::foo $offset [expr {$offset+$maxChars}]] + return [string range $::foo $offset [expr {$offset+$maxChars-1}]] } # Now we grab the selection itself @@ -174,3 +181,6 @@ proc lost {} { clipboard(n) .SH KEYWORDS clear, format, handler, ICCCM, own, selection, target, type +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -14,7 +14,6 @@ send \- Execute a command in a different application .SH SYNOPSIS \fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the @@ -50,23 +49,20 @@ Serves no purpose except to terminate the list of options. This option is needed only if \fIapp\fR could contain a leading .QW \- character. - .SH "APPLICATION NAMES" .PP The name of an application is set initially from the name of the program or script that created the application. You can query and change the name of an application with the \fBtk appname\fR command. - .SH "DISABLING SENDS" .PP If the \fBsend\fR command is removed from an application (e.g. -with the command \fBrename send {}\fR) then the application +with the command \fBrename\fR \fBsend {}\fR) then the application will not respond to incoming send requests anymore, nor will it be able to issue outgoing requests. Communication can be reenabled by invoking the \fBtk appname\fR command. - .SH SECURITY .PP The \fBsend\fR command is potentially a serious security loophole. On Unix, @@ -89,6 +85,7 @@ such as that provide by \fBxauth\fR. Under Windows, \fBsend\fR is currently disabled. Most of the functionality is provided by the \fBdde\fR command instead. .SH EXAMPLE +.PP This script fragment can be used to make an application that only runs once on a particular display. .CS @@ -107,3 +104,6 @@ proc RemoteStart args { .CE .SH KEYWORDS application, dde, name, remote execution, security, send +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/spinbox.n b/doc/spinbox.n index 34b7014..7227cf1 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -spinbox \- Create and manipulate spinbox widgets +spinbox \- Create and manipulate 'spinbox' value spinner widgets .SH SYNOPSIS \fBspinbox\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -57,9 +57,9 @@ are specified correctly, the spinbox will use these values to control its contents. This value must be less than the \fB\-to\fR option. If \fB\-values\fR is specified, it supercedes this option. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fBvalidateCommand\fR returns 0. Setting +Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to an empty string disables this feature (the default). The best use of -this option is to set it to \fIbell\fR. See \fBValidation\fR below for +this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for more information. .OP \-increment increment Increment A floating-point value specifying the increment. When used with @@ -89,16 +89,16 @@ If \fB\-values\fR is specified, it supercedes this option. Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBValidation\fR below for more. +state which mode you wish to use. See \fBVALIDATION\fR below for more. .OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand Specifies a script to evaluate when you want to validate the input in the widget. Setting it to an empty string disables this feature (the default). Validation occurs according to the value of \fB\-validate\fR. This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then the value of the widget will not -change and the \fBinvalidCommand\fR will be evaluated if it is set. If it +change and the \fB\-invalidcommand\fR will be evaluated if it is set. If it returns 1, then value will be changed. -See \fBValidation\fR below for more information. +See \fBVALIDATION\fR below for more information. .OP \-values values Values Must be a proper list value. If specified, the spinbox will use these values as to control its contents, starting with the first value. This @@ -129,7 +129,7 @@ to move, or spin, through a fixed set of ascending or descending values such as times or dates in addition to editing the value as in an \fBentry\fR. When first created, a spinbox's string is empty. A portion of the spinbox may be selected as described below. -If a spinbox is exporting its selection (see the \fBexportSelection\fR +If a spinbox is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard protocols for handling the selection; spinbox selections are available as type \fBSTRING\fR. Spinboxes also observe the standard Tk rules for dealing with the @@ -141,31 +141,31 @@ Spinboxes are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Spinboxes use -the standard \fBxScrollCommand\fR mechanism for interacting with -scrollbars (see the description of the \fBxScrollCommand\fR option +the standard \fB\-xscrollcommand\fR mechanism for interacting with +scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). They also support scanning, as described below. .SH VALIDATION .PP -Validation works by setting the \fBvalidateCommand\fR -option to a script which will be evaluated according to the \fBvalidate\fR +Validation works by setting the \fB\-validatecommand\fR +option to a script which will be evaluated according to the \fB\-validate\fR option as follows: .PP .IP \fBnone\fR 10 Default. This means no validation will occur. .IP \fBfocus\fR 10 -\fBvalidateCommand\fR will be called when the spinbox receives or +The \fB\-validatecommand\fR will be called when the spinbox receives or loses focus. .IP \fBfocusin\fR 10 -\fBvalidateCommand\fR will be called when the spinbox receives focus. +The \fB\-validatecommand\fR will be called when the spinbox receives focus. .IP \fBfocusout\fR 10 -\fBvalidateCommand\fR will be called when the spinbox loses focus. +The \fB\-validatecommand\fR will be called when the spinbox loses focus. .IP \fBkey\fR 10 -\fBvalidateCommand\fR will be called when the spinbox is edited. +The \fB\-validatecommand\fR will be called when the spinbox is edited. .IP \fBall\fR 10 -\fBvalidateCommand\fR will be called for all above conditions. +The \fB\-validatecommand\fR will be called for all above conditions. .PP -It is possible to perform percent substitutions on the \fBvalidateCommand\fR -and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The +It is possible to perform percent substitutions on the \fB\-validatecommand\fR +and \fB\-invalidcommand\fR scripts, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP .IP \fB%d\fR 5 @@ -190,32 +190,32 @@ The type of validation that triggered the callback .IP \fB%W\fR 5 The name of the spinbox widget. .PP -In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be +In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR can be dangerous to mix. Any problems have been overcome so that using the -\fBvalidateCommand\fR will not interfere with the traditional behavior of -the spinbox widget. Using the \fBtextVariable\fR for read-only purposes will +\fB\-validatecommand\fR will not interfere with the traditional behavior of +the spinbox widget. Using the \fB\-textvariable\fR for read-only purposes will never cause problems. The danger comes when you try set the -\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not -accept, which causes \fBvalidate\fR to become \fBnone\fR (the -\fBinvalidCommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fBvalidateCommand\fR. +\fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not +accept, which causes \fB\-validate\fR to become \fBnone\fR (the +\fB\-invalidcommand\fR will not be triggered). The same happens +when an error occurs evaluating the \fB\-validatecommand\fR. .PP -Primarily, an error will occur when the \fBvalidateCommand\fR or -\fBinvalidCommand\fR encounters an error in its script while evaluating or -\fBvalidateCommand\fR does not return a valid Tcl boolean value. The -\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the -spinbox widget from within either the \fBvalidateCommand\fR or the -\fBinvalidCommand\fR. Such editions will override the one that was being +Primarily, an error will occur when the \fB\-validatecommand\fR or +\fB\-invalidcommand\fR encounters an error in its script while evaluating or +\fB\-validatecommand\fR does not return a valid Tcl boolean value. The +\fB\-validate\fR option will also set itself to \fBnone\fR when you edit the +spinbox widget from within either the \fB\-validatecommand\fR or the +\fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the value of the widget -during validation and still have the \fBvalidate\fR option set, you should +during validation and still have the \fB\-validate\fR option set, you should include the command .CS \fI%W config \-validate %v\fR .CE -in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you +in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an -associated \fBtextVariable\fR during validation, as that can cause the -spinbox widget to become out of sync with the \fBtextVariable\fR. +associated \fB\-textvariable\fR during validation, as that can cause the +spinbox widget to become out of sync with the \fB\-textvariable\fR. .PP Also, the \fBvalidate\fR option will set itself to \fBnone\fR when the spinbox value gets changed because of adjustment of \fBfrom\fR or \fBto\fR @@ -402,7 +402,7 @@ Returns an empty string. Returns 1 if there is are characters selected in the spinbox, 0 if nothing is selected. .TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR +\fIpathName \fBselection range \fIstart end\fR Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. @@ -430,9 +430,9 @@ value, otherwise it just returns the spinbox's string. If validation is on, it will occur when setting the string. .TP \fIpathName \fBvalidate\fR -This command is used to force an evaluation of the \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. +This command is used to force an evaluation of the \fB\-validatecommand\fR +independent of the conditions specified by the \fB\-validate\fR option. +This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .TP \fIpathName \fBxview \fIargs\fR @@ -451,7 +451,7 @@ 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 +\fIpathName \fBxview \fIindex\fR Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP @@ -473,7 +473,6 @@ If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE - .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for spinboxes that give them @@ -590,6 +589,10 @@ take place. .PP The behavior of spinboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. - +.SH "SEE ALSO" +ttk::spinbox(n) .SH KEYWORDS spinbox, entry, widget +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -8,9 +8,9 @@ .TH text n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS -'\" Note: do not modify the .SH NAME line immediately below! +'\" Note: do not modify the .SH NAME line immediately below! .SH NAME -text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widgets +text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets .SH SYNOPSIS .nf \fBtext\fR \fIpathName \fR?\fIoptions\fR? @@ -29,1037 +29,894 @@ text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widget .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-autoseparators autoSeparators AutoSeparators -Specifies a boolean that says whether separators are automatically -inserted in the undo stack. Only meaningful when the \fB\-undo\fR -option is true. +Specifies a boolean that says whether separators are automatically inserted in +the undo stack. Only meaningful when the \fB\-undo\fR option is true. .OP \-blockcursor blockCursor BlockCursor -.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 +Specifies a boolean that says whether the blinking insertion cursor should be +drawn as a character-sized rectangular block. If false (the default) a thin +vertical line is used for the insertion cursor. .OP \-endline endLine EndLine -.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 +the widget. This allows a text widget to reflect only a portion of a +larger piece of text. Instead of an integer, the empty string can be +provided to this configuration option, which will configure the widget +to end at the very last line in the textual data store. .OP \-height height Height -Specifies the desired height for the window, in units of characters -in the font given by the \fB\-font\fR option. -Must be at least one. +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 +Specifies the colour to use for the selection (the \fBsel\fR tag) when the +window does not have the input focus. If empty, \fB{}\fR, then no selection is +shown when the window does not have the focus. +.OP \-insertunfocussed insertUnfocussed InsertUnfocussed +.VS 8.6 +Specifies how to display the insertion cursor when the widget does not have +the focus. Must be \fBnone\fR (the default) which means to not display the +cursor, \fBhollow\fR which means to display a hollow box, or \fBsolid\fR which +means to display a solid box. Note that \fBhollow\fR and \fBsolid\fR will +appear very similar when the \fB\-blockcursor\fR option is false. +.VE 8.6 .OP \-maxundo maxUndo MaxUndo -Specifies the maximum number of compound undo actions on the undo -stack. A zero or a negative value imply an unlimited undo stack. +Specifies the maximum number of compound undo actions on the undo stack. A +zero or a negative value imply an unlimited undo stack. .OP \-spacing1 spacing1 Spacing1 -Requests additional space above each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the first line -on the display. -This option may be overridden with \fB\-spacing1\fR options in -tags. +Requests additional space above each text line in the widget, using any of the +standard forms for screen distances. If a line wraps, this option only applies +to the first line on the display. This option may be overridden with +\fB\-spacing1\fR options in tags. .OP \-spacing2 spacing2 Spacing2 -For lines that wrap (so that they cover more than one line on the -display) this option specifies additional space to provide between -the display lines that represent a single line of text. -The value may have any of the standard forms for screen distances. -This option may be overridden with \fB\-spacing2\fR options in -tags. +For lines that wrap (so that they cover more than one line on the display) +this option specifies additional space to provide between the display lines +that represent a single line of text. The value may have any of the standard +forms for screen distances. This option may be overridden with +\fB\-spacing2\fR options in tags. .OP \-spacing3 spacing3 Spacing3 -Requests additional space below each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the last line -on the display. -This option may be overridden with \fB\-spacing3\fR options in -tags. +Requests additional space below each text line in the widget, using any of the +standard forms for screen distances. If a line wraps, this option only applies +to the last line on the display. This option may be overridden with +\fB\-spacing3\fR options in tags. .OP \-startline startLine StartLine -.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 +Specifies an integer line index representing the first line of the underlying +textual data store that should be contained in the widget. This allows a text +widget to reflect only a portion of a larger piece of text. Instead of an +integer, the empty string can be provided to this configuration option, which +will configure the widget to start at the very first line in the textual data +store. .OP \-state state State -Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. -If the text is disabled then characters may not be inserted or deleted -and no insertion cursor will be displayed, even if the input focus is -in the widget. +Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. If +the text is disabled then characters may not be inserted or deleted and no +insertion cursor will be displayed, even if the input focus is in the widget. .OP \-tabs tabs Tabs -Specifies a set of tab stops for the window. The option's value consists -of a list of screen distances giving the positions of the tab stops, -each of which is a distance relative to the left edge of the widget -(excluding borders, padding, etc). Each -position may optionally be followed in the next list element -by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, -or \fBnumeric\fR, which specifies how to justify -text relative to the tab stop. \fBLeft\fR is the default; it causes -the text following the tab character to be positioned with its left edge -at the tab position. \fBRight\fR means that the right edge of the text -following the tab character is positioned at the tab position, and -\fBcenter\fR means that the text is centered at the tab position. -\fBNumeric\fR means that the decimal point in the text is positioned -at the tab position; if there is no decimal point then the least -significant digit of the number is positioned just to the left of the -tab position; if there is no number in the text then the text is -right-justified at the tab position. -For example, +Specifies a set of tab stops for the window. The option's value consists of a +list of screen distances giving the positions of the tab stops, each of which +is a distance relative to the left edge of the widget (excluding borders, +padding, etc). Each position may optionally be followed in the next list +element by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, or +\fBnumeric\fR, which specifies how to justify text relative to the tab stop. +\fBLeft\fR is the default; it causes the text following the tab character to +be positioned with its left edge at the tab position. \fBRight\fR means that +the right edge of the text following the tab character is positioned at the +tab position, and \fBcenter\fR means that the text is centered at the tab +position. \fBNumeric\fR means that the decimal point in the text is positioned +at the tab position; if there is no decimal point then the least significant +digit of the number is positioned just to the left of the tab position; if +there is no number in the text then the text is right-justified at the tab +position. For example, .QW "\fB\-tabs {2c left 4c 6c center}\fR" -creates three tab stops at two-centimeter intervals; the first two use left +creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. .RS .PP -If the list of tab stops does not have enough elements to cover all -of the tabs in a text line, then Tk extrapolates new tab stops using -the spacing and alignment from the last tab stop in the list. Tab -distances must be strictly positive, and must always increase from one -tab stop to the next (if not, an error is thrown). -The value of the \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. To achieve a different standard spacing, -for example every 4 characters, simply configure the widget with +If the list of tab stops does not have enough elements to cover all of the +tabs in a text line, then Tk extrapolates new tab stops using the spacing and +alignment from the last tab stop in the list. Tab distances must be strictly +positive, and must always increase from one tab stop to the next (if not, an +error is thrown). The value of the \fB\-tabs\fR option may be overridden by +\fB\-tabs\fR options in tags. +.PP +If no \fB\-tabs\fR option is specified, or if it is specified as an empty +list, then Tk uses default tabs spaced every eight (average size) characters. +To achieve a different standard spacing, for example every 4 characters, +simply configure the widget with .QW "\fB\-tabs \N'34'[expr {4 * [font measure $font 0]}] left\N'34' \-tabstyle wordprocessor\fR" . .RE .OP \-tabstyle tabStyle TabStyle -Specifies how to interpret the relationship between tab stops on a line -and tabs in the text of that line. The value must be \fBtabular\fR (the -default) or \fBwordprocessor\fR. Note that tabs are interpreted as they -are encountered in the text. If the tab style is \fBtabular\fR then the -\fIn\fR'th tab character in the line's text will be associated with -the \fIn\fR'th -tab stop defined for that line. If the tab character's x coordinate -falls to the right of the \fIn\fR'th tab stop, then a gap of a single space -will be inserted as a fallback. If the tab style is \fBwordprocessor\fR -then any tab character being laid out will use (and be defined by) the -first tab stop to the right of the preceding characters already laid out -on that line. The value of the \fBtabstyle\fR option may be overridden -by \fB\-tabstyle\fR options in tags. +Specifies how to interpret the relationship between tab stops on a line and +tabs in the text of that line. The value must be \fBtabular\fR (the default) +or \fBwordprocessor\fR. Note that tabs are interpreted as they are encountered +in the text. If the tab style is \fBtabular\fR then the \fIn\fR'th tab +character in the line's text will be associated with the \fIn\fR'th tab stop +defined for that line. If the tab character's x coordinate falls to the right +of the \fIn\fR'th tab stop, then a gap of a single space will be inserted as a +fallback. If the tab style is \fBwordprocessor\fR then any tab character being +laid out will use (and be defined by) the first tab stop to the right of the +preceding characters already laid out on that line. The value of the +\fB\-tabstyle\fR option may be overridden by \fB\-tabstyle\fR options in tags. .OP \-undo undo Undo -Specifies a boolean that says whether the undo mechanism is active or -not. +Specifies a boolean that says whether the undo mechanism is active or not. .OP \-width width Width -Specifies the desired width for the window in units of characters -in the font given by the \fB\-font\fR option. -If the font does not have a uniform width then the width of the character +Specifies the desired width for the window in units of characters in the font +given by the \fB\-font\fR option. If the font does not have a uniform width +then the width of the character .QW 0 is used in translating from character units to screen units. .OP \-wrap wrap Wrap -Specifies how to handle lines in the text that are too long to be -displayed in a single line of the text's window. -The value must be \fBnone\fR or \fBchar\fR or \fBword\fR. -A wrap mode of \fBnone\fR means that each line of text appears as -exactly one line on the screen; extra characters that do not fit -on the screen are not displayed. -In the other modes each line of text will be broken up into several -screen lines if necessary to keep all the characters visible. -In \fBchar\fR mode a screen line break may occur after any character; -in \fBword\fR mode a line break will only be made at word boundaries. +Specifies how to handle lines in the text that are too long to be displayed in +a single line of the text's window. The value must be \fBnone\fR or \fBchar\fR +or \fBword\fR. A wrap mode of \fBnone\fR means that each line of text appears +as exactly one line on the screen; extra characters that do not fit on the +screen are not displayed. In the other modes each line of text will be broken +up into several screen lines if necessary to keep all the characters visible. +In \fBchar\fR mode a screen line break may occur after any character; in +\fBword\fR mode a line break will only be made at word boundaries. .BE - .SH DESCRIPTION .PP -The \fBtext\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a text widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the text such as its default background color -and relief. The \fBtext\fR command returns the -path name of the new window. -.PP -A text widget displays one or more lines of text and allows that -text to be edited. -Text widgets support four different kinds of annotations on the -text, called tags, marks, embedded windows or embedded images. -Tags allow different portions of the text -to be displayed with different fonts and colors. -In addition, Tcl commands can be associated with tags so -that scripts are invoked when particular actions such as keystrokes -and mouse button presses occur in particular ranges of the text. -See \fBTAGS\fR below for more details. -.PP -The second form of annotation consists of floating markers in the text -called +The \fBtext\fR command creates a new window (given by the \fIpathName\fR +argument) and makes it into a text widget. Additional options, described +above, may be specified on the command line or in the option database to +configure aspects of the text such as its default background color and relief. +The \fBtext\fR command returns the path name of the new window. +.PP +A text widget displays one or more lines of text and allows that text to be +edited. Text widgets support four different kinds of annotations on the text, +called tags, marks, embedded windows or embedded images. Tags allow different +portions of the text to be displayed with different fonts and colors. In +addition, Tcl commands can be associated with tags so that scripts are invoked +when particular actions such as keystrokes and mouse button presses occur in +particular ranges of the text. See \fBTAGS\fR below for more details. +.PP +The second form of annotation consists of floating markers in the text called .QW marks . -Marks are used to keep track of various interesting positions in the -text as it is edited. -See \fBMARKS\fR below for more details. +Marks are used to keep track of various interesting positions in the text as +it is edited. See \fBMARKS\fR below for more details. .PP -The third form of annotation allows arbitrary windows to be -embedded in a text widget. -See \fBEMBEDDED WINDOWS\fR below for more details. +The third form of annotation allows arbitrary windows to be embedded in a text +widget. See \fBEMBEDDED WINDOWS\fR below for more details. .PP The fourth form of annotation allows Tk images to be embedded in a text -widget. -See \fBEMBEDDED IMAGES\fR below for more details. +widget. See \fBEMBEDDED IMAGES\fR below for more details. .PP -The text widget also has a built-in undo/redo mechanism. -See \fBTHE UNDO MECHANISM\fR below for more details. +The text widget also has a built-in undo/redo mechanism. See +\fBTHE UNDO MECHANISM\fR below for more details. .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 +The text widget allows for the creation of peer widgets. These are other text +widgets which share the same underlying data (text, marks, tags, images, etc). +See \fBPEER WIDGETS\fR below for more details. .SH INDICES .PP -Many of the widget commands for texts take one or more indices -as arguments. -An index is a string used to indicate a particular place within -a text, such as a place to insert characters or one endpoint of a -range of characters to delete. -Indices have the syntax +Many of the widget commands for texts take one or more indices as arguments. +An index is a string used to indicate a particular place within a text, such +as a place to insert characters or one endpoint of a range of characters to +delete. Indices have the syntax .CS \fIbase modifier modifier modifier ...\fR .CE -Where \fIbase\fR gives a starting point and the \fImodifier\fRs -adjust the index from the starting point (e.g. move forward or -backward one character). Every index must contain a \fIbase\fR, -but the \fImodifier\fRs are optional. -.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 +Where \fIbase\fR gives a starting point and the \fImodifier\fRs adjust the +index from the starting point (e.g. move forward or backward one character). +Every index must contain a \fIbase\fR, but the \fImodifier\fRs are optional. +Most modifiers (as documented below) allow an optional submodifier. Valid +submodifiers are \fBany\fR and \fBdisplay\fR. If the submodifier is +abbreviated, then it must be followed by whitespace, but otherwise there need +be no space between the submodifier and the following \fImodifier\fR. +Typically the \fBdisplay\fR submodifier adjusts the meaning of the following +\fImodifier\fR to make it refer to visual or non-elided units rather than +logical units, but this is explained for each relevant case below. Lastly, +where \fIcount\fR is used as part of a modifier, it can be positive or +negative, so .QW "\fIbase\fR \- \-3 lines" is perfectly valid (and equivalent to .QW "\fIbase\fR +3lines" ). -.VE 8.5 .PP The \fIbase\fR for an index must have one of the following forms: .TP 12 \fIline\fB.\fIchar\fR -Indicates \fIchar\fR'th character on line \fIline\fR. -Lines are numbered from 1 for consistency with other UNIX programs -that use this numbering scheme. -Within a line, characters are numbered from 0. -If \fIchar\fR is \fBend\fR then it refers to the newline character -that ends the line. +. +Indicates \fIchar\fR'th character on line \fIline\fR. Lines are numbered from +1 for consistency with other UNIX programs that use this numbering scheme. +Within a line, characters are numbered from 0. If \fIchar\fR is \fBend\fR then +it refers to the newline character that ends the line. .TP 12 \fB@\fIx\fB,\fIy\fR -Indicates the character that covers the pixel whose x and y coordinates -within the text's window are \fIx\fR and \fIy\fR. +. +Indicates the character that covers the pixel whose x and y coordinates within +the text's window are \fIx\fR and \fIy\fR. .TP 12 \fBend\fR -Indicates the end of the text (the character just after the last -newline). +. +Indicates the end of the text (the character just after the last newline). .TP 12 \fImark\fR +. Indicates the character just after the mark whose name is \fImark\fR. .TP 12 \fItag\fB.first\fR -Indicates the first character in the text that has been tagged with +. +Indicates the first character in the text that has been tagged with \fItag\fR. +This form generates an error if no characters are currently tagged with \fItag\fR. -This form generates an error if no characters are currently tagged -with \fItag\fR. .TP 12 \fItag\fB.last\fR -Indicates the character just after the last one in the text that has -been tagged with \fItag\fR. -This form generates an error if no characters are currently tagged -with \fItag\fR. +. +Indicates the character just after the last one in the text that has been +tagged with \fItag\fR. This form generates an error if no characters are +currently tagged with \fItag\fR. .TP 12 \fIpathName\fR -Indicates the position of the embedded window whose name is -\fIpathName\fR. -This form generates an error if there is no embedded window -by the given name. +. +Indicates the position of the embedded window whose name is \fIpathName\fR. +This form generates an error if there is no embedded window by the given name. .TP 12 \fIimageName\fR -Indicates the position of the embedded image whose name is -\fIimageName\fR. -This form generates an error if there is no embedded image -by the given name. -.PP -If the \fIbase\fR could match more than one of the above forms, such -as a \fImark\fR and \fIimageName\fR both having the same value, then -the form earlier in the above list takes precedence. -If modifiers follow the base index, each one of them must have one -of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR -may be abbreviated as long as the abbreviation is unambiguous. +. +Indicates the position of the embedded image whose name is \fIimageName\fR. +This form generates an error if there is no embedded image by the given name. +.PP +If the \fIbase\fR could match more than one of the above forms, such as a +\fImark\fR and \fIimageName\fR both having the same value, then the form +earlier in the above list takes precedence. If modifiers follow the base +index, each one of them must have one of the forms listed below. Keywords such +as \fBchars\fR and \fBwordend\fR may be abbreviated as long as the +abbreviation is unambiguous. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR -.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 +. +Adjust the index forward by \fIcount\fR characters, moving to later lines in +the text if necessary. If there are fewer than \fIcount\fR characters in the +text after the current index, then set the index to the last index in the +text. Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR +submodifier is given, elided characters are skipped over without being +counted. If \fBany\fR is given, then all characters are counted. For +historical reasons, if neither modifier is given then the count actually takes +place in units of index positions (see \fBINDICES\fR for details). This +behaviour may be changed in a future major release, so if you need an index +count, you are encouraged to use \fBindices\fR instead wherever possible. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR -Adjust the index backward by \fIcount\fR characters, moving to earlier -lines in the text if necessary. If there are fewer than \fIcount\fR -characters in the text before the current index, then set the index to -.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 +. +Adjust the index backward by \fIcount\fR characters, moving to earlier lines +in the text if necessary. If there are fewer than \fIcount\fR characters in +the text before the current index, then set the index to the first index in +the text (1.0). Spaces on either side of \fIcount\fR are optional. If the +\fBdisplay\fR submodifier is given, elided characters are skipped over without +being counted. If \fBany\fR is given, then all characters are counted. For +historical reasons, if neither modifier is given then the count actually takes +place in units of index positions (see \fBINDICES\fR for details). This +behavior may be changed in a future major release, so if you need an index +count, you are encouraged to use \fBindices\fR instead wherever possible. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR -.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 +. +Adjust the index forward by \fIcount\fR index positions, moving to later lines +in the text if necessary. If there are fewer than \fIcount\fR index positions +in the text after the current index, then set the index to the last index +position in the text. Spaces on either side of \fIcount\fR are optional. Note +that an index position is either a single character or a single embedded image +or embedded window. If the \fBdisplay\fR submodifier is given, elided indices +are skipped over without being counted. If \fBany\fR is given, then all +indices are counted; this is also the default behaviour if no modifier is +given. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR -.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 +. +Adjust the index backward by \fIcount\fR index positions, moving to earlier +lines in the text if necessary. If there are fewer than \fIcount\fR index +positions in the text before the current index, then set the index to the +first index position (1.0) in the text. Spaces on either side of \fIcount\fR +are optional. If the \fBdisplay\fR submodifier is given, elided indices are +skipped over without being counted. If \fBany\fR is given, then all indices +are counted; this is also the default behaviour if no modifier is given. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR -.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 -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 +. +Adjust the index forward by \fIcount\fR lines, retaining the same character +position within the line. If there are fewer than \fIcount\fR lines after the +line containing the current index, then set the index to refer to the same +character position on the last line of the text. Then, if the line is not long +enough to contain a character at the indicated character position, adjust the +character position to refer to the last character of the line (the newline). +Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR +submodifier is given, then each visual display line is counted separately. +Otherwise, if \fBany\fR (or no modifier) is given, then each logical line (no +matter how many times it is visually wrapped) counts just once. If the +relevant lines are not wrapped, then these two methods of counting are +equivalent. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR -.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 +. +Adjust the index backward by \fIcount\fR logical lines, retaining the same +character position within the line. If there are fewer than \fIcount\fR lines +before the line containing the current index, then set the index to refer to +the same character position on the first line of the text. Then, if the line +is not long enough to contain a character at the indicated character position, +adjust the character position to refer to the last character of the line (the +newline). Spaces on either side of \fIcount\fR are optional. If the +\fBdisplay\fR submodifier is given, then each visual display line is counted +separately. Otherwise, if \fBany\fR (or no modifier) is given, then each +logical line (no matter how many times it is visually wrapped) counts just +once. If the relevant lines are not wrapped, then these two methods of +counting are equivalent. .TP ?\fIsubmodifier\fR? \fBlinestart\fR -.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 +. +Adjust the index to refer to the first index on the line. If the \fBdisplay\fR +submodifier is given, this is the first index on the display line, otherwise +on the logical line. .TP ?\fIsubmodifier\fR? \fBlineend\fR -.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 +. +Adjust the index to refer to the last index on the line (the newline). If the +\fBdisplay\fR submodifier is given, this is the last index on the display +line, otherwise on the logical line. .TP ?\fIsubmodifier\fR? \fBwordstart\fR -.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. If the \fBdisplay\fR submodifier is given, this only -examines non-elided characters, otherwise all characters (elided or not) -are examined. -.VE 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. If the \fBdisplay\fR submodifier is given, this only examines +non-elided characters, otherwise all characters (elided or not) are examined. .TP ?\fIsubmodifier\fR? \fBwordend\fR -.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. 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 +. +Adjust the index to refer to the character just after the last one of the word +containing the current index. If the current index refers to the last +character of the text then it is not modified. If the \fBdisplay\fR +submodifier is given, this only examines non-elided characters, otherwise all +characters (elided or not) are examined. +.PP +If more than one modifier is present then they are applied in left-to-right +order. For example, the index .QW "\fBend \- 1 chars\fR" refers to the next-to-last character in the text and .QW "\fBinsert wordstart \- 1 c\fR" -refers to the character just before -the first one in the word containing the insertion cursor. Modifiers -are applied one by one in this left to right order, and after each step -the resulting index is constrained to be a valid index in the text -widget. So, for example, the index +refers to the character just before the first one in the word containing the +insertion cursor. Modifiers are applied one by one in this left to right +order, and after each step the resulting index is constrained to be a valid +index in the text widget. So, for example, the index .QW "\fB1.0 \-1c +1c\fR" refers to the index .QW \fB2.0\fR . .PP -Where modifiers result in index changes by display lines, display chars -or display indices, and the \fIbase\fR refers to an index inside an -elided tag, +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 +The first form of annotation in text widgets is a tag. A tag is a textual +string that is associated with some of the characters in a text. Tags may +contain arbitrary characters, but it is probably best to avoid using the +characters .QW " " -(space), \fB+\fR, or \fB\-\fR: -these characters have special meaning in indices, so tags containing -them cannot be used as indices. -There may be any number of tags associated with characters in a -text. -Each tag may refer to a single character, a range of characters, or -several ranges of characters. -An individual character may have any number of tags associated with it. -.PP -A priority order is defined among tags, and this order is used in -implementing some of the tag-related functions described below. -When a tag is defined (by associating it with characters or setting -its display options or binding commands to it), it is given -a priority higher than any existing tag. -The priority order of tags may be redefined using the +(space), \fB+\fR, or \fB\-\fR: these characters have special meaning in +indices, so tags containing them cannot be used as indices. There may be any +number of tags associated with characters in a text. Each tag may refer to a +single character, a range of characters, or several ranges of characters. An +individual character may have any number of tags associated with it. +.PP +A priority order is defined among tags, and this order is used in implementing +some of the tag-related functions described below. When a tag is defined (by +associating it with characters or setting its display options or binding +commands to it), it is given a priority higher than any existing tag. The +priority order of tags may be redefined using the .QW "\fIpathName \fBtag raise\fR" and .QW "\fIpathName \fBtag lower\fR" widget commands. .PP -Tags serve three purposes in text widgets. -First, they control the way information is displayed on the screen. -By default, characters are displayed as determined by the -\fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the -text widget. -However, display options may be associated with individual tags -using the +Tags serve three purposes in text widgets. First, they control the way +information is displayed on the screen. By default, characters are displayed +as determined by the \fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR +options for the text widget. However, display options may be associated with +individual tags using the .QW "\fIpathName \fBtag configure\fR" -widget command. -If a character has been tagged, then the display options associated -with the tag override the default display style. -The following options are currently supported for tags: +widget command. If a character has been tagged, then the display options +associated with the tag override the default display style. The following +options are currently supported for tags: .TP \fB\-background \fIcolor\fR -\fIColor\fR specifies the background color to use for characters -associated with the tag. -It may have any of the forms accepted by \fBTk_GetColor\fR. +. +\fIColor\fR specifies the background color to use for characters associated +with the tag. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-bgstipple \fIbitmap\fR -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern -for the background. -It may have any of the forms accepted by \fBTk_GetBitmap\fR. -If \fIbitmap\fR has not been specified, or if it is specified -as an empty string, then a solid fill will be used for the -background. +. +\fIBitmap\fR specifies a bitmap that is used as a stipple pattern for the +background. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If +\fIbitmap\fR has not been specified, or if it is specified as an empty string, +then a solid fill will be used for the background. .TP \fB\-borderwidth \fIpixels\fR -\fIPixels\fR specifies the width of a 3-D border to draw around -the background. -It may have any of the forms accepted by \fBTk_GetPixels\fR. -This option is used in conjunction with the \fB\-relief\fR -option to give a 3-D appearance to the background for characters; -it is ignored unless the \fB\-background\fR option -has been set for the tag. +. +\fIPixels\fR specifies the width of a border to draw around the tag using any +of the forms accepted by \fBTk_GetPixels\fR. This option should be used in +conjunction with the \fB\-relief\fR option to provide the desired border. .TP \fB\-elide \fIboolean\fR -\fIElide\fR specifies whether the data should -be elided. Elided data (characters, images, embedded windows, etc) is -not displayed and takes no space on screen, but further on behaves just -as normal data. +. +\fIElide\fR specifies whether the data should be elided. Elided data +(characters, images, embedded windows, etc.) is not displayed and takes no +space on screen, but further on behaves just as normal data. .TP \fB\-fgstipple \fIbitmap\fR -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern -when drawing text and other foreground information such as -underlines. -It may have any of the forms accepted by \fBTk_GetBitmap\fR. -If \fIbitmap\fR has not been specified, or if it is specified -as an empty string, then a solid fill will be used. +. +\fIBitmap\fR specifies a bitmap that is used as a stipple pattern when drawing +text and other foreground information such as underlines. It may have any of +the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been +specified, or if it is specified as an empty string, then a solid fill will be +used. .TP \fB\-font \fIfontName\fR -\fIFontName\fR is the name of a font to use for drawing characters. -It may have any of the forms accepted by \fBTk_GetFont\fR. +. +\fIFontName\fR is the name of a font to use for drawing characters. It may +have any of the forms accepted by \fBTk_GetFont\fR. .TP \fB\-foreground \fIcolor\fR -\fIColor\fR specifies the color to use when drawing text and other -foreground information such as underlines. -It may have any of the forms accepted by \fBTk_GetColor\fR. +. +\fIColor\fR specifies the color to use when drawing text and other foreground +information such as underlines. It may have any of the forms accepted by +\fBTk_GetColor\fR. .TP \fB\-justify \fIjustify\fR +. If the first non-elided character of a display line has a tag for which this -option has been specified, then \fIjustify\fR determines how to -justify the line. -It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. -If a line wraps, then the justification for each line on the -display is determined by the first non-elided character of that display line. +option has been specified, then \fIjustify\fR determines how to justify the +line. It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. If a line +wraps, then the justification for each line on the display is determined by +the first non-elided character of that display line. .TP \fB\-lmargin1 \fIpixels\fR +. If the first non-elided character of a text line has a tag for which this -option has been specified, then \fIpixels\fR specifies how -much the line should be indented from the left edge of the -window. -\fIPixels\fR may have any of the standard forms for screen -distances. -If a line of text wraps, this option only applies to the -first line on the display; the \fB\-lmargin2\fR option controls -the indentation for subsequent lines. +option has been specified, then \fIpixels\fR specifies how much the line +should be indented from the left edge of the window. \fIPixels\fR may have any +of the standard forms for screen distances. If a line of text wraps, this +option only applies to the first line on the display; the \fB\-lmargin2\fR +option controls the indentation for subsequent lines. .TP \fB\-lmargin2 \fIpixels\fR +. If the first non-elided character of a display line has a tag for which this -option has been specified, and if the display line is not the -first for its text line (i.e., the text line has wrapped), then -\fIpixels\fR specifies how much the line should be indented from -the left edge of the window. -\fIPixels\fR may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled, and it only -applies to the second and later display lines for a text line. +option has been specified, and if the display line is not the first for its +text line (i.e., the text line has wrapped), then \fIpixels\fR specifies how +much the line should be indented from the left edge of the window. +\fIPixels\fR may have any of the standard forms for screen distances. This +option is only used when wrapping is enabled, and it only applies to the +second and later display lines for a text line. .TP \fB\-offset \fIpixels\fR -\fIPixels\fR specifies an amount by which the text's baseline -should be offset vertically from the baseline of the overall -line, in pixels. -For example, a positive offset can be used for superscripts -and a negative offset can be used for subscripts. -\fIPixels\fR may have any of the standard forms for screen +. +\fIPixels\fR specifies an amount by which the text's baseline should be offset +vertically from the baseline of the overall line, in pixels. For example, a +positive offset can be used for superscripts and a negative offset can be used +for subscripts. \fIPixels\fR may have any of the standard forms for screen distances. .TP \fB\-overstrike \fIboolean\fR -Specifies whether or not to draw a horizontal rule through -the middle of characters. -\fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. +. +Specifies whether or not to draw a horizontal rule through the middle of +characters. \fIBoolean\fR may have any of the forms accepted by +\fBTcl_GetBoolean\fR. .TP \fB\-relief \fIrelief\fR -\fIRelief\fR specifies the 3-D relief to use for drawing backgrounds, -in any of the forms accepted by \fBTk_GetRelief\fR. -This option is used in conjunction with the \fB\-borderwidth\fR -option to give a 3-D appearance to the background for characters; -it is ignored unless the \fB\-background\fR option -has been set for the tag. +. +\fIRelief\fR specifies the relief style to use for drawing the border, in any +of the forms accepted by \fBTk_GetRelief\fR. This option is used in +conjunction with the \fB\-borderwidth\fR option to enable to the desired +border appearance. .TP \fB\-rmargin \fIpixels\fR +. If the first non-elided character of a display line has a tag for which this -option has been specified, then \fIpixels\fR specifies how wide -a margin to leave between the end of the line and the right -edge of the window. -\fIPixels\fR may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled. -If a text line wraps, the right margin for each line on the -display is determined by the first non-elided character of that display -line. +option has been specified, then \fIpixels\fR specifies how wide a margin to +leave between the end of the line and the right edge of the window. +\fIPixels\fR may have any of the standard forms for screen distances. This +option is only used when wrapping is enabled. If a text line wraps, the right +margin for each line on the display is determined by the first non-elided +character of that display line. .TP \fB\-spacing1 \fIpixels\fR -\fIPixels\fR specifies how much additional space should be -left above each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the first -line on the display. +. +\fIPixels\fR specifies how much additional space should be left above each +text line, using any of the standard forms for screen distances. If a line +wraps, this option only applies to the first line on the display. .TP \fB\-spacing2 \fIpixels\fR -For lines that wrap, this option specifies how much additional -space to leave between the display lines for a single text line. -\fIPixels\fR may have any of the standard forms for screen -distances. +. +For lines that wrap, this option specifies how much additional space to leave +between the display lines for a single text line. \fIPixels\fR may have any of +the standard forms for screen distances. .TP \fB\-spacing3 \fIpixels\fR -\fIPixels\fR specifies how much additional space should be -left below each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the last -line on the display. +. +\fIPixels\fR specifies how much additional space should be left below each +text line, using any of the standard forms for screen distances. If a line +wraps, this option only applies to the last line on the display. .TP \fB\-tabs \fItabList\fR -\fITabList\fR specifies a set of tab stops in the same form -as for the \fB\-tabs\fR option for the text widget. This -option only applies to a display line if it applies to the -first non-elided character on that display line. -If this option is specified as an empty string, it cancels -the option, leaving it unspecified for the tag (the default). -If the option is specified as a non-empty string that is -an empty list, such as \fB\-tags\0{\0}\fR, then it requests -default 8-character tabs as described for the \fB\-tags\fR -widget option. +. +\fITabList\fR specifies a set of tab stops in the same form as for the +\fB\-tabs\fR option for the text widget. This option only applies to a display +line if it applies to the first non-elided character on that display line. If +this option is specified as an empty string, it cancels the option, leaving it +unspecified for the tag (the default). If the option is specified as a +non-empty string that is an empty list, such as \fB\-tags\0{\0}\fR, then it +requests default 8-character tabs as described for the \fB\-tags\fR widget +option. .TP \fB\-tabstyle \fIstyle\fR -\fIStyle\fR specifies either the \fItabular\fR or -\fIwordprocessor\fR style of tabbing to use for the text widget. -This option only applies to a display line if it applies to the -first non-elided character on that display line. -If this option is specified as an empty string, it cancels -the option, leaving it unspecified for the tag (the default). +. +\fIStyle\fR specifies either the \fItabular\fR or \fIwordprocessor\fR style of +tabbing to use for the text widget. This option only applies to a display line +if it applies to the first non-elided character on that display line. If this +option is specified as an empty string, it cancels the option, leaving it +unspecified for the tag (the default). .TP \fB\-underline \fIboolean\fR +. \fIBoolean\fR specifies whether or not to draw an underline underneath -characters. -It may have any of the forms accepted by \fBTcl_GetBoolean\fR. +characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR. .TP \fB\-wrap \fImode\fR -\fIMode\fR specifies how to handle lines that are wider than the -text's window. -It has the same legal values as the \fB\-wrap\fR option -for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. -If this tag option is specified, it overrides the \fB\-wrap\fR option -for the text widget. -.PP -If a character has several tags associated with it, and if their -display options conflict, then the options of the highest priority -tag are used. -If a particular display option has not been specified for a -particular tag, or if it is specified as an empty string, then -that option will never be used; the next-highest-priority -tag's option will used instead. -If no tag specifies a particular display option, then the default -style for the widget will be used. -.PP -The second purpose for tags is event bindings. -You can associate bindings with a tag in much the same way you can -associate bindings with a widget class: whenever particular X -events occur on characters with the given tag, a given -Tcl command will be executed. -Tag bindings can be used to give behaviors to ranges of characters; -among other things, this allows hypertext-like -features to be implemented. -For details, see the description of the +. +\fIMode\fR specifies how to handle lines that are wider than the text's +window. It has the same legal values as the \fB\-wrap\fR option for the text +widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. If this tag option is +specified, it overrides the \fB\-wrap\fR option for the text widget. +.PP +If a character has several tags associated with it, and if their display +options conflict, then the options of the highest priority tag are used. If a +particular display option has not been specified for a particular tag, or if +it is specified as an empty string, then that option will never be used; the +next-highest-priority tag's option will used instead. If no tag specifies a +particular display option, then the default style for the widget will be used. +.PP +The second purpose for tags is event bindings. You can associate bindings with +a tag in much the same way you can associate bindings with a widget class: +whenever particular X events occur on characters with the given tag, a given +Tcl command will be executed. Tag bindings can be used to give behaviors to +ranges of characters; among other things, this allows hypertext-like features +to be implemented. For details, see the description of the .QW "\fIpathName \fBtag bind\fR" -widget command below. -.VS 8.5 -Tag bindings are shared between all peer widgets +widget command below. 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 +.PP +The third use for tags is in managing the selection. See \fBTHE SELECTION\fR +below. With the exception of the special \fBsel\fR tag, all tags are shared +between peer text widgets, and may be manipulated on an equal basis from any +such widget. The \fBsel\fR tag exists separately and independently in each +peer text widget (but any tag bindings to \fBsel\fR are shared). .SH MARKS .PP -The second form of annotation in text widgets is a mark. -Marks are used for remembering particular places in a text. -They are something like tags, in that they have names and -they refer to places in the file, but a mark is not associated -with particular characters. -Instead, a mark is associated with the gap between two characters. -Only a single position may be associated with a mark at any given -time. -If the characters around a mark are deleted the mark will still -remain; it will just have new neighbor characters. -In contrast, if the characters containing a tag are deleted then -the tag will no longer have an association with characters in -the file. -Marks may be manipulated with the +The second form of annotation in text widgets is a mark. Marks are used for +remembering particular places in a text. They are something like tags, in that +they have names and they refer to places in the file, but a mark is not +associated with particular characters. Instead, a mark is associated with the +gap between two characters. Only a single position may be associated with a +mark at any given time. If the characters around a mark are deleted the mark +will still remain; it will just have new neighbor characters. In contrast, if +the characters containing a tag are deleted then the tag will no longer have +an association with characters in the file. Marks may be manipulated with the .QW "\fIpathName \fBmark\fR" -widget -command, and their current locations may be determined by using the +widget command, and their current locations may be determined by using the mark name as an index in widget commands. .PP Each mark also has a .QW gravity , -which is either \fBleft\fR or \fBright\fR. -The gravity for a mark specifies what happens to the mark when -text is inserted at the point of the mark. -If a mark has left gravity, then the mark is treated as if it -were attached to the character on its left, so the mark will -remain to the left of any text inserted at the mark position. -If the mark has right gravity, new text inserted at the mark -position will appear to the left of the mark (so that the mark -remains rightmost). The gravity for a mark defaults to \fBright\fR. -.PP -The name space for marks is different from that for tags: the -same name may be used for both a mark and a tag, but they will refer -to different things. -.PP -Two marks have special significance. -First, the mark \fBinsert\fR is associated with the insertion cursor, -as described under \fBTHE INSERTION CURSOR\fR below. -Second, the mark \fBcurrent\fR is associated with the character -closest to the mouse and is adjusted automatically to track the -mouse position and any changes to the text in the widget (one -exception: \fBcurrent\fR is not updated in response to mouse -motions if a mouse button is down; the update will be deferred -until all mouse buttons have been released). -Neither of these special marks may be deleted. -.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 +which is either \fBleft\fR or \fBright\fR. The gravity for a mark specifies +what happens to the mark when text is inserted at the point of the mark. If a +mark has left gravity, then the mark is treated as if it were attached to the +character on its left, so the mark will remain to the left of any text +inserted at the mark position. If the mark has right gravity, new text +inserted at the mark position will appear to the left of the mark (so that the +mark remains rightmost). The gravity for a mark defaults to \fBright\fR. +.PP +The name space for marks is different from that for tags: the same name may be +used for both a mark and a tag, but they will refer to different things. +.PP +Two marks have special significance. First, the mark \fBinsert\fR is +associated with the insertion cursor, as described under +\fBTHE INSERTION CURSOR\fR +below. Second, the mark \fBcurrent\fR is associated with the +character closest to the mouse and is adjusted automatically to track the +mouse position and any changes to the text in the widget (one exception: +\fBcurrent\fR is not updated in response to mouse motions if a mouse button is +down; the update will be deferred until all mouse buttons have been released). +Neither of these special marks may be deleted. With the exception of these two +special marks, all marks are shared between peer text widgets, and may be +manipulated on an equal basis from any peer. .SH "EMBEDDED WINDOWS" .PP -The third form of annotation in text widgets is an embedded window. -Each embedded window annotation causes a window to be displayed -at a particular point in the text. -There may be any number of embedded windows in a text widget, -and any widget may be used as an embedded window (subject to the -usual rules for geometry management, which require the text window -to be the parent of the embedded window or a descendant of its -parent). -.PP -The embedded window's position on the screen will be updated as the -text is modified or scrolled, and it will be mapped and unmapped as -it moves into and out of the visible area of the text widget. -Each embedded window occupies one -.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 -.VS 8.5 -Eliding an embedded window immediately after scheduling it for creation -via \fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it -from being effectively created. -Uneliding an elided embedded window scheduled for creation via -\fIpathName \fBwindow create \fIindex \fB-create\fR will automatically -trigger the associated creation script. -After destroying an elided embedded window, the latter won't get -automatically recreated. -.VE 8.5 -.PP -When an embedded window is added to a text widget with the -\fIpathName \fBwindow create\fR widget command, several configuration -options may be associated with it. -These options may be modified later with the \fIpathName \fBwindow configure\fR -widget command. -The following options are currently supported: +The third form of annotation in text widgets is an embedded window. Each +embedded window annotation causes a window to be displayed at a particular +point in the text. There may be any number of embedded windows in a text +widget, and any widget may be used as an embedded window (subject to the usual +rules for geometry management, which require the text window to be the parent +of the embedded window or a descendant of its parent). +.PP +The embedded window's position on the screen will be updated as the text is +modified or scrolled, and it will be mapped and unmapped as it moves into and +out of the visible area of the text widget. Each embedded window occupies one +unit's worth of index space in the text widget, and it may be referred to +either by the name of its embedded window or by its position in the widget's +index space. If the range of text containing the embedded window is deleted +then the window is destroyed. Similarly if the text widget as a whole is +deleted, then the window is destroyed. +.PP +Eliding an embedded window immediately after scheduling it for creation via +\fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it from being +effectively created. Uneliding an elided embedded window scheduled for creation +via \fIpathName \fBwindow create \fIindex \fB-create\fR will automatically +trigger the associated creation script. After destroying an elided embedded +window, the latter won't get automatically recreated. +.PP +When an embedded window is added to a text widget with the \fIpathName +\fBwindow create\fR widget command, several configuration options may be +associated with it. These options may be modified later with the \fIpathName +\fBwindow configure\fR widget command. The following options are currently +supported: .TP \fB\-align \fIwhere\fR -If the window is not as tall as the line in which it is displayed, -this option determines where the window is displayed in the line. -\fIWhere\fR must have one of the values \fBtop\fR (align the top of the window -with the top of the line), \fBcenter\fR (center the window -within the range of the line), \fBbottom\fR (align the bottom of the -window with the bottom of the line's area), -or \fBbaseline\fR (align the bottom of the window with the baseline -of the line). +. +If the window is not as tall as the line in which it is displayed, this option +determines where the window is displayed in the line. \fIWhere\fR must have +one of the values \fBtop\fR (align the top of the window with the top of the +line), \fBcenter\fR (center the window within the range of the line), +\fBbottom\fR (align the bottom of the window with the bottom of the line's +area), or \fBbaseline\fR (align the bottom of the window with the baseline of +the line). .TP \fB\-create \fIscript\fR -Specifies a Tcl script that may be evaluated to create the window -for the annotation. -If no \fB\-window\fR option has been specified for the annotation -this script will be evaluated when the annotation is about to -be displayed on the screen. -\fIScript\fR must create a window for the annotation and return -the name of that window as its result. -.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. +. +Specifies a Tcl script that may be evaluated to create the window for the +annotation. If no \fB\-window\fR option has been specified for the annotation +this script will be evaluated when the annotation is about to be displayed on +the screen. \fIScript\fR must create a window for the annotation and return +the name of that window as its result. Two substitutions will be performed in +\fIscript\fR before evaluation. \fI%W\fR will be substituted by the name of +the parent text widget, and \fI%%\fR will be substituted by a single \fI%\fR. +If the annotation's window should ever be deleted, \fIscript\fR will be +evaluated again the next time the annotation is displayed. .TP \fB\-padx \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -each side of the embedded window. -It may have any of the usual forms defined for a screen distance. +. +\fIPixels\fR specifies the amount of extra space to leave on each side of the +embedded window. It may have any of the usual forms defined for a screen +distance. .TP \fB\-pady \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -the top and on the bottom of the embedded window. -It may have any of the usual forms defined for a screen distance. +. +\fIPixels\fR specifies the amount of extra space to leave on the top and on +the bottom of the embedded window. It may have any of the usual forms defined +for a screen distance. .TP \fB\-stretch \fIboolean\fR -If the requested height of the embedded window is less than the -height of the line in which it is displayed, this option can be -used to specify whether the window should be stretched vertically -to fill its line. -If the \fB\-pady\fR option has been specified as well, then the -requested padding will be retained even if the window is -stretched. +. +If the requested height of the embedded window is less than the height of the +line in which it is displayed, this option can be used to specify whether the +window should be stretched vertically to fill its line. If the \fB\-pady\fR +option has been specified as well, then the requested padding will be retained +even if the window is stretched. .TP \fB\-window \fIpathName\fR -Specifies the name of a window to display in the annotation. -.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 +. +Specifies the name of a window to display in the annotation. Note that if a +\fIpathName\fR has been set, then later configuring a window to the empty +string will not delete the widget corresponding to the old \fIpathName\fR. +Rather it will remove the association between the old \fIpathName\fR and the +text widget. If multiple peer widgets are in use, it is usually simpler to use +the \fB\-create\fR option if embedded windows are desired in each peer. .SH "EMBEDDED IMAGES" .PP -The final form of annotation in text widgets is an embedded image. -Each embedded image annotation causes an image to be displayed -at a particular point in the text. -There may be any number of embedded images in a text widget, -and a particular image may be embedded in multiple places in the same +The final form of annotation in text widgets is an embedded image. Each +embedded image annotation causes an image to be displayed at a particular +point in the text. There may be any number of embedded images in a text +widget, and a particular image may be embedded in multiple places in the same text widget. .PP -The embedded image's position on the screen will be updated as the -text is modified or scrolled. -Each embedded image occupies one -.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 \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 -.VS 8.5 -Eliding an embedded image immediately after scheduling it for creation -via \fIpathName \fBimage create \fIindex \fB-create\fR will prevent it -from being effectively created. -Uneliding an elided embedded image scheduled for creation via -\fIpathName \fBimage create \fIindex \fB-create\fR will automatically -trigger the associated creation script. -After destroying an elided embedded image, the latter won't get -automatically recreated. -.VE 8.5 +The embedded image's position on the screen will be updated as the text is +modified or scrolled. Each embedded image occupies one unit's worth of index +space in the text widget, and it may be referred to either by its position in +the widget's index space, or the name it is assigned when the image is inserted +into the text widget with \fIpathName \fBimage create\fR. If the range of text +containing the embedded image is deleted then that copy of the image is removed +from the screen. +.PP +Eliding an embedded image immediately after scheduling it for creation via +\fIpathName \fBimage create \fIindex \fB-create\fR will prevent it from being +effectively created. Uneliding an elided embedded image scheduled for creation +via \fIpathName \fBimage create \fIindex \fB-create\fR will automatically +trigger the associated creation script. After destroying an elided embedded +image, the latter won't get automatically recreated. +.PP +When an embedded image is added to a text widget with the \fIpathName \fBimage +create\fR widget command, a name unique to this instance of the image is +returned. This name may then be used to refer to this image instance. The name +is taken to be the value of the \fB\-name\fR option (described below). If the +\fB\-name\fR option is not provided, the \fB\-image\fR name is used instead. +If the \fIimageName\fR is already in use in the text widget, then \fB#\fInn\fR +is added to the end of the \fIimageName\fR, where \fInn\fR is an arbitrary +integer. This insures the \fIimageName\fR is unique. Once this name is +assigned to this instance of the image, it does not change, even though the +\fB\-image\fR or \fB\-name\fR values can be changed with \fIpathName \fBimage +configure\fR. .PP When an embedded image is added to a text widget with the \fIpathName \fBimage -create\fR widget command, a name unique to this instance of the image -is returned. This name may then be used to refer to this image -instance. The name is taken to be the value of the \fB\-name\fR option -(described below). If the \fB\-name\fR option is not provided, the -\fB\-image\fR name is used instead. If the \fIimageName\fR is already -in use in the text widget, then \fB#\fInn\fR is added to the end of the -\fIimageName\fR, where \fInn\fR is an arbitrary integer. This insures -the \fIimageName\fR is unique. -Once this name is assigned to this instance of the image, it does not -change, even though the \fB\-image\fR or \fB\-name\fR values can be changed -with \fIpathName \fBimage configure\fR. -.PP -When an embedded image is added to a text widget with the -\fIpathName \fBimage create\fR widget command, several configuration -options may be associated with it. -These options may be modified later with the \fIpathName \fBimage configure\fR -widget command. -The following options are currently supported: +create\fR widget command, several configuration options may be associated with +it. These options may be modified later with the \fIpathName \fBimage +configure\fR widget command. The following options are currently supported: .TP \fB\-align \fIwhere\fR -If the image is not as tall as the line in which it is displayed, -this option determines where the image is displayed in the line. -\fIWhere\fR must have one of the values \fBtop\fR (align the top of the image -with the top of the line), \fBcenter\fR (center the image -within the range of the line), \fBbottom\fR (align the bottom of the -image with the bottom of the line's area), -or \fBbaseline\fR (align the bottom of the image with the baseline -of the line). +. +If the image is not as tall as the line in which it is displayed, this option +determines where the image is displayed in the line. \fIWhere\fR must have one +of the values \fBtop\fR (align the top of the image with the top of the line), +\fBcenter\fR (center the image within the range of the line), \fBbottom\fR +(align the bottom of the image with the bottom of the line's area), or +\fBbaseline\fR (align the bottom of the image with the baseline of the line). .TP \fB\-image \fIimage\fR -Specifies the name of the Tk image to display in the annotation. -If \fIimage\fR is not a valid Tk image, then an error is returned. +. +Specifies the name of the Tk image to display in the annotation. If +\fIimage\fR is not a valid Tk image, then an error is returned. .TP \fB\-name \fIImageName\fR -Specifies the name by which this image instance may be referenced in -the text widget. If \fIImageName\fR is not supplied, then the -name of the Tk image is used instead. -If the \fIimageName\fR is already in use, \fI#nn\fR is appended to -the end of the name as described above. +. +Specifies the name by which this image instance may be referenced in the text +widget. If \fIImageName\fR is not supplied, then the name of the Tk image is +used instead. If the \fIimageName\fR is already in use, \fI#nn\fR is appended +to the end of the name as described above. .TP \fB\-padx \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -each side of the embedded image. -It may have any of the usual forms defined for a screen distance. +. +\fIPixels\fR specifies the amount of extra space to leave on each side of the +embedded image. It may have any of the usual forms defined for a screen +distance. .TP \fB\-pady \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -the top and on the bottom of the embedded image. -It may have any of the usual forms defined for a screen distance. +. +\fIPixels\fR specifies the amount of extra space to leave on the top and on +the bottom of the embedded image. It may have any of the usual forms defined +for a screen distance. .SH "THE SELECTION" .PP -Selection support is implemented via tags. -If the \fBexportSelection\fR option for the text widget is true -then the \fBsel\fR tag will be associated with the selection: +Selection support is implemented via tags. If the \fB\-exportselection\fR option +for the text widget is true then the \fBsel\fR tag will be associated with the +selection: .IP [1] -Whenever characters are tagged with \fBsel\fR the text widget -will claim ownership of the selection. +Whenever characters are tagged with \fBsel\fR the text widget will claim +ownership of the selection. .IP [2] -Attempts to retrieve the -selection will be serviced by the text widget, returning all the -characters with the \fBsel\fR tag. +Attempts to retrieve the selection will be serviced by the text widget, +returning all the characters with the \fBsel\fR tag. .IP [3] -If the selection is claimed away by another application or by another -window within this application, then the \fBsel\fR tag will be removed -from all characters in the text. +If the selection is claimed away by another application or by another window +within this application, then the \fBsel\fR tag will be removed from all +characters in the text. .IP [4] -Whenever the \fBsel\fR tag range changes a virtual event -\fB<<Selection>>\fR is generated. +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 +The \fBsel\fR tag is automatically defined when a text widget is created, and +it may not be deleted with the .QW "\fIpathName \fBtag delete\fR" -widget command. Furthermore, the \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 +widget command. Furthermore, the \fB\-selectbackground\fR, +\fB\-selectborderwidth\fR, and \fB\-selectforeground\fR options for the text +widget are tied to the \fB\-background\fR, \fB\-borderwidth\fR, and +\fB\-foreground\fR options for the \fBsel\fR tag: changes in either will +automatically be reflected in the other. Also the +\fB\-inactiveselectbackground\fR option for the text widget is used instead of +\fB\-selectbackground\fR when the text widget does not have the focus. This +allows programmatic control over the visualization of the \fBsel\fR tag for +foreground and background windows, or to have \fBsel\fR not shown at all (when +\fB\-inactiveselectbackground\fR is empty) for background windows. Each peer +text widget has its own \fBsel\fR tag which can be separately configured and +set. .SH "THE INSERTION CURSOR" .PP -The mark named \fBinsert\fR has special significance in text widgets. -It is defined automatically when a text widget is created and it -may not be unset with the +The mark named \fBinsert\fR has special significance in text widgets. It is +defined automatically when a text widget is created and it may not be unset +with the .QW "\fIpathName \fBmark unset\fR" -widget command. -The \fBinsert\fR mark represents the position of the insertion -cursor, and the insertion cursor will automatically be drawn at -this point whenever the text widget has the input focus. +widget command. The \fBinsert\fR mark represents the position of the insertion +cursor, and the insertion cursor will automatically be drawn at this point +whenever the text widget has the input focus. .SH "THE MODIFIED FLAG" -The text widget can keep track of changes to the content of the widget -by means of the modified flag. Inserting or deleting text will set -this flag. The flag can be queried, set and cleared programmatically -as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual -event is generated. See the \fIpathName \fBedit modified\fR widget command for -more details. +.PP +The text widget can keep track of changes to the content of the widget by +means of the modified flag. Inserting or deleting text will set this flag. The +flag can be queried, set and cleared programmatically as well. Whenever the +flag changes state a \fB<<Modified>>\fR virtual event is generated. See the +\fIpathName \fBedit modified\fR widget command for more details. .SH "THE UNDO MECHANISM" .PP The text widget has an unlimited undo and redo mechanism (when the -\fB\-undo\fR widget option is true) which records every insert and -delete action on a stack. +\fB\-undo\fR widget option is true) which records every insert and delete +action on a stack. .PP Boundaries (called .QW separators ) -are inserted between edit actions. The -purpose of these separators is to group inserts, deletes and replaces -into one compound edit action. When undoing a change everything between -two separators will be undone. The undone changes are then moved to the -redo stack, so that an undone edit can be redone again. The redo stack -is cleared whenever new edit actions are recorded on the undo stack. The -undo and redo stacks can be cleared to keep their depth under control. -.PP -Separators are inserted automatically when the \fB\-autoseparators\fR -widget option is true. You can insert separators programmatically as -well. If a separator is already present at the top of the undo stack -no other will be inserted. That means that two separators on the undo -stack are always separated by at least one insert or delete action. -.PP -The undo mechanism is also linked to the modified flag. This means -that undoing or redoing changes can take a modified text widget back -to the unmodified state or vice versa. The modified flag will be set -automatically to the appropriate state. This automatic coupling -does not work when the modified flag has been set by the user, until -the flag has been reset again. +are inserted between edit actions. The purpose of these separators is to group +inserts, deletes and replaces into one compound edit action. When undoing a +change everything between two separators will be undone. The undone changes +are then moved to the redo stack, so that an undone edit can be redone again. +The redo stack is cleared whenever new edit actions are recorded on the undo +stack. The undo and redo stacks can be cleared to keep their depth under +control. +.PP +Separators are inserted automatically when the \fB\-autoseparators\fR widget +option is true. You can insert separators programmatically as well. If a +separator is already present at the top of the undo stack no other will be +inserted. That means that two separators on the undo stack are always +separated by at least one insert or delete action. +.PP +The undo mechanism is also linked to the modified flag. This means that +undoing or redoing changes can take a modified text widget back to the +unmodified state or vice versa. The modified flag will be set automatically to +the appropriate state. This automatic coupling does not work when the modified +flag has been set by the user, until the flag has been reset again. .PP See below for the \fIpathName \fBedit\fR widget command that controls the undo mechanism. .SH "PEER WIDGETS" .PP -.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. +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. +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 +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 +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 "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" .PP In order to maintain a responsive user-experience, the text widget calculates @@ -1139,452 +996,431 @@ if {![$w pendingsync]} { .CE .SH "WIDGET COMMAND" .PP -The \fBtext\fR command creates a new Tcl command whose -name is the same as the path name of the text's window. This -command may be used to invoke various -operations on the widget. It has the following general form: +The \fBtext\fR command creates a new Tcl command whose name is the same as the +path name of the text's window. This command may be used to invoke various +operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg arg ...\fR? .CE -\fIPathName\fR is the name of the command, which is the same as -the text widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for text widgets: +\fIPathName\fR is the name of the command, which is the same as the text +widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact +behavior of the command. The following commands are possible for text widgets: .TP \fIpathName \fBbbox \fIindex\fR -Returns a list of four elements describing the screen area -of the character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -character, and the last two elements give the width and height -of the area. -If the character is only partially visible on the screen, then -the return value reflects just the visible part. -If the character is not visible on the screen then the return -value is an empty list. +. +Returns a list of four elements describing the screen area of the character +given by \fIindex\fR. The first two elements of the list give the x and y +coordinates of the upper-left corner of the area occupied by the character, +and the last two elements give the width and height of the area. If the +character is only partially visible on the screen, then the return value +reflects just the visible part. If the character is not visible on the screen +then the return value is an empty list. .TP \fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBtext\fR -command. +. +Returns the current value of the configuration option given by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBtext\fR command. .TP \fIpathName \fBcompare\fR \fIindex1 op index2\fR -Compares the indices given by \fIindex1\fR and \fIindex2\fR according -to the relational operator given by \fIop\fR, and returns 1 if -the relationship is satisfied and 0 if it is not. -\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. -If \fIop\fR is == then 1 is returned if the two indices refer to -the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR -refers to an earlier character in the text than \fIindex2\fR, and -so on. +. +Compares the indices given by \fIindex1\fR and \fIindex2\fR according to the +relational operator given by \fIop\fR, and returns 1 if the relationship is +satisfied and 0 if it is not. \fIOp\fR must be one of the operators <, <=, ==, +>=, >, or !=. If \fIop\fR is == then 1 is returned if the two indices refer to +the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR refers +to an earlier character in the text than \fIindex2\fR, and so on. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBtext\fR -command. -.VS 8.5 +. +Query or modify the configuration options of the widget. If no \fIoption\fR is +specified, returns a list describing all of the available options for +\fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of +this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command +returns a list describing the one named option (this list will be identical to +the corresponding sublist of the value returned if no \fIoption\fR is +specified). If one or more \fIoption\-value\fR pairs are specified, then the +command modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. \fIOption\fR may have any of +the values accepted by the \fBtext\fR command. .TP \fIpathName \fBcount\fR \fI?options\fR? \fIindex1 index2\fR -Counts the number of relevant things between the two indices. -If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number -(and this holds for each of the possible options). -The actual items which are counted depend on the -options given. The result is a list of integers, one for the result of -each counting option given. Valid counting options are \fB\-chars\fR, +. +Counts the number of relevant things between the two indices. If \fIindex1\fR +is after \fIindex2\fR, the result will be a negative number (and this holds +for each of the possible options). The actual items which are counted depend +on the options given. The result is a list of integers, one for the result of +each counting option given. Valid counting options are \fB\-chars\fR, \fB\-displaychars\fR, \fB\-displayindices\fR, \fB\-displaylines\fR, \fB\-indices\fR, \fB\-lines\fR, \fB\-xpixels\fR and \fB\-ypixels\fR. The default value, if no option is specified, is \fB\-indices\fR. There is an additional possible option \fB\-update\fR which is a modifier. If given (and if the text widget is managed by a geometry manager), then all subsequent -options ensure that any possible out of date information is recalculated. -This currently only has any effect for the \fI\-ypixels\fR count (which, if +options ensure that any possible out of date information is recalculated. +This currently only has any effect for the \fB\-ypixels\fR count (which, if \fB\-update\fR is not given, will use the text widget's current cached value for each line). This \fB\-update\fR option is obsoleted by \fIpathName \fBsync\fR, \fIpathName \fBpendingsync\fR and \fB<<WidgetViewSync>>\fR. The count options are interpreted as follows: .RS .IP \fB\-chars\fR -count all characters, whether elided or not. Do not count -embedded windows or images. +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. +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. +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. +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 +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 +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 +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 -false values accepted by Tcl_GetBoolean. -If the value is a true one then internal consistency checks will be -turned on in the B-tree code associated with text widgets. -If \fIboolean\fR has a false value then the debugging checks will -be turned off. -In either case the command returns an empty string. -If \fIboolean\fR is not specified then the command returns \fBon\fR -or \fBoff\fR to indicate whether or not debugging is turned on. -There is a single debugging switch shared by all text widgets: turning -debugging on or off in any widget turns it on or off for all widgets. -For widgets with large amounts of text, the consistency checks may -cause a noticeable slow-down. +. +If \fIboolean\fR is specified, then it must have one of the true or false +values accepted by Tcl_GetBoolean. If the value is a true one then internal +consistency checks will be turned on in the B-tree code associated with text +widgets. If \fIboolean\fR has a false value then the debugging checks will be +turned off. In either case the command returns an empty string. If +\fIboolean\fR is not specified then the command returns \fBon\fR or \fBoff\fR +to indicate whether or not debugging is turned on. There is a single debugging +switch shared by all text widgets: turning debugging on or off in any widget +turns it on or off for all widgets. For widgets with large amounts of text, +the consistency checks may cause a noticeable slow-down. .RS .PP -When debugging is turned on, the drawing routines of the text widget -set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR -to the lists of indices that are redrawn. The values of these variables -are tested by Tk's test suite. +When debugging is turned on, the drawing routines of the text widget set the +global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of +indices that are redrawn. The values of these variables are tested by Tk's +test suite. .RE .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? -Delete a range of characters from the text. -If both \fIindex1\fR and \fIindex2\fR are specified, then delete -all the characters starting with the one given by \fIindex1\fR -and stopping just before \fIindex2\fR (i.e. the character at -\fIindex2\fR is not deleted). -If \fIindex2\fR does not specify a position later in the text -than \fIindex1\fR then no characters are deleted. -If \fIindex2\fR is not specified then the single character at -\fIindex1\fR is deleted. -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. -If more indices are given, multiple ranges of text will be deleted. -All indices are first checked for validity before any deletions are made. -They are sorted and the text is removed from the last range to the -first range so deleted text does not cause an undesired index shifting -side-effects. If multiple ranges with the same start index are given, -then the longest range is used. If overlapping ranges are given, then -they will be merged into spans that do not cause deletion of text -outside the given ranges due to text shifted during deletion. +. +Delete a range of characters from the text. If both \fIindex1\fR and +\fIindex2\fR are specified, then delete all the characters starting with the +one given by \fIindex1\fR and stopping just before \fIindex2\fR (i.e. the +character at \fIindex2\fR is not deleted). If \fIindex2\fR does not specify a +position later in the text than \fIindex1\fR then no characters are deleted. +If \fIindex2\fR is not specified then the single character at \fIindex1\fR is +deleted. 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. If more indices are given, multiple ranges of text will be deleted. +All indices are first checked for validity before any deletions are made. They +are sorted and the text is removed from the last range to the first range so +deleted text does not cause an undesired index shifting side-effects. If +multiple ranges with the same start index are given, then the longest range is +used. If overlapping ranges are given, then they will be merged into spans +that do not cause deletion of text outside the given ranges due to text +shifted during deletion. .TP \fIpathName \fBdlineinfo \fIindex\fR -Returns a list with five elements describing the area occupied -by the display line containing \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -line, the third and fourth elements give the width and height -of the area, and the fifth element gives the position of the baseline -for the line, measured down from the top of the area. -All of this information is measured in pixels. -If the current wrap mode is \fBnone\fR and the line extends beyond -the boundaries of the window, -the area returned reflects the entire area of the line, including the -portions that are out of the window. -If the line is shorter than the full width of the window then the -area returned reflects just the portion of the line that is occupied -by characters and embedded windows. -If the display line containing \fIindex\fR is not visible on -the screen then the return value is an empty list. +. +Returns a list with five elements describing the area occupied by the display +line containing \fIindex\fR. The first two elements of the list give the x and +y coordinates of the upper-left corner of the area occupied by the line, the +third and fourth elements give the width and height of the area, and the fifth +element gives the position of the baseline for the line, measured down from +the top of the area. All of this information is measured in pixels. If the +current wrap mode is \fBnone\fR and the line extends beyond the boundaries of +the window, the area returned reflects the entire area of the line, including +the portions that are out of the window. If the line is shorter than the full +width of the window then the area returned reflects just the portion of the +line that is occupied by characters and embedded windows. If the display line +containing \fIindex\fR is not visible on the screen then the return value is +an empty list. .TP \fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? -Return the contents of the text widget from \fIindex1\fR up to, -but not including \fIindex2\fR, -including the text and -information about marks, tags, and embedded windows. -If \fIindex2\fR is not specified, then it defaults to -one character past \fIindex1\fR. The information is returned -in the following format: +. +Return the contents of the text widget from \fIindex1\fR up to, but not +including \fIindex2\fR, including the text and information about marks, tags, +and embedded windows. If \fIindex2\fR is not specified, then it defaults to +one character past \fIindex1\fR. The information is returned in the following +format: .RS .LP \fIkey1 value1 index1 key2 value2 index2\fR ... .LP -The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, -\fBtagon\fR, \fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding -\fIvalue\fR is the text, mark name, tag name, image name, or window name. -The \fIindex\fR information is the index of the -start of the text, mark, tag transition, image or window. -One or more of the following switches (or abbreviations thereof) +The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR, +\fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding \fIvalue\fR is +the text, mark name, tag name, image name, or window name. The \fIindex\fR +information is the index of the start of the text, mark, tag transition, image +or window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump: .TP \fB\-all\fR +. Return information about all elements: text, marks, tags, images and windows. This is the default. .TP \fB\-command \fIcommand\fR +. Instead of returning the information as the result of the dump operation, invoke the \fIcommand\fR on each element of the text widget within the range. -The command has three arguments appended to it before it is evaluated: -the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. +The command has three arguments appended to it before it is evaluated: the +\fIkey\fR, \fIvalue\fR, and \fIindex\fR. .TP \fB\-image\fR +. Include information about images in the dump results. .TP \fB\-mark\fR +. Include information about marks in the dump results. .TP \fB\-tag\fR -Include information about tag transitions in the dump results. Tag -information is returned as \fBtagon\fR and \fBtagoff\fR elements that -indicate the begin and end of each range of each tag, respectively. +. +Include information about tag transitions in the dump results. Tag information +is returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the begin +and end of each range of each tag, respectively. .TP \fB\-text\fR -Include information about text in the dump results. The value is the -text up to the next element or the end of range indicated by \fIindex2\fR. -A text element does not span newlines. A multi-line block of text that -contains no marks or tag transitions will still be dumped as a set -of text segments that each end with a newline. The newline is part -of the value. +. +Include information about text in the dump results. The value is the text up +to the next element or the end of range indicated by \fIindex2\fR. A text +element does not span newlines. A multi-line block of text that contains no +marks or tag transitions will still be dumped as a set of text segments that +each end with a newline. The newline is part of the value. .TP \fB\-window\fR -Include information about embedded windows in the dump results. -The value of a window is its Tk pathname, unless the window -has not been created yet. (It must have a create script.) -In this case an empty string is returned, and you must query the -window by its index position to get more information. +. +Include information about embedded windows in the dump results. The value of a +window is its Tk pathname, unless the window has not been created yet. (It +must have a create script.) In this case an empty string is returned, and you +must query the window by its index position to get more information. .RE .TP \fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? -This command controls the undo mechanism and the modified flag. The -exact behavior of the command depends on the \fIoption\fR argument -that follows the \fBedit\fR argument. The following forms of the -command are currently supported: +. +This command controls the undo mechanism and the modified flag. The exact +behavior of the command depends on the \fIoption\fR argument that follows the +\fBedit\fR argument. The following forms of the command are currently +supported: .RS .TP -\fIpathName \fBedit modified ?\fIboolean\fR? -If \fIboolean\fR is not specified, returns the modified flag of the -widget. The insert, delete, edit undo and edit redo commands or the -user can set or clear the modified flag. If \fIboolean\fR is -specified, sets the modified flag of the widget to \fIboolean\fR. +\fIpathName \fBedit modified \fR?\fIboolean\fR? +. +If \fIboolean\fR is not specified, returns the modified flag of the widget. +The insert, delete, edit undo and edit redo commands or the user can set or +clear the modified flag. If \fIboolean\fR is specified, sets the modified flag +of the widget to \fIboolean\fR. .TP \fIpathName \fBedit redo\fR -When the \fB\-undo\fR option is true, reapplies the last undone edits -provided no other edits were done since then. Generates an error when -the redo stack is empty. Does nothing when the \fB\-undo\fR option is -false. +. +When the \fB\-undo\fR option is true, reapplies the last undone edits provided +no other edits were done since then. Generates an error when the redo stack is +empty. Does nothing when the \fB\-undo\fR option is false. .TP \fIpathName \fBedit reset\fR +. Clears the undo and redo stacks. .TP \fIpathName \fBedit separator\fR -Inserts a separator (boundary) on the undo stack. Does nothing when -the \fB\-undo\fR option is false. +. +Inserts a separator (boundary) on the undo stack. Does nothing when the +\fB\-undo\fR option is false. .TP \fIpathName \fBedit undo\fR -Undoes the last edit action when the \fB\-undo\fR option is true. An -edit action is defined as all the insert and delete commands that are -recorded on the undo stack in between two separators. Generates an -error when the undo stack is empty. Does nothing when the \fB\-undo\fR -option is false. +. +Undoes the last edit action when the \fB\-undo\fR option is true. An edit +action is defined as all the insert and delete commands that are recorded on +the undo stack in between two separators. Generates an error when the undo +stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE .TP -\fIpathName \fBget\fR \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 -the one whose index is \fIindex2\fR (the character at \fIindex2\fR -will not be returned). -If \fIindex2\fR is omitted then the single character at \fIindex1\fR -is returned. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then an empty string is returned. -If the specified range contains embedded windows, no information -about them is included in the returned string. -If multiple index pairs are given, multiple ranges of text will be returned -in a list. Invalid ranges will not be represented with empty strings in -the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. -.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 +\fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? +. +Return a range of characters from the text. The return value will be all the +characters in the text starting with the one whose index is \fIindex1\fR and +ending just before the one whose index is \fIindex2\fR (the character at +\fIindex2\fR will not be returned). If \fIindex2\fR is omitted then the single +character at \fIindex1\fR is returned. If there are no characters in the +specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR +is less than or equal to \fIindex1\fR) then an empty string is returned. If +the specified range contains embedded windows, no information about them is +included in the returned string. If multiple index pairs are given, multiple +ranges of text will be returned in a list. Invalid ranges will not be +represented with empty strings in the list. The ranges are returned in the +order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is +given, then, within each range, only those characters which are not elided +will be returned. This may have the effect that some of the returned ranges +are empty strings. .TP \fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate embedded images. -The behavior of the command depends on the \fIoption\fR argument -that follows the \fBtag\fR argument. -The following forms of the command are currently supported: +. +This command is used to manipulate embedded images. The behavior of the +command depends on the \fIoption\fR argument that follows the \fBtag\fR +argument. The following forms of the command are currently supported: .RS .TP -\fIpathName \fBimage cget\fR \fIindex option\fR -Returns the value of a configuration option for an embedded image. -\fIIndex\fR identifies the embedded image, and \fIoption\fR -specifies a particular configuration option, which must be one of -the ones listed in the section \fBEMBEDDED IMAGES\fR. +\fIpathName \fBimage cget \fIindex option\fR +. +Returns the value of a configuration option for an embedded image. \fIIndex\fR +identifies the embedded image, and \fIoption\fR specifies a particular +configuration option, which must be one of the ones listed in the section +\fBEMBEDDED IMAGES\fR. .TP \fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? -Query or modify the configuration options for an embedded image. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the embedded image at \fIindex\fR -(see \fBTk_ConfigureInfo\fR for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -\fIoption\fR is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See \fBEMBEDDED IMAGES\fR for information on the options that -are supported. +. +Query or modify the configuration options for an embedded image. If no +\fIoption\fR is specified, returns a list describing all of the available +options for the embedded image at \fIindex\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified with no +\fIvalue\fR, then the command returns a list describing the one named option +(this list will be identical to the corresponding sublist of the value +returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR +pairs are specified, then the command modifies the given option(s) to have the +given value(s); in this case the command returns an empty string. See +\fBEMBEDDED IMAGES\fR for information on the options that are supported. .TP \fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? -This command creates a new image annotation, which will appear -in the text at the position given by \fIindex\fR. -Any number of \fIoption\-value\fR pairs may be specified to -configure the annotation. -Returns a unique identifier that may be used as an index to refer to -this image. -See \fBEMBEDDED IMAGES\fR for information on the options that -are supported, and a description of the identifier returned. +. +This command creates a new image annotation, which will appear in the text at +the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may +be specified to configure the annotation. Returns a unique identifier that may +be used as an index to refer to this image. See \fBEMBEDDED IMAGES\fR for +information on the options that are supported, and a description of the +identifier returned. .TP \fIpathName \fBimage names\fR +. Returns a list whose elements are the names of all image instances currently embedded in \fIwindow\fR. .RE .TP \fIpathName \fBindex \fIindex\fR -Returns the position corresponding to \fIindex\fR in the form -\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR -is the character number. +. +Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR +where \fIline\fR is the line number and \fIchar\fR is the character number. \fIIndex\fR may have any of the forms described under \fBINDICES\fR above. .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? +. Inserts all of the \fIchars\fR arguments just before the character at -\fIindex\fR. -If \fIindex\fR refers to the end of the text (the character after -the last newline) then the new text is inserted just before the -last newline instead. -If there is a single \fIchars\fR argument and no \fItagList\fR, then -the new text will receive any tags that are present on both the -character before and the character after the insertion point; if a tag -is present on only one of these characters then it will not be -applied to the new text. -If \fItagList\fR is specified then it consists of a list of -tag names; the new characters will receive all of the tags in -this list and no others, regardless of the tags present around -the insertion point. -If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, -they produce the same effect as if a separate \fIpathName \fBinsert\fR widget -command had been issued for each pair, in order. -The last \fItagList\fR argument may be omitted. +\fIindex\fR. If \fIindex\fR refers to the end of the text (the character after +the last newline) then the new text is inserted just before the last newline +instead. If there is a single \fIchars\fR argument and no \fItagList\fR, then +the new text will receive any tags that are present on both the character +before and the character after the insertion point; if a tag is present on +only one of these characters then it will not be applied to the new text. If +\fItagList\fR is specified then it consists of a list of tag names; the new +characters will receive all of the tags in this list and no others, regardless +of the tags present around the insertion point. If multiple +\fIchars\fR\-\fItagList\fR argument pairs are present, they produce the same +effect as if a separate \fIpathName \fBinsert\fR widget command had been +issued for each pair, in order. The last \fItagList\fR argument may be +omitted. .TP \fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate marks. The exact behavior of -the command depends on the \fIoption\fR argument that follows -the \fBmark\fR argument. The following forms of the command -are currently supported: +. +This command is used to manipulate marks. The exact behavior of the command +depends on the \fIoption\fR argument that follows the \fBmark\fR argument. The +following forms of the command are currently supported: .RS .TP \fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR? -If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR -to indicate which of its adjacent characters \fImarkName\fR is attached -to. -If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; -the gravity of \fImarkName\fR is set to the given value. +. +If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR to +indicate which of its adjacent characters \fImarkName\fR is attached to. If +\fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; the +gravity of \fImarkName\fR is set to the given value. .TP \fIpathName \fBmark names\fR -Returns a list whose elements are the names of all the marks that -are currently set. +. +Returns a list whose elements are the names of all the marks that are +currently set. .TP \fIpathName \fBmark next \fIindex\fR -Returns the name of the next mark at or after \fIindex\fR. -If \fIindex\fR is specified in numerical form, then the search for -the next mark begins at that index. -If \fIindex\fR is the name of a mark, then the search for -the next mark begins immediately after that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the \fBmark next\fR operation can be used to -step through all the marks in a text widget in the same order -as the mark information returned by the \fIpathName \fBdump\fR operation. -If a mark has been set to the special \fBend\fR index, -then it appears to be \fIafter\fR \fBend\fR with respect to the \fIpathName \fBmark next\fR operation. -An empty string is returned if there are no marks after \fIindex\fR. +. +Returns the name of the next mark at or after \fIindex\fR. If \fIindex\fR is +specified in numerical form, then the search for the next mark begins at that +index. If \fIindex\fR is the name of a mark, then the search for the next mark +begins immediately after that mark. This can still return a mark at the same +position if there are multiple marks at the same index. These semantics mean +that the \fBmark next\fR operation can be used to step through all the marks +in a text widget in the same order as the mark information returned by the +\fIpathName \fBdump\fR operation. If a mark has been set to the special +\fBend\fR index, then it appears to be \fIafter\fR \fBend\fR with respect to +the \fIpathName \fBmark next\fR operation. An empty string is returned if +there are no marks after \fIindex\fR. .TP \fIpathName \fBmark previous \fIindex\fR -Returns the name of the mark at or before \fIindex\fR. -If \fIindex\fR is specified in numerical form, then the search for -the previous mark begins with the character just before that index. -If \fIindex\fR is the name of a mark, then the search for -the next mark begins immediately before that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the \fIpathName \fBmark previous\fR operation can be used to -step through all the marks in a text widget in the reverse order -as the mark information returned by the \fIpathName \fBdump\fR operation. -An empty string is returned if there are no marks before \fIindex\fR. +. +Returns the name of the mark at or before \fIindex\fR. If \fIindex\fR is +specified in numerical form, then the search for the previous mark begins with +the character just before that index. If \fIindex\fR is the name of a mark, +then the search for the next mark begins immediately before that mark. This +can still return a mark at the same position if there are multiple marks at +the same index. These semantics mean that the \fIpathName \fBmark previous\fR +operation can be used to step through all the marks in a text widget in the +reverse order as the mark information returned by the \fIpathName \fBdump\fR +operation. An empty string is returned if there are no marks before +\fIindex\fR. .TP \fIpathName \fBmark set \fImarkName index\fR -Sets the mark named \fImarkName\fR to a position just before the -character at \fIindex\fR. -If \fImarkName\fR already exists, it is moved from its old position; -if it does not exist, a new mark is created. -This command returns an empty string. +. +Sets the mark named \fImarkName\fR to a position just before the character at +\fIindex\fR. If \fImarkName\fR already exists, it is moved from its old +position; if it does not exist, a new mark is created. This command returns an +empty string. .TP \fIpathName \fBmark unset \fImarkName \fR?\fImarkName markName ...\fR? -Remove the mark corresponding to each of the \fImarkName\fR arguments. -The removed marks will not be usable in indices and will not be -returned by future calls to +. +Remove the mark corresponding to each of the \fImarkName\fR arguments. The +removed marks will not be usable in indices and will not be returned by future +calls to .QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE .TP -\fIpathName \fBpeer\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: +\fIpathName \fBpeer \fIoption args\fR +. +This command is used to create and query widget peers. It has two forms, +depending on \fIoption\fR: .RS .TP \fIpathName \fBpeer create \fInewPathName\fR ?\fIoptions\fR? -Creates a peer text widget with the given \fInewPathName\fR, and any -optional standard configuration options (as for the \fItext\fR command). -By default the peer will have the same start and end line as the -parent widget, but these can be overridden with the standard -configuration options. +. +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. +itself). The order within this list is undefined. .RE .TP \fIpathName \fBpendingsync\fR @@ -1600,110 +1436,107 @@ arguments, and the section on \fIpathName \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. +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: +\fIpathName \fBscan \fIoption args\fR +. +This command is used to implement scanning on texts. It has two forms, +depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR -Records \fIx\fR and \fIy\fR and the current view in the text window, -for use in conjunction with later \fIpathName \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget. It returns an empty string. +. +Records \fIx\fR and \fIy\fR and the current view in the text window, for use +in conjunction with later \fIpathName \fBscan dragto\fR commands. Typically +this command is associated with a mouse button press in the widget. It returns +an empty string. .TP \fIpathName \fBscan dragto \fIx y\fR -This command computes the difference between its \fIx\fR and \fIy\fR -arguments and the \fIx\fR and \fIy\fR arguments to the last -\fIpathName \fBscan mark\fR command for the widget. -It then adjusts the view by 10 times the difference in coordinates. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the text at high speed through the window. The return -value is an empty string. +. +This command computes the difference between its \fIx\fR and \fIy\fR arguments +and the \fIx\fR and \fIy\fR arguments to the last \fIpathName \fBscan mark\fR +command for the widget. It then adjusts the view by 10 times the difference in +coordinates. This command is typically associated with mouse motion events in +the widget, to produce the effect of dragging the text at high speed through +the window. The return value is an empty string. .RE .TP \fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? -Searches the text in \fIpathName\fR starting at \fIindex\fR for a range -of characters that matches \fIpattern\fR. -If a match is found, the index of the first character in the match is -returned as result; otherwise an empty string is returned. -One or more of the following switches (or abbreviations thereof) +. +Searches the text in \fIpathName\fR starting at \fIindex\fR for a range of +characters that matches \fIpattern\fR. If a match is found, the index of the +first character in the match is returned as result; otherwise an empty string +is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search: .RS .TP \fB\-forwards\fR -The search will proceed forward through the text, finding the first -matching range starting at or after the position given by \fIindex\fR. -This is the default. +. +The search will proceed forward through the text, finding the first matching +range starting at or after the position given by \fIindex\fR. This is the +default. .TP \fB\-backwards\fR -The search will proceed backward through the text, finding the -matching range closest to \fIindex\fR whose first character -is before \fIindex\fR -.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 +. +The search will proceed backward through the text, finding the matching range +closest to \fIindex\fR whose first character is before \fIindex\fR (it is not +allowed to be at \fIindex\fR). Note that, for a variety of reasons, backwards +searches can be substantially slower than forwards searches (particularly when +using \fB\-regexp\fR), so it is recommended that performance-critical code use +forward searches. .TP \fB\-exact\fR -Use exact matching: the characters in the matching range must be -identical to those in \fIpattern\fR. -This is the default. +. +Use exact matching: the characters in the matching range must be identical to +those in \fIpattern\fR. This is the default. .TP \fB\-regexp\fR -Treat \fIpattern\fR as a regular expression and match it against -the text using the rules for regular expressions (see the \fBregexp\fR -command 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 +. +Treat \fIpattern\fR as a regular expression and match it against the text +using the rules for regular expressions (see the \fBregexp\fR command +and the \fBre_syntax\fR page for +details). The default matching automatically passes both the +\fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless +\fB\-nolinestop\fR is used), so that \fI^$\fR match beginning and end of line, +and \fI.\fR, \fI[^\fR sequences will never match the newline character +\fI\en\fR. .TP \fB\-nolinestop\fR -.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 +. +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. .TP \fB\-count\fI varName\fR -The argument following \fB\-count\fR gives the name of a variable; -if a match is found, the number of index positions between beginning and -end of the matching range will be stored in the variable. If there are no -embedded images or windows in the matching range (and there are no -elided characters if \fB\-elide\fR is not given), this is equivalent to the -number of characters matched. In either case, the range \fImatchIdx\fR to -\fImatchIdx + $count chars\fR will return the entire matched text. +. +The argument following \fB\-count\fR gives the name of a variable; if a match +is found, the number of index positions between beginning and end of the +matching range will be stored in the variable. If there are no embedded images +or windows in the matching range (and there are no elided characters if +\fB\-elide\fR is not given), this is equivalent to the number of characters +matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count +chars\fR will return the entire matched text. .TP \fB\-all\fR -.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 +. +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" @@ -1712,76 +1545,65 @@ will just match twice, once for each word, and matching 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 +. +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 +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 +will now match twice. An error will be thrown if this switch is used without +\fB\-all\fR. .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 +. +When performing any search, the normal behaviour is that the start and stop +limits are checked with respect to the start of the matching text. With the +\fB\-strictlimits\fR flag, the entire matching range must lie inside the start +and stop limits specified for the match to be valid. .TP \fB\-elide\fR -Find elided (hidden) text as well. By default only displayed text is -searched. +. +Find elided (hidden) text as well. By default only displayed text is searched. .TP \fB\-\|\-\fR -This switch has no effect except to terminate the list of switches: -the next argument will be treated as \fIpattern\fR even if it starts -with \fB\-\fR. -.PP -.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 -text than \fIstopIndex\fR will be considered. -If \fIstopIndex\fR is omitted, the entire text will be searched: -when the beginning or end of the text is reached, the search -continues at the other end until the starting location is reached -again; if \fIstopIndex\fR is specified, no wrap-around will occur. -This means that, for example, if the search is \fB\-forwards\fR -but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, -nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of -minor limitations of the \fIpathName \fBsearch\fR command. +. +This switch has no effect except to terminate the list of switches: the next +argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. +.PP +The matching range may be within a single line of text, or run across multiple +lines (if parts of the pattern can match a new-line). For regular expression +matching one can use the various newline-matching features such as \fB$\fR to +match the end of a line, \fB^\fR to match the beginning of a line, and to +control whether \fB.\fR is allowed to match a new-line. If \fIstopIndex\fR is +specified, the search stops at that index: for forward searches, no match at +or after \fIstopIndex\fR will be considered; for backward searches, no match +earlier in the text than \fIstopIndex\fR will be considered. If +\fIstopIndex\fR is omitted, the entire text will be searched: when the +beginning or end of the text is reached, the search continues at the other end +until the starting location is reached again; if \fIstopIndex\fR is specified, +no wrap-around will occur. This means that, for example, if the search is +\fB\-forwards\fR but \fIstopIndex\fR is earlier in the text than +\fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a +number of minor limitations of the \fIpathName \fBsearch\fR command. .RE .TP \fIpathName \fBsee \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is completely visible. -If \fIindex\fR is already visible then the command does nothing. -If \fIindex\fR is a short distance out of view, the command -adjusts the view just enough to make \fIindex\fR visible at the -edge of the window. -If \fIindex\fR is far out of view, then the command centers -\fIindex\fR in the window. +. +Adjusts the view in the window so that the character given by \fIindex\fR is +completely visible. If \fIindex\fR is already visible then the command does +nothing. If \fIindex\fR is a short distance out of view, the command adjusts +the view just enough to make \fIindex\fR visible at the edge of the window. +If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the +window. .TP \fIpathName \fBsync\fR ?\fB-command \fIcommand\fR? Controls the synchronization of the view of the text widget. @@ -1801,548 +1623,494 @@ string. \fBbgerror\fR is called on \fIcommand\fR failure. .RE .TP \fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate tags. The exact behavior of the -command depends on the \fIoption\fR argument that follows the -\fBtag\fR argument. The following forms of the command are currently -supported: +. +This command is used to manipulate tags. The exact behavior of the command +depends on the \fIoption\fR argument that follows the \fBtag\fR argument. The +following forms of the command are currently supported: .RS .TP \fIpathName \fBtag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -Associate the tag \fItagName\fR with all of the characters starting -with \fIindex1\fR and ending just before -\fIindex2\fR (the character at \fIindex2\fR is not tagged). -A single command may contain any number of \fIindex1\fR\-\fIindex2\fR -pairs. -If the last \fIindex2\fR is omitted then the single character at -\fIindex1\fR is tagged. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then the command has no effect. +. +Associate the tag \fItagName\fR with all of the characters starting with +\fIindex1\fR and ending just before \fIindex2\fR (the character at +\fIindex2\fR is not tagged). A single command may contain any number of +\fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the +single character at \fIindex1\fR is tagged. If there are no characters in the +specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR +is less than or equal to \fIindex1\fR) then the command has no effect. .TP \fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? -This command associates \fIscript\fR with the tag given by -\fItagName\fR. -Whenever the event sequence given by \fIsequence\fR occurs for a -character that has been tagged with \fItagName\fR, -the script will be invoked. -This widget command is similar to the \fBbind\fR command except that -it operates on characters in a text rather than entire widgets. -See the \fBbind\fR manual entry for complete details -on the syntax of \fIsequence\fR and the substitutions performed -on \fIscript\fR before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same \fIsequence\fR and \fItagName\fR -(if the first character of \fIscript\fR is +. +This command associates \fIscript\fR with the tag given by \fItagName\fR. +Whenever the event sequence given by \fIsequence\fR occurs for a character +that has been tagged with \fItagName\fR, the script will be invoked. This +widget command is similar to the \fBbind\fR command except that it operates on +characters in a text rather than entire widgets. See the \fBbind\fR manual +entry for complete details on the syntax of \fIsequence\fR and the +substitutions performed on \fIscript\fR before invoking it. If all arguments +are specified then a new binding is created, replacing any existing binding +for the same \fIsequence\fR and \fItagName\fR (if the first character of +\fIscript\fR is .QW + -then \fIscript\fR augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If \fIscript\fR is omitted then the command returns the \fIscript\fR -associated with \fItagName\fR and \fIsequence\fR (an error occurs -if there is no such binding). -If both \fIscript\fR and \fIsequence\fR are omitted then the command -returns a list of all the sequences for which bindings have been -defined for \fItagName\fR. +then \fIscript\fR augments an existing binding rather than replacing it). In +this case the return value is an empty string. If \fIscript\fR is omitted then +the command returns the \fIscript\fR associated with \fItagName\fR and +\fIsequence\fR (an error occurs if there is no such binding). If both +\fIscript\fR and \fIsequence\fR are omitted then the command returns a list of +all the sequences for which bindings have been defined for \fItagName\fR. .RS .PP -The only events for which bindings may be specified are those related -to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, -\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. -Event bindings for a text widget use the \fBcurrent\fR mark described -under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag -first becomes present on the current character, and a \fBLeave\fR event -triggers for a tag when it ceases to be present on the current character. -\fBEnter\fR and \fBLeave\fR events can happen either because the -\fBcurrent\fR mark moved or because the character at that position -changed. Note that these events are different than \fBEnter\fR and -\fBLeave\fR events for windows. Mouse and keyboard events are directed -to the current character. If a virtual event is used in a binding, that -binding can trigger only if the virtual event is defined by an underlying +The only events for which bindings may be specified are those related to the +mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, +\fBMotion\fR, and \fBKeyPress\fR) or virtual events. Event bindings for a text +widget use the \fBcurrent\fR mark described under \fBMARKS\fR above. An +\fBEnter\fR event triggers for a tag when the tag first becomes present on the +current character, and a \fBLeave\fR event triggers for a tag when it ceases +to be present on the current character. \fBEnter\fR and \fBLeave\fR events can +happen either because the \fBcurrent\fR mark moved or because the character at +that position changed. Note that these events are different than \fBEnter\fR +and \fBLeave\fR events for windows. Mouse and keyboard events are directed to +the current character. If a virtual event is used in a binding, that binding +can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. .PP -It is possible for the current character to have multiple tags, -and for each of them to have a binding for a particular event -sequence. -When this occurs, one binding is invoked for each tag, in order -from lowest-priority to highest priority. -If there are multiple matching bindings for a single tag, then -the most specific binding is chosen (see the manual entry for -the \fBbind\fR command for details). -\fBcontinue\fR and \fBbreak\fR commands within binding scripts -are processed in the same way as for bindings created with -the \fBbind\fR command. -.PP -If bindings are created for the widget as a whole using the -\fBbind\fR command, then those bindings will supplement the -tag bindings. -The tag bindings will be invoked first, followed by bindings -for the window as a whole. +It is possible for the current character to have multiple tags, and for each +of them to have a binding for a particular event sequence. When this occurs, +one binding is invoked for each tag, in order from lowest-priority to highest +priority. If there are multiple matching bindings for a single tag, then the +most specific binding is chosen (see the manual entry for the \fBbind\fR +command for details). \fBcontinue\fR and \fBbreak\fR commands within binding +scripts are processed in the same way as for bindings created with the +\fBbind\fR command. +.PP +If bindings are created for the widget as a whole using the \fBbind\fR +command, then those bindings will supplement the tag bindings. The tag +bindings will be invoked first, followed by bindings for the window as a +whole. .RE .TP -\fIpathName \fBtag cget\fR \fItagName option\fR +\fIpathName \fBtag cget \fItagName option\fR +. This command returns the current value of the option named \fIoption\fR -associated with the tag given by \fItagName\fR. -\fIOption\fR may have any of the values accepted by the \fIpathName \fBtag -configure\fR widget command. +associated with the tag given by \fItagName\fR. \fIOption\fR may have any of +the values accepted by the \fIpathName \fBtag configure\fR widget command. .TP \fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -This command is similar to the \fIpathName \fBconfigure\fR widget command except -that it modifies options associated with the tag given by \fItagName\fR -instead of modifying options for the overall text widget. -If no \fIoption\fR is specified, the command returns a list describing -all of the available options for \fItagName\fR (see \fBTk_ConfigureInfo\fR -for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command returns -a list describing the one named option (this list will be identical to -the corresponding sublist of the value returned if no \fIoption\fR -is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s) in \fItagName\fR; -in this case the command returns an empty string. +. +This command is similar to the \fIpathName \fBconfigure\fR widget command +except that it modifies options associated with the tag given by \fItagName\fR +instead of modifying options for the overall text widget. If no \fIoption\fR +is specified, the command returns a list describing all of the available +options for \fItagName\fR (see \fBTk_ConfigureInfo\fR for information on the +format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then +the command returns a list describing the one named option (this list will be +identical to the corresponding sublist of the value returned if no +\fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are +specified, then the command modifies the given option(s) to have the given +value(s) in \fItagName\fR; in this case the command returns an empty string. See \fBTAGS\fR above for details on the options available for tags. .TP \fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR? -Deletes all tag information for each of the \fItagName\fR -arguments. -The command removes the tags from all characters in the file -and also deletes any other information associated with the tags, -such as bindings and display information. -The command returns an empty string. +. +Deletes all tag information for each of the \fItagName\fR arguments. The +command removes the tags from all characters in the file and also deletes any +other information associated with the tags, such as bindings and display +information. The command returns an empty string. .TP \fIpathName\fB tag lower \fItagName \fR?\fIbelowThis\fR? -Changes the priority of tag \fItagName\fR so that it is just lower -in priority than the tag whose name is \fIbelowThis\fR. -If \fIbelowThis\fR is omitted, then \fItagName\fR's priority -is changed to make it lowest priority of all tags. +. +Changes the priority of tag \fItagName\fR so that it is just lower in priority +than the tag whose name is \fIbelowThis\fR. If \fIbelowThis\fR is omitted, +then \fItagName\fR's priority is changed to make it lowest priority of all +tags. .TP \fIpathName \fBtag names \fR?\fIindex\fR? -Returns a list whose elements are the names of all the tags that -are active at the character position given by \fIindex\fR. -If \fIindex\fR is omitted, then the return value will describe -all of the tags that exist for the text (this includes all tags -that have been named in a +. +Returns a list whose elements are the names of all the tags that are active at +the character position given by \fIindex\fR. If \fIindex\fR is omitted, then +the return value will describe all of the tags that exist for the text (this +includes all tags that have been named in a .QW "\fIpathName \fBtag\fR" widget command but have not been deleted by a .QW "\fIpathName \fBtag delete\fR" -widget command, even if no characters are currently marked with the tag). -The list will be sorted in order from lowest priority to highest -priority. +widget command, even if no characters are currently marked with the tag). The +list will be sorted in order from lowest priority to highest priority. .TP \fIpathName \fBtag nextrange \fItagName index1 \fR?\fIindex2\fR? -This command searches the text for a range of characters tagged -with \fItagName\fR where the first character of the range is -no earlier than the character at \fIindex1\fR and no later than -the character just before \fIindex2\fR (a range starting at -\fIindex2\fR will not be considered). -If several matching ranges exist, the first one is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. -If \fIindex2\fR is not given then it defaults to the end of the text. +. +This command searches the text for a range of characters tagged with +\fItagName\fR where the first character of the range is no earlier than the +character at \fIindex1\fR and no later than the character just before +\fIindex2\fR (a range starting at \fIindex2\fR will not be considered). If +several matching ranges exist, the first one is chosen. The command's return +value is a list containing two elements, which are the index of the first +character of the range and the index of the character just after the last one +in the range. If no matching range is found then the return value is an empty +string. If \fIindex2\fR is not given then it defaults to the end of the text. .TP \fIpathName \fBtag prevrange \fItagName index1 \fR?\fIindex2\fR? -This command searches the text for a range of characters tagged -with \fItagName\fR where the first character of the range is -before the character at \fIindex1\fR and no earlier than -the character at \fIindex2\fR (a range starting at -\fIindex2\fR will be considered). -If several matching ranges exist, the one closest to \fIindex1\fR is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. +. +This command searches the text for a range of characters tagged with +\fItagName\fR where the first character of the range is before the character +at \fIindex1\fR and no earlier than the character at \fIindex2\fR (a range +starting at \fIindex2\fR will be considered). If several matching ranges +exist, the one closest to \fIindex1\fR is chosen. The command's return value +is a list containing two elements, which are the index of the first character +of the range and the index of the character just after the last one in the +range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the beginning of the text. .TP \fIpathName\fB tag raise \fItagName \fR?\fIaboveThis\fR? -Changes the priority of tag \fItagName\fR so that it is just higher -in priority than the tag whose name is \fIaboveThis\fR. -If \fIaboveThis\fR is omitted, then \fItagName\fR's priority -is changed to make it highest priority of all tags. +. +Changes the priority of tag \fItagName\fR so that it is just higher in +priority than the tag whose name is \fIaboveThis\fR. If \fIaboveThis\fR is +omitted, then \fItagName\fR's priority is changed to make it highest priority +of all tags. .TP \fIpathName \fBtag ranges \fItagName\fR -Returns a list describing all of the ranges of text that have been -tagged with \fItagName\fR. -The first two elements of the list describe the first tagged range -in the text, the next two elements describe the second range, and -so on. -The first element of each pair contains the index of the first -character of the range, and the second element of the pair contains -the index of the character just after the last one in the -range. -If there are no characters tagged with \fItag\fR then an -empty string is returned. +. +Returns a list describing all of the ranges of text that have been tagged with +\fItagName\fR. The first two elements of the list describe the first tagged +range in the text, the next two elements describe the second range, and so on. +The first element of each pair contains the index of the first character of +the range, and the second element of the pair contains the index of the +character just after the last one in the range. If there are no characters +tagged with \fItag\fR then an empty string is returned. .TP \fIpathName \fBtag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -Remove the tag \fItagName\fR from all of the characters starting -at \fIindex1\fR and ending just before -\fIindex2\fR (the character at \fIindex2\fR is not affected). -A single command may contain any number of \fIindex1\fR\-\fIindex2\fR -pairs. -If the last \fIindex2\fR is omitted then the tag is removed from the -single character at \fIindex1\fR. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then the command has no effect. -This command returns an empty string. +. +Remove the tag \fItagName\fR from all of the characters starting at +\fIindex1\fR and ending just before \fIindex2\fR (the character at +\fIindex2\fR is not affected). A single command may contain any number of +\fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the +tag is removed from the single character at \fIindex1\fR. If there are no +characters in the specified range (e.g. \fIindex1\fR is past the end of the +file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command +has no effect. This command returns an empty string. .RE .TP \fIpathName \fBwindow \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate embedded windows. -The behavior of the command depends on the \fIoption\fR argument -that follows the \fBwindow\fR argument. -The following forms of the command are currently supported: +. +This command is used to manipulate embedded windows. The behavior of the +command depends on the \fIoption\fR argument that follows the \fBwindow\fR +argument. The following forms of the command are currently supported: .RS .TP -\fIpathName \fBwindow cget\fR \fIindex option\fR +\fIpathName \fBwindow cget \fIindex option\fR +. Returns the value of a configuration option for an embedded window. -\fIIndex\fR identifies the embedded window, and \fIoption\fR -specifies a particular configuration option, which must be one of -the ones listed in the section \fBEMBEDDED WINDOWS\fR. +\fIIndex\fR identifies the embedded window, and \fIoption\fR specifies a +particular configuration option, which must be one of the ones listed in the +section \fBEMBEDDED WINDOWS\fR. .TP \fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? -Query or modify the configuration options for an embedded window. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the embedded window at \fIindex\fR -(see \fBTk_ConfigureInfo\fR for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -\fIoption\fR is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See \fBEMBEDDED WINDOWS\fR for information on the options that -are supported. +. +Query or modify the configuration options for an embedded window. If no +\fIoption\fR is specified, returns a list describing all of the available +options for the embedded window at \fIindex\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified with no +\fIvalue\fR, then the command returns a list describing the one named option +(this list will be identical to the corresponding sublist of the value +returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR +pairs are specified, then the command modifies the given option(s) to have the +given value(s); in this case the command returns an empty string. See +\fBEMBEDDED WINDOWS\fR for information on the options that are supported. .TP \fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR? -This command creates a new window annotation, which will appear -in the text at the position given by \fIindex\fR. -Any number of \fIoption\-value\fR pairs may be specified to -configure the annotation. -See \fBEMBEDDED WINDOWS\fR for information on the options that -are supported. -Returns an empty string. +. +This command creates a new window annotation, which will appear in the text at +the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may +be specified to configure the annotation. See \fBEMBEDDED WINDOWS\fR for +information on the options that are supported. Returns an empty string. .TP \fIpathName \fBwindow names\fR -Returns a list whose elements are the names of all windows currently -embedded in \fIwindow\fR. +. +Returns a list whose elements are the names of all windows currently embedded +in \fIwindow\fR. .RE .TP \fIpathName \fBxview \fIoption args\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: +. +This command is used to query and change the horizontal position of the text +in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the portion of the document's horizontal span that is visible in -the window. -For example, if the first element is .2 and the second element is .6, -20% of the text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -The fractions refer only to the lines that are actually visible in the -window: if the lines in the window are all very short, so that they -are entirely visible, the returned fractions will be 0 and 1, -even if there are other lines in the text that are -much wider than the window. +. +Returns a list containing two elements. Each element is a real fraction +between 0 and 1; together they describe the portion of the document's +horizontal span that is visible in the window. For example, if the first +element is .2 and the second element is .6, 20% of the text is off-screen to +the left, the middle 40% is visible in the window, and 40% of the text is +off-screen to the right. The fractions refer only to the lines that are +actually visible in the window: if the lines in the window are all very short, +so that they are entirely visible, the returned fractions will be 0 and 1, +even if there are other lines in the text that are much wider than the window. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that \fIfraction\fR of the horizontal -span of the text is off-screen to the left. -\fIFraction\fR is a fraction between 0 and 1. +. +Adjusts the view in the window so that \fIfraction\fR of the horizontal span +of the text is off-screen to the left. \fIFraction\fR is a fraction between 0 +and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fIWhat\fR must be \fBunits\fR, \fBpages\fR or \fBpixels\fR. -.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 +\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or +\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR +must be an integer, otherwise number may be specified in any of the forms +acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i -(the result is rounded -to the nearest integer value. If no units are given, pixels are -assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is +(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. +\fBpixels\fR then the view adjusts by \fInumber\fR pixels. If \fInumber\fR is +negative then characters farther to the left become visible; if it is positive +then characters farther to the right become visible. .RE .TP -\fIpathName \fByview \fI?args\fR? -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: +\fIpathName \fByview \fR?\fIargs\fR? +. +This command is used to query and change the vertical position of the text in +the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR +. Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the first visible pixel of the -first character (or image, etc) in the -top line in the window, relative to the text as a whole (0.5 means -it is halfway through the text, for example). -The second element gives the position of the first pixel just after the -last visible one in the bottom line of the window, -relative to the text as a whole. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. +between 0 and 1. The first element gives the position of the first visible +pixel of the first character (or image, etc) in the top line in the window, +relative to the text as a whole (0.5 means it is halfway through the text, for +example). The second element gives the position of the first pixel just after +the last visible one in the bottom line of the window, relative to the text as +a whole. These are the same values passed to scrollbars via the +\fB\-yscrollcommand\fR option. .TP \fIpathName \fByview moveto\fI fraction\fR +. Adjusts the view in the window so that the pixel given by \fIfraction\fR -appears at the top of the top line of the window. -\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first -pixel of the first character in the text, 0.33 indicates the pixel that is -one-third the way through the text; and so on. -.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 +appears at the top of the top line of the window. \fIFraction\fR is a fraction +between 0 and 1; 0 indicates the first pixel of the first character in the +text, 0.33 indicates the pixel that is one-third the way through the text; and +so on. Values close to 1 will indicate values close to the last pixel in the +text (1 actually refers to one pixel beyond the last pixel), but in such cases +the widget will never scroll beyond the last pixel, and so a value of 1 will +effectively be rounded back to whatever fraction ensures the last pixel is at +the bottom of the window, and some other pixel is at the top. .TP \fIpathName \fByview scroll \fInumber what\fR +. This command adjust the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fIWhat\fR must be \fBunits\fR, \fBpages\fR or \fBpixels\fR. -.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 +\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or +\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR +must be an integer, otherwise number may be specified in any of the forms +acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i -(the result is rounded -to the nearest integer value. If no units are given, pixels are -assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR lines on the display; if it is \fBpages\fR then the view +(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. +adjusts by \fInumber\fR pixels. If \fInumber\fR is negative then earlier +positions in the text become visible; if it is positive then later positions +in the text become visible. .TP \fIpathName \fByview \fR?\fB\-pickplace\fR? \fIindex\fR -Changes the view in the widget's window to make \fIindex\fR visible. -If the \fB\-pickplace\fR option is not specified then \fIindex\fR will -appear at the top of the window. -If \fB\-pickplace\fR is specified then the widget chooses where -\fIindex\fR appears in the window: +. +Changes the view in the widget's window to make \fIindex\fR visible. If the +\fB\-pickplace\fR option is not specified then \fIindex\fR will appear at the +top of the window. If \fB\-pickplace\fR is specified then the widget chooses +where \fIindex\fR appears in the window: .RS .IP [1] -If \fIindex\fR is already visible somewhere in the window then the -command does nothing. +If \fIindex\fR is already visible somewhere in the window then the command +does nothing. .IP [2] -If \fIindex\fR is only a few lines off-screen above the window then -it will be positioned at the top of the window. +If \fIindex\fR is only a few lines off-screen above the window then it will be +positioned at the top of the window. .IP [3] -If \fIindex\fR is only a few lines off-screen below the window then -it will be positioned at the bottom of the window. +If \fIindex\fR is only a few lines off-screen below the window then it will be +positioned at the bottom of the window. .IP [4] Otherwise, \fIindex\fR will be centered in the window. -.LP -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). +.PP +The \fB\-pickplace\fR option has been obsoleted by the \fIpathName \fBsee\fR +widget command (\fIpathName \fBsee\fR handles both x- and y-motion to make a +location visible, whereas the \fB\-pickplace\fR mode only handles motion in +y). .RE .TP \fIpathName \fByview \fInumber\fR -This command makes the first character on the line after -the one given by \fInumber\fR visible at the top of the window. -\fINumber\fR must be an integer. -This command used to be used for scrolling, but now it is obsolete. +. +This command makes the first character on the line after the one given by +\fInumber\fR visible at the top of the window. \fINumber\fR must be an +integer. This command used to be used for scrolling, but now it is obsolete. .RE .SH BINDINGS .PP -Tk automatically creates class bindings for texts that give them -the following default behavior. -In the descriptions below, +Tk automatically creates class bindings for texts that give them the following +default behavior. In the descriptions below, .QW word -is dependent on the value of -the \fBtcl_wordchars\fR variable. See \fBtclvars\fR(n). +is dependent on the value of the \fBtcl_wordchars\fR variable. See +\fBtclvars\fR(n). .IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. +Clicking mouse button 1 positions the insertion cursor just before the +character underneath the mouse cursor, sets the input focus to this widget, +and clears any selection in the widget. Dragging with mouse button 1 strokes +out a selection between the insertion cursor and the character under the +mouse. .IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the start of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. +Double-clicking with mouse button 1 selects the word under the mouse and +positions the insertion cursor at the start of the word. Dragging after a +double click will stroke out a selection consisting of whole words. .IP [3] -Triple-clicking with mouse button 1 selects the line under the mouse -and positions the insertion cursor at the start of the line. -Dragging after a triple click will stroke out a selection consisting -of whole lines. +Triple-clicking with mouse button 1 selects the line under the mouse and +positions the insertion cursor at the start of the line. Dragging after a +triple click will stroke out a selection consisting of whole lines. .IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words; if it is triple-clicked -then the selection will be adjusted in units of whole lines. +The ends of the selection can be adjusted by dragging with mouse button 1 +while the Shift key is down; this will adjust the end of the selection that +was nearest to the mouse cursor when button 1 was pressed. If the button is +double-clicked before dragging then the selection will be adjusted in units of +whole words; if it is triple-clicked then the selection will be adjusted in +units of whole lines. .IP [5] Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting the selection. .IP [6] -If any normal printing characters are typed, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the widget can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the text at the position of the mouse cursor. -The Insert key also inserts the selection, but at the position of +If any normal printing characters are typed, they are inserted at the point of the insertion cursor. +.IP [7] +The view in the widget can be adjusted by dragging with mouse button 2. If +mouse button 2 is clicked without moving the mouse, the selection is copied +into the text at the position of the mouse cursor. The Insert key also inserts +the selection, but at the position of the insertion cursor. .IP [8] -If the mouse is dragged out of the widget -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). +If the mouse is dragged out of the widget while button 1 is pressed, the entry +will automatically scroll to make more text visible (if there is more text +off-screen on the side where the mouse left the window). .IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the text. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. +The Left and Right keys move the insertion cursor one character to the left or +right; they also clear any selection in the text. If Left or Right is typed +with the Shift key down, then the insertion cursor moves and the selection is +extended to include the new character. Control-Left and Control-Right move the +insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move +the insertion cursor by words and also extend the selection. Control-b and +Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f +behave the same as Control-Left and Control-Right, respectively. .IP [10] -The Up and Down keys move the insertion cursor one line up or -down and clear any selection in the text. -If Up or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Up and Control-Down move the insertion cursor by paragraphs (groups -of lines separated by blank lines), and -Control-Shift-Up and Control-Shift-Down move the insertion cursor -by paragraphs and also extend the selection. -Control-p and Control-n behave the same as Up and Down, respectively. +The Up and Down keys move the insertion cursor one line up or down and clear +any selection in the text. If Up or Right is typed with the Shift key down, +then the insertion cursor moves and the selection is extended to include the +new character. Control-Up and Control-Down move the insertion cursor by +paragraphs (groups of lines separated by blank lines), and Control-Shift-Up +and Control-Shift-Down move the insertion cursor by paragraphs and also extend +the selection. Control-p and Control-n behave the same as Up and Down, +respectively. .IP [11] -The Next and Prior keys move the insertion cursor forward or backwards -by one screenful and clear any selection in the text. -If the Shift key is held down while Next or Prior is typed, then -the selection is extended to include the new character. +The Next and Prior keys move the insertion cursor forward or backwards by one +screenful and clear any selection in the text. If the Shift key is held down +while Next or Prior is typed, then the selection is extended to include the +new character. .IP [12] Control-Next and Control-Prior scroll the view right or left by one page without moving the insertion cursor or affecting the selection. .IP [13] -Home and Control-a move the insertion cursor to the -beginning of its display line and clear any selection in the widget. -Shift-Home moves the insertion cursor to the beginning of the display line -and also extends the selection to that point. +Home and Control-a move the insertion cursor to the beginning of its display +line and clear any selection in the widget. Shift-Home moves the insertion +cursor to the beginning of the display line and also extends the selection to +that point. .IP [14] -End and Control-e move the insertion cursor to the -end of the display line and clear any selection in the widget. -Shift-End moves the cursor to the end of the display line and extends -the selection to that point. +End and Control-e move the insertion cursor to the end of the display line and +clear any selection in the widget. Shift-End moves the cursor to the end of +the display line and extends the selection to that point. .IP [15] -Control-Home and Meta-< move the insertion cursor to the beginning of -the text and clear any selection in the widget. -Control-Shift-Home moves the insertion cursor to the beginning of the text -and also extends the selection to that point. +Control-Home and Meta-< move the insertion cursor to the beginning of the text +and clear any selection in the widget. Control-Shift-Home moves the insertion +cursor to the beginning of the text and also extends the selection to that +point. .IP [16] -Control-End and Meta-> move the insertion cursor to the end of the -text and clear any selection in the widget. -Control-Shift-End moves the cursor to the end of the text and extends -the selection to that point. +Control-End and Meta-> move the insertion cursor to the end of the text and +clear any selection in the widget. Control-Shift-End moves the cursor to the +end of the text and extends the selection to that point. .IP [17] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They do not affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. +The Select key and Control-Space set the selection anchor to the position of +the insertion cursor. They do not affect the current selection. Shift-Select +and Control-Shift-Space adjust the selection to the current position of the +insertion cursor, selecting from the anchor to the insertion cursor if there +was not any selection previously. .IP [18] Control-/ selects the entire contents of the widget. .IP [19] Control-\e clears any selection in the widget. .IP [20] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -This action is carried out by the command \fBtk_textCopy\fR. +The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the +selection in the widget to the clipboard, if there is a selection. This +action is carried out by the command \fBtk_textCopy\fR. .IP [21] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -This action is carried out by the command \fBtk_textCut\fR. -If there is no selection in the widget then these keys have no effect. +The F20 key (labelled Cut on many Sun workstations) or Control-w copies the +selection in the widget to the clipboard and deletes the selection. This +action is carried out by the command \fBtk_textCut\fR. If there is no +selection in the widget then these keys have no effect. .IP [22] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -This action is carried out by the command \fBtk_textPaste\fR. +The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the +contents of the clipboard at the position of the insertion cursor. This action +is carried out by the command \fBtk_textPaste\fR. .IP [23] -The Delete key deletes the selection, if there is one in the widget. -If there is no selection, it deletes the character to the right of -the insertion cursor. +The Delete key deletes the selection, if there is one in the widget. If there +is no selection, it deletes the character to the right of the insertion +cursor. .IP [24] -Backspace and Control-h delete the selection, if there is one -in the widget. -If there is no selection, they delete the character to the left of -the insertion cursor. +Backspace and Control-h delete the selection, if there is one in the widget. +If there is no selection, they delete the character to the left of the +insertion cursor. .IP [25] Control-d deletes the character to the right of the insertion cursor. .IP [26] Meta-d deletes the word to the right of the insertion cursor. .IP [27] -Control-k deletes from the insertion cursor to the end of its line; -if the insertion cursor is already at the end of a line, then -Control-k deletes the newline character. +Control-k deletes from the insertion cursor to the end of its line; if the +insertion cursor is already at the end of a line, then Control-k deletes the +newline character. .IP [28] -Control-o opens a new line by inserting a newline character in -front of the insertion cursor without moving the insertion cursor. +Control-o opens a new line by inserting a newline character in front of the +insertion cursor without moving the insertion cursor. .IP [29] -Meta-backspace and Meta-Delete delete the word to the left of the -insertion cursor. +Meta-backspace and Meta-Delete delete the word to the left of the insertion +cursor. .IP [30] -Control-x deletes whatever is selected in the text widget -after copying it to the clipboard. +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. +Control-t reverses the order of the two characters to the right of the +insertion cursor. .IP [32] -Control-z (undoes the last edit action if the \fB\-undo\fR option is -true. Does nothing otherwise. +Control-z undoes the last edit action if the \fB\-undo\fR option is true. +Does nothing otherwise. .IP [33] -Control-Z (or Control-y on Windows) reapplies the last undone edit -action if the \fB\-undo\fR option is true. Does nothing otherwise. +Control-Z (or Control-y on Windows) reapplies the last undone edit action if +the \fB\-undo\fR option is true. Does nothing otherwise. .PP -If the widget is disabled using the \fB\-state\fR option, then its -view can still be adjusted and text can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. +If the widget is disabled using the \fB\-state\fR option, then its view can +still be adjusted and text can still be selected, but no insertion cursor will +be displayed and no text modifications will take place. .PP -The behavior of texts can be changed by defining new bindings for -individual widgets or by redefining the class bindings. +The behavior of texts can be changed by defining new bindings for individual +widgets or by redefining the class bindings. .SH "KNOWN ISSUES" .SS "ISSUES CONCERNING CHARS AND INDICES" -.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 +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 . @@ -2350,89 +2118,78 @@ 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 +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 +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 -main memory for each byte of text, so texts containing a megabyte -or more should be practical on most workstations. -Text is represented internally with a modified B-tree structure -that makes operations relatively efficient even with large texts. -Tags are included in the B-tree structure in a way that allows -tags to span large ranges or have many disjoint smaller ranges -without loss of efficiency. -Marks are also implemented in a way that allows large numbers of -marks. -In most cases it is fine to have large numbers of unique tags, -or a tag that has many distinct ranges. -.PP -One performance problem can arise if you have hundreds or thousands -of different tags that all have the following characteristics: -the first and last ranges of each tag are near the beginning and -end of the text, respectively, -or a single tag range covers most of the text widget. -The cost of adding and deleting tags like this is proportional -to the number of other tags with the same properties. -In contrast, there is no problem with having thousands of distinct -tags if their overall ranges are localized and spread uniformly throughout -the text. -.PP -Very long text lines can be expensive, -especially if they have many marks and tags within them. -.PP -The display line with the insert cursor is redrawn each time the -cursor blinks, which causes a steady stream of graphics traffic. -Set the \fBinsertOffTime\fR attribute to 0 avoid this. +Text widgets should run efficiently under a variety of conditions. The text +widget uses about 2-3 bytes of main memory for each byte of text, so texts +containing a megabyte or more should be practical on most workstations. Text +is represented internally with a modified B-tree structure that makes +operations relatively efficient even with large texts. Tags are included in +the B-tree structure in a way that allows tags to span large ranges or have +many disjoint smaller ranges without loss of efficiency. Marks are also +implemented in a way that allows large numbers of marks. In most cases it is +fine to have large numbers of unique tags, or a tag that has many distinct +ranges. +.PP +One performance problem can arise if you have hundreds or thousands of +different tags that all have the following characteristics: the first and last +ranges of each tag are near the beginning and end of the text, respectively, +or a single tag range covers most of the text widget. The cost of adding and +deleting tags like this is proportional to the number of other tags with the +same properties. In contrast, there is no problem with having thousands of +distinct tags if their overall ranges are localized and spread uniformly +throughout the text. +.PP +Very long text lines can be expensive, especially if they have many marks and +tags within them. +.PP +The display line with the insert cursor is redrawn each time the cursor +blinks, which causes a steady stream of graphics traffic. Set the +\fB\-insertofftime\fR attribute to 0 avoid this. .SS "KNOWN BUGS" -.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: +.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] +pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\encccc\enbbbb\enaaaa\en" \&.t search \-regexp \-\- {(a+|b+\enc+\enb+)+\ena+} 1.0 .CE -will not find a match when one exists of 19 -characters starting from the first +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: +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] +pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\enbbbb\enbbbb\enbbbb\\n" \&.t search \-regexp \-backward \-\- {b+\en|a+\en(b+\en)+} end .CE @@ -2449,8 +2206,10 @@ and 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 +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -14,7 +14,6 @@ tk \- Manipulate Tk internal state .SH SYNOPSIS \fBtk\fR \fIoption \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBtk\fR command provides access to miscellaneous @@ -46,7 +45,14 @@ If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. .TP -\fBtk caret window \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? +\fBtk busy \fIsubcommand\fR ... +. +This command controls the marking of window hierarchies as +.QW busy , +rendering them non-interactive while some other operation is proceeding. For +more details see the \fBbusy\fR manual page. +.TP +\fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . Sets and queries the caret location for the display of the specified Tk window \fIwindow\fR. The caret is the per-display cursor location @@ -54,17 +60,39 @@ used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair -format. \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 +format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and +\fB\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. .TP +\fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? +. +Returns a positive integer, the number of milliseconds since the last +time the user interacted with the system. If the \fB\-displayof\fR +option is given then the return value refers to the display of +\fIwindow\fR; otherwise it refers to the display of the application's +main window. +.RS +.PP +\fBtk inactive\fR will return \-1, if querying the user inactive time +is not supported by the system, and in safe interpreters. +.PP +If the literal string \fBreset\fR is given as an additional argument, +the timer is reset and an empty string is returned. Resetting the +inactivity time is forbidden in safe interpreters and will throw an +error if tried. +.RE +.TP +\fBtk fontchooser \fIsubcommand\fR ... +Controls the Tk font selection dialog. For more details see the +\fBfontchooser\fR manual page. +.TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The \fInumber\fR argument is a floating point number that specifies the number of pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is -omitted, it defaults to the main window. If the \fInumber\fR argument is +omitted, it defaults to the main window. If the \fInumber\fR argument is omitted, the current value of the scaling factor is returned. .RS .PP @@ -83,24 +111,6 @@ is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE .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) @@ -117,6 +127,9 @@ Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (Mac OS X Aqua). .SH "SEE ALSO" -send(n), winfo(n) +busy(n), fontchooser(n), send(n), winfo(n) .SH KEYWORDS application name, send +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/tkerror.n b/doc/tkerror.n index d66bf0f..0780901 100644 --- a/doc/tkerror.n +++ b/doc/tkerror.n @@ -14,7 +14,6 @@ tkerror \- Command invoked to process background errors .SH SYNOPSIS \fBtkerror \fImessage\fR .BE - .SH DESCRIPTION .PP Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to @@ -31,6 +30,8 @@ to the user. If you want your own error management you should directly override \fBbgerror\fR instead of \fBtkerror\fR. Documentation for \fBbgerror\fR is available as part of Tcl's documentation. - .SH KEYWORDS background error, reporting +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/tkvars.n b/doc/tkvars.n index 4a45868..a80fd54 100644 --- a/doc/tkvars.n +++ b/doc/tkvars.n @@ -10,20 +10,22 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -tkvars \- Variables used or set by Tk +geometry, tk_library, tk_patchLevel, tk_strictMotif, tk_version \- Variables used or set by Tk .BE - .SH DESCRIPTION .PP The following Tcl variables are either set or used by Tk at various times in its execution: .TP 15 \fBtk_library\fR +. This variable holds the file name for a directory containing a library of Tcl scripts related to Tk. These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors for widgets. +.RS +.PP The initial value of \fBtcl_library\fR is set when Tk is added to an interpreter; this is done by searching several different directories until one is found that contains an appropriate Tk startup script. @@ -34,36 +36,34 @@ directory, then Tk checks several other directories based on a compiled-in default location, the location of the Tcl library directory, the location of the binary containing the application, and the current working directory. +.PP The variable can be modified by an application to switch to a different library. +.RE .TP \fBtk_patchLevel\fR -Contains a decimal integer giving the current patch level for Tk. +. +Contains a dot-separated sequence of decimal integers giving the +current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk. -.TP -\fBtk::Priv\fR -This variable is an array containing several pieces of information -that are private to Tk. The elements of \fBtk::Priv\fR are used by -Tk library procedures and default bindings. -They should not be accessed by any code outside Tk. +.RS +.PP +This value is normally the same as the result of +.QW "\fBpackage require\fR \fBTk\fR" . +.RE .TP \fBtk_strictMotif\fR +. This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. -.TP -\fBtk_textRedraw\fR -.TP -\fBtk_textRelayout\fR -These variables are set by text widgets when they have debugging -turned on. The values written to these variables can be used to -test or debug text widget operations. These variables are mostly -used by Tk's test suite. +Modern applications should not normally set this variable. .TP 15 \fBtk_version\fR +. Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and @@ -73,6 +73,38 @@ any Tk release that includes changes that are not backward compatible work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes. - +.SS "INTERNAL AND DEBUGGING VARIABLES" +.PP +These variables should not normally be set by user code. +.TP +\fBtk::Priv\fR +. +This variable is an array containing several pieces of information +that are private to Tk. The elements of \fBtk::Priv\fR are used by +Tk library procedures and default bindings. +They should not be accessed by any code outside Tk. +.TP +\fBtk_textRedraw\fR +.TP +\fBtk_textRelayout\fR +. +These variables are set by text widgets when they have debugging +turned on. The values written to these variables can be used to +test or debug text widget operations. These variables are mostly +used by Tk's test suite. +.SH "OTHER GLOBAL VARIABLES" +The following variables are only guaranteed to exist in \fBwish\fR +executables; the Tk library does not define them itself but many Tk +environments do. +.TP 6 +\fBgeometry\fR +. +If set, contains the user-supplied geometry specification to use for +the main Tk window. +.SH "SEE ALSO" +package(n), tclvars(n), wish(1) .SH KEYWORDS -variables, version, text +environment, text, variables, version +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/tkwait.n b/doc/tkwait.n index 334d518..a31aee7 100644 --- a/doc/tkwait.n +++ b/doc/tkwait.n @@ -18,7 +18,6 @@ tkwait \- Wait for variable to change or window to be destroyed .sp \fBtkwait window \fIname\fR .BE - .SH DESCRIPTION .PP The \fBtkwait\fR command waits for one of several things to happen, @@ -44,6 +43,10 @@ the normal fashion, so the application will continue to respond to user interactions. If an event handler invokes \fBtkwait\fR again, the nested call to \fBtkwait\fR must complete before the outer call can complete. - +.SH "SEE ALSO" +bind(n), vwait(n) .SH KEYWORDS variable, visibility, wait, window +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/toplevel.n b/doc/toplevel.n index 80008be..271d9f1 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -toplevel \- Create and manipulate toplevel widgets +toplevel \- Create and manipulate 'toplevel' main and popup window widgets .SH SYNOPSIS \fBtoplevel\fR \fIpathName \fR?\fIoptions\fR? .SO @@ -20,7 +20,7 @@ toplevel \- Create and manipulate toplevel widgets .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background -This option is the same as the standard \fBbackground\fR option +This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background @@ -30,7 +30,7 @@ Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR +The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. @@ -39,7 +39,7 @@ created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. -If the \fBcolormap\fR option is not specified, the new window +If the \fB\-colormap\fR option is not specified, the new window uses the default colormap of its screen. This option may not be changed with the \fBconfigure\fR widget command. @@ -86,7 +86,7 @@ Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the default visual for its screen. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR +The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms @@ -94,7 +94,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 \fBtoplevel\fR command creates a new toplevel widget (given @@ -112,7 +111,6 @@ purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only visible features of a toplevel are its background color and an optional 3-D border to make the toplevel appear raised or sunken. - .SH "WIDGET COMMAND" .PP The \fBtoplevel\fR command creates a new Tcl command whose @@ -127,7 +125,7 @@ the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for toplevel widgets: .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR @@ -146,18 +144,14 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. - .SH BINDINGS .PP When a new toplevel is created, it has no default event bindings: toplevels are not intended to be interactive. - .SH "SEE ALSO" frame(n) - .SH KEYWORDS toplevel, widget - '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 index f403004..8dfae37 100644 --- a/doc/ttk_Geometry.3 +++ b/doc/ttk_Geometry.3 @@ -88,7 +88,7 @@ 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. +Extra padding (in pixels) to add to the right side of a region. .AP Ttk_Side side in One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, \fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR. @@ -128,7 +128,7 @@ typedef struct { .CE All coordinates are relative to the window. .PP -\fBTtk_MakeBox\fR is a convenience routine that contsructs +\fBTtk_MakeBox\fR is a convenience routine that constructs a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates. .PP @@ -173,7 +173,7 @@ typedef struct { } \fBTtk_Padding\fR; .CE .PP -\fBTtk_MakePadding\fR is a convenience routine that contsructs +\fBTtk_MakePadding\fR is a convenience routine that constructs a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom components. .PP diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index 924aa05..34779a6 100644 --- a/doc/ttk_entry.n +++ b/doc/ttk_entry.n @@ -39,7 +39,7 @@ requests when it has a selection. .\" 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. +A script template to evaluate whenever the \fB\-validatecommand\fR returns 0. See \fBVALIDATION\fR below for more information. .OP \-justify justify Justify Specifies how the text is aligned within the entry widget. @@ -87,7 +87,7 @@ in average-size characters of the widget's font. .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 +If an entry is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type \fBSTRING\fR. Entries also observe the standard Tk rules for dealing with the @@ -99,8 +99,8 @@ 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 +the standard \fB\-xscrollcommand\fR mechanism for interacting with +scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). .SH "INDICES" .PP diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index 12c3d6b..cecae48 100644 --- a/doc/ttk_notebook.n +++ b/doc/ttk_notebook.n @@ -100,7 +100,7 @@ which returns the number of tabs .QW "\fIpathname \fBindex\fR" ). .SH "WIDGET COMMAND" .TP -\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBadd \fIwindow\fR ?\fIoptions...\fR? Adds a new tab to the notebook. See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR. If \fIwindow\fR is currently managed by the notebook but hidden, @@ -109,38 +109,38 @@ it is restored to its previous position. \fIpathname \fBconfigure\fR ?\fIoptions\fR? See \fIttk::widget(n)\fR. .TP -\fIpathname \fBcget\fR \fIoption\fR +\fIpathname \fBcget \fIoption\fR See \fIttk::widget(n)\fR. .TP -\fIpathname \fBforget\fR \fItabid\fR +\fIpathname \fBforget \fItabid\fR Removes the tab specified by \fItabid\fR, unmaps and unmanages the associated window. .TP -\fIpathname \fBhide\fR \fItabid\fR +\fIpathname \fBhide \fItabid\fR Hides the tab specified by \fItabid\fR. The tab will not be displayed, but the associated window remains managed by the notebook and its configuration remembered. Hidden tabs may be restored with the \fBadd\fR command. .TP -\fIpathname \fBidentify\fR \fIcomponent\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify\fI component x y\fR Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. The following subcommands are supported: .RS .TP -\fIpathname \fBidentify\fR \fBelement\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify element\fR \fIx y\fR Returns the name of the element at the specified location. .TP -\fIpathname \fBidentify\fR \fBtab\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify tab\fR \fIx y\fR Returns the index of the tab at the specified location. .RE .TP -\fIpathname \fBindex\fR \fItabid\fR +\fIpathname \fBindex \fItabid\fR Returns the numeric index of the tab specified by \fItabid\fR, or the total number of tabs if \fItabid\fR is the string .QW \fBend\fR . .TP -\fIpathname \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\fR +\fIpathname \fBinsert \fIpos subwindow options...\fR Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. @@ -148,7 +148,7 @@ 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? +\fIpathname \fBinstate \fIstatespec \fR?\fIscript...\fR? See \fIttk::widget(n)\fR. .TP \fIpathname \fBselect\fR ?\fItabid\fR? @@ -161,7 +161,7 @@ currently selected pane. \fIpathname \fBstate\fR ?\fIstatespec\fR? See \fIttk::widget(n)\fR. .TP -\fIpathname \fBtab\fR \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR +\fIpathname \fBtab \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR Query or modify the options of the specific tab. If no \fI\-option\fR is specified, returns a dictionary of the tab option values. @@ -184,9 +184,9 @@ 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. +\fBControl-Shift-Tab\fR selects the tab preceding the currently selected one. .IP \(bu -\fBAlt-K\fR, where \fBK\fR is the mnemonic (underlined) character +\fBAlt-\fIK\fR, where \fIK\fR is the mnemonic (underlined) character of any tab, will select that tab. .PP Multiple notebooks in a single toplevel may be enabled for traversal, diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index 27eb57d..29fca1d 100644 --- a/doc/ttk_panedwindow.n +++ b/doc/ttk_panedwindow.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH ttk::panedwindow n 8.5.9 Tk "Tk Themed Widget" +.TH ttk::panedwindow n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME @@ -52,29 +52,29 @@ 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 +\fIpathname \fBadd \fIsubwindow options...\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 +\fIpathname \fBforget \fIpane\fR Removes the specified subpane from the widget. \fIpane\fR is either an integer index or the name of a managed subwindow. .TP -\fIpathname\fR \fBidentify\fR \fIcomponent\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify \fIcomponent x y\fR Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. If \fIcomponent\fR is omitted, it defaults to \fBsash\fR. The following subcommands are supported: .RS .TP -\fIpathname\fR \fBidentify\fR \fBelement\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify element \fIx y\fR Returns the name of the element at the specified location. .TP -\fIpathname\fR \fBidentify\fR \fBsash\fR \fIx\fR \fIy\fR +\fIpathname \fBidentify sash \fIx y\fR Returns the index of the sash at the specified location. .RE .TP -\fIpathname\fR \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\fR +\fIpathname \fBinsert \fIpos subwindow options...\fR Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. @@ -82,7 +82,7 @@ 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 +\fIpathname \fBpane \fIpane \-option \fR?\fIvalue \fR?\fI\-option value...\fR Query or modify the options of the specified \fIpane\fR, where \fIpane\fR is either an integer index or the name of a managed subwindow. If no \fI\-option\fR is specified, returns a dictionary of the pane @@ -90,10 +90,10 @@ 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 +\fIpathname \fBpanes\fR Returns the list of all windows managed by the widget. .TP -\fIpathname\fR \fBsashpos\fR \fIindex\fR ?\fInewpos\fR? +\fIpathname \fBsashpos \fIindex\fR ?\fInewpos\fR? If \fInewpos\fR is specified, sets the position of sash number \fIindex\fR. May adjust the positions of adjacent sashes diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n index 3b90371..6306450 100644 --- a/doc/ttk_progressbar.n +++ b/doc/ttk_progressbar.n @@ -57,13 +57,13 @@ to provide additional animation effects. .SH "WIDGET COMMAND" .PP .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? Modify or query widget options; see \fIttk::widget(n)\fR. .TP -\fIpathName \fBidentify\fR \fIx y\fR +\fIpathName \fBidentify \fIx y\fR Returns the name of the element at position \fIx\fR, \fIy\fR. See \fIttk::widget(n)\fR. .TP diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n index 86fc417..c16f2cd 100644 --- a/doc/ttk_radiobutton.n +++ b/doc/ttk_radiobutton.n @@ -29,7 +29,7 @@ it sets the variable to its associated value. .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 +The value to store in the associated \fB\-variable\fR when the widget is selected. .OP \-variable variable Variable The name of a global variable whose value is linked to the widget. diff --git a/doc/ttk_scale.n b/doc/ttk_scale.n index 7371b58..b52f9ac 100644 --- a/doc/ttk_scale.n +++ b/doc/ttk_scale.n @@ -39,7 +39,7 @@ 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. +This value may be either less than or greater than the \fB\-from\fR option. .OP \-value value Value Specifies the current floating-point value of the variable. .OP \-variable variable Variable @@ -65,7 +65,7 @@ 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 +\fIpathName \fBidentify \fIx y\fR Returns the name of the element at position \fIx\fR, \fIy\fR. See \fIttk::widget(n)\fR. .TP diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index 0a2c719..56df214 100644 --- a/doc/ttk_scrollbar.n +++ b/doc/ttk_scrollbar.n @@ -48,7 +48,7 @@ Specifies the orientation of the scrollbar. .SH "WIDGET COMMAND" .PP .TP -\fIpathName \fBcget\fR \fIoption\fR +\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? @@ -58,14 +58,14 @@ Modify or query widget options; see \fIttk::widget(n)\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 +\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 \fIfirst last\fR +\fIpathName \fBset \fIfirst last\fR This command is normally invoked by the scrollbar's associated widget from an \fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. Specifies the visible range to be displayed. diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n index 3c7287a..f10af3d 100644 --- a/doc/ttk_spinbox.n +++ b/doc/ttk_spinbox.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH ttk::spinbox n 8.5.9 Tk "Tk Themed Widget" +.TH ttk::spinbox n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME @@ -30,11 +30,11 @@ to a Tcl variable. .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 +used in conjunction with \fB\-to\fR and \fB\-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. +widget. See also \fB\-from\fR and \fB\-increment\fR. range. .OP \-increment increment Increment A floating\-point value specifying the change in value to be applied each @@ -42,8 +42,8 @@ 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 +override any range set using the \fB\-from\fR, \fB\-to\fR and +\fB\-increment\fR options. The widget will instead use the values specified beginning with the first value. .OP \-wrap wrap Wrap Must be a proper boolean value. If on, the spinbox will wrap around the @@ -61,7 +61,7 @@ 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. +\fB\-validate\fR and \fB\-validatecommand\fR options. .SH "WIDGET COMMAND" .PP The following subcommands are possible for spinbox widgets in addition to @@ -73,9 +73,9 @@ the commands described for the \fBttk::entry\fR widget: 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 +Set the spinbox string to \fIvalue\fR. If a \fB\-format\fR option has been configured then this format will be applied. If formatting fails -or is not set or the \fI\-values\fR option has been used then the value +or is not set or the \fB\-values\fR option has been used then the value is set directly. .SH "VIRTUAL EVENTS" .PP diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index ef8d34d..dd83c20 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH ttk::treeview n 8.5.9 Tk "Tk Themed Widget" +.TH ttk::treeview n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME @@ -380,16 +380,16 @@ the specified tag. \fIpathName \fBtag names\fR Returns a list of all tags used by the widget. .TP -\fIpathName \fBtag add\fR \fItag\fR \fIitems\fR +\fIpathName \fBtag add \fItag items\fR Adds the specified \fItag\fR to each of the listed \fIitems\fR. If \fItag\fR is already present for a particular item, -then the \fB-tags\fR for that item are unchanged. +then the \fB\-tags\fR for that item are unchanged. .TP -\fIpathName \fBtag remove\fR \fItag\fR ?\fIitems\fR? +\fIpathName \fBtag remove \fItag\fR ?\fIitems\fR? Removes the specified \fItag\fR from each of the listed \fIitems\fR. If \fIitems\fR is omitted, removes \fItag\fR from each item in the tree. If \fItag\fR is not present for a particular item, -then the \fB-tags\fR for that item are unchanged. +then the \fB\-tags\fR for that item are unchanged. .RE .TP \fIpathName \fBxview \fIargs\fR diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index 96fdf28..34145fb 100644 --- a/doc/ttk_vsapi.n +++ b/doc/ttk_vsapi.n @@ -14,54 +14,58 @@ ttk_vsapi \- Define a Microsoft Visual Styles element .BE .SH DESCRIPTION .PP -The \fIvsapi\fR element factory creates a new element +The \fBvsapi\fR element factory creates a new element in the current theme whose visual appearance is drawn using the -Microsoft Visual Styles API which is reponsible for the themed styles +Microsoft Visual Styles API which is responsible for the themed styles on Windows XP and Vista. This factory permits any of the Visual -Styles parts to be declared as ttk elements that can then be -included in a style layout to modify the appearance of ttk widgets. +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 +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 +\fB\-padding \fIpadding\fR +. Specify the element's interior padding. \fIpadding\fR is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options. .TP -\fB\-margins\fR \fIpadding\fR +\fB\-margins \fIpadding\fR +. Specifies the elements exterior padding. \fIpadding\fR is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options. .TP -\fB\-width\fR \fIwidth\fR +\fB\-width \fIwidth\fR +. Specifies the height for the element. If this option is set then the Visual Styles API will not be queried for the recommended -size or the part. If this option is set then \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. +size or the part. If this option is set then \fB\-height\fR should +also be set. The \fB\-width\fR and \fB\-height\fR options cannot +be mixed with the \fB\-padding\fR or \fB\-margins\fR options. .TP -\fB\-height\fR \fIheight\fR -Specifies the height of the element. See the comments for \fI-width\fR. +\fB\-height \fIheight\fR +. +Specifies the height of the element. See the comments for \fB\-width\fR. .SH "STATE MAP" .PP The \fIstateMap\fR parameter is a list of ttk states and the corresponding Visual Styles API state value. -This permits the element appearence to respond to changes in the +This permits the element appearance to respond to changes in the widget state such as becoming active or being pressed. The list should be as described for the \fBttk::style map\fR command but note that the last pair in the list should be the default state and is typically 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 +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 @@ -73,16 +77,16 @@ 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 \\ +ttk::style element create smallclose \fBvsapi\fR WINDOW 19 \\ {disabled 4 pressed 3 active 2 {} 1} ttk::style layout CloseButton {CloseButton.smallclose -sticky news} pack [ttk::button .close -style CloseButton] .CE .PP -Change the appearence of a \fBttk::checkbutton\fR(n) to use the +Change the appearance of a \fBttk::checkbutton\fR(n) to use the Explorer pin part EBP_HEADERPIN. .CS -ttk::style element create pin vsapi EXPLORERBAR 3 { +ttk::style element create pin \fBvsapi\fR EXPLORERBAR 3 { {pressed !selected} 3 {active !selected} 2 {pressed selected} 6 diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index 390635c..2ecc29f 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH ttk::widget n 8.5.9 Tk "Tk Themed Widget" +.TH ttk::widget n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME @@ -54,7 +54,7 @@ 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 +Typically the \fB\-xscrollcommand\fR option consists of the path name of a \fBscrollbar\fR widget followed by .QW set , e.g. @@ -123,11 +123,13 @@ but the \fBstate\fR widget command does not affect the \fB\-state\fR option. .SH COMMANDS .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) @@ -142,14 +144,16 @@ and current value. 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 +\fIpathName \fBidentify element \fIx y\fR +. Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or an empty string if the point does not lie within any element. \fIx\fR and \fIy\fR are pixel coordinates relative to the widget. Some widgets accept other \fBidentify\fR subcommands. .TP -\fIpathName \fBinstate\fR \fIstatespec\fR ?\fIscript\fR? +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +. Test the widget's state. If \fIscript\fR is not specified, returns 1 if the widget state matches \fIstatespec\fR and 0 otherwise. @@ -159,6 +163,7 @@ 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 @@ -178,6 +183,7 @@ 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 @@ -187,19 +193,23 @@ and pressing a mouse button will cause some action to occur. (aka .QW hover ). .TP \fBdisabled\fR +. Widget is disabled under program control (aka .QW unavailable , -.QW inactive ) +.QW inactive ). .TP \fBfocus\fR -Widget has keyboard focus +. +Widget has keyboard focus. .TP \fBpressed\fR +. Widget is being pressed (aka .QW armed in Motif). .TP \fBselected\fR +. .QW On , .QW true , or @@ -207,6 +217,7 @@ or for things like checkbuttons and radiobuttons. .TP \fBbackground\fR +. Windows and the Mac have a notion of an .QW active or foreground window. @@ -214,9 +225,11 @@ 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 @@ -225,11 +238,13 @@ or 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 @@ -245,13 +260,13 @@ indicating that the bit is off. set b [ttk::button .b] # Disable the widget: -$b state disabled +$b \fBstate\fR disabled # Invoke the widget only if it is currently pressed and enabled: -$b instate {pressed !disabled} { .b invoke } +$b \fBinstate\fR {pressed !disabled} { .b invoke } # Reenable widget: -$b state !disabled +$b \fBstate\fR !disabled .CE .SH "SEE ALSO" ttk::intro(n), ttk::style(n) diff --git a/doc/winfo.n b/doc/winfo.n index bb8e057..5008448 100644 --- a/doc/winfo.n +++ b/doc/winfo.n @@ -14,7 +14,6 @@ winfo \- Return window-related information .SH SYNOPSIS \fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBwinfo\fR command is used to retrieve information about windows @@ -105,7 +104,7 @@ in pixels. \fBwinfo height \fIwindow\fR Returns a decimal string giving \fIwindow\fR's height in pixels. When a window is first created its height will be 1 pixel; the -height will eventually be changed by a geometry manager to fulfill +height will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true height immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, @@ -316,7 +315,7 @@ Returns 0 if there is no virtual root window for \fIwindow\fR. \fBwinfo width \fIwindow\fR Returns a decimal string giving \fIwindow\fR's width in pixels. When a window is first created its width will be 1 pixel; the -width will eventually be changed by a geometry manager to fulfill +width will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true width immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, @@ -335,6 +334,7 @@ parent, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). .SH EXAMPLE +.PP Print where the mouse pointer is and what window it is currently over: .CS lassign [\fBwinfo pointerxy\fR .] x y @@ -346,7 +346,9 @@ if {$win eq ""} { puts "over $win" } .CE - .SH KEYWORDS atom, children, class, geometry, height, identifier, information, interpreters, mapped, parent, path name, screen, virtual root, width, window +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -15,10 +15,8 @@ wish \- Simple windowing shell \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. @@ -63,7 +61,7 @@ language, the Tk toolkit, and a main program that reads commands from standard input or from a file. It creates a main window and then processes Tcl commands. If \fBwish\fR is invoked with arguments, then the first few -arguments, ?\fB\-encoding \fIname\fR? ?\fIfileName\fR? specify the +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 @@ -213,5 +211,8 @@ The variable \fBtcl_prompt2\fR is used in a similar way when a newline is typed but the current command is not yet complete; if \fBtcl_prompt2\fR is not set then no prompt is output for incomplete commands. +.SH "SEE ALSO" +tclsh(1), toplevel(n), Tk_Main(3), Tk_MainLoop(3), Tk_MainWindow(3) .SH KEYWORDS -shell, toolkit +application, argument, interpreter, prompt, script file, shell, +toolkit, toplevel @@ -27,6 +27,7 @@ top-level window. The legal forms for the \fBwm\fR command are: .TP \fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? +. If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR are all specified, then they will be passed to the window manager and the window manager should use them to enforce a range of @@ -47,6 +48,7 @@ returned). \fBwm attributes \fIwindow\fR ?\fBoption\fR? .TP \fBwm attributes \fIwindow\fR ?\fBoption value option value...\fR? +. This subcommand returns or sets platform specific attributes associated with a window. The first form returns a list of the platform specific flags and their values. The second form returns the value for the @@ -57,82 +59,162 @@ values are as follows: All platforms support the following attributes (though X11 users should see the notes below): .TP +\fB\-alpha\fR +. +Specifies the alpha transparency level of the toplevel. It accepts a value +from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values outside that +range will be constrained. Where not supported, the \fB\-alpha\fR value +remains at \fB1.0\fR. +.TP \fB\-fullscreen\fR +. Places the window in a mode that takes up the entire screen, has no borders, and covers the general use area (i.e. Start menu and taskbar on Windows, dock and menubar on OSX, general window decorations on X11). .TP \fB\-topmost\fR +. Specifies whether this is a topmost window (displays above all other windows). .PP On Windows, the following attributes may be set. .TP -\fB\-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. -.VE 8.5 .PP On Mac OS X, the following attributes may be set. .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\-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 +the transparency to be effective, the toplevel background needs to be set to a color with some alpha, e.g. .QW systemTransparent . .PP -On X11, the following attributes may be set. -These are not supported by all window managers, -and will have no effect under older WMs. +On X11, the following attributes may be set. These are not supported by all +window managers, and will have no effect under older WMs. .\" See http://www.freedesktop.org/Standards/wm-spec .TP +\fB\-type\fR +.VS 8.6 +Requests that the window should be interpreted by the window manager as being +of the specified type(s). This may cause the window to be decorated in a +different way or otherwise managed differently, though exactly what happens is +entirely up to the window manager. A list of types may be used, in order of +preference. The following values are mapped to constants defined in the EWMH +specification (using others is possible, but not advised): +.RS +.TP +\fBdesktop\fR +. +indicates a desktop feature, +.TP +\fBdock\fR +. +indicates a dock/panel feature, +.TP +\fBtoolbar\fR +. +indicates a toolbar window that should be acting on behalf of another window, +as indicated with \fBwm transient\fR, +.TP +\fBmenu\fR +. +indicates a torn-off menu that should be acting on behalf of another window, +as indicated with \fBwm transient\fR, +.TP +\fButility\fR +. +indicates a utility window (e.g., palette or toolbox) that should be acting on +behalf of another window, as indicated with \fBwm transient\fR, +.TP +\fBsplash\fR +. +indicates a splash screen, displayed during application start up, +.TP +\fBdialog\fR +. +indicates a general dialog window, that should be acting on behalf of another +window, as indicated with \fBwm transient\fR, +.TP +\fBdropdown_menu\fR +. +indicates a menu summoned from a menu bar, which should usually also be set to +be override-redirected (with \fBwm overrideredirect\fR), +.TP +\fBpopup_menu\fR +. +indicates a popup menu, which should usually also be set to be +override-redirected (with \fBwm overrideredirect\fR), +.TP +\fBtooltip\fR +. +indicates a tooltip window, which should usually also be set to be +override-redirected (with \fBwm overrideredirect\fR), +.TP +\fBnotification\fR +. +indicates a window that provides a background notification of some event, +which should usually also be set to be override-redirected (with \fBwm +overrideredirect\fR), +.TP +\fBcombo\fR +. +indicates the drop-down list of a combobox widget, which should usually also +be set to be override-redirected (with \fBwm overrideredirect\fR), +.TP +\fBdnd\fR +. +indicates a window that represents something being dragged, which should +usually also be set to be override-redirected (with +\fBwm overrideredirect\fR), +.TP +\fBnormal\fR +. +indicates a window that has no special interpretation. +.RE +.VE 8.6 +.TP \fB\-zoomed\fR -Requests that the window should be maximized. -This is the same as \fBwm state zoomed\fR on Windows and Mac OS X. +. +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. +On X11, changes to window attributes are performed asynchronously. Querying +the value of an attribute returns the current state, which will not be the +same as the value most recently set if the window manager has not yet +processed the request or if it does not support the attribute. .RE .TP \fBwm client \fIwindow\fR ?\fIname\fR? +. If \fIname\fR is specified, this command stores \fIname\fR (which should be the name of the host on which the application is executing) in \fIwindow\fR's @@ -145,6 +227,7 @@ If \fIname\fR is specified as an empty string, the command deletes the \fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. .TP \fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? +. This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR property, which provides information to the window managers about windows that have private colormaps. @@ -175,6 +258,7 @@ See the ICCCM documentation for more information on the .RE .TP \fBwm command \fIwindow\fR ?\fIvalue\fR? +. If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's \fBWM_COMMAND\fR property for use by the window manager or session manager and returns an empty string. @@ -186,6 +270,7 @@ If \fIvalue\fR is specified as an empty string, the command deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. .TP \fBwm deiconify \fIwindow\fR +. Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. This is done by mapping the window. If the window has never been mapped then this command will not map the window, but it will ensure @@ -195,6 +280,7 @@ raised and be given the focus (made the active window). Returns an empty string. .TP \fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? +. If \fBactive\fR or \fBpassive\fR is supplied as an optional argument to the command, then it specifies the focus model for \fIwindow\fR. In this case the command returns an empty string. If no additional @@ -214,6 +300,7 @@ 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 @@ -221,6 +308,7 @@ longer managed by \fBwm\fR, however, the \fB\-menu\fR configuration will be remembered and the menus will return once the widget is managed again. .TP \fBwm frame \fIwindow\fR +. If \fIwindow\fR has been reparented by the window manager into a decorative frame, the command returns the platform specific window identifier for the outermost frame that contains \fIwindow\fR (the @@ -229,6 +317,7 @@ has not been reparented by the window manager then the command returns the platform specific window identifier for \fIwindow\fR. .TP \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? +. If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR is changed and an empty string is returned. Otherwise the current geometry for \fIwindow\fR is returned (this is the most recent @@ -272,6 +361,7 @@ made through this command. .RE .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? +. This command indicates that \fIwindow\fR is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. @@ -307,6 +397,7 @@ provide easier access to the same functionality. .RE .TP \fBwm group \fIwindow\fR ?\fIpathName\fR? +. If \fIpathName\fR is specified, it gives the path name for the leader of a group of related windows. The window manager may use this information, for example, to unmap all of the windows in a group when the group's @@ -317,6 +408,7 @@ returns the path name of \fIwindow\fR's current group leader, or an empty string if \fIwindow\fR is not part of any group. .TP \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? +. If \fIbitmap\fR is specified, then it names a bitmap in the standard forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). This bitmap is passed to the window manager to be displayed in @@ -327,10 +419,11 @@ If \fIbitmap\fR is specified then the command returns an empty string. Otherwise it returns the name of the current icon bitmap associated with \fIwindow\fR, or an empty string if \fIwindow\fR has no icon bitmap. On the Windows operating -system, an additional flag is supported: +system, an additional flag is supported: .RS .TP \fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR? +. If the \fB\-default\fR flag is given, the icon is applied to all toplevel windows (existing and future) to which no other specific icon has yet been applied. @@ -344,11 +437,13 @@ a bitmap. .RE .TP \fBwm iconify \fIwindow\fR +. Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped. .TP \fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? +. If \fIbitmap\fR is specified, then it names a bitmap in the standard forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). This bitmap is passed to the window manager to be used as a mask @@ -363,6 +458,7 @@ returns the name of the current icon mask associated with \fIwindow\fR, or an empty string if no mask is in effect. .TP \fBwm iconname \fIwindow\fR ?\fInewName\fR? +. If \fInewName\fR is specified, then it is passed to the window manager; the window manager should display \fInewName\fR inside the icon associated with \fIwindow\fR. In this case an empty @@ -371,9 +467,9 @@ 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 @@ -393,10 +489,10 @@ 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 manager as a hint about where to position the icon for \fIwindow\fR. In this case an empty string is returned. If \fIx\fR and \fIy\fR are @@ -406,6 +502,7 @@ a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned). .TP \fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? +. If \fIpathName\fR is specified, it is the path name for a window to use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then \fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR @@ -423,6 +520,7 @@ 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 @@ -431,6 +529,7 @@ an error. Attempting to manage a \fItoplevel\fR widget is benign and achieves nothing. See also \fBGEOMETRY MANAGEMENT\fR. .TP \fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? +. If \fIwidth\fR and \fIheight\fR are specified, they give the maximum permissible dimensions for \fIwindow\fR. For gridded windows the dimensions are specified in @@ -445,6 +544,7 @@ The maximum size defaults to the size of the screen. See the sections on geometry management below for more information. .TP \fBwm minsize \fIwindow\fR ?\fIwidth height\fR? +. If \fIwidth\fR and \fIheight\fR are specified, they give the minimum permissible dimensions for \fIwindow\fR. For gridded windows the dimensions are specified in @@ -459,6 +559,7 @@ The minimum size defaults to one pixel in each dimension. See the sections on geometry management below for more information. .TP \fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? +. If \fIboolean\fR is specified, it must have a proper boolean form and the override-redirect flag for \fIwindow\fR is set to that value. If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is @@ -469,8 +570,16 @@ it to be ignored by the window manager; among other things, this means that the window will not be reparented from the root window into a decorative frame and the user will not be able to manipulate the window using the normal window manager mechanisms. +.RS +.PP +Note that the override-redirect flag is only guaranteed to be taken notice of +when the window is first mapped or when mapped after the state is changed from +withdrawn to normal. Some, but not all, platforms will take notice at +additional times. +.RE .TP \fBwm positionfrom \fIwindow\fR ?\fIwho\fR? +. If \fIwho\fR is specified, it must be either \fBprogram\fR or \fBuser\fR, or an abbreviation of one of these two. It indicates whether \fIwindow\fR's current position was requested by the @@ -491,6 +600,7 @@ when a \fBwm geometry\fR command is invoked, unless the source has been set explicitly to \fBprogram\fR. .TP \fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? +. This command is used to manage window manager protocols such as \fBWM_DELETE_WINDOW\fR. \fIName\fR is the name of an atom corresponding to a window manager @@ -524,6 +634,7 @@ which it was received. .RE .TP \fBwm resizable \fIwindow\fR ?\fIwidth height\fR? +. This command controls whether or not the user may interactively resize a top-level window. If \fIwidth\fR and \fIheight\fR are specified, they are boolean values that determine whether the @@ -539,6 +650,7 @@ command. If there has been no such operation then the window's natural size will be used. .TP \fBwm sizefrom \fIwindow\fR ?\fIwho\fR? +. If \fIwho\fR is specified, it must be either \fBprogram\fR or \fBuser\fR, or an abbreviation of one of these two. It indicates whether \fIwindow\fR's current size was requested by the @@ -556,6 +668,7 @@ no source has been specified yet. Most window managers interpret as equivalent to \fBprogram\fR. .TP \fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? +. The \fBstackorder\fR command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the @@ -569,6 +682,7 @@ or not the first window is currently above or below the second window in the stacking order. .TP \fBwm state \fIwindow\fR ?newstate? +. If \fInewstate\fR is specified, the window will be set to the new state, otherwise it returns the current state of \fIwindow\fR: either \fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and Mac @@ -580,6 +694,7 @@ purpose is to serve as the icon for some other window (via the \fBwm iconwindow\fR command). The \fBicon\fR state cannot be set. .TP \fBwm title \fIwindow\fR ?\fIstring\fR? +. If \fIstring\fR is specified, then it will be passed to the window manager for use as the title for \fIwindow\fR (the window manager should display this string in \fIwindow\fR's title bar). In this @@ -588,6 +703,7 @@ specified then the command returns the current title for the \fIwindow\fR. The title for a window defaults to its name. .TP \fBwm transient \fIwindow\fR ?\fImaster\fR? +. If \fImaster\fR is specified, then the window manager is informed that \fIwindow\fR is a transient window (e.g. pull-down menu) working on behalf of \fImaster\fR (where \fImaster\fR is the @@ -599,8 +715,12 @@ empty string if \fIwindow\fR is not currently a transient window. A transient window will mirror state changes in the master and inherit the state of the master when initially mapped. It is an error to attempt to make a window a transient of itself. +The window manager may also decorate a transient window differently, removing +some features normally present (e.g., minimize and maximize buttons) though +this is entirely at the discretion of the window manager. .TP \fBwm withdraw \fIwindow\fR +. Arranges for \fIwindow\fR to be withdrawn from the screen. This causes the window to be unmapped and forgotten about by the window manager. If the window @@ -693,6 +813,7 @@ operation of the \fBwm\fR command. For example, some changes will not take effect if the window is already active: the window will have to be withdrawn and de-iconified in order to make the change happen. .SH EXAMPLES +.PP A fixed-size window that says that it is fixed-size too: .CS toplevel .fixed @@ -727,3 +848,6 @@ set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] toplevel(n), winfo(n) .SH KEYWORDS aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager +'\" Local Variables: +'\" mode: nroff +'\" End: |