Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Comment: | Doc update (to be reviewed) |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | doc-update |
Files: | files | file ages | folders |
SHA3-256: |
0540ca2c71319f629293b304ffec030e |
User & Date: | jan.nijtmans 2024-05-01 15:30:10 |
2024-05-01
| ||
15:30 | Doc update (to be reviewed) Leaf check-in: 0540ca2c user: jan.nijtmans tags: doc-update | |
09:39 | Backport ttk documentation from Tk 9.0 check-in: 0764601c user: jan.nijtmans tags: core-8-branch | |
Changes to doc/3DBorder.3.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .so man.macros .BS .SH NAME Tk_Alloc3DBorderFromObj, Tk_ClipDrawableToRect, Tk_DrawHighlightBorder, Tk_Get3DBorder, Tk_Get3DBorderColors, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance .SH SYNOPSIS .nf \fB#include <tk.h>\fR | | | < | < | | < | | < | < | < | < | < | < | < | | | | | | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | .so man.macros .BS .SH NAME Tk_Alloc3DBorderFromObj, Tk_ClipDrawableToRect, Tk_DrawHighlightBorder, Tk_Get3DBorder, Tk_Get3DBorderColors, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance .SH SYNOPSIS .nf \fB#include <tk.h>\fR Tk_3DBorder \fBTk_Alloc3DBorderFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp \fBTk_ClipDrawableToRect\fR(\fIdisplay, drawable, x, y, width, height\fR) .sp \fBTk_DrawHighlightBorder\fR(\fItkwin, fgGC, bgGC, highlightWidth, drawable\fR) .sp Tk_3DBorder \fBTk_Get3DBorder\fR(\fIinterp, tkwin, colorName\fR) .sp \fBTk_Get3DBorderColors\fR(\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\fR) .sp Tk_3DBorder \fBTk_Get3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Draw3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Fill3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Draw3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_Fill3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fR) .sp \fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fR) .sp \fBTk_SetBackgroundFromBorder\fR(\fItkwin, border\fR) .sp const char * \fBTk_NameOf3DBorder\fR(\fIborder\fR) .sp XColor * \fBTk_3DBorderColor\fR(\fIborder\fR) .sp GC * \fBTk_3DBorderGC\fR(\fItkwin, border, which\fR) .sp \fBTk_Free3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Free3DBorder\fR(\fIborder\fR) .fi .SH ARGUMENTS .AS "Tk_3DBorder" borderWidth .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window (for all procedures except \fBTk_Get3DBorder\fR, must be the window for which the border was allocated). |
︙ | ︙ | |||
96 97 98 99 100 101 102 | .AP int height in Height of rectangle describing border or bevel, in pixels. .AP int borderWidth in Width of border in pixels. Positive means border is inside rectangle given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means border is outside rectangle. .AP int highlightWidth in | | > | 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | .AP int height in Height of rectangle describing border or bevel, in pixels. .AP int borderWidth in Width of border in pixels. Positive means border is inside rectangle given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means border is outside rectangle. .AP int highlightWidth in Width of ring around the outside of the widget if the widget has received the input focus. .AP int relief in Indicates 3-D position of interior of value relative to exterior; should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR for \fBTk_Fill3DRectangle\fR). .AP XPoint *pointPtr in Pointer to array of points describing the set of vertices in a polygon. |
︙ | ︙ | |||
143 144 145 146 147 148 149 | it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. .AP XColor *bgColorPtr out Pointer to location in which to store the background color of the given border. .AP XColor *darkColorPtr out | | > | > | 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. .AP XColor *bgColorPtr out Pointer to location in which to store the background color of the given border. .AP XColor *darkColorPtr out Pointer to location in which to store the color for darker areas of the given border. .AP XColor *lightColorPtr out Pointer to location in which to store the color for lighter areas of the given border. .AP GC fgGC in Foreground X graphics context. .AP GC fgGC in Background X graphics context. .BE .SH DESCRIPTION .PP |
︙ | ︙ | |||
176 177 178 179 180 181 182 | then NULL is returned and an error message is left as the result of interpreter \fIinterp\fR. If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP | | > > | | > | | | 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 | then NULL is returned and an error message is left as the result of interpreter \fIinterp\fR. If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_ClipDrawableToRect\fR will clip all drawing into the drawable \fId\fR to the given rectangle. If \fIwidth\fR or \fIheight\fR are negative, reset to no clipping. Subsequent drawing into \fId\fR is offset and clipped as specified. The function is only used when \fBTK_NO_DOUBLE_BUFFERING\fR is specified at compile time. .PP \fBTk_DrawHighlightBorder\fR draws a rectangular ring around the outside of a widget to indicate that it has received the input focus. On the Macintosh, this puts a 1 pixel border in the bgGC color between the widget and the focus ring, except in the case where highlightWidth is 1, in which case the border is left out. For proper Mac L&F, use highlightWidth of 3. .PP \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except that the color is specified with a string instead of a value. This |
︙ | ︙ | |||
222 223 224 225 226 227 228 | \fIwidth\fR and \fIheight\fR are the dimensions of the window), and \fIborderWidth\fR specifies the number of pixels actually occupied by the border. The \fIrelief\fR argument indicates which of several three-dimensional effects is desired: \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. | | | | 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 | \fIwidth\fR and \fIheight\fR are the dimensions of the window), and \fIborderWidth\fR specifies the number of pixels actually occupied by the border. The \fIrelief\fR argument indicates which of several three-dimensional effects is desired: \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be a groove or ridge around the exterior of the rectangle. .PP \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except that it first fills the rectangular area with the background color (one corresponding to the color used to create \fIborder\fR). Then it calls \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of the rectangular area. The argument \fIrelief\fR indicates the desired |
︙ | ︙ | |||
321 322 323 324 325 326 327 | with the window and color name used to create the border; for \fBTk_Free3DBorder\fR the border to release is specified with the Tk_3DBorder token for the border. There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. .SH KEYWORDS | | > | 318 319 320 321 322 323 324 325 326 | with the window and color name used to create the border; for \fBTk_Free3DBorder\fR the border to release is specified with the Tk_3DBorder token for the border. There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. .SH KEYWORDS 3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect |
Changes to doc/AddOption.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | \fB#include <tk.h>\fR .sp void \fBTk_AddOption\fR(\fItkwin, name, value, priority\fR) .sp Tcl_Obj * \fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR) .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Multi-element name of option. .AP "const char" *value in Value of option. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | \fB#include <tk.h>\fR .sp void \fBTk_AddOption\fR(\fItkwin, name, value, priority\fR) .sp Tcl_Obj * \fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR) .fi .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Multi-element name of option. .AP "const char" *value in Value of option. |
︙ | ︙ |
Changes to doc/BindTable.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_BindingTable | | | | | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | .SH NAME Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_BindingTable \fBTk_CreateBindingTable\fR(\fIinterp\fR) .sp \fBTk_DeleteBindingTable\fR(\fIbindingTable\fR) .sp unsigned long \fBTk_CreateBinding\fR(\fIinterp, bindingTable, object, eventString, script, append\fR) .sp int \fBTk_DeleteBinding\fR(\fIinterp, bindingTable, object, eventString\fR) .sp const char * \fBTk_GetBinding\fR(\fIinterp, bindingTable, object, eventString\fR) .sp \fBTk_GetAllBindings\fR(\fIinterp, bindingTable, object\fR) .sp \fBTk_DeleteAllBindings\fR(\fIbindingTable, object\fR) .sp \fBTk_BindEvent\fR(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fR) .fi .SH ARGUMENTS .AS Tk_BindingTable bindingTable .AP Tcl_Interp *interp in Interpreter to use when invoking bindings in binding table. Also used for returning results and errors from binding procedures. .AP Tk_BindingTable bindingTable in Token for binding table; must have been returned by some previous |
︙ | ︙ |
Changes to doc/CanvPsY.3.
︙ | ︙ | |||
25 26 27 28 29 30 31 32 33 34 35 36 37 38 | int \fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR) .sp \fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) .sp int \fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) .SH ARGUMENTS .AS int "numPoints" .AP Tk_Canvas canvas in A token that identifies a canvas widget for which Postscript is being generated. .AP double canvasY in Y-coordinate in the space of the canvas. | > | 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | int \fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR) .sp \fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) .sp int \fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) .fi .SH ARGUMENTS .AS int "numPoints" .AP Tk_Canvas canvas in A token that identifies a canvas widget for which Postscript is being generated. .AP double canvasY in Y-coordinate in the space of the canvas. |
︙ | ︙ |
Changes to doc/CanvTkwin.3.
︙ | ︙ | |||
26 27 28 29 30 31 32 33 34 35 36 37 38 39 | \fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) .sp \fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) .sp Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; .sp Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; .SH ARGUMENTS .AS Tk_ItemType *drawableXPtr .AP Tk_Canvas canvas in A token that identifies a canvas widget. .AP Tcl_Interp *interp in/out Interpreter to use for error reporting. .AP "const char" *string in | > | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | \fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) .sp \fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) .sp Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; .sp Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; .fi .SH ARGUMENTS .AS Tk_ItemType *drawableXPtr .AP Tk_Canvas canvas in A token that identifies a canvas widget. .AP Tcl_Interp *interp in/out Interpreter to use for error reporting. .AP "const char" *string in |
︙ | ︙ | |||
145 146 147 148 149 150 151 | .CS static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, Tk_CanvasTagsPrintProc, NULL }; static const Tk_ConfigSpec configSpecs[] = { ... | | | 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | .CS static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, Tk_CanvasTagsPrintProc, NULL }; static const Tk_ConfigSpec configSpecs[] = { ... {TK_CONFIG_CUSTOM, "-tags", NULL, NULL, NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, ... }; .CE .SH KEYWORDS canvas, focus, item type, redisplay, selection, type manager |
Changes to doc/CanvTxtInfo.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_CanvasTextInfo \- additional information for managing text items in canvases .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_CanvasTextInfo * \fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) .SH ARGUMENTS .AS Tk_Canvas canvas .AP Tk_Canvas canvas in A token that identifies a particular canvas widget. .BE .SH DESCRIPTION .PP | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_CanvasTextInfo \- additional information for managing text items in canvases .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_CanvasTextInfo * \fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) .fi .SH ARGUMENTS .AS Tk_Canvas canvas .AP Tk_Canvas canvas in A token that identifies a particular canvas widget. .BE .SH DESCRIPTION .PP |
︙ | ︙ |
Changes to doc/Clipboard.3.
︙ | ︙ | |||
15 16 17 18 19 20 21 22 23 24 25 26 27 28 | \fB#include <tk.h>\fR .sp int \fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) .sp int \fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) .SH ARGUMENTS .AS Tk_ClipboardClear tkwin .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window that determines which display's clipboard to manipulate. .AP Atom target in | > | 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | \fB#include <tk.h>\fR .sp int \fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) .sp int \fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) .fi .SH ARGUMENTS .AS Tk_ClipboardClear tkwin .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window that determines which display's clipboard to manipulate. .AP Atom target in |
︙ | ︙ |
Changes to doc/ClrSelect.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_ClearSelection \- Deselect a selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ClearSelection\fR(\fItkwin, selection\fR) .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in The selection will be cleared from the display containing this window. .AP Atom selection in The name of selection to be cleared. | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_ClearSelection \- Deselect a selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ClearSelection\fR(\fItkwin, selection\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in The selection will be cleared from the display containing this window. .AP Atom selection in The name of selection to be cleared. |
︙ | ︙ |
Changes to doc/ConfigWidg.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | .SH NAME Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_ConfigureWidget\fR(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fR) .sp int \fBTk_ConfigureInfo\fR(\fIinterp, tkwin, specs, widgRec, argvName, flags\fR) .sp int \fBTk_ConfigureValue\fR(\fIinterp, tkwin, specs, widgRec, argvName, flags\fR) .sp \fBTk_FreeOptions\fR(\fIspecs, widgRec, display, flags\fR) .fi .SH ARGUMENTS .AS void *widgRec in/out .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window used to represent widget (needed to set up X resources). .AP "const Tk_ConfigSpec" *specs in |
︙ | ︙ | |||
58 59 60 61 62 63 64 | options. .AP Display *display in Display containing widget whose record is being freed; needed in order to free up resources. .BE .SH DESCRIPTION .PP | | | | 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | options. .AP Display *display in Display containing widget whose record is being freed; needed in order to free up resources. .BE .SH DESCRIPTION .PP Note that \fBTk_ConfigureWidget\fR should be replaced with the new \fBTcl_Obj\fR based API, \fBTk_SetOptions\fR. The old interface is retained for backward compatibility. .PP \fBTk_ConfigureWidget\fR is called to configure various aspects of a widget, such as colors, fonts, border width, etc. It is intended as a convenience procedure to reduce the amount of code that must be written in individual widget managers to handle configuration information. |
︙ | ︙ | |||
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | in the descriptions below. .PP The \fItype\fR field of each entry in \fIspecs\fR determines what to do with the string value of that configuration option. The legal values for \fItype\fR, and the corresponding actions, are: .TP \fBTK_CONFIG_ACTIVE_CURSOR\fR The value must be an ASCII string identifying a cursor in a form suitable for passing to \fBTk_GetCursor\fR. The value is converted to a \fBTk_Cursor\fR by calling \fBTk_GetCursor\fR and the result is stored in the target. In addition, the resulting cursor is made the active cursor for \fItkwin\fR by calling \fBXDefineCursor\fR. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target and \fItkwin\fR's active cursor will be set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. .TP \fBTK_CONFIG_ANCHOR\fR The value must be an ASCII string identifying an anchor point in one of the ways accepted by \fBTk_GetAnchor\fR. The string is converted to a \fBTk_Anchor\fR by calling \fBTk_GetAnchor\fR and the result is stored in the target. .TP \fBTK_CONFIG_BITMAP\fR The value must be an ASCII string identifying a bitmap in a form suitable for passing to \fBTk_GetBitmap\fR. The value is converted to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target is set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. .TP \fBTK_CONFIG_BOOLEAN\fR The value must be an ASCII string specifying a boolean value. Any of the values .QW true , .QW yes , .QW on , or .QW 1 , or an abbreviation of one of these values, means true; any of the values .QW false , .QW no , .QW off , or .QW 0 , or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0. .TP \fBTK_CONFIG_BORDER\fR The value must be an ASCII string identifying a border color in a form suitable for passing to \fBTk_Get3DBorder\fR. The value is converted to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. .TP \fBTK_CONFIG_CAP_STYLE\fR The value must be an ASCII string identifying a cap style in one of the ways accepted by \fBTk_GetCapStyle\fR. The string is converted to an integer value corresponding to the cap style by calling \fBTk_GetCapStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_COLOR\fR The value must be an ASCII string identifying a color in a form suitable for passing to \fBTk_GetColor\fR. The value is converted to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to \fBNone\fR. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR. .TP \fBTK_CONFIG_CURSOR\fR This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except that the new cursor is not made the active one for \fItkwin\fR. .TP \fBTK_CONFIG_CUSTOM\fR This option allows applications to define new option types. The \fIcustomPtr\fR field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. .TP \fBTK_CONFIG_DOUBLE\fR The value must be an ASCII floating-point number in the format accepted by \fBstrtol\fR. The string is converted to a \fBdouble\fR value, and the value is stored in the target. .TP \fBTK_CONFIG_END\fR Marks the end of the table. The last entry in \fIspecs\fR must have this type; all of its other fields are ignored and it will never match any arguments. .TP \fBTK_CONFIG_FONT\fR The value must be an ASCII string identifying a font in a form suitable for passing to \fBTk_GetFont\fR. The value is converted to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR. .TP \fBTK_CONFIG_INT\fR The value must be an ASCII integer string in the format accepted by \fBstrtol\fR (e.g. .QW 0 and .QW 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target. .TP \fBTK_CONFIG_JOIN_STYLE\fR The value must be an ASCII string identifying a join style in one of the ways accepted by \fBTk_GetJoinStyle\fR. The string is converted to an integer value corresponding to the join style by calling \fBTk_GetJoinStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_JUSTIFY\fR The value must be an ASCII string identifying a justification method in one of the ways accepted by \fBTk_GetJustify\fR. The string is converted to a \fBTk_Justify\fR by calling \fBTk_GetJustify\fR and the result is stored in the target. .TP \fBTK_CONFIG_MM\fR The value must specify a screen distance in one of the forms acceptable to \fBTk_GetScreenMM\fR. The string is converted to double-precision floating-point distance in millimeters and the value is stored in the target. .TP \fBTK_CONFIG_PIXELS\fR The value must specify screen units in one of the forms acceptable to \fBTk_GetPixels\fR. The string is converted to an integer distance in pixels and the value is stored in the target. .TP \fBTK_CONFIG_RELIEF\fR The value must be an ASCII string identifying a relief in a form suitable for passing to \fBTk_GetRelief\fR. The value is converted to an integer relief value by calling \fBTk_GetRelief\fR and the result is stored in the target. .TP \fBTK_CONFIG_STRING\fR | > > > > > > > > > > > > > > > > > > < > | > > > | 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | in the descriptions below. .PP The \fItype\fR field of each entry in \fIspecs\fR determines what to do with the string value of that configuration option. The legal values for \fItype\fR, and the corresponding actions, are: .TP \fBTK_CONFIG_ACTIVE_CURSOR\fR . The value must be an ASCII string identifying a cursor in a form suitable for passing to \fBTk_GetCursor\fR. The value is converted to a \fBTk_Cursor\fR by calling \fBTk_GetCursor\fR and the result is stored in the target. In addition, the resulting cursor is made the active cursor for \fItkwin\fR by calling \fBXDefineCursor\fR. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target and \fItkwin\fR's active cursor will be set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. .TP \fBTK_CONFIG_ANCHOR\fR . The value must be an ASCII string identifying an anchor point in one of the ways accepted by \fBTk_GetAnchor\fR. The string is converted to a \fBTk_Anchor\fR by calling \fBTk_GetAnchor\fR and the result is stored in the target. .TP \fBTK_CONFIG_BITMAP\fR . The value must be an ASCII string identifying a bitmap in a form suitable for passing to \fBTk_GetBitmap\fR. The value is converted to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target is set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. .TP \fBTK_CONFIG_BOOLEAN\fR . The value must be an ASCII string specifying a boolean value. Any of the values .QW true , .QW yes , .QW on , or .QW 1 , or an abbreviation of one of these values, means true; any of the values .QW false , .QW no , .QW off , or .QW 0 , or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0. .TP \fBTK_CONFIG_BORDER\fR . The value must be an ASCII string identifying a border color in a form suitable for passing to \fBTk_Get3DBorder\fR. The value is converted to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. .TP \fBTK_CONFIG_CAP_STYLE\fR . The value must be an ASCII string identifying a cap style in one of the ways accepted by \fBTk_GetCapStyle\fR. The string is converted to an integer value corresponding to the cap style by calling \fBTk_GetCapStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_COLOR\fR . The value must be an ASCII string identifying a color in a form suitable for passing to \fBTk_GetColor\fR. The value is converted to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to \fBNone\fR. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR. .TP \fBTK_CONFIG_CURSOR\fR . This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except that the new cursor is not made the active one for \fItkwin\fR. .TP \fBTK_CONFIG_CUSTOM\fR . This option allows applications to define new option types. The \fIcustomPtr\fR field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. .TP \fBTK_CONFIG_DOUBLE\fR . The value must be an ASCII floating-point number in the format accepted by \fBstrtol\fR. The string is converted to a \fBdouble\fR value, and the value is stored in the target. .TP \fBTK_CONFIG_END\fR . Marks the end of the table. The last entry in \fIspecs\fR must have this type; all of its other fields are ignored and it will never match any arguments. .TP \fBTK_CONFIG_FONT\fR . The value must be an ASCII string identifying a font in a form suitable for passing to \fBTk_GetFont\fR. The value is converted to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR. .TP \fBTK_CONFIG_INT\fR . The value must be an ASCII integer string in the format accepted by \fBstrtol\fR (e.g. .QW 0 and .QW 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target. .TP \fBTK_CONFIG_JOIN_STYLE\fR . The value must be an ASCII string identifying a join style in one of the ways accepted by \fBTk_GetJoinStyle\fR. The string is converted to an integer value corresponding to the join style by calling \fBTk_GetJoinStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_JUSTIFY\fR . The value must be an ASCII string identifying a justification method in one of the ways accepted by \fBTk_GetJustify\fR. The string is converted to a \fBTk_Justify\fR by calling \fBTk_GetJustify\fR and the result is stored in the target. .TP \fBTK_CONFIG_MM\fR . The value must specify a screen distance in one of the forms acceptable to \fBTk_GetScreenMM\fR. The string is converted to double-precision floating-point distance in millimeters and the value is stored in the target. .TP \fBTK_CONFIG_PIXELS\fR . The value must specify screen units in one of the forms acceptable to \fBTk_GetPixels\fR. The string is converted to an integer distance in pixels and the value is stored in the target. .TP \fBTK_CONFIG_RELIEF\fR . The value must be an ASCII string identifying a relief in a form suitable for passing to \fBTk_GetRelief\fR. The value is converted to an integer relief value by calling \fBTk_GetRelief\fR and the result is stored in the target. .TP \fBTK_CONFIG_STRING\fR . A copy of the value is made by allocating memory space with \fBTcl_Alloc\fR and copying the value into the dynamically-allocated space. A pointer to the new string is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTcl_Free\fR. .TP \fBTK_CONFIG_SYNONYM\fR . This \fItype\fR value identifies special entries in \fIspecs\fR that are synonyms for other entries. If an \fIargv\fR value matches the \fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR for another entry whose \fIargvName\fR is the same as the \fIdbName\fR field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just as if its \fIargvName\fR had matched the \fIargv\fR value. The synonym mechanism allows multiple \fIargv\fR values to be used for a single configuration option, such as .QW \-background and .QW \-bg . .TP \fBTK_CONFIG_UID\fR . The value is translated to a \fBTk_Uid\fR (by passing it to \fBTk_GetUid\fR). The resulting value is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value is an empty string then the target will be set to NULL. .TP \fBTK_CONFIG_WINDOW\fR . The value must be a window path name. It is translated to a \fBTk_Window\fR token and the token is stored in the target. .SH "GROUPED ENTRIES" .PP In some cases it is useful to generate multiple resources from a single configuration value. For example, a color name might be used both to generate the background color for a widget (using |
︙ | ︙ | |||
377 378 379 380 381 382 383 | The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR to provide additional control over the processing of configuration options. These values are used in three different ways as described below. .PP First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has | | > > > > > < < < < < < < < | 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 | The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR to provide additional control over the processing of configuration options. These values are used in three different ways as described below. .PP First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0), then the option database and \fIdefValue\fR fields are not used. In this case, if an entry in \fIspecs\fR does not match a field in \fIargv\fR then nothing happens: the corresponding target is not modified. This feature is useful when the goal is to modify certain configuration options while leaving others in their current state, such as when a \fBconfigure\fR widget command is being processed. .PP Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used to control the processing of that entry. Each \fIspecFlags\fR field may consists of an OR-ed combination of the following values: .TP \fBTK_CONFIG_COLOR_ONLY\fR . If this bit is set then the entry will only be considered if the display for \fItkwin\fR has more than one bit plane. If the display is monochromatic then this \fIspecs\fR entry will be ignored. .TP \fBTK_CONFIG_MONO_ONLY\fR . If this bit is set then the entry will only be considered if the display for \fItkwin\fR has exactly one bit plane. If the display is not monochromatic then this \fIspecs\fR entry will be ignored. .TP \fBTK_CONFIG_NULL_OK\fR . This bit is only relevant for some types of entries (see the descriptions of the various entry types above). If this bit is set, it indicates that an empty string value for the field is acceptable and if it occurs then the target should be set to NULL or \fBNone\fR, depending on the type of the target. This flag is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to \fBNone\fR so that a window simply inherits its parent's cursor. If this bit is not set then empty strings are processed as strings, which generally results in an error. .TP \fBTK_CONFIG_DONT_SET_DEFAULT\fR . If this bit is one, it means that the \fIdefValue\fR field of the entry should only be used for returning the default value in \fBTk_ConfigureInfo\fR. In calls to \fBTk_ConfigureWidget\fR no default will be supplied for entries with this flag set; it is assumed that the caller has already supplied a default value in the target location. This flag provides a performance optimization where it is expensive to process the default string: the client can compute the default once, save the value, and provide it before calling \fBTk_ConfigureWidget\fR. .PP The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically used to specify different default values for monochrome and color displays. This is done by creating two entries in \fIspecs\fR that are identical except for their \fIdefValue\fR and \fIspecFlags\fR fields. One entry should have the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the |
︙ | ︙ | |||
529 530 531 532 533 534 535 | corresponding field of the widget record to null. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures: .CS | | | 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 | corresponding field of the widget record to null. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures: .CS typedef struct { Tk_OptionParseProc *\fIparseProc\fR; Tk_OptionPrintProc *\fIprintProc\fR; void *\fIclientData\fR; } \fBTk_CustomOption\fR; typedef int \fBTk_OptionParseProc\fR( void *\fIclientData\fR, |
︙ | ︙ |
Changes to doc/ConfigWind.3.
︙ | ︙ | |||
35 36 37 38 39 40 41 42 43 44 45 46 47 48 | \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) .sp \fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) .sp \fBTk_DefineCursor\fR(\fItkwin, cursor\fR) .sp \fBTk_UndefineCursor\fR(\fItkwin\fR) .SH ARGUMENTS .AS XSetWindowAttributes borderWidth .AP Tk_Window tkwin in Token for window. .AP "unsigned int" valueMask in OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. | > | 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) .sp \fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) .sp \fBTk_DefineCursor\fR(\fItkwin, cursor\fR) .sp \fBTk_UndefineCursor\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS XSetWindowAttributes borderWidth .AP Tk_Window tkwin in Token for window. .AP "unsigned int" valueMask in OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. |
︙ | ︙ |
Changes to doc/CoordToWin.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_CoordsToWindow \- Find window containing a point .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) .SH ARGUMENTS .AS Tk_Window tkwin .AP int rootX in X-coordinate (in root window coordinates). .AP int rootY in Y-coordinate (in root window coordinates). .AP Tk_Window tkwin in | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_CoordsToWindow \- Find window containing a point .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP int rootX in X-coordinate (in root window coordinates). .AP int rootY in Y-coordinate (in root window coordinates). .AP Tk_Window tkwin in |
︙ | ︙ |
Changes to doc/CrtCmHdlr.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateClientMessageHandler\fR(\fIproc\fR) .sp \fBTk_DeleteClientMessageHandler\fR(\fIproc\fR) .SH ARGUMENTS .AP Tk_ClientMessageProc *proc in Procedure to invoke whenever a ClientMessage X event occurs on any display. .BE .SH DESCRIPTION .PP \fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateClientMessageHandler\fR(\fIproc\fR) .sp \fBTk_DeleteClientMessageHandler\fR(\fIproc\fR) .fi .SH ARGUMENTS .AP Tk_ClientMessageProc *proc in Procedure to invoke whenever a ClientMessage X event occurs on any display. .BE .SH DESCRIPTION .PP \fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked |
︙ | ︙ |
Changes to doc/CrtConsoleChan.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 17 18 19 20 21 22 23 | .SH NAME Tk_InitConsoleChannels \- Install the console channels as standard channels .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_InitConsoleChannels\fR(\fIinterp\fR) .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Interpreter in which the console channels are created. .BE .SH DESCRIPTION .PP | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_InitConsoleChannels \- Install the console channels as standard channels .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_InitConsoleChannels\fR(\fIinterp\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Interpreter in which the console channels are created. .BE .SH DESCRIPTION .PP |
︙ | ︙ |
Changes to doc/CrtErrHdlr.3.
︙ | ︙ | |||
14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .nf \fB#include <tk.h>\fR .sp Tk_ErrorHandler \fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) .sp \fBTk_DeleteErrorHandler\fR(\fIhandler\fR) .SH ARGUMENTS .AS "Tk_ErrorHandler" clientData .AP Display *display in Display whose errors are to be handled. .AP int error in Match only error events with this value in the \fIerror_code\fR field. If \-1, then match any \fIerror_code\fR value. | > | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | .nf \fB#include <tk.h>\fR .sp Tk_ErrorHandler \fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) .sp \fBTk_DeleteErrorHandler\fR(\fIhandler\fR) .fi .SH ARGUMENTS .AS "Tk_ErrorHandler" clientData .AP Display *display in Display whose errors are to be handled. .AP int error in Match only error events with this value in the \fIerror_code\fR field. If \-1, then match any \fIerror_code\fR value. |
︙ | ︙ |
Changes to doc/CrtGenHdlr.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) .sp \fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) .SH ARGUMENTS .AS "Tk_GenericProc" clientData .AP Tk_GenericProc *proc in Procedure to invoke whenever any X event occurs on any display. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) .sp \fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) .fi .SH ARGUMENTS .AS "Tk_GenericProc" clientData .AP Tk_GenericProc *proc in Procedure to invoke whenever any X event occurs on any display. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE |
︙ | ︙ |
Changes to doc/CrtImgType.3.
1 2 3 4 5 6 7 8 9 10 11 | '\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME | | | < < < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | '\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateImageType, Tk_GetImageModelData \- define new kind of image .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateImageType\fR(\fItypePtr\fR) .sp void * \fBTk_GetImageModelData\fR(\fIinterp, name, typePtrPtr\fR) .fi .SH ARGUMENTS .AS "const Tk_ImageType" *typePtrPtr .AP "const Tk_ImageType" *typePtr in Structure that defines the new type of image. For Tk 8.4 and earlier this must be static: a pointer to this structure is retained by the image code. In Tk 8.5, this limitation was relaxed. .AP Tcl_Interp *interp in Interpreter in which image was created. .AP "const char" *name in Name of existing image. .AP Tk_ImageType **typePtrPtr out Points to word in which to store a pointer to type information for the given image, if it exists. .AP char ***argvPtr in/out Pointer to argument list .BE .SH DESCRIPTION .PP \fBTk_CreateImageType\fR is invoked to define a new kind of image. An image type corresponds to a particular value of the \fItype\fR |
︙ | ︙ | |||
54 55 56 57 58 59 60 | \fIimage manager\fR. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: .CS | | | 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | \fIimage manager\fR. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: .CS typedef struct { const char *\fIname\fR; Tk_ImageCreateProc *\fIcreateProc\fR; Tk_ImageGetProc *\fIgetProc\fR; Tk_ImageDisplayProc *\fIdisplayProc\fR; Tk_ImageFreeProc *\fIfreeProc\fR; Tk_ImageDeleteProc *\fIdeleteProc\fR; } \fBTk_ImageType\fR; |
︙ | ︙ | |||
237 238 239 240 241 242 243 | in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is filled in with type information for the image (the \fItypePtr\fR value passed to \fBTk_CreateImageType\fR when the image type was registered) and the return value is the clientData value returned by the \fIcreateProc\fR when the image was created (this is typically a pointer to the image model data structure). If no such image exists then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | 234 235 236 237 238 239 240 241 242 243 244 | in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is filled in with type information for the image (the \fItypePtr\fR value passed to \fBTk_CreateImageType\fR when the image type was registered) and the return value is the clientData value returned by the \fIcreateProc\fR when the image was created (this is typically a pointer to the image model data structure). If no such image exists then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. .SH "SEE ALSO" Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage .SH KEYWORDS image manager, image type, instance, model |
Changes to doc/CrtItemType.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | .nf \fB#include <tk.h>\fR .sp \fBTk_CreateItemType\fR(\fItypePtr\fR) .sp Tk_ItemType * \fBTk_GetItemTypes\fR() .SH ARGUMENTS .AS Tk_ItemType *typePtr .AP Tk_ItemType *typePtr in Structure that defines the new type of canvas item. .BE .SH INTRODUCTION .PP \fBTk_CreateItemType\fR is invoked to define a new kind of canvas item described by the \fItypePtr\fR argument. An item type corresponds to a particular value of the \fItype\fR argument to the \fBcreate\fR widget command for canvases, and | > > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | .nf \fB#include <tk.h>\fR .sp \fBTk_CreateItemType\fR(\fItypePtr\fR) .sp Tk_ItemType * \fBTk_GetItemTypes\fR() .fi .SH ARGUMENTS .AS Tk_ItemType *typePtr .AP Tk_ItemType *typePtr in Structure that defines the new type of canvas item. Note that this is not \fIconst\fR; Tk may write to these structures. .BE .SH INTRODUCTION .PP \fBTk_CreateItemType\fR is invoked to define a new kind of canvas item described by the \fItypePtr\fR argument. An item type corresponds to a particular value of the \fItype\fR argument to the \fBcreate\fR widget command for canvases, and |
︙ | ︙ | |||
67 68 69 70 71 72 73 | size_t \fIitemSize\fR; Tk_ItemCreateProc *\fIcreateProc\fR; const Tk_ConfigSpec *\fIconfigSpecs\fR; Tk_ItemConfigureProc *\fIconfigProc\fR; Tk_ItemCoordProc *\fIcoordProc\fR; Tk_ItemDeleteProc *\fIdeleteProc\fR; Tk_ItemDisplayProc *\fIdisplayProc\fR; | | | | 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | size_t \fIitemSize\fR; Tk_ItemCreateProc *\fIcreateProc\fR; const Tk_ConfigSpec *\fIconfigSpecs\fR; Tk_ItemConfigureProc *\fIconfigProc\fR; Tk_ItemCoordProc *\fIcoordProc\fR; Tk_ItemDeleteProc *\fIdeleteProc\fR; Tk_ItemDisplayProc *\fIdisplayProc\fR; int \fIflags\fR; Tk_ItemPointProc *\fIpointProc\fR; Tk_ItemAreaProc *\fIareaProc\fR; Tk_ItemPostscriptProc *\fIpostscriptProc\fR; Tk_ItemScaleProc *\fIscaleProc\fR; Tk_ItemTranslateProc *\fItranslateProc\fR; Tk_ItemIndexProc *\fIindexProc\fR; Tk_ItemCursorProc *\fIicursorProc\fR; Tk_ItemSelectionProc *\fIselectionProc\fR; Tk_ItemInsertProc *\fIinsertProc\fR; Tk_ItemDCharsProc *\fIdCharsProc\fR; struct Tk_ItemType *\fInextPtr\fR; .VS "8.7, TIP164" Tk_ItemRotateProc *\fIrotateProc\fR; .VE "8.7, TIP164" } \fBTk_ItemType\fR; .CE .PP The fields of a Tk_ItemType structure are described in more detail |
︙ | ︙ | |||
109 110 111 112 113 114 115 | defined by Tk via the type Tk_Item; the rest of the item record is defined by the type manager. A type manager must define its item records with a Tk_Item as the first field. For example, the item record for bitmap items is defined as follows: .PP .CS | | | 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | defined by Tk via the type Tk_Item; the rest of the item record is defined by the type manager. A type manager must define its item records with a Tk_Item as the first field. For example, the item record for bitmap items is defined as follows: .PP .CS typedef struct { Tk_Item \fIheader\fR; double \fIx\fR, \fIy\fR; Tk_Anchor \fIanchor\fR; Pixmap \fIbitmap\fR; XColor *\fIfgColor\fR; XColor *\fIbgColor\fR; GC \fIgc\fR; |
︙ | ︙ | |||
165 166 167 168 169 170 171 | Once \fBTk_CreateImageType\fR returns, this name may be used in \fBcreate\fR widget commands to create items of the new type. If there already existed an item type by this name then the new item type replaces the old one. .SS "FLAGS (IN ALWAYSREDRAW)" .PP | | < < < < < < < < | 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | Once \fBTk_CreateImageType\fR returns, this name may be used in \fBcreate\fR widget commands to create items of the new type. If there already existed an item type by this name then the new item type replaces the old one. .SS "FLAGS (IN ALWAYSREDRAW)" .PP The \fItypePtr\->flags\fR field contains a collection of flag bits that modify how the canvas core interacts with the item. The following bits are defined: .TP \fBTK_ALWAYS_REDRAW\fR . Indicates that the item should always be redrawn when any part of the canvas is redrawn, rather than only when the bounding box of the item overlaps the area being redrawn. This is used by window items, for example, which need to unmap subwindows that are not on the screen. .TP \fBTK_MOVABLE_POINTS\fR .VS 8.6 Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and \fIinsertProc\fR with the same semantics as Tk's built-in line and polygon types, and that hence individual coordinate points can be moved. Must not be set if any of the above methods is NULL. .VE 8.6 |
︙ | ︙ | |||
225 226 227 228 229 230 231 | \fIitemPtr\fR is a pointer to a newly-allocated item of size \fItypePtr\->itemSize\fR. Tk has already initialized the item's header (the first \fBsizeof(Tk_ItemType)\fR bytes). The \fIobjc\fR and \fIobjv\fR arguments describe all of the arguments to the \fBcreate\fR command after the \fItype\fR argument. | < < < | 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | \fIitemPtr\fR is a pointer to a newly-allocated item of size \fItypePtr\->itemSize\fR. Tk has already initialized the item's header (the first \fBsizeof(Tk_ItemType)\fR bytes). The \fIobjc\fR and \fIobjv\fR arguments describe all of the arguments to the \fBcreate\fR command after the \fItype\fR argument. For example, in the widget command: .PP .CS \fB\&.c create rectangle 10 20 50 50 \-fill black\fR .CE .PP \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the |
︙ | ︙ | |||
257 258 259 260 261 262 263 | \fBTk_ConfigureWidget\fR. This table will normally be used by \fItypePtr\->createProc\fR and \fItypePtr\->configProc\fR, but Tk also uses it directly to retrieve option information in the \fBitemcget\fR and \fBitemconfigure\fR widget commands. \fItypePtr\->configSpecs\fR must point to the configuration table for this type. | > | | 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 | \fBTk_ConfigureWidget\fR. This table will normally be used by \fItypePtr\->createProc\fR and \fItypePtr\->configProc\fR, but Tk also uses it directly to retrieve option information in the \fBitemcget\fR and \fBitemconfigure\fR widget commands. \fItypePtr\->configSpecs\fR must point to the configuration table for this type. .PP Note that Tk provides a custom option type \fBtk_CanvasTagsOption\fR for implementing the \fB\-tags\fR option; see an existing type manager for an example of how to use it in \fIconfigSpecs\fR. .SS CONFIGPROC .PP \fItypePtr\->configProc\fR is called by Tk whenever the \fBitemconfigure\fR widget command is invoked to change the configuration options for a canvas item. |
︙ | ︙ | |||
281 282 283 284 285 286 287 | int \fIflags\fR); .CE .PP The \fIinterp\fR argument identifies the interpreter in which the widget command was invoked, \fIcanvas\fR is a handle for the canvas widget, and \fIitemPtr\fR is a pointer to the item being configured. \fIobjc\fR and \fIobjv\fR contain the configuration options. | < < < | 273 274 275 276 277 278 279 280 281 282 283 284 285 286 | int \fIflags\fR); .CE .PP The \fIinterp\fR argument identifies the interpreter in which the widget command was invoked, \fIcanvas\fR is a handle for the canvas widget, and \fIitemPtr\fR is a pointer to the item being configured. \fIobjc\fR and \fIobjv\fR contain the configuration options. For example, if the following command is invoked: .PP .CS \fB\&.c itemconfigure 2 \-fill red \-outline black\fR .CE .PP \fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR |
︙ | ︙ | |||
320 321 322 323 324 325 326 | int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); .CE .PP The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR all have the standard meanings, and \fIobjc\fR and \fIobjv\fR describe the coordinate arguments. | < < < | 309 310 311 312 313 314 315 316 317 318 319 320 321 322 | int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); .CE .PP The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR all have the standard meanings, and \fIobjc\fR and \fIobjv\fR describe the coordinate arguments. For example, if the following widget command is invoked: .PP .CS \fB\&.c coords 2 30 90\fR .CE .PP \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects |
︙ | ︙ | |||
397 398 399 400 401 402 403 | will not necessarily be the same as those in the canvas. \fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR to transform coordinates from those of the canvas to those of \fIdst\fR. .PP Normally an item's \fIdisplayProc\fR is only invoked if the item overlaps the area being displayed. | | | | 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 | will not necessarily be the same as those in the canvas. \fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR to transform coordinates from those of the canvas to those of \fIdst\fR. .PP Normally an item's \fIdisplayProc\fR is only invoked if the item overlaps the area being displayed. However, if bit zero of \fItypePtr\->flags\fR is 1, (i.e.\| .QW "\fItypePtr\->flags & 1 == 1\fR" ) then \fIdisplayProc\fR is invoked during every redisplay operation, even if the item does not overlap the area of redisplay; this is useful for cases such as window items, where the subwindow needs to be unmapped when it is off the screen. .SS POINTPROC .PP \fItypePtr\->pointProc\fR is invoked by Tk to find out how close |
︙ | ︙ | |||
573 574 575 576 577 578 579 | the item is to be rotated, and \fIangleRad\fR gives the anticlockwise rotation to be applied in radians. The item should adjust the coordinates of its control points so that where they used to have coordinates \fIx\fR and \fIy\fR, they will have new coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .PP .CS | | | | 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 | the item is to be rotated, and \fIangleRad\fR gives the anticlockwise rotation to be applied in radians. The item should adjust the coordinates of its control points so that where they used to have coordinates \fIx\fR and \fIy\fR, they will have new coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .PP .CS \fIrelX\fR = \fIx\fR \(mi \fIoriginX\fR \fIrelY\fR = \fIy\fR \(mi \fIoriginY\fR \fIx\(fm\fR = \fIoriginX\fR + \fIrelX\fR \(mu cos(\fIangleRad\fR) + \fIrelY\fR \(mu sin(\fIangleRad\fR) \fIy\(fm\fR = \fIoriginY\fR \(mi \fIrelX\fR \(mu sin(\fIangleRad\fR) + \fIrelY\fR \(mu cos(\fIangleRad\fR) .CE .PP The control points for an item are not necessarily the coordinates provided to the item when it is created (or via the \fItypePtr\->coordProc\fR), but could instead be derived from them. |
︙ | ︙ | |||
612 613 614 615 616 617 618 | .CE .PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have the usual meaning. \fIindexObj\fR contains a textual description of an index, and \fIindexPtr\fR points to an integer value that should be filled in with a numerical index. | < < < | 598 599 600 601 602 603 604 605 606 607 608 609 610 611 | .CE .PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have the usual meaning. \fIindexObj\fR contains a textual description of an index, and \fIindexPtr\fR points to an integer value that should be filled in with a numerical index. It is up to the type manager to decide what forms of index are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, \fBend\fR, etc.). \fIindexProc\fR should return a Tcl completion code and set the interpreter result in the event of an error. .SS ICURSORPROC .PP |
︙ | ︙ | |||
698 699 700 701 702 703 704 | .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIindex\fR is an index into the item's text, as returned by a previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR contains new text to insert just before the character given by \fIindex\fR. | < < < | 681 682 683 684 685 686 687 688 689 690 691 692 693 694 | .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIindex\fR is an index into the item's text, as returned by a previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR contains new text to insert just before the character given by \fIindex\fR. If the item supports modification of the coordinates list by this .PP The type manager should insert the text and recompute the bounding box in the item's header. .SS DCHARSPROC .PP \fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR |
︙ | ︙ |
Changes to doc/CrtPhImgFmt.3.
︙ | ︙ | |||
54 55 56 57 58 59 60 | An image file format handler consists of a collection of procedures plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormatVersion3 structure contains the following fields: .VS 8.7 .CS | | | 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 | An image file format handler consists of a collection of procedures plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormatVersion3 structure contains the following fields: .VS 8.7 .CS typedef struct { const char *\fIname\fR; Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR; Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR; Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR; Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR; Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR; Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR; |
︙ | ︙ | |||
147 148 149 150 151 152 153 | return 0. .SS FILEREADPROC .PP \fIformatPtr->fileReadProc\fR provides the address of a procedure for Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS | | | 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | return 0. .SS FILEREADPROC .PP \fIformatPtr->fileReadProc\fR provides the address of a procedure for Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileReadProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, |
︙ | ︙ | |||
180 181 182 183 184 185 186 | The return value is a standard Tcl return value. .SS STRINGREADPROC .PP \fIformatPtr->stringReadProc\fR provides the address of a procedure for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS | | | 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | The return value is a standard Tcl return value. .SS STRINGREADPROC .PP \fIformatPtr->stringReadProc\fR provides the address of a procedure for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringReadProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, |
︙ | ︙ | |||
212 213 214 215 216 217 218 | The return value is a standard Tcl return value. .SS FILEWRITEPROC .PP \fIformatPtr->fileWriteProc\fR provides the address of a procedure for Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS | | | 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 | The return value is a standard Tcl return value. .SS FILEWRITEPROC .PP \fIformatPtr->fileWriteProc\fR provides the address of a procedure for Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileWriteProcVersion3\fR( Tcl_Interp *\fIinterp\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was |
︙ | ︙ | |||
241 242 243 244 245 246 247 | .SS STRINGWRITEPROC .PP \fIformatPtr->stringWriteProc\fR provides the address of a procedure for Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS | | | 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | .SS STRINGWRITEPROC .PP \fIformatPtr->stringWriteProc\fR provides the address of a procedure for Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. |
︙ | ︙ | |||
272 273 274 275 276 277 278 | Image formats contain a description of the image bitmap and may contain additional information like image resolution or comments. Image metadata may be read from image files and passed to the script level by including dictionary keys into the metadata property of the image. Image metadata may be written to image data on file write or image data output. .PP | < | | | < | < < | > > > | | | | | | | | | > > | 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 | Image formats contain a description of the image bitmap and may contain additional information like image resolution or comments. Image metadata may be read from image files and passed to the script level by including dictionary keys into the metadata property of the image. Image metadata may be written to image data on file write or image data output. .PP .SS "METADATA KEYS" .PP The metadata may contain any key. A driver will handle only a set of dictionary keys documented in the documentation. See the photo image manual page for currently defined keys for the system drivers. .PP The following rules may give guidance to name metadata keys: .IP \(bu Abbreviations are in upper case. .IP \(bu Words are in US English in small case (except proper nouns) .IP \(bu Vertical DPI is expressed as DPI/aspect. The reason is, that some image formats may feature aspect and no resolution value. .SS "METADATA INPUT" .PP Each driver function gets a Tcl object pointer \fBmetadataIn\fR as parameter. This parameter serves to input a metadata dict to the driver function. It may be NULL to flag that the metadata dict is empty. .PP A typical driver code snipped to check for a metadata key is: .CS if (NULL != metadataIn) { Tcl_Obj *itemData; Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj("Comment",-1), &itemData)); // use value reference in itemData } .CE .PP The \fB\-metadata\fR command option data of the following commands is passed to the driver: \fBimage create\fR, \fBconfigure\fR, \fBput\fR, \fBread\fR, \fBdata\fR and \fBwrite\fR. If no \fB\-metadata\fR command option available or not given, the metadata property of the image is passed to the driver using the following commands: \fBcget\fR, \fBconfigure\fR, \fBdata\fR and \fBwrite\fR. .PP Note that setting the \fB\-metadata\fR property of an image using \fBconfigure\fR without any other option does not invoke any driver function. .PP The metadata dictionary is not suited to pass options to the driver related to the bitmap representation, as the image bitmap is not recreated on a metadata change. The format string should be used for this purpose. .PP .SS "METADATA OUTPUT" .PP The image match and read driver functions may set keys in a prepared metadata dict to return them. Those functions get a Tcl object pointer \fImetadataOut\fR as parameter. \fImetadataOut\fR may be NULL to indicate, that no metadata return is required (\fBput\fR, \fBread\fR subcommands). The variable pointed to by \fImetadataOut\fR is initialized to an empty unshared dict object if metadata return is attended (\fBimage create\fR command, \fBconfigure\fR subcommand). The driver may set dict keys in this object to return metadata. If a match function succeeds, the metadataOut pointer is passed to the corresponding read function. .PP A sample driver code snippet is: .CS if (NULL != metadataOut) { Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj("XMP",-1), Tcl_NewStringObj(xmpMetadata)); } .CE .PP The metadata keys returned by the driver are merged into the present metadata property of the image or into the metadata dict given by the \fB\-metadata\fR command line option. At the script level, the command \fBimage create\fR and the \fBconfigure\fR method may return metadata from the driver. |
︙ | ︙ | |||
372 373 374 375 376 377 378 | Structure that defines the new file format. .BE .SS DESCRIPTION A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR for driver registration. The Tk_PhotoImageFormat structure contains the following fields: .CS | | | 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | Structure that defines the new file format. .BE .SS DESCRIPTION A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR for driver registration. The Tk_PhotoImageFormat structure contains the following fields: .CS typedef struct { const char *\fIname\fR; Tk_ImageFileMatchProc *\fIfileMatchProc\fR; Tk_ImageStringMatchProc *\fIstringMatchProc\fR; Tk_ImageFileReadProc *\fIfileReadProc\fR; Tk_ImageStringReadProc *\fIstringReadProc\fR; Tk_ImageFileWriteProc *\fIfileWriteProc\fR; Tk_ImageStringWriteProc *\fIstringWriteProc\fR; |
︙ | ︙ | |||
453 454 455 456 457 458 459 | \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | 454 455 456 457 458 459 460 461 462 463 464 | \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE .SH "SEE ALSO" Tk_FindPhoto, Tk_PhotoPutBlock .SH KEYWORDS photo image, image file |
Changes to doc/CrtSelHdlr.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) .sp \fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) .SH ARGUMENTS .AS Tk_SelectionProc clientData .AP Tk_Window tkwin in Window for which \fIproc\fR will provide selection information. .AP Atom selection in The name of the selection for which \fIproc\fR will provide selection information. | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) .sp \fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) .fi .SH ARGUMENTS .AS Tk_SelectionProc clientData .AP Tk_Window tkwin in Window for which \fIproc\fR will provide selection information. .AP Atom selection in The name of the selection for which \fIproc\fR will provide selection information. |
︙ | ︙ |
Changes to doc/CrtWindow.3.
︙ | ︙ | |||
22 23 24 25 26 27 28 29 30 31 32 33 34 35 | .sp Tk_Window \fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) .sp \fBTk_DestroyWindow\fR(\fItkwin\fR) .sp \fBTk_MakeWindowExist\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tcl_Interp *topLevScreen .AP Tcl_Interp *interp out Tcl interpreter to use for error reporting. If no error occurs, then \fI*interp\fR is not modified. .AP Tk_Window parent in Token for the window that is to serve as the logical parent of | > | 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | .sp Tk_Window \fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) .sp \fBTk_DestroyWindow\fR(\fItkwin\fR) .sp \fBTk_MakeWindowExist\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *topLevScreen .AP Tcl_Interp *interp out Tcl interpreter to use for error reporting. If no error occurs, then \fI*interp\fR is not modified. .AP Tk_Window parent in Token for the window that is to serve as the logical parent of |
︙ | ︙ |
Changes to doc/DeleteImg.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 17 18 19 20 21 22 23 | .SH NAME Tk_DeleteImage \- Destroy an image. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_DeleteImage\fR(\fIinterp, name\fR) .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter for which the image was created. .AP "const char" *name in Name of the image. .BE | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_DeleteImage \- Destroy an image. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_DeleteImage\fR(\fIinterp, name\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter for which the image was created. .AP "const char" *name in Name of the image. .BE |
︙ | ︙ |
Changes to doc/DrawFocHlt.3.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .BS .SH NAME Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp | | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .BS .SH NAME Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_DrawFocusHighlight\fR(\fItkwin, gc, width, drawable\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tk_Window tkwin in Window for which the highlight is being drawn. Used to retrieve the window's dimensions, among other things. .AP GC gc in Graphics context to use for drawing the highlight. |
︙ | ︙ |
Changes to doc/EventHndlr.3.
︙ | ︙ | |||
17 18 19 20 21 22 23 24 25 26 27 28 29 30 | \fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_GetButtonMask\fR(\fIbutton\fR) .sp \fBTk_SendVirtualEvent\fR(\fItkwin, eventName, detail\fR) .SH ARGUMENTS .AS "unsigned long" clientData .AP unsigned button in Button number. .AP "const char" *eventName in The name of the virtual event. .AP Tcl_Obj *detail in | > | 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | \fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_GetButtonMask\fR(\fIbutton\fR) .sp \fBTk_SendVirtualEvent\fR(\fItkwin, eventName, detail\fR) .fi .SH ARGUMENTS .AS "unsigned long" clientData .AP unsigned button in Button number. .AP "const char" *eventName in The name of the virtual event. .AP Tcl_Obj *detail in |
︙ | ︙ |
Changes to doc/FindPhoto.3.
︙ | ︙ | |||
28 29 30 31 32 33 34 | int \fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ zoomX, zoomY, subsampleX, subsampleY, compRule\fR) .sp int \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) .sp | < < > | 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | int \fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ zoomX, zoomY, subsampleX, subsampleY, compRule\fR) .sp int \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) .sp \fBTk_PhotoBlank\fR(\fIhandle\fR) .sp int \fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) .sp \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) .sp int \fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) .fi .SH ARGUMENTS .AS Tk_PhotoImageBlock window_path .AP Tcl_Interp *interp in Interpreter in which image was created and in which error reporting is to be done. .AP "const char" *imageName in Name of the photo image. |
︙ | ︙ |
Changes to doc/FontId.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for fonts .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Font | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for fonts .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Font \fBTk_FontId\fR(\fItkfont\fR) .sp \fBTk_GetFontMetrics\fR(\fItkfont, fmPtr\fR) .sp int \fBTk_PostscriptFontName\fR(\fItkfont, dsPtr\fR) .fi .SH ARGUMENTS .AS Tk_FontMetrics *dsPtr .AP Tk_Font tkfont in Opaque font token being queried. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP Tk_FontMetrics *fmPtr out Pointer to structure in which the font metrics for \fItkfont\fR will |
︙ | ︙ | |||
65 66 67 68 69 70 71 | Any other font families may not print correctly because the computed Postscript font name may be incorrect or not exist on the printer. .SH "DATA STRUCTURES" .PP The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to return information about a font and is defined as follows: .CS | | | 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 | Any other font families may not print correctly because the computed Postscript font name may be incorrect or not exist on the printer. .SH "DATA STRUCTURES" .PP The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to return information about a font and is defined as follows: .CS typedef struct { int \fIascent\fR; int \fIdescent\fR; int \fIlinespace\fR; } \fBTk_FontMetrics\fR; .CE .PP The \fIascent\fR field is the amount in pixels that the tallest |
︙ | ︙ |
Changes to doc/GeomReq.3.
︙ | ︙ | |||
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | \fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) .sp \fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) .sp \fBTk_SetInternalBorder\fR(\fItkwin, width\fR) .sp \fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) .SH ARGUMENTS .AS baseHeight clientData .AP Tk_Window tkwin in Window for which geometry is being requested. .AP int reqWidth in Desired width for \fItkwin\fR, in pixel units. .AP int reqHeight in Desired height for \fItkwin\fR, in pixel units. .AP int minWidth in Desired minimum requested width for \fItkwin\fR, in pixel units. .AP int minHeight in Desired minimum requested height for \fItkwin\fR, in pixel units. .AP int width in Space to leave for internal border for \fItkwin\fR, in pixel units. .AP int left in | > | > | > | > | > | 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | \fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) .sp \fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) .sp \fBTk_SetInternalBorder\fR(\fItkwin, width\fR) .sp \fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) .fi .SH ARGUMENTS .AS baseHeight clientData .AP Tk_Window tkwin in Window for which geometry is being requested. .AP int reqWidth in Desired width for \fItkwin\fR, in pixel units. .AP int reqHeight in Desired height for \fItkwin\fR, in pixel units. .AP int minWidth in Desired minimum requested width for \fItkwin\fR, in pixel units. .AP int minHeight in Desired minimum requested height for \fItkwin\fR, in pixel units. .AP int width in Space to leave for internal border for \fItkwin\fR, in pixel units. .AP int left in Space to leave for left side of internal border for \fItkwin\fR, in pixel units. .AP int right in Space to leave for right side of internal border for \fItkwin\fR, in pixel units. .AP int top in Space to leave for top side of internal border for \fItkwin\fR, in pixel units. .AP int bottom in Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. .BE .SH DESCRIPTION .PP \fBTk_GeometryRequest\fR is called by widget code to indicate its preference for the dimensions of a particular window. The arguments to \fBTk_GeometryRequest\fR are made available to the geometry manager for the window, which then decides on the actual geometry |
︙ | ︙ |
Changes to doc/GetAnchor.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | .SH NAME Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetAnchorFromObj\fR(\fIinterp, objPtr, anchorPtr\fR) .sp int \fBTk_GetAnchor\fR(\fIinterp, string, anchorPtr\fR) .sp const char * \fBTk_NameOfAnchor\fR(\fIanchor\fR) .fi .SH ARGUMENTS .AS "Tk_Anchor" *anchorPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out String value contains name of anchor point: .QW \fBn\fR , |
︙ | ︙ |
Changes to doc/GetBitmap.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Pixmap | | | | | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | .SH NAME Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Pixmap \fBTk_AllocBitmapFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Pixmap \fBTk_GetBitmap\fR(\fIinterp, tkwin, info\fR) .sp Pixmap \fBTk_GetBitmapFromObj\fR(\fItkwin, objPtr\fR) .sp int \fBTk_DefineBitmap\fR(\fIinterp, name, source, width, height\fR) .sp const char * \fBTk_NameOfBitmap\fR(\fIdisplay, bitmap\fR) .sp \fBTk_SizeOfBitmap\fR(\fIdisplay, bitmap, widthPtr, heightPtr\fR) .sp \fBTk_FreeBitmapFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeBitmap\fR(\fIdisplay, bitmap\fR) .fi .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting; if NULL then no error message is left after errors. .AP Tk_Window tkwin in Token for window in which the bitmap will be used. |
︙ | ︙ | |||
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap that matches the description in \fIobjPtr\fR and is suitable for use in \fItkwin\fR. It re-uses an existing bitmap, if possible, and creates a new one otherwise. \fIObjPtr\fR's value must have one of the following forms: .TP 20 \fB@\fIfileName\fR \fIFileName\fR must be the name of a file containing a bitmap description in the standard X11 format. .TP 20 \fIname\fR \fIName\fR must be the name of a bitmap defined previously with a call to \fBTk_DefineBitmap\fR. The following names are pre-defined by Tk: .RS | > > < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | < | | 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 | \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap that matches the description in \fIobjPtr\fR and is suitable for use in \fItkwin\fR. It re-uses an existing bitmap, if possible, and creates a new one otherwise. \fIObjPtr\fR's value must have one of the following forms: .TP 20 \fB@\fIfileName\fR . \fIFileName\fR must be the name of a file containing a bitmap description in the standard X11 format. .TP 20 \fIname\fR . \fIName\fR must be the name of a bitmap defined previously with a call to \fBTk_DefineBitmap\fR. The following names are pre-defined by Tk: .RS .IP \fBerror\fR 12 The international .QW don't symbol: a circle with a diagonal line across it. .IP \fBgray75\fR 12 75% gray: a checkerboard pattern where three out of four bits are on. .IP \fBgray50\fR 12 50% gray: a checkerboard pattern where every other bit is on. .IP \fBgray25\fR 12 25% gray: a checkerboard pattern where one out of every four bits is on. .IP \fBgray12\fR 12 12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row. .IP \fBhourglass\fR 12 An hourglass symbol. .IP \fBinfo\fR 12 A large letter .QW i . .IP \fBquesthead\fR 12 The silhouette of a human head, with a question mark in it. .IP \fBquestion\fR 12 A large question-mark. .IP \fBwarning\fR 12 A large exclamation point. .PP In addition, the following pre-defined names are available only on the \fBMacintosh\fR platform: .IP \fBdocument\fR 12 A generic document. .IP \fBstationery\fR 12 Document stationery. .IP \fBedition\fR 12 The \fIedition\fR symbol. .IP \fBapplication\fR 12 Generic application icon. .IP \fBaccessory\fR 12 A desk accessory. .IP \fBfolder\fR 12 Generic folder icon. .IP \fBpfolder\fR 12 A locked folder. .IP \fBtrash\fR 12 A trash can. .IP \fBfloppy\fR 12 A floppy disk. .IP \fBramdisk\fR 12 A floppy disk with chip. .IP \fBcdrom\fR 12 A cd disk icon. .IP \fBpreferences\fR 12 A folder with prefs symbol. .IP \fBquerydoc\fR 12 A database document icon. .IP \fBstop\fR 12 A stop sign. .IP \fBnote\fR 12 A face with balloon words. .IP \fBcaution\fR 12 A triangle with an exclamation point. .RE .LP Under normal conditions, \fBTk_AllocBitmapFromObj\fR returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error |
︙ | ︙ | |||
206 207 208 209 210 211 212 | have been used in a call to \fBTk_DefineBitmap\fR. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR describe the bitmap. \fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then \fBTCL_ERROR\fR is returned and an error message is left in interpreter \fIinterp\fR's result. | | | 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | have been used in a call to \fBTk_DefineBitmap\fR. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR describe the bitmap. \fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then \fBTCL_ERROR\fR is returned and an error message is left in interpreter \fIinterp\fR's result. Note that \fBTk_DefineBitmap\fR expects the memory pointed to by \fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make a private copy of this memory, but uses the bytes pointed to by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a bitmap file directly into a C program and then referencing |
︙ | ︙ |
Changes to doc/GetCapStyl.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | .SH NAME Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetCapStyle\fR(\fIinterp, string, capPtr\fR) .sp const char * \fBTk_NameOfCapStyle\fR(\fIcap\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *capPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in String containing name of cap style \- one of .QW \fBbutt\fR , |
︙ | ︙ |
Changes to doc/GetClrmap.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Colormap | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | .SH NAME Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Colormap \fBTk_GetColormap\fR(\fIinterp, tkwin, string\fR) .sp \fBTk_PreserveColormap\fR(\fIdisplay, colormap\fR) .sp \fBTk_FreeColormap\fR(\fIdisplay, colormap\fR) .fi .SH ARGUMENTS .AS "Colormap" colormap .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which colormap will be used. .AP "const char" *string in |
︙ | ︙ |
Changes to doc/GetColor.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp XColor * | | | | | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | .SH NAME Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp XColor * \fBTk_AllocColorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp XColor * \fBTk_GetColor\fR(\fIinterp, tkwin, name\fR) .sp XColor * \fBTk_GetColorFromObj\fR(\fItkwin, objPtr\fR) .sp XColor * \fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fR) .sp const char * \fBTk_NameOfColor\fR(\fIcolorPtr\fR) .sp GC \fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) .sp \fBTk_FreeColorFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeColor\fR(\fIcolorPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *colorPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which color will be used. .AP Tcl_Obj *objPtr in/out |
︙ | ︙ | |||
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | .PP Given a textual description of a color, \fBTk_AllocColorFromObj\fR locates a pixel value that may be used to render the color in a particular window. The desired color is specified with a value whose string value must have one of the following forms: .TP 20 \fIcolorname\fR Any of the valid textual names for a color defined in the server's color database file, such as \fBred\fR or \fBPeachPuff\fR. .TP 20 \fB#\fIRGB\fR .TP 20 \fB#\fIRRGGBB\fR .TP 20 \fB#\fIRRRGGGBBB\fR .TP 20 \fB#\fIRRRRGGGGBBBB\fR A numeric specification of the red, green, and blue intensities to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR represents a single hexadecimal digit. The four forms permit colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. When fewer than 16 bits are provided for each color, they represent the most significant bits of the color, while the lower unfilled bits will be repeatedly replicated from the available higher bits. | > > | 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | .PP Given a textual description of a color, \fBTk_AllocColorFromObj\fR locates a pixel value that may be used to render the color in a particular window. The desired color is specified with a value whose string value must have one of the following forms: .TP 20 \fIcolorname\fR . Any of the valid textual names for a color defined in the server's color database file, such as \fBred\fR or \fBPeachPuff\fR. .TP 20 \fB#\fIRGB\fR .TP 20 \fB#\fIRRGGBB\fR .TP 20 \fB#\fIRRRGGGBBB\fR .TP 20 \fB#\fIRRRRGGGGBBBB\fR . A numeric specification of the red, green, and blue intensities to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR represents a single hexadecimal digit. The four forms permit colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. When fewer than 16 bits are provided for each color, they represent the most significant bits of the color, while the lower unfilled bits will be repeatedly replicated from the available higher bits. |
︙ | ︙ |
Changes to doc/GetCursor.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Cursor | | | | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | .SH NAME Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Cursor \fBTk_AllocCursorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_Cursor \fBTk_GetCursor\fR(\fIinterp, tkwin, name\fR) .sp Tk_Cursor \fBTk_GetCursorFromObj\fR(\fItkwin, objPtr\fR) .sp Tk_Cursor \fBTk_GetCursorFromData\fR(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fR) .sp const char * \fBTk_NameOfCursor\fR(\fIdisplay, cursor\fR) .sp \fBTk_FreeCursorFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeCursor\fR(\fIdisplay, cursor\fR) .fi .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which the cursor will be used. .AP Tcl_Obj *objPtr in/out |
︙ | ︙ | |||
83 84 85 86 87 88 89 90 91 92 93 94 95 96 | \fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error message will be stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: .TP \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] \fIName\fR is the name of a cursor in the standard X cursor cursor, i.e., any of the names defined in \fBcursorcursor.h\fR, without the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, or \fBleft_ptr\fR. Appendix B of .QW "The X Window System" by Scheifler & Gettys has illustrations showing what each of these cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both | > | 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | \fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error message will be stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: .TP \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] . \fIName\fR is the name of a cursor in the standard X cursor cursor, i.e., any of the names defined in \fBcursorcursor.h\fR, without the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, or \fBleft_ptr\fR. Appendix B of .QW "The X Window System" by Scheifler & Gettys has illustrations showing what each of these cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both |
︙ | ︙ | |||
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | name of the resource. The application and all its open dynamic library's resource files will be searched for the named cursor. If there are conflicts color cursors will always be loaded in preference to black and white cursors. .RE .TP \fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR In this form, \fIsourceName\fR and \fImaskName\fR are the names of files describing cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. \fIFgColor\fR and \fIbgColor\fR indicate the colors to use for the cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\0fgColor\fR This form is similar to the one above, except that the source is used as mask also. This means that the cursor's background is transparent. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\fR This form only works on Windows, and will load a Windows system cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in \fIsourceName\fR. .PP \fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except that the description of the cursor is specified with a string instead of an object. This prevents \fBTk_GetCursor\fR from caching the | > > > | 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | name of the resource. The application and all its open dynamic library's resource files will be searched for the named cursor. If there are conflicts color cursors will always be loaded in preference to black and white cursors. .RE .TP \fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR . In this form, \fIsourceName\fR and \fImaskName\fR are the names of files describing cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. \fIFgColor\fR and \fIbgColor\fR indicate the colors to use for the cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\0fgColor\fR . This form is similar to the one above, except that the source is used as mask also. This means that the cursor's background is transparent. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\fR . This form only works on Windows, and will load a Windows system cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in \fIsourceName\fR. .PP \fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except that the description of the cursor is specified with a string instead of an object. This prevents \fBTk_GetCursor\fR from caching the |
︙ | ︙ | |||
192 193 194 195 196 197 198 | The procedure \fBTk_NameOfCursor\fR is roughly the inverse of \fBTk_GetCursor\fR. If its \fIcursor\fR argument was created by \fBTk_GetCursor\fR, then the return value is the \fIname\fR argument that was passed to \fBTk_GetCursor\fR to create the cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. | | | 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 | The procedure \fBTk_NameOfCursor\fR is roughly the inverse of \fBTk_GetCursor\fR. If its \fIcursor\fR argument was created by \fBTk_GetCursor\fR, then the return value is the \fIname\fR argument that was passed to \fBTk_GetCursor\fR to create the cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. Note that the string returned by \fBTk_NameOfCursor\fR is only guaranteed to persist until the next call to \fBTk_NameOfCursor\fR. Also, this call is not portable except for cursors returned by \fBTk_GetCursor\fR. .PP When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR is no longer needed, \fBTk_FreeCursorFromObj\fR or |
︙ | ︙ |
Changes to doc/GetFont.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Font | | | | | | | < | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | .SH NAME Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Font \fBTk_AllocFontFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_Font \fBTk_GetFont\fR(\fIinterp, tkwin, string\fR) .sp Tk_Font \fBTk_GetFontFromObj\fR(\fItkwin, objPtr\fR) .sp Tcl_Obj * \fBTk_FontGetDescription\fR(\fItkfont\fR) .sp const char * \fBTk_NameOfFont\fR(\fItkfont\fR) .sp Tk_Font \fBTk_FreeFontFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeFont\fR(\fItkfont\fR) .fi .SH ARGUMENTS .AS "const char" *tkfont .AP "Tcl_Interp" *interp in Interpreter to use for error reporting. If \fBNULL\fR, then no error messages are left after errors. .AP Tk_Window tkwin in Token for window in which font will be used. |
︙ | ︙ | |||
88 89 90 91 92 93 94 | a database of all fonts they have allocated. If the same font is requested multiple times (e.g. by different windows or for different purposes), then a single Tk_Font will be shared for all uses. The underlying resources will be freed automatically when no-one is using the font anymore. .PP The procedure \fBTk_FontGetDescription\fR returns information about the font | | > | 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | a database of all fonts they have allocated. If the same font is requested multiple times (e.g. by different windows or for different purposes), then a single Tk_Font will be shared for all uses. The underlying resources will be freed automatically when no-one is using the font anymore. .PP The procedure \fBTk_FontGetDescription\fR returns information about the font description as a Tcl list. One possible result is .QW "{{DejaVu Sans} -16 bold underline}" . .PP The procedure \fBTk_NameOfFont\fR is roughly the inverse of \fBTk_GetFont\fR. Given a \fItkfont\fR that was created by \fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is the \fIstring\fR argument that was passed to \fBTk_GetFont\fR to create the font. The string returned by \fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR |
︙ | ︙ |
Changes to doc/GetGC.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp GC \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) .sp | | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp GC \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) .sp \fBTk_FreeGC\fR(\fIdisplay, gc\fR) .fi .SH ARGUMENTS .AS "unsigned long" valueMask .AP Tk_Window tkwin in Token for window in which the graphics context will be used. .AP "unsigned long" valueMask in Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) indicating which fields of \fI*valuePtr\fR are valid. |
︙ | ︙ |
Changes to doc/GetHINSTANCE.3.
︙ | ︙ | |||
9 10 11 12 13 14 15 16 17 18 19 20 21 22 | Tk_GetHINSTANCE \- retrieve the global application instance handle .SH SYNOPSIS .nf \fB#include <tkPlatDecls.h>\fR .sp HINSTANCE \fBTk_GetHINSTANCE\fR() .BE .SH DESCRIPTION .PP \fBTk_GetHINSTANCE\fR returns the Windows application instance handle for the Tk application. This function is only available on Windows platforms. .SH KEYWORDS identifier, instance | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | Tk_GetHINSTANCE \- retrieve the global application instance handle .SH SYNOPSIS .nf \fB#include <tkPlatDecls.h>\fR .sp HINSTANCE \fBTk_GetHINSTANCE\fR() .fi .BE .SH DESCRIPTION .PP \fBTk_GetHINSTANCE\fR returns the Windows application instance handle for the Tk application. This function is only available on Windows platforms. .SH KEYWORDS identifier, instance |
Changes to doc/GetHWND.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | \fB#include <tkPlatDecls.h>\fR .sp HWND \fBTk_GetHWND\fR(\fIwindow\fR) .sp Window \fBTk_AttachHWND\fR(\fItkwin, hwnd\fR) .SH ARGUMENTS .AP Window window in X token for window. .AP Tk_Window tkwin in Tk window for window. .AP HWND hwnd in Windows HWND for window. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | \fB#include <tkPlatDecls.h>\fR .sp HWND \fBTk_GetHWND\fR(\fIwindow\fR) .sp Window \fBTk_AttachHWND\fR(\fItkwin, hwnd\fR) .fi .SH ARGUMENTS .AP Window window in X token for window. .AP Tk_Window tkwin in Tk window for window. .AP HWND hwnd in Windows HWND for window. |
︙ | ︙ |
Changes to doc/GetImage.3.
︙ | ︙ | |||
18 19 20 21 22 23 24 25 26 27 28 29 30 31 | \fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) .sp \fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) .sp \fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) .sp \fBTk_FreeImage\fR(\fIimage\fR) .SH ARGUMENTS .AS Tk_ImageChangedProc *changeProc .AP Tcl_Interp *interp in Place to leave error message. .AP Tk_Window tkwin in Window in which image will be used. .AP "const char" *name in | > | 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | \fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) .sp \fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) .sp \fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) .sp \fBTk_FreeImage\fR(\fIimage\fR) .fi .SH ARGUMENTS .AS Tk_ImageChangedProc *changeProc .AP Tcl_Interp *interp in Place to leave error message. .AP Tk_Window tkwin in Window in which image will be used. .AP "const char" *name in |
︙ | ︙ |
Changes to doc/GetJoinStl.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | .SH NAME Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetJoinStyle\fR(\fIinterp, string, joinPtr\fR) .sp const char * \fBTk_NameOfJoinStyle\fR(\fIjoin\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in String containing name of join style \- one of .QW \fBbevel\fR , |
︙ | ︙ |
Changes to doc/GetJustify.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | .SH NAME Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetJustifyFromObj\fR(\fIinterp, objPtr, justifyPtr\fR) .sp int \fBTk_GetJustify\fR(\fIinterp, string, justifyPtr\fR) .sp const char * \fBTk_NameOfJustify\fR(\fIjustify\fR) .fi .SH ARGUMENTS .AS "Tk_Justify" *justifyPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out String value contains name of justification style \- one of .QW \fBleft\fR , |
︙ | ︙ | |||
44 45 46 47 48 49 50 | Justification style (one of the values listed below). .BE .SH DESCRIPTION .PP \fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value corresponding to \fIobjPtr\fR's value. This value will be one of the following: | < | < | < | | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | Justification style (one of the values listed below). .BE .SH DESCRIPTION .PP \fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value corresponding to \fIobjPtr\fR's value. This value will be one of the following: .IP \fBTK_JUSTIFY_LEFT\fR Means that the text on each line should start at the left edge of the line; as a result, the right edges of lines may be ragged. .IP \fBTK_JUSTIFY_RIGHT\fR Means that the text on each line should end at the right edge of the line; as a result, the left edges of lines may be ragged. .IP \fBTK_JUSTIFY_CENTER\fR Means that the text on each line should be centered; as a result, both the left and right edges of lines may be ragged. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIobjPtr\fR does not contain a valid justification style or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, |
︙ | ︙ |
Changes to doc/GetOption.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_GetOption \- retrieve an option from the option database .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Uid \fBTk_GetOption\fR(\fItkwin, name, class\fR) .SH ARGUMENTS .AS Tk_Window *class .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Name of desired option. .AP "const char" *class in | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_GetOption \- retrieve an option from the option database .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Uid \fBTk_GetOption\fR(\fItkwin, name, class\fR) .fi .SH ARGUMENTS .AS Tk_Window *class .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Name of desired option. .AP "const char" *class in |
︙ | ︙ |
Changes to doc/GetPixels.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | .SH NAME Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetPixelsFromObj\fR(\fIinterp, tkwin, objPtr, intPtr\fR) .sp int \fBTk_GetDoublePixelsFromObj\fR(\fIinterp, tkwin, objPtr, doublePtr\fR) .sp int \fBTk_GetPixels\fR(\fIinterp, tkwin, string, intPtr\fR) .sp int \fBTk_GetMMFromObj\fR(\fIinterp, tkwin, objPtr, doublePtr\fR) .sp int \fBTk_GetScreenMM\fR(\fIinterp, tkwin, string, doublePtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Window whose screen geometry determines the conversion between absolute units and pixels. |
︙ | ︙ | |||
52 53 54 55 56 57 58 | the screen (\fIobjPtr\fR or \fIstring\fR) and compute the corresponding distance either in integer pixels or floating-point millimeters. In either case, \fIobjPtr\fR or \fIstring\fR specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: | < | < | < | < | < | | 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | the screen (\fIobjPtr\fR or \fIstring\fR) and compute the corresponding distance either in integer pixels or floating-point millimeters. In either case, \fIobjPtr\fR or \fIstring\fR specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: .IP <none> The number specifies a distance in pixels. .IP \fBc\fR The number specifies a distance in centimeters on the screen. .IP \fBi\fR The number specifies a distance in inches on the screen. .IP \fBm\fR The number specifies a distance in millimeters on the screen. .IP \fBp\fR The number specifies a distance in printer's points (1/72 inch) on the screen. .PP \fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the nearest even number of pixels and stores that value at \fI*intPtr\fR. It returns \fBTCL_OK\fR under normal circumstances. If an error occurs (e.g. \fIobjPtr\fR contains a number followed |
︙ | ︙ |
Changes to doc/GetPixmap.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Pixmap | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | .SH NAME Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Pixmap \fBTk_GetPixmap\fR(\fIdisplay, d, width, height, depth\fR) .sp \fBTk_FreePixmap\fR(\fIdisplay, pixmap\fR) .fi .SH ARGUMENTS .AS "Drawable" *pixelPtr .AP Display *display in X display for the pixmap. .AP Drawable d in Pixmap or window where the new pixmap will be used for drawing. .AP "int" width in |
︙ | ︙ |
Changes to doc/GetRelief.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | .SH NAME Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetReliefFromObj\fR(\fIinterp, objPtr, reliefPtr\fR) .sp int \fBTk_GetRelief\fR(\fIinterp, name, reliefPtr\fR) .sp const char * \fBTk_NameOfRelief\fR(\fIrelief\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *reliefPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tcl_Obj *objPtr in/out String value contains name of relief, one of .QW \fBflat\fR , |
︙ | ︙ |
Changes to doc/GetRootCrd.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_GetRootCoords \- Compute root-window coordinates of window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .AP int *xPtr out Pointer to location in which to store root-window x-coordinate corresponding to left edge of \fItkwin\fR's border. | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_GetRootCoords \- Compute root-window coordinates of window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .AP int *xPtr out Pointer to location in which to store root-window x-coordinate corresponding to left edge of \fItkwin\fR's border. |
︙ | ︙ |
Changes to doc/GetScroll.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | .SH NAME Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetScrollInfoObj\fR(\fIinterp, objc, objv, fractionPtr, stepsPtr\fR) .sp int \fBTk_GetScrollInfo\fR(\fIinterp, argc, argv, fractionPtr, stepsPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *fractionPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP int objc in Number of Tcl_Obj's in \fIobjv\fR array. .AP "Tcl_Obj *const *" objv in |
︙ | ︙ |
Changes to doc/GetSelect.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_GetSelection \- retrieve the contents of a selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) .SH ARGUMENTS .AS Tk_GetSelProc clientData .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window on whose behalf to retrieve the selection (determines display from which to retrieve). | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_GetSelection \- retrieve the contents of a selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) .fi .SH ARGUMENTS .AS Tk_GetSelProc clientData .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window on whose behalf to retrieve the selection (determines display from which to retrieve). |
︙ | ︙ |
Changes to doc/GetUid.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_GetUid, Tk_Uid \- convert from string to unique identifier .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Uid \fBTk_GetUid\fR(\fIstring\fR) .SH ARGUMENTS .AP char *string in String for which the corresponding unique identifier is desired. .BE .SH DESCRIPTION .PP | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_GetUid, Tk_Uid \- convert from string to unique identifier .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Uid \fBTk_GetUid\fR(\fIstring\fR) .fi .SH ARGUMENTS .AP char *string in String for which the corresponding unique identifier is desired. .BE .SH DESCRIPTION .PP |
︙ | ︙ |
Changes to doc/GetVRoot.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .BS .SH NAME Tk_GetVRootGeometry \- Get location and size of virtual root for window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp | | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .BS .SH NAME Tk_GetVRootGeometry \- Get location and size of virtual root for window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_GetVRootGeometry\fR(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fR) .fi .SH ARGUMENTS .AS Tk_Window heightPtr .AP Tk_Window tkwin in Token for window whose virtual root is to be queried. .AP int xPtr out Points to word in which to store x-offset of virtual root. .AP int yPtr out |
︙ | ︙ |
Changes to doc/GetVisual.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetVisual \- translate from string to visual .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Visual * | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME Tk_GetVisual \- translate from string to visual .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Visual * \fBTk_GetVisual\fR(\fIinterp, tkwin, string, depthPtr, colormapPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *colormapPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which the visual will be used. .AP "const char" *string in |
︙ | ︙ | |||
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | also locates an appropriate colormap for use with the result visual and stores its X identifier at \fI*colormapPtr\fR. .PP The \fIstring\fR argument specifies the desired visual in one of the following ways: .TP 15 \fIclass depth\fR The string consists of a class name followed by an integer depth, with any amount of white space (including none) in between. \fIclass\fR selects what sort of visual is desired and must be one of \fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or \fBtruecolor\fR, or a unique abbreviation. \fIdepth\fR specifies how many bits per pixel are needed for the visual. If possible, \fBTk_GetVisual\fR will return a visual with this depth; if there is no visual of the desired depth then \fBTk_GetVisual\fR looks first for a visual with greater depth, then one with less depth. .TP 15 \fBdefault\fR Use the default visual for \fItkwin\fR's screen. .TP 15 \fIpathName\fR Use the visual for the window given by \fIpathName\fR. \fIpathName\fR must be the name of a window on the same screen as \fItkwin\fR. .TP 15 \fInumber\fR Use the visual whose X identifier is \fInumber\fR. .TP 15 \fBbest\fR ?\fIdepth\fR? Choose the .QW "best possible" visual, using the following rules, in decreasing order of priority: .RS .IP (a) a visual that has exactly the desired depth is best, followed by a visual with greater depth than requested (but as little extra | > > > > > | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | also locates an appropriate colormap for use with the result visual and stores its X identifier at \fI*colormapPtr\fR. .PP The \fIstring\fR argument specifies the desired visual in one of the following ways: .TP 15 \fIclass depth\fR . The string consists of a class name followed by an integer depth, with any amount of white space (including none) in between. \fIclass\fR selects what sort of visual is desired and must be one of \fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or \fBtruecolor\fR, or a unique abbreviation. \fIdepth\fR specifies how many bits per pixel are needed for the visual. If possible, \fBTk_GetVisual\fR will return a visual with this depth; if there is no visual of the desired depth then \fBTk_GetVisual\fR looks first for a visual with greater depth, then one with less depth. .TP 15 \fBdefault\fR . Use the default visual for \fItkwin\fR's screen. .TP 15 \fIpathName\fR . Use the visual for the window given by \fIpathName\fR. \fIpathName\fR must be the name of a window on the same screen as \fItkwin\fR. .TP 15 \fInumber\fR . Use the visual whose X identifier is \fInumber\fR. .TP 15 \fBbest\fR ?\fIdepth\fR? . Choose the .QW "best possible" visual, using the following rules, in decreasing order of priority: .RS .IP (a) a visual that has exactly the desired depth is best, followed by a visual with greater depth than requested (but as little extra |
︙ | ︙ |
Changes to doc/Grab.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) .sp | < > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) .sp \fBTk_Ungrab\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AP Tcl_Interp *interp in Interpreter to use for error reporting .AP Tk_Window tkwin in Window on whose behalf the pointer is to be grabbed or released .AP int grabGlobal in Boolean indicating whether the grab is global or application local |
︙ | ︙ |
Changes to doc/HWNDToWindow.3.
︙ | ︙ | |||
9 10 11 12 13 14 15 16 17 18 19 20 21 22 | Tk_HWNDToWindow \- Find Tk's window information for a Windows window .SH SYNOPSIS .nf \fB#include <tkPlatDecls.h>\fR .sp Tk_Window \fBTk_HWNDToWindow\fR(\fIhwnd\fR) .SH ARGUMENTS .AP HWND hwnd in Windows handle for the window. .BE .SH DESCRIPTION .PP Given a Windows HWND window identifier, this procedure returns the | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | Tk_HWNDToWindow \- Find Tk's window information for a Windows window .SH SYNOPSIS .nf \fB#include <tkPlatDecls.h>\fR .sp Tk_Window \fBTk_HWNDToWindow\fR(\fIhwnd\fR) .fi .SH ARGUMENTS .AP HWND hwnd in Windows handle for the window. .BE .SH DESCRIPTION .PP Given a Windows HWND window identifier, this procedure returns the |
︙ | ︙ |
Changes to doc/HandleEvent.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_HandleEvent \- invoke event handlers for window system events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_HandleEvent\fR(\fIeventPtr\fR) .SH ARGUMENTS .AS XEvent *eventPtr .AP XEvent *eventPtr in Pointer to X event to dispatch to relevant handler(s). It is important that all unused fields of the structure be set to zero. .BE .SH DESCRIPTION | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_HandleEvent \- invoke event handlers for window system events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_HandleEvent\fR(\fIeventPtr\fR) .fi .SH ARGUMENTS .AS XEvent *eventPtr .AP XEvent *eventPtr in Pointer to X event to dispatch to relevant handler(s). It is important that all unused fields of the structure be set to zero. .BE .SH DESCRIPTION |
︙ | ︙ |
Changes to doc/IdToWindow.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_IdToWindow \- Find Tk's window information for an X window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_IdToWindow\fR(\fIdisplay, window\fR) .SH ARGUMENTS .AS Tk_Window display .AP Display *display in X display containing the window. .AP Window window in X id for window. .BE | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_IdToWindow \- Find Tk's window information for an X window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_IdToWindow\fR(\fIdisplay, window\fR) .fi .SH ARGUMENTS .AS Tk_Window display .AP Display *display in X display containing the window. .AP Window window in X id for window. .BE |
︙ | ︙ |
Changes to doc/ImgChanged.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_ImageChanged \- notify widgets that image needs to be redrawn .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR) .SH ARGUMENTS .AS Tk_ImageModel imageHeight .AP Tk_ImageModel model in Token for image, which was passed to image's \fIcreateProc\fR when the image was created. .AP int x in X-coordinate of upper-left corner of region that needs redisplay (measured | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_ImageChanged \- notify widgets that image needs to be redrawn .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR) .fi .SH ARGUMENTS .AS Tk_ImageModel imageHeight .AP Tk_ImageModel model in Token for image, which was passed to image's \fIcreateProc\fR when the image was created. .AP int x in X-coordinate of upper-left corner of region that needs redisplay (measured |
︙ | ︙ |
Changes to doc/Inactive.3.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .SH NAME Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp long | | | > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp long \fBTk_GetUserInactiveTime\fR(\fIdisplay\fR) .sp \fBTk_ResetUserInactiveTime\fR(\fIdisplay\fR) .fi .SH ARGUMENTS .AS Display *display .AP Display *display in The display on which the user inactivity timer is to be queried or reset. .BE .SH DESCRIPTION |
︙ | ︙ |
Changes to doc/InternAtom.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Atom | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | .SH NAME Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Atom \fBTk_InternAtom\fR(\fItkwin, name\fR) .sp const char * \fBTk_GetAtomName\fR(\fItkwin, atom\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. Used to map atom or name relative to a particular display. .AP "const char" *name in String name for which atom is desired. .AP Atom atom in |
︙ | ︙ |
Changes to doc/MainLoop.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_MainLoop \- loop for events until all windows are deleted .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_MainLoop\fR() .BE .SH DESCRIPTION .PP \fBTk_MainLoop\fR is a procedure that loops repeatedly calling \fBTcl_DoOneEvent\fR. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most windowing applications will call \fBTk_MainLoop\fR after | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_MainLoop \- loop for events until all windows are deleted .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_MainLoop\fR() .fi .BE .SH DESCRIPTION .PP \fBTk_MainLoop\fR is a procedure that loops repeatedly calling \fBTcl_DoOneEvent\fR. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most windowing applications will call \fBTk_MainLoop\fR after |
︙ | ︙ |
Changes to doc/MainWin.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_MainWindow\fR(\fIinterp\fR) .sp | < < > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_MainWindow\fR(\fIinterp\fR) .sp \fBTk_SetMainMenubar\fR(\fIinterp, tkwin, menuName\fR) .sp \fBTk_SetWindowMenubar\fR(\fIinterp, tkwin, oldMenuName, menuName\fR) .sp int \fBTk_GetNumMainWindows\fR() .fi .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tcl_Interp *interp in/out Interpreter associated with the application. .AP Tk_Window tkwin in Token for main window. .AP const char *menuName in |
︙ | ︙ | |||
48 49 50 51 52 53 54 | associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and leaves an error message in interpreter \fIinterp\fR's result. .PP \fBTk_GetNumMainWindows\fR returns a count of the number of main windows currently open in the current thread. \fBTk_SetMainMenubar\fR Called when a toplevel widget is brought to front. On the Macintosh, | | | 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and leaves an error message in interpreter \fIinterp\fR's result. .PP \fBTk_GetNumMainWindows\fR returns a count of the number of main windows currently open in the current thread. \fBTk_SetMainMenubar\fR Called when a toplevel widget is brought to front. On the Macintosh, sets up the menubar that goes across the top of the main monitor. On other platforms, nothing is necessary. \fBTk_SetWindowMenubar\fR associates a menu with a window. The old menu clones for the menubar are thrown away, and a handler is set up to allocate the new ones. .SH KEYWORDS application, main window |
Changes to doc/MaintGeom.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR) .sp \fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR) .SH ARGUMENTS .AS Tk_Window container .AP Tk_Window window in Window whose geometry is to be controlled. .AP Tk_Window container in Window relative to which \fIwindow\fR's geometry will be controlled. .AP int x in | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR) .sp \fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR) .fi .SH ARGUMENTS .AS Tk_Window container .AP Tk_Window window in Window whose geometry is to be controlled. .AP Tk_Window container in Window relative to which \fIwindow\fR's geometry will be controlled. .AP int x in |
︙ | ︙ |
Changes to doc/ManageGeom.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_ManageGeometry \- arrange to handle geometry requests for a window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) .SH ARGUMENTS .AS Tk_GeometryProc clientData .AP Tk_Window tkwin in Token for window to be managed. .AP "const Tk_GeomMgr" *mgrPtr in Pointer to data structure containing information about the geometry manager, or NULL to indicate that \fItkwin\fR's geometry | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_ManageGeometry \- arrange to handle geometry requests for a window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) .fi .SH ARGUMENTS .AS Tk_GeometryProc clientData .AP Tk_Window tkwin in Token for window to be managed. .AP "const Tk_GeomMgr" *mgrPtr in Pointer to data structure containing information about the geometry manager, or NULL to indicate that \fItkwin\fR's geometry |
︙ | ︙ |
Changes to doc/MapWindow.3.
︙ | ︙ | |||
14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_MapWindow\fR(\fItkwin\fR) .sp \fBTk_UnmapWindow\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP | > | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_MapWindow\fR(\fItkwin\fR) .sp \fBTk_UnmapWindow\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP |
︙ | ︙ |
Changes to doc/MeasureChar.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .SH NAME Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int | | | | | | | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | .SH NAME Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_MeasureChars\fR(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fR) .sp int \fBTk_TextWidth\fR(\fItkfont, string, numBytes\fR) .sp \fBTk_DrawChars\fR(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fR) .sp \fBTk_UnderlineChars\fR(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fR) .fi .SH ARGUMENTS .AS "const char" firstChar .AP Tk_Font tkfont in Token for font in which text is to be drawn or measured. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP "const char" *string in Text to be measured or displayed. Need not be null terminated. Any |
︙ | ︙ | |||
44 45 46 47 48 49 50 | .AP int flags in Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character as long as any part of it fits in the length given by \fImaxPixels\fR; otherwise, a character must fit completely to be considered. \fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible. If \fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no characters could fit in the length given by \fImaxPixels\fR. If | | | | 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | .AP int flags in Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character as long as any part of it fits in the length given by \fImaxPixels\fR; otherwise, a character must fit completely to be considered. \fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible. If \fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no characters could fit in the length given by \fImaxPixels\fR. If \fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if not even one word fits on the line, return the first few letters of the word that did fit; if not even one letter of the word fit, then the first letter will still be returned. .AP int *lengthPtr out Filled with the number of pixels occupied by the number of characters returned as the result of \fBTk_MeasureChars\fR. .AP Display *display in Display on which to draw. |
︙ | ︙ |
Changes to doc/MoveToplev.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .BS .SH NAME Tk_MoveToplevelWindow \- Adjust the position of a top-level window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp | | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .BS .SH NAME Tk_MoveToplevelWindow \- Adjust the position of a top-level window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_MoveToplevelWindow\fR(\fItkwin, x, y\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for top-level window to move. .AP int x in New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the top-left pixel of the decorative border supplied for \fItkwin\fR by the |
︙ | ︙ |
Changes to doc/Name.3.
︙ | ︙ | |||
18 19 20 21 22 23 24 25 26 27 28 29 30 31 | \fBTk_Name\fR(\fItkwin\fR) .sp char * \fBTk_PathName\fR(\fItkwin\fR) .sp Tk_Window \fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tk_Window tkwin in Token for window. .AP Tcl_Interp *interp out Interpreter to use for error reporting. .AP "const char" *pathName in | > | 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | \fBTk_Name\fR(\fItkwin\fR) .sp char * \fBTk_PathName\fR(\fItkwin\fR) .sp Tk_Window \fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tk_Window tkwin in Token for window. .AP Tcl_Interp *interp out Interpreter to use for error reporting. .AP "const char" *pathName in |
︙ | ︙ |
Changes to doc/NameOfImg.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_NameOfImage \- Return name of image. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_NameOfImage\fR(\fIimageModel\fR) .SH ARGUMENTS .AS Tk_ImageModel imageModel .AP Tk_ImageModel imageModel in Token for image, which was passed to image manager's \fIcreateProc\fR when the image was created. .BE .SH DESCRIPTION | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_NameOfImage \- Return name of image. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_NameOfImage\fR(\fIimageModel\fR) .fi .SH ARGUMENTS .AS Tk_ImageModel imageModel .AP Tk_ImageModel imageModel in Token for image, which was passed to image manager's \fIcreateProc\fR when the image was created. .BE .SH DESCRIPTION |
︙ | ︙ |
Changes to doc/OwnSelect.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_OwnSelection \- make a window the owner of the primary selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) .SH ARGUMENTS .AS Tk_LostSelProc clientData .AP Tk_Window tkwin in Window that is to become new selection owner. .AP Atom selection in The name of the selection to be owned, such as XA_PRIMARY. .AP Tk_LostSelProc *proc in | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME Tk_OwnSelection \- make a window the owner of the primary selection .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) .fi .SH ARGUMENTS .AS Tk_LostSelProc clientData .AP Tk_Window tkwin in Window that is to become new selection owner. .AP Atom selection in The name of the selection to be owned, such as XA_PRIMARY. .AP Tk_LostSelProc *proc in |
︙ | ︙ |
Changes to doc/ParseArgv.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_ParseArgv \- process command-line options .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) .SH ARGUMENTS .AS Tk_ArgvInfo *argTable .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_ParseArgv \- process command-line options .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) .fi .SH ARGUMENTS .AS Tk_ArgvInfo *argTable .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed. |
︙ | ︙ | |||
109 110 111 112 113 114 115 | .QW "the matching argument" in the descriptions below. As part of the processing, \fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR after the matching argument, which is called .QW "the following argument" . The legal values for \fItype\fR, and the processing that they cause, are as follows: | < | < | < | < | < | < | < | < | < | < | < | < | | 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | .QW "the matching argument" in the descriptions below. As part of the processing, \fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR after the matching argument, which is called .QW "the following argument" . The legal values for \fItype\fR, and the processing that they cause, are as follows: .IP \fBTK_ARGV_END\fR Marks the end of the table. The last entry in \fIargTable\fR must have this type; all of its other fields are ignored and it will never match any arguments. .IP \fBTK_ARGV_CONSTANT\fR \fISrc\fR is treated as an integer and \fIdst\fR is treated as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. The matching argument is discarded. .IP \fBTK_ARGV_INT\fR The following argument must contain an integer string in the format accepted by \fBstrtol\fR (e.g. .QW 0 and .QW 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). \fIDst\fR is treated as a pointer to an integer; the following argument is converted to an integer value and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching and following arguments are discarded from \fIargv\fR. .IP \fBTK_ARGV_FLOAT\fR The following argument must contain a floating-point number in the format accepted by \fBstrtol\fR. \fIDst\fR is treated as the address of a double-precision floating point value; the following argument is converted to a double-precision value and stored at \fI*dst\fR. The matching and following arguments are discarded from \fIargv\fR. .IP \fBTK_ARGV_STRING\fR In this form, \fIdst\fR is treated as a pointer to a (char *); \fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following argument, and discards the matching and following arguments from \fIargv\fR. \fISrc\fR is ignored. .IP \fBTK_ARGV_UID\fR This form is similar to \fBTK_ARGV_STRING\fR, except that the argument is turned into a Tk_Uid by calling \fBTk_GetUid\fR. \fIDst\fR is treated as a pointer to a Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from \fIargv\fR. \fISrc\fR is ignored. .IP \fBTK_ARGV_CONST_OPTION\fR This form causes a Tk option to be set (as if the \fBoption\fR command had been invoked). The \fIsrc\fR field is treated as a pointer to a string giving the value of an option, and \fIdst\fR is treated as a pointer to the name of the option. The matching argument is discarded. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_OPTION_VALUE\fR This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the value of the option is taken from the following argument instead of from \fIsrc\fR. \fIDst\fR is used as the name of the option. \fISrc\fR is ignored. The matching and following arguments are discarded. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_OPTION_NAME_VALUE\fR In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both \fIsrc\fR and \fIdst\fR are ignored. All three arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_HELP\fR When this kind of option is encountered, \fBTk_ParseArgv\fR uses the \fIhelp\fR fields of \fIargTable\fR to format a message describing all the valid arguments. The message is placed in interpreter \fIinterp\fR's result and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the caller normally prints the help message and aborts. If the \fIkey\fR field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other \fBTK_ARGV_HELP\fR entry causes help information to be returned. .IP \fBTK_ARGV_REST\fR This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a \fBTK_ARGV_REST\fR argument is found, then \fBTk_ParseArgv\fR does not process any of the remaining arguments; it returns them all at the beginning of \fIargv\fR (along with any other unprocessed arguments). In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an integer value, and stores at \fI*dst\fR the index of the first of the \fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the program to distinguish the \fBTK_ARGV_REST\fR options from other unprocessed options that preceded the \fBTK_ARGV_REST\fR. .IP \fBTK_ARGV_FUNC\fR For this kind of argument, \fIsrc\fR is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure: .RS .CS int \fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) |
︙ | ︙ | |||
228 229 230 231 232 233 234 | (or NULL if there are not any more arguments left in \fIargv\fR). If \fIfunc\fR uses \fInextArg\fR (so that \fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it should return 0 and \fBTkParseArgv\fR will process the following argument in the normal fashion. In either event the matching argument is discarded. .RE | < | | 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | (or NULL if there are not any more arguments left in \fIargv\fR). If \fIfunc\fR uses \fInextArg\fR (so that \fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it should return 0 and \fBTkParseArgv\fR will process the following argument in the normal fashion. In either event the matching argument is discarded. .RE .IP \fBTK_ARGV_GENFUNC\fR This form provides a more general procedural escape. It treats \fIsrc\fR as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: .RS .CS int |
︙ | ︙ | |||
262 263 264 265 266 267 268 | \fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters an error then it should leave an error message in interpreter \fIinterp\fR's result, in the usual Tcl fashion, and return \-1; when this happens \fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. .RE .SS "FLAGS" | < | < | < | < | | 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 | \fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters an error then it should leave an error message in interpreter \fIinterp\fR's result, in the usual Tcl fashion, and return \-1; when this happens \fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. .RE .SS "FLAGS" .IP \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR \fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program or command name, and returns it to the caller just as if it had not matched \fIargTable\fR. If this flag is given, then \fIargv[0]\fR is not given special treatment. .IP \fBTK_ARGV_NO_ABBREV\fR Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for \fIkey\fR values in \fIargTable\fR. If this flag is given then only exact matches will be acceptable. .IP \fBTK_ARGV_NO_LEFTOVERS\fR Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR will return an error if it encounters any argument that does not match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, which will be returned to the caller with no errors as long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified. .IP \fBTK_ARGV_NO_DEFAULTS\fR Normally, \fBTk_ParseArgv\fR searches an internal table of standard argument specifiers in addition to \fIargTable\fR. If this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will use only \fIargTable\fR and not its default table. .SH EXAMPLE .PP Here is an example definition of an \fIargTable\fR and |
︙ | ︙ | |||
308 309 310 311 312 313 314 | char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { | | | | < < | | | | | 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 | char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { {"-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag, "Turn on debugging printfs"}, {"-N", TK_ARGV_INT, NULL, &numReps, "Number of repetitions"}, {"-of", TK_ARGV_STRING, NULL, &fileName, "Name of file for output"}, {"x", TK_ARGV_REST, NULL, &exec, "File to exec, followed by any arguments (must be last argument)."}, {NULL, TK_ARGV_END, NULL, NULL, NULL} }; int main(int argc, char *argv[]) { \&... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp))); exit(1); } /* * Remainder of the program. */ } .CE .PP Note that default values can be assigned to variables named in \fIargTable\fR: the variables will only be overwritten if the particular arguments are present in \fIargv\fR. Here are some example command lines and their effects. .CS prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps .CE In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, \fIargv\fR[0] will be .QW prog , \fIargv\fR[1] will be .QW infile , and \fIargv\fR[2] will be NULL. .SH KEYWORDS arguments, command line, options |
Changes to doc/QWinEvent.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .nf \fB#include <tk.h>\fR .sp int \fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) .sp \fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) .SH ARGUMENTS .AS Tcl_QueuePosition position .AP Display *display in Display for which to control motion event collapsing. .AP int collapse in Indicates whether motion events should be collapsed or not. .AP XEvent *eventPtr in | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .nf \fB#include <tk.h>\fR .sp int \fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) .sp \fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) .fi .SH ARGUMENTS .AS Tcl_QueuePosition position .AP Display *display in Display for which to control motion event collapsing. .AP int collapse in Indicates whether motion events should be collapsed or not. .AP XEvent *eventPtr in |
︙ | ︙ |
Changes to doc/Restack.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_RestackWindow \- Change a window's position in the stacking order .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) .SH ARGUMENTS .AS Tk_Window aboveBelow .AP Tk_Window tkwin in Token for window to restack. .AP int aboveBelow in Indicates new position of \fItkwin\fR relative to \fIother\fR; must be \fBAbove\fR or \fBBelow\fR. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_RestackWindow \- Change a window's position in the stacking order .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) .fi .SH ARGUMENTS .AS Tk_Window aboveBelow .AP Tk_Window tkwin in Token for window to restack. .AP int aboveBelow in Indicates new position of \fItkwin\fR relative to \fIother\fR; must be \fBAbove\fR or \fBBelow\fR. |
︙ | ︙ |
Changes to doc/RestrictEv.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_RestrictEvents \- filter and selectively delay X events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_RestrictProc * \fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) .SH ARGUMENTS .AS Tk_RestrictProc **prevArgPtr .AP Tk_RestrictProc *proc in Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. .AP void *arg in Arbitrary argument to pass to \fIproc\fR. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_RestrictEvents \- filter and selectively delay X events .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_RestrictProc * \fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) .fi .SH ARGUMENTS .AS Tk_RestrictProc **prevArgPtr .AP Tk_RestrictProc *proc in Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. .AP void *arg in Arbitrary argument to pass to \fIproc\fR. |
︙ | ︙ |
Changes to doc/SetAppName.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_SetAppName \- Set the name of an application for 'send' commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_SetAppName\fR(\fItkwin, name\fR) .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window in application. Used only to select a particular application. .AP "const char" *name in Name under which to register the application. | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_SetAppName \- Set the name of an application for 'send' commands .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_SetAppName\fR(\fItkwin, name\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window in application. Used only to select a particular application. .AP "const char" *name in Name under which to register the application. |
︙ | ︙ |
Changes to doc/SetCaret.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_SetCaretPos \- set the display caret location .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP int x in Window-relative x coordinate. .AP int y in Window-relative y coordinate. | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_SetCaretPos \- set the display caret location .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) .fi .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP int x in Window-relative x coordinate. .AP int y in Window-relative y coordinate. |
︙ | ︙ |
Changes to doc/SetClass.3.
︙ | ︙ | |||
14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .nf \fB#include <tk.h>\fR .sp \fBTk_SetClass\fR(\fItkwin, class\fR) .sp Tk_Uid \fBTk_Class\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .AP char *class in New class name for window. .BE | > | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | .nf \fB#include <tk.h>\fR .sp \fBTk_SetClass\fR(\fItkwin, class\fR) .sp Tk_Uid \fBTk_Class\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .AP char *class in New class name for window. .BE |
︙ | ︙ |
Changes to doc/SetClassProcs.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 17 18 19 20 21 22 23 | .SH NAME Tk_SetClassProcs \- register widget specific procedures .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) .SH ARGUMENTS .AS Tk_ClassProc instanceData .AP Tk_Window tkwin in Token for window to modify. .AP "const Tk_ClassProcs" *procs in Pointer to data structure containing widget specific procedures. The data structure pointed to by \fIprocs\fR must be static: | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME Tk_SetClassProcs \- register widget specific procedures .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) .fi .SH ARGUMENTS .AS Tk_ClassProc instanceData .AP Tk_Window tkwin in Token for window to modify. .AP "const Tk_ClassProcs" *procs in Pointer to data structure containing widget specific procedures. The data structure pointed to by \fIprocs\fR must be static: |
︙ | ︙ |
Changes to doc/SetGrid.3.
︙ | ︙ | |||
13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) .sp \fBTk_UnsetGrid\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tk_Window heightInc .AP Tk_Window tkwin in Token for window. .AP int reqWidth in Width in grid units that corresponds to the pixel dimension \fItkwin\fR has requested via \fBTk_GeometryRequest\fR. | > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) .sp \fBTk_UnsetGrid\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window heightInc .AP Tk_Window tkwin in Token for window. .AP int reqWidth in Width in grid units that corresponds to the pixel dimension \fItkwin\fR has requested via \fBTk_GeometryRequest\fR. |
︙ | ︙ |
Changes to doc/SetOptions.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .SH NAME Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions \- process configuration options .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_OptionTable | | | | | | | | | | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | .SH NAME Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions \- process configuration options .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_OptionTable \fBTk_CreateOptionTable\fR(\fIinterp, templatePtr\fR) .sp \fBTk_DeleteOptionTable\fR(\fIoptionTable\fR) .sp int \fBTk_InitOptions\fR(\fIinterp, recordPtr, optionTable, tkwin\fR) .sp int \fBTk_SetOptions\fR(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fR) .sp \fBTk_FreeSavedOptions\fR(\fIsavedPtr\fR) .sp \fBTk_RestoreSavedOptions\fR(\fIsavedPtr\fR) .sp Tcl_Obj * \fBTk_GetOptionValue\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp Tcl_Obj * \fBTk_GetOptionInfo\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp \fBTk_FreeConfigOptions\fR(\fIrecordPtr, optionTable, tkwin\fR) .fi .SH ARGUMENTS .AS Tk_SavedOptions "*const objv[]" in/out .AP Tcl_Interp *interp in A Tcl interpreter. Most procedures use this only for returning error messages; if it is NULL then no error messages are returned. For \fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the interpreter in which the option table will be used. |
︙ | ︙ | |||
94 95 96 97 98 99 100 | .QW widget will be used to refer to the object whose options are being managed; in practice the object may not actually be a widget. The term .QW "widget record" is used to refer to the C-level structure in which information about a particular widget or object is stored. .PP | | | 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | .QW widget will be used to refer to the object whose options are being managed; in practice the object may not actually be a widget. The term .QW "widget record" is used to refer to the C-level structure in which information about a particular widget or object is stored. .PP Note that the easiest way to learn how to use these procedures is to look at a working example. In Tk, the simplest example is the code that implements the button family of widgets, which is in \fBtkButton.c\fR. Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. .PP In order to use these procedures, the code that implements the widget must contain a static array of Tk_OptionSpec structures. This is a template that describes the various options supported by that class of |
︙ | ︙ | |||
297 298 299 300 301 302 303 | \fBTK_OPTION_INT\fR then the internal form is an integer. If the \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the value is not stored in that form. At least one of the offsets must be greater than or equal to zero. .PP The \fIflags\fR field consists of one or more bits ORed together. The following flags are supported: | < | < | < | < | | > | | | | | < | < | | | | < | < | < | < | < | < | < | < | | | < | | > | < | | > < | | | < | < | < | < | < | | 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 | \fBTK_OPTION_INT\fR then the internal form is an integer. If the \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the value is not stored in that form. At least one of the offsets must be greater than or equal to zero. .PP The \fIflags\fR field consists of one or more bits ORed together. The following flags are supported: .IP \fBTK_OPTION_NULL_OK\fR If this bit is set for an option then an empty string will be accepted as the value for the option and the resulting internal form will be a NULL pointer, a zero value, or \fBNone\fR, depending on the type of the option. If the flag is not set then empty strings will result in errors. \fBTK_OPTION_NULL_OK\fR is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to \fBNone\fR so that a window simply inherits its parent's cursor. Not all option types support the \fBTK_OPTION_NULL_OK\fR flag; for those that do, there is an explicit indication of that fact in the descriptions below. .IP \fBTK_OPTION_DONT_SET_DEFAULT\fR If this bit is set for an option then no default value will be set in \fBTk_InitOptions\fR for this option. Neither the option database, nor any system default value, nor \fIoptionTable\fR are used to give a default value to this option. Instead it is assumed that the caller has already supplied a default value in the widget code. .IP \fBTK_OPTION_ENUM_VAR\fR If this value is set for an option, then it indicates the the internalOffset points to an enum variable in stead of an int variable. Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR, \fBTK_OPTION_BOOLEAN\fR, \fBTK_OPTION_ANCHOR\fR, \fBTK_OPTION_JUSTIFY\fR, or \fBTK_OPTION_ANCHOR\fR. .IP \fBTK_OPTION_VAR(\fItype\fB)\fR If this value is set for an option, then it indicates the the internalOffset points to a \fItype\fR variable in stead of an int variable. Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR or \fBTK_OPTION_BOOLEAN\fR, or as \fBTK_OPTION_VAR(int)\fR with \fBTK_OPTION_INT\fR .RS .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The legal value for \fItype\fR, and the corresponding actions, are described below. If the type requires a \fItkwin\fR value to be passed into procedures like \fBTk_SetOptions\fR, or if it uses the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated explicitly; if not mentioned, the type requires neither \fItkwin\fR nor \fIclientData\fR. .RE .IP \fBTK_OPTION_ANCHOR\fR The value must be a standard anchor position such as \fBne\fR or \fBcenter\fR. The internal form is a Tk_Anchor value like the ones returned by \fBTk_GetAnchorFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if the empty string is specified as the value for the option, the integer relief value is set to \fBTK_ANCHOR_NULL\fR. .IP \fBTK_OPTION_BITMAP\fR The value must be a standard Tk bitmap name. The internal form is a Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_BOOLEAN\fR The value must be a standard boolean value such as \fBtrue\fR or \fBno\fR. The internal form is an integer with value 0 or 1. Note that if the \fIobjOffset\fR field is not used, information about the original value of this option will be lost. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to -1. .IP \fBTK_OPTION_BORDER\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is a Tk_3DBorder token like the ones returned by \fBTk_Alloc3DBorderFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_COLOR\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is an (XColor *) token like the ones returned by \fBTk_AllocColorFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_CURSOR\fR The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. The internal form is a Tk_Cursor token like the ones returned by \fBTk_AllocCursorFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and when the option is set the cursor for the window is changed by calling \fBXDefineCursor\fR. This option type also supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_CUSTOM\fR This option allows applications to define new option types. The clientData field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. .IP \fBTK_OPTION_DOUBLE\fR The string value must be a floating-point number in the format accepted by \fBstrtol\fR. The internal form is a C \fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to NaN. .IP \fBTK_OPTION_END\fR Marks the end of the template. There must be a Tk_OptionSpec structure with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the \fIclientData\fR field of this structure is not NULL, then it points to an additional array of Tk_OptionSpec's, which is itself terminated by another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily deeply. This feature allows common options to be shared by several widget classes. .IP \fBTK_OPTION_FONT\fR The value must be a standard font name such as \fBTimes 16\fR. The internal form is a Tk_Font handle like the ones returned by \fBTk_AllocFontFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_INT\fR The string value must be an integer in the format accepted by \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to specify octal or hexadecimal numbers, respectively). The internal form is a C \fBint\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_INDEX\fR The string value must be an index in the format accepted by \fBTcl_GetIntForIndex()\fR or the empty string. The internal form is a C \fBint\fR value. If the string starts with \fB\-\fR, the internal representation will be set to INT_MIN. If the string has the form \fBend-???\fR, then the result will be a negative number: \fB-1\fR stands for \fBend\fR, \fB-2\fR stands for \fBend-1\fR and so on. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_JUSTIFY\fR The value must be a standard justification value such as \fBleft\fR. The internal form is a Tk_Justify like the values returned by \fBTk_GetJustifyFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if the empty string is specified as the value for the option, the integer relief value is set to \fBTK_JUSTIFY_NULL\fR. .IP \fBTK_OPTION_PIXELS\fR The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. The internal form is an integer value giving a distance in pixels, like the values returned by \fBTk_GetPixelsFromObj\fR. Note that if the \fIobjOffset\fR field is not used, information about the original value of this option will be lost. See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_RELIEF\fR The value must be standard relief such as \fBraised\fR. The internal form is an integer relief value such as \fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to \fBTK_RELIEF_NULL\fR. .IP \fBTK_OPTION_STRING\fR The value may be any string. The internal form is a (char *) pointer that points to a dynamically allocated copy of the value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_STRING_TABLE\fR For this type, \fIclientData\fR is a pointer to an array of strings suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must be one of the strings in the table, or a unique abbreviation of one of the strings. The internal form is an integer giving the index into the table of the matching string, like the return value from \fBTcl_GetStringFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to -1. .IP \fBTK_OPTION_SYNONYM\fR This type is used to provide alternative names for an option (for example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). The \fBclientData\fR field is a string that gives the name of another option in the same table. Whenever the synonym option is used, the information from the other option will be used instead. .IP \fBTK_OPTION_WINDOW\fR The value must be a window path name. The internal form is a \fBTk_Window\fR token for the window. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR (in order to identify the application), and it supports the \fBTK_OPTION_NULL_OK\fR flag. .SH "STORAGE MANAGEMENT ISSUES" .PP |
︙ | ︙ | |||
523 524 525 526 527 528 529 | the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options it is better to use the \fIobjOffset\fR field. In this case the original value of the option is retained in the object and can be returned when the option is retrieved. In most cases it is convenient to use the \fIinternalOffset\fR field as well, so that the integer value is immediately available for use in the widget code (alternatively, \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from | | | | 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 | the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options it is better to use the \fIobjOffset\fR field. In this case the original value of the option is retained in the object and can be returned when the option is retrieved. In most cases it is convenient to use the \fIinternalOffset\fR field as well, so that the integer value is immediately available for use in the widget code (alternatively, \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from the object whenever it is needed). Note that the problem of losing information on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. .PP The second reason to use the \fIobjOffset\fR field is in order to implement new types of options not supported by these procedures. To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field but not the \fIinternalOffset\fR field. Then, after calling \fBTk_SetOptions\fR, convert the object to internal form yourself. |
︙ | ︙ | |||
593 594 595 596 597 598 599 | may be NULL, indicating that no function should be called for those operations. .PP The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are: .RS | < | < | < | < | < | < | < | < | | 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 | may be NULL, indicating that no function should be called for those operations. .PP The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are: .RS .IP \fIclientData\fR A copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. .IP \fIinterp\fR A pointer to a Tcl interpreter, used for error reporting. .IP \fITkwin\fR A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR .IP \fIvaluePtr\fR A pointer to a reference to a Tcl_Obj describing the new value for the option; it could have been specified explicitly in the call to \fBTk_SetOptions\fR or it could come from the option database or a default. If the objOffset for the option is non-negative (the option value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj pointer referenced by \fIvaluePtr\fR is the pointer that will be stored at the objOffset for the option. \fISetProc\fR may modify the value if necessary; for example, \fIsetProc\fR may change the value to NULL to support the \fBTK_OPTION_NULL_OK\fR flag. .IP \fIrecordPtr\fR A pointer to the start of the widget record to modify. .IP \fIinternalOffset\fR Offset in bytes from the start of the widget record to the location where the internal representation of the option value is to be placed. .IP \fIsaveInternalPtr\fR A pointer to storage allocated in a Tk_SavedOptions structure for the internal representation of the original option value. Before setting the option to its new value, \fIsetProc\fR should set the value referenced by \fIsaveInternalPtr\fR to the original value of the option in order to support \fBTk_RestoreSavedOptions\fR. .IP \fIflags\fR A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the option .RE .PP \fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error message may be left in the Tcl interpreter given by \fIinterp\fR in |
︙ | ︙ |
Changes to doc/SetVisual.3.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_SetWindowVisual \- change visual characteristics of window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) .SH ARGUMENTS .AS "Tk_Window int" colormap .AP Tk_Window tkwin in Token for window. .AP Visual *visual in New visual type to use for \fItkwin\fR. .AP "int" depth in | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Tk_SetWindowVisual \- change visual characteristics of window .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) .fi .SH ARGUMENTS .AS "Tk_Window int" colormap .AP Tk_Window tkwin in Token for window. .AP Visual *visual in New visual type to use for \fItkwin\fR. .AP "int" depth in |
︙ | ︙ | |||
39 40 41 42 43 44 45 | The safest thing is to call \fBTk_SetWindowVisual\fR immediately after calling \fBTk_CreateWindow\fR. If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR is called then it returns 0 and does not make any changes; otherwise it returns 1 to signify that the operation completed successfully. .PP | | | 40 41 42 43 44 45 46 47 48 49 50 51 | The safest thing is to call \fBTk_SetWindowVisual\fR immediately after calling \fBTk_CreateWindow\fR. If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR is called then it returns 0 and does not make any changes; otherwise it returns 1 to signify that the operation completed successfully. .PP Note that \fBTk_SetWindowVisual\fR should not be called if you just want to change a window's colormap without changing its visual or depth; call \fBTk_SetWindowColormap\fR instead. .SH KEYWORDS colormap, depth, visual |
Changes to doc/StrictMotif.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_StrictMotif \- Return value of tk_strictMotif variable .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_StrictMotif\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_StrictMotif \- Return value of tk_strictMotif variable .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp int \fBTk_StrictMotif\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP |
︙ | ︙ |
Changes to doc/TextLayout.3.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .SH NAME Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_TextLayout | | < | < | < | | | | | < | > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | .SH NAME Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_TextLayout \fBTk_ComputeTextLayout\fR(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fR) .sp \fBTk_FreeTextLayout\fR(\fIlayout\fR) .sp \fBTk_DrawTextLayout\fR(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fR) .sp \fBTk_UnderlineTextLayout\fR(\fIdisplay, drawable, gc, layout, x, y, underline\fR) .sp int \fBTk_PointToChar\fR(\fIlayout, x, y\fR) .sp int \fBTk_CharBbox\fR(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fR) .sp int \fBTk_DistanceToTextLayout\fR(\fIlayout, x, y\fR) .sp int \fBTk_IntersectTextLayout\fR(\fIlayout, x, y, width, height\fR) .sp \fBTk_TextLayoutToPostscript\fR(\fIinterp, layout\fR) .fi .SH ARGUMENTS .AS Tk_TextLayout "*xPtr, *yPtr" .AP Tk_Font tkfont in Font to use when constructing and displaying a text layout. The \fItkfont\fR must remain valid for the lifetime of the text layout. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP "const char" *string in |
︙ | ︙ |
Changes to doc/TkInitStubs.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 18 19 20 21 22 23 24 | Tk_InitStubs \- initialize the Tk stubs mechanism .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_InitStubs\fR(\fIinterp, version, exact\fR) .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Tcl interpreter handle. .AP char *version in A version string consisting of one or more decimal numbers separated by dots. | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Tk_InitStubs \- initialize the Tk stubs mechanism .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp const char * \fBTk_InitStubs\fR(\fIinterp, version, exact\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Tcl interpreter handle. .AP char *version in A version string consisting of one or more decimal numbers separated by dots. |
︙ | ︙ |
Changes to doc/Tk_Init.3.
︙ | ︙ | |||
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 | its command-line arguments). .PP \fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes all Tk commands that are considered unsafe. Those commands and the reasons for their exclusion are: .TP \fBbell\fR Continuous ringing of the bell is a nuisance. .TP \fBclipboard\fR A malicious script could replace the contents of the clipboard with the string .QW "\fBrm \-r *\fR" and lead to surprises when the contents of the clipboard are pasted. .TP \fBgrab\fR Grab can be used to block the user from using any other applications. .TP \fBmenu\fR Menus can be used to cover the entire screen and to steal input from the user. .TP \fBselection\fR See clipboard. .TP \fBsend\fR Send can be used to cause unsafe interpreters to execute commands. .TP \fBtk\fR The tk command recreates the send command, which is unsafe. .TP \fBtkwait\fR Tkwait can block the containing process forever .TP \fBtoplevel\fR Toplevels can be used to cover the entire screen and to steal input from the user. .TP \fBwm\fR If toplevels are ever allowed, wm can be used to remove decorations, move windows around, etc. .SH KEYWORDS safe, application, initialization, load, main window | > > > > > > > > > > | 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | its command-line arguments). .PP \fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes all Tk commands that are considered unsafe. Those commands and the reasons for their exclusion are: .TP \fBbell\fR . Continuous ringing of the bell is a nuisance. .TP \fBclipboard\fR . A malicious script could replace the contents of the clipboard with the string .QW "\fBrm \-r *\fR" and lead to surprises when the contents of the clipboard are pasted. .TP \fBgrab\fR . Grab can be used to block the user from using any other applications. .TP \fBmenu\fR . Menus can be used to cover the entire screen and to steal input from the user. .TP \fBselection\fR . See clipboard. .TP \fBsend\fR . Send can be used to cause unsafe interpreters to execute commands. .TP \fBtk\fR . The tk command recreates the send command, which is unsafe. .TP \fBtkwait\fR . Tkwait can block the containing process forever .TP \fBtoplevel\fR . Toplevels can be used to cover the entire screen and to steal input from the user. .TP \fBwm\fR . If toplevels are ever allowed, wm can be used to remove decorations, move windows around, etc. .SH KEYWORDS safe, application, initialization, load, main window |
Changes to doc/WinUtil.3.
︙ | ︙ | |||
11 12 13 14 15 16 17 | .SH NAME Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window | | | | | > | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | .SH NAME Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp Tk_Window \fBTk_GetOtherWindow\fR(\fItkwin\fR) .sp \fBTk_MakeContainer\fR(\fItkwin\fR) .sp \fBTk_MakeWindow\fR(\fItkwin, parent\fR) .sp int \fBTk_UseWindow\fR(\fIinterp, tkwin, string\fR) .fi .SH ARGUMENTS .AS XSetWindowAttributes borderWidth .AP Tcl_Interp * interp in Interpreter associated with the application. .AP Tk_Window tkwin in Token for window. .AP Window parent in |
︙ | ︙ |
Changes to doc/WindowId.3.
︙ | ︙ | |||
99 100 101 102 103 104 105 106 107 108 109 110 111 112 | \fBTk_Colormap\fR(\fItkwin\fR) .sp Tcl_Interp * \fBTk_Interp\fR(\fItkwin\fR) .sp Tcl_Obj * \fBTk_NewWindowObj\fR(\fItkwin\fR) .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP | > | 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | \fBTk_Colormap\fR(\fItkwin\fR) .sp Tcl_Interp * \fBTk_Interp\fR(\fItkwin\fR) .sp Tcl_Obj * \fBTk_NewWindowObj\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP |
︙ | ︙ | |||
143 144 145 146 147 148 149 | The width and height information refers to the interior size of the window, not including any border. \fBTk_Changes\fR returns a pointer to a structure containing all of the above information plus a few other fields. \fBTk_Attributes\fR returns a pointer to an XSetWindowAttributes structure describing all of the attributes of the \fItkwin\fR's window, such as background pixmap, event mask, and so on (Tk keeps track of all this information | | | 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 | The width and height information refers to the interior size of the window, not including any border. \fBTk_Changes\fR returns a pointer to a structure containing all of the above information plus a few other fields. \fBTk_Attributes\fR returns a pointer to an XSetWindowAttributes structure describing all of the attributes of the \fItkwin\fR's window, such as background pixmap, event mask, and so on (Tk keeps track of all this information as it is changed by the application). Note that it is essential that applications use Tk procedures like \fBTk_ResizeWindow\fR instead of X procedures like \fBXResizeWindow\fR, so that Tk can keep its data structures up-to-date. .PP \fBTk_IsContainer\fR returns a non-zero value if \fItkwin\fR is a container, and that some other application may be embedding itself inside \fItkwin\fR. |
︙ | ︙ |
Changes to doc/bind.n.
︙ | ︙ | |||
145 146 147 148 149 150 151 | times, and also place a time and space requirement on the sequence: for a sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, \fB<Double\-Button\-1>\fR is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space requirement. .PP | | > | | 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | times, and also place a time and space requirement on the sequence: for a sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, \fB<Double\-Button\-1>\fR is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space requirement. .PP The \fBCommand\fR, \fBOption\fR, \fBNum\fR and \fBFn\fRmodifiers are equivalents of \fBMod1\fR up to \fBMod4\fR; they correspond to Macintosh-specific modifier keys. .PP The \fBExtended\fR modifier is, at present, specific to Windows. It appears on events that are associated with the keys on the .QW "extended keyboard" . On a US keyboard, the extended keys include the \fBAlt\fR and \fBControl\fR keys at the right of the keyboard, the cursor keys in the cluster to the left of the numeric pad, the \fBNumLock\fR key, |
︙ | ︙ | |||
645 646 647 648 649 650 651 | appended scripts, is terminated but Tk will continue processing binding scripts associated with other \fItag\fR's. If the \fBbreak\fR command is invoked within a binding script, then that script terminates and no other scripts will be invoked for the event. .PP Within a script called from the binding script, \fBreturn\fR | | | | 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 | appended scripts, is terminated but Tk will continue processing binding scripts associated with other \fItag\fR's. If the \fBbreak\fR command is invoked within a binding script, then that script terminates and no other scripts will be invoked for the event. .PP Within a script called from the binding script, \fBreturn\fR \fB\-code ok\fR may be used to continue processing (including .QW + appended scripts), or \fBreturn\fR \fB\-code break\fR may be used to stop processing all other binding scripts. .PP If more than one binding matches a particular event and they have the same \fItag\fR, then the most specific binding is chosen and its script is evaluated. The following tests are applied, in order, to determine which of several matching sequences is more specific: |
︙ | ︙ | |||
735 736 737 738 739 740 741 | The \fBbgerror\fR command will be executed at global level (outside the context of any Tcl procedure). .SH "EXAMPLES" .PP Arrange for a string describing the motion of the mouse to be printed out when the mouse is double-clicked: .CS | | | | 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 | The \fBbgerror\fR command will be executed at global level (outside the context of any Tcl procedure). .SH "EXAMPLES" .PP Arrange for a string describing the motion of the mouse to be printed out when the mouse is double-clicked: .CS \fBbind\fR . <Double-1> { puts "hi from (%x,%y)" } .CE .PP A little GUI that displays what the keysym name of the last key pressed is: .CS set keysym "Press any key" pack [label .l -textvariable keysym -padx 2m -pady 1m] \fBbind\fR . <Key> { set keysym "You pressed %K" } .CE .SH "SEE ALSO" bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n) .SH KEYWORDS binding, event '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/bitmap.n.
︙ | ︙ | |||
11 12 13 14 15 16 17 | '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bitmap \- Images that display two colors .SH SYNOPSIS .nf \fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? | | | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bitmap \- Images that display two colors .SH SYNOPSIS .nf \fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? \fIimageName \fBcget\fI option\fR \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? .fi .BE .SH DESCRIPTION .PP A bitmap is an image whose pixels can display either of two colors or be transparent. |
︙ | ︙ | |||
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | the source data is one and the background color if the source data is zero. .SH "CREATING BITMAPS" .PP Like all images, bitmaps are created using the \fBimage create\fR command. Bitmaps support the following \fIoptions\fR: .TP \fB\-background \fIcolor\fR . Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any \fB\-maskdata\fR or \fB\-maskfile\fR options. .TP \fB\-data \fIstring\fR . Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-data\fR option takes precedence. .TP \fB\-file \fIname\fR . \fIname\fR gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .TP \fB\-foreground \fIcolor\fR . Specifies a foreground color for the image in any of the standard ways accepted by Tk. .TP \fB\-maskdata \fIstring\fR . Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, the \fB\-maskdata\fR option takes precedence. .TP \fB\-maskfile \fIname\fR . \fIname\fR gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .SH "IMAGE COMMAND" .PP When a bitmap image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: .CS \fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for bitmap images: .TP | > > > > > > > | > | 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | the source data is one and the background color if the source data is zero. .SH "CREATING BITMAPS" .PP Like all images, bitmaps are created using the \fBimage create\fR command. Bitmaps support the following \fIoptions\fR: .\" OPTION: -background .TP \fB\-background \fIcolor\fR . Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any \fB\-maskdata\fR or \fB\-maskfile\fR options. .\" OPTION: -data .TP \fB\-data \fIstring\fR . Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-data\fR option takes precedence. .\" OPTION: -file .TP \fB\-file \fIname\fR . \fIname\fR gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . Specifies a foreground color for the image in any of the standard ways accepted by Tk. .\" OPTION: -maskdata .TP \fB\-maskdata \fIstring\fR . Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, the \fB\-maskdata\fR option takes precedence. .\" OPTION: -maskfile .TP \fB\-maskfile \fIname\fR . \fIname\fR gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .SH "IMAGE COMMAND" .PP When a bitmap image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: .CS \fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for bitmap images: .\" METHOD: cget .TP \fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBbitmap\fR command. .\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified |
︙ | ︙ |
Changes to doc/busy.n.
︙ | ︙ | |||
26 27 28 29 30 31 32 | .TH busy n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS | > | < < | < < | < < > | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | .TH busy n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS .nf \fBtk busy\fI window \fR?\fIoptions\fR? \fBtk busy busywindow \fIwindow\fR \fBtk busy hold\fI window \fR?\fIoptions\fR? \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... \fBtk busy forget\fI window \fR?\fIwindow \fR?... \fBtk busy current\fR ?\fIpattern\fR? \fBtk busy status \fIwindow\fR .fi .BE .SH DESCRIPTION .PP The \fBtk busy\fR command provides a simple means to block mouse pointer events from Tk widgets, while overriding the widget's cursor with a configurable busy cursor. Note this command does not prevent keyboard events from being sent to the widgets made busy. |
︙ | ︙ | |||
112 113 114 115 116 117 118 | \fBtk busy\fR forget .top .CE .PP The busy window has a configurable cursor. You can change the busy cursor using the \fBconfigure\fR operation. .PP .CS | | > > | > | 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | \fBtk busy\fR forget .top .CE .PP The busy window has a configurable cursor. You can change the busy cursor using the \fBconfigure\fR operation. .PP .CS \fBtk busy\fR configure .top -cursor "watch" .CE .PP Destroying the widget will also clean up any resources allocated by the \fBtk busy\fR command. .PP .SH OPERATIONS .PP The following operations are available for the \fBtk busy\fR command: .TP \fBtk busy \fIwindow\fR ?\fIoption value\fR?... . Shortcut for \fBtk busy hold\fR command. .\" METHOD: busywindow .TP \fBtk busy busywindow \fIwindow\fR . Returns the pathname of the busy window (i.e. the transparent window shielding the window appearing busy) created by the \fBtk busy hold\fR command for \fIwindow\fR, or the empty string if \fIwindow\fR is not busy. .\" METHOD: cget .TP \fBtk busy cget \fIwindow option\fR . Queries the \fBtk busy\fR command configuration options for \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made busy by the \fBhold\fR operation. The command returns the present value of the specified \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBhold\fR operation. .\" METHOD: configure .TP \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... . Queries or modifies the \fBtk busy\fR command configuration options for \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made busy by the \fBhold\fR operation. If no options are specified, a list describing all of the available options for \fIwindow\fR (see |
︙ | ︙ | |||
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | specified for it by either \fBoption\fR command: .PP .CS option add *frame.busyCursor gumby option add *Frame.BusyCursor gumby .CE .RE .TP \fBtk busy current \fR?\fIpattern\fR? . Returns the pathnames of all widgets that are currently busy. If a \fIpattern\fR is given, only the path names of busy widgets matching \fIpattern\fR are returned. .TP \fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... . Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR, including the transparent window. User events will again be received by \fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. \fIWindow\fR must be the name of a widget specified in the \fBhold\fR operation, otherwise an error is reported. .TP \fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... . Makes the specified \fIwindow\fR (and its descendants in the Tk window hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. A transparent window is put in front of the specified window. This transparent window is mapped the next time idle tasks are processed, and the specified window and its descendants will be blocked from user interactions. Normally \fBupdate\fR should be called immediately afterward to insure that the hold operation is in effect before the application starts its processing. The command returns the pathname of the busy window that was created (i.e. the transparent window shielding the window appearing busy). The following configuration options are valid: .RS .TP \fB\-cursor \fIcursorName\fR . Specifies the cursor to be displayed when the widget is made busy. \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. .RE .TP \fBtk busy status \fIwindow\fR . Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not receive user interactions, \fB1\fR is returned, otherwise \fB0\fR. .SH "EVENT HANDLING" .SS BINDINGS | > > > > > | 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | specified for it by either \fBoption\fR command: .PP .CS option add *frame.busyCursor gumby option add *Frame.BusyCursor gumby .CE .RE .\" METHOD: current .TP \fBtk busy current \fR?\fIpattern\fR? . Returns the pathnames of all widgets that are currently busy. If a \fIpattern\fR is given, only the path names of busy widgets matching \fIpattern\fR are returned. .\" METHOD: forget .TP \fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... . Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR, including the transparent window. User events will again be received by \fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. \fIWindow\fR must be the name of a widget specified in the \fBhold\fR operation, otherwise an error is reported. .\" METHOD: hold .TP \fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... . Makes the specified \fIwindow\fR (and its descendants in the Tk window hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. A transparent window is put in front of the specified window. This transparent window is mapped the next time idle tasks are processed, and the specified window and its descendants will be blocked from user interactions. Normally \fBupdate\fR should be called immediately afterward to insure that the hold operation is in effect before the application starts its processing. The command returns the pathname of the busy window that was created (i.e. the transparent window shielding the window appearing busy). The following configuration options are valid: .RS .\" OPTION: -cursor .TP \fB\-cursor \fIcursorName\fR . Specifies the cursor to be displayed when the widget is made busy. \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. .RE .\" METHOD: status .TP \fBtk busy status \fIwindow\fR . Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not receive user interactions, \fB1\fR is returned, otherwise \fB0\fR. .SH "EVENT HANDLING" .SS BINDINGS |
︙ | ︙ |
Changes to doc/button.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH button n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME button \- Create and manipulate 'button' action widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH button n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME button \- Create and manipulate 'button' action widgets .SH SYNOPSIS \fBbutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-font \-relief \-activeforeground \-foreground \-repeatdelay \-anchor \-highlightbackground \-repeatinterval \-background \-highlightcolor \-takefocus \-bitmap \-highlightthickness \-text \-borderwidth \-image \-textvariable |
︙ | ︙ | |||
110 111 112 113 114 115 116 117 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for button widgets: .TP | > | > > > > > > > | 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for button widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flash the button. This is accomplished by redisplaying the button several times, alternating between the configured activebackground and background colors. At the end of the flash the button is left in the same normal/active state as when the command was invoked. This command is ignored if the button's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Invoke the Tcl command associated with the button, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the button. This command is ignored if the button's state is \fBdisabled\fR. .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for buttons that give them |
︙ | ︙ | |||
184 185 186 187 188 189 190 | .SH EXAMPLES .PP This is the classic Tk .QW "Hello, World!" demonstration: .PP .CS | | | | | | | 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | .SH EXAMPLES .PP This is the classic Tk .QW "Hello, World!" demonstration: .PP .CS \fBbutton\fR .b -text "Hello, World!" -command exit pack .b .CE .PP This example demonstrates how to handle button accelerators: .PP .CS \fBbutton\fR .b1 -text Hello -underline 0 \fBbutton\fR .b2 -text World -underline 0 bind . <Key-h> {.b1 flash; .b1 invoke} bind . <Key-w> {.b2 flash; .b2 invoke} pack .b1 .b2 .CE .SH "SEE ALSO" ttk::button(n) .SH KEYWORDS button, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/canvas.n.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .TH canvas n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets .SH SYNOPSIS | | | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | .TH canvas n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets .SH SYNOPSIS \fBcanvas\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-highlightbackground \-highlightcolor \-highlightthickness \-insertbackground \-insertborderwidth \-insertofftime \-insertontime \-insertwidth \-relief \-selectbackground \-selectborderwidth \-selectforeground \-takefocus \-xscrollcommand \-yscrollcommand |
︙ | ︙ | |||
252 253 254 255 256 257 258 | support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. | < | < < | < < | < < | < < | < < | < | 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. .IP \fInumber\fR 10 A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater than the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. .IP \fBend\fR 10 Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item). .IP \fBinsert\fR 10 Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. .IP \fBsel.first\fR 10 Refers to the first selected character in the item. If the selection is not in this item then this form is illegal. .IP \fBsel.last\fR 10 Refers to the last selected character in the item. If the selection is not in this item then this form is illegal. .IP \fB@\fIx,y\fR 10 Refers to the character or coordinate at the point given by \fIx\fR and \fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate system of the canvas. If \fIx\fR and \fIy\fR lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. .SH "DASH PATTERNS" |
︙ | ︙ | |||
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following widget commands are possible for canvas widgets: .TP \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR? . For each item that meets the constraints specified by \fIsearchSpec\fR and the \fIarg\fRs, add \fItag\fR to the list of tags associated with the item if it is not already present on that list. It is possible that no items will satisfy the constraints given by \fIsearchSpec\fR and \fIarg\fRs, in which case the command has no effect. This command returns an empty string as result. \fISearchSpec\fR and \fIarg\fR's may take any of the following forms: .RS | > < | < < | < < | < < | < < | < < | < < | < > > | 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following widget commands are possible for canvas widgets: .\" METHOD: addtag .TP \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR? . For each item that meets the constraints specified by \fIsearchSpec\fR and the \fIarg\fRs, add \fItag\fR to the list of tags associated with the item if it is not already present on that list. It is possible that no items will satisfy the constraints given by \fIsearchSpec\fR and \fIarg\fRs, in which case the command has no effect. This command returns an empty string as result. \fISearchSpec\fR and \fIarg\fR's may take any of the following forms: .RS .IP "\fBabove \fItagOrId\fR" Selects the item just after (above) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the last (topmost) of these items in the display list is used. .IP \fBall\fR Selects all the items in the canvas. .IP "\fBbelow \fItagOrId\fR" Selects the item just before (below) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the first (lowest) of these items in the display list is used. .IP "\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?" Selects the item closest to the point given by \fIx\fR and \fIy\fR. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If \fIhalo\fR is specified, then it must be a non-negative value. Any item closer than \fIhalo\fR to the point is considered to overlap it. The \fIstart\fR argument may be used to step circularly through all the closest items. If \fIstart\fR is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below \fIstart\fR in the display list; if no such item exists, then the selection behaves as if the \fIstart\fR argument had not been specified. .IP "\fBenclosed\fI x1 y1 x2 y2\fR" Selects all the items completely enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .IP "\fBoverlapping\fI x1 y1 x2 y2\fR" Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .IP "\fBwithtag \fItagOrId\fR" Selects all the items given by \fItagOrId\fR. .RE .\" METHOD: bbox .TP \fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? . Returns a list with four elements giving an approximate bounding box for all the items named by the \fItagOrId\fR arguments. The list has the form .QW "\fIx1 y1 x2 y2\fR" such that the drawn areas of all the named elements are within the region bounded by \fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top, and \fIy2\fR on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the \fItagOrId\fR arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. .\" METHOD: bind .TP \fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? . This command associates \fIcommand\fR with all the items given by \fItagOrId\fR such that whenever the event sequence given by \fIsequence\fR occurs for one of the items the command will be invoked. |
︙ | ︙ | |||
499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 | .PP If bindings have been created for a canvas window using the \fBbind\fR command, then they are invoked in addition to bindings created for the canvas's items using the \fBbind\fR widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. .RE .TP \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? . Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns the canvas x-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .TP \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? . Given a window y-coordinate in the canvas \fIscreeny\fR this command returns the canvas y-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .TP | > > > | > > | | > > > > > > | 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 | .PP If bindings have been created for a canvas window using the \fBbind\fR command, then they are invoked in addition to bindings created for the canvas's items using the \fBbind\fR widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. .RE .\" METHOD: canvasx .TP \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? . Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns the canvas x-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .\" METHOD: canvasy .TP \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? . Given a window y-coordinate in the canvas \fIscreeny\fR this command returns the canvas y-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. .\" METHOD: coords .TP \fIpathName \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? .TP \fIpathName \fBcoords \fItagOrId \fR?\fIcoordList\fR? . Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list whose elements are the coordinates of the item named by \fItagOrId\fR. If coordinates are specified, then they replace the current coordinates for the named item. If \fItagOrId\fR refers to multiple items, then the first one in the display list is used. .RS .PP Note that for rectangles, ovals and arcs the returned list of coordinates has a fixed order, namely the left, top, right and bottom coordinates, which may not be the order originally given. Also the coordinates are always returned in screen units with no units (that is, in pixels). So if the original coordinates were specified for instance in centimeters or inches, the returned values will nevertheless be in pixels. .RE .\" METHOD: create .TP \fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? .TP \fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR? . Create a new item in \fIpathName\fR of type \fItype\fR. The exact format of the arguments after \fItype\fR depends on \fItype\fR, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. .\" METHOD: dchars .TP \fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? . For each item given by \fItagOrId\fR, delete the characters, or coordinates, in the range given by \fIfirst\fR and \fIlast\fR, inclusive. If some of the items given by \fItagOrId\fR do not support indexing operations then they ignore this operation. Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in \fBINDICES\fR above. If \fIlast\fR is omitted, it defaults to \fIfirst\fR. This command returns an empty string. .\" METHOD: delete .TP \fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? . Delete each of the items given by each \fItagOrId\fR, and return an empty string. .\" METHOD: dtag .TP \fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? . For each of the items given by \fItagOrId\fR, delete the tag given by \fItagToDelete\fR from the list of those associated with the item. If an item does not have the tag \fItagToDelete\fR then the item is unaffected by the command. If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. This command returns an empty string. .\" METHOD: find .TP \fIpathName \fBfind \fIsearchCommand \fR?\fIarg ...\fR? . This command returns a list consisting of all the items that meet the constraints specified by \fIsearchCommand\fR and \fIarg\fR's. \fISearchCommand\fR and \fIargs\fR have any of the forms accepted by the \fBaddtag\fR command. The items are returned in stacking order, with the lowest item first. .\" METHOD: focus .TP \fIpathName \fBfocus \fR?\fItagOrId\fR? . Set the keyboard focus for the canvas widget to the item given by \fItagOrId\fR. If \fItagOrId\fR refers to several items, then the focus is set to the first such item in the display list that supports the |
︙ | ︙ | |||
635 636 637 638 639 640 641 642 | a given item does not actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the \fBfocus\fR widget command with the \fBfocus\fR command to set the focus window to the canvas (if it was not there already). .RE .TP | > | > > > | > > > | | > | | | > > > | | | | | > > > > > > > > > > | > | 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 | a given item does not actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the \fBfocus\fR widget command with the \fBfocus\fR command to set the focus window to the canvas (if it was not there already). .RE .\" METHOD: gettags .TP \fIpathName \fBgettags\fI tagOrId\fR . Return a list whose elements are the tags associated with the item given by \fItagOrId\fR. If \fItagOrId\fR refers to more than one item, then the tags are returned from the first such item in the display list. If \fItagOrId\fR does not refer to any items, or if the item contains no tags, then an empty string is returned. .\" METHOD: icursor .TP \fIpathName \fBicursor \fItagOrId index\fR . Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR to just before the character whose position is given by \fIindex\fR. If some or all of the items given by \fItagOrId\fR do not support an insertion cursor then this command has no effect on them. See \fBINDICES\fR above for a description of the legal forms for \fIindex\fR. .RS .PP Note that the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the \fBfocus\fR widget command, above), but the cursor position may be set even when the item does not have the focus. .PP This command returns an empty string. .RE .\" METHOD: image .TP \fIpathName \fBimage \fIimagename\fR ?\fIsubsample\fR? ?\fIzoom\fR? . Draw the canvas into the Tk photo image named \fIimagename\fR. If a \fB\-scrollregion\fR has been defined then this will be the boundaries of the canvas region drawn and the final size of the photo image. Otherwise the widget width and height with an origin of 0,0 will be the size of the canvas region drawn and the final size of the photo image. Optionally an integer \fIsubsample\fR factor may be given and the photo image will be reduced in size. .RS .PP In addition to the \fIsubsample\fR an integer \fIzoom\fR factor can also be given and the photo image will be enlarged. The image background will be filled with the canvas background colour. The canvas widget does not need to be mapped for this widget command to work, but at least one of it's ancestors must be mapped. .PP This command returns an empty string. .RE .\" METHOD: imove .TP \fIpathName \fBimove \fItagOrId index x y\fR . This command causes the \fIindex\fR'th coordinate of each of the items indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). Each item interprets \fIindex\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. .\" METHOD: index .TP \fIpathName \fBindex \fItagOrId index\fR . This command returns a decimal string giving the numerical index within \fItagOrId\fR corresponding to \fIindex\fR. \fIIndex\fR gives a textual description of the desired position as described in \fBINDICES\fR above. Text items interpret \fIindex\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. If \fItagOrId\fR refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order). .\" METHOD: insert .TP \fIpathName \fBinsert \fItagOrId beforeThis string\fR . For each of the items given by \fItagOrId\fR, if the item supports text or coordinate, insertion then \fIstring\fR is inserted into the item's text just before the character, or coordinate, whose index is \fIbeforeThis\fR. Text items interpret \fIbeforeThis\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the \fIstring\fR must be a valid coordinate sequence. .RS .PP See \fBINDICES\fR above for information about the forms allowed for \fIbeforeThis\fR. .PP This command returns an empty string. .RE .\" METHOD: itemcget .TP \fIpathName \fBitemcget\fI tagOrId option\fR . Returns the current value of the configuration option for the item given by \fItagOrId\fR whose name is \fIoption\fR. This command is similar to the \fBcget\fR widget command except that it applies to a particular item rather than the widget as a whole. \fIOption\fR may have any of the values accepted by the \fBcreate\fR widget command when the item was created. If \fItagOrId\fR is a tag that refers to more than one item, the first (lowest) such item is used. .\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . This command is similar to the \fBconfigure\fR widget command except that it modifies item-specific options for the items given by \fItagOrId\fR instead of modifying options for the overall canvas widget. |
︙ | ︙ | |||
740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 | modifies the given widget option(s) to have the given value(s) in each of the items given by \fItagOrId\fR; in this case the command returns an empty string. The \fIoption\fRs and \fIvalue\fRs are the same as those permissible in the \fBcreate\fR widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. .TP \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just before the item given by \fIbelowThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIBelowThis\fR is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. | > | > > > | 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 | modifies the given widget option(s) to have the given value(s) in each of the items given by \fItagOrId\fR; in this case the command returns an empty string. The \fIoption\fRs and \fIvalue\fRs are the same as those permissible in the \fBcreate\fR widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. .\" METHOD: lower .TP \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just before the item given by \fIbelowThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIBelowThis\fR is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. Note that this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. This command returns an empty string. .\" METHOD: move .TP \fIpathName \fBmove \fItagOrId xAmount yAmount\fR . Move each of the items given by \fItagOrId\fR in the canvas coordinate space by adding \fIxAmount\fR to the x-coordinate of each point associated with the item and \fIyAmount\fR to the y-coordinate of each point associated with the item. This command returns an empty string. .\" METHOD: moveto .TP \fIpathName \fBmoveto \fItagOrId xPos yPos\fR . Move the items given by \fItagOrId\fR in the canvas coordinate space so that the first coordinate pair (the upper-left corner of the bounding box) of the first item (the lowest in the display list) with tag \fItagOrId\fR is located at position (\fIxPos\fR,\fIyPos\fR). \fIxPos\fR and \fIyPos\fR may be the empty string, in which case the corresponding coordinate will be unchanged. All items matching \fItagOrId\fR remain in the same positions relative to each other. This command returns an empty string. .\" METHOD: postscript .TP \fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? . Generate a Postscript representation for part or all of the canvas. If the \fB\-file\fR option is specified then the Postscript is written to a file and an empty string is returned; otherwise the Postscript is returned as the result of the command. |
︙ | ︙ | |||
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 | either invoke the \fBupdate\fR command to wait for the canvas window to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR options to specify the area of the canvas to print. The \fIoption\fR\-\fIvalue\fR argument pairs provide additional information to control the generation of Postscript. The following options are supported: .RS .TP \fB\-channel \fIchannelName\fR . Specifies the name of the channel to which to write the Postscript. If this option and the \fB\-file\fR option are not specified then the Postscript is returned as the result of the command. .TP \fB\-colormap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a color mapping to use in the Postscript. Each element of \fIvarName\fR must consist of Postscript code to set a particular color value (e.g. .QW "\fB1.0 1.0 0.0 setrgbcolor\fR" ). When outputting color information in the Postscript, Tk checks to see if there is an element of \fIvarName\fR with the same name as the color. If so, Tk uses the value of the element as the Postscript command to set the color. If this option has not been specified, or if there is no entry in \fIvarName\fR for a given color, then Tk uses the red, green, and blue intensities from the X color. .TP \fB\-colormode \fImode\fR . Specifies how to output color information. \fIMode\fR must be either \fBcolor\fR (for full color output), \fBgray\fR (convert all colors to their gray-scale equivalents) or \fBmono\fR (convert all colors to black or white). .TP \fB\-file \fIfileName\fR . Specifies the name of the file in which to write the Postscript. If this option and the \fB\-channel\fR option are not specified then the Postscript is returned as the result of the command. .TP \fB\-fontmap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a font mapping to use in the Postscript. Each element of \fIvarName\fR must consist of a Tcl list with two elements, which are the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks to see if \fIvarName\fR contains an element with the same name as the font. If there is such an element, then the font information contained in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but \fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to parse the font name). .TP \fB\-height \fIsize\fR . Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. .TP \fB\-pageanchor \fIanchor\fR . Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the \fB\-pagex\fR and \fB\-pagey\fR options). For example, \fB\-pageanchor n\fR means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to \fBcenter\fR. .TP \fB\-pageheight \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR high on the Postscript page. \fISize\fR consists of a floating-point number followed by \fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, or \fBp\fR or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .TP \fB\-pagewidth \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR wide on the Postscript page. \fISize\fR has the same form as for \fB\-pageheight\fR. Defaults to the width of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .TP \fB\-pagex \fIposition\fR . \fIPosition\fR gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .TP \fB\-pagey \fIposition\fR . \fIPosition\fR gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .TP \fB\-rotate \fIboolean\fR . \fIBoolean\fR specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page .PQ portrait " orientation" ; in rotated output the x-axis runs along the long dimension of the page .PQ landscape " orientation" . Defaults to non-rotated. .TP \fB\-width \fIsize\fR . Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. .TP \fB\-x \fIposition\fR . Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. .TP \fB\-y \fIposition\fR . Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. .RE .TP \fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just after the item given by \fIaboveThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIAboveThis\fR is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. This command returns an empty string. .RS .PP | > > > > > > > > > > > > > > > > > > > > > > > > > | > > | 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 | either invoke the \fBupdate\fR command to wait for the canvas window to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR options to specify the area of the canvas to print. The \fIoption\fR\-\fIvalue\fR argument pairs provide additional information to control the generation of Postscript. The following options are supported: .RS .\" OPTION: -channel .TP \fB\-channel \fIchannelName\fR . Specifies the name of the channel to which to write the Postscript. If this option and the \fB\-file\fR option are not specified then the Postscript is returned as the result of the command. .\" OPTION: -colormap .TP \fB\-colormap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a color mapping to use in the Postscript. Each element of \fIvarName\fR must consist of Postscript code to set a particular color value (e.g. .QW "\fB1.0 1.0 0.0 setrgbcolor\fR" ). When outputting color information in the Postscript, Tk checks to see if there is an element of \fIvarName\fR with the same name as the color. If so, Tk uses the value of the element as the Postscript command to set the color. .RS .PP If this option has not been specified, or if there is no entry in \fIvarName\fR for a given color, then Tk uses the red, green, and blue intensities from the X color. .RE .\" OPTION: -colormode .TP \fB\-colormode \fImode\fR . Specifies how to output color information. \fIMode\fR must be either \fBcolor\fR (for full color output), \fBgray\fR (convert all colors to their gray-scale equivalents) or \fBmono\fR (convert all colors to black or white). .\" OPTION: -file .TP \fB\-file \fIfileName\fR . Specifies the name of the file in which to write the Postscript. If this option and the \fB\-channel\fR option are not specified then the Postscript is returned as the result of the command. .\" OPTION: -fontmap .TP \fB\-fontmap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a font mapping to use in the Postscript. Each element of \fIvarName\fR must consist of a Tcl list with two elements, which are the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks to see if \fIvarName\fR contains an element with the same name as the font. If there is such an element, then the font information contained in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. .RS .PP For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but \fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to parse the font name). .RE .\" OPTION: -height .TP \fB\-height \fIsize\fR . Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. .\" OPTION: -pageanchor .TP \fB\-pageanchor \fIanchor\fR . Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the \fB\-pagex\fR and \fB\-pagey\fR options). .RS .PP For example, \fB\-pageanchor n\fR means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to \fBcenter\fR. .RE .\" OPTION: -pageheight .TP \fB\-pageheight \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR high on the Postscript page. \fISize\fR consists of a floating-point number followed by \fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, or \fBp\fR or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .\" OPTION: -pagewidth .TP \fB\-pagewidth \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR wide on the Postscript page. \fISize\fR has the same form as for \fB\-pageheight\fR. Defaults to the width of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .\" OPTION: -pagex .TP \fB\-pagex \fIposition\fR . \fIPosition\fR gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .\" OPTION: -pagey .TP \fB\-pagey \fIposition\fR . \fIPosition\fR gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .\" OPTION: -rotate .TP \fB\-rotate \fIboolean\fR . \fIBoolean\fR specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page .PQ portrait " orientation" ; in rotated output the x-axis runs along the long dimension of the page .PQ landscape " orientation" . Defaults to non-rotated. .\" OPTION: -width .TP \fB\-width \fIsize\fR . Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. .\" OPTION: -x .TP \fB\-x \fIposition\fR . Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. .\" OPTION: -y .TP \fB\-y \fIposition\fR . Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. .RE .\" METHOD: raise .TP \fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just after the item given by \fIaboveThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIAboveThis\fR is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. This command returns an empty string. .RS .PP Note this this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. .RE .\" METHOD: rchars .TP \fIpathName \fBrchars \fItagOrId first last string\fR . This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR for each of the items indicated by \fItagOrId\fR to be replaced by \fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case \fIstring\fR should be a list of coordinates to use as a replacement). The other items ignore this operation. .\" METHOD: rotate .TP \fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR .VS "8.7, TIP164" Rotate the coordinates of all of the items given by \fItagOrId\fR in canvas coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the rotation operation and \fIangle\fR identifies the amount to rotate the coordinates |
︙ | ︙ | |||
990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 | points, and the \fBarc\fR, \fBoval\fR and \fBrectangle\fR types rotate about a computed center point instead of moving the bounding box coordinates directly. .PP Some items (currently \fBarc\fR and\fB text\fR) have angles in their options; this command \fIdoes not\fR affect those options. .RE .VE "8.7, TIP164" .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR . Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling operation and \fIxScale\fR and \fIyScale\fR identify the scale | > | 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 | points, and the \fBarc\fR, \fBoval\fR and \fBrectangle\fR types rotate about a computed center point instead of moving the bounding box coordinates directly. .PP Some items (currently \fBarc\fR and\fB text\fR) have angles in their options; this command \fIdoes not\fR affect those options. .RE .VE "8.7, TIP164" .\" METHOD: scale .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR . Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling operation and \fIxScale\fR and \fIyScale\fR identify the scale |
︙ | ︙ | |||
1011 1012 1013 1014 1015 1016 1017 1018 | This command returns an empty string. .RS .PP Note that some items have only a single pair of coordinates (e.g., text, images and windows) and so scaling of them by this command can only move them around. .RE .TP | > | | 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 | This command returns an empty string. .RS .PP Note that some items have only a single pair of coordinates (e.g., text, images and windows) and so scaling of them by this command can only move them around. .RE .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on canvases. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR . |
︙ | ︙ | |||
1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 | It then adjusts the view by \fIgain\fR times the difference in coordinates, where \fIgain\fR defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. .RE .TP \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? . Manipulates the selection in one of several ways, depending on \fIoption\fR. The command may take any of the forms described below. In all of the descriptions below, \fItagOrId\fR must refer to | > | 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 | It then adjusts the view by \fIgain\fR times the difference in coordinates, where \fIgain\fR defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. .RE .\" METHOD: select .TP \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? . Manipulates the selection in one of several ways, depending on \fIoption\fR. The command may take any of the forms described below. In all of the descriptions below, \fItagOrId\fR must refer to |
︙ | ︙ | |||
1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 | The anchor point is determined by the most recent \fBselect adjust\fR or \fBselect from\fR command for this widget. If the selection anchor point for the widget is not currently in \fItagOrId\fR, then it is set to the same character given by \fIindex\fR. Returns an empty string. .RE .TP \fIpathName \fBtype\fI tagOrId\fR . Returns the type of the item given by \fItagOrId\fR, such as \fBrectangle\fR or \fBtext\fR. If \fItagOrId\fR refers to more than one item, then the type of the first item in the display list is returned. If \fItagOrId\fR does not refer to any items at all then an empty string is returned. .TP \fIpathName \fBxview \fR?\fIargs\fR? . This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: .RS | > > | 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 | The anchor point is determined by the most recent \fBselect adjust\fR or \fBselect from\fR command for this widget. If the selection anchor point for the widget is not currently in \fItagOrId\fR, then it is set to the same character given by \fIindex\fR. Returns an empty string. .RE .\" METHOD: type .TP \fIpathName \fBtype\fI tagOrId\fR . Returns the type of the item given by \fItagOrId\fR, such as \fBrectangle\fR or \fBtext\fR. If \fItagOrId\fR refers to more than one item, then the type of the first item in the display list is returned. If \fItagOrId\fR does not refer to any items at all then an empty string is returned. .\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR? . This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: .RS |
︙ | ︙ | |||
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 | If \fInumber\fR is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units of the \fBxScrollIncrement\fR option, if it is greater than zero, or in units of one-tenth the window's width otherwise. .RE .TP \fIpathName \fByview ?\fIargs\fR? . This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: .RS | > | 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 | If \fInumber\fR is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units of the \fBxScrollIncrement\fR option, if it is greater than zero, or in units of one-tenth the window's width otherwise. .RE .\" METHOD: yview .TP \fIpathName \fByview ?\fIargs\fR? . This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: .RS |
︙ | ︙ | |||
1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 | At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. .SS "COMMON ITEM OPTIONS" .PP Many items share a common set of options. These options are explained here, and then referred to be each widget type for brevity. .TP \fB\-anchor \fIanchorPos\fR . \fIAnchorPos\fR tells how to position the item relative to the positioning point for the item; it may have any of the forms accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR is \fBcenter\fR then the item is centered on the point; if \fIanchorPos\fR is \fBn\fR then the item will be drawn so that its top center point is at the positioning point. This option defaults to \fBcenter\fR. .TP \fB\-dash \fIpattern\fR .TP \fB\-activedash \fIpattern\fR .TP \fB\-disableddash \fIpattern\fR . | > > > > | > > > > | > > > | > > > > | > > > > | > > > > > | | | > | 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 | At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. .SS "COMMON ITEM OPTIONS" .PP Many items share a common set of options. These options are explained here, and then referred to be each widget type for brevity. .\" OPTION: -anchor .TP \fB\-anchor \fIanchorPos\fR . \fIAnchorPos\fR tells how to position the item relative to the positioning point for the item; it may have any of the forms accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR is \fBcenter\fR then the item is centered on the point; if \fIanchorPos\fR is \fBn\fR then the item will be drawn so that its top center point is at the positioning point. This option defaults to \fBcenter\fR. .\" OPTION: -dash .TP \fB\-dash \fIpattern\fR .\" OPTION: -activedash .TP \fB\-activedash \fIpattern\fR .\" OPTION: -disableddash .TP \fB\-disableddash \fIpattern\fR . These options specify dash patterns for the normal, active state, and disabled state of an item. \fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR. If the dash options are omitted then the default is a solid outline. See \fBDASH PATTERNS\fR for more information. .\" OPTION: -dashoffset .TP \fB\-dashoffset \fIoffset\fR . The starting \fIoffset\fR in pixels into the pattern provided by the \fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no \fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described in the \fBCOORDINATES\fR section above. .\" OPTION: -fill .TP \fB\-fill \fIcolor\fR .\" OPTION: -activefill .TP \fB\-activefill \fIcolor\fR .\" OPTION: -disabledfill .TP \fB\-disabledfill \fIcolor\fR . These options specify the color to be used to fill item's area. in its normal, active, and disabled states. The even-odd fill rule is used. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. For the line item, it specifies the color of the line drawn. For the text item, it specifies the foreground color of the text. If \fIcolor\fR is an empty string (the default for all canvas items except line and text), then the item will not be filled. .\" OPTION: -outline .TP \fB\-outline \fIcolor\fR .\" OPTION: -activeoutline .TP \fB\-activeoutline \fIcolor\fR .\" OPTION: -disabledoutline .TP \fB\-disabledoutline \fIcolor\fR . These options specify the color that should be used to draw the outline of the item in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR is specified as an empty string then no outline is drawn for the item. .\" OPTION: -offset .TP \fB\-offset \fIoffset\fR . Specifies the offset of stipples. The offset value can be of the form \fBx,y\fR or \fIside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting \fB#\fR in front of the coordinate pair indicates using the toplevel origin instead. For canvas objects, the \fB\-offset\fR option is used for stippling as well. For the line and polygon canvas items you can also specify an index as argument, which connects the stipple origin to one of the coordinate points of the line/polygon. Note that stipple offsets are \fIonly supported on X11\fR; they are silently ignored on other platforms. .\" OPTION: -outlinestipple .TP \fB\-outlinestipple \fIbitmap\fR .\" OPTION: -activeoutlinestipple .TP \fB\-activeoutlinestipple \fIbitmap\fR .\" OPTION: -disabledoutlinestipple .TP \fB\-disabledoutlinestipple \fIbitmap\fR . These options specify stipple patterns that should be used to draw the outline of the item in its normal, active and disabled states. Indicates that the outline for the item should be drawn with a stipple pattern; \fIbitmap\fR specifies the stipple pattern to use, in any of the forms accepted by \fBTk_GetBitmap\fR. If the \fB\-outline\fR option has not been specified then this option has no effect. If \fIbitmap\fR is an empty string (the default), then the outline is drawn in a solid fashion. \fINote that stipples are not well supported on platforms that do not use X11 as their drawing API.\fR .\" OPTION: -outlineoffset .TP \fB\-outlineoffset \fIoffset\fR . Specifies the offset of the stipple pattern used for outlines, in the same way that the \fB\-outline\fR option controls fill stipples. (See the \fB\-outline\fR option for a description of the syntax of \fIoffset\fR.) .\" OPTION: -stipple .TP \fB\-stipple \fIbitmap\fR .\" OPTION: -activestipple .TP \fB\-activestipple \fIbitmap\fR .\" OPTION: -disabledstipple .TP \fB\-disabledstipple \fIbitmap\fR . These options specify stipple patterns that should be used to fill the item in its normal, active and disabled states. \fIbitmap\fR specifies the stipple pattern to use, in any of the forms accepted by \fBTk_GetBitmap\fR. If the \fB\-fill\fR option has not been specified then this option has no effect. If \fIbitmap\fR is an empty string (the default), then filling is done in a solid fashion. For the text item, it affects the actual text. \fINote that stipples are not well supported on platforms that do not use X11 as their drawing API.\fR .\" OPTION: -state .TP \fB\-state \fIstate\fR . This allows an item to override the canvas widget's global \fIstate\fR option. It takes the same values: \fInormal\fR, \fIdisabled\fR or \fIhidden\fR. .\" OPTION: -tags .TP \fB\-tags \fItagList\fR . Specifies a set of tags to apply to the item. \fITagList\fR consists of a list of tag names, which replace any existing tags for the item. \fITagList\fR may be an empty list. .\" OPTION: -width .TP \fB\-width \fIoutlineWidth\fR .\" OPTION: -activewidth .TP \fB\-activewidth \fIoutlineWidth\fR .\" OPTION: -disabledwidth .TP \fB\-disabledwidth \fIoutlineWidth\fR . These options specify the width of the outline to be drawn around the item's region, in its normal, active and disabled states. \fIoutlineWidth\fR may be in any of the forms described in the \fBCOORDINATES\fR section above. If the \fB\-outline\fR option has been specified as an empty string then this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region. .SH "STANDARD ITEM TYPES" .SS "ARC ITEMS" .PP Items of type \fBarc\fR appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified by either the \fB\-start\fR and \fB\-extent\fR options or the \fB\-height\fR option) and displayed in one of several ways (specified by the \fB\-style\fR option). Arcs are created with widget commands of the following form: .CS \fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? \fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a |
︙ | ︙ | |||
1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 | \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for arcs: .TP \fB\-extent \fIdegrees\fR Specifies the size of the angular range occupied by the arc. The arc's range extends for \fIdegrees\fR degrees counter-clockwise from the starting angle given by the \fB\-start\fR option. \fIDegrees\fR may be negative. If it is greater than 360 or less than \-360, then \fIdegrees\fR modulo 360 is used as the extent. .TP \fB\-start \fIdegrees\fR Specifies the beginning of the angular range occupied by the arc. \fIDegrees\fR is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative. .TP \fB\-height \fIdistance\fR Provides a shortcut for creating a circular arc segment by defining the distance of the mid-point of the arc from its chord. When this option is used the coordinates are interpreted as the start and end coordinates | > > > > > > | | 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 | \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for arcs: .\" OPTION: -extent .TP \fB\-extent \fIdegrees\fR . Specifies the size of the angular range occupied by the arc. The arc's range extends for \fIdegrees\fR degrees counter-clockwise from the starting angle given by the \fB\-start\fR option. \fIDegrees\fR may be negative. If it is greater than 360 or less than \-360, then \fIdegrees\fR modulo 360 is used as the extent. .\" OPTION: -start .TP \fB\-start \fIdegrees\fR . Specifies the beginning of the angular range occupied by the arc. \fIDegrees\fR is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative. .\" OPTION: -height .TP \fB\-height \fIdistance\fR . Provides a shortcut for creating a circular arc segment by defining the distance of the mid-point of the arc from its chord. When this option is used the coordinates are interpreted as the start and end coordinates of the chord, and the options \fB\-start\fR and \fB\-extent\fR are ignored. The value of \fIdistance\fR has the following meaning: .RS .PP .RS \fIdistance\fR > 0 creates a clockwise arc .br \fIdistance\fR < 0 creates an counter-clockwise arc |
︙ | ︙ | |||
1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 | .RE .PP choosing the minus sign for the minor arc and the plus sign for the major arc. .PP Note that \fBitemcget \-height\fR always returns 0 so that introspection code can be kept simple. .RE .TP \fB\-style \fItype\fR Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If \fItype\fR is \fBchord\fR then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. | > > | 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 | .RE .PP choosing the minus sign for the minor arc and the plus sign for the major arc. .PP Note that \fBitemcget \-height\fR always returns 0 so that introspection code can be kept simple. .RE .\" OPTION: -style .TP \fB\-style \fItype\fR . Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If \fItype\fR is \fBchord\fR then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. |
︙ | ︙ | |||
1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 | The following standard options are supported by bitmaps: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for bitmaps: .TP \fB\-background \fIcolor\fR .TP \fB\-activebackground \fIcolor\fR .TP \fB\-disabledbackground \fIcolor\fR Specifies the color to use for each of the bitmap's .QW 0 valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If this option is not specified, or if it is specified as an empty string, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. .TP \fB\-bitmap \fIbitmap\fR .TP \fB\-activebitmap \fIbitmap\fR .TP \fB\-disabledbitmap \fIbitmap\fR | > > > > > > > > | | > > > > | | 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 | The following standard options are supported by bitmaps: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for bitmaps: .\" OPTION: -background .TP \fB\-background \fIcolor\fR .\" OPTION: -activebackground .TP \fB\-activebackground \fIcolor\fR .\" OPTION: -disabledbackground .TP \fB\-disabledbackground \fIcolor\fR . Specifies the color to use for each of the bitmap's .QW 0 valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If this option is not specified, or if it is specified as an empty string, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. .\" OPTION: -bitmap .TP \fB\-bitmap \fIbitmap\fR .\" OPTION: -activebitmap .TP \fB\-activebitmap \fIbitmap\fR .\" OPTION: -disabledbitmap .TP \fB\-disabledbitmap \fIbitmap\fR . These options specify the bitmaps to display in the item in its normal, active and disabled states. \fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR .\" OPTION: -activeforeground .TP \fB\-activeforeground \fIcolor\fR .\" OPTION: -disabledforeground .TP \fB\-disabledforeground \fIcolor\fR . These options specify the color to use for each of the bitmap's .QW 1 valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. .SS "IMAGE ITEMS" .PP Items of type \fBimage\fR are used to display images on a canvas. |
︙ | ︙ | |||
1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 | The following standard options are supported by images: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for images: .TP \fB\-image \fIname\fR .TP \fB\-activeimage \fIname\fR .TP \fB\-disabledimage \fIname\fR Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the \fBimage create\fR command. .SS "LINE ITEMS" .PP Items of type \fBline\fR appear on the display as one or more connected | > > > > | 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 | The following standard options are supported by images: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for images: .\" OPTION: -image .TP \fB\-image \fIname\fR .\" OPTION: -activeimage .TP \fB\-activeimage \fIname\fR .\" OPTION: -disabledimage .TP \fB\-disabledimage \fIname\fR . Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the \fBimage create\fR command. .SS "LINE ITEMS" .PP Items of type \fBline\fR appear on the display as one or more connected |
︙ | ︙ | |||
1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 | \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for lines: .TP \fB\-arrow \fIwhere\fR Indicates whether or not arrowheads are to be drawn at one or both ends of the line. \fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads), \fBfirst\fR (for an arrowhead at the first point of the line), \fBlast\fR (for an arrowhead at the last point of the line), or \fBboth\fR (for arrowheads at both ends). This option defaults to \fBnone\fR. When requested to draw an arrowhead, Tk internally adjusts the corresponding line end point so that the rendered line ends at the neck of the arrowhead rather than at its tip so that the line doesn't extend past the edge of the arrowhead. This may trigger a \fBLeave\fR event if the mouse is hovering this line end. Conversely, when removing an arrowhead Tk adjusts the corresponding line point the other way round, which may trigger an \fBEnter\fR event. .TP \fB\-arrowshape \fIshape\fR This option indicates how to draw arrowheads. The \fIshape\fR argument must be a list with three elements, each specifying a distance in any of the forms described in the \fBCOORDINATES\fR section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option is not specified then Tk picks a .QW reasonable shape. .TP \fB\-capstyle \fIstyle\fR Specifies the ways in which caps are to be drawn at the endpoints of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR (\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). If this option is not specified then it defaults to \fBbutt\fR. Where arrowheads are drawn the cap style is ignored. .TP \fB\-joinstyle \fIstyle\fR Specifies the ways in which joints are to be drawn at the vertices of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. If the line only contains two points then this option is irrelevant. .TP \fB\-smooth \fIsmoothMethod\fR \fIsmoothMethod\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are | > > > > > > > > > > | > > > | 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 | \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for lines: .\" OPTION: -arrow .TP \fB\-arrow \fIwhere\fR . Indicates whether or not arrowheads are to be drawn at one or both ends of the line. \fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads), \fBfirst\fR (for an arrowhead at the first point of the line), \fBlast\fR (for an arrowhead at the last point of the line), or \fBboth\fR (for arrowheads at both ends). This option defaults to \fBnone\fR. When requested to draw an arrowhead, Tk internally adjusts the corresponding line end point so that the rendered line ends at the neck of the arrowhead rather than at its tip so that the line doesn't extend past the edge of the arrowhead. This may trigger a \fBLeave\fR event if the mouse is hovering this line end. Conversely, when removing an arrowhead Tk adjusts the corresponding line point the other way round, which may trigger an \fBEnter\fR event. .\" OPTION: -arrowshape .TP \fB\-arrowshape \fIshape\fR . This option indicates how to draw arrowheads. The \fIshape\fR argument must be a list with three elements, each specifying a distance in any of the forms described in the \fBCOORDINATES\fR section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option is not specified then Tk picks a .QW reasonable shape. .\" OPTION: -capstyle .TP \fB\-capstyle \fIstyle\fR . Specifies the ways in which caps are to be drawn at the endpoints of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR (\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). If this option is not specified then it defaults to \fBbutt\fR. Where arrowheads are drawn the cap style is ignored. .\" OPTION: -joinstyle .TP \fB\-joinstyle \fIstyle\fR . Specifies the ways in which joints are to be drawn at the vertices of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. If the line only contains two points then this option is irrelevant. .\" OPTION: -smooth .TP \fB\-smooth \fIsmoothMethod\fR . \fIsmoothMethod\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes \fBtrue\fR smoothing. If the smoothing method is \fBtrue\fR, this indicates that the line should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is \fBraw\fR, this indicates that the line should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be generated within a curve by making control points equal to their neighbouring knot points. If the last point is a control point and not a knot point, the point is repeated (one or two times) so that it also becomes a knot point. .\" OPTION: -splinesteps .TP \fB\-splinesteps \fInumber\fR . Specifies the degree of smoothness desired for curves: each spline will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .SS "OVAL ITEMS" .PP Items of type \fBoval\fR appear as circular or oval regions on the display. Each oval may have an outline, a fill, or |
︙ | ︙ | |||
1708 1709 1710 1711 1712 1713 1714 | Polygon items support coordinate indexing operations using the \fBdchars\fR, \fBindex\fR and \fBinsert\fR widget commands. Polygons are created with widget commands of the following form: .CS \fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR? \fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR? .CE | | | | 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 | Polygon items support coordinate indexing operations using the \fBdchars\fR, \fBindex\fR and \fBinsert\fR widget commands. Polygons are created with widget commands of the following form: .CS \fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR? \fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for three or more points that define a polygon. The first point should not be repeated as the last to close the shape; Tk will automatically close the periphery between the first and last points. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's |
︙ | ︙ | |||
1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 | \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for polygons: .TP \fB\-joinstyle \fIstyle\fR Specifies the ways in which joints are to be drawn at the vertices of the outline. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. .TP \fB\-smooth \fIboolean\fR \fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are | > > > > | > > > | 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 | \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for polygons: .\" OPTION: -joinstyle .TP \fB\-joinstyle \fIstyle\fR . Specifies the ways in which joints are to be drawn at the vertices of the outline. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. .\" OPTION: -smooth .TP \fB\-smooth \fIboolean\fR . \fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes \fBtrue\fR smoothing. If the smoothing method is \fBtrue\fR, this indicates that the polygon should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is \fBraw\fR, this indicates that the polygon should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be generated within a curve by making control points equal to their neighbouring knot points. If the last point is not the second point of a pair of control points, the point is repeated (one or two times) so that it also becomes the second point of a pair of control points (the associated knot point will be the first control point). .\" OPTION: -splinesteps .TP \fB\-splinesteps \fInumber\fR . Specifies the degree of smoothness desired for curves: each spline will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .PP Polygon items are different from other items such as rectangles, ovals and arcs in that interior points are considered to be .QW inside |
︙ | ︙ | |||
1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 | \fB\-anchor\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for text items: .TP \fB\-angle \fIrotationDegrees\fR . \fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise about the positioning point for the text; it may have any floating-point value from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the text will be drawn vertically from bottom to top. This option defaults to \fB0.0\fR. .TP \fB\-font \fIfontName\fR Specifies the font to use for the text item. \fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR. If this option is not specified, it defaults to a system-dependent font. .TP \fB\-justify \fIhow\fR Specifies how to justify the text within its bounding region. \fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, or \fBcenter\fR. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to \fBleft\fR. .TP \fB\-text \fIstring\fR \fIString\fR specifies the characters to be displayed in the text item. Newline characters cause line breaks. The characters in the item may also be changed with the \fBinsert\fR and \fBdelete\fR widget commands. This option defaults to an empty string. .TP | > > > > > > > > | > > > | 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 | \fB\-anchor\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for text items: .\" OPTION: -angle .TP \fB\-angle \fIrotationDegrees\fR . \fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise about the positioning point for the text; it may have any floating-point value from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the text will be drawn vertically from bottom to top. This option defaults to \fB0.0\fR. .\" OPTION: -font .TP \fB\-font \fIfontName\fR . Specifies the font to use for the text item. \fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR. If this option is not specified, it defaults to a system-dependent font. .\" OPTION: -justify .TP \fB\-justify \fIhow\fR . Specifies how to justify the text within its bounding region. \fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, or \fBcenter\fR. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to \fBleft\fR. .\" OPTION: -text .TP \fB\-text \fIstring\fR . \fIString\fR specifies the characters to be displayed in the text item. Newline characters cause line breaks. The characters in the item may also be changed with the \fBinsert\fR and \fBdelete\fR widget commands. This option defaults to an empty string. .\" OPTION: -underline .TP \fB\-underline \fInumber\fR . Specifies the integer index of a character within the text to be underlined. 0 corresponds to the first character of the text displayed, 1 to the next character, and so on. \-1 means that no underline should be drawn (if the whole text item is to be underlined, the appropriate font should be used instead). .\" OPTION: -width .TP \fB\-width \fIlineLength\fR . Specifies a maximum line length for the text, in any of the forms described in the \fBCOORDINATES\fR section above. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than \fIlineLength\fR is broken just before a space character to make the line shorter than \fIlineLength\fR; the |
︙ | ︙ | |||
1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 | The following standard options are supported by window items: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for window items: .TP \fB\-height \fIpixels\fR . Specifies the height to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever height it requests internally. .TP \fB\-width \fIpixels\fR . Specifies the width to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever width it requests internally. .TP \fB\-window \fIpathName\fR . Specifies the window to associate with this item. The window specified by \fIpathName\fR must either be a child of the canvas widget or a child of some ancestor of the canvas widget. \fIPathName\fR may not refer to a top-level window. .PP | > > > | | 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 | The following standard options are supported by window items: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for window items: .\" OPTION: -height .TP \fB\-height \fIpixels\fR . Specifies the height to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever height it requests internally. .\" OPTION: -width .TP \fB\-width \fIpixels\fR . Specifies the width to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever width it requests internally. .\" OPTION: -window .TP \fB\-window \fIpathName\fR . Specifies the window to associate with this item. The window specified by \fIpathName\fR must either be a child of the canvas widget or a child of some ancestor of the canvas widget. \fIPathName\fR may not refer to a top-level window. .PP Note that, due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. Also note that window items, unlike other canvas items, are not clipped for display by their containing canvas's border, and are instead clipped by the parent widget of the window specified by the \fB\-window\fR option; when the parent widget is the canvas, this means that the window item can overlap the canvas's border. |
︙ | ︙ |
Changes to doc/checkbutton.n.
︙ | ︙ | |||
193 194 195 196 197 198 199 200 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for checkbutton widgets: .TP | > | > > > > > > > > > > > > > | 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for checkbutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. .\" METHOD: deselect .TP \fIpathName \fBdeselect\fR . Deselects the checkbutton and sets the associated variable to its .QW off value. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the Tcl command associated with the checkbutton, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is \fBdisabled\fR. .\" METHOD: select .TP \fIpathName \fBselect\fR . Selects the checkbutton and sets the associated variable to its .QW on value. .\" METHOD: toggle .TP \fIpathName \fBtoggle\fR . Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. .SH BINDINGS .PP Tk automatically creates class bindings for checkbuttons that give them the following default behavior: .IP [1] |
︙ | ︙ | |||
273 274 275 276 277 278 279 | The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH EXAMPLE .PP This example shows a group of uncoupled checkbuttons. .PP .CS | | | | | | | 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH EXAMPLE .PP This example shows a group of uncoupled checkbuttons. .PP .CS labelframe .lbl -text "Steps:" \fBcheckbutton\fR .c1 -text Lights -variable lights \fBcheckbutton\fR .c2 -text Cameras -variable cameras \fBcheckbutton\fR .c3 -text Action! -variable action pack .c1 .c2 .c3 -in .lbl pack .lbl .CE .SH "SEE ALSO" button(n), options(n), radiobutton(n), ttk::checkbutton(n) .SH KEYWORDS checkbutton, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/chooseColor.n.
︙ | ︙ | |||
14 15 16 17 18 19 20 21 | \fBtk_chooseColor \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseColor\fR pops up a dialog box for the user to select a color. The following \fIoption\-value\fR pairs are possible as command line arguments: .TP | > | > > | > > | > | | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | \fBtk_chooseColor \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseColor\fR pops up a dialog box for the user to select a color. The following \fIoption\-value\fR pairs are possible as command line arguments: .\" OPTION: -initialcolor .TP \fB\-initialcolor\fI color\fR . Specifies the color to display in the color dialog when it pops up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR function. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the color dialog. The color dialog is displayed on top of its parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .LP If the user selects a color, \fBtk_chooseColor\fR will return the name of the color in a form acceptable to \fBTk_GetColor\fR. If the user cancels the operation, both commands will return the empty string. .SH EXAMPLE .PP .CS button .b -bg [tk_chooseColor -initialcolor gray -title "Choose color"] .CE .SH KEYWORDS color, color selection, dialog '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/chooseDirectory.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 | \fBtk_chooseDirectory \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the user to select a directory. The following \fIoption\-value\fR pairs are possible as command line arguments: .TP | > | > > | > > | > > | > > | > > | > | | | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | \fBtk_chooseDirectory \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the user to select a directory. The following \fIoption\-value\fR pairs are possible as command line arguments: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on Mac OS X. .\" OPTION: -initialdir .TP \fB\-initialdir\fI dirname\fR . Specifies that the directories in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. .\" OPTION: -mustexist .TP \fB\-mustexist\fI boolean\fR . Specifies whether the user may specify non-existent directories. If this parameter is true, then the user may only select directories that already exist. The default value is \fIfalse\fR. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the dialog. The dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .SH EXAMPLE .PP .CS set dir [\fBtk_chooseDirectory\fR \e -initialdir ~ -title "Choose a directory"] if {$dir eq ""} { label .l -text "No directory selected" } else { label .l -text "Selected $dir" } .CE .SH "SEE ALSO" tk_getOpenFile(n), tk_getSaveFile(n) .SH KEYWORDS directory, selection, dialog, platform-specific '\" Local Variables: |
︙ | ︙ |
Changes to doc/clipboard.n.
︙ | ︙ | |||
23 24 25 26 27 28 29 30 | be called, followed by a sequence of one or more calls to \fBclipboard append\fR. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop. .PP The first argument to \fBclipboard\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .TP | > | | 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | be called, followed by a sequence of one or more calls to \fBclipboard append\fR. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop. .PP The first argument to \fBclipboard\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .\" METHOD: append .TP \fBclipboard append\fR ?\fB\-displayof\fI window\fR? ?\fB\-format\fI format\fR? ?\fB\-type\fI type\fR? ?\fB\-\|\-\fR? \fIdata\fR . Appends \fIdata\fR to the clipboard on \fIwindow\fR's display in the form given by \fItype\fR with the representation given by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's display. .RS .PP |
︙ | ︙ | |||
67 68 69 70 71 72 73 74 | irrelevant. .PP A \fB\-\|\-\fR argument may be specified to mark the end of options: the next argument will always be used as \fIdata\fR. This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE .TP | > | > | | 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | irrelevant. .PP A \fB\-\|\-\fR argument may be specified to mark the end of options: the next argument will always be used as \fIdata\fR. This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE .\" METHOD: clear .TP \fBclipboard clear\fR ?\fB\-displayof\fI window\fR? . Claims ownership of the clipboard on \fIwindow\fR's display and removes any previous contents. \fIWindow\fR defaults to .QW . . Returns an empty string. .\" METHOD: get .TP \fBclipboard get\fR ?\fB\-displayof\fI window\fR? ?\fB\-type\fI type\fR? . Retrieve data from the clipboard on \fIwindow\fR's display. \fIWindow\fR defaults to .QW . . \fIType\fR specifies the form in which the data is to be returned and should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR. \fIType\fR defaults to \fBSTRING\fR. This command is |
︙ | ︙ | |||
118 119 120 121 122 123 124 | # it produces a script that recreates the item(s) when executed proc getItemConfig {canvas tag} { set script {} foreach item [$canvas find withtag $tag] { append script {$canvas create } [$canvas type $item] append script { } [$canvas coords $item] { } foreach config [$canvas itemconf $item] { | | | | | | 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | # it produces a script that recreates the item(s) when executed proc getItemConfig {canvas tag} { set script {} foreach item [$canvas find withtag $tag] { append script {$canvas create } [$canvas type $item] append script { } [$canvas coords $item] { } foreach config [$canvas itemconf $item] { lassign $config name - - - value append script [list $name $value] { } } append script \en } return [string trim $script] } # Set up a binding on a canvas to cut and paste an item set c [canvas .c] pack $c $c create text 150 30 -text "cut and paste me" bind $c <<Cut>> { \fBclipboard clear\fR \fBclipboard append -type\fR TkCanvasItem \e [getItemConfig %W current] # Delete because this is cut, not copy. %W delete current } bind $c <<Paste>> { catch { set canvas %W eval [\fBclipboard get -type\fR TkCanvasItem] } } .CE .SH "SEE ALSO" interp(n), selection(n) .SH KEYWORDS clear, format, clipboard, append, selection, type '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/colors.n.
︙ | ︙ | |||
892 893 894 895 896 897 898 | systemTextBackgroundColor systemTextColor .DE .RE . The numbered systemWindowBackgroundColors below are used in the \fBttk::notebook\fR and \fBttk::labelframe\fR widgets | | < | 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 | systemTextBackgroundColor systemTextColor .DE .RE . The numbered systemWindowBackgroundColors below are used in the \fBttk::notebook\fR and \fBttk::labelframe\fR widgets to provide a contrasting background. Each numbered color contrasts with its predecessor. .RS .DS systemWindowBackgroundColor systemWindowBackgroundColor1 systemWindowBackgroundColor2 systemWindowBackgroundColor3 systemWindowBackgroundColor4 systemWindowBackgroundColor5 systemWindowBackgroundColor6 systemWindowBackgroundColor7 .DE .RE .TP \fBWindows\fR . On Windows, the following additional system colors are available (note that the actual color values depend on the currently active OS theme): .RS .DS .ta 6c |
︙ | ︙ |
Changes to doc/console.n.
1 2 3 4 5 6 7 8 9 10 11 12 13 | '\" '\" Copyright (c) 2001 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH console n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME console \- Control the console on systems without a real console .SH SYNOPSIS | | | | > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | '\" '\" Copyright (c) 2001 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH console n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME console \- Control the console on systems without a real console .SH SYNOPSIS \fBconsole\fI subcommand\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The console window is a replacement for a real console to allow input and output on the standard I/O channels on platforms that do not have a real console. It is implemented as a separate interpreter with the Tk toolkit loaded, and control over this interpreter is given through the \fBconsole\fR command. The behaviour of the console window is defined mainly through the contents of the \fIconsole.tcl\fR file in the Tk library. Except for TkAqua, this command is not available when Tk is loaded into a tclsh interpreter with .QW "\fBpackage require Tk\fR" , as a conventional terminal is expected to be present in that case. In TkAqua, this command is disabled when there is a startup script and stdin is \fB/dev/null\fR (as is the case e.g. when a bundled application embedding Tk is started by the macOS Launcher). To enable the command in that case, define the environment variable \fBTK_CONSOLE\fR. This can be done by modifying the Info.plist file by adding the LSEnvironment key to the main dict and setting its value to be a dict with the key \fBTK_CONSOLE\fR. .PP .\" METHOD: eval .TP \fBconsole eval \fIscript\fR . Evaluate the \fIscript\fR argument as a Tcl script in the console interpreter. The normal interpreter is accessed through the \fBconsoleinterp\fR command in the console interpreter. .\" METHOD: hide .TP \fBconsole hide\fR . Hide the console window from view. Precisely equivalent to withdrawing the \fB.\fR window in the console interpreter. .\" METHOD: show .TP \fBconsole show\fR . Display the console window. Precisely equivalent to deiconifying the \fB.\fR window in the console interpreter. .\" METHOD: title .TP \fBconsole title \fR?\fIstring\fR? . Query or modify the title of the console window. If \fIstring\fR is not specified, queries the title of the console window, and sets the title of the console window to \fIstring\fR otherwise. Precisely equivalent to using the \fBwm title\fR command in the console interpreter. .SH "ACCESS TO THE MAIN INTERPRETER" .PP The \fBconsoleinterp\fR command in the console interpreter allows scripts to be evaluated in the main interpreter. It supports two subcommands: \fBeval\fR and \fBrecord\fR. .PP .\" METHOD: eval .TP \fBconsoleinterp eval \fIscript\fR . Evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter. .\" METHOD: record .TP \fBconsoleinterp record \fIscript\fR . Records and evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter as if \fIscript\fR had been typed in at the console. .SH "ADDITIONAL TRAP CALLS" .PP There are several additional commands in the console interpreter that are called in response to activity in the main interpreter. |
︙ | ︙ |
Changes to doc/cursors.n.
︙ | ︙ | |||
97 98 99 100 101 102 103 104 105 106 107 108 109 110 | xterm .CE .PP The \fBnone\fR cursor can be specified to eliminate the cursor. .SH "PORTABILITY ISSUES" .TP \fBWindows\fR On Windows systems, the following cursors are mapped to native cursors: .RS .CS arrow center_ptr crosshair fleur | > | 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | xterm .CE .PP The \fBnone\fR cursor can be specified to eliminate the cursor. .SH "PORTABILITY ISSUES" .TP \fBWindows\fR . On Windows systems, the following cursors are mapped to native cursors: .RS .CS arrow center_ptr crosshair fleur |
︙ | ︙ | |||
127 128 129 130 131 132 133 134 135 136 137 138 139 140 | size_we uparrow wait .CE .RE .TP \fBMac OS X\fR On Mac OS X systems, the following cursors are mapped to native cursors: .RS .CS arrow top_left_arrow left_ptr cross | > | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | size_we uparrow wait .CE .RE .TP \fBMac OS X\fR . On Mac OS X systems, the following cursors are mapped to native cursors: .RS .CS arrow top_left_arrow left_ptr cross |
︙ | ︙ |
Changes to doc/dialog.n.
︙ | ︙ | |||
15 16 17 18 19 20 21 | \fBtk_dialog \fIwindow title text bitmap default string string ...\fR .BE .SH DESCRIPTION .PP This procedure is part of the Tk script library. It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR. Its arguments describe a dialog box: | < | < | < | < | < | < | | 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | \fBtk_dialog \fIwindow title text bitmap default string string ...\fR .BE .SH DESCRIPTION .PP This procedure is part of the Tk script library. It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR. Its arguments describe a dialog box: .IP \fIwindow\fR Name of top-level window to use for dialog. Any existing window by this name is destroyed. .IP \fItitle\fR Text to appear in the window manager's title bar for the dialog. .IP \fItext\fR Message to appear in the top portion of the dialog box. .IP \fIbitmap\fR If non-empty, specifies a bitmap (in a form suitable for Tk_GetBitmap) to display in the top portion of the dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the dialog. .IP \fIdefault\fR If this is an integer greater than or equal to zero, then it gives the index of the button that is to be the default button for the dialog (0 for the leftmost button, and so on). If less than zero or an empty string then there will not be any default button. .IP \fIstring\fR There will be one button for each of these arguments. Each \fIstring\fR specifies text to display in a button, in order from left to right. .PP After creating a dialog box, \fBtk_dialog\fR waits for the user to select one of the buttons either by clicking on the button with the mouse or by typing return to invoke the default button (if any). |
︙ | ︙ |
Changes to doc/entry.n.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .TH entry n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME entry \- Create and manipulate 'entry' one-line text entry widgets .SH SYNOPSIS | | | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | .TH entry n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME entry \- Create and manipulate 'entry' one-line text entry widgets .SH SYNOPSIS \fBentry\fI pathName \fR?\fIoptions\fR? .SO \-background \-highlightthickness \-selectbackground \-borderwidth \-insertbackground \-selectborderwidth \-cursor \-insertborderwidth \-selectforeground \-exportselection \-insertofftime \-takefocus \-font \-insertontime \-textvariable \-foreground \-insertwidth \-xscrollcommand |
︙ | ︙ | |||
172 173 174 175 176 177 178 | \fB\-invalidcommand\fR encounters an error in its script while evaluating or \fB\-validatecommand\fR does not return a valid Tcl boolean value. The \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the entry widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the \fB\-validate\fR option set, you should | | | | 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 | \fB\-invalidcommand\fR encounters an error in its script while evaluating or \fB\-validatecommand\fR does not return a valid Tcl boolean value. The \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the entry widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the \fB\-validate\fR option set, you should include the command: .CS after idle {%W config -validate %v} .CE in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the entry widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the entry widget to become out of sync with the \fB\-textvariable\fR. .SH "WIDGET COMMAND" .PP |
︙ | ︙ | |||
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | .SS INDICES .PP Many of the widget commands for entries take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: .TP 12 \fInumber\fR Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .TP 12 \fBanchor\fR Indicates the anchor point for the selection, which is set with the \fBselect from\fR and \fBselect adjust\fR widget commands. .TP 12 \fBend\fR Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. .TP 12 \fBinsert\fR Indicates the character adjacent to and immediately following the insertion cursor. .TP 12 \fBsel.first\fR Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fBsel.last\fR Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fB@\fInumber\fR In this form, \fInumber\fR is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .LP Abbreviations may be used for any of the forms above, e.g. .QW \fBe\fR or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for entry widgets: .TP \fIpathName \fBbbox \fIindex\fR Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .TP | > > > > > > > > > > | > > > > > > > > > > > > > > | > > > > > > > > > | > > > > > > > | > > > | 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 | .SS INDICES .PP Many of the widget commands for entries take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: .TP 12 \fInumber\fR . Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .TP 12 \fBanchor\fR . Indicates the anchor point for the selection, which is set with the \fBselect from\fR and \fBselect adjust\fR widget commands. .TP 12 \fBend\fR . Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. .TP 12 \fBinsert\fR . Indicates the character adjacent to and immediately following the insertion cursor. .TP 12 \fBsel.first\fR . Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fBsel.last\fR . Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fB@\fInumber\fR . In this form, \fInumber\fR is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .LP Abbreviations may be used for any of the forms above, e.g. .QW \fBe\fR or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for entry widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Delete one or more elements of the entry. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the entry's string. .\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR . Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. .\" METHOD: index .TP \fIpathName \fBindex\fI index\fR . Returns the numerical index corresponding to \fIindex\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR . Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on entries. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx\fR . Records \fIx\fR and the current view in the entry window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx\fR . This command computes the difference between its \fIx\fR argument and the \fIx\fR argument to the last \fBscan mark\fR command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the window. The return value is an empty string. .RE .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within an entry. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection adjust \fIindex\fR . Locate the end of the selection nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection is not currently in the entry, then a new selection is created to include the characters between \fIindex\fR and the most recent selection anchor point, inclusive. Returns an empty string. .TP \fIpathName \fBselection clear\fR . Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection from \fIindex\fR . Set the selection anchor point to just before the character given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR . Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR . Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the entry's selection is cleared. .TP \fIpathName \fBselection to \fIindex\fR . If \fIindex\fR is before the anchor point, set the selection to the characters from \fIindex\fR up to but not including the anchor point. If \fIindex\fR is the same as the anchor point, do nothing. If \fIindex\fR is after the anchor point, set the selection to the characters from the anchor point up to but not including \fIindex\fR. The anchor point is determined by the most recent \fBselect from\fR or \fBselect adjust\fR command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE .\" METHOD: validate .TP \fIpathName \fBvalidate\fR . This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the entry's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview\fI index\fR . Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. |
︙ | ︙ |
Changes to doc/event.n.
︙ | ︙ | |||
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | .BE .SH DESCRIPTION .PP The \fBevent\fR command provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. The command has several different forms, determined by the first argument. The following forms are currently supported: .TP \fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? Associates the virtual event \fIvirtual\fR with the physical event sequence(s) given by the \fIsequence\fR arguments, so that the virtual event will trigger whenever any one of the \fIsequence\fRs occurs. \fIVirtual\fR may be any string value and \fIsequence\fR may have any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. If \fIvirtual\fR is already defined, the new physical event sequences add to the existing sequences for the event. .TP | > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > > > | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 | .BE .SH DESCRIPTION .PP The \fBevent\fR command provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. The command has several different forms, determined by the first argument. The following forms are currently supported: .\" METHOD: add .TP \fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? . Associates the virtual event \fIvirtual\fR with the physical event sequence(s) given by the \fIsequence\fR arguments, so that the virtual event will trigger whenever any one of the \fIsequence\fRs occurs. \fIVirtual\fR may be any string value and \fIsequence\fR may have any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. If \fIvirtual\fR is already defined, the new physical event sequences add to the existing sequences for the event. .\" METHOD: delete .TP \fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence sequence ...\fR? . Deletes each of the \fIsequence\fRs from those associated with the virtual event given by \fIvirtual\fR. \fIVirtual\fR may be any string value and \fIsequence\fR may have any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. Any \fIsequence\fRs not currently associated with \fIvirtual\fR are ignored. If no \fIsequence\fR argument is provided, all physical event sequences are removed for \fIvirtual\fR, so that the virtual event will not trigger anymore. .\" METHOD: generate .TP \fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? . Generates a window event and arranges for it to be processed just as if it had come from the window system. \fIWindow\fR gives the path name of the window for which the event will be generated; it may also be an identifier (such as returned by \fBwinfo id\fR) as long as it is for a window in the current application. \fIEvent\fR provides a basic description of the event, such as \fB<Shift-Button-2>\fR or \fB<<Paste>>\fR. If \fIWindow\fR is empty the whole screen is meant, and coordinates are relative to the screen. \fIEvent\fR may have any of the forms allowed for the \fIsequence\fR argument of the \fBbind\fR command except that it must consist of a single event pattern, not a sequence. \fIOption-value\fR pairs may be used to specify additional attributes of the event, such as the x and y mouse position; see \fBEVENT FIELDS\fR below. If the \fB\-when\fR option is not specified, the event is processed immediately: all of the handlers for the event will complete before the \fBevent generate\fR command returns. If the \fB\-when\fR option is specified then it determines when the event is processed. Certain events, such as key events, require that the window has focus to receive the event properly. .\" METHOD: info .TP \fBevent info \fR?\fB<<\fIvirtual\fB>>\fR? . Returns information about virtual events. If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value is a list of all the virtual events that are currently defined. If \fB<<\fIvirtual\fB>>\fR is specified then the return value is a list whose elements are the physical event sequences currently defined for the given virtual event; if the virtual event is not defined then an empty string is returned. .RS .PP Note that virtual events that are not bound to physical event sequences are \fInot\fR returned by \fBevent info\fR. .RE .SH "EVENT FIELDS" .PP The following options are supported for the \fBevent generate\fR command. These correspond to the .QW % expansions allowed in binding scripts for the \fBbind\fR command. .\" OPTION: -above .TP \fB\-above\fI window\fR . \fIWindow\fR specifies the \fIabove\fR field for the event, either as a window path name or as an integer window id. Valid for \fBConfigure\fR events. Corresponds to the \fB%a\fR substitution for binding scripts. .\" OPTION: -borderwidth .TP \fB\-borderwidth\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIborder_width\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%B\fR substitution for binding scripts. .\" OPTION: -button .TP \fB\-button\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIdetail\fR field for a \fBButton\fR or \fBButtonRelease\fR event, overriding any button number provided in the base \fIevent\fR argument. Corresponds to the \fB%b\fR substitution for binding scripts. .\" OPTION: -count .TP \fB\-count\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIcount\fR field for the event. Valid for \fBExpose\fR events. Corresponds to the \fB%c\fR substitution for binding scripts. .\" OPTION: -data .TP \fB\-data\fI string\fR . \fIString\fR may be any value; it specifies the \fIuser_data\fR field for the event. Only valid for virtual events. Corresponds to the \fB%d\fR substitution for virtual events in binding scripts. .\" OPTION: -delta .TP \fB\-delta\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIdelta\fR field for the \fBMouseWheel\fR event. The \fIdelta\fR refers to the direction and magnitude the mouse wheel was rotated. Note the value is not a screen distance but are units of motion in the mouse wheel. Typically these values are multiples of 120. For example, 120 should scroll the text widget up 4 lines and \-240 would scroll the text widget down 8 lines. Of course, other widgets may define different behaviors for mouse wheel motion. This field corresponds to the \fB%D\fR substitution for binding scripts. .\" OPTION: -detail .TP \fB\-detail\fI detail\fR . \fIDetail\fR specifies the \fIdetail\fR field for the event and must be one of the following: .RS .DS .ta 6c \fBNotifyAncestor\fR \fBNotifyNonlinearVirtual\fR \fBNotifyDetailNone\fR \fBNotifyPointer\fR \fBNotifyInferior\fR \fBNotifyPointerRoot\fR \fBNotifyNonlinear\fR \fBNotifyVirtual\fR .DE Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and \fBFocusOut\fR events. Corresponds to the \fB%d\fR substitution for binding scripts. .RE .\" OPTION: -focus .TP \fB\-focus\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR field for the event. Valid for \fBEnter\fR and \fBLeave\fR events. Corresponds to the \fB%f\fR substitution for binding scripts. .\" OPTION: -height .TP \fB\-height\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIheight\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%h\fR substitution for binding scripts. .\" OPTION: -keycode .TP \fB\-keycode\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIkeycode\fR field for the event. Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%k\fR substitution for binding scripts. .\" OPTION: -keysym .TP \fB\-keysym\fI name\fR . \fIName\fR must be the name of a valid keysym, such as \fBg\fR, \fBspace\fR, or \fBReturn\fR; its corresponding keycode value is used as the \fIkeycode\fR field for event, overriding any detail specified in the base \fIevent\fR argument. Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%K\fR substitution for binding scripts. .\" OPTION: -mode .TP \fB\-mode\fI notify\fR . \fINotify\fR specifies the \fImode\fR field for the event and must be one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or \fBNotifyWhileGrabbed\fR. Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events. Corresponds to the \fB%m\fR substitution for binding scripts. .\" OPTION: -override .TP \fB\-override\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIoverride_redirect\fR field for the event. Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. Corresponds to the \fB%o\fR substitution for binding scripts. .\" OPTION: -place .TP \fB\-place\fI where\fR . \fIWhere\fR specifies the \fIplace\fR field for the event; it must be either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid for \fBCirculate\fR events. Corresponds to the \fB%p\fR substitution for binding scripts. .\" OPTION: -root .TP \fB\-root\fI window\fR . \fIWindow\fR must be either a window path name or an integer window identifier; it specifies the \fIroot\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%R\fR substitution for binding scripts. .\" OPTION: -rootx .TP \fB\-rootx\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIx_root\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%X\fR substitution for binding scripts. .\" OPTION: -rooty .TP \fB\-rooty\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIy_root\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%Y\fR substitution for binding scripts. .\" OPTION: -sendevent .TP \fB\-sendevent\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR field for the event. Valid for all events. Corresponds to the \fB%E\fR substitution for binding scripts. .\" OPTION: -serial .TP \fB\-serial\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIserial\fR field for the event. Valid for all events. Corresponds to the \fB%#\fR substitution for binding scripts. .\" OPTION: -state .TP \fB\-state\fI state\fR . \fIState\fR specifies the \fIstate\fR field for the event. For \fBKey\fR, \fBKeyRelease\fR, \fBButtons\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events it must be an integer value. For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR specified in the base \fIevent\fR. Corresponds to the \fB%s\fR substitution for binding scripts. .\" OPTION: -subwindow .TP \fB\-subwindow\fI window\fR . \fIWindow\fR specifies the \fIsubwindow\fR field for the event, either as a path name for a Tk widget or as an integer window identifier. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Similar to \fB%S\fR substitution for binding scripts. .\" OPTION: -time .TP \fB\-time\fI integer\fR . \fIInteger\fR must be an integer value; it specifies the \fItime\fR field for the event. Additionally, the special value \fBcurrent\fR is allowed; this value will be substituted by the current event time. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, and \fBProperty\fR events. Corresponds to the \fB%t\fR substitution for binding scripts. .\" OPTION: -warp .TP \fB\-warp\fI boolean\fR . \fIboolean\fR must be a boolean value; it specifies whether the screen pointer should be warped as well. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events. The pointer will only warp to a window if it is mapped. .\" OPTION: -width .TP \fB\-width\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIwidth\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%w\fR substitution for binding scripts. .\" OPTION: -when .TP \fB\-when\fI when\fR . \fIWhen\fR determines when the event will be processed; it must have one of the following values: .RS .IP \fBnow\fR 10 Process the event immediately, before the command returns. This also happens if the \fB\-when\fR option is omitted. .IP \fBtail\fR 10 Place the event on Tcl's event queue behind any events already queued for this application. .IP \fBhead\fR 10 Place the event at the front of Tcl's event queue, so that it will be handled before any other events already queued. .IP \fBmark\fR 10 Place the event at the front of Tcl's event queue but behind any other events already queued with \fB\-when mark\fR. This option is useful when generating a series of events that should be processed in order but at the front of the queue. .RE .\" OPTION: -x .TP \fB\-x\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIx\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. Corresponds to the \fB%x\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%X\fR substitution for binding scripts. .\" OPTION: -y .TP \fB\-y\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIy\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. Corresponds to the \fB%y\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%Y\fR substitution for binding scripts. .PP Any options that are not specified when generating an event are filled with the value 0, except for \fIserial\fR, which is filled with the next X event serial number. .SH "PREDEFINED VIRTUAL EVENTS" .PP Tk defines the following virtual events for the purposes of notification: .TP \fB<<AltUnderlined>>\fR . This is sent to widget to notify it that the letter it has underlined (as an accelerator indicator) with the \fB\-underline\fR option has been pressed in combination with the Alt key. The usual response to this is to either focus into the widget (or some related widget) or to invoke the widget. .TP \fB<<Invoke>>\fR . This can be sent to some widgets (e.g. button, listbox, menu) as an alternative to <space>. .TP \fB<<ListboxSelect>>\fR . This is sent to a listbox when the set of selected item(s) in the listbox is updated. .TP \fB<<MenuSelect>>\fR . This is sent to a menu when the currently selected item in the menu changes. It is intended for use with context-sensitive help systems. .TP \fB<<Modified>>\fR . This is sent to a text widget when the contents of the widget are changed. .TP \fB<<Selection>>\fR . This is sent to a text widget when the selection in the widget is changed. .TP \fB<<ThemeChanged>>\fR . This is sent to all widgets when the ttk theme changed. The ttk widgets listen to this event and redisplay themselves when it fires. The legacy widgets ignore this event. .TP \fB<<TkWorldChanged>>\fR . This event is sent to all widgets when a font is changed, for example, by the use of [font configure]. The user_data field (%d) will have the value "FontChanged". For other system wide changes, this event will be sent to all widgets, and the user_data field will indicate the cause of the change. NOTE: all tk and ttk widgets already handle this event internally. .TP \fB<<TraverseIn>>\fR . This is sent to a widget when the focus enters the widget because of a user-driven .QW "tab to widget" action. .TP \fB<<TraverseOut>>\fR . This is sent to a widget when the focus leaves the widget because of a user-driven .QW "tab to widget" action. .TP \fB<<UndoStack>>\fR . This is sent to a text widget when its undo stack or redo stack becomes empty or unempty. .TP \fB<<WidgetViewSync>>\fR . This is sent to a text widget when its internal data become obsolete, and again when these internal data are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). .PP Tk defines the following virtual events for the purposes of unifying bindings across multiple platforms. Users expect them to behave in the following way: .TP \fB<<Clear>>\fR . Delete the currently selected widget contents. .TP \fB<<Copy>>\fR . Copy the currently selected widget contents to the clipboard. .TP \fB<<Cut>>\fR . Move the currently selected widget contents to the clipboard. .TP \fB<<LineEnd>>\fR . Move to the end of the line in the current widget while deselecting any selected contents. .TP |
︙ | ︙ | |||
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 | .TP \fB<<NextWord>>\fR . Move to the next group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Paste>>\fR Replace the currently selected widget contents with the contents of the clipboard. .TP \fB<<PasteSelection>>\fR Insert the contents of the selection at the mouse location. (This event has meaningful \fB%x\fR and \fB%y\fR substitutions). .TP \fB<<PrevChar>>\fR . Move to the previous item (i.e., visible character) in the current widget while deselecting any selected contents. .TP \fB<<PrevLine>>\fR . Move to the previous line in the current widget while deselecting any selected contents. .TP \fB<<PrevPara>>\fR . Move to the previous paragraph in the current widget while deselecting any selected contents. .TP \fB<<PrevWindow>>\fR Traverse to the previous window. .TP \fB<<PrevWord>>\fR . Move to the previous group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Redo>>\fR Redo one undone action. .TP \fB<<SelectAll>>\fR . Set the range of selected contents to the complete widget. .TP \fB<<SelectLineEnd>>\fR | > > > > | 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 | .TP \fB<<NextWord>>\fR . Move to the next group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Paste>>\fR . Replace the currently selected widget contents with the contents of the clipboard. .TP \fB<<PasteSelection>>\fR . Insert the contents of the selection at the mouse location. (This event has meaningful \fB%x\fR and \fB%y\fR substitutions). .TP \fB<<PrevChar>>\fR . Move to the previous item (i.e., visible character) in the current widget while deselecting any selected contents. .TP \fB<<PrevLine>>\fR . Move to the previous line in the current widget while deselecting any selected contents. .TP \fB<<PrevPara>>\fR . Move to the previous paragraph in the current widget while deselecting any selected contents. .TP \fB<<PrevWindow>>\fR . Traverse to the previous window. .TP \fB<<PrevWord>>\fR . Move to the previous group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Redo>>\fR . Redo one undone action. .TP \fB<<SelectAll>>\fR . Set the range of selected contents to the complete widget. .TP \fB<<SelectLineEnd>>\fR |
︙ | ︙ |
Changes to doc/focus.n.
︙ | ︙ | |||
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | implement a focus order among the windows of a top-level; they are used in the default bindings for Tab and Shift-Tab, among other things. .PP The \fBfocus\fR command can take any of the following forms: .TP \fBfocus\fR Returns the path name of the focus window on the display containing the application's main window, or an empty string if no window in this application has the focus on that display. Note: it is better to specify the display explicitly using \fB\-displayof\fR (see below) so that the code will work in applications using multiple displays. .TP \fBfocus \fIwindow\fR If the application currently has the input focus on \fIwindow\fR's display, this command resets the input focus for \fIwindow\fR's display to \fIwindow\fR and returns an empty string. If the application does not currently have the input focus on \fIwindow\fR's display, \fIwindow\fR will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to \fIwindow\fR. If \fIwindow\fR is an empty string then the command does nothing. .TP | > > | > > | > | 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | implement a focus order among the windows of a top-level; they are used in the default bindings for Tab and Shift-Tab, among other things. .PP The \fBfocus\fR command can take any of the following forms: .TP \fBfocus\fR . Returns the path name of the focus window on the display containing the application's main window, or an empty string if no window in this application has the focus on that display. Note: it is better to specify the display explicitly using \fB\-displayof\fR (see below) so that the code will work in applications using multiple displays. .TP \fBfocus \fIwindow\fR . If the application currently has the input focus on \fIwindow\fR's display, this command resets the input focus for \fIwindow\fR's display to \fIwindow\fR and returns an empty string. If the application does not currently have the input focus on \fIwindow\fR's display, \fIwindow\fR will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to \fIwindow\fR. If \fIwindow\fR is an empty string then the command does nothing. .TP \fBfocus \-displayof \fIwindow\fR . Returns the name of the focus window on the display containing \fIwindow\fR. If the focus window for \fIwindow\fR's display is not in this application, the return value is an empty string. .TP \fBfocus \-force \fIwindow\fR . Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if the application does not currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. If \fIwindow\fR is an empty string then the command does nothing. .TP \fBfocus \-lastfor \fIwindow\fR . Returns the name of the most recent window to have the input focus among all the windows in the same top-level as \fIwindow\fR. If no window in that top-level has ever had the input focus, or if the most recent focus window has been deleted, then the name of the top-level is returned. The return value is the window that will receive the input focus the next time the window manager gives the focus to the top-level. |
︙ | ︙ | |||
105 106 107 108 109 110 111 112 | the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. .SH "EXAMPLE" .PP To make a window that only participates in the focus traversal ring when a variable is set, add the following bindings to the widgets \fIbefore\fR and \fIafter\fR it in that focus ring: .CS | > | | | | | | | 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. .SH "EXAMPLE" .PP To make a window that only participates in the focus traversal ring when a variable is set, add the following bindings to the widgets \fIbefore\fR and \fIafter\fR it in that focus ring: .PP .CS button .before -text "Before" button .middle -text "Middle" button .after -text "After" checkbutton .flag -variable traverseToMiddle -takefocus 0 pack .flag -side left pack .before .middle .after bind .before <Tab> { if {!$traverseToMiddle} { \fBfocus\fR .after break } } bind .after <Shift-Tab> { if {!$traverseToMiddle} { \fBfocus\fR .before break } } \fBfocus\fR .before .CE .SH KEYWORDS events, focus, keyboard, top-level, window manager '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/focusNext.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 15 | .TH tk_focusNext n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus. .SH SYNOPSIS \fBtk_focusNext \fIwindow\fR | > < < > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .TH tk_focusNext n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus. .SH SYNOPSIS .nf \fBtk_focusNext \fIwindow\fR \fBtk_focusPrev \fIwindow\fR \fBtk_focusFollowsMouse\fR .fi .BE .SH DESCRIPTION .PP \fBtk_focusNext\fR is a utility procedure used for keyboard traversal. It returns the .QW next window after \fIwindow\fR in focus order. The focus order is determined by |
︙ | ︙ | |||
45 46 47 48 49 50 51 | \fBtk_focusFollowsMouse\fR changes the focus model for the application to an implicit one where the window under the mouse gets the focus. After this procedure is called, whenever the mouse enters a window Tk will automatically give it the input focus. The \fBfocus\fR command may be used to move the focus to a window other than the one under the mouse, but as soon as the mouse moves into a new window the focus will jump to that window. | > | | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | \fBtk_focusFollowsMouse\fR changes the focus model for the application to an implicit one where the window under the mouse gets the focus. After this procedure is called, whenever the mouse enters a window Tk will automatically give it the input focus. The \fBfocus\fR command may be used to move the focus to a window other than the one under the mouse, but as soon as the mouse moves into a new window the focus will jump to that window. .PP Note that at present there is no built-in support for returning the application to an explicit focus model; to do this you will have to write a script that deletes the bindings created by \fBtk_focusFollowsMouse\fR. .SH KEYWORDS focus, keyboard traversal, top-level '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/font.n.
︙ | ︙ | |||
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | .BE .SH DESCRIPTION .PP The \fBfont\fR command provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: .TP \fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR? . Returns information about the actual attributes that are obtained when \fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained may differ from the attributes requested due to platform-dependent limitations, such as the availability of font families and point sizes. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See \fBFONT OPTIONS\fR below for a list of the possible attributes. If the \fIchar\fR argument is supplied, it must be a single character. The font attributes returned will be those of the specific font used to render that character, which will be different from the base font if the base font does not contain the given character. If \fIchar\fR may be a hyphen, it should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled \fIoption\fR. .TP \fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the desired attributes for the named font called \fIfontname\fR. If no \fIoption\fR is specified, returns a list describing all the options and their values for \fIfontname\fR. If a single \fIoption\fR is specified with no \fIvalue\fR, then returns the current value of that attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, then the command modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .RS .PP Note that on Aqua/Mac OS X, the system fonts (see \fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they are implemented by the system theme. To achieve the effect of modification, use \fBfont actual\fR to get their configuration and \fBfont create\fR to synthesize a copy of the font which can be modified. .RE .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . Creates a new named font and returns its name. \fIfontname\fR specifies the name for the font; if it is omitted, then Tk generates a new name of the form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for the new named font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .TP | > > > > | > > > > > | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | .BE .SH DESCRIPTION .PP The \fBfont\fR command provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: .\" METHOD: actual .TP \fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR? . Returns information about the actual attributes that are obtained when \fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained may differ from the attributes requested due to platform-dependent limitations, such as the availability of font families and point sizes. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See \fBFONT OPTIONS\fR below for a list of the possible attributes. If the \fIchar\fR argument is supplied, it must be a single character. The font attributes returned will be those of the specific font used to render that character, which will be different from the base font if the base font does not contain the given character. If \fIchar\fR may be a hyphen, it should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled \fIoption\fR. .\" METHOD: configure .TP \fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the desired attributes for the named font called \fIfontname\fR. If no \fIoption\fR is specified, returns a list describing all the options and their values for \fIfontname\fR. If a single \fIoption\fR is specified with no \fIvalue\fR, then returns the current value of that attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, then the command modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .RS .PP Note that on Aqua/Mac OS X, the system fonts (see \fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they are implemented by the system theme. To achieve the effect of modification, use \fBfont actual\fR to get their configuration and \fBfont create\fR to synthesize a copy of the font which can be modified. .RE .\" METHOD: create .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . Creates a new named font and returns its name. \fIfontname\fR specifies the name for the font; if it is omitted, then Tk generates a new name of the form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for the new named font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .\" METHOD: delete .TP \fBfont delete\fI fontname\fR ?\fIfontname ...\fR? . Delete the specified named fonts. If there are widgets using the named font, the named font will not actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to \fBfont create\fR, the widgets will use the new named font and redisplay themselves using the new attributes of that font. .\" METHOD: families .TP \fBfont families\fR ?\fB\-displayof \fIwindow\fR? . The return value is a list of the case-insensitive names of all font families that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is omitted, it defaults to the main window. .\" METHOD: measure .TP \fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR . Measures the amount of space the string \fItext\fR would use in the given \fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. The return value is the total width in pixels of \fItext\fR, not including the extra pixels used by highly exaggerated characters such as cursive .QW f . If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. .\" METHOD: metrics .TP \fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? . Returns information about the metrics (the font-specific data), for \fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See \fBFONT METRICS\fR below for a list of the possible metrics. .\" METHOD: names .TP \fBfont names\fR . The return value is a list of all the named fonts that are currently defined. .SH "FONT DESCRIPTIONS" .PP The following formats are accepted as a font description anywhere \fIfont\fR is specified as an argument above; these same forms are also permitted when specifying the \fB\-font\fR option for widgets. .TP |
︙ | ︙ | |||
196 197 198 199 200 201 202 203 | font. In the following definitions, the .QW baseline of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case .QW g stick below the baseline. .TP | > | > | > > | > > > > > > > > > < | < < | < < | < < | < < | < < | < < | < < | < < | < > > > | 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 | font. In the following definitions, the .QW baseline of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case .QW g stick below the baseline. .\" OPTION: -ascent .TP \fB\-ascent\fR . The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. .\" OPTION: -descent .TP \fB\-descent\fR . The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. .\" OPTION: -linespace .TP \fB\-linespace\fR . Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. .\" OPTION: -fixed .TP \fB\-fixed\fR . Returns a boolean flag that is .QW \fB1\fR if this is a fixed-width font, where each normal character is the same width as all the other characters, or is .QW \fB0\fR if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. .SH "FONT OPTIONS" .PP The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: .\" OPTION: -family .TP \fB\-family \fIname\fR . The case-insensitive font family name. Tk guarantees to support the font families named \fBCourier\fR (a monospaced .QW typewriter font), \fBTimes\fR (a serifed .QW newspaper font), and \fBHelvetica\fR (a sans-serif .QW European font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The \fIname\fR may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. .\" OPTION: -size .TP \fB\-size \fIsize\fR . The desired size of the font. If the \fIsize\fR argument is a positive number, it is interpreted as a size in points. If \fIsize\fR is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default size will be chosen. .RS .PP Sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. However, specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap. The mapping between points and pixels is set when the application starts, based on properties of the installed monitor, but it can be overridden by calling the \fBtk scaling\fR command. .RE .\" OPTION: -weight .TP \fB\-weight \fIweight\fR . The nominal thickness of the characters in the font. The value \fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is \fBnormal\fR. .\" OPTION: -slant .TP \fB\-slant \fIslant\fR . The amount the characters in the font are slanted away from the vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is \fBroman\fR. .\" OPTION: -underline .TP \fB\-underline \fIboolean\fR . The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is \fBfalse\fR. .\" OPTION: -overstrike .TP \fB\-overstrike \fIboolean\fR . The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is \fBfalse\fR. .SH "STANDARD FONTS" .PP The following named fonts are supported on all systems, and default to values that match appropriate system defaults. .IP \fBTkDefaultFont\fR This font is the default for all GUI items not otherwise specified. .IP \fBTkTextFont\fR This font should be used for user text in entry widgets, listboxes etc. .IP \fBTkFixedFont\fR This font is the standard fixed-width font. .IP \fBTkMenuFont\fR This font is used for menu items. .IP \fBTkHeadingFont\fR This font should be used for column headings in lists and tables. .IP \fBTkCaptionFont\fR This font should be used for window and dialog caption bars. .IP \fBTkSmallCaptionFont\fR This font should be used for captions on contained windows or tool dialogs. .IP \fBTkIconFont\fR This font should be used for icon captions. .IP \fBTkTooltipFont\fR This font should be used for tooltip windows (transient information windows). .LP It is \fInot\fR advised to change these fonts, as they may be modified by Tk itself in response to system changes. Instead, make a copy of the font and modify that. .SH "PLATFORM SPECIFIC FONTS" .PP The following system fonts are supported: .TP \fBX Windows\fR . All valid X font names, including those listed by xlsfonts(1), are available. .TP \fBMS Windows\fR . The following fonts are supported, and are mapped to the user's style defaults. .RS .DS .ta 3c 6c \fBsystem\fR \fBansi\fR \fBdevice\fR \fBsystemfixed\fR \fBansifixed\fR \fBoemfixed\fR .DE .RE .TP \fBMac OS X\fR . The following fonts are supported, and are mapped to the user's style defaults. .RS .DS .ta 3c 6c \fBsystem\fR \fBapplication\fR \fBmenu\fR .DE |
︙ | ︙ | |||
382 383 384 385 386 387 388 | .DE .RE .SH EXAMPLE .PP Fill a text widget with lots of font demonstrators, one for every font family installed on your system: .CS | | | | | | | | | | 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 | .DE .RE .SH EXAMPLE .PP Fill a text widget with lots of font demonstrators, one for every font family installed on your system: .CS pack [text .t -wrap none] -fill both -expand 1 set count 0 set tabwidth 0 foreach family [lsort -dictionary [\fBfont families\fR]] { .t tag configure f[incr count] -font [list $family 10] .t insert end ${family}:\et {} \e "This is a simple sampler\en" f$count set w [\fBfont measure\fR [.t cget -font] ${family}:] if {$w + 5 > $tabwidth} { set tabwidth [expr {$w + 5}] .t configure -tabs $tabwidth } } .CE .SH "SEE ALSO" options(n) .SH KEYWORDS font '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/fontchooser.n.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | '\" '\" Copyright (c) 2008 Daniel A. Steffen <[email protected]> '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH fontchooser n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME fontchooser \- control font selection dialog .SH SYNOPSIS \fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR? | > < < > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | '\" '\" Copyright (c) 2008 Daniel A. Steffen <[email protected]> '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH fontchooser n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME fontchooser \- control font selection dialog .SH SYNOPSIS .nf \fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR? \fBtk fontchooser\fR \fBshow\fR \fBtk fontchooser\fR \fBhide\fR .fi .BE .SH DESCRIPTION .PP The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses the native platform font selection dialog where available, or a dialog implemented in Tcl otherwise. .PP Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not return an immediate result, as on some platforms (Mac OS X) the standard font dialog is modeless while on others (Windows) it is modal. To accommodate this difference, all user interaction with the dialog will be communicated to the caller via callbacks or virtual events. .PP The \fBtk fontchooser\fR command can have one of the following forms: .\" METHOD: configure .TP \fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value ...\fR? . Set or query one or more of the configurations options below (analogous to Tk widget configuration). .\" METHOD: show .TP \fBtk fontchooser\fR \fBshow\fR . Show the font selection dialog. Depending on the platform, may return immediately or only once the dialog has been withdrawn. .\" METHOD: hide .TP \fBtk fontchooser\fR \fBhide\fR . Hide the font selection dialog if it is visible and cause any pending \fBtk fontchooser\fR \fBshow\fR command to return. .PP .SH "CONFIGURATION OPTIONS" .\" OPTION: -parent .TP \fB\-parent\fR . Specifies/returns the logical parent window of the font selection dialog (similar to the \fB\-parent\fR option to other dialogs). The font selection dialog is hidden if it is visible when the parent window is destroyed. .\" OPTION: -title .TP \fB\-title\fR . Specifies/returns the title of the dialog. Has no effect on platforms where the font selection dialog does not support titles. .\" OPTION: -font .TP \fB\-font\fR . Specifies/returns the font that is currently selected in the dialog if it is visible, or that will be initially selected when the dialog is shown (if supported by the platform). Can be set to the empty string to indicate that no font should be selected. Fonts can be specified in any form given by the "FONT DESCRIPTION" section in the \fBfont\fR manual page. .\" OPTION: -command .TP \fB\-command\fR . Specifies/returns the command prefix to be called when a font selection has been made by the user. The command prefix is evaluated at the global level after having the specification of the selected font appended. On platforms where the font selection dialog offers the user control of further font attributes (such as color), additional key/value pairs may be appended before evaluation. Can be set to the empty string to indicate that no callback should be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" section in the \fBfont\fR manual page (i.e. a list of the form \fI{family size style ?style ...?}\fR). .\" OPTION: -visible .TP \fB\-visible\fR . Read-only option that returns a boolean indicating whether the font selection dialog is currently visible. Attempting to set this option results in an error. .PP .SH "VIRTUAL EVENTS" .TP \fB<<TkFontchooserVisibility>>\fR . Sent to the dialog parent whenever the visibility of the font selection dialog changes, both as a result of user action (e.g. disposing of the dialog via OK/Cancel button or close box) and of the \fBtk fontchooser\fR \fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the current visibility of the dialog by querying the \fB\-visible\fR configuration option. .TP \fB<<TkFontchooserFontChanged>>\fR . Sent to the dialog parent whenever the font selection dialog is visible and the selected font changes, both as a result of user action and of the \fB\-font\fR configuration option being set. Binding scripts can determine the currently selected font by querying the \fB\-font\fR configuration option. .PP .SH NOTES .PP |
︙ | ︙ | |||
135 136 137 138 139 140 141 | to ensure its selected font matches the new value of the named font. .PP .SH EXAMPLE .PP .CS proc fontchooserDemo {} { wm title . "Font Chooser Demo" | | | | | | | | | | | | | | 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | to ensure its selected font matches the new value of the named font. .PP .SH EXAMPLE .PP .CS proc fontchooserDemo {} { wm title . "Font Chooser Demo" \fBtk fontchooser\fR \fBconfigure\fR -parent . button .b -command fontchooserToggle -takefocus 0 fontchooserVisibility .b bind . \fB<<TkFontchooserVisibility>>\fR \e [list fontchooserVisibility .b] foreach w {.t1 .t2} { text $w -width 20 -height 4 -borderwidth 1 -relief solid bind $w <FocusIn> [list fontchooserFocus $w] $w insert end "Text Widget $w" } .t1 configure -font {Courier 14} .t2 configure -font {Times 16} pack .b .t1 .t2; focus .t1 } proc fontchooserToggle {} { \fBtk fontchooser\fR [expr { [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "\fBhide\fR" : "\fBshow\fR"}] } proc fontchooserVisibility {w} { $w configure -text [expr { [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "Hide Font Dialog" : "Show Font Dialog"}] } proc fontchooserFocus {w} { \fBtk fontchooser\fR \fBconfigure\fR -font [$w cget -font] \e -command [list fontchooserFontSelection $w] } proc fontchooserFontSelection {w font args} { $w configure -font [font actual $font] } fontchooserDemo .CE .SH "SEE ALSO" font(n), tk(n) .SH KEYWORDS dialog, font, font selection, font chooser, font panel '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/frame.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH frame n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME frame \- Create and manipulate 'frame' simple container widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH frame n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME frame \- Create and manipulate 'frame' simple container widgets .SH SYNOPSIS \fBframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief \-highlightbackground \-padx \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background |
︙ | ︙ | |||
123 124 125 126 127 128 129 130 | \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the frame widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .TP | > | > | 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 | \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the frame widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBframe\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified |
︙ | ︙ |
Changes to doc/getOpenFile.n.
︙ | ︙ | |||
30 31 32 33 34 35 36 37 | The \fBtk_getSaveFile\fR command is usually associated with the \fBSave as\fR command in the \fBFile\fR menu. If the user enters a file that already exists, the dialog box prompts the user for confirmation whether the existing file should be overwritten or not. .PP The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: .TP | > | > > | > > | > | > | > | > | > | > | > | > | | 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | The \fBtk_getSaveFile\fR command is usually associated with the \fBSave as\fR command in the \fBFile\fR menu. If the user enters a file that already exists, the dialog box prompts the user for confirmation whether the existing file should be overwritten or not. .PP The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on Mac OS X. .\" OPTION: -confirmoverwrite .TP \fB\-confirmoverwrite\fI boolean\fR . Configures how the Save dialog reacts when the selected file already exists, and saving would overwrite it. A true value requests a confirmation dialog be presented to the user. A false value requests that the overwrite take place without confirmation. Default value is true. .\" OPTION: -defaultextension .TP \fB\-defaultextension\fI extension\fR . Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on Mac OS X, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. .\" OPTION: -filetypes .TP \fB\-filetypes\fI filePatternList\fR . If a \fBFile types\fR listbox exists in the file dialog on the particular platform, this option gives the \fIfiletype\fRs in this listbox. When the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the empty list, or if the \fBFile types\fR listbox is not supported by the particular platform then all files are listed regardless of their types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. .\" OPTION: -initialdir .TP \fB\-initialdir\fI directory\fR . Specifies that the files in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .\" OPTION: -initialfile .TP \fB\-initialfile\fI filename\fR . Specifies a filename to be displayed in the dialog when it pops up. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. .\" OPTION: -multiple .TP \fB\-multiple\fI boolean\fR . Allows the user to choose multiple files from the Open dialog. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the file dialog. The file dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\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: -typevariable .TP \fB\-typevariable\fI variableName\fR . The global variable \fIvariableName\fR is used to preselect which filter is used from \fIfilterList\fR when the dialog box is opened and is updated when the dialog box is closed, to the last selected filter. The variable is read once at the beginning to select the appropriate filter. If the variable does not exist, or its value does not match any filter typename, or is empty (\fB{}\fR), the dialog box |
︙ | ︙ | |||
188 189 190 191 192 193 194 | {{Text Files} {.txt} } {{TCL Scripts} {.tcl} } {{C Source Files} {.c} TEXT} {{GIF Files} {.gif} } {{GIF Files} {} GIFF} {{All Files} * } } | | | 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | {{Text Files} {.txt} } {{TCL Scripts} {.tcl} } {{C Source Files} {.c} TEXT} {{GIF Files} {.gif} } {{GIF Files} {} GIFF} {{All Files} * } } set filename [\fBtk_getOpenFile\fR -filetypes $types] if {$filename ne ""} { # Open the file ... } .CE .SH "SEE ALSO" tk_chooseDirectory .SH KEYWORDS file selection dialog '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/grab.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 15 | .TH grab n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME grab \- Confine pointer and keyboard events to a window sub-tree .SH SYNOPSIS \fBgrab \fR?\fB\-global\fR? \fIwindow\fR | > < > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .TH grab n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME grab \- Confine pointer and keyboard events to a window sub-tree .SH SYNOPSIS .nf \fBgrab \fR?\fB\-global\fR? \fIwindow\fR \fBgrab \fIoption \fR?\fIarg \fR...? .fi .BE .SH DESCRIPTION .PP This command implements simple pointer and keyboard grabs for Tk. Tk's grabs are different than the grabs described in the Xlib documentation. When a grab is set for a particular window, Tk restricts all pointer |
︙ | ︙ | |||
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 | It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once. .PP The \fBgrab\fR command can take any of the following forms: .TP \fBgrab \fR?\fB\-global\fR? \fIwindow\fR Same as \fBgrab set\fR, described below. .TP \fBgrab current \fR?\fIwindow\fR? If \fIwindow\fR is specified, returns the name of the current grab window in this application for \fIwindow\fR's display, or an empty string if there is no such window. If \fIwindow\fR is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs. .TP \fBgrab release \fIwindow\fR Releases the grab on \fIwindow\fR if there is one, otherwise does nothing. Returns an empty string. .TP \fBgrab set \fR?\fB\-global\fR? \fIwindow\fR Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on \fIwindow\fR's display then it is automatically released. If there is already a grab on \fIwindow\fR and it has the same global/local form as the requested grab, then the command does nothing. Returns an empty string. .TP \fBgrab status \fIwindow\fR Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. .SH WARNING .PP It is very easy to use global grabs to render a display completely unusable (e.g. by setting a grab on a widget which does not respond to | > > > > > > > > > | 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once. .PP The \fBgrab\fR command can take any of the following forms: .TP \fBgrab \fR?\fB\-global\fR? \fIwindow\fR . Same as \fBgrab set\fR, described below. .\" METHOD: current .TP \fBgrab current \fR?\fIwindow\fR? . If \fIwindow\fR is specified, returns the name of the current grab window in this application for \fIwindow\fR's display, or an empty string if there is no such window. If \fIwindow\fR is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs. .\" METHOD: release .TP \fBgrab release \fIwindow\fR . Releases the grab on \fIwindow\fR if there is one, otherwise does nothing. Returns an empty string. .\" METHOD: set .TP \fBgrab set \fR?\fB\-global\fR? \fIwindow\fR . Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on \fIwindow\fR's display then it is automatically released. If there is already a grab on \fIwindow\fR and it has the same global/local form as the requested grab, then the command does nothing. Returns an empty string. .\" METHOD: status .TP \fBgrab status \fIwindow\fR . Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. .SH WARNING .PP It is very easy to use global grabs to render a display completely unusable (e.g. by setting a grab on a widget which does not respond to |
︙ | ︙ | |||
132 133 134 135 136 137 138 | processes, this restriction does not exist. .SH EXAMPLE .PP Set a grab so that only one button may be clicked out of a group. The other buttons are unresponsive to the mouse until the middle button is clicked. .CS | | | | | 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | processes, this restriction does not exist. .SH EXAMPLE .PP Set a grab so that only one button may be clicked out of a group. The other buttons are unresponsive to the mouse until the middle button is clicked. .CS pack [button .b1 -text "Click me! #1" -command {destroy .b1}] pack [button .b2 -text "Click me! #2" -command {destroy .b2}] pack [button .b3 -text "Click me! #3" -command {destroy .b3}] \fBgrab\fR .b2 .CE .SH "SEE ALSO" busy(n) .SH KEYWORDS grab, keyboard events, pointer events, window '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/grid.n.
︙ | ︙ | |||
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | \fBgrid \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . If the first argument to \fBgrid\fR is suitable as the first window argument to \fBgrid configure\fR, either a window name (any value starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR (see the \fBRELATIVE PLACEMENT\fR section below), then the command is processed in the same way as \fBgrid configure\fR. .TP \fBgrid anchor \fIwindow\fR ?\fIanchor\fR? . The anchor value controls how to place the grid within the container window when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below for further details. The default \fIanchor\fR is \fInw\fR. .TP \fBgrid bbox \fIwindow\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? . With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the container window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR arguments are specified, then the bounding box spanning the rows and columns indicated is returned. .TP \fBgrid columnconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the column properties of the \fIindex\fR column of the geometry container, \fIwindow\fR. The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR and \fB\-pad\fR. | > > > | 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | \fBgrid \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . If the first argument to \fBgrid\fR is suitable as the first window argument to \fBgrid configure\fR, either a window name (any value starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR (see the \fBRELATIVE PLACEMENT\fR section below), then the command is processed in the same way as \fBgrid configure\fR. .\" METHOD: anchor .TP \fBgrid anchor \fIwindow\fR ?\fIanchor\fR? . The anchor value controls how to place the grid within the container window when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below for further details. The default \fIanchor\fR is \fInw\fR. .\" METHOD: bbox .TP \fBgrid bbox \fIwindow\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? . With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the container window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR arguments are specified, then the bounding box spanning the rows and columns indicated is returned. .\" METHOD: columnconfigure .TP \fBgrid columnconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the column properties of the \fIindex\fR column of the geometry container, \fIwindow\fR. The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR and \fB\-pad\fR. |
︙ | ︙ | |||
78 79 80 81 82 83 84 | The \fB\-pad\fR option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of | | > > > > > > > > > > > | 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 | The \fB\-pad\fR option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of .QW "\fI\-option value\fR" pairs. .\" METHOD: configure .TP \fBgrid configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. The characters \fB\-\fR, \fBx\fR and \fB^\fR, can be specified instead of a window name to alter the default location of a \fIwindow\fR, as described in the \fBRELATIVE PLACEMENT\fR section, below. The following options are supported: .RS .\" OPTION: -column .TP \fB\-column \fIn\fR . Insert the window so that it occupies the \fIn\fRth column in the grid. Column numbers start with 0. If this option is not supplied, then the window is arranged just to the right of previous window specified on this call to \fBgrid\fR, or column .QW 0 if it is the first window. For each \fBx\fR that immediately precedes the \fIwindow\fR, the column position is incremented by one. Thus the \fBx\fR represents a blank column for this row in the grid. .\" OPTION: -columnspan .TP \fB\-columnspan \fIn\fR . Insert the window so that it occupies \fIn\fR columns in the grid. The default is one column, unless the window name is followed by a \fB\-\fR, in which case the columnspan is incremented once for each immediately following \fB\-\fR. .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . Insert the window(s) in the container window given by \fIcontainer\fR. The default is the first window's parent window. .\" OPTION: -ipadx .TP \fB\-ipadx \fIamount\fR . The \fIamount\fR specifies how much horizontal internal padding to leave on each side of the content. This is space is added inside the content border. The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. It defaults to 0. .\" OPTION: -ipady .TP \fB\-ipady \fIamount\fR . The \fIamount\fR specifies how much vertical internal padding to leave on the top and bottom of the content. This space is added inside the content border. The \fIamount\fR defaults to 0. .\" OPTION: -padx .TP \fB\-padx \fIamount\fR . The \fIamount\fR specifies how much horizontal external padding to leave on each side of the content, in screen units. \fIAmount\fR may be a list of two values to specify padding for left and right separately. The \fIamount\fR defaults to 0. This space is added outside the content border. .\" OPTION: -pady .TP \fB\-pady \fIamount\fR . The \fIamount\fR specifies how much vertical external padding to leave on the top and bottom of the content, in screen units. \fIAmount\fR may be a list of two values to specify padding for top and bottom separately. The \fIamount\fR defaults to 0. This space is added outside the content border. .\" OPTION: -row .TP \fB\-row \fIn\fR . Insert the content so that it occupies the \fIn\fRth row in the grid. Row numbers start with 0. If this option is not supplied, then the content is arranged on the same row as the previous content specified on this call to \fBgrid\fR, or the next row after the highest occupied row if this is the first content. .\" OPTION: -rowspan .TP \fB\-rowspan \fIn\fR . Insert the content so that it occupies \fIn\fR rows in the grid. The default is one row. If the next \fBgrid\fR command contains \fB^\fR characters instead of \fIcontent\fR that line up with the columns of this \fIcontent\fR, then the \fBrowspan\fR of this \fIcontent\fR is extended by one. .\" OPTION: -sticky .TP \fB\-sticky \fIstyle\fR . If a content's cell is larger than its requested dimensions, this option may be used to position (or stretch) the content within its cell. \fIStyle\fR is a string that contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. |
︙ | ︙ | |||
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | .QW "" , which causes the content to be centered in its cavity, at its requested size. .LP If any of the content is already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE .TP \fBgrid forget \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. The configuration options for that window are forgotten, so that if the window is managed once more by the grid geometry manager, the initial default settings are used. .RS .PP .VS "TIP 518" | > > > > > > > > > > | | > > | | | | > > > > > | | | | 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | .QW "" , which causes the content to be centered in its cavity, at its requested size. .LP If any of the content is already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE .\" METHOD: content .TP \fBgrid content \fIwindow\fR ?\fI\-option value\fR? . If no options are supplied, a list of all of the content in \fIwindow\fR is returned, most recently managed first. \fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which causes only the content in the row (or column) specified by \fIvalue\fR to be returned. .\" METHOD: forget .TP \fBgrid forget \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. The configuration options for that window are forgotten, so that if the window is managed once more by the grid geometry manager, the initial default settings are used. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: info .TP \fBgrid info \fIwindow\fR . Returns a list whose elements are the current configuration state of the content given by \fIwindow\fR in the same option-value form that might be specified to \fBgrid configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the windows's container window. .\" METHOD: location .TP \fBgrid location \fIwindow x y\fR . Given \fIx\fR and \fIy\fR values in screen units relative to the container window, the column and row number at that \fIx\fR and \fIy\fR location is returned. For locations that are above or to the left of the grid, \fB\-1\fR is returned. .\" METHOD: propagate .TP \fBgrid propagate \fIwindow\fR ?\fIboolean\fR? . If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fIwindow\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). If \fIboolean\fR has a false boolean value then propagation is disabled for \fIwindow\fR. In either of these cases an empty string is returned. If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIwindow\fR. .RS .PP Propagation is enabled by default. .RE .\" METHOD: rowconfigure .TP \fBgrid rowconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the row properties of the \fIindex\fR row of the geometry container, \fIwindow\fR. The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR and \fB\-pad\fR. If one or more options are provided, then \fIindex\fR may be given as a list of row indices to which the configuration options will operate on. Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR the options apply to all rows currently occupied by content windows. For a window name, that window must be a content window of this container and the options apply to all rows currently occupied by the container window. The \fB\-minsize\fR option sets the minimum size, in screen units, that will be permitted for this row. The \fB\-weight\fR option (an integer value) sets the relative weight for apportioning any extra spaces among rows. A weight of zero (0) indicates the row will not deviate from its requested |
︙ | ︙ | |||
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 | grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of .QW "-option value" pairs. .TP \fBgrid remove \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. However, the configuration options for that window are remembered, so that if the content window is managed once more by the grid geometry manager, the previous values are retained. .RS .PP .VS "TIP 518" | > | | | > < < | < < < < < < | < | | | < | < < | < | | | 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 | grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of .QW "-option value" pairs. .\" METHOD: remove .TP \fBgrid remove \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. However, the configuration options for that window are remembered, so that if the content window is managed once more by the grid geometry manager, the previous values are retained. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: size .TP \fBgrid size \fIcontainer\fR . Returns the size of the grid (in columns then rows) for \fIcontainer\fR. The size is determined either by the \fIcontent\fR occupying the largest row or column, or the largest column or row with a \fB\-minsize\fR, \fB\-weight\fR, or \fB\-pad\fR that is non-zero. .\" METHOD: slaves .TP \fBgrid slaves \fIwindow\fR ?\fI\-option value\fR? . Synonym for \fBgrid content \fIwindow\fR ?\fI\-option value\fR?. .SH "RELATIVE PLACEMENT" .PP The \fBgrid\fR command contains a limited set of capabilities that permit layouts to be created without specifying the row and column information for each content. This permits content to be rearranged, added, or removed without the need to explicitly specify row and column information. When no column or row information is specified for a \fIcontent\fR, default values are chosen for \fB\-column\fR, \fB\-row\fR, \fB\-columnspan\fR and \fB\-rowspan\fR at the time the \fIcontent\fR is managed. The values are chosen based upon the current layout of the grid, the position of the \fIcontent\fR relative to other \fIcontent\fRs in the same grid command, and the presence of the characters \fB\-\fR, \fBx\fR, and \fB^\fR in \fBgrid\fR command where \fIcontent\fR names are normally expected. .RS .IP \fB\-\fR This increases the \fB\-columnspan\fR of the \fIcontent\fR to the left. Several \fB\-\fR's in a row will successively increase the number of columns spanned. A \fB\-\fR may not follow a \fB^\fR or a \fBx\fR, nor may it be the first \fIcontent\fR argument to \fBgrid configure\fR. .IP \fBx\fR This leaves an empty column between the \fIcontent\fR on the left and the \fIcontent\fR on the right. .IP \fB^\fR This extends the \fB\-rowspan\fR of the \fIcontent\fR above the \fB^\fR's in the grid. The number of \fB^\fR's in a row must match the number of columns spanned by the \fIcontent\fR above it. .RE .SH "THE GRID ALGORITHM" .PP The grid geometry manager lays out its content in three steps. In the first step, the minimum size needed to fit all of the content is computed, then (if propagation is turned on), a request is made of the container window to become that size. In the second step, the requested size is compared against the actual size of the container. If the sizes are different, then spaces is added to or taken away from the layout as needed. For the final step, each content is positioned in its row(s) and column(s) based on the setting of its \fIsticky\fR flag. .PP To compute the minimum size of a layout, the grid geometry manager first looks at all content whose \fB\-columnspan\fR and \fB\-rowspan\fR values are one, and computes the nominal size of each row or column to be either the \fIminsize\fR for that row or column, or the sum of the \fIpad\fRding plus the size of the largest content, whichever is greater. After that the rows or columns in each uniform group adapt to each other. Then the content whose row-spans or column-spans are greater than one are examined. If a group of rows or columns need to be increased in size in order to accommodate these content, then extra space is added to each |
︙ | ︙ | |||
437 438 439 440 441 442 443 | .SH EXAMPLES .PP A toplevel window containing a text widget and two scrollbars: .PP .CS # Make the widgets toplevel .t | | | | | | | | | | | | | | 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 | .SH EXAMPLES .PP A toplevel window containing a text widget and two scrollbars: .PP .CS # Make the widgets toplevel .t text .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set} scrollbar .t.v -orient vertical -command {.t.txt yview} scrollbar .t.h -orient horizontal -command {.t.txt xview} # Lay them out \fBgrid\fR .t.txt .t.v -sticky nsew \fBgrid\fR .t.h -sticky nsew # Tell the text widget to take all the extra room \fBgrid rowconfigure\fR .t .t.txt -weight 1 \fBgrid columnconfigure\fR .t .t.txt -weight 1 .CE .PP Three widgets of equal width, despite their different .QW natural widths: .PP .CS button .b -text "Foo" entry .e -textvariable foo ; set foo "Hello World!" label .l -text "This is a fairly long piece of text" \fBgrid\fR .b .e .l -sticky ew \fBgrid columnconfigure\fR . "all" -uniform allTheSame .CE .SH "SEE ALSO" pack(n), place(n) .SH KEYWORDS geometry manager, location, grid, cell, propagation, size, pack '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/image.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH image n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME image \- Create and manipulate images .SH SYNOPSIS | | > > > > > > > > > > > > > > > > < | < | < | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | .TH image n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME image \- Create and manipulate images .SH SYNOPSIS \fBimage\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBimage\fR command is used to create, delete, and query images. It can take several different forms, depending on the \fIoption\fR argument. The legal forms are: .\" METHOD: create .TP \fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? . Creates a new image and a command with the same name and returns its name. \fItype\fR specifies the type of the image, which must be one of the types currently defined (e.g., \fBbitmap\fR). \fIname\fR specifies the name for the image; if it is omitted then Tk picks a name of the form \fBimage\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide configuration options for the new image. The legal set of options is defined separately for each image type; see below for details on the options for built-in image types. If an image already exists by the given name then it is replaced with the new image and any instances of that image will redisplay with the new contents. It is important to note that the image command will silently overwrite any procedure that may currently be defined by the given name, so choose the name wisely. It is recommended to use a separate namespace for image names (e.g., \fB::img::logo\fR, \fB::img::large\fR). .\" METHOD: delete .TP \fBimage delete \fR?\fIname name\fR ...? . Deletes each of the named images and returns an empty string. If there are instances of the images displayed in widgets, the images will not actually be deleted until all of the instances are released. However, the association between the instances and the image manager will be dropped. Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated with another call to \fBimage create\fR, the existing instances will use the new image. .\" METHOD: height .TP \fBimage height \fIname\fR . Returns a decimal string giving the height of image \fIname\fR in pixels. .\" METHOD: inuse .TP \fBimage inuse \fIname\fR . Returns a boolean value indicating whether or not the image given by \fIname\fR is in use by any widgets. .\" METHOD: names .TP \fBimage names\fR . Returns a list containing the names of all existing images. .\" METHOD: type .TP \fBimage type \fIname\fR . Returns the type of image \fIname\fR (the value of the \fItype\fR argument to \fBimage create\fR when the image was created). .\" METHOD: types .TP \fBimage types\fR . Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the \fItype\fR argument to \fBimage create\fR). .\" METHOD: width .TP \fBimage width \fIname\fR . Returns a decimal string giving the width of image \fIname\fR in pixels. .PP Additional operations (e.g. writing the image to a file) may be available as subcommands of the image instance command. See the manual page for the particular image type for details. .SH "BUILT-IN IMAGE TYPES" .PP The following image types are defined by Tk so they will be available in any Tk application. Individual applications or extensions may define additional types. .IP \fBbitmap\fR Each pixel in the image displays a foreground color, a background color, or nothing. See the \fBbitmap\fR manual entry for more information. .IP \fBphoto\fR Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. .IP \fBnsimage\fR This type is only available in the Aqua platform. It is a full-color image which may be created from a named system image. It has options designed to facilitate the use of these images in buttons. An \fBnsimage\fR can be based on an a \fItemplate image\fR, which is an anti-aliased 2-color image format that automatically interchanges black and white in response to changes between the light and dark modes on macOS. An \fBnsimage\fR can also generate an alternate |
︙ | ︙ |
Changes to doc/label.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH label n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME label \- Create and manipulate 'label' non-interactive text or image widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH label n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME label \- Create and manipulate 'label' non-interactive text or image widgets .SH SYNOPSIS \fBlabel\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable |
︙ | ︙ | |||
76 77 78 79 80 81 82 83 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for label widgets: .TP | > | > > > | | | | | | | | | | 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for label widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabel\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlabel\fR command. .SH BINDINGS .PP When a new label is created, it has no default event bindings: labels are not intended to be interactive. .SH EXAMPLE .PP .CS # Make the widgets \fBlabel\fR .t -text "This widget is at the top" -bg red \fBlabel\fR .b -text "This widget is at the bottom" -bg green \fBlabel\fR .l -text "Left\enHand\enSide" \fBlabel\fR .r -text "Right\enHand\enSide" text .mid \&.mid insert end "This layout is like Java's BorderLayout" # Lay them out pack .t -side top -fill x pack .b -side bottom -fill x pack .l -side left -fill y pack .r -side right -fill y pack .mid -expand 1 -fill both .CE .SH "SEE ALSO" labelframe(n), button(n), ttk::label(n) .SH KEYWORDS label, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/labelframe.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH labelframe n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME labelframe \- Create and manipulate 'labelframe' labelled container widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH labelframe n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME labelframe \- Create and manipulate 'labelframe' labelled container widgets .SH SYNOPSIS \fBlabelframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightbackground \-pady \-cursor \-highlightcolor \-relief \-font \-highlightthickness \-takefocus \-foreground \-padx \-text .SE .SH "WIDGET-SPECIFIC OPTIONS" |
︙ | ︙ | |||
97 98 99 100 101 102 103 104 | .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .TP | > | > > > | 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabelframe\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If |
︙ | ︙ | |||
128 129 130 131 132 133 134 | .SH EXAMPLE .PP This shows how to build part of a GUI for a hamburger vendor. The \fBlabelframe\fR widgets are used to organize the available choices by the kinds of things that the choices are being made over. .PP .CS | | | | | | 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | .SH EXAMPLE .PP This shows how to build part of a GUI for a hamburger vendor. The \fBlabelframe\fR widgets are used to organize the available choices by the kinds of things that the choices are being made over. .PP .CS grid [\fBlabelframe\fR .burger -text "Burger"] \e [\fBlabelframe\fR .bun -text "Bun"] -sticky news grid [\fBlabelframe\fR .cheese -text "Cheese Option"] \e [\fBlabelframe\fR .pickle -text "Pickle Option"] -sticky news foreach {type name val} { burger Beef beef burger Lamb lamb burger Vegetarian beans bun Plain white bun Sesame seeds |
︙ | ︙ | |||
153 154 155 156 157 158 159 | cheese "Monterey Jack" jack pickle None none pickle Gherkins gherkins pickle Onions onion pickle Chili chili } { | | | | | 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | cheese "Monterey Jack" jack pickle None none pickle Gherkins gherkins pickle Onions onion pickle Chili chili } { set w [radiobutton .$type.$val -text $name -anchor w \e -variable $type -value $val] pack $w -side top -fill x } set burger beef set bun white set cheese none set pickle none .CE .SH "SEE ALSO" frame(n), label(n), ttk::labelframe(n) .SH KEYWORDS labelframe, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/listbox.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH listbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME listbox \- Create and manipulate 'listbox' item list widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH listbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME listbox \- Create and manipulate 'listbox' item list widgets .SH SYNOPSIS \fBlistbox\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-disabledforeground \-exportselection \-font \-foreground \-highlightbackground \-highlightcolor \-highlightthickness \-justify \-relief \-selectbackground \-selectborderwidth \-selectforeground \-setgrid \-takefocus \-xscrollcommand |
︙ | ︙ | |||
91 92 93 94 95 96 97 | They also support scanning, as described below. .SH "INDICES" .PP Many of the widget commands for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways: | < | < < | < < | < < | < < | | > | > | > | > > > > > > > > > > > > > > | | 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 | They also support scanning, as described below. .SH "INDICES" .PP Many of the widget commands for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways: .IP \fInumber\fR 12 Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox. .IP \fBactive\fR 12 Indicates the element that has the location cursor. This element will be displayed as specified by \fB\-activestyle\fR when the listbox has the keyboard focus, and it is specified with the \fBactivate\fR widget command. .IP \fBanchor\fR 12 Indicates the anchor point for the selection, which is set with the \fBselection anchor\fR widget command. .IP \fBend\fR 12 Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as \fBindex\fR and \fBinsert\fR it refers to the element just after the last one. .IP \fB@\fIx\fB,\fIy\fR 12 Indicates the element that covers the point in the listbox window specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no element covers that point, then the closest element to that point is used. .PP Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. In the widget command descriptions below, arguments named \fIindex\fR, \fIfirst\fR, and \fIlast\fR always contain text indices in one of the above forms. .SH "WIDGET COMMAND" .PP The \fBlistbox\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for listbox widgets: .\" METHOD: activate .TP \fIpathName \fBactivate\fI index\fR . Sets the active element to the one indicated by \fIindex\fR. If \fIindex\fR is outside the range of elements in the listbox then the closest element is activated. The active element is drawn as specified by \fB\-activestyle\fR when the widget has the input focus, and its index may be retrieved with the index \fBactive\fR. .\" METHOD: bbox .TP \fIpathName \fBbbox\fI index\fR . Returns a list of four numbers describing the bounding box of the text in the element given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by \fIindex\fR is visible on the screen, or if \fIindex\fR refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. .\" METHOD: curselection .TP \fIpathName \fBcurselection\fR . Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR are indices specifying the first and last elements in the range to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR, i.e. a single element is deleted. .\" METHOD: get .TP \fIpathName \fBget \fIfirst\fR ?\fIlast\fR? . If \fIlast\fR is omitted, returns the contents of the listbox element indicated by \fIfirst\fR, or an empty string if \fIfirst\fR refers to a non-existent element. If \fIlast\fR is specified, the command returns a list whose elements are all of the listbox elements between \fIfirst\fR and \fIlast\fR, inclusive. Both \fIfirst\fR and \fIlast\fR may have any of the standard forms for indices. .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the integer index value that corresponds to \fIindex\fR. If \fIindex\fR is \fBend\fR the return value is a count of the number of elements in the listbox (not the index of the last element). .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? . Inserts zero or more new elements in the list just before the element given by \fIindex\fR. If \fIindex\fR is specified as \fBend\fR then the new elements are added to the end of the list. Returns an empty string. .\" METHOD: itemcget .TP \fIpathName \fBitemcget \fIindex option\fR . Returns the current value of the item configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBitemconfigure\fR command. .\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . Query or modify the configuration options of an item in the listbox. If no \fIoption\fR is specified, returns a list describing all of the available options for the item (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are currently supported for items: .RS .\" OPTION: -background .TP \fB\-background \fIcolor\fR . \fIColor\fR specifies the background color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . \fIColor\fR specifies the foreground color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -selectbackground .TP \fB\-selectbackground \fIcolor\fR . \fIcolor\fR specifies the background color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -selectforeground .TP \fB\-selectforeground \fIcolor\fR . \fIcolor\fR specifies the foreground color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .RE .\" METHOD: nearest .TP \fIpathName \fBnearest \fIy\fR . Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on listboxes. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR . |
︙ | ︙ | |||
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 | \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. .RE .TP \fIpathName \fBsee \fIindex\fR . Adjust the view in the listbox so that the element given by \fIindex\fR is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within a listbox. It has several forms, depending on \fIoption\fR: .RS .TP | > > | 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 | \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. .RE .\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . Adjust the view in the listbox so that the element given by \fIindex\fR is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within a listbox. It has several forms, depending on \fIoption\fR: .RS .TP |
︙ | ︙ | |||
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | .TP \fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? . Selects all of the elements in the range between \fIfirst\fR and \fIlast\fR, inclusive, without affecting the selection state of elements outside that range. .RE .TP \fIpathName \fBsize\fR . Returns a decimal string indicating the total number of elements in the listbox. .TP \fIpathName \fBxview \fR?\fIargs\fR . This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: .RS | > > | 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | .TP \fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? . Selects all of the elements in the range between \fIfirst\fR and \fIlast\fR, inclusive, without affecting the selection state of elements outside that range. .RE .\" METHOD: size .TP \fIpathName \fBsize\fR . Returns a decimal string indicating the total number of elements in the listbox. .\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR . This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: .RS |
︙ | ︙ | |||
395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR character units (the width of the \fB0\fR character) on the display. .RE .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. | > > | 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR character units (the width of the \fB0\fR character) on the display. .RE .\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR . Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. |
︙ | ︙ |
Changes to doc/loadTk.n.
1 2 3 4 5 6 7 8 9 10 11 12 13 | '\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | '\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS \fBsafe::loadTk \fIchild\fR ?\fB\-use\fI windowId\fR? ?\fB\-display\fI displayName\fR? .BE .SH DESCRIPTION .PP Safe Tk is based on Safe Tcl, which provides a mechanism that allows restricted and mediated access to auto-loading and packages for safe interpreters. Safe Tk adds the ability to configure the interpreter for safe Tk operations and load Tk into safe interpreters. .PP The \fBsafe::loadTk\fR command initializes the required data structures in the named safe interpreter and then loads Tk into it. The interpreter must have been created with \fBsafe::interpCreate\fR or have been initialized with \fBsafe::interpInit\fR. The command returns the name of the safe interpreter. If \fB\-use\fR is specified, the window identified by the specified system dependent identifier \fIwindowId\fR is used to contain the .QW . window of the safe interpreter; it can be any valid id, eventually referencing a window belonging to another application. As a convenience, if the window you plan to use is a Tk Window of the application you can use the window name (e.g., .QW \fB.x.y\fR ) instead of its window Id (e.g., from \fBwinfo id\fI .x.y\fR). When \fB\-use\fR is not specified, a new toplevel window is created for the .QW . window of the safe interpreter. On X11 if you want the embedded window to use another display than the default one, specify it with \fB\-display\fR. See the \fBSECURITY ISSUES\fR section below for implementation details. .SH "SECURITY ISSUES" .PP Please read the \fBsafe\fR manual page for Tcl to learn about the basic security considerations for Safe Tcl. .PP \fBsafe::loadTk\fR adds the value of \fBtk_library\fR taken from the parent interpreter to the virtual access path of the safe interpreter so that auto-loading will work in the safe interpreter. .PP Tk initialization is now safe with respect to not trusting the child's state for startup. \fBsafe::loadTk\fR registers the child's name so when the Tk initialization (\fBTk_SafeInit\fR) is called and in turn calls the parent's \fBsafe::InitTk\fR it will return the desired \fBargv\fR equivalent (\fB\-use\fI windowId\fR, correct \fB\-display\fR, etc.) .PP When \fB\-use\fR is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes from a potentially unsafe code and can easily delete the corresponding interpreter. .PP On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely to generate a fatal X error. |
︙ | ︙ |
Changes to doc/menu.n.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars .SH SYNOPSIS .nf | | | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars .SH SYNOPSIS .nf \fBmenu\fI pathName \fR?\fIoptions\fR? \fBtk_menuSetFocus\fI pathName\fR .fi .SO \-activebackground \-borderwidth \-foreground \-activeborderwidth \-cursor \-relief \-activeforeground \-disabledforeground \-takefocus \-background \-font \-activerelief .SE .SH "WIDGET-SPECIFIC OPTIONS" |
︙ | ︙ | |||
308 309 310 311 312 313 314 | \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .PP Many of the widget commands for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called \fIindex\fRes and may be specified in any of the following forms: | < | < < | < < | < < | < < < < < < < | < < | < < | < < | < > | > > > > > > > > > | > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > | 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 | \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .PP Many of the widget commands for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called \fIindex\fRes and may be specified in any of the following forms: .IP \fBactive\fR 12 Indicates the entry that is currently active. If no entry is active then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .IP \fBend\fR 12 Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .IP \fBlast\fR 12 Same as \fBend\fR. .IP \fB{}\fR 12 Indicates .QW "no entry at all" ; this is used most commonly with the \fBactivate\fR option to deactivate all the entries in the menu. In most cases the specification of \fB{}\fR causes nothing to happen in the widget command. .IP \fB@\fIx\fB,\fIy\fR 12 Indicates the entry that covers the point in the menu's window specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no entry covers that point, then this form is equivalent to \fB{}\fR. If only a single number is specified, it is treated as the y-coordinate. .IP \fInumber\fR 12 Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. .IP \fIid\fR 12 If the index does not satisfy one of the above forms then the menu is searched for an entry with the specified id. .IP \fIpattern\fR 12 If all of the above methods for finding an entry fail, this form is used. \fIPattern\fR is pattern-matched against the label of each entry in the menu, in order from the top down, until a matching entry is found. The rules of \fBstring match\fR are used. .PP If the index could match more than one of the above forms, then the form earlier in the above list takes precedence. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .PP The following widget commands are possible for menu widgets: .\" METHOD: activate .TP \fIpathName \fBactivate \fIindex\fR . Change the state of the entry indicated by \fIindex\fR to \fBactive\fR and redisplay it using its active colors. Any previously-active entry is deactivated. If \fIindex\fR is specified as \fB{}\fR, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string. .\" METHOD: add .TP \fIpathName \fBadd \fItype \fR?\fIid\fR? ?\fIoption value option value ...\fR? . Add a new entry to the bottom of the menu. The new entry's type is given by \fItype\fR and must be one of \fBcascade\fR, \fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, or a unique abbreviation of one of the above. If the \fIid\fR argument is specified, it is used as the entry identifier; \fIid\fR must not already exist in the menu. Otherwise, a new unique identifier is generated. If additional arguments are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR section below. The \fBadd\fR widget command returns the id of the new entry. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. .\" METHOD: clone .TP \fIpathName \fBclone \fInewPathname\fR ?\fIcloneType\fR? . Makes a clone of the current menu named \fInewPathName\fR. This clone is a menu in its own right, but any changes to the clone are propagated to the original menu and vice versa. \fIcloneType\fR can be \fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be called outside of the Tk library. See the \fBCLONES\fR section for more information. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? . Delete all of the menu entries between \fIindex1\fR and \fIindex2\fR inclusive. If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. Attempts to delete a tear-off menu entry are ignored (instead, you should change the \fB\-tearoff\fR option to remove the tear-off entry). .\" METHOD: entrycget .TP \fIpathName \fBentrycget \fIindex option\fR . Returns the current value of a configuration option for the entry given by \fIindex\fR. \fIOption\fR may have any of the names described in the \fBMENU ENTRY OPTIONS\fR section below. .\" METHOD: entryconfigure .TP \fIpathName \fBentryconfigure \fIindex \fR?\fIoptions...\fR? . This command is similar to the \fBconfigure\fR command, except that it applies to the options for an individual entry, whereas \fBconfigure\fR applies to the options for the menu as a whole. \fIOptions\fR may have any of the values described in the \fBMENU ENTRY OPTIONS\fR section below. If \fIoptions\fR are specified, options are modified as indicated in the command and the command returns an empty string. If no \fIoptions\fR are specified, returns a list describing the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). .\" METHOD: id .TP \fIpathName \fBid \fIindex\fR . Returns the id of the menu entry given by \fIindex\fR. This is the identifier that was assigned to the entry when it was created using the \fBadd\fR or \fBinsert\fR widget command. Returns an empty string for the tear-off entry, or if \fIindex\fR is equivalent to \fB{}\fR. .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the numerical index corresponding to \fIindex\fR, or \fB{}\fR if \fIindex\fR was specified as \fB{}\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex type \fR?\fIid\fR? ?\fIoption value option value ...\fR? . Same as the \fBadd\fR widget command except that it inserts the new entry just before the entry given by \fIindex\fR, instead of appending to the end of the menu. The \fItype\fR, \fIid\fR, \fIoption\fR, and \fIvalue\fR arguments have the same interpretation as for the \fBadd\fR widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one. The \fBinsert\fR widget command returns the id of the new entry. .\" METHOD: invoke .TP \fIpathName \fBinvoke \fIindex\fR . Invoke the action of the menu entry. See the sections on the individual entries above for details on what happens. If the menu entry is disabled then nothing happens. If the entry has a command associated with it then the result of that command is returned as the result of the \fBinvoke\fR widget command. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the \fBinvoke\fR widget command. .\" METHOD: post .TP \fIpathName \fBpost \fIx y\fR ?\fIindex\fR? . Arrange for the menu to be displayed on the screen at the root-window coordinates given by \fIx\fR and \fIy\fR. If an index is specified the menu will be located so that the entry with that index is displayed at the point. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen. This command normally returns an empty string. If the \fB\-postcommand\fR option has been specified, then its value is executed as a Tcl script before posting the menu and the result of that script is returned as the result of the \fBpost\fR widget command. If an error returns while executing the command, then the error is returned without posting the menu. .\" METHOD: postcascade .TP \fIpathName \fBpostcascade \fIindex\fR . Posts the submenu associated with the cascade entry given by \fIindex\fR, and unposts any previously posted submenu. If \fIindex\fR does not correspond to a cascade entry, or if \fIpathName\fR is not posted, the command has no effect except to unpost any currently posted submenu. .\" METHOD: type .TP \fIpathName \fBtype \fIindex\fR . Returns the type of the menu entry given by \fIindex\fR. This is the \fItype\fR argument passed to the \fBadd\fR or \fBinsert\fR widget command when the entry was created, such as \fBcommand\fR or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. .\" METHOD: unpost .TP \fIpathName \fBunpost\fR . Unmap the window so that it is no longer displayed. If a lower-level cascaded menu is posted, unpost that menu. Returns an empty string. This subcommand does not work on Windows and the Macintosh, as those platforms have their own way of unposting menus. .\" METHOD: xposition .TP \fIpathName \fBxposition \fIindex\fR . Returns a decimal string giving the x-coordinate within the menu window of the leftmost pixel in the entry specified by \fIindex\fR. .\" METHOD: yposition .TP \fIpathName \fByposition \fIindex\fR . Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by \fIindex\fR. .SH "MENU ENTRY OPTIONS" The following options are allowed on menu entries. Most options are not supported by all entry types. .\" OPTION: -activebackground .TP \fB\-activebackground \fIvalue\fR . Specifies a background color to use for displaying this entry when it is active. This option is ignored on Aqua/MacOS. If it is specified as an empty string (the default), then the \fB\-activebackground\fR option for the overall menu is used. If the \fBtk_strictMotif\fR variable has been set to request strict Motif compliance, then this option is ignored and the \fB\-background\fR option is used in its place. This option is not available for separator or tear-off entries. .\" OPTION: -activeforeground .TP \fB\-activeforeground \fIvalue\fR . Specifies a foreground color to use for displaying this entry when it is active. This option is ignored on Aqua/macOS. If this option is specified as an empty string (the default), then the \fB\-activeforeground\fR option for the overall menu is used. .\" OPTION: -accelerator .TP \fB\-accelerator \fIvalue\fR . Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be used to invoke the same function as the menu entry. This is a display option, it does not actually set the corresponding binding (which can be achieved using the \fBbind\fR command). This option is not available for separator or tear-off entries. .\" OPTION: -background .TP \fB\-background \fIvalue\fR . Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-background\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -bitmap .TP \fB\-bitmap \fIvalue\fR . Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by \fBTk_GetBitmap\fR. This option overrides the \fB\-label\fR option (as controlled by the \fB\-compound\fR option) but may be reset to an empty string to enable a textual label to be displayed. If a \fB\-image\fR option has been specified, it overrides \fB\-bitmap\fR. This option is not available for separator or tear-off entries. .\" OPTION: -columnbreak .TP \fB\-columnbreak \fIvalue\fR . When this option is zero, the entry appears below the previous entry. When this option is one, the entry appears at the top of a new column in the menu. This option is ignored on Aqua/macOS, where menus are always a single column. .\" OPTION: -command .TP \fB\-command \fIvalue\fR . Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. .\" OPTION: -compound .TP \fB\-compound \fIvalue\fR . Specifies whether the menu entry should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are \fBbottom\fR, \fBcenter\fR, \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value is \fBnone\fR, meaning that the button will display either an image or text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR options. .\" OPTION: -font .TP \fB\-font \fIvalue\fR . Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the \fB\-font\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -foreground .TP \fB\-foreground \fIvalue\fR . Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-foreground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -hidemargin .TP \fB\-hidemargin \fIvalue\fR . Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used. .\" OPTION: -image .TP \fB\-image \fIvalue\fR . Specifies an image to display in the menu instead of a text string or bitmap. The image must have been created by some previous invocation of \fBimage create\fR. This option overrides the \fB\-label\fR and \fB\-bitmap\fR options (as controlled by the \fB\-compound\fR option) but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries. .\" OPTION: -indicatoron .TP \fB\-indicatoron \fIvalue\fR . Available only for checkbutton and radiobutton entries. \fIValue\fR is a boolean that determines whether or not the indicator should be displayed. .\" OPTION: -label .TP \fB\-label \fIvalue\fR . Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries. .\" OPTION: -menu .TP \fB\-menu \fIvalue\fR . Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu. .\" OPTION: -offvalue .TP \fB\-offvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected. .\" OPTION: -onvalue .TP \fB\-onvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. .\" OPTION: -selectcolor .TP \fB\-selectcolor \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the \fB\-selectcolor\fR option for the menu determines the indicator color. .\" OPTION: -selectimage .TP \fB\-selectimage \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the \fB\-image\fR option) when it is selected. \fIValue\fR is the name of an image, which must have been created by some previous invocation of \fBimage create\fR. This option is ignored unless the \fB\-image\fR option has been specified. .\" OPTION: -state .TP \fB\-state \fIvalue\fR . Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the entry is displayed using the \fB\-foreground\fR option for the menu and the \fB\-background\fR option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the \fB\-activeforeground\fR option for the menu along with the \fB\-activebackground\fR option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the \fB\-disabledforeground\fR option for the menu and the \fB\-background\fR option from the entry. This option is not available for separator entries. .\" OPTION: -underline .TP \fB\-underline \fIvalue\fR . Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. 0 corresponds to the first character of the text displayed in the entry, 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries. .\" OPTION: -value .TP \fB\-value \fIvalue\fR . Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the \fB\-label\fR option for the entry as the value to store in the variable. .\" OPTION: -variable .TP \fB\-variable \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies the name of a global variable to set when the entry is selected. For checkbutton entries the variable is also set when the entry is deselected. For radiobutton entries, changing the variable |
︙ | ︙ |
Changes to doc/menubutton.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH menubutton n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH menubutton n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets .SH SYNOPSIS \fBmenubutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable |
︙ | ︙ | |||
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for menubutton widgets: .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified | > > | 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for menubutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified |
︙ | ︙ |
Changes to doc/message.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH message n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME message \- Create and manipulate 'message' non-interactive text widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH message n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME message \- Create and manipulate 'message' non-interactive text widgets .SH SYNOPSIS \fBmessage\fI pathName \fR?\fIoptions\fR? .SO \-anchor \-background \-borderwidth \-cursor \-font \-foreground \-highlightbackground \-highlightcolor \-highlightthickness \-padx \-pady \-relief \-takefocus \-text \-textvariable .SE |
︙ | ︙ | |||
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for message widgets: .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified | > > | 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for message widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified |
︙ | ︙ |
Changes to doc/messageBox.n.
︙ | ︙ | |||
19 20 21 22 23 24 25 26 | application-specified message, an icon and a set of buttons. Each of the buttons in the message window is identified by a unique symbolic name (see the \fB\-type\fR options). After the message window is popped up, \fBtk_messageBox\fR waits for the user to select one of the buttons. Then it returns the symbolic name of the selected button. .PP The following option-value pairs are supported: .TP | > | > > | > | > | > | > | > | > | < | < < | < < | < < | < < | < < | < | | | | | | | 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | application-specified message, an icon and a set of buttons. Each of the buttons in the message window is identified by a unique symbolic name (see the \fB\-type\fR options). After the message window is popped up, \fBtk_messageBox\fR waits for the user to select one of the buttons. Then it returns the symbolic name of the selected button. .PP The following option-value pairs are supported: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog. The actual command consists of \fIstring\fR followed by a space and the name of the button clicked by the user to close the dialog. This is only available on Mac OS X. .\" OPTION: -default .TP \fB\-default\fI name\fR . \fIName\fR gives the symbolic name of the default button for this message window ( .QW ok , .QW cancel , and so on). See \fB\-type\fR for a list of the symbolic names. If this option is not specified, the first button in the dialog will be made the default. .\" OPTION: -detail .TP \fB\-detail\fI string\fR . Specifies an auxiliary message to the main message given by the \fB\-message\fR option. The message detail will be presented beneath the main message and, where supported by the OS, in a less emphasized font than the main message. .\" OPTION: -icon .TP \fB\-icon\fI iconImage\fR . Specifies an icon to display. \fIIconImage\fR must be one of the following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or \fBwarning\fR. If this option is not specified, then the info icon will be displayed. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies the message to display in this message box. The default value is an empty string. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the message box. The message box is displayed on top of its parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the message box. The default value is an empty string. .\" OPTION: -type .TP \fB\-type\fI predefinedType\fR . Arranges for a predefined set of buttons to be displayed. The following values are possible for \fIpredefinedType\fR: .RS .IP \fBabortretryignore\fR 18 Displays three buttons whose symbolic names are \fBabort\fR, \fBretry\fR and \fBignore\fR. .IP \fBok\fR 18 Displays one button whose symbolic name is \fBok\fR. .IP \fBokcancel\fR 18 Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR. .IP \fBretrycancel\fR 18 Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR. .IP \fByesno\fR 18 Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR. .IP \fByesnocancel\fR 18 Displays three buttons whose symbolic names are \fByes\fR, \fBno\fR and \fBcancel\fR. .RE .PP .SH EXAMPLE .PP .CS set answer [\fBtk_messageBox\fR -message "Really quit?" \e -icon question -type yesno \e -detail "Select \e"Yes\e" to make the application exit"] switch -- $answer { yes exit no {\fBtk_messageBox\fR -message "I know you like this application!" \e -type ok} } .CE .SH KEYWORDS message box '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/nsimage.n.
︙ | ︙ | |||
22 23 24 25 26 27 28 29 | \fBimage create nsimage \fR?\fIname\fR? ?\fIoption value ...\fR? .PP creates a new nsimage and a command with the same name and returns its name. .SH OPTIONS .PP Valid \fIoptions\fR are: .TP | > | > | | | | < | < > | < < | < < | < > > | > | > | > | > | | > | > | | 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | \fBimage create nsimage \fR?\fIname\fR? ?\fIoption value ...\fR? .PP creates a new nsimage and a command with the same name and returns its name. .SH OPTIONS .PP Valid \fIoptions\fR are: .\" OPTION: -source .TP \fB\-source\fI string\fR .PP The value of the \fB\-source\fR option is a string describing an NSimage. There are several ways to interpret this string, and the interpretation is determined by the value of the \fB\-as\fR option. This option is required. .PP .\" OPTION: -as .TP \fB\-as\fI type\fR .PP There are four possible values for the \fB\-as\fR option which specify how the source string should be interpreted. The allowed values and their meanings are: .RS .IP \fBname\fR The source should be interpreted as the name of a named NSImage provided by the system. This is the default if the \fB\-as\fR option is not specified. .IP \fBfile\fR The source should be interpreted as a path to an image file in one of the formats understood by the NSImage class. .IP \fBpath\fR The source should be interpreted as a path to an arbitrary file. The type of the file will be examined and the resulting image will be the system icon for files of that type. .IP \fBfiletype\fR The source is interpreted as a string identifying a particular file type. It may be a filename extension, an Apple Uniform Type Identifier or a 4-character OSType value as used in the HFS filesystem. .RE .\" OPTION: -width .TP \fB\-width\fI pixels\fR .PP The value of the \fIwidth\fR option is an integer specifying the width in pixels of the nsimage. If the width is not specified it will be computed from the height so as to preserve the aspect ration. If neither width nor height are specified then the width and height of the underlying NSImage will be used. .\" OPTION: -height .TP \fB\-height\fI pixels\fR .PP The value of the \fIheight\fR option is an integer specifying the height in pixels of the nsimage. If the height is not specified it will be computed from the height so as to preserve the aspect ration. If neither width nor height are specified then the width and height of the underlying NSImage will be used. .\" OPTION: -radius .TP \fB\-radius\fI pixels\fR .PP The value of the \fIradius\fR option is an integer. If non-zero the image will be clipped to a rounded rectangle with the same width and height as the image, but with circular arcs of the specified radius cutting off the corners of the rectangle. .\" OPTION: -ring .TP \fB\-ring\fI pixels\fR .PP The value of the \fIring\fR option is an integer. If non-zero then it specifies the thickness of a focus ring which will be drawn around the image using the control accent color specified in the System Preferences. The image is resized to reduce its width and height by twice the thickness of the ring. Note that this may create a small amount of distortion. The aspect ration of a non-square image will change slightly. .\" OPTION: -alpha .TP \fB\-alpha\fI float\fR .PP The value of the \fIalpha\fR option should be a floating point number between 0.0 and 1.0. This alpha value will be applied to each pixel of the nsimage, producing a partially transparent image. The default value is 1.0, which makes the image opaque. .\" OPTION: -pressed .TP \fB\-pressed\fI boolean\fR .PP The \fIpressed\fR option takes a boolean value. If the value is true or 1 then the image will be algorithmically modified to become darker in light mode or lighter in dark mode. The default is false. For an image button, the primary image should use the value false while the pressed image should be the same image but with the \fIpressed\fR option set to true. .\" OPTION: -template .TP \fB\-template\fI boolean\fR .PP The \fItemplate\fR option takes a boolean value. If the value is true or 1 then the image will be marked as being a template image. This means that the system will algorithmically convert the image to a light colored image when in dark mode. For the algorithm to work correctly the image must consist only of black pixels with alpha values. |
︙ | ︙ |
Changes to doc/option.n.
︙ | ︙ | |||
18 19 20 21 22 23 24 | \fBoption get \fIwindow name class\fR \fBoption readfile \fIfileName \fR?\fIpriority\fR? .fi .BE .SH DESCRIPTION .PP The \fBoption\fR command allows you to add entries to the Tk option | | > | > > > < | < | < | < | | 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | \fBoption get \fIwindow name class\fR \fBoption readfile \fIfileName \fR?\fIpriority\fR? .fi .BE .SH DESCRIPTION .PP The \fBoption\fR command allows you to add entries to the Tk option database or to retrieve options from the database. .\" METHOD: add The \fBadd\fR form of the command adds a new option to the database. \fIPattern\fR contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format (see \fBPATTERN FORMAT\fR). \fIValue\fR contains a text string to associate with \fIpattern\fR; this is the value that will be returned in calls to \fBTk_GetOption\fR or by invocations of the \fBoption get\fR command. If \fIpriority\fR is specified, it indicates the priority level for this option (see below for legal values); it defaults to \fBinteractive\fR. This command always returns an empty string. .PP .\" METHOD: clear The \fBoption clear\fR command clears the option database. Default options (from the \fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR file) will be reloaded automatically the next time an option is added to the database or removed from it. This command always returns an empty string. .PP .\" METHOD: get The \fBoption get\fR command returns the value of the option specified for \fIwindow\fR under \fIname\fR and \fIclass\fR. If several entries in the option database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then the command returns whichever was created with highest \fIpriority\fR level. If there are several matching entries at the same priority level, then it returns whichever entry was most recently entered into the option database. If there are no matching entries, then the empty string is returned. .PP .\" METHOD: readfile The \fBreadfile\fR form of the command reads \fIfileName\fR, which should have the standard format for an X resource database such as \fB.Xdefaults\fR, and adds all the options specified in that file to the option database. If \fIpriority\fR is specified, it indicates the priority level at which to enter the options; \fIpriority\fR defaults to \fBinteractive\fR. .PP The file is read through a channel which is in "utf-8" encoding, invalid byte sequences are automatically converted to valid ones. This means that encodings like ISO 8859-1 or cp1252 with high probability will work as well, but this cannot be guaranteed. This cannot be changed, setting the [encoding system] has no effect. .PP The \fIpriority\fR arguments to the \fBoption\fR command are normally specified symbolically using one of the following values: .IP \fBwidgetDefault\fR3 Level 20. Used for default values hard-coded into widgets. .IP \fBstartupFile\fR Level 40. Used for options specified in application-specific startup files. .IP \fBuserDefault\fR Level 60. Used for options specified in user-specific defaults files, such as \fB.Xdefaults\fR, resource databases loaded into the X server, or user-specific startup files. .IP \fBinteractive\fR Level 80. Used for options specified interactively after the application starts running. If \fIpriority\fR is not specified, it defaults to this level. .PP Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority |
︙ | ︙ |
Changes to doc/options.n.
︙ | ︙ | |||
56 57 58 59 60 61 62 | This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). .OP \-activeforeground activeForeground Background Specifies foreground color to use when drawing active elements. See above for definition of active elements. .OP \-activerelief activeRelief Relief Specifies the 3-D effect desired for the active item of the widget. | | | 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). .OP \-activeforeground activeForeground Background Specifies foreground color to use when drawing active elements. See above for definition of active elements. .OP \-activerelief activeRelief Relief Specifies the 3-D effect desired for the active item of the widget. See the \fB\-relief\fR option for details. .OP \-anchor anchor Anchor Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. For example, \fBnw\fR means display the information such that its top-left corner is at the top-left corner of the widget. |
︙ | ︙ | |||
288 289 290 291 292 293 294 | If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. The script must return \fB0\fR, \fB1\fR, or an empty string: a \fB0\fR or \fB1\fR value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. | | | 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 | If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. The script must return \fB0\fR, \fB1\fR, or an empty string: a \fB0\fR or \fB1\fR value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note that this interpretation of the option is defined entirely by the Tcl scripts that implement traversal: the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts. .OP \-text text Text Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as \fB\-anchor\fR or \fB\-justify\fR. |
︙ | ︙ |
Changes to doc/pack.n.
︙ | ︙ | |||
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | The \fBpack\fR command is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The \fBpack\fR command can have any of several forms, depending on the \fIoption\fR argument: .TP \fBpack \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? If the first argument to \fBpack\fR is a window name (any value starting with .QW . ), then the command is processed in the same way as \fBpack configure\fR. .TP \fBpack configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. See \fBTHE PACKER ALGORITHM\fR below for details on how the options are used by the packer. The following options are supported: .RS .TP \fB\-after \fIother\fR \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just after \fIother\fR in the packing order. .TP \fB\-anchor \fIanchor\fR \fIAnchor\fR must be a valid anchor position such as \fBn\fR or \fBsw\fR; it specifies where to position each content in its parcel. Defaults to \fBcenter\fR. .TP \fB\-before \fIother\fR \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just before \fIother\fR in the packing order. .TP \fB\-expand \fIboolean\fR Specifies whether the content should be expanded to consume extra space in their container. \fIBoolean\fR may have any proper boolean value, such as \fB1\fR or \fBno\fR. Defaults to 0. .TP \fB\-fill \fIstyle\fR If a content's parcel is larger than its requested dimensions, this option may be used to stretch the content. \fIStyle\fR must have one of the following values: .RS | > > > > > > > > > > > > > < | < | < | < | > > > > > > > > > > > > > > > > > > > > > > | | | > > > > | < < < < < | 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 | The \fBpack\fR command is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The \fBpack\fR command can have any of several forms, depending on the \fIoption\fR argument: .TP \fBpack \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . If the first argument to \fBpack\fR is a window name (any value starting with .QW . ), then the command is processed in the same way as \fBpack configure\fR. .\" METHOD: configure .TP \fBpack configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. See \fBTHE PACKER ALGORITHM\fR below for details on how the options are used by the packer. The following options are supported: .RS .\" OPTION: -after .TP \fB\-after \fIother\fR . \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just after \fIother\fR in the packing order. .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . \fIAnchor\fR must be a valid anchor position such as \fBn\fR or \fBsw\fR; it specifies where to position each content in its parcel. Defaults to \fBcenter\fR. .\" OPTION: -before .TP \fB\-before \fIother\fR . \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just before \fIother\fR in the packing order. .\" OPTION: -expand .TP \fB\-expand \fIboolean\fR . Specifies whether the content should be expanded to consume extra space in their container. \fIBoolean\fR may have any proper boolean value, such as \fB1\fR or \fBno\fR. Defaults to 0. .\" OPTION: -fill .TP \fB\-fill \fIstyle\fR . If a content's parcel is larger than its requested dimensions, this option may be used to stretch the content. \fIStyle\fR must have one of the following values: .RS .IP \fBnone\fR Give the content its requested dimensions plus any internal padding requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. .IP \fBx\fR Stretch the content horizontally to fill the entire width of its parcel (except leave external padding as specified by \fB\-padx\fR). .IP \fBy\fR Stretch the content vertically to fill the entire height of its parcel (except leave external padding as specified by \fB\-pady\fR). .IP \fBboth\fR Stretch the content both horizontally and vertically. .RE .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . Insert the window at the end of the packing order for the container window given by \fIcontainer\fR. .\" OPTION: -ipadx .TP \fB\-ipadx \fIamount\fR . \fIAmount\fR specifies how much horizontal internal padding to leave on each side of the content. \fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. It defaults to 0. .\" OPTION: -ipady .TP \fB\-ipady \fIamount\fR . \fIAmount\fR specifies how much vertical internal padding to leave on each side of the content. \fIAmount\fR defaults to 0. .\" OPTION: -padx .TP \fB\-padx \fIamount\fR . \fIAmount\fR specifies how much horizontal external padding to leave on each side of the content. \fIAmount\fR may be a list of two values to specify padding for left and right separately. \fIAmount\fR defaults to 0. .\" OPTION: -pady .TP \fB\-pady \fIamount\fR . \fIAmount\fR specifies how much vertical external padding to leave on each side of the content. \fIAmount\fR may be a list of two values to specify padding for top and bottom separately. \fIAmount\fR defaults to 0. .\" OPTION: -side .TP \fB\-side \fIside\fR . Specifies which side of the container the content will be packed against. Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. Defaults to \fBtop\fR. .LP If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified then each of the content will be inserted at the end of the packing list for its parent unless it is already managed by the packer (in which case it will be left where it is). If one of these options is specified then all the content will be inserted at the specified point. If any of the content are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE .\" METHOD: content .TP \fBpack content \fIwindow\fR . Returns a list of all of the content windows in the packing order for \fIwindow\fR. The order of the content windows in the list is the same as their order in the packing order. If \fIwindow\fR has no content then an empty string is returned. .\" METHOD: forget .TP \fBpack forget \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from the packing order for its container and unmaps their windows. The content will no longer be managed by the packer. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: info .TP \fBpack info \fIwindow\fR . Returns a list whose elements are the current configuration state of the window given by \fIwindow\fR in the same option-value form that might be specified to \fBpack configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the window's container. .\" METHOD: propagate .TP \fBpack propagate \fIcontainer\fR ?\fIboolean\fR? . If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fIcontainer\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). If \fIboolean\fR has a false boolean value then propagation is disabled for \fIcontainer\fR. In either of these cases an empty string is returned. If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIcontainer\fR. Propagation is enabled by default. .\" METHOD: slaves .TP \fBpack slaves \fIwindow\fR . Synonym for \fBpack content \fIwindow\fR. .SH "THE PACKER ALGORITHM" .PP For each container the packer maintains an ordered list of content |
︙ | ︙ | |||
269 270 271 272 273 274 275 | will be highest in the stacking order. Or, you can use the \fBraise\fR and \fBlower\fR commands to change the stacking order of either the container or the content. .SH EXAMPLE .PP .CS # Make the widgets | | | | | | | | | | | 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 | will be highest in the stacking order. Or, you can use the \fBraise\fR and \fBlower\fR commands to change the stacking order of either the container or the content. .SH EXAMPLE .PP .CS # Make the widgets label .t -text "This widget is at the top" -bg red label .b -text "This widget is at the bottom" -bg green label .l -text "Left\enHand\enSide" label .r -text "Right\enHand\enSide" text .mid \&.mid insert end "This layout is like Java's BorderLayout" # Lay them out \fBpack\fR .t -side top -fill x \fBpack\fR .b -side bottom -fill x \fBpack\fR .l -side left -fill y \fBpack\fR .r -side right -fill y \fBpack\fR .mid -expand 1 -fill both .CE .SH "SEE ALSO" grid(n), place(n) .SH KEYWORDS geometry manager, location, packer, parcel, propagation, size '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/palette.n.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | '\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_setPalette, tk_bisque \- Modify the Tk color palette .SH SYNOPSIS \fBtk_setPalette \fIbackground\fR | > < < > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | '\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_setPalette, tk_bisque \- Modify the Tk color palette .SH SYNOPSIS .nf \fBtk_setPalette \fIbackground\fR \fBtk_setPalette \fIname value \fR?\fIname value ...\fR? \fBtk_bisque\fR .fi .BE .SH DESCRIPTION .PP The \fBtk_setPalette\fR procedure changes the color scheme for Tk. It does this by modifying the colors of existing widgets and by changing the option database so that future widgets will use the new color scheme. If \fBtk_setPalette\fR is invoked with a single argument, the |
︙ | ︙ |
Changes to doc/panedwindow.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH panedwindow n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME panedwindow \- Create and manipulate 'panedwindow' split container widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH panedwindow n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME panedwindow \- Create and manipulate 'panedwindow' split container widgets .SH SYNOPSIS \fBpanedwindow\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-orient \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-handlepad handlePad HandlePad When sash handles are drawn, specifies the distance from the top or |
︙ | ︙ | |||
34 35 36 37 38 39 40 | or if resizing should be deferred until the sash is placed (false). In the latter case, a .QW ghost version of the sash is displayed during the resizing to show where the panes will be resized to when releasing the mouse button. This .QW ghost version of the sash is the proxy. It's rendering can be configured | | | | | | 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | or if resizing should be deferred until the sash is placed (false). In the latter case, a .QW ghost version of the sash is displayed during the resizing to show where the panes will be resized to when releasing the mouse button. This .QW ghost version of the sash is the proxy. It's rendering can be configured using the \fB\-proxybackground\fR, \fB\-proxyborderwidth\fR and \fB\-proxyrelief\fR options. .OP \-proxybackground proxyBackground ProxyBackground Background color to use when drawing the proxy. If an empty string, the value of the \fB\-background\fR option will be used. .OP \-proxyborderwidth proxyBorderWidth ProxyBorderWidth Specifies the borderwidth of the proxy. May be any value accepted by \fBTk_GetPixels\fR. .OP \-proxyrelief proxyRelief ProxyRelief Relief to use when drawing the proxy. May be any of the standard Tk relief values. If an empty string, the value of the \fB\-sashrelief\fR option will be used. .OP \-sashcursor sashCursor SashCursor Mouse cursor to use when over a sash. If null, \fBsb_h_double_arrow\fR will be used for horizontal panedwindows, and \fBsb_v_double_arrow\fR will be used for vertical panedwindows. .OP \-sashpad sashPad SashPad Specifies the amount of padding to leave of each side of a sash. May |
︙ | ︙ | |||
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 | .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for panedwindow widgets: .TP \fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? . Add one or more windows to the panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. \fIOption\fR may have any of the values accepted by the \fBconfigure\fR subcommand. .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .TP \fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .TP \fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? . Remove the pane containing \fIwindow\fR from the panedwindow. All geometry management options for \fIwindow\fR will be forgotten. .TP \fIpathName \fBidentify \fIx y\fR . Identify the panedwindow component underneath the point given by \fIx\fR and \fIy\fR, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. .TP \fIpathName \fBpanecget \fIwindow option\fR . Query a management option for \fIwindow\fR. \fIOption\fR may be any value allowed by the \fBpaneconfigure\fR subcommand. .TP \fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the management options for \fIwindow\fR. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are supported: .RS .TP \fB\-after \fIwindow\fR . Insert the window after the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .TP \fB\-before \fIwindow\fR . Insert the window before the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .TP \fB\-height \fIsize\fR . Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-height\fR is not specified, then the height requested internally by the window will be used initially; the height may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .TP \fB\-hide \fIboolean\fR . Controls the visibility of a pane. When the \fIboolean\fR is true (according to \fBTcl_GetBoolean\fR) the pane will not be visible, but it will still be maintained in the list of panes. .TP \fB\-minsize \fIn\fR . Specifies that the size of the window cannot be made less than \fIn\fR. This constraint only affects the size of the widget in the paned dimension \(em the x dimension for horizontal panedwindows, the y dimension for vertical panedwindows. May be any value accepted by \fBTk_GetPixels\fR. .TP \fB\-padx \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .TP \fB\-pady \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .TP \fB\-sticky \fIstyle\fR . If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. \fIStyle\fR is a string that contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the window will .QW stick to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are specified, the window will be stretched to fill the entire height (or width) of its cavity. .TP \fB\-stretch \fIwhen\fR . Controls how extra space is allocated to each of the panes. \fIWhen\fR is one of \fBalways\fR, \fBfirst\fR, \fBlast\fR, \fBmiddle\fR, and \fBnever\fR. The panedwindow will calculate the required size of all its panes. Any remaining (or deficit) space will be distributed to those panes marked for stretching. The space will be distributed based on each panes current ratio of the whole. The \fIwhen\fR values have the following definition: .RS | > > > > > > > > > > > > > > > > < | < < | < < | < < | < < | < > > > | 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 | .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for panedwindow widgets: .\" METHOD: add .TP \fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? . Add one or more windows to the panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. \fIOption\fR may have any of the values accepted by the \fBconfigure\fR subcommand. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .\" METHOD: forget .TP \fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? . Remove the pane containing \fIwindow\fR from the panedwindow. All geometry management options for \fIwindow\fR will be forgotten. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Identify the panedwindow component underneath the point given by \fIx\fR and \fIy\fR, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. .\" METHOD: panecget .TP \fIpathName \fBpanecget \fIwindow option\fR . Query a management option for \fIwindow\fR. \fIOption\fR may be any value allowed by the \fBpaneconfigure\fR subcommand. .\" METHOD: paneconfigure .TP \fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the management options for \fIwindow\fR. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are supported: .RS .\" OPTION: -after .TP \fB\-after \fIwindow\fR . Insert the window after the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .\" OPTION: -before .TP \fB\-before \fIwindow\fR . Insert the window before the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .\" OPTION: -height .TP \fB\-height \fIsize\fR . Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-height\fR is not specified, then the height requested internally by the window will be used initially; the height may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .\" OPTION: -hide .TP \fB\-hide \fIboolean\fR . Controls the visibility of a pane. When the \fIboolean\fR is true (according to \fBTcl_GetBoolean\fR) the pane will not be visible, but it will still be maintained in the list of panes. .\" OPTION: -minsize .TP \fB\-minsize \fIn\fR . Specifies that the size of the window cannot be made less than \fIn\fR. This constraint only affects the size of the widget in the paned dimension \(em the x dimension for horizontal panedwindows, the y dimension for vertical panedwindows. May be any value accepted by \fBTk_GetPixels\fR. .\" OPTION: -padx .TP \fB\-padx \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .\" OPTION: -pady .TP \fB\-pady \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .\" OPTION: -sticky .TP \fB\-sticky \fIstyle\fR . If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. \fIStyle\fR is a string that contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the window will .QW stick to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are specified, the window will be stretched to fill the entire height (or width) of its cavity. .\" OPTION: -stretch .TP \fB\-stretch \fIwhen\fR . Controls how extra space is allocated to each of the panes. \fIWhen\fR is one of \fBalways\fR, \fBfirst\fR, \fBlast\fR, \fBmiddle\fR, and \fBnever\fR. The panedwindow will calculate the required size of all its panes. Any remaining (or deficit) space will be distributed to those panes marked for stretching. The space will be distributed based on each panes current ratio of the whole. The \fIwhen\fR values have the following definition: .RS .IP \fBalways\fR This pane will always stretch. .IP \fBfirst\fR Only if this pane is the first pane (left-most or top-most) will it stretch. .IP \fBlast\fR Only if this pane is the last pane (right-most or bottom-most) will it stretch. This is the default value. .IP \fBmiddle\fR Only if this pane is not the first or last pane will it stretch. .IP \fBnever\fR This pane will never stretch. .RE .\" OPTION: -width .TP \fB\-width \fIsize\fR . Specify a width for the window. The width will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-width\fR is not specified, then the width requested internally by the window will be used initially; the width may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .RE .\" METHOD: panes .TP \fIpathName \fBpanes\fR . Returns an ordered list of the widgets managed by \fIpathName\fR. .\" METHOD: proxy .TP \fIpathName \fBproxy \fR?\fIargs\fR? . This command is used to query and change the position of the sash proxy, used for rubberband-style pane resizing. It can take any of the following forms: .RS |
︙ | ︙ | |||
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | . Remove the proxy from the display. .TP \fIpathName \fBproxy place \fIx y\fR . Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE .TP \fIpathName \fBsash \fR?\fIargs\fR? This command is used to query and change the position of sashes in the panedwindow. It can take any of the following forms: .RS .TP \fIpathName \fBsash coord \fIindex\fR . Return the current x and y coordinate pair for the sash given by | > > | 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 | . Remove the proxy from the display. .TP \fIpathName \fBproxy place \fIx y\fR . Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE .\" METHOD: sash .TP \fIpathName \fBsash \fR?\fIargs\fR? . This command is used to query and change the position of sashes in the panedwindow. It can take any of the following forms: .RS .TP \fIpathName \fBsash coord \fIindex\fR . Return the current x and y coordinate pair for the sash given by |
︙ | ︙ |
Changes to doc/photo.n.
︙ | ︙ | |||
39 40 41 42 43 44 45 | internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from C code through a procedural interface. At present, only .VS 8.6 PNG, .VE 8.6 | > > > > | | > > | > > > > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from C code through a procedural interface. At present, only .VS 8.6 PNG, .VE 8.6 GIF, PPM/PGM, .VS 8.7 and (read-only) SVG .VE 8.7 formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is (semi)transparent if the image data it was obtained from had transparency information. In regions where no image data has been supplied, it is fully transparent. Transparency may also be modified with the \fBtransparency set\fR subcommand. .SH "CREATING PHOTOS" .PP Like all images, photos are created using the \fBimage create\fR command. Photos support the following \fIoptions\fR: .\" OPTION: -data .TP \fB\-data \fIstring\fR . Specifies the contents of the image as a string. .VS 8.7 The string should contain data in the default list-of-lists form, .VE 8.7 binary data or, for some formats, base64-encoded data (this is currently guaranteed to be supported for PNG and GIF images). The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-file\fR option takes precedence. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the file format for the data specified with the \fB\-data\fR or \fB\-file\fR option and optional arguments passed to the format handler. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -file .TP \fB\-file \fIname\fR . \fIname\fR gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data. .\" OPTION: -gamma .TP \fB\-gamma \fIvalue\fR . Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker. .\" OPTION: -height .TP \fB\-height \fInumber\fR . Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it. .VS 8.7 .\" OPTION: -metadata .TP \fB\-metadata \fImetadata\fR . Set the metadata dictionary of the image. Additional keys may be set within the metadata dictionary of the image, if image data is processed due to a \fB\-file\fR or \fB\-data\fR options and the driver outputs any metadata keys. See section \fBMETADATA DICTIONARY\fR below. .VE 8.7 .\" OPTION: -palette .TP \fB\-palette \fIpalette-spec\fR . Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The \fIpalette-spec\fR string may be either a single decimal number, specifying the number of shades of gray to use, or three decimal numbers separated by slashes (/), specifying the number of shades of red, green and blue to use, respectively. If the first form (a single number) is used, the image will be displayed in monochrome (i.e., grayscale). .\" OPTION: -width .TP \fB\-width \fInumber\fR . Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it. |
︙ | ︙ | |||
147 148 149 150 151 152 153 154 155 156 157 158 | of the image, if necessary, to accommodate the data written to the image, unless the user has specified non-zero values for the \fB\-width\fR and/or \fB\-height\fR configuration options, in which case the width and/or height, respectively, of the image will not be changed. .PP The following commands are possible for photo images: .TP \fIimageName \fBblank\fR . Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever | > | > > | > | > | > > > > > > > | > > | > > > | > > | | | | > | > | | > | > | > | > > | | > > > > < | | | < < | | | > > > | > > > | | | | 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 | of the image, if necessary, to accommodate the data written to the image, unless the user has specified non-zero values for the \fB\-width\fR and/or \fB\-height\fR configuration options, in which case the width and/or height, respectively, of the image will not be changed. .PP The following commands are possible for photo images: .\" METHOD: blank .TP \fIimageName \fBblank\fR . Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. The metadata dict of the image is not changed. .\" METHOD: cget .TP \fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBphoto\fR command. .\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBphoto\fR command. .VS 8.7 Note that setting the \fB\-metadata\fR option without any other option will not invoke the image format driver to recreate the bitmap. .VE 8.7 .\" METHOD: copy .TP \fIimageName \fBcopy\fI sourceImage\fR ?\fIoption value(s) ...\fR? . Copies a region from the image called \fIsourceImage\fR (which must be a photo image) to the image called \fIimageName\fR, possibly with pixel zooming and/or subsampling. If no options are specified, this command copies the whole of \fIsourceImage\fR into \fIimageName\fR, starting at coordinates (0,0) in \fIimageName\fR. The following options may be specified: .RS .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the source image to be copied. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the \fB\-from\fR option is not given, the default is the whole source image. .\" OPTION: -to .TP \fB\-to \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the destination image to be affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the default value is (\fIx1,y1\fR) plus the size of the source region (after subsampling and zooming, if specified). If \fIx2\fR and \fIy2\fR are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion. .\" OPTION: -shrink .TP \fB\-shrink\fR . Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .\" OPTION: -zoom .TP \fB\-zoom \fIx y\fR . Specifies that the source region should be magnified by a factor of \fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR is not given, the default value is the same as \fIx\fR. With this option, each pixel in the source image will be expanded into a block of \fIx\fR x \fIy\fR pixels in the destination image, all the same color. \fIx\fR and \fIy\fR must be greater than 0. .\" OPTION: -subsample .TP \fB\-subsample \fIx y\fR . Specifies that the source image should be reduced in size by using only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If \fIy\fR is not given, the default value is the same as \fIx\fR. .\" OPTION: -compositingrule .TP \fB\-compositingrule \fIrule\fR . Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of \fIoverlay\fR is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of \fIset\fR is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is \fIoverlay\fR. .RE .\" METHOD: data .TP \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? . Returns image data in the form of a string. .VS 8.7 The format of the string depends on the format handler. By default, a human readable format as a list of lists of pixel data is used, other formats can be chosen with the \fB\-format\fR option. See \fBIMAGE FORMATS\fR below for details. .VE 8.7 The following options may be specified: .RS .\" OPTION: -background .TP \fB\-background\fI color\fR . If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the image file format handler to use and, optionally, arguments to the format handler. Specifically, this subcommand searches for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write a string containing this image data. .VS 8.7 If this option is not given, this subcommand uses the default format that consists of a list (one element per row) of lists (one element per pixel/column) of colors in .QW \fB#\fIrrggbb\fR format (see \fBIMAGE FORMATS\fR below). .VE 8.7 Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular region of \fIimageName\fR to be returned. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of \fIimageName\fR. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region, including x1,y1 and excluding x2,y2. The default, if this option is not given, is the whole image. .\" OPTION: -grayscale .TP \fB\-grayscale\fR . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .VS 8.7 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the returned data string. The specified \fImetadata\fR is passed to the driver for inclusion in the data. If no \fB\-metadata\fR option is given, the current metadata of the image is used. .VE 8.7 .RE .\" METHOD: get .TP \fIimageName \fBget\fI x y\fR ?\fB\-withalpha\fR? . Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively. If the \fB\-withalpha\fR option is specified, the returned list will have a fourth element representing the alpha value of the pixel as an integer between 0 and 255. .\" METHOD: put .TP \fIimageName \fBput\fI data\fR ?\fIoption value(s) ...\fR? . Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. .VS 8.7 This command searches the list of image file format handlers for a handler that can interpret the data in \fIdata\fR, and then reads the image encoded within into \fIimageName\fR (the destination image). See \fBIMAGE FORMATS\fR below for details on formats for image data. .VE 8.7 The following options may be specified: .RS .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ..\fR?} . Specifies the format of the image data in \fIdata\fR and, optionally, arguments to be passed to the format handler. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .VS 8.7 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. .VE 8.7 .\" OPTION: -to .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? . Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR) of the region of \fIimageName\fR into which the image data will be copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given and \fIdata\fR is not large enough to cover the rectangle specified by this option, the image data extracted will be tiled so it covers the entire destination rectangle. If the region specified with this option is smaller than the supplied \fIdata\fR, the exceeding data is silently discarded. Note that if \fIdata\fR specifies a single color value, then a region extending to the bottom-right corner represented by (\fIx2\fR,\fIy2\fR) will be filled with that color. .RE .\" METHOD: read .TP \fIimageName \fBread\fI filename\fR ?\fIoption value(s) ...\fR? . Reads image data from the file named \fIfilename\fR into the image. This command first searches the list of image file format handlers for a handler that can interpret the data in \fIfilename\fR, and then reads the image in \fIfilename\fR into \fIimageName\fR (the destination image). The following options may be specified: .RS .\" OPTION: -format .TP \fB\-format {\fIformat-name\fR ?\fIoption value ..\fR?} . Specifies the format of the image data in \fIfilename\fR and, optionally, additional options to the format handler. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the image file data to be copied to the destination image. If only \fIx1\fR and \fIy1\fR are specified, the region extends from (\fIx1,y1\fR) to the bottom-right corner of the image in the image file. If all four coordinates are specified, they specify diagonally opposite corners or the region. The default, if this option is not specified, is the whole of the image in the image file. .VS 8.7 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. .VE 8.7 .\" OPTION: -shrink .TP \fB\-shrink\fR . If this option, the size of \fIimageName\fR will be reduced, if necessary, so that the region into which the image file data are read is at the bottom-right corner of the \fIimageName\fR. This option will not affect the width or height of the image if the user has specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .\" OPTION: -to .TP \fB\-to \fIx y\fR . Specifies the coordinates of the top-left corner of the region of \fIimageName\fR into which data from \fIfilename\fR are to be read. The default is (0,0). .RE .\" METHOD: redither .TP \fIimageName \fBredither\fR . The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data for \fIimageName\fR is supplied in pieces, the dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. .\" METHOD: transparency .TP \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? . Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS .TP \fIimageName \fBtransparency get \fIx y\fR ?\fB\-alpha\fR? .VS 8.7 Returns true if the pixel at (\fIx\fR,\fIy\fR) is fully transparent, false otherwise. If the option \fB\-alpha\fR is passed, returns the alpha value of the pixel instead, as an integer in the range 0 to 255. .VE 8.7 .TP \fIimageName \fBtransparency set \fIx y newVal\fR ?\fB\-alpha\fR? .VS 8.7 Change the transparency of the pixel at (\fIx\fR,\fIy\fR) to \fInewVal.\fR If no additional option is passed, \fInewVal\fR is interpreted as a boolean and the pixel is made fully transparent if that value is true, fully opaque otherwise. If the \fB\-alpha\fR option is passed, \fInewVal\fR is interpreted as an integral alpha value for the pixel, which must be in the range 0 to 255. .VE 8.7 .RE .\" METHOD: write .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? . Writes image data from \fIimageName\fR to a file named \fIfilename\fR. The following options may be specified: .RS .\" OPTION: -background .TP \fB\-background\fI color\fR . If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the image file format handler to be used to write the data to the file and, optionally, options to pass to the format handler. Specifically, this subcommand searches for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write an image file. If this option is not given, the format is guessed from the file extension. If that cannot be determined, this subcommand uses the first handler that has the capability to write an image file. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular region of \fIimageName\fR to be written to the image file. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of \fIimageName\fR. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image. .\" OPTION: -grayscale .TP \fB\-grayscale\fR . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .VS 8.7 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the written file. The specified \fImetadata\fR is passed to the driver for inclusion in the file. If no \fB\-metadata\fR option is given, the current metadata of the image is used. .VE 8.7 .RE .SH "IMAGE FORMATS" .PP The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The standard Tk distribution comes with handlers for PPM/PGM, PNG, GIF and (read-only) SVG formats, .VS 8.7 as well as the \fBdefault\fR handler to encode/decode image data in a human readable form. .VE 8.7 These handlers are automatically registered on initialization. .PP When reading an image file or processing string data specified with |
︙ | ︙ | |||
551 552 553 554 555 556 557 | .SS "THE DEFAULT IMAGE HANDLER" .PP The \fBdefault\fR image handler cannot be used to read or write data from/to a file. Its sole purpose is to encode and decode image data in string form in a clear text, human readable, form. The \fIimageName\fR \fBdata\fR subcommand uses this handler when no other format is specified. When reading image data from a string with \fIimageName\fR | | | > | > > > > > > | > > | > > < | | > > | | > > | | | > > | > > | | | > > | | > > | > > | | > > | | > > | | > > | 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 | .SS "THE DEFAULT IMAGE HANDLER" .PP The \fBdefault\fR image handler cannot be used to read or write data from/to a file. Its sole purpose is to encode and decode image data in string form in a clear text, human readable, form. The \fIimageName\fR \fBdata\fR subcommand uses this handler when no other format is specified. When reading image data from a string with \fIimageName\fR \fBput\fR or the \fB\-data\fR option, the default handler is treated as the other handlers. .PP Image data in the \fBdefault\fR string format is a (top-to-bottom) list of scan-lines, with each scan-line being a (left-to-right) list of pixel data. Every scan-line has the same length. The color and, optionally, alpha value of each pixel is specified in any of the forms described in the \fBCOLOR FORMATS\fR section below. .VE 8.7 .SS "FORMAT SUBOPTIONS" .PP .VS 8.6 Image formats may support sub-options, which are specified using additional words in the value to the \fB\-format\fR option. These suboptions can affect how image data is read or written to file or string. The nature and values of these options is up to the format handler. The built-in handlers support these suboptions: .\" OPTION -colorformat .VS 8.7 .TP \fBdefault \-colorformat\fI formatType\fR . The option is allowed when writing image data to a string with \fIimageName \fBdata\fR. Specifies the format to use for the color string of each pixel. \fIformatType\fR may be one of: \fBrgb\fR to encode pixel data in the form \fB#\fIRRGGBB\fR, \fBrgba\fR to encode pixel data in the form \fB#\fIRRGGBBAA\fR or \fBlist\fR to encode pixel data as a list with four elements. See \fBCOLOR FORMATS\fR below for details. The default is \fBrgb\fR. .VE 8.7 .\" OPTION -index .TP \fBgif \-index\fI indexValue\fR . The option has effect when reading image data from a file. When parsing a multi-part GIF image, Tk normally only accesses the first image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value may be used instead. The \fIindexValue\fR must be an integer from 0 up to the number of image parts in the GIF data. .\" OPTION -alpha .TP \fBpng \-alpha\fI alphaValue\fR . The option has effect when reading image data from a file. Specifies an additional alpha filtering for the overall image, which allows the background on which the image is displayed to show through. This usually also has the effect of desaturating the image. The \fIalphaValue\fR must be between 0.0 and 1.0. .\" OPTION -dpi .\" OPTION -scale .\" OPTION -scaletowidth .\" OPTION -scaletoheight .TP \fBsvg \-dpi\fI dpiValue \fB\-scale\fI scaleValue \fB\-scaletowidth\fI width \fB\-scaletoheight\fI height\fR . \fIdpiValue\fR is used in conversion between given coordinates and screen resolution. The value must be greater than 0 and the default value is 96. .PP .RS \fIscaleValue\fR is used to scale the resulting image. The value must be greater than 0 and the default value is 1. \fIwidth\fR and \fIheight\fR are the width or height that the image will be adjusted to. Only one parameter among \fB\-scale\fR, \fB\-scaletowidth\fR and \fB\-scaletoheight\fR can be given at a time and the aspect ratio of the original image is always preserved. The \fBsvg\fR format supports a wide range of SVG features, but the full SVG standard is not available, for instance the 'text' feature is missing and silently ignored when reading the SVG data. The supported SVG features are: .TP \fBelements:\fR . g, path, rect, circle, ellipse, line, polyline, polygon, linearGradient, radialGradient, stop, defs, svg, style .TP \fBattributes:\fR . width, height, viewBox, preserveAspectRatio with none, xMin, xMid, xMax, yMin, yMid, yMax, slice .TP \fBgradient attributes:\fR . gradientUnits with objectBoundingBox, gradientTransform, cx, cy, r fx, fy x1, y1, x2, y2 spreadMethod with pad, reflect or repeat, xlink:href .TP \fBpoly attributes:\fR . points .TP \fBline attributes:\fR . x1, y1, x2, y2 .TP \fBellipse attributes:\fR . cx, cy, rx, ry .TP \fBcircle attributes:\fR . cx, cy, r .TP \fBrectangle attributes:\fR . x, y, width, height, rx, ry .TP \fBpath attributes:\fR . d with m, M, l, L, h, H, v, V, c, C, s, S, q, Q, t, T, a, A, z, Z .TP \fBstyle attributes:\fR . display with none, visibility, hidden, visible, fill with nonzero and evenodd, opacity, fill-opacity, stroke, stroke-width, stroke-dasharray, stroke-dashoffset, stroke-opacity, stroke-linecap with butt, round and square, stroke-linejoin with miter, round and bevel, stroke-miterlimit fill-rule, font-size, transform with matrix, translate, scale, rotate, skewX and skewY, stop-color, stop-opacity, offset, id, class .RE .PP .RS Currently only SVG images reading and conversion into (pixel-based format) photos is supported: Tk does not (yet) support bundling photo images in SVG vector graphics. .RE .VE 8.6 .VS 8.7 .SH "COLOR FORMATS" .PP The default image handler can represent/parse color and alpha values of a pixel in one of the formats listed below. If a color format does not contain transparency information, full opacity is assumed. The |
︙ | ︙ | |||
742 743 744 745 746 747 748 | comments. Image format drivers may output metadata when image data is parsed, or may use metadata to be included in image files or formats. .SS "METADATA KEYS (MULTIPLE FORMATS)" .PP Each image format driver supports an individual set of metadata dictionary keys. Predefined keys are: | < | < < | < < | < | | | | | > | > | | | | | | | | | | 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 | comments. Image format drivers may output metadata when image data is parsed, or may use metadata to be included in image files or formats. .SS "METADATA KEYS (MULTIPLE FORMATS)" .PP Each image format driver supports an individual set of metadata dictionary keys. Predefined keys are: .IP \fBDPI\fR Horizontal image resolution in DPI as a double value. Supported by format \fBpng\fR. .IP \fBaspect\fR Aspect ratio horizontal divided by vertical as double value. Supported by formats \fBgif\fR and \fBpng\fR. .IP \fBcomment\fR Image text comment. Supported by formats \fBgif\fR and \fBpng\fR. .PP It is valid to set any key in the metadata dict. A format driver will ignore keys that it does not handle. .SS "METADATA KEYS FOR ANIMATED GIF INFORMATION" .PP The following metadata keys are reported when reading a \fBgif\fR format file. They are typically used in conjunction with the \fB\-index\fR option of an animated \fBgif\fR file to properly display the subimage sequence. The options are linked to each subimage selected by \fB\-index\fR. .TP \fBdelay time\fI time\fR . Update delay time in 10ms units. This key is only present if the delay time is not 0. .TP \fBdisposal method\fI method\fR . Disposal method of the preceeding image, if given for the current image. Possible values are: \fBdo not dispose\fR, \fBrestore to background color\fR, \fBrestore to previous\fR. .TP \fBuser interaction\fI bool\fR . The key is present with a value of 1, if user interaction is specified. Otherwise, the key is not present. .TP \fBupdate region\fI X0\fR, \fIY0\fR, \fIwidth\fR, \fIheight\fR . Update region of the current subimage, if subimage has not the same size as the full image. The pixel outside of this box are all fully transparent. .PP .VE 8.7 .SH CREDITS .PP The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout. .SH EXAMPLE .PP Load an image from a file and tile it to the size of a window, which is useful for producing a tiled background: .PP .CS # These lines should be called once \fBimage create photo\fR untiled -file "theFile.ppm" \fBimage create photo\fR tiled # These lines should be called whenever .someWidget changes # size; a <Configure> binding is useful here set width [winfo width .someWidget] set height [winfo height .someWidget] tiled \fBcopy\fR untiled -to 0 0 $width $height -shrink .CE .PP .VS 8.6 The PNG image loader allows the application of an additional alpha factor during loading, which is useful for generating images suitable for disabled buttons: .PP .CS \fBimage create photo\fR icon -file "icon.png" \fBimage create photo\fR iconDisabled -file "icon.png" \e -format "png -alpha 0.5" button .b -image icon -disabledimage iconDisabled .CE .VE 8.6 .PP .VS 8.7 Create a green box with a simple shadow effect .PP .CS |
︙ | ︙ |
Changes to doc/place.n.
︙ | ︙ | |||
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | in response to changes in the size of the container. Lastly, the placer allows you to mix these styles of placement so that, for example, the content has a fixed width and height but is centered inside the container. .PP .TP \fBplace \fIwindow option value \fR?\fIoption value ...\fR? Arrange for the placer to manage the geometry of a content whose pathName is \fIwindow\fR. The remaining arguments consist of one or more \fIoption\-value\fR pairs that specify the way in which \fIwindow\fR's geometry is managed. \fIOption\fR may have any of the values accepted by the \fBplace configure\fR command. .TP \fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? Query or modify the geometry options of the content given by \fIwindow\fR. If no \fIoption\fR is specified, this command returns a list describing the available options (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. .RS .PP The following \fIoption\-value\fR pairs are supported: .TP \fB\-anchor \fIwhere\fR \fIWhere\fR specifies which point of \fIwindow\fR is to be positioned at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, \fB\-relx\fR, and \fB\-rely\fR options. The anchor point is in terms of the outer area of \fIwindow\fR including its border, if any. Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of \fIwindow\fR's border will appear at the given (x,y) location in the container. The anchor position defaults to \fBnw\fR. .TP \fB\-bordermode \fImode\fR \fIMode\fR determines the degree to which borders within the container are used in determining the placement of the content. The default and most common value is \fBinside\fR. In this case the placer considers the area of the container to be the innermost area of the container, inside any border: an option of \fB\-x 0\fR corresponds to an x-coordinate just inside the border and an option of \fB\-relwidth 1.0\fR | > > > > > > > | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | in response to changes in the size of the container. Lastly, the placer allows you to mix these styles of placement so that, for example, the content has a fixed width and height but is centered inside the container. .PP .TP \fBplace \fIwindow option value \fR?\fIoption value ...\fR? . Arrange for the placer to manage the geometry of a content whose pathName is \fIwindow\fR. The remaining arguments consist of one or more \fIoption\-value\fR pairs that specify the way in which \fIwindow\fR's geometry is managed. \fIOption\fR may have any of the values accepted by the \fBplace configure\fR command. .\" METHOD: configure .TP \fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the geometry options of the content given by \fIwindow\fR. If no \fIoption\fR is specified, this command returns a list describing the available options (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. .RS .PP The following \fIoption\-value\fR pairs are supported: .\" OPTION: -anchor .TP \fB\-anchor \fIwhere\fR . \fIWhere\fR specifies which point of \fIwindow\fR is to be positioned at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, \fB\-relx\fR, and \fB\-rely\fR options. The anchor point is in terms of the outer area of \fIwindow\fR including its border, if any. Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of \fIwindow\fR's border will appear at the given (x,y) location in the container. The anchor position defaults to \fBnw\fR. .\" OPTION: -bordermode .TP \fB\-bordermode \fImode\fR . \fIMode\fR determines the degree to which borders within the container are used in determining the placement of the content. The default and most common value is \fBinside\fR. In this case the placer considers the area of the container to be the innermost area of the container, inside any border: an option of \fB\-x 0\fR corresponds to an x-coordinate just inside the border and an option of \fB\-relwidth 1.0\fR |
︙ | ︙ | |||
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 | outside its container, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. Lastly, \fImode\fR may be specified as \fBignore\fR, in which case borders are ignored: the area of the container is considered to be its official X area, which includes any internal border but no external border. A bordermode of \fBignore\fR is probably not very useful. .RE .TP \fB\-height \fIsize\fR \fISize\fR specifies the height for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The height will be the outer dimension of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-height\fR or \fB\-relheight\fR option is specified, then the height requested internally by the window will be used. .TP \fB\-in \fIcontainer\fR \fIContainer\fR specifies the path name of the window relative to which \fIwindow\fR is to be placed. \fIContainer\fR must either be \fIwindow\fR's parent or a descendant of \fIwindow\fR's parent. In addition, \fIcontainer\fR and \fIwindow\fR must both be descendants of the same top-level window. These restrictions are necessary to guarantee that \fIwindow\fR is visible whenever \fIcontainer\fR is visible. If this option is not specified then the other window defaults to \fIwindow\fR's parent. .TP \fB\-relheight \fIsize\fR \fISize\fR specifies the height for \fIwindow\fR. In this case the height is specified as a floating-point number relative to the height of the container: 0.5 means \fIwindow\fR will be half as high as the container, 1.0 means \fIwindow\fR will have the same height as the container, and so on. If both \fB\-height\fR and \fB\-relheight\fR are specified for a content, their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR makes the content 2 pixels shorter than the container. .TP \fB\-relwidth \fIsize\fR \fISize\fR specifies the width for \fIwindow\fR. In this case the width is specified as a floating-point number relative to the width of the container: 0.5 means \fIwindow\fR will be half as wide as the container, 1.0 means \fIwindow\fR will have the same width as the container, and so on. If both \fB\-width\fR and \fB\-relwidth\fR are specified for a content, their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR makes the content 5 pixels wider than the container. .TP \fB\-relx \fIlocation\fR \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the location is specified in a relative fashion as a floating-point number: 0.0 corresponds to the left edge of the container and 1.0 corresponds to the right edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-x\fR and \fB\-relx\fR are specified for a content then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR positions the left edge of the content 2 pixels to the left of the center of its container. .TP \fB\-rely \fIlocation\fR \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the value is specified in a relative fashion as a floating-point number: 0.0 corresponds to the top edge of the container and 1.0 corresponds to the bottom edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-y\fR and \fB\-rely\fR are specified for a content then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR positions the top edge of the content 3 pixels below the center of its container. .TP \fB\-width \fIsize\fR \fISize\fR specifies the width for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The width will be the outer width of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-width\fR or \fB\-relwidth\fR option is specified, then the width requested internally by the window will be used. .TP \fB\-x \fIlocation\fR \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .TP \fB\-y \fIlocation\fR \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .PP If the same value is specified separately with two different options, such as \fB\-x\fR and \fB\-relx\fR, then the most recent option is used and the older one is ignored. .RE .TP \fBplace forget \fIwindow\fR Causes the placer to stop managing the geometry of \fIwindow\fR. As a side effect of this command \fIwindow\fR will be unmapped so that it does not appear on the screen. If \fIwindow\fR is not currently managed by the placer then the command has no effect. This command returns an empty string. .TP \fBplace info \fIwindow\fR Returns a list giving the current configuration of \fIwindow\fR. The list consists of \fIoption\-value\fR pairs in exactly the same form as might be specified to the \fBplace configure\fR command. | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | < < < | 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | outside its container, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. Lastly, \fImode\fR may be specified as \fBignore\fR, in which case borders are ignored: the area of the container is considered to be its official X area, which includes any internal border but no external border. A bordermode of \fBignore\fR is probably not very useful. .RE .\" OPTION: -height .TP \fB\-height \fIsize\fR . \fISize\fR specifies the height for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The height will be the outer dimension of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-height\fR or \fB\-relheight\fR option is specified, then the height requested internally by the window will be used. .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . \fIContainer\fR specifies the path name of the window relative to which \fIwindow\fR is to be placed. \fIContainer\fR must either be \fIwindow\fR's parent or a descendant of \fIwindow\fR's parent. In addition, \fIcontainer\fR and \fIwindow\fR must both be descendants of the same top-level window. These restrictions are necessary to guarantee that \fIwindow\fR is visible whenever \fIcontainer\fR is visible. If this option is not specified then the other window defaults to \fIwindow\fR's parent. .\" OPTION: -relheight .TP \fB\-relheight \fIsize\fR . \fISize\fR specifies the height for \fIwindow\fR. In this case the height is specified as a floating-point number relative to the height of the container: 0.5 means \fIwindow\fR will be half as high as the container, 1.0 means \fIwindow\fR will have the same height as the container, and so on. If both \fB\-height\fR and \fB\-relheight\fR are specified for a content, their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR makes the content 2 pixels shorter than the container. .\" OPTION: -relwidth .TP \fB\-relwidth \fIsize\fR . \fISize\fR specifies the width for \fIwindow\fR. In this case the width is specified as a floating-point number relative to the width of the container: 0.5 means \fIwindow\fR will be half as wide as the container, 1.0 means \fIwindow\fR will have the same width as the container, and so on. If both \fB\-width\fR and \fB\-relwidth\fR are specified for a content, their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR makes the content 5 pixels wider than the container. .\" OPTION: -relx .TP \fB\-relx \fIlocation\fR . \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the location is specified in a relative fashion as a floating-point number: 0.0 corresponds to the left edge of the container and 1.0 corresponds to the right edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-x\fR and \fB\-relx\fR are specified for a content then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR positions the left edge of the content 2 pixels to the left of the center of its container. .\" OPTION: -rely .TP \fB\-rely \fIlocation\fR . \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the value is specified in a relative fashion as a floating-point number: 0.0 corresponds to the top edge of the container and 1.0 corresponds to the bottom edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-y\fR and \fB\-rely\fR are specified for a content then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR positions the top edge of the content 3 pixels below the center of its container. .\" OPTION: -width .TP \fB\-width \fIsize\fR . \fISize\fR specifies the width for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The width will be the outer width of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-width\fR or \fB\-relwidth\fR option is specified, then the width requested internally by the window will be used. .\" OPTION: -x .TP \fB\-x \fIlocation\fR . \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .\" OPTION: -y .TP \fB\-y \fIlocation\fR . \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .PP If the same value is specified separately with two different options, such as \fB\-x\fR and \fB\-relx\fR, then the most recent option is used and the older one is ignored. .RE .\" METHOD: content .TP \fBplace content \fIwindow\fR . Returns a list of all the content windows for which \fIwindow\fR is the container. If there is no content for \fIwindow\fR then an empty string is returned. .\" METHOD: forget .TP \fBplace forget \fIwindow\fR . Causes the placer to stop managing the geometry of \fIwindow\fR. As a side effect of this command \fIwindow\fR will be unmapped so that it does not appear on the screen. If \fIwindow\fR is not currently managed by the placer then the command has no effect. This command returns an empty string. .\" METHOD: info .TP \fBplace info \fIwindow\fR . Returns a list giving the current configuration of \fIwindow\fR. The list consists of \fIoption\-value\fR pairs in exactly the same form as might be specified to the \fBplace configure\fR command. .\" METHOD: slaves .TP \fBplace slaves \fIwindow\fR . Synonym for \fBplace content \fIwindow\fR. .PP If the configuration of a window has been retrieved with \fBplace info\fR, that configuration can be restored later by |
︙ | ︙ | |||
243 244 245 246 247 248 249 | To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. .SH EXAMPLE .PP Make the label occupy the middle bit of the toplevel, no matter how it is resized: .CS | | | | > | 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 | To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. .SH EXAMPLE .PP Make the label occupy the middle bit of the toplevel, no matter how it is resized: .CS label .l -text "In the\enMiddle!" -bg black -fg white \fBplace\fR .l -relwidth .3 -relx .35 -relheight .3 -rely .35 .CE .SH "SEE ALSO" grid(n), pack(n) .SH KEYWORDS geometry manager, height, location, container, place, rubber sheet, content, width '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/popup.n.
︙ | ︙ | |||
27 28 29 30 31 32 33 | the given point. .SH EXAMPLE .PP How to attach a simple popup menu to a widget. .CS # Create a menu set m [menu .popupMenu] | | | | | 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | the given point. .SH EXAMPLE .PP How to attach a simple popup menu to a widget. .CS # Create a menu set m [menu .popupMenu] $m add command -label "Example 1" -command bell $m add command -label "Example 2" -command bell # Create something to attach it to pack [label .l -text "Click me!"] # Arrange for the menu to pop up when the label is clicked bind .l <Button-1> {\fBtk_popup\fR .popupMenu %X %Y} .CE .SH "SEE ALSO" bind(n), menu(n), tk_optionMenu(n) .SH KEYWORDS |
︙ | ︙ |
Changes to doc/radiobutton.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH radiobutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME radiobutton \- Create and manipulate 'radiobutton' pick-one widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH radiobutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME radiobutton \- Create and manipulate 'radiobutton' pick-one widgets .SH SYNOPSIS \fBradiobutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable |
︙ | ︙ | |||
61 62 63 64 65 66 67 | raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the radiobutton. The empty string is the default value. .OP \-selectcolor selectColor Background Specifies a background color to use when the button is selected. If \fBindicatorOn\fR is true then the color is used as the background for the indicator regardless of the select state. | | | | 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the radiobutton. The empty string is the default value. .OP \-selectcolor selectColor Background Specifies a background color to use when the button is selected. If \fBindicatorOn\fR is true then the color is used as the background for the indicator regardless of the select state. If \fB\-indicatoron\fR is false, this color is used as the background for the entire widget, in place of \fB\-background\fR or \fB\-activeBackground\fR, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. .OP \-selectimage selectImage SelectImage Specifies an image to display (in place of the \fB\-image\fR option) when the radiobutton is selected. This option is ignored unless the \fB\-image\fR option has been |
︙ | ︙ | |||
177 178 179 180 181 182 183 184 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for radiobutton widgets: .TP | > | > > > > > | 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for radiobutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. .\" METHOD: deselect .TP \fIpathName \fBdeselect\fR . Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flashes the radiobutton. This is accomplished by redisplaying the radiobutton several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active state as when the command was invoked. This command is ignored if the radiobutton's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Does just what would have happened if the user invoked the radiobutton with the mouse: selects the button and invokes its associated Tcl command, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is \fBdisabled\fR. .\" METHOD: select .TP \fIpathName \fBselect\fR . Selects the radiobutton and sets the associated variable to the value corresponding to this widget. .SH BINDINGS .PP |
︙ | ︙ | |||
253 254 255 256 257 258 259 | .PP If the radiobutton's state is \fBdisabled\fR then none of the above actions occur: the radiobutton is completely non-responsive. .PP The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" | | > | 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | .PP If the radiobutton's state is \fBdisabled\fR then none of the above actions occur: the radiobutton is completely non-responsive. .PP The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" checkbutton(n), labelframe(n), listbox(n), options(n), scale(n), ttk::radiobutton(n) .SH KEYWORDS radiobutton, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/raise.n.
︙ | ︙ | |||
37 38 39 40 41 42 43 | .SH EXAMPLE .PP Make a button appear to be in a sibling frame that was created after it. This is is often necessary when building GUIs in the style where you create your activity widgets first before laying them out on the display: .CS | | | | | | | 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | .SH EXAMPLE .PP Make a button appear to be in a sibling frame that was created after it. This is is often necessary when building GUIs in the style where you create your activity widgets first before laying them out on the display: .CS button .b -text "Hi there!" pack [frame .f -background blue] pack [label .f.l1 -text "This is above"] pack .b -in .f pack [label .f.l2 -text "This is below"] \fBraise\fR .b .CE .SH "SEE ALSO" lower(n) .SH KEYWORDS obscure, raise, stacking order '\" Local Variables: |
︙ | ︙ |
Changes to doc/scale.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH scale n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scale \- Create and manipulate 'scale' value-controlled slider widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH scale n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scale \- Create and manipulate 'scale' value-controlled slider widgets .SH SYNOPSIS \fBscale\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-foreground \-relief \-background \-highlightbackground \-repeatdelay \-borderwidth \-highlightcolor \-repeatinterval \-cursor \-highlightthickness \-takefocus \-font \-orient \-troughcolor .SE |
︙ | ︙ | |||
74 75 76 77 78 79 80 | If the scale is disabled then the value may not be changed and the scale will not activate. If the scale is active, the slider is displayed using the color specified by the \fB\-activebackground\fR option. .OP \-tickinterval tickInterval TickInterval Must be a real value. Determines the spacing between numerical | | > > | 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | If the scale is disabled then the value may not be changed and the scale will not activate. If the scale is active, the slider is displayed using the color specified by the \fB\-activebackground\fR option. .OP \-tickinterval tickInterval TickInterval Must be a real value. Determines the spacing between numerical tick marks displayed below or to the left of the slider. The values will all be displayed with the same number of decimal places, which will be enough to ensure they are all accurate to within 20% of a tick interval. If 0, no tick marks will be displayed. .OP \-to to To Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the \fB\-from\fR option. .OP \-variable variable Variable Specifies the name of a global variable to link to the scale. Whenever the |
︙ | ︙ | |||
139 140 141 142 143 144 145 146 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scale widgets: .TP | > | > > > > > | 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scale widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. .\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to \fIvalue\fR. If \fIvalue\fR is omitted then the scale's current value is used. .\" METHOD: get .TP \fIpathName \fBget\fR ?\fIx y\fR? . If \fIx\fR and \fIy\fR are omitted, returns the current value of the scale. If \fIx\fR and \fIy\fR are specified, they give pixel coordinates within the widget; the command returns the scale value corresponding to the given pixel. Only one of \fIx\fR or \fIy\fR is used: for horizontal scales \fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Returns a string indicating what part of the scale lies under the coordinates given by \fIx\fR and \fIy\fR. A return value of \fBslider\fR means that the point is over the slider; \fBtrough1\fR means that the point is over the portion of the slider above or to the left of the slider; and \fBtrough2\fR means that the point is over the portion of the slider below or to the right of the slider. If the point is not over one of these elements, an empty string is returned. .\" METHOD: set .TP \fIpathName \fBset \fIvalue\fR . This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. \fIValue\fR gives the new value for the scale. The command has no effect if the scale is disabled. |
︙ | ︙ |
Changes to doc/scrollbar.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH scrollbar n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH scrollbar n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets .SH SYNOPSIS \fBscrollbar\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightcolor \-repeatdelay \-background \-highlightthickness \-repeatinterval \-borderwidth \-jump \-takefocus \-cursor \-orient \-troughcolor \-highlightbackground \-relief .SE |
︙ | ︙ | |||
77 78 79 80 81 82 83 | Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See the \fBBINDINGS\fR section below for details. .SH "ELEMENTS" .PP A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar: | < | < | < | < | < | > > > > > > > > | 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 | Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See the \fBBINDINGS\fR section below for details. .SH "ELEMENTS" .PP A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar: .IP \fBarrow1\fR 10 The top or left arrow in the scrollbar. .IP \fBtrough1\fR 10 The region between the slider and \fBarrow1\fR. .IP \fBslider\fR 10 The rectangle that indicates what is visible in the associated widget. .IP \fBtrough2\fR 10 The region between the slider and \fBarrow2\fR. .IP \fBarrow2\fR 10 The bottom or right arrow in the scrollbar. .SH "WIDGET COMMAND" .PP The \fBscrollbar\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scrollbar widgets: .\" METHOD: activate .TP \fIpathName \fBactivate \fR?\fIelement\fR? . Marks the element indicated by \fIelement\fR as active, which causes it to be displayed as specified by the \fB\-activebackground\fR and \fB\-activerelief\fR options. The only element values understood by this command are \fBarrow1\fR, \fBslider\fR, or \fBarrow2\fR. If any other value is specified then no element of the scrollbar will be active. If \fIelement\fR is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. .\" METHOD: delta .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR . Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. .\" METHOD: fraction .TP \fIpathName \fBfraction \fIx y\fR . Returns a real number between 0 and 1 indicating where the point given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent \fBset\fR widget command. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Returns the name of the element under the point given by \fIx\fR and \fIy\fR (such as \fBarrow1\fR), or an empty string if the point does not lie in any element of the scrollbar. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. .\" METHOD: set .TP \fIpathName \fBset \fIfirst last\fR . This command is invoked by the scrollbar's associated widget to tell the scrollbar about the current view in the widget. The command takes two arguments, each of which is a real fraction between 0 and 1. |
︙ | ︙ | |||
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's \fB\-command\fR option. The command may take any of the following forms. In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like .QW "\fB.t yview\fR" . .TP \fIprefix \fBmoveto \fIfraction\fR . \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. If \fIfraction\fR is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .TP \fIprefix \fBscroll \fInumber \fBpages\fR . The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. | > > | 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 | must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's \fB\-command\fR option. The command may take any of the following forms. In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like .QW "\fB.t yview\fR" . .\" METHOD: moveto .TP \fIprefix \fBmoveto \fIfraction\fR . \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. If \fIfraction\fR is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .\" METHOD: scroll .TP \fIprefix \fBscroll \fInumber \fBpages\fR . The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. |
︙ | ︙ | |||
304 305 306 307 308 309 310 | .IP [14] The End key adjusts the view to the bottom (right edge) of the document. .SH EXAMPLE .PP Create a window with a scrollable \fBtext\fR widget: .CS toplevel .tl | | | | | | | 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 | .IP [14] The End key adjusts the view to the bottom (right edge) of the document. .SH EXAMPLE .PP Create a window with a scrollable \fBtext\fR widget: .CS toplevel .tl text .tl.t -yscrollcommand {.tl.s set} \fBscrollbar\fR .tl.s -command {.tl.t yview} grid .tl.t .tl.s -sticky nsew grid columnconfigure .tl 0 -weight 1 grid rowconfigure .tl 0 -weight 1 .CE .SH "SEE ALSO" ttk:scrollbar(n) .SH KEYWORDS scrollbar, widget '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/selection.n.
︙ | ︙ | |||
22 23 24 25 26 27 28 29 | .PP Note that for management of the \fBCLIPBOARD\fR selection (see below), the \fBclipboard\fR command may also be used. .PP The first argument to \fBselection\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .TP | > | > | | 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | .PP Note that for management of the \fBCLIPBOARD\fR selection (see below), the \fBclipboard\fR command may also be used. .PP The first argument to \fBselection\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .\" METHOD: clear .TP \fBselection clear\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? . If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it so that no window owns the selection anymore. \fISelection\fR specifies the X selection that should be cleared, and should be an atom name such as \fBPRIMARY\fR or \fBCLIPBOARD\fR; see the Inter-Client Communication Conventions Manual for complete details. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . Returns an empty string. .\" METHOD: get .TP \fBselection get\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? ?\fB\-type\fI type\fR? . Retrieves the value of \fIselection\fR from \fIwindow\fR's display and returns it as a result. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . \fIType\fR specifies the form in which the selection is to be returned (the desired |
︙ | ︙ | |||
57 58 59 60 61 62 63 64 | than the selection type; see the ICCCM for all the confusing details). If the selection is returned in a non-string format, such as \fBINTEGER\fR or \fBATOM\fR, the \fBselection\fR command converts it to string format as a collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that \fBselection get\fR does not retrieve the selection in the \fBUTF8_STRING\fR format unless told to. .TP | > | | 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | than the selection type; see the ICCCM for all the confusing details). If the selection is returned in a non-string format, such as \fBINTEGER\fR or \fBATOM\fR, the \fBselection\fR command converts it to string format as a collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that \fBselection get\fR does not retrieve the selection in the \fBUTF8_STRING\fR format unless told to. .\" METHOD: handle .TP \fBselection handle\fR ?\fB\-selection\fI s\fR? ?\fB\-type\fI t\fR? ?\fB\-format\fI f\fR? \fIwindow command\fR . Creates a handler for selection requests, such that \fIcommand\fR will be executed whenever selection \fIs\fR is owned by \fIwindow\fR and someone attempts to retrieve it in the form given by type \fIt\fR (e.g. \fIt\fR is specified in the \fBselection get\fR command). \fIS\fR defaults to \fBPRIMARY\fR, \fIt\fR defaults to \fBSTRING\fR, and \fIf\fR defaults to \fBSTRING\fR. If \fIcommand\fR is an empty string |
︙ | ︙ | |||
115 116 117 118 119 120 121 122 | .PP The \fIformat\fR argument is needed only for compatibility with selection requesters that do not use Tk. If Tk is being used to retrieve the selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .RE .TP | > | | | > > > > | > > > | > | > > > > > | > > | > > | > > | | | | | 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 | .PP The \fIformat\fR argument is needed only for compatibility with selection requesters that do not use Tk. If Tk is being used to retrieve the selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .RE .\" METHOD: own .TP \fBselection own\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? .TP \fBselection own\fR ?\fB\-command\fI command\fR? ?\fB\-selection\fI selection\fR? \fIwindow\fR . The first form of \fBselection own\fR returns the path name of the window in this application that owns \fIselection\fR on the display containing \fIwindow\fR, or an empty string if no window in this application owns the selection. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . .RS .PP The second form of \fBselection own\fR causes \fIwindow\fR to become the new owner of \fIselection\fR on \fIwindow\fR's display, returning an empty string as result. The existing owner, if any, is notified that it has lost the selection. If \fIcommand\fR is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from \fIwindow\fR. \fISelection\fR defaults to PRIMARY. .RE .SH WIDGET FACILITIES .PP The \fBtext\fR, \fBentry\fR, \fBttk::entry\fR, \fBlistbox\fR, \fBspinbox\fR and \fBttk::spinbox\fR widgets have the option \fB\-exportselection\fR. If a widget has this option set to boolean \fBtrue\fR, then (in an unsafe interpreter) a selection made in the widget is automatically written to the \fBPRIMARY\fR selection. .PP A GUI event, for example \fB<<PasteSelection>>\fR, can copy the \fBPRIMARY\fR selection to certain widgets. This copy is implemented by a widget binding to the event. The binding script makes appropriate calls to the \fBselection\fR command. .PP .SH PORTABILITY ISSUES .PP On X11, the \fBPRIMARY\fR selection is a system-wide feature of the X server, allowing communication between different processes that are X11 clients. .PP On Windows, the \fBPRIMARY\fR selection is not provided by the system, but only by Tk, and so it is shared only between windows of a parent interpreter and its child interpreters. It is not shared between interpreters in different processes or different threads. Each parent interpreter has a separate \fBPRIMARY\fR selection that is shared only with its child interpreters which are not safe interpreters. .PP .SH SECURITY .PP A safe interpreter cannot read from the \fBPRIMARY\fR selection because its \fBselection\fR command is hidden. For this reason the \fBPRIMARY\fR selection cannot be written to the Tk widgets of a safe interpreter. .PP A Tk widget can have its option \fB\-exportselection\fR set to boolean \fBtrue\fR, but in a safe interpreter this option has no effect: writing from the widget to the \fBPRIMARY\fR selection is disabled. .PP These are security features. A safe interpreter may run untrusted code, and it is a security risk if this untrusted code can read or write the \fBPRIMARY\fR selection used by other interpreters. .PP .SH EXAMPLES .PP On X11 platforms, one of the standard selections available is the \fBSECONDARY\fR selection. Hardly anything uses it, but here is how to read it using Tk: .PP .CS set selContents [\fBselection get\fR -selection SECONDARY] .CE .PP Many different types of data may be available for a selection; the special type \fBTARGETS\fR allows you to get a list of available types: .PP .CS foreach type [\fBselection get\fR -type TARGETS] { puts "Selection PRIMARY supports type $type" } .CE .PP To claim the selection, you must first set up a handler to supply the data for the selection. Then you have to claim the selection... .CS # Set up the data handler ready for incoming requests set foo "This is a string with some data in it... blah blah" \fBselection handle\fR -selection SECONDARY . getData proc getData {offset maxChars} { puts "Retrieving selection starting at $offset" return [string range $::foo $offset [expr {$offset+$maxChars-1}]] } # Now we grab the selection itself puts "Claiming selection" \fBselection own\fR -command lost -selection SECONDARY . proc lost {} { puts "Lost selection" } .CE .SH "SEE ALSO" clipboard(n) .SH KEYWORDS clear, format, handler, ICCCM, own, selection, target, type '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/send.n.
︙ | ︙ | |||
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | contained entirely within the \fIcmd\fR argument. If one or more \fIarg\fRs are present, they are concatenated to form the command to be executed, just as for the \fBeval\fR command. .PP If the initial arguments of the command begin with .QW \- they are treated as options. The following options are currently defined: .TP \fB\-async\fR Requests asynchronous invocation. In this case the \fBsend\fR command will complete immediately without waiting for \fIcmd\fR to complete in the target application; no result will be available and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the \fB\-async\fR option is ignored. .TP | > > > | > > > | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | contained entirely within the \fIcmd\fR argument. If one or more \fIarg\fRs are present, they are concatenated to form the command to be executed, just as for the \fBeval\fR command. .PP If the initial arguments of the command begin with .QW \- they are treated as options. The following options are currently defined: .\" OPTION: -async .TP \fB\-async\fR . Requests asynchronous invocation. In this case the \fBsend\fR command will complete immediately without waiting for \fIcmd\fR to complete in the target application; no result will be available and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the \fB\-async\fR option is ignored. .\" OPTION: -displayof .TP \fB\-displayof\fI pathName\fR . Specifies that the target application's main window is on the display of the window given by \fIpathName\fR, instead of the display containing the application's main window. .\" OPTION: -- .TP \fB\-\|\-\fR . Serves no purpose except to terminate the list of options. This option is needed only if \fIapp\fR could contain a leading .QW \- character. .SH "APPLICATION NAMES" .PP The name of an application is set initially from the name of the |
︙ | ︙ | |||
86 87 88 89 90 91 92 | functionality is provided by the \fBdde\fR command instead. .SH EXAMPLE .PP This script fragment can be used to make an application that only runs once on a particular display. .CS if {[tk appname FoobarApp] ne "FoobarApp"} { | | | 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | functionality is provided by the \fBdde\fR command instead. .SH EXAMPLE .PP This script fragment can be used to make an application that only runs once on a particular display. .CS if {[tk appname FoobarApp] ne "FoobarApp"} { \fBsend\fR -async FoobarApp RemoteStart $argv exit } # The command that will be called remotely, which raises # the application main window and opens the requested files proc RemoteStart args { raise . foreach filename $args { |
︙ | ︙ |
Changes to doc/spinbox.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH spinbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME spinbox \- Create and manipulate 'spinbox' value spinner widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH spinbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME spinbox \- Create and manipulate 'spinbox' value spinner widgets .SH SYNOPSIS \fBspinbox\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightthickness \-repeatinterval \-background \-insertbackground \-selectbackground \-borderwidth \-insertborderwidth \-selectborderwidth \-cursor \-insertontime \-selectforeground \-exportselection \-insertwidth \-takefocus \-font \-insertofftime \-textvariable |
︙ | ︙ | |||
164 165 166 167 168 169 170 | The \fB\-validatecommand\fR will be called when the spinbox loses focus. .IP \fBkey\fR 10 The \fB\-validatecommand\fR will be called when the spinbox is edited. .IP \fBall\fR 10 The \fB\-validatecommand\fR will be called for all above conditions. .PP It is possible to perform percent substitutions on the \fB\-validatecommand\fR | | | | 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | The \fB\-validatecommand\fR will be called when the spinbox loses focus. .IP \fBkey\fR 10 The \fB\-validatecommand\fR will be called when the spinbox is edited. .IP \fBall\fR 10 The \fB\-validatecommand\fR will be called for all above conditions. .PP It is possible to perform percent substitutions on the \fB\-validatecommand\fR and \fB\-invalidcommand\fR scripts, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP .IP \fB%d\fR 5 Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, or \-1 for focus, forced or textvariable validation. .IP \fB%i\fR 5 Index of char string to be inserted/deleted, if any, otherwise \-1. .IP \fB%P\fR 5 |
︙ | ︙ | |||
209 210 211 212 213 214 215 | \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the spinbox widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the value of the widget during validation and still have the \fB\-validate\fR option set, you should include the command .CS | | | | | | | | | > > > > > > > > > > | > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > | 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 | \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the spinbox widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the value of the widget during validation and still have the \fB\-validate\fR option set, you should include the command .CS \fI%W config -validate %v\fR .CE in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fB\-textvariable\fR. .PP Also, the \fB\-validate\fR option will set itself to \fBnone\fR when the spinbox value gets changed because of adjustment of \fB\-from\fR or \fB\-to\fR and the \fB\-validatecommand\fR returns false. For instance .CS \fIspinbox pathName -from 1 -to 10 -validate all -validatecommand {return 0}\fR .CE will in fact set the \fB\-validate\fR option to \fBnone\fR because the default value for the spinbox gets changed (due to the \fB\-from\fR and \fB\-to\fR options) to a value not accepted by the validation script. .PP Moreover, forced validation is performed when invoking any spinbutton of the spinbox. If the validation script returns false in this situation, then the \fB\-validate\fR option will be automatically set to \fBnone\fR. .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .SS INDICES .PP Many of the widget commands for spinboxes take one or more indices as arguments. An index specifies a particular character in the spinbox's string, in any of the following ways: .TP 12 \fInumber\fR . Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .TP 12 \fBanchor\fR . Indicates the anchor point for the selection, which is set with the \fBselect from\fR and \fBselect adjust\fR widget commands. .TP 12 \fBend\fR . Indicates the character just after the last one in the spinbox's string. This is equivalent to specifying a numerical index equal to the length of the spinbox's string. .TP 12 \fBinsert\fR . Indicates the character adjacent to and immediately following the insertion cursor. .TP 12 \fBsel.first\fR . Indicates the first character in the selection. It is an error to use this form if the selection is not in the spinbox window. .TP 12 \fBsel.last\fR . Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the spinbox window. .TP 12 \fB@\fInumber\fR . In this form, \fInumber\fR is treated as an x-coordinate in the spinbox's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .LP Abbreviations may be used for any of the forms above, e.g. .QW \fBe\fR or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for spinbox widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Delete one or more elements of the spinbox. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the spinbox's string. .\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR . Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. .\" METHOD: identify .TP \fIpathName \fBidentify\fI x y\fR . Returns the name of the window element corresponding to coordinates \fIx\fR and \fIy\fR in the spinbox. Return value is one of: \fBnone\fR, \fBbuttondown\fR, \fBbuttonup\fR, \fBentry\fR. .\" METHOD: index .TP \fIpathName \fBindex\fI index\fR . Returns the numerical index corresponding to \fIindex\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR . Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fI element\fR . Causes the specified element, either \fBbuttondown\fR or \fBbuttonup\fR, to be invoked, triggering the action associated with it. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on spinboxes. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx\fR . Records \fIx\fR and the current view in the spinbox window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx\fR . This command computes the difference between its \fIx\fR argument and the \fIx\fR argument to the last \fBscan mark\fR command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the spinbox at high speed through the window. The return value is an empty string. .RE .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within a spinbox. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection adjust \fIindex\fR . Locate the end of the selection nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection is not currently in the spinbox, then a new selection is created to include the characters between \fIindex\fR and the most recent selection anchor point, inclusive. Returns an empty string. .TP \fIpathName \fBselection clear\fR . Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection element\fR ?\fIelement\fR? . Sets or gets the currently selected element. If a spinbutton element is specified, it will be displayed depressed. .TP \fIpathName \fBselection from \fIindex\fR . Set the selection anchor point to just before the character given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR . Returns 1 if there is are characters selected in the spinbox, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR . Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the spinbox's selection is cleared. .TP \fIpathName \fBselection to \fIindex\fR . If \fIindex\fR is before the anchor point, set the selection to the characters from \fIindex\fR up to but not including the anchor point. If \fIindex\fR is the same as the anchor point, do nothing. If \fIindex\fR is after the anchor point, set the selection to the characters from the anchor point up to but not including \fIindex\fR. The anchor point is determined by the most recent \fBselect from\fR or \fBselect adjust\fR command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE .\" METHOD: set .TP \fIpathName \fBset\fR ?\fIstring\fR? . If \fIstring\fR is specified, the spinbox will try and set it to this value, otherwise it just returns the spinbox's string. If validation is on, it will occur when setting the string. .\" METHOD: validate .TP \fIpathName \fBvalidate\fR . This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the spinbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview \fIindex\fR . Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR |
︙ | ︙ |
Changes to doc/sysnotify.n.
1 2 3 4 5 6 7 8 9 10 11 12 | .\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk sysnotify n "" Tk "Tk Built-In Commands" .so man.macros .SH NAME sysnotify \- Creates a notification window with a title and message. .SH SYNOPSIS | > | | > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk sysnotify n "" Tk "Tk Built-In Commands" .so man.macros .BS .SH NAME sysnotify \- Creates a notification window with a title and message. .SH SYNOPSIS \fBtk sysnotify\fI title message\fR .BE .SH DESCRIPTION .PP The \fBtk sysnotify\fR command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. .SH EXAMPLE .PP Here is an example of the \fBtk sysnotify\fR code: .PP .CS tk sysnotify "Alert" \e "This is just a test of the Tk System Notification Code." |
︙ | ︙ |
Changes to doc/systray.n.
1 2 3 4 5 6 7 8 9 10 11 12 | .\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk systray n "" Tk "Tk Built-In Commands" .so man.macros .SH NAME systray \- Creates an icon display in the platform-specific system tray. .SH SYNOPSIS | > < | > < < | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk systray n "" Tk "Tk Built-In Commands" .so man.macros .BS .SH NAME systray \- Creates an icon display in the platform-specific system tray. .SH SYNOPSIS .nf \fBtk systray create \-image \fIimage\fR ?\fB\-text \fItext\fR? ?\fB\-button1 \fIcallback\fR? ?\fB\-button3 \fIcallback\fR? \fBtk systray configure \fI?option? ?value option value ...?\fR \fBtk systray exists\fR \fBtk systray destroy\fR .fi .BE .SH DESCRIPTION .PP .\" METHOD: create The \fBtk systray create\fR command creates an icon in the platform-specific tray. The widget is configured with a Tk image for the icon display, an optional string for display in a tooltip, and optional callbacks that are |
︙ | ︙ |
Changes to doc/text.n.
︙ | ︙ | |||
9 10 11 12 13 14 15 | .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets .SH SYNOPSIS .nf | | | | | > | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets .SH SYNOPSIS .nf \fBtext\fI pathName \fR?\fIoptions\fR? \fBtk_textCopy\fI pathName\fR \fBtk_textCut\fI pathName\fR \fBtk_textPaste\fI pathName\fR .fi .SO \-background \-highlightthickness \-relief \-borderwidth \-insertbackground \-selectbackground \-cursor \-insertborderwidth \-selectborderwidth \-exportselection \-insertofftime \-selectforeground \-font \-insertontime \-setgrid \-foreground \-insertwidth \-takefocus |
︙ | ︙ | |||
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 | as determined by the \fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the text widget. However, display options may be associated with individual tags using the .QW "\fIpathName \fBtag configure\fR" widget command. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags: .TP \fB\-background \fIcolor\fR . \fIColor\fR specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-bgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used for the background. .TP \fB\-borderwidth \fIpixels\fR . \fIPixels\fR specifies the width of a border to draw around the tag using any of the forms accepted by \fBTk_GetPixels\fR. This option should be used in conjunction with the \fB\-relief\fR option to provide the desired border. .TP \fB\-elide \fIboolean\fR . \fIElide\fR specifies whether the data should be elided. Elided data (characters, images, embedded windows, etc.) is not displayed and takes no space on screen, but further on behaves just as normal data. .TP \fB\-fgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used. .TP \fB\-font \fIfontName\fR . \fIFontName\fR is the name of a font to use for drawing characters. It may have any of the forms accepted by \fBTk_GetFont\fR. .TP \fB\-foreground \fIcolor\fR . \fIColor\fR specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetColor\fR. .TP \fB\-justify \fIjustify\fR . If the first non-elided character of a display line has a tag for which this option has been specified, then \fIjustify\fR determines how to justify the line. It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. If a line wraps, then the justification for each line on the display is determined by the first non-elided character of that display line. .TP \fB\-lmargin1 \fIpixels\fR . If the first non-elided character of a text line has a tag for which this option has been specified, then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the \fB\-lmargin2\fR option controls the indentation for subsequent lines. .TP \fB\-lmargin2 \fIpixels\fR . If the first non-elided character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line. .TP \fB\-lmargincolor \fIcolor\fR . \fIColor\fR specifies the background color to use in regions that do not contain characters because they are indented by \fB\-lmargin1\fR or \fB\-lmargin2\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the | > > > > > > > > > > > | | > > > > > > | | > > > > > > > > > > > > | 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 | as determined by the \fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the text widget. However, display options may be associated with individual tags using the .QW "\fIpathName \fBtag configure\fR" widget command. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags: .\" OPTION: -background .TP \fB\-background \fIcolor\fR . \fIColor\fR specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -bgstipple .TP \fB\-bgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used for the background. .\" OPTION: -borderwidth .TP \fB\-borderwidth \fIpixels\fR . \fIPixels\fR specifies the width of a border to draw around the tag using any of the forms accepted by \fBTk_GetPixels\fR. This option should be used in conjunction with the \fB\-relief\fR option to provide the desired border. .\" OPTION: -elide .TP \fB\-elide \fIboolean\fR . \fIElide\fR specifies whether the data should be elided. Elided data (characters, images, embedded windows, etc.) is not displayed and takes no space on screen, but further on behaves just as normal data. .\" OPTION: -fgstipple .TP \fB\-fgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used. .\" OPTION: -font .TP \fB\-font \fIfontName\fR . \fIFontName\fR is the name of a font to use for drawing characters. It may have any of the forms accepted by \fBTk_GetFont\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . \fIColor\fR specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -justify .TP \fB\-justify \fIjustify\fR . If the first non-elided character of a display line has a tag for which this option has been specified, then \fIjustify\fR determines how to justify the line. It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. If a line wraps, then the justification for each line on the display is determined by the first non-elided character of that display line. .\" OPTION: -lmargin1 .TP \fB\-lmargin1 \fIpixels\fR . If the first non-elided character of a text line has a tag for which this option has been specified, then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the \fB\-lmargin2\fR option controls the indentation for subsequent lines. .\" OPTION: -lmargin2 .TP \fB\-lmargin2 \fIpixels\fR . If the first non-elided character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line. .\" OPTION: -lmargincolor .TP \fB\-lmargincolor \fIcolor\fR . \fIColor\fR specifies the background color to use in regions that do not contain characters because they are indented by \fB\-lmargin1\fR or \fB\-lmargin2\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the \fB\-background\fR tag option (or, if this is also unspecified, by the \fB\-background\fR widget option). .\" OPTION: -offset .TP \fB\-offset \fIpixels\fR . \fIPixels\fR specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. \fIPixels\fR may have any of the standard forms for screen distances. .\" OPTION: -overstrike .TP \fB\-overstrike \fIboolean\fR . Specifies whether or not to draw a horizontal rule through the middle of characters. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. .\" OPTION: -overstrikefg .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. .\" OPTION: -relief .TP \fB\-relief \fIrelief\fR . \fIRelief\fR specifies the relief style to use for drawing the border, in any of the forms accepted by \fBTk_GetRelief\fR. This option is used in conjunction with the \fB\-borderwidth\fR option to enable to the desired border appearance. .\" OPTION: -rmargin .TP \fB\-rmargin \fIpixels\fR . If the first non-elided character of a display line has a tag for which this option has been specified, then \fIpixels\fR specifies how wide a margin to leave between the end of the line and the right edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first non-elided character of that display line. .\" OPTION: -rmargincolor .TP \fB\-rmargincolor \fIcolor\fR . \fIColor\fR specifies the background color to use in regions that do not contain characters because they are indented by \fB\-rmargin\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the \fB\-background\fR tag option (or, if this is also unspecified, by the \fB\-background\fR widget option). .\" OPTION: -selectbackground .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. .\" OPTION: -selectforeground .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. .\" OPTION: -spacing1 .TP \fB\-spacing1 \fIpixels\fR . \fIPixels\fR specifies how much additional space should be left above each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. .\" OPTION: -spacing2 .TP \fB\-spacing2 \fIpixels\fR . For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. \fIPixels\fR may have any of the standard forms for screen distances. .\" OPTION: -spacing3 .TP \fB\-spacing3 \fIpixels\fR . \fIPixels\fR specifies how much additional space should be left below each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. .\" OPTION: -tabs .TP \fB\-tabs \fItabList\fR . \fITabList\fR specifies a set of tab stops in the same form as for the \fB\-tabs\fR option for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as \fB\-tags\0{\0}\fR, then it requests default 8-character tabs as described for the \fB\-tags\fR widget option. .\" OPTION: -tabstyle .TP \fB\-tabstyle \fIstyle\fR . \fIStyle\fR specifies either the \fItabular\fR or \fIwordprocessor\fR style of tabbing to use for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). .\" OPTION: -underline .TP \fB\-underline \fIboolean\fR . \fIBoolean\fR specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR. .\" OPTION: -underlinefg .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. .\" OPTION: -wrap .TP \fB\-wrap \fImode\fR . \fIMode\fR specifies how to handle lines that are wider than the text's window. This option only applies to a display line if it applies to the first non-elided character on that display line. It has the same legal values as the \fB\-wrap\fR option for the text widget: \fBnone\fR, |
︙ | ︙ | |||
692 693 694 695 696 697 698 | unit's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed. Similarly if the text widget as a whole is deleted, then the window is destroyed. .PP Eliding an embedded window immediately after scheduling it for creation via | | | > > > > > > | 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 | unit's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed. Similarly if the text widget as a whole is deleted, then the window is destroyed. .PP Eliding an embedded window immediately after scheduling it for creation via \fIpathName \fBwindow create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded window scheduled for creation via \fIpathName \fBwindow create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded window, the latter won't get automatically recreated. .PP When an embedded window is added to a text widget with the \fIpathName \fBwindow create\fR widget command, several configuration options may be associated with it. These options may be modified later with the \fIpathName \fBwindow configure\fR widget command. The following options are currently supported: .\" OPTION: -align .TP \fB\-align \fIwhere\fR . If the window is not as tall as the line in which it is displayed, this option determines where the window is displayed in the line. \fIWhere\fR must have one of the values \fBtop\fR (align the top of the window with the top of the line), \fBcenter\fR (center the window within the range of the line), \fBbottom\fR (align the bottom of the window with the bottom of the line's area), or \fBbaseline\fR (align the bottom of the window with the baseline of the line). .\" OPTION: -create .TP \fB\-create \fIscript\fR . Specifies a Tcl script that may be evaluated to create the window for the annotation. If no \fB\-window\fR option has been specified for the annotation this script will be evaluated when the annotation is about to be displayed on the screen. \fIScript\fR must create a window for the annotation and return the name of that window as its result. Two substitutions will be performed in \fIscript\fR before evaluation. \fI%W\fR will be substituted by the name of the parent text widget, and \fI%%\fR will be substituted by a single \fI%\fR. If the annotation's window should ever be deleted, \fIscript\fR will be evaluated again the next time the annotation is displayed. .\" OPTION: -padx .TP \fB\-padx \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on each side of the embedded window. It may have any of the usual forms defined for a screen distance. .\" OPTION: -pady .TP \fB\-pady \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on the top and on the bottom of the embedded window. It may have any of the usual forms defined for a screen distance. .\" OPTION: -stretch .TP \fB\-stretch \fIboolean\fR . If the requested height of the embedded window is less than the height of the line in which it is displayed, this option can be used to specify whether the window should be stretched vertically to fill its line. If the \fB\-pady\fR option has been specified as well, then the requested padding will be retained even if the window is stretched. .\" OPTION: -window .TP \fB\-window \fIpathName\fR . Specifies the name of a window to display in the annotation. Note that if a \fIpathName\fR has been set, then later configuring a window to the empty string will not delete the widget corresponding to the old \fIpathName\fR. Rather it will remove the association between the old \fIpathName\fR and the |
︙ | ︙ | |||
771 772 773 774 775 776 777 | space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget with \fIpathName \fBimage create\fR. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. .PP Eliding an embedded image immediately after scheduling it for creation via | | | > > > > > | 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 | space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget with \fIpathName \fBimage create\fR. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. .PP Eliding an embedded image immediately after scheduling it for creation via \fIpathName \fBimage create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded image scheduled for creation via \fIpathName \fBimage create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded image, the latter won't get automatically recreated. .PP When an embedded image is added to a text widget with the \fIpathName \fBimage create\fR widget command, a name unique to this instance of the image is returned. This name may then be used to refer to this image instance. The name is taken to be the value of the \fB\-name\fR option (described below). If the \fB\-name\fR option is not provided, the \fB\-image\fR name is used instead. If the \fIimageName\fR is already in use in the text widget, then \fB#\fInn\fR is added to the end of the \fIimageName\fR, where \fInn\fR is an arbitrary integer. This insures the \fIimageName\fR is unique. Once this name is assigned to this instance of the image, it does not change, even though the \fB\-image\fR or \fB\-name\fR values can be changed with \fIpathName \fBimage configure\fR. .PP When an embedded image is added to a text widget with the \fIpathName \fBimage create\fR widget command, several configuration options may be associated with it. These options may be modified later with the \fIpathName \fBimage configure\fR widget command. The following options are currently supported: .\" OPTION: -align .TP \fB\-align \fIwhere\fR . If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. \fIWhere\fR must have one of the values \fBtop\fR (align the top of the image with the top of the line), \fBcenter\fR (center the image within the range of the line), \fBbottom\fR (align the bottom of the image with the bottom of the line's area), or \fBbaseline\fR (align the bottom of the image with the baseline of the line). .\" OPTION: -image .TP \fB\-image \fIimage\fR . Specifies the name of the Tk image to display in the annotation. If \fIimage\fR is not a valid Tk image, then an error is returned. .\" OPTION: -name .TP \fB\-name \fIImageName\fR . Specifies the name by which this image instance may be referenced in the text widget. If \fIImageName\fR is not supplied, then the name of the Tk image is used instead. If the \fIimageName\fR is already in use, \fI#nn\fR is appended to the end of the name as described above. .\" OPTION: -padx .TP \fB\-padx \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on each side of the embedded image. It may have any of the usual forms defined for a screen distance. .\" OPTION: -pady .TP \fB\-pady \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on the top and on the bottom of the embedded image. It may have any of the usual forms defined for a screen distance. .SH "THE SELECTION" |
︙ | ︙ | |||
975 976 977 978 979 980 981 | creation of peer widgets. .SH "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" .PP In order to maintain a responsive user-experience, the text widget calculates lines metrics (line heights in pixels) asynchronously. Because of this, some commands of the text widget may return wrong results if the asynchronous calculations are not finished at the time of calling. This applies to | | | 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 | creation of peer widgets. .SH "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" .PP In order to maintain a responsive user-experience, the text widget calculates lines metrics (line heights in pixels) asynchronously. Because of this, some commands of the text widget may return wrong results if the asynchronous calculations are not finished at the time of calling. This applies to \fIpathName \fBcount \-ypixels\fR and \fIpathName \fByview\fR. .PP Again for performance reasons, it would not be appropriate to let these commands always wait for the end of the update calculation each time they are called. In most use cases of these commands a more or less inaccurate result does not really matter compared to execution speed. .PP In case accurate result is needed (and if the text widget is managed by a |
︙ | ︙ | |||
1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the text widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for text widgets: .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four elements describing the screen area of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. .TP | > > | > | > > | 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 | operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the text widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for text widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four elements describing the screen area of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. .\" METHOD: compare .TP \fIpathName \fBcompare\fI index1 op index2\fR . Compares the indices given by \fIindex1\fR and \fIindex2\fR according to the relational operator given by \fIop\fR, and returns 1 if the relationship is satisfied and 0 if it is not. \fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. If \fIop\fR is == then 1 is returned if the two indices refer to the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR refers to an earlier character in the text than \fIindex2\fR, and so on. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. .\" METHOD: count .TP \fIpathName \fBcount\fR ?\fIoptions\fR? \fIindex1 index2\fR . Counts the number of relevant things between the two indices. If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number (and this holds for each of the possible options). The actual items which are counted depend on the options given. The result is a list of integers, one for the result of |
︙ | ︙ | |||
1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 | The command returns a positive or negative integer corresponding to the number of items counted between the two indices. One such integer is returned for each counting option given, so a list is returned if more than one option was supplied. For example .QW ".text count \-xpixels \-ypixels 1.3 4.5" is perfectly valid and will return a list of two elements. .RE .TP \fIpathName \fBdebug \fR?\fIboolean\fR? . If \fIboolean\fR is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. If the value is a true one then internal consistency checks will be turned on in the B-tree code associated with text widgets. If \fIboolean\fR has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If \fIboolean\fR is not specified then the command returns \fBon\fR or \fBoff\fR to indicate whether or not debugging is turned on. There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down. .RS .PP When debugging is turned on, the drawing routines of the text widget set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. .RE .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? . Delete a range of characters from the text. If both \fIindex1\fR and \fIindex2\fR are specified, then delete all the characters starting with the one given by \fIindex1\fR and stopping just before \fIindex2\fR (i.e. the character at | > > | 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 | The command returns a positive or negative integer corresponding to the number of items counted between the two indices. One such integer is returned for each counting option given, so a list is returned if more than one option was supplied. For example .QW ".text count \-xpixels \-ypixels 1.3 4.5" is perfectly valid and will return a list of two elements. .RE .\" METHOD: debug .TP \fIpathName \fBdebug \fR?\fIboolean\fR? . If \fIboolean\fR is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. If the value is a true one then internal consistency checks will be turned on in the B-tree code associated with text widgets. If \fIboolean\fR has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If \fIboolean\fR is not specified then the command returns \fBon\fR or \fBoff\fR to indicate whether or not debugging is turned on. There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down. .RS .PP When debugging is turned on, the drawing routines of the text widget set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. .RE .\" METHOD: delete .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 |
︙ | ︙ | |||
1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 | All indices are first checked for validity before any deletions are made. They are sorted and the text is removed from the last range to the first range so deleted text does not cause an undesired index shifting side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text outside the given ranges due to text shifted during deletion. .TP \fIpathName \fBdlineinfo \fIindex\fR . Returns a list with five elements describing the area occupied by the display line containing \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is \fBnone\fR and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing \fIindex\fR is not visible on the screen then the return value is an empty list. .TP \fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? . Return the contents of the text widget from \fIindex1\fR up to, but not including \fIindex2\fR, including the text and information about marks, tags, and embedded windows. If \fIindex2\fR is not specified, then it defaults to one character past \fIindex1\fR. The information is returned in the following format: .RS .LP \fIkey1 value1 index1 key2 value2 index2\fR ... .LP The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR, \fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding \fIvalue\fR is the text, mark name, tag name, image name, or window name. The \fIindex\fR information is the index of the start of the text, mark, tag transition, image or window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump: .TP \fB\-all\fR . Return information about all elements: text, marks, tags, images and windows. This is the default. .TP \fB\-command \fIcommand\fR . Instead of returning the information as the result of the dump operation, invoke the \fIcommand\fR on each element of the text widget within the range. The command has three arguments appended to it before it is evaluated: the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. .TP \fB\-image\fR . Include information about images in the dump results. .TP \fB\-mark\fR . Include information about marks in the dump results. .TP \fB\-tag\fR . Include information about tag transitions in the dump results. Tag information is returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the begin and end of each range of each tag, respectively. .TP \fB\-text\fR . Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by \fIindex2\fR. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text segments that each end with a newline. The newline is part of the value. .TP \fB\-window\fR . Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. .RE .TP \fIpathName \fBedit \fIoption \fR?\fIarg ...\fR? . This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBedit\fR argument. The following forms of the command are currently supported: | > > > > > > > > > > | 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 | 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. .\" METHOD: dlineinfo .TP \fIpathName \fBdlineinfo \fIindex\fR . Returns a list with five elements describing the area occupied by the display line containing \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is \fBnone\fR and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing \fIindex\fR is not visible on the screen then the return value is an empty list. .\" METHOD: dump .TP \fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? . Return the contents of the text widget from \fIindex1\fR up to, but not including \fIindex2\fR, including the text and information about marks, tags, and embedded windows. If \fIindex2\fR is not specified, then it defaults to one character past \fIindex1\fR. The information is returned in the following format: .RS .LP \fIkey1 value1 index1 key2 value2 index2\fR ... .LP The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR, \fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding \fIvalue\fR is the text, mark name, tag name, image name, or window name. The \fIindex\fR information is the index of the start of the text, mark, tag transition, image or window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump: .\" OPTION: -all .TP \fB\-all\fR . Return information about all elements: text, marks, tags, images and windows. This is the default. .\" OPTION: -command .TP \fB\-command \fIcommand\fR . Instead of returning the information as the result of the dump operation, invoke the \fIcommand\fR on each element of the text widget within the range. The command has three arguments appended to it before it is evaluated: the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. .\" OPTION: -image .TP \fB\-image\fR . Include information about images in the dump results. .\" OPTION: -mark .TP \fB\-mark\fR . Include information about marks in the dump results. .\" OPTION: -tag .TP \fB\-tag\fR . Include information about tag transitions in the dump results. Tag information is returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the begin and end of each range of each tag, respectively. .\" OPTION: -text .TP \fB\-text\fR . Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by \fIindex2\fR. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text segments that each end with a newline. The newline is part of the value. .\" OPTION: -window .TP \fB\-window\fR . Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. .RE .\" METHOD: edit .TP \fIpathName \fBedit \fIoption \fR?\fIarg ...\fR? . This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBedit\fR argument. The following forms of the command are currently supported: |
︙ | ︙ | |||
1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 | . Undoes the last edit action when the \fB\-undo\fR option is true, and returns a list of indices indicating what ranges were changed by the undo operation. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE .TP \fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? . Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is \fIindex1\fR and ending just before the one whose index is \fIindex2\fR (the character at \fIindex2\fR will not be returned). If \fIindex2\fR is omitted then the single character at \fIindex1\fR is returned. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. .TP \fIpathName \fBimage \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded images. The behavior of the command depends on the \fIoption\fR argument that follows the \fBimage\fR argument. The following forms of the command are currently supported: .RS | > > | 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 | . Undoes the last edit action when the \fB\-undo\fR option is true, and returns a list of indices indicating what ranges were changed by the undo operation. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE .\" METHOD: get .TP \fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? . Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is \fIindex1\fR and ending just before the one whose index is \fIindex2\fR (the character at \fIindex2\fR will not be returned). If \fIindex2\fR is omitted then the single character at \fIindex1\fR is returned. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. .\" METHOD: image .TP \fIpathName \fBimage \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded images. The behavior of the command depends on the \fIoption\fR argument that follows the \fBimage\fR argument. The following forms of the command are currently supported: .RS |
︙ | ︙ | |||
1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 | identifier returned. .TP \fIpathName \fBimage names\fR . Returns a list whose elements are the names of all image instances currently embedded in \fIwindow\fR. .RE .TP \fIpathName \fBindex \fIindex\fR . Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR where \fIline\fR is the line number and \fIchar\fR is the character number. \fIIndex\fR may have any of the forms described under \fBINDICES\fR above. .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? . Inserts all of the \fIchars\fR arguments just before the character at \fIindex\fR. If \fIindex\fR refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single \fIchars\fR argument and no \fItagList\fR, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If \fItagList\fR is specified then it consists of a list of tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, they produce the same effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. .TP \fIpathName \fBmark \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate marks. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBmark\fR argument. The following forms of the command are currently supported: .RS | > > > | 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 | identifier returned. .TP \fIpathName \fBimage names\fR . Returns a list whose elements are the names of all image instances currently embedded in \fIwindow\fR. .RE .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR where \fIline\fR is the line number and \fIchar\fR is the character number. \fIIndex\fR may have any of the forms described under \fBINDICES\fR above. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? . Inserts all of the \fIchars\fR arguments just before the character at \fIindex\fR. If \fIindex\fR refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single \fIchars\fR argument and no \fItagList\fR, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If \fItagList\fR is specified then it consists of a list of tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, they produce the same effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. .\" METHOD: mark .TP \fIpathName \fBmark \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate marks. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBmark\fR argument. The following forms of the command are currently supported: .RS |
︙ | ︙ | |||
1443 1444 1445 1446 1447 1448 1449 | specified in numerical form, then the search for the next mark begins at that index. If \fIindex\fR is the name of a mark, then the search for the next mark begins immediately after that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the \fBmark next\fR operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the \fIpathName \fBdump\fR operation. If a mark has been set to the special | | | 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 | specified in numerical form, then the search for the next mark begins at that index. If \fIindex\fR is the name of a mark, then the search for the next mark begins immediately after that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the \fBmark next\fR operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the \fIpathName \fBdump\fR operation. If a mark has been set to the special \fBend\fR index, then it appears to be \fIafter \fBend\fR with respect to the \fIpathName \fBmark next\fR operation. An empty string is returned if there are no marks after \fIindex\fR. .TP \fIpathName \fBmark previous \fIindex\fR . Returns the name of the mark at or before \fIindex\fR. If \fIindex\fR is specified in numerical form, then the search for the previous mark begins with |
︙ | ︙ | |||
1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 | . Remove the mark corresponding to each of the \fImarkName\fR arguments. The removed marks will not be usable in indices and will not be returned by future calls to .QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE .TP \fIpathName \fBpeer \fIoption args\fR . This command is used to create and query widget peers. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBpeer create \fInewPathName\fR ?\fIoptions\fR? . Creates a peer text widget with the given \fInewPathName\fR, and any optional standard configuration options (as for the \fItext\fR command). By default the peer will have the same start and end line as the parent widget, but these can be overridden with the standard configuration options. .TP \fIpathName \fBpeer names\fR . Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. .RE .TP \fIpathName \fBpendingsync\fR Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. .TP | > > > > | > > | 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 | . Remove the mark corresponding to each of the \fImarkName\fR arguments. The removed marks will not be usable in indices and will not be returned by future calls to .QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE .\" METHOD: peer .TP \fIpathName \fBpeer \fIoption args\fR . This command is used to create and query widget peers. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBpeer create \fInewPathName\fR ?\fIoptions\fR? . Creates a peer text widget with the given \fInewPathName\fR, and any optional standard configuration options (as for the \fItext\fR command). By default the peer will have the same start and end line as the parent widget, but these can be overridden with the standard configuration options. .TP \fIpathName \fBpeer names\fR . Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. .RE .\" METHOD: pendingsync .TP \fIpathName \fBpendingsync\fR . Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. .\" METHOD: replace .TP \fIpathName \fBreplace\fI index1 index2 chars\fR ?\fItagList chars tagList ...\fR? . Replaces the range of characters between \fIindex1\fR and \fIindex2\fR with the given characters and tags. See the section on \fIpathName \fBinsert\fR for an explanation of the handling of the \fItagList...\fR arguments, and the section on \fIpathName \fBdelete\fR for an explanation of the handling of the indices. If \fIindex2\fR corresponds to an index earlier in the text than \fIindex1\fR, an error will be generated. .RS .PP The deletion and insertion are arranged so that no unnecessary scrolling of the window or movement of insertion cursor occurs. In addition the undo/redo stack are correctly modified, if undo operations are active in the text widget. The command returns an empty string. .RE .\" METHOD: scan .TP \fIpathName \fBscan \fIoption args\fR . This command is used to implement scanning on texts. It has two forms, depending on \fIoption\fR: .RS .TP |
︙ | ︙ | |||
1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 | This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last \fIpathName \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string. .RE .TP \fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? . Searches the text in \fIpathName\fR starting at \fIindex\fR for a range of characters that matches \fIpattern\fR. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search: .RS .TP \fB\-forwards\fR . The search will proceed forward through the text, finding the first matching range starting at or after the position given by \fIindex\fR. This is the default. .TP \fB\-backwards\fR . The search will proceed backward through the text, finding the matching range closest to \fIindex\fR whose first character is before \fIindex\fR (it is not allowed to be at \fIindex\fR). Note that, for a variety of reasons, backwards searches can be substantially slower than forwards searches (particularly when using \fB\-regexp\fR), so it is recommended that performance-critical code use forward searches. .TP \fB\-exact\fR . Use exact matching: the characters in the matching range must be identical to those in \fIpattern\fR. This is the default. .TP \fB\-regexp\fR . Treat \fIpattern\fR as a regular expression and match it against the text using the rules for regular expressions (see the \fBregexp\fR command and the \fBre_syntax\fR page for details). The default matching automatically passes both the \fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless \fB\-nolinestop\fR is used), so that \fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR sequences will never match the newline character \fI\en\fR. .TP \fB\-nolinestop\fR . This allows \fI.\fR and \fI[^\fR sequences to match the newline character \fI\en\fR, which they will otherwise not do (see the \fBregexp\fR command for details). This option is only meaningful if \fB\-regexp\fR is also given, and an error will be thrown otherwise. For example, to match the entire text, use .QW "\fIpathName \fBsearch \-nolinestop \-regexp\fR \N'34'.*\N'34' 1.0" . .TP \fB\-nocase\fR . Ignore case differences between the pattern and the text. .TP \fB\-count\fI varName\fR . The argument following \fB\-count\fR gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range (and there are no elided characters if \fB\-elide\fR is not given), this is equivalent to the number of characters matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count chars\fR will return the entire matched text. .TP \fB\-all\fR . Find all matches in the given range and return a list of the indices of the first character of each match. If a \fB\-count\fI varName\fR switch is given, then \fIvarName\fR is also set to a list containing one element for each successful match. Note that, even for exact searches, the elements of this list may be different, if there are embedded images, windows or hidden text. Searches with \fB\-all\fR behave very similarly to the Tcl command \fBregexp \-all\fR, in that overlapping matches are not normally returned. For example, applying an \fB\-all\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice, once for each word, and matching .QW "Z[a\-z]+Z" against .QW ZooZooZoo will just match once. .TP \fB\-overlap\fR . When performing \fB\-all\fR searches, the normal behaviour is that matches which overlap an already-found match will not be returned. This switch changes that behaviour so that all matches which are not totally enclosed within another match are returned. For example, applying an \fB\-overlap\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice (i.e. no different to just \fB\-all\fR), but matching .QW Z[a\-z]+Z against .QW ZooZooZoo will now match twice. An error will be thrown if this switch is used without \fB\-all\fR. .TP \fB\-strictlimits\fR . When performing any search, the normal behaviour is that the start and stop limits are checked with respect to the start of the matching text. With the \fB\-strictlimits\fR flag, the entire matching range must lie inside the start and stop limits specified for the match to be valid. .TP \fB\-elide\fR . Find elided (hidden) text as well. By default only displayed text is searched. .TP \fB\-\|\-\fR . This switch has no effect except to terminate the list of switches: the next argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. .PP The matching range may be within a single line of text, or run across multiple | > > > > > > > > > > > > > | 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 | This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last \fIpathName \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string. .RE .\" METHOD: search .TP \fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? . Searches the text in \fIpathName\fR starting at \fIindex\fR for a range of characters that matches \fIpattern\fR. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search: .RS .\" OPTION: -forwards .TP \fB\-forwards\fR . The search will proceed forward through the text, finding the first matching range starting at or after the position given by \fIindex\fR. This is the default. .\" OPTION: -backwards .TP \fB\-backwards\fR . The search will proceed backward through the text, finding the matching range closest to \fIindex\fR whose first character is before \fIindex\fR (it is not allowed to be at \fIindex\fR). Note that, for a variety of reasons, backwards searches can be substantially slower than forwards searches (particularly when using \fB\-regexp\fR), so it is recommended that performance-critical code use forward searches. .\" OPTION: -exact .TP \fB\-exact\fR . Use exact matching: the characters in the matching range must be identical to those in \fIpattern\fR. This is the default. .\" OPTION: -regexp .TP \fB\-regexp\fR . Treat \fIpattern\fR as a regular expression and match it against the text using the rules for regular expressions (see the \fBregexp\fR command and the \fBre_syntax\fR page for details). The default matching automatically passes both the \fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless \fB\-nolinestop\fR is used), so that \fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR sequences will never match the newline character \fI\en\fR. .\" OPTION: -nolinestop .TP \fB\-nolinestop\fR . This allows \fI.\fR and \fI[^\fR sequences to match the newline character \fI\en\fR, which they will otherwise not do (see the \fBregexp\fR command for details). This option is only meaningful if \fB\-regexp\fR is also given, and an error will be thrown otherwise. For example, to match the entire text, use .QW "\fIpathName \fBsearch \-nolinestop \-regexp\fR \N'34'.*\N'34' 1.0" . .\" OPTION: -nocase .TP \fB\-nocase\fR . Ignore case differences between the pattern and the text. .\" OPTION: -count .TP \fB\-count\fI varName\fR . The argument following \fB\-count\fR gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range (and there are no elided characters if \fB\-elide\fR is not given), this is equivalent to the number of characters matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count chars\fR will return the entire matched text. .\" OPTION: -all .TP \fB\-all\fR . Find all matches in the given range and return a list of the indices of the first character of each match. If a \fB\-count\fI varName\fR switch is given, then \fIvarName\fR is also set to a list containing one element for each successful match. Note that, even for exact searches, the elements of this list may be different, if there are embedded images, windows or hidden text. Searches with \fB\-all\fR behave very similarly to the Tcl command \fBregexp \-all\fR, in that overlapping matches are not normally returned. For example, applying an \fB\-all\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice, once for each word, and matching .QW "Z[a\-z]+Z" against .QW ZooZooZoo will just match once. .\" OPTION: -overlap .TP \fB\-overlap\fR . When performing \fB\-all\fR searches, the normal behaviour is that matches which overlap an already-found match will not be returned. This switch changes that behaviour so that all matches which are not totally enclosed within another match are returned. For example, applying an \fB\-overlap\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice (i.e. no different to just \fB\-all\fR), but matching .QW Z[a\-z]+Z against .QW ZooZooZoo will now match twice. An error will be thrown if this switch is used without \fB\-all\fR. .\" OPTION: -strictlimits .TP \fB\-strictlimits\fR . When performing any search, the normal behaviour is that the start and stop limits are checked with respect to the start of the matching text. With the \fB\-strictlimits\fR flag, the entire matching range must lie inside the start and stop limits specified for the match to be valid. .\" OPTION: -elide .TP \fB\-elide\fR . Find elided (hidden) text as well. By default only displayed text is searched. .\" OPTION: -- .TP \fB\-\|\-\fR . This switch has no effect except to terminate the list of switches: the next argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. .PP The matching range may be within a single line of text, or run across multiple |
︙ | ︙ | |||
1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 | beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if \fIstopIndex\fR is specified, no wrap-around will occur. This means that, for example, if the search is \fB\-forwards\fR but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of minor limitations of the \fIpathName \fBsearch\fR command. .RE .TP \fIpathName \fBsee \fIindex\fR . Adjusts the view in the window so that the character given by \fIindex\fR is completely visible. If \fIindex\fR is already visible then the command does nothing. If \fIindex\fR is a short distance out of view, the command adjusts the view just enough to make \fIindex\fR visible at the edge of the window. If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the window. .TP | > > | > > | > > | 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 | beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if \fIstopIndex\fR is specified, no wrap-around will occur. This means that, for example, if the search is \fB\-forwards\fR but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of minor limitations of the \fIpathName \fBsearch\fR command. .RE .\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . Adjusts the view in the window so that the character given by \fIindex\fR is completely visible. If \fIindex\fR is already visible then the command does nothing. If \fIindex\fR is a short distance out of view, the command adjusts the view just enough to make \fIindex\fR visible at the edge of the window. If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the window. .\" METHOD: sync .TP \fIpathName \fBsync\fR ?\fB\-command \fIcommand\fR? . Controls the synchronization of the view of the text widget. .RS .TP \fIpathName \fBsync\fR . Immediately brings the line metrics up-to-date by forcing computation of any outdated line heights. The command returns immediately if there is no such outdated line heights, otherwise it returns only at the end of the computation. The command returns an empty string. .TP \fIpathName \fBsync \-command \fIcommand\fR . Schedules \fIcommand\fR to be executed (by the event loop) exactly once as soon as all line heights are up-to-date. If there are no pending line metrics calculations, the scheduling is immediate. The command returns the empty string. \fBbgerror\fR is called on \fIcommand\fR failure. .RE .\" METHOD: tag .TP \fIpathName \fBtag \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate tags. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBtag\fR argument. The following forms of the command are currently supported: .RS |
︙ | ︙ | |||
1834 1835 1836 1837 1838 1839 1840 | starting at \fIindex2\fR will be considered). If several matching ranges exist, the one closest to \fIindex1\fR is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the beginning of the text. .TP | | | 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 | starting at \fIindex2\fR will be considered). If several matching ranges exist, the one closest to \fIindex1\fR is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the beginning of the text. .TP \fIpathName \fBtag raise \fItagName \fR?\fIaboveThis\fR? . Changes the priority of tag \fItagName\fR so that it is just higher in priority than the tag whose name is \fIaboveThis\fR. If \fIaboveThis\fR is omitted, then \fItagName\fR's priority is changed to make it highest priority of all tags. .TP \fIpathName \fBtag ranges \fItagName\fR |
︙ | ︙ | |||
1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 | \fIindex2\fR is not affected). A single command may contain any number of \fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the tag is removed from the single character at \fIindex1\fR. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. This command returns an empty string. .RE .TP \fIpathName \fBwindow \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded windows. The behavior of the command depends on the \fIoption\fR argument that follows the \fBwindow\fR argument. The following forms of the command are currently supported: .RS | > | 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 | \fIindex2\fR is not affected). A single command may contain any number of \fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the tag is removed from the single character at \fIindex1\fR. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. This command returns an empty string. .RE .\" METHOD: window .TP \fIpathName \fBwindow \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded windows. The behavior of the command depends on the \fIoption\fR argument that follows the \fBwindow\fR argument. The following forms of the command are currently supported: .RS |
︙ | ︙ | |||
1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 | information on the options that are supported. Returns an empty string. .TP \fIpathName \fBwindow names\fR . Returns a list whose elements are the names of all windows currently embedded in \fIwindow\fR. .RE .TP \fIpathName \fBxview \fIoption args\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP | > | 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 | information on the options that are supported. Returns an empty string. .TP \fIpathName \fBwindow names\fR . Returns a list whose elements are the names of all windows currently embedded in \fIwindow\fR. .RE .\" METHOD: xview .TP \fIpathName \fBxview \fIoption args\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP |
︙ | ︙ | |||
1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 | pixels are assumed). If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is \fBpixels\fR then the view adjusts by \fInumber\fR pixels; if it is \fBunits\fR, the view adjusts left or right by \fInumber\fR average-width characters on the display. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP | > | 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 | pixels are assumed). If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is \fBpixels\fR then the view adjusts by \fInumber\fR pixels; if it is \fBunits\fR, the view adjusts left or right by \fInumber\fR average-width characters on the display. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE .\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP |
︙ | ︙ | |||
2251 2252 2253 2254 2255 2256 2257 | means in the case where the first extra line added results in no match and Tcl's regexp system returns the incorrect code and adding a second extra line would actually match, the text widget will return the wrong result. In practice this is a rare problem, but it can occur, for example: .CS pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\encccc\enbbbb\enaaaa\en" | | | | 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 | means in the case where the first extra line added results in no match and Tcl's regexp system returns the incorrect code and adding a second extra line would actually match, the text widget will return the wrong result. In practice this is a rare problem, but it can occur, for example: .CS pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\encccc\enbbbb\enaaaa\en" \&.t search -regexp -- {(a+|b+\enc+\enb+)+\ena+} 1.0 .CE will not find a match when one exists of 19 characters starting from the first .QW b . .PP Whenever one possible match is fully enclosed in another, the search command will attempt to ensure only the larger match is returned. When performing backwards regexp searches it is possible that Tcl will not always achieve this, in the case where a match is preceded by one or more short, non-overlapping matches, all of which are preceded by a large match which actually encompasses all of them. The search algorithm used by the widget does not look back arbitrarily far for a possible match which might cover large portions of the widget. For example: .CS pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\enbbbb\enbbbb\enbbbb\\n" \&.t search -regexp -backward -- {b+\en|a+\en(b+\en)+} end .CE matches at .QW 5.0 when a true greedy match would match at .QW 1.0 . Similarly if we add \fB\-all\fR to this case, it matches at all of .QW 5.0 , |
︙ | ︙ |
Changes to doc/tk.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH tk n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS | | > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | .TH tk n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS \fBtk\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBtk\fR command provides access to miscellaneous elements of Tk's internal state. Most of the information manipulated by this command pertains to the application as a whole, or to a screen or display, rather than to a particular window. The command can take any of a number of different forms depending on the \fIoption\fR argument. The legal forms are: .\" METHOD: appname .TP \fBtk appname \fR?\fInewName\fR? . If \fInewName\fR is not specified, this command returns the name of the application (the name that may be used in \fBsend\fR commands to communicate with the application). If \fInewName\fR is specified, then the name of the application |
︙ | ︙ | |||
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | \fInewName\fR should not start with a capital letter. This will interfere with option processing, since names starting with capitals are assumed to be classes; as a result, Tk may not be able to find some options for the application. If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. .TP \fBtk busy \fIsubcommand\fR ... . This command controls the marking of window hierarchies as .QW busy , rendering them non-interactive while some other operation is proceeding. For more details see the \fBbusy\fR manual page. .TP \fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . Sets and queries the caret location for the display of the specified Tk window \fIwindow\fR. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and \fB\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. .TP \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? . Returns a positive integer, the number of milliseconds since the last time the user interacted with the system. If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. .RS .PP \fBtk inactive\fR will return \-1, if querying the user inactive time is not supported by the system, and in safe interpreters. .PP If the literal string \fBreset\fR is given as an additional argument, the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. .RE .TP \fBtk fontchooser \fIsubcommand\fR ... Controls the Tk font selection dialog. For more details see the \fBfontchooser\fR manual page. .TP \fBtk print \fIwindow\fR . The \fBtk print\fR command posts a dialog that allows users to print output from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using platform-native APIs and dialogs where available. For more details see the \fBprint\fR manual page. .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The \fInumber\fR argument is a floating point number that specifies the number of pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is | > > > > > > > | 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | \fInewName\fR should not start with a capital letter. This will interfere with option processing, since names starting with capitals are assumed to be classes; as a result, Tk may not be able to find some options for the application. If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. .\" METHOD: busy .TP \fBtk busy \fIsubcommand\fR ... . This command controls the marking of window hierarchies as .QW busy , rendering them non-interactive while some other operation is proceeding. For more details see the \fBbusy\fR manual page. .\" METHOD: caret .TP \fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . Sets and queries the caret location for the display of the specified Tk window \fIwindow\fR. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and \fB\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. .\" METHOD: inactive .TP \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? . Returns a positive integer, the number of milliseconds since the last time the user interacted with the system. If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. .RS .PP \fBtk inactive\fR will return \-1, if querying the user inactive time is not supported by the system, and in safe interpreters. .PP If the literal string \fBreset\fR is given as an additional argument, the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. .RE .\" METHOD: fontchooser .TP \fBtk fontchooser \fIsubcommand\fR ... . Controls the Tk font selection dialog. For more details see the \fBfontchooser\fR manual page. .\" METHOD: print .TP \fBtk print \fIwindow\fR . The \fBtk print\fR command posts a dialog that allows users to print output from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using platform-native APIs and dialogs where available. For more details see the \fBprint\fR manual page. .\" METHOD: scaling .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The \fInumber\fR argument is a floating point number that specifies the number of pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is |
︙ | ︙ | |||
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor, but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE .TP \fBtk sysnotify \fP \fItitle\fP? \fImessage\fP? . The \fBtk sysnotify\fP command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. For more details see the \fBsysnotify\fR manual page. .TP \fBtk systray create\fP \fIsubcommand...\fP . The \fBtk systray\fP command creates an icon in the platform-specific tray. For more details see the \fBsystray\fR manual page. .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in some locales (i.e., Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current state is returned. This is turned on by default for the main display. .TP \fBtk windowingsystem\fR . Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (Mac OS X Aqua). .SH "SEE ALSO" busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n) .SH KEYWORDS application name, print, send, sysnotify, systray '\" Local Variables: '\" mode: nroff '\" End: | > > > > | 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 | displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor, but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE .\" METHOD: sysnotify .TP \fBtk sysnotify \fP \fItitle\fP? \fImessage\fP? . The \fBtk sysnotify\fP command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. For more details see the \fBsysnotify\fR manual page. .\" METHOD: systray .TP \fBtk systray create\fP \fIsubcommand...\fP . The \fBtk systray\fP command creates an icon in the platform-specific tray. For more details see the \fBsystray\fR manual page. .\" METHOD: useinputmethods .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in some locales (i.e., Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current state is returned. This is turned on by default for the main display. .\" METHOD: windowingsystem .TP \fBtk windowingsystem\fR . Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (Mac OS X Aqua). .SH "SEE ALSO" busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n) .SH KEYWORDS application name, print, send, sysnotify, systray '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/tk_mac.n.
︙ | ︙ | |||
31 32 33 34 35 36 37 | \fB::tk::mac::standardAboutPanel\fR \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR \fB::tk::mac::CGAntialiasLimit \fIlimit\fR \fB::tk::mac::antialiasedtext \fInumber\fR \fB::tk::mac::useThemedToplevel \fIboolean\fR | < > > > > > | 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | \fB::tk::mac::standardAboutPanel\fR \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR \fB::tk::mac::CGAntialiasLimit \fIlimit\fR \fB::tk::mac::antialiasedtext \fInumber\fR \fB::tk::mac::useThemedToplevel \fIboolean\fR \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR .fi .BE .SH "EVENT HANDLER CALLBACKS" .PP The Aqua/Mac OS X application environment defines a number of additional events that applications should respond to. These events are mapped by Tk to calls to commands in the \fB::tk::mac\fR namespace; unless otherwise noted, if the command is absent, no action will be taken. .\" COMMAND: DoScriptFile .TP \fB::tk::mac::DoScriptFile\fR . The default Apple Event handler for AEDoScriptHandler. This command executes a Tcl file when an AppleScript sends a .QW "do script" command to Wish with a file path as a parameter. .\" COMMAND: DoScriptText .TP \fB::tk::mac::DoScriptText\fR . The default Apple Event handler for AEDoScriptHandler. This command executes Tcl code when an AppleScript sends a .QW "do script" command to Wish with Tcl code or a Tcl procedure as a parameter. .\" COMMAND: ShowPreferences .TP \fB::tk::mac::ShowPreferences\fR . The default Apple Event handler for kAEShowPreferences, .QW pref . The application menu .QW "Preferences" menu item is only enabled when this proc is defined. Typically this command is used to wrap a specific own preferences command, which pops up a preferences window. Something like: .RS .PP .CS proc ::tk::mac::ShowPreferences {} { setPref } .CE .RE .\" COMMAND: OpenApplication .TP \fB::tk::mac::OpenApplication\fR . If a proc of this name is defined, this proc fill fire when your application is initially opened. It is the default Apple Event handler for kAEOpenApplication, .QW oapp . .\" COMMAND: ReopenApplication .TP \fB::tk::mac::ReopenApplication\fR . If a proc of this name is defined it is the default Apple Event handler for kAEReopenApplication, .QW rapp , the Apple Event sent when your application is opened when it is already |
︙ | ︙ | |||
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | } else { wm deiconify . } raise . } .CE .RE .TP \fB::tk::mac::OpenDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEOpenDocuments, .QW odoc , the Apple Event sent when your application is asked to open one or more documents (e.g., by drag & drop onto the app or by opening a document of a type associated to the app). The proc should take as arguments paths to the files to be opened, like so: .RS .PP .CS proc ::tk::mac::OpenDocument {args} { foreach f $args {my_open_document $f} } .CE .RE .TP \fB::tk::mac::PrintDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEPrintDocuments, .QW pdoc , the Apple Event sent when your application is asked to print a document. It takes a single absolute file path as an argument. .TP \fB::tk::mac::Quit\fR . If a proc of this name is defined it is the default Apple Event handler for kAEQuitApplication, .QW quit , the Apple Event sent when your application is asked to be quit, e.g. via the quit menu item in the application menu, the quit menu item in the Dock menu, or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is called instead. .TP \fB::tk::mac::OnHide\fR . If defined, this is called when your application receives a kEventAppHidden event, e.g. via the hide menu item in the application or Dock menus. .TP \fB::tk::mac::OnShow\fR . If defined, this is called when your application receives a kEventAppShown event, e.g. via the show all menu item in the application menu, or by clicking the Dock icon of a hidden application. .TP \fB::tk::mac::ShowHelp\fR . Customizes behavior of Apple Help menu; if this procedure is not defined, the platform-specific standard Help menu item .QW "YourApp Help" performs the default Cocoa action of showing the Help Book configured in the application's Info.plist (or displaying an alert if no Help Book is set). .TP \fB::tk::mac::PerformService\fR . Executes a Tcl procedure called from the macOS .QW Services menu in the Application menu item. The .QW Services | > > > > > > > | 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | } else { wm deiconify . } raise . } .CE .RE .\" COMMAND: OpenDocument .TP \fB::tk::mac::OpenDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEOpenDocuments, .QW odoc , the Apple Event sent when your application is asked to open one or more documents (e.g., by drag & drop onto the app or by opening a document of a type associated to the app). The proc should take as arguments paths to the files to be opened, like so: .RS .PP .CS proc ::tk::mac::OpenDocument {args} { foreach f $args {my_open_document $f} } .CE .RE .\" COMMAND: PrintDocument .TP \fB::tk::mac::PrintDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEPrintDocuments, .QW pdoc , the Apple Event sent when your application is asked to print a document. It takes a single absolute file path as an argument. .\" COMMAND: Quit .TP \fB::tk::mac::Quit\fR . If a proc of this name is defined it is the default Apple Event handler for kAEQuitApplication, .QW quit , the Apple Event sent when your application is asked to be quit, e.g. via the quit menu item in the application menu, the quit menu item in the Dock menu, or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is called instead. .\" COMMAND: OnHide .TP \fB::tk::mac::OnHide\fR . If defined, this is called when your application receives a kEventAppHidden event, e.g. via the hide menu item in the application or Dock menus. .\" COMMAND: OnShow .TP \fB::tk::mac::OnShow\fR . If defined, this is called when your application receives a kEventAppShown event, e.g. via the show all menu item in the application menu, or by clicking the Dock icon of a hidden application. .\" COMMAND: ShowHelp .TP \fB::tk::mac::ShowHelp\fR . Customizes behavior of Apple Help menu; if this procedure is not defined, the platform-specific standard Help menu item .QW "YourApp Help" performs the default Cocoa action of showing the Help Book configured in the application's Info.plist (or displaying an alert if no Help Book is set). .\" COMMAND: PerformService .TP \fB::tk::mac::PerformService\fR . Executes a Tcl procedure called from the macOS .QW Services menu in the Application menu item. The .QW Services |
︙ | ︙ | |||
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 | the application's Info.plist file. The underlying code supporting this command also allows the text, entry and ttk::entry widgets to access services from other applications via the Services menu. The NSPortName key in Wish's Info.plist file is currently set as .QW "Wish" ; if a developer changes the name of the Wish executable to something else, this key should be modified with the same name. .TP \fB::tk::mac::LaunchURL \fIURL...\fR . If defined, launches a URL within Tk. This would be used if a Tk application wants to handle a URL itself, such as displaying data from an RSS feed, rather than launching a default application to handle the URL, although it can defined as such. Wish includes a stub URL scheme of .QW foo:// | > | | | < < > > > > > > | 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | the application's Info.plist file. The underlying code supporting this command also allows the text, entry and ttk::entry widgets to access services from other applications via the Services menu. The NSPortName key in Wish's Info.plist file is currently set as .QW "Wish" ; if a developer changes the name of the Wish executable to something else, this key should be modified with the same name. .\" COMMAND: LaunchURL .TP \fB::tk::mac::LaunchURL \fIURL...\fR . If defined, launches a URL within Tk. This would be used if a Tk application wants to handle a URL itself, such as displaying data from an RSS feed, rather than launching a default application to handle the URL, although it can defined as such. Wish includes a stub URL scheme of .QW foo:// in the CFBundleURLSchemes key of its Info.plist file; this should be customized for the specific URL scheme the developer wants to support. .TP \fB::tk::mac::GetAppPath\fR . Returns the current applications's file path. .PP .SH "ADDITIONAL DIALOGS" .PP The Aqua/Mac OS X defines additional dialogs that applications should support. .\" COMMAND: standardAboutPanel .TP \fB::tk::mac::standardAboutPanel\fR . Brings the standard Cocoa about panel to the front with information filled in from the application bundle files. The panel displays the application icon and the values associated to the info.plist keys named CFBundleName, CFBundleShortVersionString, NSAboutPanelOptionVersion and NSHumanReadableCopyright. If a file named \fICredits.html\fR or \fICredits.rtf\fR exists in the bundle's Resources directory then its contents will be displayed in a scrolling text box at the bottom of the dialog. See the documentation for -[NSApplication orderFrontStandardAboutPanelWithOptions:] for more details. A hook is also provided for a custom About dialog. If a Tcl proc named tkAboutDialog is defined in the main interpreter then that procedure will be called instead of opening the standardAboutPanel. .SH "SYSTEM CONFIGURATION" .PP There are a number of additional global configuration options that control the details of how Tk renders by default. .\" COMMAND: useCompatibilityMetrics .TP \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR . Preserves compatibility with older Tk/Aqua metrics; set to \fBfalse\fR for more native spacing. .\" COMMAND: CGAntialiasLimit .TP \fB::tk::mac::CGAntialiasLimit \fIlimit\fR . Sets the antialiasing limit; lines thinner that \fIlimit\fR pixels will not be antialiased. Integer, set to 0 by default, making all lines be antialiased. .\" COMMAND: antialiasedtext .TP \fB::tk::mac::antialiasedtext \fInumber\fR . Sets anti-aliased text. Controls text antialiasing, possible values for \fInumber\fR are -1 (default, use system default for text AA), 0 (no text AA), 1 (use text AA). .\" COMMAND: useThemedToplevel .TP \fB::tk::mac::useThemedToplevel \fIboolean\fR . Sets toplevel windows to draw with the modern grayish/ pinstripe Mac background. Equivalent to configuring the toplevel with .QW "\fB\-background systemWindowHeaderBackground\fR" , or to using a \fBttk::frame\fR. .SH "SUPPORT COMMANDS" .\" COMMAND: iconBitmap .TP \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR . Renders native icons and bitmaps in Tk applications (including any image file readable by NSImage). A native bitmap name is interpreted as follows (in order): .RS |
︙ | ︙ | |||
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 | .IP \(bu 3 NSImage url string .IP \(bu 3 4-char OSType of IconServices icon .PP The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define the dimensions of the image to create, and \fI\-kind\fR must be one of: .TP \fB\-file\fR . icon of file at given path .TP \fB\-fileType\fR . icon of given file type .TP \fB\-osType\fR . icon of given 4-char OSType file type .TP \fB\-systemType\fR . icon for given IconServices 4-char OSType .TP \fB\-namedImage\fR . named NSImage for given name .TP \fB\-imageFile\fR . image at given path .RE .SH "SEE ALSO" bind(n), wm(n) .SH KEYWORDS about dialog, antialiasing, Apple event, icon, NSImage '\" Local Variables: '\" mode: nroff '\" End: | > > > > > > | 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 | .IP \(bu 3 NSImage url string .IP \(bu 3 4-char OSType of IconServices icon .PP The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define the dimensions of the image to create, and \fI\-kind\fR must be one of: .\" OPTION: -file .TP \fB\-file\fR . icon of file at given path .\" OPTION: -fileType .TP \fB\-fileType\fR . icon of given file type .\" OPTION: -osType .TP \fB\-osType\fR . icon of given 4-char OSType file type .\" OPTION: -systemType .TP \fB\-systemType\fR . icon for given IconServices 4-char OSType .\" OPTION: -namedImage .TP \fB\-namedImage\fR . named NSImage for given name .\" OPTION: -imageFile .TP \fB\-imageFile\fR . image at given path .RE .SH "SEE ALSO" bind(n), wm(n) .SH KEYWORDS about dialog, antialiasing, Apple event, icon, NSImage '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/tkerror.n.
︙ | ︙ | |||
14 15 16 17 18 19 20 | .SH SYNOPSIS \fBtkerror \fImessage\fR .BE .SH DESCRIPTION .PP Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to \fBbgerror\fR because the event loop (which is what usually invokes | > > | | | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | .SH SYNOPSIS \fBtkerror \fImessage\fR .BE .SH DESCRIPTION .PP Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to \fBbgerror\fR because the event loop (which is what usually invokes it) is now part of Tcl. Using the \fBtkerror\fR name is deprecated. .PP For backward compatibility the \fBbgerror\fR provided by the current Tk version still tries to call \fBtkerror\fR if there is one (or an auto loadable one), so old script defining that error handler should still work, but you should anyhow modify your scripts to use \fBbgerror\fR instead of \fBtkerror\fR because that support for the old name might vanish in the future. If that call fails, \fBbgerror\fR posts a dialog showing the error and offering to see the stack trace to the user. If you want your own error management you should directly override \fBbgerror\fR instead of \fBtkerror\fR. Documentation for \fBbgerror\fR is available as part of Tcl's documentation. .SH KEYWORDS background error, reporting |
︙ | ︙ |
Changes to doc/tkvars.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 19 20 21 22 23 24 25 | .SH NAME geometry, tk_library, tk_patchLevel, tk::scalingPct, tk_strictMotif, tk::svgFmt, tk_version \- Variables used or set by Tk .BE .SH DESCRIPTION .PP The following Tcl variables are either set or used by Tk at various times in its execution: .TP 15 \fBtk_library\fR . This variable holds the file name for a directory containing a library of Tcl scripts related to Tk. These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors | > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME geometry, tk_library, tk_patchLevel, tk::scalingPct, tk_strictMotif, tk::svgFmt, tk_version \- Variables used or set by Tk .BE .SH DESCRIPTION .PP The following Tcl variables are either set or used by Tk at various times in its execution: .\" VARIABLE: tk_library .TP 15 \fBtk_library\fR . This variable holds the file name for a directory containing a library of Tcl scripts related to Tk. These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors |
︙ | ︙ | |||
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | compiled-in default location, the location of the Tcl library directory, the location of the binary containing the application, and the current working directory. .PP The variable can be modified by an application to switch to a different library. .RE .TP \fBtk_patchLevel\fR . Contains a dot-separated sequence of decimal integers giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk. .RS .PP This value is normally the same as the result of .QW "\fBpackage require\fR \fBtk\fR" . .RE .TP \fBtk::scalingPct\fR . Tk sets this variable at initialization time to the scaling percentage corresponding to the display's DPI scaling level. This value is at least 100 and is restricted to multiples of 25 (100, 125, 150, 175, 200, 225, ...). The sizes and various attributes of the Tk core and Ttk | > > | 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | compiled-in default location, the location of the Tcl library directory, the location of the binary containing the application, and the current working directory. .PP The variable can be modified by an application to switch to a different library. .RE .\" VARIABLE: tk_patchLevel .TP \fBtk_patchLevel\fR . Contains a dot-separated sequence of decimal integers giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk. .RS .PP This value is normally the same as the result of .QW "\fBpackage require\fR \fBtk\fR" . .RE .\" VARIABLE: scalingPct .TP \fBtk::scalingPct\fR . Tk sets this variable at initialization time to the scaling percentage corresponding to the display's DPI scaling level. This value is at least 100 and is restricted to multiples of 25 (100, 125, 150, 175, 200, 225, ...). The sizes and various attributes of the Tk core and Ttk |
︙ | ︙ | |||
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | 150, or 175 when running GNOME on Xorg or the Cinnamon desktop). On \fBx11\fR the scaling percentage is computed mostly (but not exclusively) from the value of the X resource Xft.dpi, and, as an additional step, Tk synchronizes the scaling factor used to convert between physical units and pixels with the scaling percentage, with the aid of the \fBtk scaling\fR command. .RE .TP \fBtk_strictMotif\fR . This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. Modern applications should not normally set this variable. .TP \fBtk::svgFmt\fR . This variable is set at Tk initialization time to .RS .RS 4 .PP | > > | 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | 150, or 175 when running GNOME on Xorg or the Cinnamon desktop). On \fBx11\fR the scaling percentage is computed mostly (but not exclusively) from the value of the X resource Xft.dpi, and, as an additional step, Tk synchronizes the scaling factor used to convert between physical units and pixels with the scaling percentage, with the aid of the \fBtk scaling\fR command. .RE .\" VARIABLE: tk_strictMotif .TP \fBtk_strictMotif\fR . This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. Modern applications should not normally set this variable. .\" VARIABLE: svgFmt .TP \fBtk::svgFmt\fR . This variable is set at Tk initialization time to .RS .RS 4 .PP |
︙ | ︙ | |||
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | DPI scaling level. .PP Note that any access to this variable is supposed to be strictly read-only! Note also that whenever the scaling factor used to convert between physical units and pixels is changed via \fBtk scaling\fR, the value of the variable \fBtk::svgFmt\fR is automatically updated. .RE .TP \fBtk_version\fR . Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and \fIminor\fR are integers. The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes. .SS "INTERNAL AND DEBUGGING VARIABLES" .PP These variables should not normally be set by user code. .TP \fBtk::Priv\fR . This variable is an array containing several pieces of information that are private to Tk. The elements of \fBtk::Priv\fR are used by Tk library procedures and default bindings. They should not be accessed by any code outside Tk. .TP \fBtk_textRedraw\fR .TP \fBtk_textRelayout\fR . These variables are set by text widgets when they have debugging turned on. The values written to these variables can be used to test or debug text widget operations. These variables are mostly used by Tk's test suite. .SH "OTHER GLOBAL VARIABLES" The following variables are only guaranteed to exist in \fBwish\fR executables; the Tk library does not define them itself but many Tk environments do. .TP \fBgeometry\fR . If set, contains the user-supplied geometry specification to use for the main Tk window. .SH "SEE ALSO" package(n), tclvars(n), wish(1) .SH KEYWORDS environment, text, variables, version '\" Local Variables: '\" mode: nroff '\" End: | > > > > > | 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 | DPI scaling level. .PP Note that any access to this variable is supposed to be strictly read-only! Note also that whenever the scaling factor used to convert between physical units and pixels is changed via \fBtk scaling\fR, the value of the variable \fBtk::svgFmt\fR is automatically updated. .RE .\" VARIABLE: tk_version .TP \fBtk_version\fR . Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and \fIminor\fR are integers. The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes. .SS "INTERNAL AND DEBUGGING VARIABLES" .PP These variables should not normally be set by user code. .\" VARIABLE: Priv .TP \fBtk::Priv\fR . This variable is an array containing several pieces of information that are private to Tk. The elements of \fBtk::Priv\fR are used by Tk library procedures and default bindings. They should not be accessed by any code outside Tk. .\" VARIABLE: tk_textRedraw .\" VARIABLE: tk_textRelayout .TP \fBtk_textRedraw\fR .TP \fBtk_textRelayout\fR . These variables are set by text widgets when they have debugging turned on. The values written to these variables can be used to test or debug text widget operations. These variables are mostly used by Tk's test suite. .SH "OTHER GLOBAL VARIABLES" The following variables are only guaranteed to exist in \fBwish\fR executables; the Tk library does not define them itself but many Tk environments do. .\" VARIABLE: geometry .TP \fBgeometry\fR . If set, contains the user-supplied geometry specification to use for the main Tk window. .SH "SEE ALSO" package(n), tclvars(n), wish(1) .SH KEYWORDS environment, text, variables, version '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/tkwait.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 15 | .TH tkwait n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tkwait \- Wait for variable to change or window to be destroyed .SH SYNOPSIS \fBtkwait variable \fIname\fR | > < < > > > > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | .TH tkwait n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tkwait \- Wait for variable to change or window to be destroyed .SH SYNOPSIS .nf \fBtkwait variable \fIname\fR \fBtkwait visibility \fIname\fR \fBtkwait window \fIname\fR .fi .BE .SH DESCRIPTION .PP The \fBtkwait\fR command waits for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. .\" METHOD: variable If the first argument is \fBvariable\fR (or any abbreviation of it) then the second argument is the name of a global variable and the command waits for that variable to be modified. .\" METHOD: visibility If the first argument is \fBvisibility\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for a change in its visibility state (as indicated by the arrival of a VisibilityNotify event). This form is typically used to wait for a newly-created window to appear on the screen before taking some action. .\" METHOD: window If the first argument is \fBwindow\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for that window to be destroyed. This form is typically used to wait for a user to finish interacting with a dialog box before using the result of that interaction. .PP While the \fBtkwait\fR command is waiting it processes events in |
︙ | ︙ |
Changes to doc/toplevel.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH toplevel n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME toplevel \- Create and manipulate 'toplevel' main and popup window widgets .SH SYNOPSIS | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | .TH toplevel n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME toplevel \- Create and manipulate 'toplevel' main and popup window widgets .SH SYNOPSIS \fBtoplevel\fI pathName \fR?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief \-highlightbackground \-padx \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background |
︙ | ︙ | |||
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 | \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for toplevel widgets: .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified | > > | 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 | \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for toplevel widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified |
︙ | ︙ |
Changes to doc/winfo.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH winfo n 4.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME winfo \- Return window-related information .SH SYNOPSIS | | > > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 | .TH winfo n 4.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME winfo \- Return window-related information .SH SYNOPSIS \fBwinfo\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBwinfo\fR command is used to retrieve information about windows managed by Tk. It can take any of a number of different forms, depending on the \fIoption\fR argument. The legal forms are: .\" METHOD: atom .TP \fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR . Returns a decimal string giving the integer identifier for the atom whose name is \fIname\fR. If no atom exists with the name \fIname\fR then a new one is created. If the \fB\-displayof\fR option is given then the atom is looked up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. .\" METHOD: atomname .TP \fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR . Returns the textual name for the atom whose integer identifier is \fIid\fR. If the \fB\-displayof\fR option is given then the identifier is looked up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. This command is the inverse of the \fBwinfo atom\fR command. It generates an error if no such atom exists. .\" METHOD: cells .TP \fBwinfo cells \fIwindow\fR . Returns a decimal string giving the number of cells in the color map for \fIwindow\fR. .\" METHOD: children .TP \fBwinfo children \fIwindow\fR . Returns a list containing the path names of all the children of \fIwindow\fR. Top-level windows are returned as children of their logical parents. The list is in stacking order, with the lowest window first, except for Top-level windows which are not returned in stacking order. Use the \fBwm stackorder\fR command to query the stacking order of Top-level windows. .\" METHOD: class .TP \fBwinfo class \fIwindow\fR . Returns the class name for \fIwindow\fR. .\" METHOD: colormapfull .TP \fBwinfo colormapfull \fIwindow\fR . Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 otherwise. The colormap for a window is .QW known to be full if the last attempt to allocate a new color on that window failed and this application has not freed any colors in the colormap since the failed allocation. .\" METHOD: containing .TP \fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR . Returns the path name for the window containing the point given by \fIrootX\fR and \fIrootY\fR. \fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. any form acceptable to \fBTk_GetPixels\fR) in the coordinate system of the root window (if a virtual-root window manager is in use then the coordinate system of the virtual root window is used). If the \fB\-displayof\fR option is given then the coordinates refer to the screen containing \fIwindow\fR; otherwise they refer to the screen of the application's main window. If no window in this application contains the point then an empty string is returned. An empty string is also returned if the point lies in the title bar or border of its highest containing toplevel in this application. (Note that with some window managers the borders may be invisible.) In selecting the containing window, children are given higher priority than parents and among siblings the highest one in the stacking order is chosen. .\" METHOD: depth .TP \fBwinfo depth \fIwindow\fR . Returns a decimal string giving the depth of \fIwindow\fR (number of bits per pixel). .\" METHOD: exists .TP \fBwinfo exists \fIwindow\fR . Returns 1 if there exists a window named \fIwindow\fR, 0 if no such window exists. .\" METHOD: fpixels .TP \fBwinfo fpixels \fIwindow number\fR . Returns a floating-point value giving the number of pixels in \fIwindow\fR corresponding to the distance given by \fInumber\fR. \fINumber\fR may be specified in any of the forms acceptable to \fBTk_GetScreenMM\fR, such as .QW 2.0c or .QW 1i . The return value may be fractional; for an integer value, use \fBwinfo pixels\fR. .\" METHOD: geometry .TP \fBwinfo geometry \fIwindow\fR . Returns the geometry for \fIwindow\fR, in the form \fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are in pixels. .\" METHOD: height .TP \fBwinfo height \fIwindow\fR . Returns a decimal string giving \fIwindow\fR's height in pixels. When a window is first created its height will be 1 pixel; the height will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true height immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, or use \fBwinfo reqheight\fR to get the window's requested height instead of its actual height. .\" METHOD: id .TP \fBwinfo id \fIwindow\fR . Returns a hexadecimal string giving a low-level platform-specific identifier for \fIwindow\fR. On Unix platforms, this is the X window identifier. Under Windows, this is the Windows HWND. On the Macintosh the value has no meaning outside Tk. .\" METHOD: interps .TP \fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? . Returns a list whose members are the names of all Tcl interpreters (e.g. all Tk-based applications) currently registered for a particular display. If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. .\" METHOD: ismapped .TP \fBwinfo ismapped \fIwindow\fR . Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. .\" METHOD: manager .TP \fBwinfo manager \fIwindow\fR . Returns the name of the geometry manager currently responsible for \fIwindow\fR, or an empty string if \fIwindow\fR is not managed by any geometry manager. The name is usually the name of the Tcl command for the geometry manager, such as \fBpack\fR or \fBplace\fR. If the geometry manager is a widget, such as canvases or text, the name is the widget's class command, such as \fBcanvas\fR. .\" METHOD: name .TP \fBwinfo name \fIwindow\fR . Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed to its full path name). The command \fBwinfo name .\fR will return the name of the application. .\" METHOD: parent .TP \fBwinfo parent \fIwindow\fR . Returns the path name of \fIwindow\fR's parent, or an empty string if \fIwindow\fR is the main window of the application. .\" METHOD: pathname .TP \fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR . Returns the path name of the window whose X identifier is \fIid\fR. \fIId\fR must be a decimal, hexadecimal, or octal integer and must correspond to a window in the invoking application. If the \fB\-displayof\fR option is given then the identifier is looked up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. .\" METHOD: pixels .TP \fBwinfo pixels \fIwindow number\fR . Returns the number of pixels in \fIwindow\fR corresponding to the distance given by \fInumber\fR. \fINumber\fR may be specified in any of the forms acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i . The result is rounded to the nearest integer value; for a fractional result, use \fBwinfo fpixels\fR. .\" METHOD: pointerx .TP \fBwinfo pointerx \fIwindow\fR . If the mouse pointer is on the same screen as \fIwindow\fR, returns the pointer's x coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. .\" METHOD: pointerxy .TP \fBwinfo pointerxy \fIwindow\fR . If the mouse pointer is on the same screen as \fIwindow\fR, returns a list with two elements, which are the pointer's x and y coordinates measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then both of the returned coordinates are \-1. .\" METHOD: pointery .TP \fBwinfo pointery \fIwindow\fR . If the mouse pointer is on the same screen as \fIwindow\fR, returns the pointer's y coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. .\" METHOD: reqheight .TP \fBwinfo reqheight \fIwindow\fR . Returns a decimal string giving \fIwindow\fR's requested height, in pixels. This is the value used by \fIwindow\fR's geometry manager to compute its geometry. .\" METHOD: reqwidth .TP \fBwinfo reqwidth \fIwindow\fR . Returns a decimal string giving \fIwindow\fR's requested width, in pixels. This is the value used by \fIwindow\fR's geometry manager to compute its geometry. .\" METHOD: rgb .TP \fBwinfo rgb \fIwindow color\fR . Returns a list containing three decimal values in the range 0 to 65535, which are the red, green, and blue intensities that correspond to \fIcolor\fR in the window given by \fIwindow\fR. \fIColor\fR may be specified in any of the forms acceptable for a color option. .\" METHOD: rootx .TP \fBwinfo rootx \fIwindow\fR . Returns a decimal string giving the x-coordinate, in the root window of the screen, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). .\" METHOD: rooty .TP \fBwinfo rooty \fIwindow\fR . Returns a decimal string giving the y-coordinate, in the root window of the screen, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). .\" METHOD: screen .TP \fBwinfo screen \fIwindow\fR . Returns the name of the screen associated with \fIwindow\fR, in the form \fIdisplayName\fR.\fIscreenIndex\fR. .\" METHOD: screencells .TP \fBwinfo screencells \fIwindow\fR . Returns a decimal string giving the number of cells in the default color map for \fIwindow\fR's screen. .\" METHOD: screendepth .TP \fBwinfo screendepth \fIwindow\fR . Returns a decimal string giving the depth of the root window of \fIwindow\fR's screen (number of bits per pixel). .\" METHOD: screenheight .TP \fBwinfo screenheight \fIwindow\fR . Returns a decimal string giving the height of \fIwindow\fR's screen, in pixels. .\" METHOD: screenmmheight .TP \fBwinfo screenmmheight \fIwindow\fR . Returns a decimal string giving the height of \fIwindow\fR's screen, in millimeters. .\" METHOD: screenmmwidth .TP \fBwinfo screenmmwidth \fIwindow\fR . Returns a decimal string giving the width of \fIwindow\fR's screen, in millimeters. .\" METHOD: screenvisual .TP \fBwinfo screenvisual \fIwindow\fR . Returns one of the following strings to indicate the default visual class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or \fBtruecolor\fR. .\" METHOD: screenwidth .TP \fBwinfo screenwidth \fIwindow\fR . Returns a decimal string giving the width of \fIwindow\fR's screen, in pixels. .\" METHOD: server .TP \fBwinfo server \fIwindow\fR . Returns a string containing information about the server for \fIwindow\fR's display. The exact format of this string may vary from platform to platform. For X servers the string has the form .QW "\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR" where \fImajor\fR and \fIminor\fR are the version and revision numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR is the name of the vendor for the server, and \fIvendorRelease\fR is an integer release number provided by the server. .\" METHOD: toplevel .TP \fBwinfo toplevel \fIwindow\fR . Returns the path name of the top-of-hierarchy window containing \fIwindow\fR. In standard Tk this will always be a \fBtoplevel\fR widget, but extensions may create other kinds of top-of-hierarchy widgets. .\" METHOD: viewable .TP \fBwinfo viewable \fIwindow\fR . Returns 1 if \fIwindow\fR and all of its ancestors up through the nearest toplevel window are mapped. Returns 0 if any of these windows are not mapped. .\" METHOD: visual .TP \fBwinfo visual \fIwindow\fR . Returns one of the following strings to indicate the visual class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or \fBtruecolor\fR. .\" METHOD: visualid .TP \fBwinfo visualid \fIwindow\fR . Returns the X identifier for the visual for \fIwindow\fR. .\" METHOD: visualsavailable .TP \fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? . Returns a list whose elements describe the visuals available for \fIwindow\fR's screen. Each element consists of a visual class followed by an integer depth. The class has the same form as returned by \fBwinfo visual\fR. The depth gives the number of bits per pixel in the visual. In addition, if the \fBincludeids\fR argument is provided, then the depth is followed by the X identifier for the visual. .\" METHOD: vrootheight .TP \fBwinfo vrootheight \fIwindow\fR . Returns the height of the virtual root window associated with \fIwindow\fR if there is one; otherwise returns the height of \fIwindow\fR's screen. .\" METHOD: vrootwidth .TP \fBwinfo vrootwidth \fIwindow\fR . Returns the width of the virtual root window associated with \fIwindow\fR if there is one; otherwise returns the width of \fIwindow\fR's screen. .\" METHOD: vrootx .TP \fBwinfo vrootx \fIwindow\fR . Returns the x-offset of the virtual root window associated with \fIwindow\fR, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for \fIwindow\fR. .\" METHOD: vrooty .TP \fBwinfo vrooty \fIwindow\fR . Returns the y-offset of the virtual root window associated with \fIwindow\fR, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for \fIwindow\fR. .\" METHOD: width .TP \fBwinfo width \fIwindow\fR . Returns a decimal string giving \fIwindow\fR's width in pixels. When a window is first created its width will be 1 pixel; the width will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true width immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, or use \fBwinfo reqwidth\fR to get the window's requested width instead of its actual width. .\" METHOD: x .TP \fBwinfo x \fIwindow\fR . Returns a decimal string giving the x-coordinate, in \fIwindow\fR's parent, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). .\" METHOD: y .TP \fBwinfo y \fIwindow\fR . Returns a decimal string giving the y-coordinate, in \fIwindow\fR's parent, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). .SH EXAMPLE .PP Print where the mouse pointer is and what window it is currently over: .CS lassign [\fBwinfo pointerxy\fR .] x y puts -nonewline "Mouse pointer at ($x,$y) which is " set win [\fBwinfo containing\fR $x $y] if {$win eq ""} { puts "over no window" } else { puts "over $win" } .CE .SH KEYWORDS atom, children, class, geometry, height, identifier, information, interpreters, mapped, parent, path name, screen, virtual root, width, window '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/wish.1.
︙ | ︙ | |||
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME wish \- Simple windowing shell .SH SYNOPSIS \fBwish\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg ...\fR? .SH OPTIONS .IP "\fB\-encoding \fIname\fR" 20 Specifies the encoding of the text stored in \fIfileName\fR. This option is only recognized prior to the \fIfileName\fR argument. .IP "\fB\-colormap \fInew\fR" 20 Specifies that the window should have a new private colormap instead of using the default colormap for the screen. .IP "\fB\-display \fIdisplay\fR" 20 Display (and screen) on which to display window. .IP "\fB\-geometry \fIgeometry\fR" 20 Initial geometry to use for window. If this option is specified, its value is stored in the \fBgeometry\fR global variable of the application's Tcl interpreter. .IP "\fB\-name \fIname\fR" 20 Use \fIname\fR as the title to be displayed in the window, and as the name of the interpreter for \fBsend\fR commands. .IP "\fB\-sync\fR" 20 Execute all X server commands synchronously, so that errors are reported immediately. This will result in much slower execution, but it is useful for debugging. .IP "\fB\-use\fR \fIid\fR" 20 Specifies that the main window for the application is to be embedded in the window whose identifier is \fIid\fR, instead of being created as an independent toplevel window. \fIId\fR must be specified in the same way as the value for the \fB\-use\fR option for toplevel widgets (i.e. it has a form like that returned by the \fBwinfo id\fR command). .RS Note that on some platforms this will only work correctly if \fIid\fR refers to a Tk \fBframe\fR or \fBtoplevel\fR that has its \fB\-container\fR option enabled. .RE .IP "\fB\-visual \fIvisual\fR" 20 Specifies the visual to use for the window. \fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR procedure. .IP "\fB\-\|\-\fR" 20 Pass all remaining arguments through to the script's \fBargv\fR variable without interpreting them. This provides a mechanism for passing arguments such as \fB\-name\fR to a script instead of having \fBwish\fR interpret them. .BE .SH DESCRIPTION | > > > > > > > > > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME wish \- Simple windowing shell .SH SYNOPSIS \fBwish\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg ...\fR? .SH OPTIONS .\" OPTION: -encoding .IP "\fB\-encoding \fIname\fR" 20 Specifies the encoding of the text stored in \fIfileName\fR. This option is only recognized prior to the \fIfileName\fR argument. .\" OPTION: -colormap .IP "\fB\-colormap \fInew\fR" 20 Specifies that the window should have a new private colormap instead of using the default colormap for the screen. .\" OPTION: -display .IP "\fB\-display \fIdisplay\fR" 20 Display (and screen) on which to display window. .\" OPTION: -geometry .IP "\fB\-geometry \fIgeometry\fR" 20 Initial geometry to use for window. If this option is specified, its value is stored in the \fBgeometry\fR global variable of the application's Tcl interpreter. .\" OPTION: -name .IP "\fB\-name \fIname\fR" 20 Use \fIname\fR as the title to be displayed in the window, and as the name of the interpreter for \fBsend\fR commands. .\" OPTION: -sync .IP "\fB\-sync\fR" 20 Execute all X server commands synchronously, so that errors are reported immediately. This will result in much slower execution, but it is useful for debugging. .\" OPTION: -use .IP "\fB\-use\fR \fIid\fR" 20 Specifies that the main window for the application is to be embedded in the window whose identifier is \fIid\fR, instead of being created as an independent toplevel window. \fIId\fR must be specified in the same way as the value for the \fB\-use\fR option for toplevel widgets (i.e. it has a form like that returned by the \fBwinfo id\fR command). .RS Note that on some platforms this will only work correctly if \fIid\fR refers to a Tk \fBframe\fR or \fBtoplevel\fR that has its \fB\-container\fR option enabled. .RE .\" OPTION: -visual .IP "\fB\-visual \fIvisual\fR" 20 Specifies the visual to use for the window. \fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR procedure. .\" OPTION: -- .IP "\fB\-\|\-\fR" 20 Pass all remaining arguments through to the script's \fBargv\fR variable without interpreting them. This provides a mechanism for passing arguments such as \fB\-name\fR to a script instead of having \fBwish\fR interpret them. .BE .SH DESCRIPTION |
︙ | ︙ | |||
113 114 115 116 117 118 119 | .PP The class of the application, which is used for purposes such as specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults file, is the same as its name except that the first letter is capitalized. .SH "VARIABLES" .PP | | > > > > > > > > > > | 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | .PP The class of the application, which is used for purposes such as specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults file, is the same as its name except that the first letter is capitalized. .SH "VARIABLES" .PP \fBWish\fR sets the following global Tcl variables: .\" VARIABLE: argc .TP 15 \fBargc\fR . Contains a count of the number of \fIarg\fR arguments (0 if none), not including the options described above. .\" VARIABLE: argv .TP 15 \fBargv\fR . Contains a Tcl list whose elements are the \fIarg\fR arguments that follow a \fB\-\|\-\fR option or do not match any of the options described in \fBOPTIONS\fR above, in order, or an empty string if there are no such arguments. .\" VARIABLE: argv0 .TP 15 \fBargv0\fR . Contains \fIfileName\fR if it was specified. Otherwise, contains the name by which \fBwish\fR was invoked. .\" VARIABLE: geometry .TP 15 \fBgeometry\fR . If the \fB\-geometry\fR option is specified, \fBwish\fR copies its value into this variable. If the variable still exists after \fIfileName\fR has been evaluated, \fBwish\fR uses the value of the variable in a \fBwm geometry\fR command to set the main window's geometry. .\" VARIABLE: tcl_interactive .TP 15 \fBtcl_interactive\fR . Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR was not specified and standard input is a terminal-like device), 0 otherwise. .SH "SCRIPT FILES" .PP If you create a Tcl script in a file whose first line is .CS |
︙ | ︙ |
Changes to doc/wm.n.
︙ | ︙ | |||
8 9 10 11 12 13 14 | .TH wm n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME wm \- Communicate with window manager .SH SYNOPSIS | | > > > > > > > > > > > > > > > > > > > < | < < | < < | < < | < < | < < | < < | < < | < < | < < | < < | < < | < < | < < | < > > > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | .TH wm n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME wm \- Communicate with window manager .SH SYNOPSIS \fBwm\fI option window \fR?\fIargs\fR? .BE .SH DESCRIPTION .PP The \fBwm\fR command is used to interact with window managers in order to control such things as the title for a window, its geometry, or the increments in terms of which it may be resized. The \fBwm\fR command can take any of a number of different forms, depending on the \fIoption\fR argument. All of the forms expect at least one additional argument, \fIwindow\fR, which must be the path name of a top-level window. .PP The legal forms for the \fBwm\fR command are: .\" METHOD: aspect .TP \fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? . If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR are all specified, then they will be passed to the window manager and the window manager should use them to enforce a range of acceptable aspect ratios for \fIwindow\fR. The aspect ratio of \fIwindow\fR (width/length) will be constrained to lie between \fIminNumer\fR/\fIminDenom\fR and \fImaxNumer\fR/\fImaxDenom\fR. If \fIminNumer\fR etc. are all specified as empty strings, then any existing aspect ratio restrictions are removed. If \fIminNumer\fR etc. are specified, then the command returns an empty string. Otherwise, it returns a Tcl list containing four elements, which are the current values of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR (if no aspect restrictions are in effect, then an empty string is returned). .\" METHOD: attributes .TP \fBwm attributes \fIwindow\fR .TP \fBwm attributes \fIwindow\fR ?\fBoption\fR? .TP \fBwm attributes \fIwindow\fR ?\fBoption value option value...\fR? . This subcommand returns or sets platform specific attributes associated with a window. The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows: .RS .PP All platforms support the following attributes (though X11 users should see the notes below): .\" OPTION: -alpha .TP \fB\-alpha\fR . Specifies the alpha transparency level of the toplevel. It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values outside that range will be constrained. Where not supported, the \fB\-alpha\fR value remains at \fB1.0\fR. .\" OPTION: -fullscreen .TP \fB\-fullscreen\fR . Places the window in a mode that takes up the entire screen, has no borders, and covers the general use area (i.e. Start menu and taskbar on Windows, dock and menubar on OSX, general window decorations on X11). .\" OPTION: -topmost .TP \fB\-topmost\fR . Specifies whether this is a topmost window (displays above all other windows). .PP On Windows, the following attributes may be set. .\" OPTION: -disabled .TP \fB\-disabled\fR . Specifies whether the window is in a disabled state. .\" OPTION: -toolwindow .TP \fB\-toolwindow\fR . Specifies a toolwindow style window (as defined in the MSDN). .\" OPTION: -transparentcolor .TP \fB\-transparentcolor\fR . Specifies the transparent color index of the toplevel. It takes any color value accepted by \fBTk_GetColor\fR. If the empty string is specified (default), no transparent color is used. This is supported on Windows 2000/XP+. Where not supported, the \fB\-transparentcolor\fR value remains at \fB{}\fR. .PP On MacOS, the following attributes may be set. .\" OPTION: -appearance .TP \fB\-appearance\fR . Specifies whether the window is rendered in "dark mode". Allowed values are \fBauto\fR, \fBaqua\fR and \fBdarkaqua\fR. If the setting is auto then the appearance of the window is controlled by the System Settings. .\" OPTION: -class .TP \fB\-class\fR . Specifies whether the underlying Aqua window for a toplevel is an object of the NSWindow class or the NSPanel class. The two allowed values for this option are \fBnswindow\fR and \fBnspanel\fR. It is not possible to change the class of the underlying Aqua window once that window has been instantiated, and attempting to do that is an error. However it is allowed to set this option for a pathname that does not correspond to an existing window. Doing that causes the class name to be cached for later use. When a toplevel with that pathname is eventually created, the cached class name will determine which class is used for the underlying Aqua window. .\" OPTION: -isdark .TP \fB\-isdark\fR . Returns a boolean value which is true if the window is currently in dark mode. .\" OPTION: -modified .TP \fB\-modified\fR . Specifies the modification state of the window (determines whether the window close widget contains the modification indicator and whether the proxy icon is draggable). .\" OPTION: -notify .TP \fB\-notify\fR . Specifies process notification state (bouncing of the application dock icon). .\" OPTION: -stylemask .TP \fB\-stylemask\fR . Specifies an integer to be assigned as the styleMask of the underlying Aqua window. (See the Apple documentation for styleMask property of the NSWindow class.) The value of this option should be a list of bitnames. Each bit named in the list will be set to 1, and all other bits will be set to 0. The allowed bitnames are: \fBtitled\fR, \fBclosable\fR, \fBminiaturizable\fR, \fBresizable\fR, \fBfullsizecontentview\fR, \fBdocmodal\fR, \fButility\fR, \fBnonactivatingpanel\fR, and \fBHUDwindow\fR. Note that a side effect of setting the fullsizecontentview bit is that the window title bar becomes transparent. .\" OPTION: -tabbingid .TP \fB\-tabbingid\fR . Controls how tabbed toplevel windows are grouped together. Two tabs in the same group must correspond to toplevels with the same tabbingid, which can be an arbitrary UTF8 string. In the Tk implementation, changing the tabbingid of a toplevel in a tab group will cause it to be moved into a different group, in which all tabs have the new tabbingid or, if the new tabbingid is unique, to become a normal non-tabbed toplevel. It is allowed to set the tabbingid before the toplevel is created. If the pathname provided in the command does not correspond to a toplevel, the value will be cached and used later when the toplevel is actually created. .\" OPTION: -tabbingmode .TP \fB\-tabbingmode\fR . Controls whether a toplevel can be opened as a tab within a tab group. The allowed values are \fBauto\fR, \fBpreferred\fR or \fBdisallowed\fR. A toplevel can be opened as a tab in exactly two situations: if its tabbingmode is \fBpreferred\fR; or if its tabbingmode is \fBauto\fR and the user has selected "prefer tabs when opening documents" in the Desktop and Dock panel of the System Settings application. It is allowed to set the tabbingmode before the toplevel is created. If the pathname provided in the command does not correspond to a toplevel, the value will be cached and used later when the toplevel is actually created. .\" OPTION: -titlepath .TP \fB\-titlepath\fR . Specifies the path of the file referenced as the window proxy icon (which can be dragged and dropped in lieu of the file's finder icon). .\" OPTION: -transparent .TP \fB\-transparent\fR . Makes the window content area transparent and turns off the window shadow. For the transparency to be effective, the toplevel background needs to be set to a color with some alpha, e.g. .QW systemTransparent . .PP On X11, the following attributes may be set. These are not supported by all window managers, and will have no effect under older WMs. .\" See https://www.freedesktop.org/wiki/Specifications/wm-spec/ .\" OPTION: -type .TP \fB\-type\fR .VS 8.6 Requests that the window should be interpreted by the window manager as being of the specified type(s). This may cause the window to be decorated in a different way or otherwise managed differently, though exactly what happens is entirely up to the window manager. A list of types may be used, in order of preference. The following values are mapped to constants defined in the EWMH specification (using others is possible, but not advised): .RS .IP \fBdesktop\fR indicates a desktop feature, .IP \fBdock\fR indicates a dock/panel feature, .IP \fBtoolbar\fR indicates a toolbar window that should be acting on behalf of another window, as indicated with \fBwm transient\fR, .IP \fBmenu\fR indicates a torn-off menu that should be acting on behalf of another window, as indicated with \fBwm transient\fR, .IP \fButility\fR indicates a utility window (e.g., palette or toolbox) that should be acting on behalf of another window, as indicated with \fBwm transient\fR, .IP \fBsplash\fR indicates a splash screen, displayed during application start up, .IP \fBdialog\fR indicates a general dialog window, that should be acting on behalf of another window, as indicated with \fBwm transient\fR, .IP \fBdropdown_menu\fR indicates a menu summoned from a menu bar, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBpopup_menu\fR indicates a popup menu, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBtooltip\fR indicates a tooltip window, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBnotification\fR indicates a window that provides a background notification of some event, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBcombo\fR indicates the drop-down list of a combobox widget, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBdnd\fR indicates a window that represents something being dragged, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), .IP \fBnormal\fR indicates a window that has no special interpretation. .RE .VE 8.6 .\" OPTION: -zoomed .TP \fB\-zoomed\fR . Requests that the window should be maximized. This is the same as \fBwm state zoomed\fR on Windows and Mac OS X. .PP On X11, changes to window attributes are performed asynchronously. Querying the value of an attribute returns the current state, which will not be the same as the value most recently set if the window manager has not yet processed the request or if it does not support the attribute. .RE .\" METHOD: client .TP \fBwm client \fIwindow\fR ?\fIname\fR? . If \fIname\fR is specified, this command stores \fIname\fR (which should be the name of the host on which the application is executing) in \fIwindow\fR's \fBWM_CLIENT_MACHINE\fR property for use by the window manager or session manager. The command returns an empty string in this case. If \fIname\fR is not specified, the command returns the last name set in a \fBwm client\fR command for \fIwindow\fR. If \fIname\fR is specified as an empty string, the command deletes the \fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. .\" METHOD: colormapwindows .TP \fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? . This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR property, which provides information to the window managers about windows that have private colormaps. .RS |
︙ | ︙ | |||
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 | If \fBwm colormapwindows\fR is not invoked, Tk will automatically set the property for each top-level window to all the internal windows whose colormaps differ from their parents, followed by the top-level itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the \fBWM_COLORMAP_WINDOWS\fR property. .RE .TP \fBwm command \fIwindow\fR ?\fIvalue\fR? . If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's \fBWM_COMMAND\fR property for use by the window manager or session manager and returns an empty string. \fIValue\fR must have proper list structure; the elements should contain the words of the command used to invoke the application. If \fIvalue\fR is not specified then the command returns the last value set in a \fBwm command\fR command for \fIwindow\fR. If \fIvalue\fR is specified as an empty string, the command deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. .TP \fBwm deiconify \fIwindow\fR . Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. This is done by mapping the window. If the window has never been mapped then this command will not map the window, but it will ensure that when the window is first mapped it will be displayed in de-iconified form. On Windows, a deiconified window will also be raised and be given the focus (made the active window). Returns an empty string. .TP \fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? . If \fBactive\fR or \fBpassive\fR is supplied as an optional argument to the command, then it specifies the focus model for \fIwindow\fR. In this case the command returns an empty string. If no additional argument is supplied, then the command returns the current focus model for \fIwindow\fR. .RS .PP An \fBactive\fR focus model means that \fIwindow\fR will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. \fBPassive\fR means that \fIwindow\fR will never claim the focus for itself: the window manager should give the focus to \fIwindow\fR at appropriate times. However, once the focus has been given to \fIwindow\fR or one of its descendants, the application may re-assign the focus among \fIwindow\fR's descendants. The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command assumes a passive model of focusing. .RE .TP \fBwm forget \fIwindow\fR . The \fIwindow\fR will be unmapped from the screen and will no longer be managed by \fBwm\fR. Windows created with the \fBtoplevel\fR command will be treated like \fBframe\fR windows once they are no longer managed by \fBwm\fR, however, the \fB\-menu\fR configuration will be remembered and the menus will return once the widget is managed again. .TP \fBwm frame \fIwindow\fR . If \fIwindow\fR has been reparented by the window manager into a decorative frame, the command returns the platform specific window identifier for the outermost frame that contains \fIwindow\fR (the window whose parent is the root or virtual root). If \fIwindow\fR has not been reparented by the window manager then the command returns the platform specific window identifier for \fIwindow\fR. .TP \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? . If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR is changed and an empty string is returned. Otherwise the current geometry for \fIwindow\fR is returned (this is the most recent geometry specified either by manual resizing or | > > > > > > | 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 | If \fBwm colormapwindows\fR is not invoked, Tk will automatically set the property for each top-level window to all the internal windows whose colormaps differ from their parents, followed by the top-level itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the \fBWM_COLORMAP_WINDOWS\fR property. .RE .\" METHOD: command .TP \fBwm command \fIwindow\fR ?\fIvalue\fR? . If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's \fBWM_COMMAND\fR property for use by the window manager or session manager and returns an empty string. \fIValue\fR must have proper list structure; the elements should contain the words of the command used to invoke the application. If \fIvalue\fR is not specified then the command returns the last value set in a \fBwm command\fR command for \fIwindow\fR. If \fIvalue\fR is specified as an empty string, the command deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. .\" METHOD: deiconify .TP \fBwm deiconify \fIwindow\fR . Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. This is done by mapping the window. If the window has never been mapped then this command will not map the window, but it will ensure that when the window is first mapped it will be displayed in de-iconified form. On Windows, a deiconified window will also be raised and be given the focus (made the active window). Returns an empty string. .\" METHOD: focusmodel .TP \fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? . If \fBactive\fR or \fBpassive\fR is supplied as an optional argument to the command, then it specifies the focus model for \fIwindow\fR. In this case the command returns an empty string. If no additional argument is supplied, then the command returns the current focus model for \fIwindow\fR. .RS .PP An \fBactive\fR focus model means that \fIwindow\fR will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. \fBPassive\fR means that \fIwindow\fR will never claim the focus for itself: the window manager should give the focus to \fIwindow\fR at appropriate times. However, once the focus has been given to \fIwindow\fR or one of its descendants, the application may re-assign the focus among \fIwindow\fR's descendants. The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command assumes a passive model of focusing. .RE .\" METHOD: forget .TP \fBwm forget \fIwindow\fR . The \fIwindow\fR will be unmapped from the screen and will no longer be managed by \fBwm\fR. Windows created with the \fBtoplevel\fR command will be treated like \fBframe\fR windows once they are no longer managed by \fBwm\fR, however, the \fB\-menu\fR configuration will be remembered and the menus will return once the widget is managed again. .\" METHOD: frame .TP \fBwm frame \fIwindow\fR . If \fIwindow\fR has been reparented by the window manager into a decorative frame, the command returns the platform specific window identifier for the outermost frame that contains \fIwindow\fR (the window whose parent is the root or virtual root). If \fIwindow\fR has not been reparented by the window manager then the command returns the platform specific window identifier for \fIwindow\fR. .\" METHOD: geometry .TP \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? . If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR is changed and an empty string is returned. Otherwise the current geometry for \fIwindow\fR is returned (this is the most recent geometry specified either by manual resizing or |
︙ | ︙ | |||
419 420 421 422 423 424 425 426 427 428 429 430 431 432 | actual size and location of \fIwindow\fR, whereas \fBwm geometry\fR allows both setting and querying of the \fIwindow manager\fR's understanding of the size and location of the window. This can vary significantly, for example to reflect the addition of decorative elements to \fIwindow\fR such as title bars, and window managers are not required to precisely follow the requests made through this command. .RE .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? . This command indicates that \fIwindow\fR is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. \fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid | > | 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 | actual size and location of \fIwindow\fR, whereas \fBwm geometry\fR allows both setting and querying of the \fIwindow manager\fR's understanding of the size and location of the window. This can vary significantly, for example to reflect the addition of decorative elements to \fIwindow\fR such as title bars, and window managers are not required to precisely follow the requests made through this command. .RE .\" METHOD: grid .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? . This command indicates that \fIwindow\fR is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. \fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid |
︙ | ︙ | |||
451 452 453 454 455 456 457 | .PP Otherwise the return value is a Tcl list containing four elements corresponding to the current \fIbaseWidth\fR, \fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if \fIwindow\fR is not currently gridded, then an empty string is returned. .PP | | > > | | | | | > | 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 | .PP Otherwise the return value is a Tcl list containing four elements corresponding to the current \fIbaseWidth\fR, \fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if \fIwindow\fR is not currently gridded, then an empty string is returned. .PP Note that this command should not be needed very often, since the \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option provide easier access to the same functionality. .RE .\" METHOD: group .TP \fBwm group \fIwindow\fR ?\fIpathName\fR? . If \fIpathName\fR is specified, it gives the path name for the leader of a group of related windows. The window manager may use this information, for example, to unmap all of the windows in a group when the group's leader is iconified. \fIPathName\fR may be specified as an empty string to remove \fIwindow\fR from any group association. If \fIpathName\fR is specified then the command returns an empty string; otherwise it returns the path name of \fIwindow\fR's current group leader, or an empty string if \fIwindow\fR is not part of any group. .\" METHOD: iconbadge .TP \fBwm iconbadge \fIwindow badge\fR . Sets a badge for the icon of the \fIwindow\fR. The badge can be a positive integer number, for instance the number of new or unread messages, or an exclamation point denoting attention needed. If the badge is an empty string, the badge image is removed from the application icon. Managing these changes through bindings, such as <FocusIn>, is the responsibility of the developer. .RS .PP On X11, for this command to work, the variable \fB::tk::icons::base_icon($window)\fR must be set to the image that is being used for the window icon of $window. On Windows and X11, the iconphoto images work best at 32x32 or a similar dimension, as the badge images are provided by Tk and drawn to overlay the icon images using native (Windows) API's or Tk rendering. On macOS, the icon badge is rendered by a system API and is not provided by Tk. The icon image itself should be higher-resolution, preferably 512 pixels, to avoid being blurry. .PP The icon badge is intended for display in the Dock (macOS), taskbar (Windows) or app panel (X11). On macOS, the last badge called will be displayed in the Dock, regardless of how many different icon badges may be assigned to different windows. On Windows, the taskbar display depends on whether the taskbar buttons are combined or not (this is an OS setting available to the user): if combined, the behavior is the same as on macOS, otherwise each button in the taskbar shows the badge it was assigned. Badge display on macOS is configured in the system preferences. App panel display behavior on X11 will depend on the window manager and/or desktop environment. .RE .\" METHOD: iconbitmap .TP \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? . If \fIbitmap\fR is specified, then it names a bitmap in the standard forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). This bitmap is passed to the window manager to be displayed in \fIwindow\fR's icon, and the command returns an empty string. If |
︙ | ︙ | |||
526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 | any file which contains a valid Windows icon is also accepted (usually .ico or .icr files), or any file for which the shell has assigned an icon. Tcl will first test if the file contains an icon, then if it has an assigned icon, and finally, if that fails, test for a bitmap. .RE .TP \fBwm iconify \fIwindow\fR . Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped. .TP \fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? . If \fIbitmap\fR is specified, then it names a bitmap in the standard forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). This bitmap is passed to the window manager to be used as a mask in conjunction with the \fBiconbitmap\fR option: where the mask has zeroes no icon will be displayed; where it has ones, the bits from the icon bitmap will be displayed. If an empty string is specified for \fIbitmap\fR then any current icon mask is cancelled for \fIwindow\fR (this is equivalent to specifying a bitmap of all ones). If \fIbitmap\fR is specified then the command returns an empty string. Otherwise it returns the name of the current icon mask associated with \fIwindow\fR, or an empty string if no mask is in effect. .TP \fBwm iconname \fIwindow\fR ?\fInewName\fR? . If \fInewName\fR is specified, then it is passed to the window manager; the window manager should display \fInewName\fR inside the icon associated with \fIwindow\fR. In this case an empty string is returned as result. If \fInewName\fR is not specified then the command returns the current icon name for \fIwindow\fR, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the \fBwm title\fR command). .TP \fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR? . Sets the titlebar icon for \fIwindow\fR based on the named photo images. If \fB\-default\fR is specified, this is applied to all future created toplevels as well. The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not | > > > > | 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 | any file which contains a valid Windows icon is also accepted (usually .ico or .icr files), or any file for which the shell has assigned an icon. Tcl will first test if the file contains an icon, then if it has an assigned icon, and finally, if that fails, test for a bitmap. .RE .\" METHOD: iconify .TP \fBwm iconify \fIwindow\fR . Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped. .\" METHOD: iconmask .TP \fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? . If \fIbitmap\fR is specified, then it names a bitmap in the standard forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). This bitmap is passed to the window manager to be used as a mask in conjunction with the \fBiconbitmap\fR option: where the mask has zeroes no icon will be displayed; where it has ones, the bits from the icon bitmap will be displayed. If an empty string is specified for \fIbitmap\fR then any current icon mask is cancelled for \fIwindow\fR (this is equivalent to specifying a bitmap of all ones). If \fIbitmap\fR is specified then the command returns an empty string. Otherwise it returns the name of the current icon mask associated with \fIwindow\fR, or an empty string if no mask is in effect. .\" METHOD: iconname .TP \fBwm iconname \fIwindow\fR ?\fInewName\fR? . If \fInewName\fR is specified, then it is passed to the window manager; the window manager should display \fInewName\fR inside the icon associated with \fIwindow\fR. In this case an empty string is returned as result. If \fInewName\fR is not specified then the command returns the current icon name for \fIwindow\fR, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the \fBwm title\fR command). .\" METHOD: iconphoto .TP \fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR? . Sets the titlebar icon for \fIwindow\fR based on the named photo images. If \fB\-default\fR is specified, this is applied to all future created toplevels as well. The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not |
︙ | ︙ | |||
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 | format, and becomes the application icon in dialogs, the Dock, and other contexts. At the script level the command will accept only the first image passed in the parameters as support for multiple sizes/resolutions on macOS is outside Tk's scope. Developers should use the largest icon they can support (preferably 512 pixels) to ensure smooth rendering on the Mac. .RE .TP \fBwm iconposition \fIwindow\fR ?\fIx y\fR? . If \fIx\fR and \fIy\fR are specified, they are passed to the window manager as a hint about where to position the icon for \fIwindow\fR. In this case an empty string is returned. If \fIx\fR and \fIy\fR are specified as empty strings then any existing icon position hint is cancelled. If neither \fIx\fR nor \fIy\fR is specified, then the command returns a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned). .TP \fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? . If \fIpathName\fR is specified, it is the path name for a window to use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then \fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR is de-iconified then \fIpathName\fR will be unmapped again. If \fIpathName\fR is specified as an empty string then any existing icon window association for \fIwindow\fR will be cancelled. If the \fIpathName\fR argument is specified then an empty string is returned. Otherwise the command returns the path name of the current icon window for \fIwindow\fR, or an empty string if there is no icon window currently specified for \fIwindow\fR. Button press events are disabled for \fIwindow\fR as long as it is an icon window; this is needed in order to allow window managers to .QW own those events. | > > | > > > > > > | 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 | format, and becomes the application icon in dialogs, the Dock, and other contexts. At the script level the command will accept only the first image passed in the parameters as support for multiple sizes/resolutions on macOS is outside Tk's scope. Developers should use the largest icon they can support (preferably 512 pixels) to ensure smooth rendering on the Mac. .RE .\" METHOD: iconposition .TP \fBwm iconposition \fIwindow\fR ?\fIx y\fR? . If \fIx\fR and \fIy\fR are specified, they are passed to the window manager as a hint about where to position the icon for \fIwindow\fR. In this case an empty string is returned. If \fIx\fR and \fIy\fR are specified as empty strings then any existing icon position hint is cancelled. If neither \fIx\fR nor \fIy\fR is specified, then the command returns a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned). .\" METHOD: iconwindow .TP \fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? . If \fIpathName\fR is specified, it is the path name for a window to use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then \fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR is de-iconified then \fIpathName\fR will be unmapped again. If \fIpathName\fR is specified as an empty string then any existing icon window association for \fIwindow\fR will be cancelled. If the \fIpathName\fR argument is specified then an empty string is returned. Otherwise the command returns the path name of the current icon window for \fIwindow\fR, or an empty string if there is no icon window currently specified for \fIwindow\fR. Button press events are disabled for \fIwindow\fR as long as it is an icon window; this is needed in order to allow window managers to .QW own those events. Note that not all window managers support the notion of an icon window, and the concept is entirely meaningless on non-X11 platforms. .\" METHOD: manage .TP \fBwm manage \fIwidget\fR . The \fIwidget\fR specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc. Only \fIframe\fR, \fIlabelframe\fR and \fItoplevel\fR widgets can be used with this command. Attempting to pass any other widget type will raise an error. Attempting to manage a \fItoplevel\fR widget is benign and achieves nothing. See also \fBGEOMETRY MANAGEMENT\fR. .\" METHOD: maxsize .TP \fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? . If \fIwidth\fR and \fIheight\fR are specified, they give the maximum permissible dimensions for \fIwindow\fR. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be less than or equal to \fIwidth\fR and \fIheight\fR. If \fIwidth\fR and \fIheight\fR are specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the maximum width and height currently in effect. The maximum size defaults to the size of the screen. See the sections on geometry management below for more information. .\" METHOD: minsize .TP \fBwm minsize \fIwindow\fR ?\fIwidth height\fR? . If \fIwidth\fR and \fIheight\fR are specified, they give the minimum permissible dimensions for \fIwindow\fR. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be greater than or equal to \fIwidth\fR and \fIheight\fR. If \fIwidth\fR and \fIheight\fR are specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the minimum width and height currently in effect. The minimum size defaults to one pixel in each dimension. See the sections on geometry management below for more information. .\" METHOD: overrideredirect .TP \fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? . If \fIboolean\fR is specified, it must have a proper boolean form and the override-redirect flag for \fIwindow\fR is set to that value. If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is returned to indicate whether or not the override-redirect flag is currently set for \fIwindow\fR. Setting the override-redirect flag for a window causes it to be ignored by the window manager; among other things, this means that the window will not be reparented from the root window into a decorative frame and the user will not be able to manipulate the window using the normal window manager mechanisms. .RS .PP Note that the override-redirect flag is only guaranteed to be taken notice of when the window is first mapped or when mapped after the state is changed from withdrawn to normal. Some, but not all, platforms will take notice at additional times. .RE .\" METHOD: positionfrom .TP \fBwm positionfrom \fIwindow\fR ?\fIwho\fR? . If \fIwho\fR is specified, it must be either \fBprogram\fR or \fBuser\fR, or an abbreviation of one of these two. It indicates whether \fIwindow\fR's current position was requested by the program or by the user. Many window managers ignore program-requested |
︙ | ︙ | |||
696 697 698 699 700 701 702 703 704 705 706 707 708 709 | source of the window's current position, or an empty string if no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. Tk will automatically set the position source to \fBuser\fR when a \fBwm geometry\fR command is invoked, unless the source has been set explicitly to \fBprogram\fR. .TP \fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? . This command is used to manage window manager protocols. The \fIname\fR argument in the \fBwm protocol\fR command is the name of an atom corresponding to a window manager protocol. Examples include \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR or \fBWM_TAKE_FOCUS\fR. | > | 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 | source of the window's current position, or an empty string if no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. Tk will automatically set the position source to \fBuser\fR when a \fBwm geometry\fR command is invoked, unless the source has been set explicitly to \fBprogram\fR. .\" METHOD: protocol .TP \fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? . This command is used to manage window manager protocols. The \fIname\fR argument in the \fBwm protocol\fR command is the name of an atom corresponding to a window manager protocol. Examples include \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR or \fBWM_TAKE_FOCUS\fR. |
︙ | ︙ | |||
743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 | is not returned). If \fIcommand\fR is specified as an empty string then the atom for \fIname\fR is removed from the \fBWM_PROTOCOLS\fR property of \fIwindow\fR and the handler is destroyed; an empty string is returned. Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the \fBwm protocol\fR command returns a list of all of the protocols for which handlers are currently defined for \fIwindow\fR. .RE .TP \fBwm resizable \fIwindow\fR ?\fIwidth height\fR? . This command controls whether or not the user may interactively resize a top-level window. If \fIwidth\fR and \fIheight\fR are specified, they are boolean values that determine whether the width and height of \fIwindow\fR may be modified by the user. In this case the command returns an empty string. If \fIwidth\fR and \fIheight\fR are omitted then the command returns a list with two 0/1 elements that indicate whether the width and height of \fIwindow\fR are currently resizable. By default, windows are resizable in both dimensions. If resizing is disabled, then the window's size will be the size from the most recent interactive resize or \fBwm geometry\fR command. If there has been no such operation then the window's natural size will be used. .TP \fBwm sizefrom \fIwindow\fR ?\fIwho\fR? . If \fIwho\fR is specified, it must be either \fBprogram\fR or \fBuser\fR, or an abbreviation of one of these two. It indicates whether \fIwindow\fR's current size was requested by the program or by the user. Some window managers ignore program-requested sizes and ask the user to manually size the window; if \fBuser\fR is specified then the window manager should give the window its specified size without asking the user for assistance. If \fIwho\fR is specified as an empty string, then the current size source is cancelled. If \fIwho\fR is specified, then the command returns an empty string. Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the source of the window's current size, or an empty string if no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. .TP \fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? . The \fBstackorder\fR command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the window's children that are toplevels. Only those toplevels that are currently mapped to the screen are returned. The \fBstackorder\fR command can also be used to determine if one toplevel is positioned above or below a second toplevel. When two window arguments separated by either \fBisabove\fR or \fBisbelow\fR are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. .TP \fBwm state \fIwindow\fR ?newstate? . If \fInewstate\fR is specified, the window will be set to the new state, otherwise it returns the current state of \fIwindow\fR: either \fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and Mac OS X only) \fBzoomed\fR. The difference between \fBiconic\fR and \fBicon\fR is that \fBiconic\fR refers to a window that has been iconified (e.g., with the \fBwm iconify\fR command) while \fBicon\fR refers to a window whose only purpose is to serve as the icon for some other window (via the \fBwm iconwindow\fR command). The \fBicon\fR state cannot be set. .TP \fBwm title \fIwindow\fR ?\fIstring\fR? . If \fIstring\fR is specified, then it will be passed to the window manager for use as the title for \fIwindow\fR (the window manager should display this string in \fIwindow\fR's title bar). In this case the command returns an empty string. If \fIstring\fR is not specified then the command returns the current title for the \fIwindow\fR. The title for a window defaults to its name. .TP \fBwm transient \fIwindow\fR ?\fIcontainer\fR? . If \fIcontainer\fR is specified, then the window manager is informed that \fIwindow\fR is a transient window (e.g. pull-down menu) working on behalf of \fIcontainer\fR (where \fIcontainer\fR is the path name for a top-level window). If \fIcontainer\fR is specified as an empty string then \fIwindow\fR is marked as not being a transient window any more. Otherwise the command returns the path name of \fIwindow\fR's current container, or an empty string if \fIwindow\fR is not currently a transient window. A transient window will mirror state changes in the container and inherit the state of the container when initially mapped. The directed graph with an edge from each transient to its container must be acyclic. In particular, it is an error to attempt to make a window a transient of itself. The window manager may also decorate a transient window differently, removing some features normally present (e.g., minimize and maximize buttons) though this is entirely at the discretion of the window manager. .TP \fBwm withdraw \fIwindow\fR . Arranges for \fIwindow\fR to be withdrawn from the screen. This causes the window to be unmapped and forgotten about by the window manager. If the window has never been mapped, then this command causes the window to be mapped in the withdrawn state. Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. | > > > > > > > | | 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 | is not returned). If \fIcommand\fR is specified as an empty string then the atom for \fIname\fR is removed from the \fBWM_PROTOCOLS\fR property of \fIwindow\fR and the handler is destroyed; an empty string is returned. Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the \fBwm protocol\fR command returns a list of all of the protocols for which handlers are currently defined for \fIwindow\fR. .RE .\" METHOD: resizable .TP \fBwm resizable \fIwindow\fR ?\fIwidth height\fR? . This command controls whether or not the user may interactively resize a top-level window. If \fIwidth\fR and \fIheight\fR are specified, they are boolean values that determine whether the width and height of \fIwindow\fR may be modified by the user. In this case the command returns an empty string. If \fIwidth\fR and \fIheight\fR are omitted then the command returns a list with two 0/1 elements that indicate whether the width and height of \fIwindow\fR are currently resizable. By default, windows are resizable in both dimensions. If resizing is disabled, then the window's size will be the size from the most recent interactive resize or \fBwm geometry\fR command. If there has been no such operation then the window's natural size will be used. .\" METHOD: sizefrom .TP \fBwm sizefrom \fIwindow\fR ?\fIwho\fR? . If \fIwho\fR is specified, it must be either \fBprogram\fR or \fBuser\fR, or an abbreviation of one of these two. It indicates whether \fIwindow\fR's current size was requested by the program or by the user. Some window managers ignore program-requested sizes and ask the user to manually size the window; if \fBuser\fR is specified then the window manager should give the window its specified size without asking the user for assistance. If \fIwho\fR is specified as an empty string, then the current size source is cancelled. If \fIwho\fR is specified, then the command returns an empty string. Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the source of the window's current size, or an empty string if no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. .\" METHOD: stackorder .TP \fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? . The \fBstackorder\fR command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the window's children that are toplevels. Only those toplevels that are currently mapped to the screen are returned. The \fBstackorder\fR command can also be used to determine if one toplevel is positioned above or below a second toplevel. When two window arguments separated by either \fBisabove\fR or \fBisbelow\fR are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. .\" METHOD: state .TP \fBwm state \fIwindow\fR ?newstate? . If \fInewstate\fR is specified, the window will be set to the new state, otherwise it returns the current state of \fIwindow\fR: either \fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and Mac OS X only) \fBzoomed\fR. The difference between \fBiconic\fR and \fBicon\fR is that \fBiconic\fR refers to a window that has been iconified (e.g., with the \fBwm iconify\fR command) while \fBicon\fR refers to a window whose only purpose is to serve as the icon for some other window (via the \fBwm iconwindow\fR command). The \fBicon\fR state cannot be set. .\" METHOD: title .TP \fBwm title \fIwindow\fR ?\fIstring\fR? . If \fIstring\fR is specified, then it will be passed to the window manager for use as the title for \fIwindow\fR (the window manager should display this string in \fIwindow\fR's title bar). In this case the command returns an empty string. If \fIstring\fR is not specified then the command returns the current title for the \fIwindow\fR. The title for a window defaults to its name. .\" METHOD: transient .TP \fBwm transient \fIwindow\fR ?\fIcontainer\fR? . If \fIcontainer\fR is specified, then the window manager is informed that \fIwindow\fR is a transient window (e.g. pull-down menu) working on behalf of \fIcontainer\fR (where \fIcontainer\fR is the path name for a top-level window). If \fIcontainer\fR is specified as an empty string then \fIwindow\fR is marked as not being a transient window any more. Otherwise the command returns the path name of \fIwindow\fR's current container, or an empty string if \fIwindow\fR is not currently a transient window. A transient window will mirror state changes in the container and inherit the state of the container when initially mapped. The directed graph with an edge from each transient to its container must be acyclic. In particular, it is an error to attempt to make a window a transient of itself. The window manager may also decorate a transient window differently, removing some features normally present (e.g., minimize and maximize buttons) though this is entirely at the discretion of the window manager. .\" METHOD: widthdraw .TP \fBwm withdraw \fIwindow\fR . Arranges for \fIwindow\fR to be withdrawn from the screen. This causes the window to be unmapped and forgotten about by the window manager. If the window has never been mapped, then this command causes the window to be mapped in the withdrawn state. Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. Note that it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with \fBwm deiconify\fR) to get some window managers to pay attention to changes in window attributes such as group. .SH "GEOMETRY MANAGEMENT" .PP By default a top-level window appears on the screen in its \fInatural size\fR, which is the one determined internally by its |
︙ | ︙ | |||
938 939 940 941 942 943 944 | \fBwm resizable\fR .fixed 0 0 .CE .PP A simple dialog-like window, centred on the screen: .CS # Create and arrange the dialog contents. toplevel .msg | | | | | | | | > | 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 | \fBwm resizable\fR .fixed 0 0 .CE .PP A simple dialog-like window, centred on the screen: .CS # Create and arrange the dialog contents. toplevel .msg label .msg.l -text "This is a very simple dialog demo." button .msg.ok -text OK -default active -command {destroy .msg} pack .msg.ok -side bottom -fill x pack .msg.l -expand 1 -fill both # Now set the widget up as a centred dialog. # But first, we need the geometry managers to finish setting # up the interior of the dialog, for which we need to run the # event loop with the widget hidden completely... \fBwm withdraw\fR .msg update set x [expr {([winfo screenwidth .] - [winfo width .msg]) / 2}] set y [expr {([winfo screenheight .] - [winfo height .msg]) / 2}] \fBwm geometry\fR .msg +$x+$y \fBwm transient\fR .msg . \fBwm title\fR .msg "Dialog demo" \fBwm deiconify\fR .msg .CE .SH "SEE ALSO" toplevel(n), winfo(n) .SH KEYWORDS aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager '\" Local Variables: '\" mode: nroff '\" End: |