diff options
Diffstat (limited to 'doc')
54 files changed, 418 insertions, 321 deletions
diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 index ddc1030..92be073 100644 --- a/doc/ConfigWidg.3 +++ b/doc/ConfigWidg.3 @@ -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 Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -174,7 +174,7 @@ legal values for \fItype\fR, and the corresponding actions, are: \fBTK_CONFIG_ACTIVE_CURSOR\fR The value must be an ASCII string identifying a cursor in a form -suitable for passing to \fBTk_GetCursor\fR. +suitable for passing to \fBTk_GetCursor\fR. The value is converted to a \fBTk_Cursor\fR by calling \fBTk_GetCursor\fR and the result is stored in the target. In addition, the resulting cursor is made the active cursor diff --git a/doc/CrtSelHdlr.3 b/doc/CrtSelHdlr.3 index 2aeffa9..2292ccc 100644 --- a/doc/CrtSelHdlr.3 +++ b/doc/CrtSelHdlr.3 @@ -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 Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS @@ -44,7 +44,7 @@ requestor. \fBTk_CreateSelHandler\fR arranges for a particular procedure (\fIproc\fR) to be called whenever \fIselection\fR is owned by \fItkwin\fR and the selection contents are requested in the -form given by \fItarget\fR. +form given by \fItarget\fR. \fITarget\fR should be one of the entries defined in the left column of Table 2 of the X Inter-Client Communication Conventions Manual (ICCCM) or diff --git a/doc/CrtWindow.3 b/doc/CrtWindow.3 index 8f44545..b254460 100644 --- a/doc/CrtWindow.3 +++ b/doc/CrtWindow.3 @@ -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 Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" .so man.macros .BS @@ -52,7 +52,7 @@ Name of new window, specified as path name within application .BE .SH DESCRIPTION .PP -The procedures \fBTk_CreateWindow\fR, +The procedures \fBTk_CreateWindow\fR, \fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR are used to create new windows for use in Tk-based applications. Each of the procedures returns a token diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3 index d6ccb5b..e4d83f0 100644 --- a/doc/FindPhoto.3 +++ b/doc/FindPhoto.3 @@ -99,6 +99,8 @@ being written to the photo image. particular photo image to the other procedures. The parameter is the name of the image, that is, the name specified to the \fBimage create photo\fR command, or assigned by that command if no name was specified. +If \fIimageName\fR does not exist or is not a photo image, +\fBTk_FindPhoto\fR returns NULL. .PP \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be displayed. The call affects an area of the image of size @@ -181,6 +183,18 @@ in the structure pointed to by the \fIblockPtr\fR parameter with values that describe the address and layout of the image data that the photo image has stored internally. The values are valid until the image is destroyed or its size is changed. +.PP +It is possible to modify an image by writing directly to the data +the \fIpixelPtr\fR field points to. The size of the image cannot be +changed this way, though. +Also, changes made by writing directly to \fIpixelPtr\fR will not be +immediately visible, but only after a call to +\fBTk_ImageChanged\fR or after an event that causes the interested +widgets to redraw themselves. +For these reasons usually it is preferable to make changes to +a copy of the image data and write it back with +\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. +.PP \fBTk_PhotoGetImage\fR returns 1 for compatibility with the corresponding procedure in the old photo widget. .PP diff --git a/doc/FontId.3 b/doc/FontId.3 index c79b89f..9d35ae6 100644 --- a/doc/FontId.3 +++ b/doc/FontId.3 @@ -3,12 +3,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME -Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for +Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for fonts .SH SYNOPSIS .nf @@ -37,7 +37,7 @@ Postscript font that corresponds to \fItkfont\fR will be appended. .PP Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be selected into an XGCValues structure in order to construct a graphics -context that can be used to draw text in the specified font. +context that can be used to draw text in the specified font. .PP \fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the \fItkfont\fR in pixels and stores those values in the structure pointer to by @@ -45,7 +45,7 @@ context that can be used to draw text in the specified font. multiple lines of text, to align the baselines of text in different fonts, and to vertically align text in a given region. See the documentation for the \fBfont\fR command for definitions of the terms -ascent, descent, and linespace, used in font metrics. +ascent, descent, and linespace, used in font metrics. .PP \fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding Postscript font name that should be used when printing. The return value @@ -56,10 +56,10 @@ appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized Postscript printer, the following screen font families should print correctly: .IP -\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, +\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, \fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, \fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, -\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and +\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and \fBZapf Dingbats\fR. .PP Any other font families may not print correctly because the computed diff --git a/doc/GetColor.3 b/doc/GetColor.3 index 9d07d95..15254aa 100644 --- a/doc/GetColor.3 +++ b/doc/GetColor.3 @@ -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 Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -127,7 +127,7 @@ This package maintains a database of all the colors currently in use. If the same color is requested multiple times from \fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different -windows), or if the +windows), or if the same intensities are requested multiple times from \fBTk_GetColorByValue\fR, then existing pixel values will be re-used. Re-using an existing pixel avoids any interaction diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 index 8526a47..403c05e 100644 --- a/doc/GetCursor.3 +++ b/doc/GetCursor.3 @@ -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 Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -118,7 +118,7 @@ in preference to black and white cursors. In this form, \fIsourceName\fR and \fImaskName\fR are the names of files describing cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. -\fIFgColor\fR and \fIbgColor\fR +\fIFgColor\fR and \fIbgColor\fR indicate the colors to use for the cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This form of the command will not work on Macintosh or Windows computers. diff --git a/doc/GetFont.3 b/doc/GetFont.3 index cf02f00..0504916 100644 --- a/doc/GetFont.3 +++ b/doc/GetFont.3 @@ -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 Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -14,19 +14,19 @@ Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFr .nf \fB#include <tk.h>\fR .sp -Tk_Font +Tk_Font \fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp -Tk_Font -\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR +Tk_Font +\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR .sp -Tk_Font +Tk_Font \fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR .sp const char * \fBTk_NameOfFont(\fItkfont\fB)\fR .sp -Tk_Font +Tk_Font \fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR .sp void @@ -55,7 +55,7 @@ returns a token that represents the font. The return value can be used in subsequent calls to procedures such as \fBTk_GetFontMetrics\fR, \fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR. The Tk_Font token will remain valid until -\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. +\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. \fIObjPtr\fR can contain either a symbolic name or a font description; see the documentation for the \fBfont\fR command for a description of the valid formats. If \fBTk_AllocFontFromObj\fR is unsuccessful (because, diff --git a/doc/MapWindow.3 b/doc/MapWindow.3 index 8abce64..a3c6296 100644 --- a/doc/MapWindow.3 +++ b/doc/MapWindow.3 @@ -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 Tk_MapWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS @@ -35,9 +35,9 @@ deferred window creation. from the screen. .PP If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was -used to create a child window), then event handlers interested in map -and unmap events are invoked immediately. If \fItkwin\fR is not an -internal window, then the event handlers will be invoked later, after +used to create a child window), then event handlers interested in map +and unmap events are invoked immediately. If \fItkwin\fR is not an +internal window, then the event handlers will be invoked later, after X has seen the request and returned an event for it. .PP These procedures should be used in place of the X procedures diff --git a/doc/MeasureChar.3 b/doc/MeasureChar.3 index 7433451..3959978 100644 --- a/doc/MeasureChar.3 +++ b/doc/MeasureChar.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -32,7 +32,7 @@ returned by a previous call to \fBTk_GetFont\fR. Text to be measured or displayed. Need not be null terminated. Any non-printing meta-characters in the string (such as tabs, newlines, and other control characters) will be measured or displayed in a -platform-dependent manner. +platform-dependent manner. .AP int numBytes in The maximum number of bytes to consider when measuring or drawing \fIstring\fR. Must be greater than or equal to 0. @@ -60,11 +60,11 @@ Display on which to draw. .AP Drawable drawable in Window or pixmap in which to draw. .AP GC gc in -Graphics context for drawing characters. The font selected into this GC +Graphics context for drawing characters. The font selected into this GC must be the same as the \fItkfont\fR. .AP int "x, y" in Coordinates at which to place the left edge of the baseline when displaying -\fIstring\fR. +\fIstring\fR. .AP int firstByte in The index of the first byte of the first character to underline in the \fIstring\fR. Underlining begins at the left edge of this character. @@ -80,7 +80,7 @@ single-line strings. To measure and display single-font, multi-line, justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR. There is no programming interface in the core of Tk that supports multi-font, multi-line text; support for that behavior must be built on -top of simpler layers. +top of simpler layers. Note that the interfaces described here are byte-oriented not character-oriented, so index values coming from Tcl scripts need to be converted to byte offsets using the @@ -95,7 +95,7 @@ escape sequences, while under Windows and Macintosh hollow or solid boxes may be substituted. Refer to the documentation for \fBTk_ComputeTextLayout\fR for a programming interface that supports the platform-independent expansion of tab characters into columns and -newlines/returns into multi-line text. +newlines/returns into multi-line text. .PP \fBTk_MeasureChars\fR is used both to compute the length of a given string and to compute how many characters from a string fit in a given @@ -106,12 +106,12 @@ value will be \fInumBytes\fR. \fI*lengthPtr\fR is filled with the computed width, in pixels, of the portion of the string that was measured. For example, if the return value is 5, then \fI*lengthPtr\fR is filled with the distance between the left edge of \fIstring\fR[0] and the right edge of -\fIstring\fR[4]. +\fIstring\fR[4]. .PP \fBTk_TextWidth\fR is a wrapper function that provides a simpler interface to the \fBTk_MeasureChars\fR function. The return value is how much space in pixels the given \fIstring\fR needs. -.PP +.PP \fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the given \fIdrawable\fR. .PP @@ -120,7 +120,7 @@ given \fIstring\fR. It does not draw the characters (which are assumed to have been displayed previously by \fBTk_DrawChars\fR); it just draws the underline. This procedure is used to underline a few characters without having to construct an underlined font. To produce natively underlined -text, the appropriate underlined font should be constructed and used. +text, the appropriate underlined font should be constructed and used. .SH "SEE ALSO" font(n), FontId(3) .SH KEYWORDS diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 index 3863ee7..5729a44 100644 --- a/doc/TextLayout.3 +++ b/doc/TextLayout.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS @@ -48,7 +48,7 @@ have been returned by a previous call to \fBTk_GetFont\fR. .AP "const char" *string in Potentially multi-line string whose dimensions are to be computed and stored in the text layout. The \fIstring\fR must remain valid for the -lifetime of the text layout. +lifetime of the text layout. .AP int numChars in The number of characters to consider from \fIstring\fR. If \fInumChars\fR is less than 0, then assumes \fIstring\fR is null @@ -77,7 +77,7 @@ measured and displayed in a platform-dependent manner as described in \fBTk_MeasureChars\fR, and will not have any special behaviors. .AP int *widthPtr out If non-NULL, filled with either the width, in pixels, of the widest -line in the text layout, or the width, in pixels, of the bounding box for the +line in the text layout, or the width, in pixels, of the bounding box for the character specified by \fIindex\fR. .AP int *heightPtr out If non-NULL, filled with either the total height, in pixels, of all @@ -101,7 +101,7 @@ text layout when it is being drawn, or the coordinates of a point (with respect to the upper-left hand corner of the text layout) to check against the text layout. .AP int firstChar in -The index of the first character to draw from the given text layout. +The index of the first character to draw from the given text layout. The number 0 means to draw from the beginning. .AP int lastChar in The index of the last character up to which to draw. The character @@ -119,7 +119,7 @@ for the character specified by \fIindex\fR. Either or both \fIxPtr\fR and \fIyPtr\fR may be NULL, in which case the corresponding value is not calculated. .AP int "width, height" in -Specifies the width and height, in pixels, of the rectangular area to +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 @@ -132,7 +132,7 @@ justified text. To measure and display simple single-font, single-line strings, refer to the documentation for \fBTk_MeasureChars\fR. There is no programming interface in the core of Tk that supports multi-font, multi-line text; support for that behavior must be built on top of -simpler layers. +simpler layers. Note that unlike the lower level text display routines, the functions described here all operate on character-oriented lengths and indices rather than byte-oriented values. See the description of @@ -150,11 +150,11 @@ returns a Tk_TextLayout token that holds this information. This token is used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, \fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The \fIstring\fR and \fItkfont\fR used when computing the layout must remain -valid for the lifetime of this token. +valid for the lifetime of this token. .PP \fBTk_FreeTextLayout\fR is called to release the storage associated with \fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used -in any other text layout procedures once it has been released. +in any other text layout procedures once it has been released. .PP \fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a single-font, multi-line, justified string of text at the specified location. @@ -191,7 +191,7 @@ placeholder character. \fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the bounding box for the character specified by \fIindex\fR. The width of the bounding box is the advance width of the character, and does not include any -left or right bearing. Any character that extends partially outside of +left or right bearing. Any character that extends partially outside of \fIlayout\fR is considered to be truncated at the edge. Any character that would be located completely outside of \fIlayout\fR is considered to be zero-width and pegged against the edge. The height of the bounding @@ -264,13 +264,13 @@ much as fits placed on the line and the rest on subsequent line(s). If \fIwrapLength\fR is so small that not even one character can fit on a given line, the \fIwrapLength\fR is ignored for that line and one character will be placed on the line anyhow. When wrapping is turned -off, only newline/return characters may cause a line break. +off, only newline/return characters may cause a line break. .PP When a text layout has been created using an underlined \fItkfont\fR, then any space characters that occur at the end of individual lines, -newlines/returns, and tabs will not be displayed underlined when +newlines/returns, and tabs will not be displayed underlined when \fBTk_DrawTextLayout\fR is called, because those characters are never actually drawn \- they are merely placeholders maintained in the -\fIlayout\fR. +\fIlayout\fR. .SH KEYWORDS font diff --git a/doc/Tk_Main.3 b/doc/Tk_Main.3 index a1bb149..ea5f771 100644 --- a/doc/Tk_Main.3 +++ b/doc/Tk_Main.3 @@ -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 Tk_Main 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS @@ -29,7 +29,7 @@ The value for this argument is usually \fBTcl_AppInit\fR. .SH DESCRIPTION .PP \fBTk_Main\fR acts as the main program for most Tk-based applications. -Starting with Tk 4.0 it is not called \fBmain\fR anymore because it +Starting with Tk 4.0 it is not called \fBmain\fR anymore because it is part of the Tk library and having a function \fBmain\fR in a library (particularly a shared library) causes problems on many systems. diff --git a/doc/WindowId.3 b/doc/WindowId.3 index 6d55dc0..f937963 100644 --- a/doc/WindowId.3 +++ b/doc/WindowId.3 @@ -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 Tk_WindowId 3 "8.4" Tk "Tk Library Procedures" .so man.macros .BS @@ -168,7 +168,7 @@ the window's minimum requested size. These values correspond to the last call to \fBTk_SetMinimumRequestSize\fR for \fItkwin\fR. .PP \fBTk_InternalBorderLeft\fR, \fBTk_InternalBorderRight\fR, -\fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR +\fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR return the width of one side of the internal border that has been requested for \fItkwin\fR, or 0 if no internal border was requested. The return value is simply the last value passed to diff --git a/doc/button.n b/doc/button.n index e9a45a3..233feb6 100644 --- a/doc/button.n +++ b/doc/button.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 button n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -69,7 +69,7 @@ In this state the \fB\-disabledforeground\fR and Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR). -For a text button (no image or with \fB\-compound none\fR) then the width +For a text button (no image or with \fB\-compound none\fR) then the width specifies how much space in characters to allocate for the text label. If the width is negative then this specifies a minimum width. If this option is not specified, the button's desired width is computed @@ -96,7 +96,7 @@ one of the characters may optionally be underlined using the \fB\-underline\fR option. It can display itself in either of three different ways, according to -the \fB\-state\fR option; +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 diff --git a/doc/canvas.n b/doc/canvas.n index bc29cc3..38697cd 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -263,7 +263,7 @@ automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For -polygons, numbers less than 0 or greater then the length +polygons, numbers less than 0 or greater than the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. @@ -405,7 +405,7 @@ behaves as if the \fIstart\fR argument had not been specified. . 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 +\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP \fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR @@ -413,7 +413,7 @@ no greater than \fIy2\fR. Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be +\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP \fBwithtag \fItagOrId\fR diff --git a/doc/checkbutton.n b/doc/checkbutton.n index 2e6f840..bfefca4 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.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 checkbutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -52,7 +52,7 @@ and setting \fB\-indicatoron\fR to false and \fB\-overrelief\fR to the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by -the Bold, Italic, and Underline checkbuttons on the toolbar of a +the Bold, Italic, and Underline checkbuttons on the toolbar of a word-processor, for example. .OP \-offvalue offValue Value Specifies value to store in the button's associated variable whenever diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index 86c593d..8528ddb 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. -'\" +'\" .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS @@ -20,7 +20,7 @@ possible as command line arguments: \fB\-initialdir\fR \fIdirname\fR Specifies that the directories in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, -the initial directory defaults to the current working directory +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 diff --git a/doc/clipboard.n b/doc/clipboard.n index 374cbd1..6f047dd 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.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 clipboard n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -17,7 +17,7 @@ clipboard \- Manipulate Tk clipboard .SH DESCRIPTION .PP This command provides a Tcl interface to the Tk clipboard, -which stores data for later retrieval using the selection mechanism +which stores data for later retrieval using the selection mechanism (via the \fB\-selection CLIPBOARD\fR option). In order to copy data into the clipboard, \fBclipboard clear\fR must be called, followed by a sequence of one or more calls to \fBclipboard @@ -52,7 +52,7 @@ Table 2 of the ICCCM), and defaults to \fBSTRING\fR. If \fIformat\fR is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other \fIformat\fR, \fIdata\fR is divided -into fields separated by white space and each +into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester. Note that strings passed to \fBclipboard append\fR are concatenated before conversion, so the diff --git a/doc/event.n b/doc/event.n index 7a3cfca..54ad42e 100644 --- a/doc/event.n +++ b/doc/event.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 event n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS @@ -172,7 +172,7 @@ one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or \fBNotifyWhileGrabbed\fR. Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events. -Corresponds to the \fB%m\fR substitution for binding scripts. +Corresponds to the \fB%m\fR substitution for binding scripts. .TP \fB\-override\fI boolean\fR \fIBoolean\fR must be a boolean value; it specifies the @@ -224,7 +224,7 @@ Corresponds to the \fB%#\fR substitution for binding scripts. For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events it must be an integer value. -For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, +For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR specified in the base \fIevent\fR. @@ -302,9 +302,9 @@ If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%Y\fR substitution for binding scripts. .PP -Any options that are not specified when generating an event are filled -with the value 0, except for \fIserial\fR, which is filled with the -next X event serial number. +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 @@ -351,6 +351,16 @@ This is sent to a widget when the focus leaves the widget because of a user-driven .QW "tab to widget" action. +.TP +\fB<<UndoStack>>\fR +This is sent to a text widget when its undo stack or redo stack becomes +empty or unempty. +.TP +\fB<<WidgetViewSync>>\fR +This is sent to a text widget when its internal data become obsolete, +and again when these internal data are back in sync with the widget +view. The detail field (%d substitution) is either true (when the +widget is in sync) or false (when it is not). .PP Tk defines the following virtual events for the purposes of unifying bindings across multiple platforms. Users expect them to behave in the @@ -540,7 +550,7 @@ will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. However, when the user types Meta-Control-y the \fB<<Paste>>\fR binding will be invoked, because the -\fBMeta\fR modifier in the physical pattern associated with the +\fBMeta\fR modifier in the physical pattern associated with the virtual binding is more specific than the \fB<Control-y\fR> sequence for the physical event. .PP @@ -560,7 +570,7 @@ bind Entry <Control-y> {} .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, +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" @@ -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 font n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS @@ -38,7 +38,7 @@ that character, which will be different from the base font if the base font does not contain the given character. If \fIchar\fR may be a hyphen, it should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled \fIoption\fR. -.TP +.TP \fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the desired attributes for the named font called @@ -88,7 +88,7 @@ omitted, it defaults to the main window. Measures the amount of space the string \fItext\fR would use in the given \fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is -omitted, it +omitted, it defaults to the main window. The return value is the total width in pixels of \fItext\fR, not including the extra pixels used by highly exaggerated characters such as cursive diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index f5e92ff..39bce41 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" .so man.macros .BS @@ -65,8 +65,8 @@ discussion on the contents of \fIfilePatternList\fR. \fB\-initialdir\fR \fIdirectory\fR . Specifies that the files in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, -the initial directory defaults to the current working directory +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 @@ -95,7 +95,7 @@ turns the file dialog into a sheet attached to the parent window. \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. +option is not specified, then a default title is displayed. .TP \fB\-typevariable\fR \fIvariableName\fR . diff --git a/doc/listbox.n b/doc/listbox.n index 9f34b5e..66b75b9 100644 --- a/doc/listbox.n +++ b/doc/listbox.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 listbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -17,9 +17,10 @@ listbox \- Create and manipulate 'listbox' item list widgets \-background \-borderwidth \-cursor \-disabledforeground \-exportselection \-font \-foreground \-highlightbackground \-highlightcolor -\-highlightthickness \-relief \-selectbackground -\-selectborderwidth \-selectforeground \-setgrid -\-takefocus \-xscrollcommand \-yscrollcommand +\-highlightthickness \-justify \-relief +\-selectbackground \-selectborderwidth \-selectforeground +\-setgrid \-takefocus \-xscrollcommand +\-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-activestyle activeStyle ActiveStyle @@ -228,7 +229,7 @@ list. Returns an empty string. \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 \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBitemconfigure\fR command. .TP \fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? @@ -248,7 +249,7 @@ are currently supported for items: .TP \fB\-background \fIcolor\fR . -\fIColor\fR specifies the background color to use when displaying the +\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 diff --git a/doc/loadTk.n b/doc/loadTk.n index d4ec51e..3673e98 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS @@ -11,7 +11,7 @@ .SH NAME safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS -\fBsafe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? +\fBsafe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? .BE .SH DESCRIPTION .PP @@ -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 menu n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS @@ -269,8 +269,8 @@ are appended to the standard Help menu of the user's menubar whenever the window's menubar is in front. The first items in the menu are provided by Mac OS X. .PP -When Tk sees a System menu on Windows, its items are appended to the -system menu that the menubar is attached to. This menu is tied to the +When Tk sees a System menu on Windows, its items are appended to the +system menu that the menubar is attached to. This menu is tied to the application icon and can be invoked with the mouse or by typing Alt+Spacebar. Due to limitations in the Windows API, any font changes, colors, images, bitmaps, or tearoff images will not appear in the @@ -676,7 +676,7 @@ 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 +In this state the entry is displayed according to the \fB\-disabledforeground\fR option for the menu and the \fB\-background\fR option from the entry. This option is not available for separator entries. diff --git a/doc/option.n b/doc/option.n index 8699c0d..2763d64 100644 --- a/doc/option.n +++ b/doc/option.n @@ -59,6 +59,12 @@ options specified in that file to the option database. If \fIpriority\fR is specified, it indicates the priority level at which to enter the options; \fIpriority\fR defaults to \fBinteractive\fR. .PP +The file is read through a channel which is in "utf-8" encoding, +invalid byte sequences are automatically converted to valid ones. +This means that encodings like ISO 8859-1 or cp1252 with high +probability will work as well, but this cannot be guaranteed. +This cannot be changed, setting the [encoding system] has no effect. +.PP The \fIpriority\fR arguments to the \fBoption\fR command are normally specified symbolically using one of the following values: .TP diff --git a/doc/options.n b/doc/options.n index 36937b1..738a1c6 100644 --- a/doc/options.n +++ b/doc/options.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 options n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -268,7 +268,7 @@ traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the \fB\-takefocus\fR option. A value of \fB0\fR means that the window should be skipped entirely -during keyboard traversal. +during keyboard traversal. \fB1\fR means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make @@ -278,7 +278,7 @@ disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. -The script must return \fB0\fR, \fB1\fR, or an empty string: a +The script must return \fB0\fR, \fB1\fR, or an empty string: a \fB0\fR or \fB1\fR value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. diff --git a/doc/panedwindow.n b/doc/panedwindow.n index e2c954a..fcfebf4 100644 --- a/doc/panedwindow.n +++ b/doc/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 panedwindow n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -151,7 +151,7 @@ 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. +Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE .TP \fIpathName \fBsash \fR?\fIargs\fR? @@ -239,13 +239,13 @@ dimension for vertical panedwindows. May be any value accepted by \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 +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 +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 diff --git a/doc/radiobutton.n b/doc/radiobutton.n index 557b42c..c79aa23 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.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 radiobutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS @@ -59,10 +59,10 @@ By setting this option to .QW flat and setting \fB\-indicatoron\fR to false and \fB\-overrelief\fR to .QW raised , -the effect is achieved +the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by -the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a +the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a word-processor, for example. .OP \-overrelief overRelief OverRelief Specifies an alternative relief for the radiobutton, to be used when the diff --git a/doc/scale.n b/doc/scale.n index 7bc5c59..0504b4b 100644 --- a/doc/scale.n +++ b/doc/scale.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 scale n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS @@ -209,7 +209,7 @@ the horizontal behavior is described in parentheses. .IP [1] If button 1 is pressed in the trough, the scale's value will be incremented or decremented by the value of the \fB\-resolution\fR -option so that the slider moves in the direction of the cursor. +option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats. .IP [2] If button 1 is pressed over the slider, the slider can be dragged diff --git a/doc/selection.n b/doc/selection.n index e06a716..f5bb660 100644 --- a/doc/selection.n +++ b/doc/selection.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 selection n 8.1 Tk "Tk Built-In Commands" .so man.macros .BS @@ -36,7 +36,7 @@ atom name such as \fBPRIMARY\fR or \fBCLIPBOARD\fR; see the Inter-Client Communication Conventions Manual for complete details. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . -Returns an empty string. +Returns an empty string. .TP \fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? . @@ -79,7 +79,7 @@ automatically handled as type \fBUTF8_STRING\fR as well. When \fIselection\fR is requested, \fIwindow\fR is the selection owner, and \fItype\fR is the requested type, \fIcommand\fR will be executed as a Tcl command with two additional numbers appended to it -(with space separators). +(with space separators). The two additional numbers are \fIoffset\fR and \fImaxChars\fR: \fIoffset\fR specifies a starting character position in the selection and \fImaxChars\fR gives the maximum diff --git a/doc/spinbox.n b/doc/spinbox.n index 7227cf1..330bb17 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -55,7 +55,7 @@ A floating-point value corresponding to the lowest value for a spinbox, to be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control its contents. This value must be less than the \fB\-to\fR option. -If \fB\-values\fR is specified, it supercedes this option. +If \fB\-values\fR is specified, it supersedes this option. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to an empty string disables this feature (the default). The best use of @@ -84,7 +84,7 @@ A floating-point value corresponding to the highest value for the spinbox, to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control its contents. This value must be greater than the \fB\-from\fR option. -If \fB\-values\fR is specified, it supercedes this option. +If \fB\-values\fR is specified, it supersedes this option. .OP \-validate validate Validate Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. @@ -486,6 +486,15 @@ much the line should be indented from the left edge of the window. option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line. .TP +\fB\-lmargincolor \fIcolor\fR +. +\fIColor\fR specifies the background color to use in regions that do not +contain characters because they are indented by \fB\-lmargin1\fR or +\fB\-lmargin2\fR. It may have any of the forms accepted by +\fBTk_GetColor\fR.If \fIcolor\fR has not been specified, or if it is +specified as an empty string, then the color specified by the +\fB-background\fR widget option is used. +.TP \fB\-offset \fIpixels\fR . \fIPixels\fR specifies an amount by which the text's baseline should be offset @@ -500,6 +509,13 @@ Specifies whether or not to draw a horizontal rule through the middle of characters. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. .TP +\fB\-overstrikefg \fIcolor\fR +. +\fIColor\fR specifies the color to use when displaying the overstrike. It may +have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not +been specified, or if it is specified as an empty string, then the color +specified by the \fB\-foreground\fR tag option is used. +.TP \fB\-relief \fIrelief\fR . \fIRelief\fR specifies the relief style to use for drawing the border, in any @@ -517,6 +533,28 @@ option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first non-elided character of that display line. .TP +\fB\-rmargincolor \fIcolor\fR +. +\fIColor\fR specifies the background color to use in regions that do not +contain characters because they are indented by \fB\-rmargin1\fR. It may +have any of the forms accepted by \fBTk_GetColor\fR.If \fIcolor\fR has not +been specified, or if it is specified as an empty string, then the color +specified by the \fB-background\fR widget option is used. +.TP +\fB\-selectbackground \fIcolor\fR +\fIColor\fR specifies the background color to use when displaying selected +items. It may have any of the forms accepted by \fBTk_GetColor\fR. If +\fIcolor\fR has not been specified, or if it is specified as an empty +string, then the color specified by the \fB\-background\fR tag option is +used. +.TP +\fB\-selectforeground \fIcolor\fR +\fIColor\fR specifies the foreground color to use when displaying selected +items. It may have any of the forms accepted by \fBTk_GetColor\fR. If +\fIcolor\fR has not been specified, or if it is specified as an empty +string, then the color specified by the \fB\-foreground\fR tag option is +used. +.TP \fB\-spacing1 \fIpixels\fR . \fIPixels\fR specifies how much additional space should be left above each @@ -559,6 +597,13 @@ unspecified for the tag (the default). \fIBoolean\fR specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR. .TP +\fB\-underlinefg \fIcolor\fR +. +\fIColor\fR specifies the color to use when displaying the underline. It may +have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not +been specified, or if it is specified as an empty string, then the color +specified by the \fB\-foreground\fR tag option is used. +.TP \fB\-wrap \fImode\fR . \fIMode\fR specifies how to handle lines that are wider than the text's @@ -852,6 +897,9 @@ separator is already present at the top of the undo stack no other will be inserted. That means that two separators on the undo stack are always separated by at least one insert or delete action. .PP +The \fB<<UndoStack>>\fR virtual event is generated every time the undo stack +or the redo stack becomes empty or unempty. +.PP The undo mechanism is also linked to the modified flag. This means that undoing or redoing changes can take a modified text widget back to the unmodified state or vice versa. The modified flag will be set automatically to @@ -935,7 +983,7 @@ geometry manager), one can resort to \fIpathName \fBsync\fR and \fIpathName \fBpendingsync\fR to control the synchronization of the view of text widgets. .PP The \fB<<WidgetViewSync>>\fR virtual event fires when the line heights of the -text widget becomes obsolete (due to some editing command or configuration +text widget become obsolete (due to some editing command or configuration change), and again when the internal data of the text widget are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). @@ -1128,22 +1176,30 @@ test suite. .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. +Attempts to delete characters in a way that would leave +the text without a newline as the last character will be tweaked by the +text widget to avoid this. In particular, deletion of complete lines of +text up to the end of the text will also delete the newline character just +before the deleted block so that it is replaced by the new final newline +of the text widget. +The command returns an empty string. +If more indices are given, multiple ranges of text will be deleted. +All indices are first checked for validity before any deletions are made. +They are sorted and the text is removed from the last range to the +first range so deleted text does not cause an undesired index shifting +side-effects. If multiple ranges with the same start index are given, +then the longest range is used. If overlapping ranges are given, then +they will be merged into spans that do not cause deletion of text +outside the given ranges due to text shifted during deletion. .TP \fIpathName \fBdlineinfo \fIindex\fR . @@ -1229,6 +1285,16 @@ behavior of the command depends on the \fIoption\fR argument that follows the supported: .RS .TP +\fIpathName \fBedit canredo\fR +. +Returns a boolean true if redo is possible, i.e. when the redo stack is not +empty. Otherwise returns false. +.TP +\fIpathName \fBedit canundo\fR +. +Returns a boolean true if undo is possible, i.e. when the undo stack is not +empty. Otherwise returns false. +.TP \fIpathName \fBedit modified \fR?\fIboolean\fR? . If \fIboolean\fR is not specified, returns the modified flag of the widget. diff --git a/doc/tkerror.n b/doc/tkerror.n index 0780901..53cb0d1 100644 --- a/doc/tkerror.n +++ b/doc/tkerror.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 tkerror n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS @@ -20,11 +20,11 @@ Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to \fBbgerror\fR because the event loop (which is what usually invokes it) is now part of Tcl. For backward compatibility the \fBbgerror\fR provided by the current Tk version still -tries to call \fBtkerror\fR if there is one (or an auto loadable one), +tries to call \fBtkerror\fR if there is one (or an auto loadable one), so old script defining that error handler should still work, but you -should anyhow modify your scripts to use \fBbgerror\fR instead +should anyhow modify your scripts to use \fBbgerror\fR instead of \fBtkerror\fR because that support for the old name might vanish -in the near future. If that call fails, \fBbgerror\fR +in the near future. If that call fails, \fBbgerror\fR posts a dialog showing the error and offering to see the stack trace to the user. If you want your own error management you should directly override \fBbgerror\fR instead of \fBtkerror\fR. diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 index 8dfae37..61015c5 100644 --- a/doc/ttk_Geometry.3 +++ b/doc/ttk_Geometry.3 @@ -75,7 +75,7 @@ Used to store error messages. .AP int left in Extra padding (in pixels) to add to the left side of a region. .AP "Tcl_Obj *" objPtr in -String value contains a symbolic name +String value contains a symbolic name to be converted to an enumerated value or bitmask. Internal rep may be be modified to cache corresponding value. .AP Ttk_Padding padding in @@ -84,18 +84,18 @@ Extra padding to add on the inside of a region. .AP Ttk_Box parcel in A rectangular region, allocated from a cavity. .AP int relief in -One of the standard Tk relief options -(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.). +One of the standard Tk relief options +(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.). See \fBTk_GetReliefFromObj\fR. .AP short right in Extra padding (in pixels) to add to the right side of a region. .AP Ttk_Side side in -One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, +One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, \fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR. .AP unsigned sticky in A bitmask containing one or more of the bits -\fBTTK_STICK_W\fR (west, or left), -\fBTTK_STICK_E\fR (east, or right, +\fBTTK_STICK_W\fR (west, or left), +\fBTTK_STICK_E\fR (east, or right, \fBTTK_STICK_N\fR (north, or top), and \fBTTK_STICK_S\fR (south, or bottom). \fBTTK_FILL_X\fR is defined as a synonym for (TTK_STICK_W|TTK_STICK_E), @@ -104,7 +104,7 @@ and \fBTTK_FILL_BOTH\fR and \fBTTK_STICK_ALL\fR are synonyms for (TTK_FILL_X|TTK_FILL_Y). See also: \fIgrid(n)\fR. .AP Tk_Window tkwin in -Window whose screen geometry determines +Window whose screen geometry determines the conversion between absolute units and pixels. .AP short top in Extra padding at the top of a region. @@ -184,14 +184,14 @@ with all components equal to the specified \fIborder\fR. and returns a combined padding containing the sum of the individual padding components. .PP -\fBTtk_RelievePadding\fR +\fBTtk_RelievePadding\fR adds an extra 2 pixels of padding to \fIpadding\fR according to the specified \fIrelief\fR. -If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, +If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, adds two pixels at the top and left so the inner region is shifted down and to the left. If it is \fBTK_RELIEF_RAISED\fR, adds two pixels -at the bottom and right so +at the bottom and right so the inner region is shifted up and to the right. Otherwise, adds 1 pixel on all sides. This is typically used in element geometry procedures to simulate a @@ -201,17 +201,17 @@ look for pushbuttons. .PP \fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR to a \fBTtk_Padding\fR structure. -The string representation is a list of -up to four length specifications +The string representation is a list of +up to four length specifications .QW "\fIleft top right bottom\fR" . -If fewer than four elements are specified, +If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and +\fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications. .PP \fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fR -except that the lengths are specified as integers +except that the lengths are specified as integers (i.e., resolution-dependant values like \fI3m\fR are not allowed). .PP \fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR diff --git a/doc/ttk_button.n b/doc/ttk_button.n index 2f3c845..62ebe47 100644 --- a/doc/ttk_button.n +++ b/doc/ttk_button.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::button n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -36,12 +36,12 @@ button (meaning, roughly, The default is \fBnormal\fR. .RS .PP -Depending on the theme, the default button may be displayed +Depending on the theme, the default button may be displayed with an extra highlight ring, or with a different border color. .RE .OP \-width width Width -If greater than zero, specifies how much space, in character widths, -to allocate for the text label. +If greater than zero, specifies how much space, in character widths, +to allocate for the text label. If less than zero, specifies a minimum width. If zero or unspecified, the natural width of the text label is used. Note that some themes may specify a non-zero \fB\-width\fR @@ -55,8 +55,8 @@ in the style. .\" .OP \-relief relief Relief .SH "WIDGET COMMAND" .PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, buttons support the following additional widget commands: .TP \fIpathName \fBinvoke\fR diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n index 6236503..ed79f5a 100644 --- a/doc/ttk_checkbutton.n +++ b/doc/ttk_checkbutton.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::checkbutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -14,7 +14,7 @@ ttk::checkbutton \- On/off widget .BE .SH DESCRIPTION A \fBttk::checkbutton\fR widget is used to show or change a setting. -It has two states, selected and deselected. +It has two states, selected and deselected. The state of the checkbutton may be linked to a Tcl variable. .SO ttk_widget \-class \-compound \-cursor @@ -26,18 +26,18 @@ The state of the checkbutton may be linked to a Tcl variable. .OP \-command command Command A Tcl script to execute whenever the widget is invoked. .OP \-offvalue offValue OffValue -The value to store in the associated \fB\-variable\fR +The value to store in the associated \fB\-variable\fR when the widget is deselected. Defaults to \fB0\fR. .OP \-onvalue onValue OnValue -The value to store in the associated \fB\-variable\fR +The value to store in the associated \fB\-variable\fR when the widget is selected. Defaults to \fB1\fR. .OP \-variable variable Variable The name of a global variable whose value is linked to the widget. Defaults to the widget pathname if not specified. .SH "WIDGET COMMAND" .PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, checkbuttons support the following additional widget commands: .TP @@ -48,17 +48,17 @@ If the widget is currently selected, sets the \fB\-variable\fR to the \fB\-offvalue\fR and deselects the widget; otherwise, sets the \fB\-variable\fR to the \fB\-onvalue\fR Returns the result of the \fB\-command\fR. -.\" Missing: select, deselect, toggle +.\" Missing: select, deselect, toggle .\" Are these useful? They don't invoke the -command .\" Missing: flash. This is definitely not useful. .SH "WIDGET STATES" .PP The widget does not respond to user input if the \fBdisabled\fR state is set. -The widget sets the \fBselected\fR state whenever +The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-onvalue\fR, and clears it otherwise. -The widget sets the \fBalternate\fR state whenever the -linked \fB\-variable\fR is unset. +The widget sets the \fBalternate\fR state whenever the +linked \fB\-variable\fR is unset. (The \fBalternate\fR state may be used to indicate a .QW tri-state or diff --git a/doc/ttk_combobox.n b/doc/ttk_combobox.n index dc1c7d1..5e5b3fc 100644 --- a/doc/ttk_combobox.n +++ b/doc/ttk_combobox.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::combobox n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -15,7 +15,7 @@ ttk::combobox \- text field with popdown selection list .SH DESCRIPTION .PP A \fBttk::combobox\fR combines a text field with a pop-down list of values; -the user may select the value of the text field from among the +the user may select the value of the text field from among the values in the list. .SO ttk_widget \-class \-cursor \-takefocus @@ -37,14 +37,14 @@ The \fB\-postcommand\fR script may specify the \fB\-values\fR to display. .OP \-state state State One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fR. In the \fBreadonly\fR state, -the value may not be edited directly, and +the value may not be edited directly, and the user can only select one of the \fB\-values\fR from the dropdown list. -In the \fBnormal\fR state, +In the \fBnormal\fR state, the text field is directly editable. In the \fBdisabled\fR state, no interaction is possible. .OP \-textvariable textVariable TextVariable -Specifies the name of a global variable whose value is linked +Specifies the name of a global variable whose value is linked to the widget value. Whenever the variable changes value the widget value is updated, and vice versa. @@ -66,7 +66,7 @@ The following subcommands are possible for combobox widgets: '\"See \fIttk::widget(n)\fR. .TP \fIpathName \fBcurrent\fR ?\fInewIndex\fR? -If \fInewIndex\fR is supplied, sets the combobox value +If \fInewIndex\fR is supplied, sets the combobox value to the element at position \fInewIndex\fR in the list of \fB\-values\fR. Otherwise, returns the index of the current value in the list of \fB\-values\fR or \fB\-1\fR if the current value does not appear in the list. diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index 34779a6..984e957 100644 --- a/doc/ttk_entry.n +++ b/doc/ttk_entry.n @@ -5,7 +5,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::entry n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -18,9 +18,9 @@ ttk::entry \- Editable text field widget .PP An \fBttk::entry\fR widget displays a one-line text string and allows that string to be edited by the user. -The value of the string may be linked to a Tcl variable +The value of the string may be linked to a Tcl variable with the \fB\-textvariable\fR option. -Entry widgets support horizontal scrolling with the +Entry widgets support horizontal scrolling with the standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. .SO ttk_widget \-class \-cursor \-style @@ -28,7 +28,7 @@ standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection -A boolean value specifying whether or not +A boolean value specifying whether or not a selection in the widget should be linked to the X selection. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any @@ -65,7 +65,7 @@ Specifies one of three states for the entry, \fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. See \fBWIDGET STATES\fR, below. .OP \-textvariable textVariable Variable -Specifies the name of a global variable whose value is linked +Specifies the name of a global variable whose value is linked to the entry widget's contents. Whenever the variable changes value, the widget's contents are updated, and vice versa. @@ -217,7 +217,7 @@ earlier one, then the entry's selection is cleared. '\"See \fIttk::widget(n)\fR. .TP \fIpathName \fBvalidate\fR -Force revalidation, independent of the conditions specified +Force revalidation, independent of the conditions specified by the \fB\-validate\fR option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the \fBinvalid\fR state accordingly. @@ -277,20 +277,20 @@ options are used to enable entry widget validation. .PP There are two main validation modes: \fIprevalidation\fR, in which the \fB\-validatecommand\fR is evaluated prior to each edit -and the return value is used to determine whether to accept +and the return value is used to determine whether to accept or reject the change; -and \fIrevalidation\fR, in which the \fB\-validatecommand\fR is +and \fIrevalidation\fR, in which the \fB\-validatecommand\fR is evaluated to determine whether the current value is valid. .PP The \fB\-validate\fR option determines when validation occurs; it may be set to any of the following values: .RS .IP \fBnone\fR -Default. This means validation will only occur when +Default. This means validation will only occur when specifically requested by the \fBvalidate\fR widget command. .IP \fBkey\fR The entry will be prevalidated prior to each edit -(specifically, whenever the \fBinsert\fR or \fBdelete\fR +(specifically, whenever the \fBinsert\fR or \fBdelete\fR widget commands are called). If prevalidation fails, the edit is rejected. .IP \fBfocus\fR @@ -311,20 +311,20 @@ may modify the entry widget's value via the widget \fBinsert\fR or \fBdelete\fR commands, or by setting the linked \fB\-textvariable\fR. If either does so during prevalidation, -then the edit is rejected +then the edit is rejected regardless of the value returned by the \fB\-validatecommand\fR. .PP -If \fB\-validatecommand\fR is empty (the default), +If \fB\-validatecommand\fR is empty (the default), validation always succeeds. .SS "VALIDATION SCRIPT SUBSTITUTIONS" .PP -It is possible to perform percent substitutions on the +It is possible to perform percent substitutions on the \fB\-validatecommand\fR and \fB\-invalidcommand\fR, just as in a \fBbind\fR script. The following substitutions are recognized: .RS .IP \fB%d\fR -Type of action: 1 for \fBinsert\fR prevalidation, +Type of action: 1 for \fBinsert\fR prevalidation, 0 for \fBdelete\fR prevalidation, or \-1 for revalidation. .IP \fB%i\fR @@ -348,19 +348,19 @@ The name of the entry widget. .PP The standard Tk entry widget automatically disables validation (by setting \fB\-validate\fR to \fBnone\fR) -if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies +if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies the entry's value. The Tk themed entry widget only disables validation if one of the validation scripts raises an error, or if \fB\-validatecommand\fR does not return a valid boolean value. -(Thus, it is not necessary to re-enable validation after +(Thus, it is not necessary to re-enable validation after modifying the entry value in a validation script). .PP In addition, the standard entry widget invokes validation whenever the linked \fB\-textvariable\fR is modified; the Tk themed entry widget does not. .SH "DEFAULT BINDINGS" .PP -The entry widget's default bindings enable the following behavior. +The entry widget's default bindings enable the following behavior. In the descriptions below, .QW word refers to a contiguous group of letters, digits, or @@ -442,22 +442,22 @@ Control-k deletes all the characters to the right of the insertion cursor. .SH "WIDGET STATES" .PP -In the \fBdisabled\fR state, +In the \fBdisabled\fR state, the entry cannot be edited and the text cannot be selected. In the \fBreadonly\fR state, -no insert cursor is displayed and -the entry cannot be edited +no insert cursor is displayed and +the entry cannot be edited (specifically: the \fBinsert\fR and \fBdelete\fR commands have no effect). -The \fBdisabled\fR state is the same as \fBreadonly\fR, +The \fBdisabled\fR state is the same as \fBreadonly\fR, and in addition text cannot be selected. .PP -Note that changes to the linked \fB\-textvariable\fR will +Note that changes to the linked \fB\-textvariable\fR will still be reflected in the entry, even if it is disabled or readonly. .PP Typically, the text is .QW grayed-out in the \fBdisabled\fR state, -and a different background is used in the \fBreadonly\fR state. +and a different background is used in the \fBreadonly\fR state. .PP The entry widget sets the \fBinvalid\fR state if revalidation fails, and clears it whenever validation succeeds. diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n index 3b885e0..b54ce96 100644 --- a/doc/ttk_frame.n +++ b/doc/ttk_frame.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::frame n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -22,9 +22,9 @@ together. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-borderwidth borderWidth BorderWidth -The desired width of the widget border. Defaults to 0. +The desired width of the widget border. Defaults to 0. .OP \-relief relief Relief -One of the standard Tk border styles: +One of the standard Tk border styles: \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR. Defaults to \fBflat\fR. diff --git a/doc/ttk_image.n b/doc/ttk_image.n index 99d38c6..4985c20 100644 --- a/doc/ttk_image.n +++ b/doc/ttk_image.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk_image n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -16,7 +16,7 @@ ttk_image \- Define an element based on an image .PP The \fIimage\fR element factory creates a new element in the current theme whose visual appearance is determined -by Tk images. +by Tk images. \fIimageSpec\fP is a list of one or more elements. The first element is the default image name. The rest of the list is a sequence of \fIstatespec / value\fR @@ -36,7 +36,7 @@ Specifies a minimum height for the element. If less than zero, the base image's height is used as a default. .TP \fB\-padding\fR \fIpadding\fR -Specifies the element's interior padding. Defaults to +Specifies the element's interior padding. Defaults to \fB\-border\fR if not specified. .TP \fB\-sticky\fR \fIspec\fR @@ -53,13 +53,13 @@ Specifies a minimum width for the element. If less than zero, the base image's width is used as a default. .SH "IMAGE STRETCHING" .PP -If the element's allocated parcel is larger than the image, +If the element's allocated parcel is larger than the image, the image will be placed in the parcel based on the \fB\-sticky\fR option. If the image needs to stretch horizontally (i.e., \fB\-sticky ew\fR) or vertically (\fB\-sticky ns\fR), subregions of the image are replicated to fill the parcel based on the \fB\-border\fR option. -The \fB\-border\fR divides the image into 9 regions: +The \fB\-border\fR divides the image into 9 regions: four fixed corners, top and left edges (which may be tiled horizontally), left and right edges (which may be tiled vertically), and the central area (which may be tiled in both directions). diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n index baef34d..bc3cd69 100644 --- a/doc/ttk_intro.n +++ b/doc/ttk_intro.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::intro n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -24,7 +24,7 @@ all aspects of the widget's appearance are controlled by the style of the widget (i.e. the style of the elements of the widget). .SH "THEMES" .PP -A \fItheme\fR is a collection of elements and styles +A \fItheme\fR is a collection of elements and styles that determine the look and feel of the widget set. Themes can be used to: .IP \(bu @@ -47,7 +47,7 @@ For example, a vertical scrollbar widget contains \fBuparrow\fR, .PP Element names use a recursive dotted notation. For example, \fBuparrow\fR identifies a generic arrow element, -and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify +and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify widget-specific elements. When looking for an element, the style engine looks for the specific name first, and if an element of that name is @@ -56,9 +56,9 @@ successive leading components of the element name. .PP Like widgets, elements have \fIoptions\fR which specify what to display and how to display it. -For example, the \fBtext\fR element +For example, the \fBtext\fR element (which displays a text string) has -\fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, +\fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, \fB\-underline\fR, and \fB\-width\fR options. The value of an element option is taken from: .IP \(bu @@ -105,14 +105,14 @@ and the various flavors of buttons which have \fBactive\fR state. The themed Tk widgets generalizes this idea: every widget has a bitmap of independent state flags. Widget state flags include \fBactive\fR, \fBdisabled\fR, -\fBpressed\fR, \fBfocus\fR, etc., +\fBpressed\fR, \fBfocus\fR, etc., (see \fIttk::widget(n)\fR for the full list of state flags). .PP -Instead of a \fB\-state\fR option, every widget now has +Instead of a \fB\-state\fR option, every widget now has a \fBstate\fR widget command which is used to set or query the state. A \fIstate specification\fR is a list of symbolic state names -indicating which bits are set, each optionally prefixed with an +indicating which bits are set, each optionally prefixed with an exclamation point indicating that the bit is cleared instead. .PP For example, the class bindings for the \fBttk::button\fR @@ -132,7 +132,7 @@ This specifies that the widget becomes \fBactive\fR when the pointer enters the widget, and inactive when it leaves. Similarly it becomes \fBpressed\fR when the mouse button is pressed, and \fB!pressed\fR on the ButtonRelease event. -In addition, the button unpresses if +In addition, the button unpresses if pointer is dragged outside the widget while Button-1 is held down, and represses if it's dragged back in. Finally, when the mouse button is released, the widget's @@ -143,7 +143,7 @@ but not by much). '\" Note to self: rewrite that paragraph. It's horrible. .SH "STYLES" .PP -Each widget is associated with a \fIstyle\fR, +Each widget is associated with a \fIstyle\fR, which specifies values for element options. Style names use a recursive dotted notation like layouts and elements; by default, widgets use the class name to look up a style in the current theme. @@ -157,7 +157,7 @@ ttk::\fBstyle configure\fR TButton \e ; .CE .PP -Many elements are displayed differently depending on the widget state. +Many elements are displayed differently depending on the widget state. For example, buttons have a different background when they are active, a different foreground when disabled, and a different relief when pressed. The \fBstyle map\fR command specifies dynamic option settings diff --git a/doc/ttk_label.n b/doc/ttk_label.n index ff93adf..6781b47 100644 --- a/doc/ttk_label.n +++ b/doc/ttk_label.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::label n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -15,7 +15,7 @@ ttk::label \- Display a text string and/or image .SH DESCRIPTION .PP A \fBttk::label\fR widget displays a textual label and/or image. -The label may be linked to a Tcl variable +The label may be linked to a Tcl variable to automatically change the displayed text. .SO ttk_widget \-class \-compound \-cursor @@ -31,7 +31,7 @@ relative to the inner margins. Legal values are \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR. See also \fB\-justify\fR. .OP \-background frameColor FrameColor -The widget's background color. +The widget's background color. If unspecified, the theme default is used. .OP \-font font Font Font to use for label text. @@ -45,17 +45,17 @@ One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. See also \fB\-anchor\fR. .OP \-padding padding Padding Specifies the amount of extra space to allocate for the widget. -The padding is a list of up to four length specifications +The padding is a list of up to four length specifications \fIleft top right bottom\fR. -If fewer than four elements are specified, +If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and +\fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. .OP \-relief relief Relief .\" Rewrite this: Specifies the 3-D effect desired for the widget border. Valid values are -\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, +\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, and \fBsunken\fR. .OP \-text text Text Specifies a text string to be displayed inside the widget diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n index 2dae91f..64edf6a 100644 --- a/doc/ttk_labelframe.n +++ b/doc/ttk_labelframe.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::labelframe n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -22,7 +22,7 @@ another widget. \-style .SE .SH "WIDGET-SPECIFIC OPTIONS" -.\" XXX: Currently included, but may go away: +.\" XXX: Currently included, but may go away: .\" XXX: .OP -borderwidth borderWidth BorderWidth .\" XXX: The desired width of the widget border. Default is theme-dependent. .\" XXX: .OP -relief relief Relief @@ -31,7 +31,7 @@ another widget. .\" XXX: \fBsolid\fR, or \fBsunken\fR. .\" XXX: Default is theme-dependent. .OP \-labelanchor labelAnchor LabelAnchor -Specifies where to place the label. +Specifies where to place the label. Allowed values are (clockwise from the top upper left corner): \fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, \fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. @@ -43,10 +43,10 @@ The default value is theme-dependent. .OP \-text text Text Specifies the text of the label. .OP \-underline underline Underline -If set, specifies the integer index (0-based) of a character to +If set, specifies the integer index (0-based) of a character to underline in the text string. -The underlined character is used for mnemonic activation. -Mnemonic activation for a \fBttk::labelframe\fR +The underlined character is used for mnemonic activation. +Mnemonic activation for a \fBttk::labelframe\fR sets the keyboard focus to the first child of the \fBttk::labelframe\fR widget. .OP \-padding padding Padding Additional padding to include inside the border. diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n index 33189e8..698bd0c 100644 --- a/doc/ttk_menubutton.n +++ b/doc/ttk_menubutton.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::menubutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -24,10 +24,10 @@ and displays a menu when pressed. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-direction direction Direction -Specifies where the menu is to be popped up relative -to the menubutton. +Specifies where the menu is to be popped up relative +to the menubutton. One of: \fBabove\fR, \fBbelow\fR, \fBleft\fR, \fBright\fR, -or \fBflush\fR. The default is \fBbelow\fR. +or \fBflush\fR. The default is \fBbelow\fR. \fBflush\fR pops the menu up directly over the menubutton. .OP \-menu menu Menu Specifies the path name of the menu associated with the menubutton. @@ -38,8 +38,8 @@ menubutton. .\" .OP \-padding padding Pad .SH "WIDGET COMMAND" .PP -Menubutton widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR +Menubutton widgets support the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. .SH "STANDARD STYLES" .PP diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index cecae48..4d1b789 100644 --- a/doc/ttk_notebook.n +++ b/doc/ttk_notebook.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::notebook n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -18,7 +18,7 @@ ttk::notebook \- Multi-paned container widget .fi .BE .SH DESCRIPTION -A \fBttk::notebook\fR widget manages a collection of windows +A \fBttk::notebook\fR widget manages a collection of windows and displays a single one at a time. Each slave window is associated with a \fItab\fR, which the user may select to change the currently-displayed window. @@ -28,35 +28,35 @@ which the user may select to change the currently-displayed window. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-height height Height -If present and greater than zero, +If present and greater than zero, specifies the desired height of the pane area (not including internal padding or tabs). Otherwise, the maximum height of all panes is used. .OP \-padding padding Padding Specifies the amount of extra space to add around the outside of the notebook. -The padding is a list of up to four length specifications +The padding is a list of up to four length specifications \fIleft top right bottom\fR. -If fewer than four elements are specified, +If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, -\fIright\fR defaults to \fIleft\fR, and +\fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. .OP \-width width Width -If present and greater than zero, +If present and greater than zero, specifies the desired width of the pane area (not including internal padding). Otherwise, the maximum width of all panes is used. .SH "TAB OPTIONS" The following options may be specified for individual notebook panes: .OP \-state state State -Either \fBnormal\fR, \fBdisabled\fR or \fBhidden\fR. +Either \fBnormal\fR, \fBdisabled\fR or \fBhidden\fR. If \fBdisabled\fR, then the tab is not selectable. If \fBhidden\fR, then the tab is not shown. .OP \-sticky sticky Sticky Specifies how the slave window is positioned within the pane area. Value is a string containing zero or more of the characters \fBn, s, e,\fR or \fBw\fR. -Each letter refers to a side (north, south, east, or west) +Each letter refers to a side (north, south, east, or west) that the slave window will .QW stick to, as per the \fBgrid\fR geometry manager. @@ -73,7 +73,7 @@ Specifies how to display the image relative to the text, in the case both \fB\-text\fR and \fB\-image\fR are present. See \fIlabel(n)\fR for legal values. .OP \-underline underline Underline -Specifies the integer index (0-based) of a character to underline +Specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation if \fBttk::notebook::enableTraversal\fR is called. @@ -87,7 +87,7 @@ The name of a slave window; .IP \(bu A positional specification of the form .QW @\fIx\fR,\fIy\fR , -which identifies the tab +which identifies the tab .IP \(bu The literal string .QW \fBcurrent\fR , @@ -95,7 +95,7 @@ which identifies the currently-selected tab; or: .IP \(bu The literal string .QW \fBend\fR , -which returns the number of tabs +which returns the number of tabs (only valid for .QW "\fIpathname \fBindex\fR" ). .SH "WIDGET COMMAND" @@ -142,9 +142,9 @@ or the total number of tabs if \fItabid\fR is the string .TP \fIpathname \fBinsert \fIpos subwindow options...\fR Inserts a pane at the specified position. -\fIpos\fR is either the string \fBend\fR, an integer index, +\fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. -If \fIsubwindow\fR is already managed by the notebook, +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 @@ -190,7 +190,7 @@ containing the notebook as follows: of any tab, will select that tab. .PP Multiple notebooks in a single toplevel may be enabled for traversal, -including nested notebooks. +including nested notebooks. However, notebook traversal only works properly if all panes are direct children of the notebook. .SH "VIRTUAL EVENTS" diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n index 6306450..1945f70 100644 --- a/doc/ttk_progressbar.n +++ b/doc/ttk_progressbar.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::progressbar n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -44,15 +44,15 @@ that is, the progress bar completes one when the \fB\-value\fR increases by \fB\-maximum\fR. .OP \-variable variable Variable The name of a global Tcl variable which is linked to the \fB\-value\fR. -If specified, the \fB\-value\fR of the progress bar is -automatically set to the value of the variable whenever +If specified, the \fB\-value\fR of the progress bar is +automatically set to the value of the variable whenever the latter is modified. .OP \-phase phase Phase Read-only option. -The widget periodically increments the value of this option +The widget periodically increments the value of this option whenever the \fB\-value\fR is greater than 0 and, in \fIdeterminate\fR mode, less than \fB\-maximum\fR. -This option may be used by the current theme +This option may be used by the current theme to provide additional animation effects. .SH "WIDGET COMMAND" .PP @@ -72,7 +72,7 @@ Test the widget state; see \fIttk::widget(n)\fR. .TP \fIpathName \fBstart\fR ?\fIinterval\fR? Begin autoincrement mode: -schedules a recurring timer event that calls \fBstep\fR +schedules a recurring timer event that calls \fBstep\fR every \fIinterval\fR milliseconds. If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). .TP @@ -80,7 +80,7 @@ If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). Modify or query the widget state; see \fIttk::widget(n)\fR. .TP \fIpathName \fBstep\fR ?\fIamount\fR? -Increments the \fB\-value\fR by \fIamount\fR. +Increments the \fB\-value\fR by \fIamount\fR. \fIamount\fR defaults to 1.0 if omitted. .TP \fIpathName \fBstop\fR diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n index c16f2cd..5b4dcce 100644 --- a/doc/ttk_radiobutton.n +++ b/doc/ttk_radiobutton.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::radiobutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -29,21 +29,21 @@ 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 \fB\-variable\fR -when the widget is selected. +The value to store in the associated \fB\-variable\fR +when the widget is selected. .OP \-variable variable Variable The name of a global variable whose value is linked to the widget. Default value is \fB::selectedButton\fR. .SH "WIDGET COMMAND" .PP -In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, radiobuttons support the following additional widget commands: .TP \fIpathname\fB invoke\fR Sets the \fB\-variable\fR to the \fB\-value\fR, selects the widget, -and evaluates the associated \fB\-command\fR. +and evaluates the associated \fB\-command\fR. Returns the result of the \fB\-command\fR, or the empty string if no \fB\-command\fR is specified. .\" Missing: select, deselect. Useful? @@ -51,11 +51,11 @@ string if no \fB\-command\fR is specified. .SH "WIDGET STATES" .PP The widget does not respond to user input if the \fBdisabled\fR state is set. -The widget sets the \fBselected\fR state whenever +The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-value\fR, and clears it otherwise. -The widget sets the \fBalternate\fR state whenever the -linked \fB\-variable\fR is unset. +The widget sets the \fBalternate\fR state whenever the +linked \fB\-variable\fR is unset. (The \fBalternate\fR state may be used to indicate a .QW tri-state or diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index 56df214..03d09f2 100644 --- a/doc/ttk_scrollbar.n +++ b/doc/ttk_scrollbar.n @@ -4,12 +4,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::scrollbar n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME -ttk::scrollbar \- Control the viewport of a scrollable widget +ttk::scrollbar \- Control the viewport of a scrollable widget .SH SYNOPSIS \fBttk::scrollbar\fR \fIpathName \fR?\fIoptions...\fR? .BE @@ -30,7 +30,7 @@ these are used to scroll the visible region in discrete units. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command -A Tcl script prefix to evaluate +A Tcl script prefix to evaluate to change the view in the widget associated with the scrollbar. Additional arguments are appended to the value of this option, as described in \fBSCROLLING COMMANDS\fR below, @@ -66,7 +66,7 @@ See \fIttk::widget(n)\fR. Test the widget state; see \fIttk::widget(n)\fR. .TP \fIpathName \fBset \fIfirst last\fR -This command is normally invoked by the scrollbar's associated widget +This command is normally invoked by the scrollbar's associated widget from an \fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. Specifies the visible range to be displayed. \fIfirst\fR and \fIlast\fR are real fractions between 0 and 1. @@ -147,7 +147,7 @@ of individual elements, based on the position and state of the mouse pointer. set f [frame .f] ttk::scrollbar $f.hsb \-orient horizontal \-command [list $f.t xview] ttk::scrollbar $f.vsb \-orient vertical \-command [list $f.t yview] -text $f.t \-xscrollcommand [list $f.hsb set] \-yscrollcommand [list $f.vsb set] +text $f.t \-xscrollcommand [list $f.hsb set] \-yscrollcommand [list $f.vsb set] grid $f.t \-row 0 \-column 0 \-sticky nsew grid $f.vsb \-row 0 \-column 1 \-sticky nsew grid $f.hsb \-row 1 \-column 0 \-sticky nsew diff --git a/doc/ttk_separator.n b/doc/ttk_separator.n index d955fc4..fea2701 100644 --- a/doc/ttk_separator.n +++ b/doc/ttk_separator.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::separator n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -26,8 +26,8 @@ One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the separator. .SH "WIDGET COMMAND" .PP -Separator widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR +Separator widgets support the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. .SH "SEE ALSO" ttk::widget(n) diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n index f10af3d..7ae586f 100644 --- a/doc/ttk_spinbox.n +++ b/doc/ttk_spinbox.n @@ -3,7 +3,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 Tk "Tk Themed Widget" .so man.macros .BS @@ -42,7 +42,7 @@ 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 \fB\-from\fR, \fB\-to\fR and +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 @@ -60,7 +60,7 @@ Specifies a Tcl command to be invoked whenever a spinbutton is invoked. 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 +See the \fBttk::entry\fR manual for information about using the \fB\-validate\fR and \fB\-validatecommand\fR options. .SH "WIDGET COMMAND" .PP diff --git a/doc/ttk_style.n b/doc/ttk_style.n index dc3bade..985e3cd 100644 --- a/doc/ttk_style.n +++ b/doc/ttk_style.n @@ -1,9 +1,9 @@ '\" '\" Copyright (c) 2004 Joe English -'\" +'\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk::style n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -23,9 +23,9 @@ which specifies the set of elements making up the widget and how they are arranged, along with dynamic and default settings for element options. By default, the style name is the same as the widget's class; -this may be overridden by the \fB\-style\fR option. +this may be overridden by the \fB\-style\fR option. .PP -A \fItheme\fR is a collection of elements and styles +A \fItheme\fR is a collection of elements and styles which controls the overall look and feel of an application. .SH DESCRIPTION .PP @@ -43,31 +43,31 @@ is used. \fBttk::style lookup \fIstyle\fR \fI\-option \fR?\fIstate \fR?\fIdefault\fR?? Returns the value specified for \fI\-option\fR in style \fIstyle\fR in state \fIstate\fR, using the standard lookup rules for element options. -\fIstate\fR is a list of state names; if omitted, +\fIstate\fR is a list of state names; if omitted, it defaults to all bits off (the .QW normal state). If the \fIdefault\fR argument is present, it is used as a fallback value in case no specification for \fI\-option\fR is found. -.\" Otherwise -- signal error? return empty string? Leave unspecified for now. +.\" Otherwise -- signal error? return empty string? Leave unspecified for now. .TP \fBttk::style layout \fIstyle\fR ?\fIlayoutSpec\fR? -Define the widget layout for style \fIstyle\fR. +Define the widget layout for style \fIstyle\fR. See \fBLAYOUTS\fR below for the format of \fIlayoutSpec\fR. If \fIlayoutSpec\fR is omitted, return the layout specification for style \fIstyle\fR. -.TP +.TP \fBttk::style element create\fR \fIelementName\fR \fItype\fR ?\fIargs...\fR? Creates a new element in the current theme of type \fItype\fR. -The only cross-platform built-in element type is \fIimage\fR -(see \fBttk_image\fR(n)) but themes may define other element types +The only cross-platform built-in element type is \fIimage\fR +(see \fBttk_image\fR(n)) but themes may define other element types (see \fBTtk_RegisterElementFactory\fR). On suitable versions of Windows an element factory is registered to create Windows theme elements (see \fBttk_vsapi\fR(n)). -.TP +.TP \fBttk::style element names\fR Returns the list of elements defined in the current theme. -.TP +.TP \fBttk::style element options \fIelement\fR Returns the list of \fIelement\fR's options. .TP @@ -79,7 +79,7 @@ If \fB\-settings\fR is present, \fIscript\fR is evaluated in the context of the new theme as per \fBttk::style theme settings\fR. .TP \fBttk::style theme settings \fIthemeName\fR \fIscript\fR -Temporarily sets the current theme to \fIthemeName\fR, +Temporarily sets the current theme to \fIthemeName\fR, evaluate \fIscript\fR, then restore the previous theme. Typically \fIscript\fR simply defines styles and elements, though arbitrary Tcl code may appear. @@ -99,7 +99,7 @@ The layout mechanism uses a simplified version of the \fBpack\fR geometry manager: given an initial cavity, each element is allocated a parcel. Valid options are: -.TP +.TP \fB\-side \fIside\fR Specifies which side of the cavity to place the element; one of \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index dd83c20..660b076 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -3,7 +3,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 Tk "Tk Themed Widget" .so man.macros .BS @@ -15,15 +15,15 @@ ttk::treeview \- hierarchical multicolumn data display widget .SH DESCRIPTION .PP The \fBttk::treeview\fR widget displays a hierarchical collection of items. -Each item has a textual label, an optional image, +Each item has a textual label, an optional image, and an optional list of data values. The data values are displayed in successive columns after the tree label. .PP The order in which data values are displayed may be controlled -by setting the \fB\-displaycolumns\fR widget option. +by setting the \fB\-displaycolumns\fR widget option. The tree widget can also display column headings. -Columns may be accessed by number or by symbolic names +Columns may be accessed by number or by symbolic names listed in the \fB\-columns\fR widget option; see \fBCOLUMN IDENTIFIERS\fR. .PP @@ -40,7 +40,7 @@ and control the appearance of the item. .\" @@@HERE: describe selection, focus item .PP Treeview widgets support horizontal and vertical scrolling with the -standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options +standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options and [\fBxy\fR]\fBview\fR widget commands. .SO ttk_widget \-class \-cursor \-takefocus @@ -48,14 +48,14 @@ and [\fBxy\fR]\fBview\fR widget commands. .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-columns columns Columns -A list of column identifiers, +A list of column identifiers, specifying the number of columns and their names. .\"X: This is a read-only option; it may only be set when the widget is created. .OP \-displaycolumns displayColumns DisplayColumns -A list of column identifiers +A list of column identifiers (either symbolic names or integer indices) -specifying which data columns are displayed -and the order in which they appear, +specifying which data columns are displayed +and the order in which they appear, or the string \fB#all\fP. If set to \fB#all\fP (the default), all columns are shown in the order given. @@ -76,7 +76,7 @@ If set to \fBextended\fR (the default), multiple items may be selected. If \fBbrowse\fR, only a single item will be selected at a time. If \fBnone\fR, the selection will not be changed. .PP -Note that application code and tag bindings can set the selection +Note that application code and tag bindings can set the selection however they wish, regardless of the value of \fB\-selectmode\fR. .RE .OP \-show show Show @@ -84,7 +84,7 @@ A list containing zero or more of the following values, specifying which elements of the tree to display. .RS .IP \fBtree\fR -Display tree labels in column #0. +Display tree labels in column #0. .IP \fBheadings\fR Display the heading row. .PP @@ -114,7 +114,7 @@ returns the list of children belonging to \fIitem\fR. .RS .PP If \fInewchildren\fR is specified, replaces \fIitem\fR's child list -with \fInewchildren\fR. +with \fInewchildren\fR. Items in the old child list not present in the new child list are detached from the tree. None of the items in \fInewchildren\fR may be an ancestor @@ -125,7 +125,7 @@ of \fIitem\fR. Query or modify the options for the specified \fIcolumn\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. -If a single \fI\-option\fR is specified, +If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the options are updated with the specified values. The following options may be set on each column: @@ -134,7 +134,7 @@ The following options may be set on each column: \fB\-id \fIname\fR The column name. This is a read-only option. For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] -returns the data column associated with display column #\fIn\fR. +returns the data column associated with display column #\fIn\fR. .TP \fB\-anchor\fR Specifies how the text in this column should be aligned @@ -145,7 +145,7 @@ with respect to the cell. One of \fB\-minwidth\fR The minimum width of the column in pixels. The treeview widget will not make the column any smaller than -\fB\-minwidth\fR when the widget is resized or the user drags a +\fB\-minwidth\fR when the widget is resized or the user drags a column separator. .TP \fB\-stretch\fR @@ -184,7 +184,7 @@ Returns 1 if the specified \fIitem\fR is present in the tree, If \fIitem\fR is specified, sets the focus item to \fIitem\fR. Otherwise, returns the current focus item, or \fB{}\fR if there is none. .\" Need: way to clear the focus item. {} works for this... -.TP +.TP \fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? Query or modify the heading options for the specified \fIcolumn\fR. Valid options are: @@ -251,13 +251,13 @@ and data columns. Returns the integer index of \fIitem\fR within its parent's list of children. .TP \fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR -Creates a new item. +Creates a new item. \fIparent\fR is the item ID of the parent item, or the empty string \fB{}\fR to create a new top-level item. \fIindex\fR is an integer, or the value \fBend\fR, specifying where in the list of \fIparent\fR's children to insert the new item. -If \fIindex\fR is less than or equal to zero, +If \fIindex\fR is less than or equal to zero, the new node is inserted at the beginning; if \fIindex\fR is greater than or equal to the current number of children, it is inserted at the end. @@ -276,9 +276,9 @@ Test the widget state; see \fIttk::widget(n)\fR. .TP \fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? Query or modify the options for the specified \fIitem\fR. -If no \fI\-option\fR is specified, +If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. -If a single \fI\-option\fR is specified, +If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the item's options are updated with the specified values. See \fBITEM OPTIONS\fR for the list of available options. @@ -292,7 +292,7 @@ If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. .RE -.TP +.TP \fIpathname \fBnext \fIitem\fR Returns the identifier of \fIitem\fR's next sibling, or \fB{}\fR if \fIitem\fR is the last child of its parent. @@ -300,7 +300,7 @@ or \fB{}\fR if \fIitem\fR is the last child of its parent. \fIpathname \fBparent \fIitem\fR Returns the ID of the parent of \fIitem\fR, or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. -.TP +.TP \fIpathname \fBprev \fIitem\fR Returns the identifier of \fIitem\fR's previous sibling, or \fB{}\fR if \fIitem\fR is the first child of its parent. @@ -308,7 +308,7 @@ or \fB{}\fR if \fIitem\fR is the first child of its parent. \fIpathname \fBsee \fIitem\fR Ensure that \fIitem\fR is visible: sets all of \fIitem\fR's ancestors to \fB\-open true\fR, -and scrolls the widget if necessary so that \fIitem\fR is +and scrolls the widget if necessary so that \fIitem\fR is within the visible portion of the tree. .TP \fIpathname \fBselection\fR ?\fIselop itemList\fR? @@ -344,7 +344,7 @@ Modify or query the widget state; see \fIttk::widget(n)\fR. .RS .TP \fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? -Add a Tk binding script for the event sequence \fIsequence\fR +Add a Tk binding script for the event sequence \fIsequence\fR to the tag \fItagName\fR. When an X event is delivered to an item, binding scripts for each of the item's \fB\-tags\fR are evaluated in order as per \fIbindtags(n)\fR. @@ -353,10 +353,10 @@ in order as per \fIbindtags(n)\fR. \fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events are sent to the focus item. \fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events -are sent to the item under the mouse pointer. +are sent to the item under the mouse pointer. No other event types are supported. .PP -The binding \fIscript\fR undergoes \fB%\fR-substitutions before +The binding \fIscript\fR undergoes \fB%\fR-substitutions before evaluation; see \fBbind(n)\fR for details. .RE .TP @@ -364,10 +364,10 @@ evaluation; see \fBbind(n)\fR for details. Query or modify the options for the specified \fItagName\fR. If one or more \fIoption/value\fR pairs are specified, sets the value of those options for the specified tag. -If a single \fIoption\fR is specified, -returns the value of that option +If a single \fIoption\fR is specified, +returns the value of that option (or the empty string if the option has not been specified for \fItagName\fR). -With no additional arguments, +With no additional arguments, returns a dictionary of the option settings for \fItagName\fR. See \fBTAG OPTIONS\fR for the list of available options. .TP @@ -420,7 +420,7 @@ the extra values are ignored. A boolean value indicating whether the item's children should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). .OP \-tags tags Tags -A list of tags associated with this item. +A list of tags associated with this item. .SH "TAG OPTIONS" .PP The following options may be specified on tags: @@ -448,8 +448,8 @@ An integer \fIn\fR, specifying the \fIn\fRth data column. A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, specifying the \fIn\fRth display column. .PP -\fBNOTE:\fR -Item \fB\-values\fR may be displayed in a different order than +\fBNOTE:\fR +Item \fB\-values\fR may be displayed in a different order than the order in which they are stored. .PP \fBNOTE:\fR Column #0 always refers to the tree column, @@ -457,7 +457,7 @@ even if \fB\-show tree\fR is not specified. .PP A \fIdata column number\fR is an index into an item's \fB\-values\fR list; a \fIdisplay column number\fR is the column number in the tree -where the values are displayed. +where the values are displayed. Tree labels are displayed in column #0. If \fB\-displaycolumns\fR is not set, then data column \fIn\fR is displayed in display column \fB#\fIn+1\fR. diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index 34145fb..334836c 100644 --- a/doc/ttk_vsapi.n +++ b/doc/ttk_vsapi.n @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH ttk_vsapi n 8.5 Tk "Tk Themed Widget" .so man.macros .BS @@ -72,7 +72,7 @@ If no \fIstateMap\fR parameter is given there is an implicit default map of {{} 1} .SH "EXAMPLE" .PP -Create a correctly themed close button by changing the layout of +Create a correctly themed close button by changing the layout of a \fBttk::button\fR(n). This uses the WINDOW part WP_SMALLCLOSEBUTTON and as documented the states CBS_DISABLED, CBS_HOT, CBS_NORMAL and CBS_PUSHED are mapped from ttk states. @@ -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 wm n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS @@ -796,7 +796,7 @@ Gridded geometry management is typically invoked by turning on the \fBsetGrid\fR option for a widget; it can also be invoked with the \fBwm grid\fR command or by calling \fBTk_SetGrid\fR. In each of these approaches the particular widget (or sometimes -code in the application as a whole) specifies the relationship between +code in the application as a whole) specifies the relationship between integral grid sizes for the window and pixel sizes. To return to non-gridded geometry management, invoke \fBwm grid\fR with empty argument strings. |