diff options
Diffstat (limited to 'doc')
114 files changed, 3162 insertions, 5975 deletions
diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index f589e66..a6deb30 100644 --- a/doc/3DBorder.3 +++ b/doc/3DBorder.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance +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 @@ -17,9 +17,18 @@ Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectang Tk_3DBorder \fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp +void +\fBTk_ClipDrawableToRect(\fIdisplay, drawable, x, y, width, height\fB)\fR +.sp +void +\fBTk_DrawHighlightBorder(\fItkwin, fgGC, bgGC, highlightWidth, drawable\fB)\fR +.sp Tk_3DBorder \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR .sp +void +\fBTk_Get3DBorderColors(\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\fB)\fR +.sp Tk_3DBorder \fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR .sp @@ -90,6 +99,8 @@ Height of rectangle describing border or bevel, in pixels. 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, @@ -133,6 +144,16 @@ 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 @@ -159,11 +180,24 @@ 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 d to the given rectangle. If width or height are negative, reset to no clipping. +Subsequent drawing into d 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 prevents \fBTk_Get3DBorder\fR from caching the return value, so \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. .PP +\fBTk_Get3DBorderColors\fR returns the used colors of the given border. +.PP \fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given the window and color name used to create the border. \fBTk_Get3DBorderFromObj\fR does not actually create the border; it must diff --git a/doc/AddOption.3 b/doc/AddOption.3 index c6f0cc1..fc46492 100644 --- a/doc/AddOption.3 +++ b/doc/AddOption.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_AddOption 3 "" Tk "Tk Library Procedures" @@ -13,6 +13,9 @@ Tk_AddOption \- Add an option to the option database .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. @@ -20,12 +23,16 @@ Token for window. Multi-element name of option. .AP "const char" *value in Value of option. +.AP "const char" *dbName in +The option database name. +.AP "const char" *className in +The name of the option class. .AP int priority in Overall priority level to use for option. .BE .SH DESCRIPTION .PP -This procedure is invoked to add an option to the database +\fBTk_AddOption\fR is invoked to add an option to the database associated with \fItkwin\fR's main window. \fIName\fR contains the option being specified and consists of names and/or classes separated by asterisks or dots, in the usual X format. @@ -46,5 +53,9 @@ user-specific startup files. .IP \fBTK_INTERACTIVE_PRIO\fR (80) Used for options specified interactively after the application starts running. +.PP +\fBTk_GetSystemDefault\fR returns a Tcl_Obj* with the string identifying +a configuration option matching the given \fIdbname\fR and \fIclassName\fR. +Returns NULL if there are no system defaults that match this pair. .SH KEYWORDS class, name, option, add diff --git a/doc/BindTable.3 b/doc/BindTable.3 index 772f39f..1d3a85b 100644 --- a/doc/BindTable.3 +++ b/doc/BindTable.3 @@ -41,7 +41,7 @@ used for returning results and errors from binding procedures. .AP Tk_BindingTable bindingTable in Token for binding table; must have been returned by some previous call to \fBTk_CreateBindingTable\fR. -.AP ClientData object in +.AP "void *" object in Identifies object with which binding is associated. .AP "const char" *eventString in String describing event sequence. @@ -57,7 +57,7 @@ Identifier for any window on the display where the event occurred. Used to find display-related information such as key maps. .AP int numObjects in Number of object identifiers pointed to by \fIobjectPtr\fR. -.AP ClientData *objectPtr in +.AP "void **" objectPtr in Points to an array of object identifiers: bindings will be considered for each of these objects in order from first to last. .BE diff --git a/doc/CanvPsY.3 b/doc/CanvPsY.3 index f789d3c..1e4e320 100644 --- a/doc/CanvPsY.3 +++ b/doc/CanvPsY.3 @@ -30,7 +30,7 @@ int int \fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) .SH ARGUMENTS -.AS "unsigned int" "numPoints" +.AS int "numPoints" .AP Tk_Canvas canvas in A token that identifies a canvas widget for which Postscript is being generated. diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 index 92be073..58712db 100644 --- a/doc/ConfigWidg.3 +++ b/doc/ConfigWidg.3 @@ -25,7 +25,7 @@ int .sp \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR .SH ARGUMENTS -.AS char *widgRec in/out +.AS void *widgRec in/out .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in @@ -107,7 +107,7 @@ typedef struct { const char *\fIdbName\fR; const char *\fIdbClass\fR; const char *\fIdefValue\fR; - int \fIoffset\fR; + size_t \fIoffset\fR; int \fIspecFlags\fR; const Tk_CustomOption *\fIcustomPtr\fR; } \fBTk_ConfigSpec\fR; @@ -161,9 +161,8 @@ contain information relevant to the manager of the widget; its exact type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store the information about this configuration option. You should use the -\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for -a description of \fBTk_Offset\fR). The location indicated by -\fIwidgRec\fR and \fIoffset\fR will be referred to as the +\fBoffsetof\fR macro to generate \fIoffset\fR values. The location +indicated by \fIwidgRec\fR and \fIoffset\fR will be referred to as the .QW target in the descriptions below. .PP @@ -469,13 +468,6 @@ for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, \fIflags\fR will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c. -.SH TK_OFFSET -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating -the \fIoffset\fR values for entries in Tk_ConfigSpec structures. -It takes two arguments: the name of a type of record, and the -name of a field in that record. It returns the byte offset of -the named field in records of the given type. .SH TK_CONFIGUREINFO .PP The \fBTk_ConfigureInfo\fR procedure may be used to obtain @@ -544,11 +536,11 @@ of the a type and creating a structure pointing to those procedures: typedef struct Tk_CustomOption { Tk_OptionParseProc *\fIparseProc\fR; Tk_OptionPrintProc *\fIprintProc\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; } \fBTk_CustomOption\fR; typedef int \fBTk_OptionParseProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, char *\fIvalue\fR, @@ -556,7 +548,7 @@ typedef int \fBTk_OptionParseProc\fR( int \fIoffset\fR); typedef const char *\fBTk_OptionPrintProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIwidgRec\fR, int \fIoffset\fR, diff --git a/doc/CrtErrHdlr.3 b/doc/CrtErrHdlr.3 index e6ebafe..09dcf8b 100644 --- a/doc/CrtErrHdlr.3 +++ b/doc/CrtErrHdlr.3 @@ -35,7 +35,7 @@ field. If \-1, then match any \fIminor_code\fR value. Procedure to invoke whenever an error event is received for \fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR. NULL means ignore any matching errors. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP Tk_ErrorHandler handler in Token for error handler to delete (return value from a previous @@ -73,7 +73,7 @@ made when the handler was active (see below for more information). following type: .CS typedef int \fBTk_ErrorProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, XErrorEvent *\fIerrEventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR diff --git a/doc/CrtGenHdlr.3 b/doc/CrtGenHdlr.3 index 1d6f3d5..aaf3285 100644 --- a/doc/CrtGenHdlr.3 +++ b/doc/CrtGenHdlr.3 @@ -21,7 +21,7 @@ Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback .AS "Tk_GenericProc" clientData .AP Tk_GenericProc *proc in Procedure to invoke whenever any X event occurs on any display. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -45,7 +45,7 @@ call \fBTk_HandleEvent\fR, such as \fBTcl_DoOneEvent\fR or type \fBTk_GenericProc\fR: .CS typedef int \fBTk_GenericProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3 index 250f537..b15a851 100644 --- a/doc/CrtImgType.3 +++ b/doc/CrtImgType.3 @@ -9,20 +9,15 @@ .so man.macros .BS .SH NAME -Tk_CreateImageType, Tk_GetImageMasterData, Tk_GetImageModelData, Tk_InitImageArgs \- define new kind of image +Tk_CreateImageType, Tk_GetImageModelData, Tk_InitImageArgs \- define new kind of image .SH SYNOPSIS .nf \fB#include <tk.h>\fR .sp \fBTk_CreateImageType\fR(\fItypePtr\fR) .sp -ClientData -\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) -.sp -.VS "TIP 581" -ClientData +void * \fBTk_GetImageModelData\fR(\fIinterp, name, typePtrPtr\fR) -.VE "TIP 581" .sp \fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR) .SH ARGUMENTS @@ -118,8 +113,8 @@ typedef int \fBTk_ImageCreateProc\fR( int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[], const Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImodel\fR, - ClientData *\fImodelDataPtr\fR); + Tk_ImageModel \fImodel\fR, + void **\fImodelDataPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the \fBimage\fR command was invoked, and \fIname\fR is the name for the new image, @@ -151,9 +146,9 @@ size of the image and request an initial redisplay. calls \fBTk_GetImage\fR to use a particular image. This procedure must match the following prototype: .CS -typedef ClientData \fBTk_ImageGetProc\fR( +typedef void *\fBTk_ImageGetProc\fR( Tk_Window \fItkwin\fR, - ClientData \fImodelData\fR); + void *\fImodelData\fR); .CE The \fItkwin\fR argument identifies the window in which the image will be used and \fImodelData\fR is the value @@ -172,7 +167,7 @@ to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). \fIdisplayProc\fR must match the following prototype: .CS typedef void \fBTk_ImageDisplayProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, Display *\fIdisplay\fR, Drawable \fIdrawable\fR, int \fIimageX\fR, @@ -208,7 +203,7 @@ canvas item is changed. \fIfreeProc\fR must match the following prototype: .CS typedef void \fBTk_ImageFreeProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, Display *\fIdisplay\fR); .CE The \fIinstanceData\fR will be the same as the value returned by @@ -226,7 +221,7 @@ each of the image's instances. \fIdeleteProc\fR must match the following prototype: .CS typedef void \fBTk_ImageDeleteProc\fR( - ClientData \fImodelData\fR); + void *\fImodelData\fR); .CE The \fImodelData\fR argument will be the same as the value stored in \fI*modelDataPtr\fR by \fIcreateProc\fR when the @@ -235,21 +230,17 @@ image was created. the image. .SH TK_GETIMAGEMODELDATA .PP -The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve +The procedure \fBTk_GetImageModelData\fR may be invoked to retrieve information about an image. For example, an image manager can use this procedure to locate its image model data for an image. If there exists an image named \fIname\fR in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is filled in with type information for the image (the \fItypePtr\fR value passed to \fBTk_CreateImageType\fR when the image type was registered) -and the return value is the ClientData value returned by the +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. -.PP -.VS "TIP 581" -\fBTk_GetImageModelData\fR is synonym for \fBTk_GetImageMasterData\fR -.VE "TIP 581" .SH "LEGACY INTERFACE SUPPORT" .PP In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR @@ -261,8 +252,8 @@ typedef int \fBTk_ImageCreateProc\fR( int \fIargc\fR, char **\fIargv\fR, Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImodel\fR, - ClientData *\fImodelDataPtr\fR); + Tk_ImageModel \fImodel\fR, + void **\fImodelDataPtr\fR); .CE Legacy programs and libraries dating from those days may still contain code that defines extended Tk image types using the old @@ -270,10 +261,6 @@ interface. The Tk header file will still support this legacy interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR defined. .PP -.VS "TIP 581" -\fITk_ImageModel\fR is synonym for \fITk_ImageMaster\fR -.VE "TIP 581" -.PP When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may see the routine \fBTk_InitImageArgs\fR in use. This was a migration tool used to create stub-enabled extensions that could be loaded diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 index f9198f3..82fc26e 100644 --- a/doc/CrtItemType.3 +++ b/doc/CrtItemType.3 @@ -64,7 +64,7 @@ the standard procedures implemented by the type manager: .CS typedef struct Tk_ItemType { const char *\fIname\fR; - int \fIitemSize\fR; + size_t \fIitemSize\fR; Tk_ItemCreateProc *\fIcreateProc\fR; const Tk_ConfigSpec *\fIconfigSpecs\fR; Tk_ItemConfigureProc *\fIconfigProc\fR; @@ -83,6 +83,9 @@ typedef struct Tk_ItemType { Tk_ItemInsertProc *\fIinsertProc\fR; Tk_ItemDCharsProc *\fIdCharsProc\fR; Tk_ItemType *\fInextPtr\fR; +.VS "8.7, TIP164" + Tk_ItemRotateProc *\fIrotateProc\fR; +.VE "8.7, TIP164" } \fBTk_ItemType\fR; .CE .PP @@ -170,7 +173,7 @@ The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons) contains a collection of flag bits that modify how the canvas core interacts with the item. The following bits are defined: .TP -\fB1\fR +\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 @@ -549,6 +552,46 @@ and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be added to each x and y coordinate within the item. The type manager should adjust the item's coordinates and update the bounding box in the item's header. +.SS ROTATEPROC +.VS "8.7, TIP164" +.PP +\fItypePtr\->rotateProc\fR is invoked by Tk to rotate a canvas item +during the \fBrotate\fR widget command. +The procedure must match the following prototype: +.PP +.CS +typedef void \fBTk_ItemRotateProc\fR( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIoriginX\fR, + double \fIoriginY\fR, + double \fIangleRad\fR); +.CE +.PP +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. +\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which +the item is to be 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 - \fIoriginX\fR +\fIrelY\fR = \fIy\fR - \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. +\fIrotateProc\fR must also update the bounding box in the item's header. +.PP +Item types do not need to provide a \fItypePtr\->rotateProc\fR. If the +\fItypePtr\->rotateProc\fR is NULL, the \fItypePtr\->coordProc\fR will be +used instead to retrieve and update the list of coordinates. +.VE "8.7, TIP164" .SS INDEXPROC .PP \fItypePtr\->indexProc\fR is invoked by Tk to translate a string diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 index 92f2441..c7accdb 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -9,7 +9,7 @@ '\" Department of Computer Science, '\" Australian National University. '\" -.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" +.TH Tk_CreatePhotoImageFormat 3 8.7 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME @@ -18,15 +18,23 @@ Tk_CreatePhotoImageFormat \- define new file format for photo images .nf \fB#include <tk.h>\fR .sp +.VS 8.7 +\fBTk_CreatePhotoImageFormatVersion3\fR(\fIformatVersion3Ptr\fR) +.VE 8.7 +.sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SH ARGUMENTS -.AS "const Tk_PhotoImageFormat" *formatPtr +.AS "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr +.VS 8.7 +.AP "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr in +Structure that defines the new file format including metadata functionality. +.VE 8.7 .AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE .SH DESCRIPTION .PP -\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format +\fBTk_CreatePhotoImageFormatVersion3\fR is invoked to define a new file format for image data for use with photo images. The code that implements an image file format is called an image file format handler, or handler for short. The photo image code @@ -38,22 +46,29 @@ The user can specify which handler to use with the \fB\-format\fR image configuration option or the \fB\-format\fR option to the \fBread\fR and \fBwrite\fR photo image subcommands. .PP +The alternate version 2 function \fBTk_CreatePhotoImageFormat\fR has +identical functionality, but does not allow the handler to get or return +the metadata dictionary of the image. +It is described in section \fBVERSION 2 INTERFACE\fR below. +.PP An image file format handler consists of a collection of procedures -plus a Tk_PhotoImageFormat structure, which contains the name of the -image file format and pointers to six procedures provided by the -handler to deal with files and strings in this format. The -Tk_PhotoImageFormat structure contains the following fields: +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 Tk_PhotoImageFormat { +typedef struct Tk_PhotoImageFormatVersion3 { const char *\fIname\fR; - Tk_ImageFileMatchProc *\fIfileMatchProc\fR; - Tk_ImageStringMatchProc *\fIstringMatchProc\fR; - Tk_ImageFileReadProc *\fIfileReadProc\fR; - Tk_ImageStringReadProc *\fIstringReadProc\fR; - Tk_ImageFileWriteProc *\fIfileWriteProc\fR; - Tk_ImageStringWriteProc *\fIstringWriteProc\fR; -} \fBTk_PhotoImageFormat\fR; + Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR; + Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR; + Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR; + Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR; + Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR; + Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR; +} \fBTk_PhotoImageFormatVersion3\fR; .CE +.VE 8.7 .PP The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be @@ -67,14 +82,16 @@ procedure, and the \fIstringMatchProc\fR procedure if it provides the .SS NAME .PP \fIformatPtr->name\fR provides a name for the image type. -Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used -in the \fB\-format\fR photo image configuration and subcommand option. +Once \fBTk_CreatePhotoImageFormatVersion3\fR returns, this name may be +used in the \fB\-format\fR photo image configuration and subcommand +option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the \fB\-format\fR option. The first character of \fIformatPtr->name\fR must not be an uppercase character from the ASCII character set (that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used only for legacy interface support (see below). +.VS 8.7 .SS FILEMATCHPROC .PP \fIformatPtr->fileMatchProc\fR provides the address of a procedure for @@ -82,39 +99,47 @@ Tk to call when it is searching for an image file format handler suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS -typedef int \fBTk_ImageFileMatchProc\fR( +typedef int \fBTk_ImageFileMatchProcVersion3\fR( + Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Obj *\fImetadataOut\fR); .CE The \fIfileName\fR argument is the name of the file containing the image data, which is open for reading as \fIchan\fR. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the file appears to be in the format supported by this handler, the \fIformatPtr->fileMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. .SS STRINGMATCHPROC .PP -\fIformatPtr->stringMatchProc\fR provides the address of a procedure for -Tk to call when it is searching for an image file format handler for +\fIformatPtr->stringMatchProc\fR provides the address of a procedure +for Tk to call when it is searching for an image file format handler suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS -typedef int \fBTk_ImageStringMatchProc\fR( +typedef int \fBTk_ImageStringMatchProcVersion3\fR( + Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Obj *\fImetadataOut\fR); .CE The \fIdata\fR argument points to the object containing the image data. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the string appears to be in the format supported by this handler, the \fIformatPtr->stringMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and @@ -131,10 +156,12 @@ typedef int \fBTk_ImageFileReadProc\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, int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + int \fIsrcX\fR, int \fIsrcY\fR, + Tcl_Obj *\fImetadataOut\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -148,34 +175,40 @@ dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. 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 provides the address of a procedure +for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringReadProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + int \fIsrcX\fR, int \fIsrcY\fR, + Tcl_Obj *\fImetadataOut\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The \fIdata\fR argument points to the image data in object form. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was -not specified. The image data in the string, or a subimage of it, is to -be read into the photo image identified by the handle +not specified. The image data in the string, or a subimage of it, is +to be read into the photo image identified by the handle \fIimageHandle\fR. The subimage of the data in the string is of dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. The return value is a standard Tcl return value. .SS FILEWRITEPROC .PP @@ -187,6 +220,7 @@ typedef int \fBTk_ImageFileWriteProc\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 @@ -201,16 +235,20 @@ not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->fileWriteProc\fR procedure may interpret these characters to specify further details about the image file. +\fBmetadataIn\fR may contain metadata keys that a driver may include +into the output data. The return value is a standard Tcl return value. .SS STRINGWRITEPROC .PP -\fIformatPtr->stringWriteProc\fR provides the address of a procedure for -Tk to call to translate image data from a photo image into a string. +\fIformatPtr->stringWriteProc\fR provides the address of a procedure +for Tk to call to translate image data from a photo image into a +string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was @@ -225,7 +263,201 @@ not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->stringWriteProc\fR procedure may interpret these characters to specify further details about the image file. +\fBmetadataIn\fR may contain metadata keys that a driver may include +into the output data. The return value is a standard Tcl return value. +.PP +.SH "METADATA INTERFACE" +.PP +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 +.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: +.RS +Abreviation are in upper case +.RE +.RS +Words are in US English in small case (except proper nouns) +.RE +.RS +Vertical DPI is expressed as DPI/aspect. The reason is, that some +image formats may feature aspect and no resolution value. +.RE +.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)); +.CE +.PP +The \-metadata 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 \-metadata 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 \-metadata 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 +matadata dict to return them. +Those functions get a Tcl object pointer \fBmetadataOut\fR as +parameter. +metadataOut may be NULL to indicate, that no metadata return is +attended(\fBput\fR, \fBread\fR subcommands). +\fBmetadataOut\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. +.PP +Format string options or metadata keys may influence the creation of +metadata within the driver. +For example, the creation of an expensive metadata key may depend on a +format string option or on a metadata input key. +.PP +.VE 8.7 +.SH "VERSION 2 INTERFACE" +.PP +Version 2 Interface does not include the possibility for the driver to +use the metadata dict for input or output. +.SS SYNOPSIS +\fB#include <tk.h>\fR +.sp +\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) +.SS ARGUMENTS +.AS "const Tk_PhotoImageFormat" *formatPtr +.AP "const Tk_PhotoImageFormat" *formatPtr in +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 Tk_PhotoImageFormat { + const char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; +} \fBTk_PhotoImageFormat\fR; +.CE +.PP +.SS FILEMATCHPROC +.PP +\fIformatPtr->fileMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileMatchProc\fR( + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +.PP +.SS STRINGMATCHPROC +.PP +\fIformatPtr->stringMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringMatchProc\fR( + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +.SS FILEREADPROC +.PP +\fIformatPtr->fileReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +.SS STRINGREADPROC +.PP +\fIformatPtr->stringReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +.SS FILEWRITEPROC +.PP +\fIformatPtr->fileWriteProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +.SS STRINGWRITEPROC +.PP +\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 +.PP .SH "LEGACY INTERFACE SUPPORT" .PP In Tk 8.2 and earlier, the definition of all the function pointer diff --git a/doc/CrtSelHdlr.3 b/doc/CrtSelHdlr.3 index 2292ccc..b3c749c 100644 --- a/doc/CrtSelHdlr.3 +++ b/doc/CrtSelHdlr.3 @@ -32,7 +32,7 @@ commands. Procedure to invoke whenever the selection is owned by \fItkwin\fR and the selection contents are requested in the format given by \fItarget\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP Atom format in If the selection requestor is not in this process, \fIformat\fR determines @@ -55,7 +55,7 @@ the selection. The most common form is STRING. type \fBTk_SelectionProc\fR: .CS typedef int \fBTk_SelectionProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIoffset\fR, char *\fIbuffer\fR, int \fImaxBytes\fR); diff --git a/doc/EventHndlr.3 b/doc/EventHndlr.3 index a2cbf8d..128f8ee 100644 --- a/doc/EventHndlr.3 +++ b/doc/EventHndlr.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event +Tk_CreateEventHandler, Tk_DeleteEventHandler, Tk_GetButtonMask, Tk_SendVirtualEvent \- associate procedure callback with an X event .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -17,8 +17,18 @@ Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback wit \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 +Detail information for the virtual event. .AP Tk_Window tkwin in Token for window in which events may occur. .AP "unsigned long" mask in @@ -27,7 +37,7 @@ for which \fIproc\fR should be called. .AP Tk_EventProc *proc in Procedure to invoke whenever an event in \fImask\fR occurs in the window given by \fItkwin\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -45,7 +55,7 @@ call \fBTk_HandleEvent\fR, such as \fBTcl_DoOneEvent\fR or type \fBTk_EventProc\fR: .CS typedef void \fBTk_EventProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR @@ -71,5 +81,10 @@ automatically; in this case there is no need to call If multiple handlers are declared for the same type of X event on the same window, then the handlers will be invoked in the order they were created. +.PP +\fBTk_GetButtonMask\fR returns the button mask corresponding to +the button. E.g it will return \fIButton1Mask\fR for button \fIButton1\fR. +.PP +\fBTk_SendVirtualEvent\fR sends a virtual event to Tk's event queue. .SH KEYWORDS bind, callback, event, handler diff --git a/doc/FreeXId.3 b/doc/FreeXId.3 index 56c7804..84fef26 100644 --- a/doc/FreeXId.3 +++ b/doc/FreeXId.3 @@ -25,24 +25,6 @@ context, or colormap) that is no longer in use. .BE .SH DESCRIPTION .PP -The default allocator for resource identifiers provided by Xlib is very -simple-minded and does not allow resource identifiers to be re-used. -If a long-running application reaches the end of the resource id -space, it will generate an X protocol error and crash. -Tk replaces the default id allocator with its own allocator, which -allows identifiers to be reused. -In order for this to work, \fBTk_FreeXId\fR must be called to -tell the allocator about resources that have been freed. -Tk automatically calls \fBTk_FreeXId\fR whenever it frees a -resource, so if you use procedures like \fBTk_GetFont\fR, -\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call -\fBTk_FreeXId\fR. -However, if you allocate resources directly from Xlib, for example -by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR -when you call the corresponding Xlib free procedure, such as -\fBXFreePixmap\fR. -If you do not call \fBTk_FreeXId\fR then the resource identifier will -be lost, which could cause problems if the application runs long enough -to lose all of the available identifiers. +This function is deprecated, it doesn't do anything since 2008-08-19. .SH KEYWORDS resource identifier diff --git a/doc/GetFont.3 b/doc/GetFont.3 index 0504916..9497556 100644 --- a/doc/GetFont.3 +++ b/doc/GetFont.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts +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 @@ -23,6 +23,9 @@ Tk_Font Tk_Font \fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR .sp +Tcl_Obj * +\fBTk_FontGetDescription(\fItkfont\fB)\fR +.sp const char * \fBTk_NameOfFont(\fItkfont\fB)\fR .sp @@ -88,6 +91,9 @@ 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 "{{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 diff --git a/doc/GetHINSTANCE.3 b/doc/GetHINSTANCE.3 index 980b374..8f82ee9 100644 --- a/doc/GetHINSTANCE.3 +++ b/doc/GetHINSTANCE.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures" diff --git a/doc/GetHWND.3 b/doc/GetHWND.3 index 15d2ff0..1e8cdc9 100644 --- a/doc/GetHWND.3 +++ b/doc/GetHWND.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH HWND 3 8.0 Tk "Tk Library Procedures" diff --git a/doc/GetImage.3 b/doc/GetImage.3 index 744f9ac..c437db7 100644 --- a/doc/GetImage.3 +++ b/doc/GetImage.3 @@ -32,7 +32,7 @@ Window in which image will be used. Name of image. .AP Tk_ImageChangedProc *changeProc in Procedure for Tk to invoke whenever image content or size changes. -.AP ClientData clientData in +.AP void *clientData in One-word value for Tk to pass to \fIchangeProc\fR. .AP Tk_Image image in Token for image instance; must have been returned by a previous @@ -106,7 +106,7 @@ The \fIchangeProc\fR and \fIclientData\fR arguments to in the image; it must match the following prototype: .CS typedef void \fBTk_ImageChangedProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIx\fR, int \fIy\fR, int \fIwidth\fR, diff --git a/doc/GetPixels.3 b/doc/GetPixels.3 index 6c31af9..568c601 100644 --- a/doc/GetPixels.3 +++ b/doc/GetPixels.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units +Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -18,6 +18,9 @@ int \fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR .sp int +\fBTk_GetDoublePixelsFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR +.sp +int \fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR .sp int @@ -81,6 +84,9 @@ in \fIinterp\fR's result if \fIinterp\fR is not NULL. value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR. .PP +\fBTk_GetDoublePixelsFromObj\fR is identical to \fBTk_GetPixelsFromObj\fR +except it returns a double not rounded to the nearest integer. +.PP \fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except that the screen distance is specified with a string instead of an object. This prevents \fBTk_GetPixels\fR from caching the diff --git a/doc/GetScroll.3 b/doc/GetScroll.3 index 43aaa48..91a2585 100644 --- a/doc/GetScroll.3 +++ b/doc/GetScroll.3 @@ -50,19 +50,20 @@ and parses the words starting with \fIobjv\fR[2]. The words starting with \fIobjv\fR[2] must have one of the following forms: .CS \fBmoveto \fIfraction\fR -\fBscroll \fInumber\fB units\fR \fBscroll \fInumber\fB pages\fR +\fBscroll \fInumber\fB units\fR .CE .LP -Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR +Any of the \fBmoveto\fR, \fBscroll\fR, \fBpages\fR, and \fBunits\fR keywords may be abbreviated. If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR is returned as result and \fI*fractionPtr\fR is filled in with the \fIfraction\fR argument to the command, which must be a proper real value. -If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR -or \fBTK_SCROLL_PAGES\fR is returned and \fI*stepsPtr\fR is filled -in with the \fInumber\fR value, which must be a proper integer. +If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_PAGES\fR +or \fBTK_SCROLL_UNITS\fR is returned and \fI*stepsPtr\fR is filled +in with the \fInumber\fR value, which must be a integer or a float, +but if it is a float then it is converted to an integer, rounded away from 0. If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR is returned and an error message is left in interpreter \fIinterp\fR's result. diff --git a/doc/GetSelect.3 b/doc/GetSelect.3 index 11e837e..455b142 100644 --- a/doc/GetSelect.3 +++ b/doc/GetSelect.3 @@ -30,7 +30,7 @@ Form in which to retrieve selection. .AP Tk_GetSelProc *proc in Procedure to invoke to process pieces of the selection as they are retrieved. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -44,7 +44,7 @@ should have arguments and result that match the type .PP .CS typedef int \fBTk_GetSelProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, char *\fIportion\fR); .CE @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_Grab 3 "" Tk "Tk Library Procedures" diff --git a/doc/HWNDToWindow.3 b/doc/HWNDToWindow.3 index a2e5a6c..c5dafdd 100644 --- a/doc/HWNDToWindow.3 +++ b/doc/HWNDToWindow.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures" diff --git a/doc/ImgChanged.3 b/doc/ImgChanged.3 index 69ba43c..ed47d26 100644 --- a/doc/ImgChanged.3 +++ b/doc/ImgChanged.3 @@ -16,8 +16,8 @@ Tk_ImageChanged \- notify widgets that image needs to be redrawn .sp \fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR) .SH ARGUMENTS -.AS Tk_ImageMaster imageHeight -.AP Tk_ImageMaster model in +.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 @@ -48,10 +48,6 @@ specify a rectangular region within the image that needs to be redrawn. \fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. .PP -.VS "TIP 581" -\fITk_ImageModel\fR is synonym for \fITk_ImageMaster\fR -.VE "TIP 581" -.PP An image manager should call \fBTk_ImageChanged\fR during its \fIcreateProc\fR to specify the image's initial size and to force redisplay if there are existing instances for the image. diff --git a/doc/Inactive.3 b/doc/Inactive.3 index 42ae5b8..ea8d735 100644 --- a/doc/Inactive.3 +++ b/doc/Inactive.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures" diff --git a/doc/MainWin.3 b/doc/MainWin.3 index 94bd7e2..b11b6cd 100644 --- a/doc/MainWin.3 +++ b/doc/MainWin.3 @@ -17,12 +17,26 @@ Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window inform Tk_Window \fBTk_MainWindow\fR(\fIinterp\fR) .sp +void +\fBTk_SetMainMenubar\fR(\fIinterp, tkwin, menuName\fR) +.sp +void +\fBTk_SetWindowMenubar\fR(\fIinterp, tkwin, oldMenuName, menuName\fR) +.sp int \fBTk_GetNumMainWindows\fR() .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 +The name of the new menubar that the toplevel needs to be set to. +NULL means that their is no menu now. +.AP const char *oldMenuName in +The name of the menubar previously set in this toplevel. +NULL means no menu was set previously. .BE .SH DESCRIPTION .PP @@ -36,5 +50,12 @@ 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 accross 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 diff --git a/doc/ManageGeom.3 b/doc/ManageGeom.3 index 4d7ac53..dd69273 100644 --- a/doc/ManageGeom.3 +++ b/doc/ManageGeom.3 @@ -25,7 +25,7 @@ geometry manager, or NULL to indicate that \fItkwin\fR's geometry should not be managed anymore. The data structure pointed to by \fImgrPtr\fR must be static: Tk keeps a reference to it as long as the window is managed. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to geometry manager callbacks. .BE .SH DESCRIPTION @@ -44,7 +44,7 @@ the geometry manager: typedef struct { const char *\fIname\fR; Tk_GeomRequestProc *\fIrequestProc\fR; - Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; + Tk_GeomLostContentProc *\fIlostContentProc\fR; } \fBTk_GeomMgr\fR; .CE The \fIname\fR field is the textual name for the geometry manager, @@ -58,7 +58,7 @@ content window to change its desired geometry. type \fBTk_GeomRequestProc\fR: .CS typedef void \fBTk_GeomRequestProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR); .CE The parameters to \fIrequestProc\fR will be identical to the @@ -67,24 +67,24 @@ corresponding parameters passed to \fBTk_ManageGeometry\fR. structure containing application-specific information about how to manage \fItkwin\fR's geometry. .PP -The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another +The \fIlostContentProc\fR field of \fImgrPtr\fR points to another procedure in the geometry manager. -Tk will invoke \fIlostSlaveProc\fR if some other manager +Tk will invoke \fIlostContentProc\fR if some other manager calls \fBTk_ManageGeometry\fR to claim \fItkwin\fR away from the current geometry manager. -\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is +\fIlostContentProc\fR is not invoked if \fBTk_ManageGeometry\fR is called with a NULL value for \fImgrPtr\fR (presumably the current geometry manager has made this call, so it already knows that the window is no longer managed), nor is it called if \fImgrPtr\fR is the same as the window's current geometry manager. -\fIlostSlaveProc\fR should have +\fIlostContentProc\fR should have arguments and results that match the following prototype: .CS -typedef void \fBTk_GeomLostSlaveProc\fR( - ClientData \fIclientData\fR, +typedef void \fBTk_GeomLostContentProc\fR( + void *\fIclientData\fR, Tk_Window \fItkwin\fR); .CE -The parameters to \fIlostSlaveProc\fR will be identical to the +The parameters to \fIlostContentProc\fR will be identical to the corresponding parameters passed to \fBTk_ManageGeometry\fR. .SH KEYWORDS callback, geometry, managed, request, unmanaged diff --git a/doc/NameOfImg.3 b/doc/NameOfImg.3 index 484e479..781650f 100644 --- a/doc/NameOfImg.3 +++ b/doc/NameOfImg.3 @@ -14,10 +14,10 @@ Tk_NameOfImage \- Return name of image. \fB#include <tk.h>\fR .sp const char * -\fBTk_NameOfImage\fR(\fIimageMaster\fR) +\fBTk_NameOfImage\fR(\fIimageModel\fR) .SH ARGUMENTS -.AS Tk_ImageMaster imageMaster -.AP Tk_ImageMaster imageMaster in +.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 @@ -26,9 +26,5 @@ the image was created. This procedure is invoked by image managers to find out the name of an image. Given the token for the image, it returns the string name for the image. -.PP -.VS "TIP 581" -\fITk_ImageModel\fR is synonym for \fITk_ImageMaster\fR -.VE "TIP 581" .SH KEYWORDS image manager, image name diff --git a/doc/OwnSelect.3 b/doc/OwnSelect.3 index 0e16eac..67bac55 100644 --- a/doc/OwnSelect.3 +++ b/doc/OwnSelect.3 @@ -23,7 +23,7 @@ Window that is to become new selection owner. The name of the selection to be owned, such as XA_PRIMARY. .AP Tk_LostSelProc *proc in Procedure to invoke when \fItkwin\fR loses selection ownership later. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -39,7 +39,7 @@ unhighlighting the selection). \fIProc\fR should have arguments and result that match the type \fBTk_LostSelProc\fR: .CS typedef void \fBTk_LostSelProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 index 4d85d15..727dcfa 100644 --- a/doc/ParseArgv.3 +++ b/doc/ParseArgv.3 @@ -72,8 +72,8 @@ expected; each of its entries has the following structure: typedef struct { const char *\fIkey\fR; int \fItype\fR; - char *\fIsrc\fR; - char *\fIdst\fR; + void *\fIsrc\fR; + void *\fIdst\fR; const char *\fIhelp\fR; } \fBTk_ArgvInfo\fR; .CE @@ -312,13 +312,13 @@ Boolean exec = FALSE; * Define option descriptions. */ Tk_ArgvInfo argTable[] = { - {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, + {"\-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag, "Turn on debugging printfs"}, - {"\-N", TK_ARGV_INT, NULL, (char *) &numReps, + {"\-N", TK_ARGV_INT, NULL, &numReps, "Number of repetitions"}, - {"\-of", TK_ARGV_STRING, NULL, (char *) &fileName, + {"\-of", TK_ARGV_STRING, NULL, &fileName, "Name of file for output"}, - {"x", TK_ARGV_REST, NULL, (char *) &exec, + {"x", TK_ARGV_REST, NULL, &exec, "File to exec, followed by any arguments (must be last argument)."}, {NULL, TK_ARGV_END, NULL, NULL, NULL} diff --git a/doc/RestrictEv.3 b/doc/RestrictEv.3 index 8b3af07..f61e764 100644 --- a/doc/RestrictEv.3 +++ b/doc/RestrictEv.3 @@ -21,9 +21,9 @@ Tk_RestrictProc * .AP Tk_RestrictProc *proc in Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. -.AP ClientData arg in +.AP void *arg in Arbitrary argument to pass to \fIproc\fR. -.AP ClientData *prevArgPtr out +.AP void **prevArgPtr out Pointer to place to save argument to previous restrict procedure. .BE .SH DESCRIPTION @@ -40,7 +40,7 @@ is a procedure with arguments and result that match the type \fBTk_RestrictProc\fR: .CS typedef Tk_RestrictAction \fBTk_RestrictProc\fR( - ClientData \fIarg\fR, + void *\fIarg\fR, XEvent *\fIeventPtr\fR); .CE The \fIarg\fR argument is a copy of the \fIarg\fR passed diff --git a/doc/SetClassProcs.3 b/doc/SetClassProcs.3 index 389d21b..d8f89a4 100644 --- a/doc/SetClassProcs.3 +++ b/doc/SetClassProcs.3 @@ -22,7 +22,7 @@ Token for window to modify. Pointer to data structure containing widget specific procedures. The data structure pointed to by \fIprocs\fR must be static: Tk keeps a reference to it as long as the window exists. -.AP ClientData instanceData in +.AP void *instanceData in Arbitrary one-word value to pass to widget callbacks. .BE .SH DESCRIPTION @@ -33,7 +33,7 @@ are used as callbacks in different places. The structure pointed to by \fIprocs\fR contains the following: .CS typedef struct Tk_ClassProcs { - unsigned int \fIsize\fR; + size_t \fIsize\fR; Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; Tk_ClassCreateProc *\fIcreateProc\fR; Tk_ClassModalProc *\fImodalProc\fR; @@ -50,7 +50,7 @@ accordingly. \fIworldChangedProc\fR should have arguments and results that match the type \fBTk_ClassWorldChangedProc\fR: .CS typedef void \fBTk_ClassWorldChangedProc\fR( - ClientData \fIinstanceData\fR); + void *\fIinstanceData\fR); .CE The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR will be identical to the \fIinstanceData\fR parameter passed to @@ -63,7 +63,7 @@ arguments and results that match the type \fBTk_ClassCreateProc\fR: typedef Window \fBTk_ClassCreateProc\fR( Tk_Window \fItkwin\fR, Window \fIparent\fR, - ClientData \fIinstanceData\fR); + void *\fIinstanceData\fR); .CE The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to the \fItkwin\fR and \fIinstanceData\fR parameters passed to diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index c989821..cbbe648 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options +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 @@ -35,9 +35,6 @@ Tcl_Obj * \fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR .sp \fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_Offset(\fItype, field\fB)\fR .SH ARGUMENTS .AS Tk_SavedOptions "*const objv[]" in/out .AP Tcl_Interp *interp in @@ -52,7 +49,7 @@ pointed to by this argument must exist for the lifetime of the Tk_OptionTable. .AP Tk_OptionTable optionTable in Token for an option table. Must have been returned by a previous call to \fBTk_CreateOptionTable\fR. -.AP char *recordPtr in/out +.AP void *recordPtr in/out Points to structure in which values of configuration options are stored; fields of this record are modified by procedures such as \fBTk_SetOptions\fR and read by procedures such as \fBTk_GetOptionValue\fR. @@ -239,12 +236,6 @@ is returned and an error message is left in \fIinterp\fR's result unless \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. It frees all of the resources associated with any of the configuration options defined in \fIrecordPtr\fR by \fIoptionTable\fR. -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating the -\fIobjOffset\fR and \fIinternalOffset\fR values for entries in -Tk_OptionSpec structures. It takes two arguments: the name of a type -of record, and the name of a field in that record. It returns the byte -offset of the named field in records of the given type. .SH "TEMPLATES" .PP The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR @@ -258,8 +249,8 @@ typedef struct { const char *\fIdbName\fR; const char *\fIdbClass\fR; const char *\fIdefValue\fR; - int \fIobjOffset\fR; - int \fIinternalOffset\fR; + size_t \fIobjOffset\fR; + size_t \fIinternalOffset\fR; int \fIflags\fR; const void *\fIclientData\fR; int \fItypeMask\fR; @@ -281,7 +272,7 @@ value is specified in the option database. The \fIobjOffset\fR and \fIinternalOffset\fR fields indicate where to store the value of this option in widget records (more on this below); values for the \fIobjOffset\fR and \fIinternalOffset\fR fields should always be generated with the -\fBTk_Offset\fR macro. +\fBoffsetof\fR macro. The \fIflags\fR field contains additional information to control the processing of this configuration option (see below for details). @@ -329,6 +320,20 @@ If this bit is set for an option then no default value will be set in 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. +.TP +\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. +.TP +\fBTK_OPTION_VAR(type)\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(Tcl_Size)\fR +with \fBTK_OPTION_INT\fR .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The @@ -342,7 +347,9 @@ nor \fIclientData\fR. \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. +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. .TP \fBTK_OPTION_BITMAP\fR The value must be a standard Tk bitmap name. The internal form is a @@ -352,7 +359,11 @@ such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .TP \fBTK_OPTION_BOOLEAN\fR The value must be a standard boolean value such as \fBtrue\fR or -\fBno\fR. The internal form is an integer with value 0 or 1. +\fBno\fR. The internal form is an integer with value 0 or 1. Note: if the +\fIobjOffset\fR field is not used then 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. .TP \fBTK_OPTION_BORDER\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. @@ -386,7 +397,7 @@ option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. The string value must be a floating-point number in the format accepted by \fBstrtol\fR. The internal form is a C \fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR -flag; if a NULL value is set, the internal representation is set to zero. +flag; if a NULL value is set, the internal representation is set to NaN. .TP \fBTK_OPTION_END\fR Marks the end of the template. There must be a Tk_OptionSpec structure @@ -408,12 +419,24 @@ such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. 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. +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. +.TP +\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. .TP \fBTK_OPTION_JUSTIFY\fR The value must be a standard justification value such as \fBleft\fR. The internal form is a Tk_Justify like the values returned by -\fBTk_GetJustifyFromObj\fR. +\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. .TP \fBTK_OPTION_PIXELS\fR The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. @@ -423,7 +446,7 @@ distance in pixels, like the values returned by used then information about the original value of this option will be lost. See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the -internal representation is set to zero. +internal representation is set to INT_MIN. .TP \fBTK_OPTION_RELIEF\fR The value must be standard relief such as \fBraised\fR. @@ -513,6 +536,10 @@ 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. +.PP +Ttk widgets do not support the \fIinternalOffset\fR machinery. +Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that +the \fIobjOffset\fR field must be used. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with @@ -526,11 +553,11 @@ typedef struct Tk_ObjCustomOption { Tk_CustomOptionGetProc *\fIgetProc\fR; Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; Tk_CustomOptionFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; } \fBTk_ObjCustomOption\fR; typedef int \fBTk_CustomOptionSetProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj **\fIvaluePtr\fR, @@ -540,19 +567,19 @@ typedef int \fBTk_CustomOptionSetProc\fR( int \fIflags\fR); typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIrecordPtr\fR, int \fIinternalOffset\fR); typedef void \fBTk_CustomOptionRestoreProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR, char *\fIsaveInternalPtr\fR); typedef void \fBTk_CustomOptionFreeProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR); .CE diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 index 5729a44..ab73d12 100644 --- a/doc/TextLayout.3 +++ b/doc/TextLayout.3 @@ -51,7 +51,7 @@ stored in the text layout. The \fIstring\fR must remain valid for the lifetime of the text layout. .AP int numChars in The number of characters to consider from \fIstring\fR. If -\fInumChars\fR is less than 0, then assumes \fIstring\fR is null +\fInumChars\fR is negative, then assumes \fIstring\fR is null terminated and uses \fBTcl_NumUtfChars\fR to determine the length of \fIstring\fR. .AP int wrapLength in @@ -108,8 +108,9 @@ The index of the last character up to which to draw. The character specified by \fIlastChar\fR itself will not be drawn. A number less than 0 means to draw all characters in the text layout. .AP int underline in -Index of the single character to underline in the text layout, or a number -less than 0 for no underline. +Index of the single character to underline in the text layout, or a +negative number counting backwards from the end of the string. Any +out-of-range number (e.g. INT_MIN) means no underline. .AP int index in The index of the character whose bounding box is desired. The bounding box is computed with respect to the upper-left hand corner of the text layout. @@ -178,7 +179,7 @@ located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be considered closest to the first character in the text layout; any point whose \fIy\fR-value is greater than the height of the text layout will be considered closest to the last character in the text layout. Any point -whose \fIx\fR-value is less than 0 will be considered closest to the first +whose \fIx\fR-value is negative will be considered closest to the first character on that line; any point whose \fIx\fR-value is greater than the width of the text layout will be considered closest to the last character on that line. The return value is the index of the character that was closest diff --git a/doc/WinUtil.3 b/doc/WinUtil.3 new file mode 100644 index 0000000..253ed19 --- /dev/null +++ b/doc/WinUtil.3 @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures" +.so man.macros +.BS +.SH NAME +Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_GetOtherWindow(\fItkwin\fB)\fR +.sp +\fBTk_MakeContainer(\fItkwin\fB)\fR +.sp +\fBTk_MakeWindow(\fItkwin, parent\fB)\fR +.sp +int +\fBTk_UseWindow(\fIinterp, tkwin, string\fB)\fR +.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 +Parent window. +.AP "const char" *string in +String identifying an X window to use for \fItkwin\fR; must be an integer value. +.BE +.SH DESCRIPTION +.PP +If both the container and embedded window are in the same process, +\fBTk_GetOtherWindow\fR will return either one, given the other. +If winPtr is a container, the return value is the token for the +embedded window, and vice versa. If the "other" window isn't in this +process, NULL is returned. +.PP +\fBTk_MakeContainer\fR is called to indicate that a particular window will be a +container for an embedded application. This changes certain aspects of +the window's behavior, such as whether it will receive events anymore. +.PP +\fBTk_MakeWindow\fR creates an actual window system window object based on the +current attributes of the specified TkWindow. It returns the handle to the new +window, or None on failure. +.PP +\fBTk_UseWindow\fR causes a Tk window to use a given X window as its +parent window, rather than the root window for the screen. It is +invoked by an embedded application to specify the window in which it +is embedded. +.PP +The return value is normally TCL_OK. If an error occurs (such as +string not being a valid window spec), then the return value is +TCL_ERROR and an error message is left in the interp's result if +interp is non-NULL. +.PP +.SH KEYWORDS +parent, window diff --git a/doc/WindowId.3 b/doc/WindowId.3 index f937963..477efe1 100644 --- a/doc/WindowId.3 +++ b/doc/WindowId.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap, Tk_Interp \- retrieve information from Tk's local data structure +Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_AlwaysShowSelection, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap, Tk_Interp, Tk_NewWindowObj \- retrieve information from Tk's local data structure .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -29,6 +29,9 @@ const char * int \fBTk_ScreenNumber\fR(\fItkwin\fR) .sp +int +\fBTk_AlwaysShowSelection\fR(\fItkwin\fR) +.sp Screen * \fBTk_Screen\fR(\fItkwin\fR) .sp @@ -97,6 +100,9 @@ Colormap .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 @@ -127,6 +133,8 @@ ASCII string identifying \fItkwin\fR's display. \fBTk_ScreenNumber\fR returns the index of \fItkwin\fR's screen among all the screens of \fItkwin\fR's display. \fBTk_Screen\fR returns a pointer to the Xlib structure corresponding to \fItkwin\fR's screen. +\fBTk_AlwaysShowSelection\fR indicates whether text/entry widgets +should always display their selection, regardless of window focus. .PP \fBTk_X\fR, \fBTk_Y\fR, \fBTk_Width\fR, and \fBTk_Height\fR return information about \fItkwin's\fR location within its @@ -182,6 +190,8 @@ and \fBTk_Colormap\fR returns the current colormap for the window. The visual characteristics are normally set from the defaults for the window's screen, but they may be overridden by calling \fBTk_SetWindowVisual\fR. +.PP +\fBTk_NewWindowObj\fR creates a new \fBTcl_Obj\fR from the window. .SH KEYWORDS attributes, colormap, depth, display, height, geometry manager, identifier, mapped, requested size, screen, top-level, @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998 by Scriptics Corporation. +'\" Copyright (c) 1998 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -70,7 +70,7 @@ event pattern may take one of three forms. In the simplest case it is a single printing ASCII character, such as \fBa\fR or \fB[\fR. The character may not be a space character or the character \fB<\fR. This form of -pattern matches a \fBKeyPress\fR event for the particular +pattern matches a \fBKey\fR event for the particular character. The second form of pattern is longer but more general. It has the following syntax: .CS @@ -106,8 +106,8 @@ Modifiers consist of any of the following values: .ta 6c \fBControl\fR \fBMod1\fR, \fBM1\fR, \fBCommand\fR \fBAlt\fR \fBMod2\fR, \fBM2\fR, \fBOption\fR -\fBShift\fR \fBMod3\fR, \fBM3\fR -\fBLock\fR \fBMod4\fR, \fBM4\fR +\fBShift\fR \fBMod3\fR, \fBM3\fR, \fBNum\fR +\fBLock\fR \fBMod4\fR, \fBM4\fR, \fBFn\fR \fBExtended\fR \fBMod5\fR, \fBM5\fR \fBButton1\fR, \fBB1\fR \fBMeta\fR, \fBM\fR \fBButton2\fR, \fBB2\fR \fBDouble\fR @@ -149,8 +149,8 @@ substantial mouse motion in between. For example, \fB<Double\-Button\-1>\fR is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space requirement. .PP -The \fBCommand\fR and \fBOption\fR modifiers are equivalents of \fBMod1\fR -resp. \fBMod2\fR, they correspond to Macintosh-specific modifier keys. +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 @@ -168,16 +168,16 @@ couple non-standard X event types that were added to better support the Macintosh and Windows platforms. Below is a list of all the valid types; where two names appear together, they are synonyms. .DS -.ta \w'\fBButtonPress, Button\0\0\0\fR'u +\w'\fBKeyPress, Key\0\0\0\fR'u +.ta \w'\fBButton, ButtonPress\0\0\0\fR'u +\w'\fBKey, KeyPress\0\0\0\fR'u \fBActivate\fR \fBDestroy\fR \fBMap\fR -\fBButtonPress\fR, \fBButton\fR \fBEnter\fR \fBMapRequest\fR +\fBButton\fR, \fBButtonPress\fR \fBEnter\fR \fBMapRequest\fR \fBButtonRelease\fR \fBExpose\fR \fBMotion\fR \fBCirculate\fR \fBFocusIn\fR \fBMouseWheel\fR -\fBCirculateRequest\fR \fBFocusOut\fR \fBProperty\fR -\fBColormap\fR \fBGravity\fR \fBReparent\fR -\fBConfigure\fR \fBKeyPress\fR, \fBKey\fR \fBResizeRequest\fR -\fBConfigureRequest\fR \fBKeyRelease\fR \fBUnmap\fR -\fBCreate\fR \fBLeave\fR \fBVisibility\fR +\fBTouchpadScroll\fR \fBCirculateRequest\fR \fBFocusOut\fR +\fBProperty\fR \fBColormap\fR \fBGravity\fR +\fBReparent\fR \fBConfigure\fR \fBKey\fR, \fBKeyPress\fR +\fBResizeRequest\fR \fBConfigureRequest\fR \fBKeyRelease\fR +\fBUnmap\fR \fBCreate\fR \fBLeave\fR \fBVisibility\fR \fBDeactivate\fR .DE Most of the above events have the same fields and behaviors as events @@ -198,7 +198,7 @@ active. Likewise, the \fBDeactive\fR event is sent when the window's state changes from active to deactive. There are no useful percent substitutions you would make when binding to these events. .IP \fBMouseWheel\fR 5 -Many contemporary mice support a mouse wheel, which is used +Many contemporary mice include a mouse wheel, which is used for scrolling documents without using the scrollbars. By rolling the wheel, the system will generate \fBMouseWheel\fR events that the application can use to scroll. The event is routed to the @@ -212,31 +212,44 @@ values should scroll up and negative values should scroll down. .RS .PP Horizontal scrolling uses \fBShift-MouseWheel\fR events, with positive -\fB%D\fR \fIdelta\fR substitution indicating left scrolling and negative -right scrolling. -Only Windows and macOS Aqua typically fire \fBMouseWheel\fR and -\fBShift-MouseWheel\fR events. On -X11 vertical scrolling is rather supported through \fBButton-4\fR and -\fBButton-5\fR events, and horizontal scrolling through \fBShift-Button-4\fR -and \fBShift-Button-5\fR events. Horizontal scrolling events may fire from -many different hardware units such as tilt wheels or touchpads. Horizontal -scrolling can also be emulated by holding Shift and scrolling vertically. +\fB%D\fR \fIdelta\fR substitution indicating left scrolling and +negative right scrolling. Horizontal scrolling events are generated +tilt wheels on some mice. Horizontal scrolling can also be emulated +by holding Shift and scrolling vertically. .RE +.IP "\fBTouchpadScroll\fR" 5 +On some platforms (currently Windows and macOS) there is support for +high-resolution scrolling devices, such as touchpads. This is +provided via \fBTouchpadScroll\fR events. These events store two +16 bit delta values in the integer provided by the \fB%D\fR +substitution. The \fIX\fR delta is in the high order 16 bits and the +\fIY\fR delta is in the low order 16 bits. These values can be +unpacked by using the tk::PreciseScrollDeltas utility procedure. For +example: +.CS +lassign [tk::PreciseScrollDeltas %D] deltaX deltaY +.CE +The \fB$#\fR substitution is a counter for \fBTouchpadScroll\fR events +which can be used by widgets that only support scrolling by units to +ignore some portion of the events. .IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5 The \fBKeyPress\fR and \fBKeyRelease\fR events are generated whenever a key is pressed or released. \fBKeyPress\fR and \fBKeyRelease\fR +.IP "\fBKey\fR, \fBKeyRelease\fR" 5 +The \fBKey\fR and \fBKeyRelease\fR events are generated +whenever a key is pressed or released. \fBKey\fR and \fBKeyRelease\fR events are sent to the window which currently has the keyboard focus. -.IP "\fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR" 5 -The \fBButtonPress\fR and \fBButtonRelease\fR events +.IP "\fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR" 5 +The \fBButton\fR and \fBButtonRelease\fR events are generated when the user presses or releases a mouse button. \fBMotion\fR events are generated whenever the pointer is moved. -\fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR events are +\fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events are normally sent to the window containing the pointer. .RS .PP When a mouse button is pressed, the window containing the pointer automatically obtains a temporary pointer grab. -Subsequent \fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR +Subsequent \fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events will be sent to that window, regardless of which window contains the pointer, until all buttons have been released. @@ -365,8 +378,8 @@ position in the stacking order. .SS "EVENT DETAILS" .PP The last part of a long event specification is \fIdetail\fR. In the -case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the -number of a button (1\-5). If a button number is given, then only an +case of a \fBButton\fR or \fBButtonRelease\fR event, it is the +number of a button (1\-9). If a button number is given, then only an event on that particular button will match; if no button number is given, then an event on any button will match. Note: giving a specific button number is different than specifying a button modifier; @@ -374,10 +387,10 @@ in the first case, it refers to a button being pressed or released, while in the second it refers to some other button that is already depressed when the matching event occurs. If a button number is given then \fItype\fR may be omitted: if will default -to \fBButtonPress\fR. For example, the specifier \fB<1>\fR -is equivalent to \fB<ButtonPress\-1>\fR. +to \fBButton\fR. For example, the specifier \fB<1>\fR +is equivalent to \fB<Button\-1>\fR. .PP -If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then +If the event type is \fBKey\fR or \fBKeyRelease\fR, then \fIdetail\fR may be specified in the form of an X keysym. Keysyms are textual specifications for particular keys on the keyboard; they include all the alphanumeric ASCII characters (e.g. @@ -397,9 +410,9 @@ system. If necessary, you can use the \fB%K\fR notation described below to print out the keysym name for a particular key. If a keysym \fIdetail\fR is given, then the -\fItype\fR field may be omitted; it will default to \fBKeyPress\fR. +\fItype\fR field may be omitted; it will default to \fBKey\fR. For example, \fB<Control\-comma>\fR is equivalent to -\fB<Control\-KeyPress\-comma>\fR. +\fB<Control\-Key\-comma>\fR. .SH "BINDING SCRIPTS AND SUBSTITUTIONS" .PP The \fIscript\fR argument to \fBbind\fR is a Tcl script, called the @@ -435,7 +448,7 @@ in the stacking order, or \fB0\fR if the receiving window is at the bottom. .IP \fB%b\fR 5 The number of the button that was pressed or released. Valid only -for \fBButtonPress\fR and \fBButtonRelease\fR events. +for \fBButton\fR and \fBButtonRelease\fR events. .IP \fB%c\fR 5 The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. Indicates that there are \fIcount\fR pending \fBExpose\fR events which have not @@ -482,7 +495,7 @@ Indicates the new or requested height of the window. The \fIwindow\fR field from the event, represented as a hexadecimal integer. Valid for all event types. .IP \fB%k\fR 5 -The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR +The \fIkeycode\fR field from the event. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%m\fR 5 The \fImode\fR field from the event. The substituted string is one of @@ -497,8 +510,8 @@ The \fIplace\fR field from the event, substituted as one of the strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only for \fBCirculate\fR and \fBCirculateRequest\fR events. .IP \fB%s\fR 5 -The \fIstate\fR field from the event. For \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR, +The \fIstate\fR field from the event. For \fBButton\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBKey\fR, \fBKeyRelease\fR, \fBLeave\fR, and \fBMotion\fR events, a decimal string is substituted. For \fBVisibility\fR, one of the strings \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, @@ -520,8 +533,8 @@ Valid only for \fBResizeRequest\fR, and \fBExpose\fR events. .IP "\fB%x\fR, \fB%y\fR" 5 The \fIx\fR and \fIy\fR fields from the event. -For \fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR, -\fBKeyPress\fR, \fBKeyRelease\fR, and \fBMouseWheel\fR events, +For \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, +\fBKey\fR, \fBKeyRelease\fR, and \fBMouseWheel\fR events, \fB%x\fR and \fB%y\fR indicate the position of the mouse pointer relative to the receiving window. For key events on the Macintosh these are the coordinates of the @@ -537,8 +550,8 @@ the empty string if the event does not correspond to a UNICODE character (e.g. the shift key was pressed). On X11, \fBXmbLookupString\fR (or \fBXLookupString\fR when input method support is turned off) does all the work of translating from the event to a UNICODE character. -On X11, valid only for \fBKeyPress\fR event. On Windows and macOS/aqua, -valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +On X11, valid only for \fBKey\fR event. On Windows and macOS/aqua, +valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%B\fR 5 The \fIborder_width\fR field from the event. Valid only for \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events. @@ -556,13 +569,13 @@ event, \fB1\fR indicates that it is a event generated by \fBSendEvent\fR. .IP \fB%K\fR 5 The keysym corresponding to the event, substituted as a textual -string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +string. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%M\fR 5 The number of script-based binding patterns matched so far for the event. Valid for all event types. .IP \fB%N\fR 5 The keysym corresponding to the event, substituted as a decimal -number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +number. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%P\fR 5 The name of the property being updated or deleted (which may be converted to an XAtom using \fBwinfo atom\fR.) Valid @@ -584,7 +597,7 @@ The \fIx_root\fR and \fIy_root\fR fields from the event. If a virtual-root window manager is being used then the substituted values are the corresponding x-coordinate and y-coordinate in the virtual root. Valid only for -\fBButtonPress\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, +\fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBKey\fR, \fBKeyRelease\fR, \fBLeave\fR and \fBMotion\fR events. Same meaning as \fB%x\fR and \fB%y\fR, except relative to the (virtual) root window. @@ -651,8 +664,9 @@ several matching sequences is more specific: an event pattern that specifies a specific button or key is more specific than one that does not; .IP (b) -a longer sequence (in terms of number -of events matched) is more specific than a shorter sequence; +a sequence with the most highest-ordered patterns (in term of highest +repetition count) is more specific than a sequence with less +highest-ordered patterns; .IP (c) if the modifiers specified in one pattern are a subset of the modifiers in another pattern, then the pattern with more modifiers @@ -696,17 +710,17 @@ When a \fIsequence\fR specified in a \fBbind\fR command contains more than one event pattern, then its script is executed whenever the recent events (leading up to and including the current event) match the given sequence. This means, for example, that if button 1 is -clicked repeatedly the sequence \fB<Double\-ButtonPress\-1>\fR will match +clicked repeatedly the sequence \fB<Double\-Button\-1>\fR will match each button press but the first. If extraneous events that would prevent a match occur in the middle of an event sequence then the extraneous events are -ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events. -For example, \fB<Double\-ButtonPress\-1>\fR will match a sequence of +ignored unless they are \fBKey\fR or \fBButton\fR events. +For example, \fB<Double\-Button\-1>\fR will match a sequence of presses of button 1, even though there will be \fBButtonRelease\fR events (and possibly \fBMotion\fR events) between the -\fBButtonPress\fR events. -Furthermore, a \fBKeyPress\fR event may be preceded by any number -of other \fBKeyPress\fR events for modifier keys without the +\fBButton\fR events. +Furthermore, a \fBKey\fR event may be preceded by any number +of other \fBKey\fR events for modifier keys without the modifier keys preventing a match. For example, the event sequence \fBaB\fR will match a press of the \fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR diff --git a/doc/bitmap.n b/doc/bitmap.n index 1751913..19716e1 100644 --- a/doc/bitmap.n +++ b/doc/bitmap.n @@ -90,7 +90,7 @@ This command may be used to invoke various operations on the image. It has the following general form: .CS -\fIimageName option \fR?\fIarg arg ...\fR? +\fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following @@ -28,10 +28,12 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -busy \- confine pointer events to a window sub-tree +busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS \fBtk busy\fR \fIwindow \fR?\fIoptions\fR? .sp +\fBtk busy busywindow \fIwindow\fR +.sp \fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR? .sp \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... @@ -44,8 +46,8 @@ busy \- confine pointer events to a window sub-tree .BE .SH DESCRIPTION .PP -The \fBtk busy\fR command provides a simple means to block pointer events from -Tk widgets, while overriding the widget's cursor with a configurable busy +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. .SH INTRODUCTION @@ -128,24 +130,11 @@ The following operations are available for the \fBtk busy\fR command: . Shortcut for \fBtk busy hold\fR command. .TP -\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... +\fBtk busy busywindow \fIwindow\fR . -Makes the specified \fIwindow\fR (and its descendants in the Tk window -hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. -A transparent window is put in front of the specified window. This transparent -window is mapped the next time idle tasks are processed, and the specified -window and its descendants will be blocked from user interactions. Normally -\fBupdate\fR should be called immediately afterward to insure that the hold -operation is in effect before the application starts its processing. The -following configuration options are valid: -.RS -.TP -\fB\-cursor \fIcursorName\fR -. -Specifies the cursor to be displayed when the widget is made busy. -\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The -default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. -.RE +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. .TP \fBtk busy cget \fIwindow\fR \fIoption\fR . @@ -181,6 +170,12 @@ 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, @@ -189,11 +184,26 @@ including the transparent window. User events will again be received by \fIWindow\fR must be the name of a widget specified in the \fBhold\fR operation, otherwise an error is reported. .TP -\fBtk busy current \fR?\fIpattern\fR? +\fBtk busy hold \fIwindow\fR ?\fIoption value\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. +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 . @@ -206,32 +216,18 @@ The event blocking feature is implemented by creating and mapping a transparent window that completely covers the widget. When the busy window is mapped, it invisibly shields the widget and its hierarchy from all events that may be sent. Like Tk widgets, busy windows have widget names in the Tk window -hierarchy. This means that you can use the \fBbind\fR command, to handle -events in the busy window. +hierarchy. This means that you can use the \fBbind\fR command to handle +events in the busy window: .PP .CS \fBtk busy\fR hold .frame.canvas -bind .frame.canvas_Busy <Enter> { ... } +bind [\fBtk busy\fR busywindow .frame.canvas] <Enter> { ... } .CE .PP -Normally the busy window is a sibling of the widget. The name of the busy -window is -.QW \fIwidget\fB_Busy\fR -where \fIwidget\fR is the name of the widget to be made busy. In the previous -example, the pathname of the busy window is -.QW \fB.frame.canvas_Busy\fR . -The exception is when the widget is a toplevel widget (such as -.QW . ) -where the busy window can't be made a sibling. The busy window is then a child -of the widget named -.QW \fIwidget\fB._Busy\fR -where \fIwidget\fR is the name of the toplevel widget. In the following -example, the pathname of the busy window is -.QW \fB._Busy\fR . -.PP +or .CS -\fBtk busy\fR hold . -bind ._Busy <Enter> { ... } +set busyWin [\fBtk busy\fR hold .frame.canvas] +bind $busyWin <Enter> { ... } .CE .SS "ENTER/LEAVE EVENTS" .PP diff --git a/doc/button.n b/doc/button.n index 233feb6..70e0e65 100644 --- a/doc/button.n +++ b/doc/button.n @@ -109,7 +109,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/canvas.n b/doc/canvas.n index a64aebe..bffa48e 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -67,7 +67,7 @@ the canvas x coordinate at the left edge of the window is always an even multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be \fBxScrollIncrement\fR. If the value of -this option is less than or equal to zero, then horizontal scrolling +this option is negative or zero, then horizontal scrolling is unconstrained. .OP \-yscrollincrement yScrollIncrement ScrollIncrement Specifies an increment for vertical scrolling, in any of the usual forms @@ -77,7 +77,7 @@ the canvas y coordinate at the top edge of the window is always an even multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be \fByScrollIncrement\fR. If the value of -this option is less than or equal to zero, then vertical scrolling +this option is negative or zero, then vertical scrolling is unconstrained. .BE .SH INTRODUCTION @@ -220,8 +220,12 @@ for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. .PP -Individual items may be moved or scaled using widget commands -described below, but they may not be rotated. +Individual items may be moved, scaled +.VS "8.7, TIP164" +or rotated +.VE "8.7, TIP164" +using widget commands +described below. .PP Note that the default origin of the canvas's visible area is coincident with the origin for the whole window as that makes bindings @@ -260,10 +264,10 @@ 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 +A negative number 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 +polygons, negative numbers or numbers 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. @@ -313,6 +317,7 @@ The second possible syntax is a character list containing only The space can be used to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples: +.PP .CS \-dash . \(-> \-dash {2 4} \-dash - \(-> \-dash {6 4} @@ -343,13 +348,13 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName 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 arg ...\fR? +\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR? . For each item that meets the constraints specified by \fIsearchSpec\fR and the \fIarg\fRs, add @@ -465,7 +470,7 @@ defined for \fItagOrId\fR. .PP The only events for which bindings may be specified are those related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, -\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. +\fBButton\fR, \fBMotion\fR, and \fBKey\fR) or virtual events. The handling of events in canvases uses the current item defined in \fBITEM IDS AND TAGS\fR above. \fBEnter\fR and \fBLeave\fR events trigger for an @@ -597,7 +602,7 @@ the item is unaffected by the command. If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. This command returns an empty string. .TP -\fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR? +\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 @@ -658,14 +663,27 @@ command, above), but the cursor position may be set even when the item does not have the focus. This command returns an empty string. .TP +\fIpathName \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. 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. +This command returns an empty string. +.TP \fIpathName \fBimove \fItagOrId index x y\fR -.VS 8.6 +. This command causes the \fIindex\fR'th coordinate of each of the items indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). Each item interprets \fIindex\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. -.VE 8.6 .TP \fIpathName \fBindex \fItagOrId index\fR . @@ -751,7 +769,7 @@ each point associated with the item. This command returns an empty string. .TP \fIpathName \fBmoveto \fItagOrId xPos yPos\fR -.VS 8.6 +. Move the items given by \fItagOrId\fR in the canvas coordinate space so that the first coordinate pair (the upper-left corner of the bounding box) of the first item (the lowest in the display list) with @@ -761,7 +779,6 @@ the empty string, in which case the corresponding coordinate will be unchanged. All items matching \fItagOrId\fR remain in the same positions relative to each other. This command returns an empty string. -.VE 8.6 .TP \fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? . @@ -947,7 +964,7 @@ determined by the \fBraise\fR command and \fBlower\fR command, not the .RE .TP \fIpathName \fBrchars \fItagOrId first last string\fR -.VS 8.6 +. This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR for each of the items indicated by \fItagOrId\fR to be replaced by \fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently @@ -956,7 +973,27 @@ set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case \fIstring\fR should be a list of coordinates to use as a replacement). The other items ignore this operation. -.VE 8.6 +.TP +\fIpathName \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 +anticlockwise, in degrees. (Negative values rotate clockwise.) +This command returns an empty string. +.RS +.PP +Implementation note: not all item types work the same with rotations. In +particular,\fB bitmap\fR,\fB image\fR,\fB text\fR and\fB window\fR items only +rotate their anchor points and do not rotate the items themselves about those +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 . @@ -1110,17 +1147,18 @@ total width of the canvas is off-screen to the left. . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +\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 \fBunits\fR, the view adjusts left or right in units -of the \fBxScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. If \fIwhat is \fBpages\fR then the view adjusts in units of nine-tenths the window's width. If \fInumber\fR is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. +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? @@ -1151,16 +1189,17 @@ area is off-screen to the top. . This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units -of the \fByScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. +\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. If \fIwhat\fR is \fBpages\fR then the view adjusts in units of nine-tenths the window's height. If \fInumber\fR is negative then higher information becomes visible; if it is positive then lower information becomes visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units +of the \fByScrollIncrement\fR option, if it is greater than zero, +or in units of one-tenth the window's height otherwise. .RE .SH "OVERVIEW OF ITEM TYPES" .PP @@ -1325,8 +1364,8 @@ arc's region. .PP Items of type \fBarc\fR appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified -by the \fB\-start\fR and \fB\-extent\fR options) and displayed in -one of several ways (specified by the \fB\-style\fR option). +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? @@ -1334,7 +1373,9 @@ Arcs are created with widget commands of the following form: .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval that defines the arc. +rectangular region enclosing the oval that defines the arc (except when +\fB\-height\fR is specified - see below). +. 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 @@ -1375,6 +1416,34 @@ 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 +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 +.br +\fIdistance\fR = 0 creates an arc as if this option had not been specified +.RE +.PP +If you want the arc to have a specific radius, \fIr\fR, use the formula: +.PP +.RS +\fIdistance\fR = \fIr\fR \(+- sqrt(\fIr\fR**2 - (chordLength / 2)**2) +.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 @@ -1796,13 +1865,12 @@ The following standard options are supported by text items: The following extra options are supported for text items: .TP \fB\-angle \fIrotationDegrees\fR -.VS 8.6 +. \fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise about the positioning point for the text; it may have any floating-point value from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the text will be drawn vertically from bottom to top. This option defaults to \fB0.0\fR. -.VE 8.6 .TP \fB\-font \fIfontName\fR Specifies the font to use for the text item. diff --git a/doc/checkbutton.n b/doc/checkbutton.n index bfefca4..411045f 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.n @@ -192,7 +192,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index e441d78..a5b30f5 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" diff --git a/doc/clipboard.n b/doc/clipboard.n index 6f047dd..ee964df 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.n @@ -12,7 +12,7 @@ .SH NAME clipboard \- Manipulate Tk clipboard .SH SYNOPSIS -\fBclipboard \fIoption\fR ?\fIarg arg ...\fR? +\fBclipboard \fIoption\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/colors.n b/doc/colors.n index 3747ee8..9c64b1d 100644 --- a/doc/colors.n +++ b/doc/colors.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" Copyright (c) 2003 ActiveState Corporation. '\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net> '\" Copyright (c) 2008 Donal K. Fellows @@ -919,19 +919,20 @@ On Windows, the following additional system colors are available .RS .DS .ta 6c -system3dDarkShadow systemHighlight -system3dLight systemHighlightText -systemActiveBorder systemInactiveBorder -systemActiveCaption systemInactiveCaption -systemAppWorkspace systemInactiveCaptionText -systemBackground systemInfoBackground -systemButtonFace systemInfoText -systemButtonHighlight systemMenu -systemButtonShadow systemMenuText +system3dDarkShadow systemHighlightText +system3dLight systemInactiveBorder +systemActiveBorder systemInactiveCaption +systemActiveCaption systemInactiveCaptionText +systemAppWorkspace systemInfoBackground +systemBackground systemInfoText +systemButtonFace systemMenu +systemButtonHighlight systemMenuText +systemButtonShadow systemPlaceholderText systemButtonText systemScrollbar systemCaptionText systemWindow systemDisabledText systemWindowFrame systemGrayText systemWindowText +systemHighlight .DE .RE .SH "SEE ALSO" diff --git a/doc/console.n b/doc/console.n index 40b7426..0a9a794 100644 --- a/doc/console.n +++ b/doc/console.n @@ -23,7 +23,7 @@ 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" , +.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 diff --git a/doc/cursors.n b/doc/cursors.n index a728755..bf8a05e 100644 --- a/doc/cursors.n +++ b/doc/cursors.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" '\" Copyright (c) 2006-2007 Daniel A. Steffen <das@users.sourceforge.net> diff --git a/doc/dialog.n b/doc/dialog.n index e4938d2..4245810 100644 --- a/doc/dialog.n +++ b/doc/dialog.n @@ -40,7 +40,7 @@ If this is an empty string then no bitmap is displayed in the dialog. If this is an integer greater than or equal to zero, then it gives the index of the button that is to be the default button for the dialog (0 for the leftmost button, and so on). -If less than zero or an empty string then there will not be any default +If negative or an empty string then there will not be any default button. .TP \fIstring\fR diff --git a/doc/entry.n b/doc/entry.n index 713929b..850932c 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -23,6 +23,7 @@ entry \- Create and manipulate 'entry' one-line text entry widgets \-foreground \-insertwidth \-xscrollcommand \-highlightbackground \-justify \-highlightcolor \-relief +\-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-disabledbackground disabledBackground DisabledBackground @@ -76,7 +77,7 @@ See \fBVALIDATION\fR below for more information. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a +If the value is negative or zero, the widget picks a size just large enough to hold its current text. .BE .SH DESCRIPTION @@ -189,7 +190,7 @@ The \fBentry\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName subcommand \fR?\fIarg arg ...\fR? +\fIpathName subcommand \fR?\fIarg ...\fR? .CE \fISubcommand\fR and the \fIarg\fRs determine the exact behavior of the command. @@ -238,6 +239,9 @@ 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: @@ -402,15 +406,16 @@ way through the text appears at the left edge of the window. \fIpathName \fBxview scroll \fInumber what\fR This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +\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 \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then characters farther to the left become +visible; if it is positive then characters farther to the right become visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display. .RE .SH "DEFAULT BINDINGS" .PP diff --git a/doc/event.n b/doc/event.n index afb5e4c..9f5a4c6 100644 --- a/doc/event.n +++ b/doc/event.n @@ -12,7 +12,7 @@ .SH NAME event \- Miscellaneous event facilities: define virtual events and generate events .SH SYNOPSIS -\fBevent\fI option \fR?\fIarg arg ...\fR? +\fBevent\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -100,7 +100,7 @@ Corresponds to the \fB%B\fR substitution for binding scripts. .TP \fB\-button\fI number\fR \fINumber\fR must be an integer; it specifies the \fIdetail\fR field -for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding +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. .TP @@ -155,7 +155,7 @@ Corresponds to the \fB%h\fR substitution for binding scripts. \fB\-keycode\fI number\fR \fINumber\fR must be an integer; it specifies the \fIkeycode\fR field for the event. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. +Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%k\fR substitution for binding scripts. .TP \fB\-keysym\fI name\fR @@ -163,7 +163,7 @@ Corresponds to the \fB%k\fR substitution for binding scripts. \fBspace\fR, or \fBReturn\fR; its corresponding keycode value is used as the \fIkeycode\fR field for event, overriding any detail specified in the base \fIevent\fR argument. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. +Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%K\fR substitution for binding scripts. .TP \fB\-mode\fI notify\fR @@ -189,7 +189,7 @@ Corresponds to the \fB%p\fR substitution for binding scripts. \fB\-root\fI window\fR \fIWindow\fR must be either a window path name or an integer window identifier; it specifies the \fIroot\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. @@ -197,14 +197,14 @@ Corresponds to the \fB%R\fR substitution for binding scripts. \fB\-rootx\fI coord\fR \fICoord\fR must be a screen distance; it specifies the \fIx_root\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. .TP \fB\-rooty\fI coord\fR \fICoord\fR must be a screen distance; it specifies the \fIy_root\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. @@ -221,7 +221,7 @@ Corresponds to the \fB%#\fR substitution for binding scripts. .TP \fB\-state\fI state\fR \fIState\fR specifies the \fIstate\fR field for the event. -For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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, @@ -233,7 +233,7 @@ Corresponds to the \fB%s\fR substitution for binding scripts. \fB\-subwindow\fI window\fR \fIWindow\fR specifies the \fIsubwindow\fR field for the event, either as a path name for a Tk widget or as an integer window identifier. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. .TP @@ -241,7 +241,7 @@ Similar to \fB%S\fR substitution for binding scripts. \fIInteger\fR must be an integer value; it specifies the \fItime\fR field for the event. Additonally the special value \fBcurrent\fR is allowed, this value will be substituted by the current event time. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. @@ -249,7 +249,7 @@ Corresponds to the \fB%t\fR substitution for binding scripts. \fB\-warp\fI boolean\fR \fIboolean\fR must be a boolean value; it specifies whether the screen pointer should be warped as well. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. .TP @@ -282,7 +282,7 @@ be processed in order but at the front of the queue. \fB\-x\fI coord\fR \fICoord\fR must be a screen distance; it specifies the \fIx\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. @@ -294,7 +294,7 @@ for binding scripts. \fB\-y\fI coord\fR \fICoord\fR must be a screen distance; it specifies the \fIy\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +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. @@ -577,7 +577,7 @@ Starting from the preceding example, if the following code is executed: .PP .CS bind Entry <Control-y> {} -\fBevent add\fR <<Paste>> <Key-F6> +\fBevent add\fR <<Paste>> <F6> .CE .PP the behavior will change such in two ways. First, the shadowed diff --git a/doc/focus.n b/doc/focus.n index e3efcd3..a6b0575 100644 --- a/doc/focus.n +++ b/doc/focus.n @@ -15,7 +15,7 @@ focus \- Manage the input focus .nf \fBfocus\fR \fBfocus \fIwindow\fR -\fBfocus \fIoption\fR ?\fIarg arg ...\fR? +\fBfocus \fIoption\fR ?\fIarg ...\fR? .fi .BE .SH DESCRIPTION @@ -12,7 +12,7 @@ .SH NAME font \- Create and inspect fonts. .SH SYNOPSIS -\fBfont\fI option \fR?\fIarg arg ...\fR? +\fBfont\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/fontchooser.n b/doc/fontchooser.n index 65aa8e7..465af2e 100644 --- a/doc/fontchooser.n +++ b/doc/fontchooser.n @@ -11,7 +11,7 @@ .SH NAME fontchooser \- control font selection dialog .SH SYNOPSIS -\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR? +\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR? .sp \fBtk fontchooser\fR \fBshow\fR .sp @@ -31,7 +31,7 @@ caller via callbacks or virtual events. .PP The \fBtk fontchooser\fR command can have one of the following forms: .TP -\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR? +\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). diff --git a/doc/frame.n b/doc/frame.n index 4800461..97ff3b1 100644 --- a/doc/frame.n +++ b/doc/frame.n @@ -25,6 +25,16 @@ except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. +.VS "8.7, TIP262" +An empty background will disable drawing the background image. +.OP \-backgroundimage backgroundImage BackgroundImage +This specifies an image to display on the frame's background within +the border of the frame (i.e., the image will be clipped by the +frame's highlight ring and border, if either are present); subwidgets +of the frame will be drawn on top. The image must have been created +with the \fBimage create\fR command. If specified as the empty string, +no image will be displayed. +.VE "8.7, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for @@ -56,12 +66,21 @@ Note that \fB\-borderwidth\fR, \fB\-padx\fR and \fB\-pady\fR are ignored when configured as a container since a container has no border. .OP \-height height Height Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. If this option is less than or equal -to zero then the window will not request any size at all. Note that this +acceptable to \fBTk_GetPixels\fR. If this option is negative or +zero then the window will not request any size at all. Note that this sets the total height of the frame, any \fB\-borderwidth\fR or similar is not added. Normally \fB\-height\fR should not be used if a propagating geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the frame since the geometry manager will override the height of the frame. +.OP \-tile tile Tile +.VS "8.7, TIP262" +This specifies how to draw the background image (see +\fB\-backgroundimage\fR) on the frame. +If true (according to \fBTcl_GetBoolean\fR), the image will be tiled +to fill the whole frame, with the origin of the first copy of the +image being the top left of the interior of the frame. +If false (the default), the image will be centered within the frame. +.VE "8.7, TIP262" .OP \-visual visual Visual Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. @@ -71,8 +90,8 @@ The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. If this option is less than or equal -to zero then the window will not request any size at all. Note that this +acceptable to \fBTk_GetPixels\fR. If this option is negative or +zero then the window will not request any size at all. Note that this sets the total width of the frame, any \fB\-borderwidth\fR or similar is not added. Normally \fB\-width\fR should not be used if a propagating geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the @@ -91,7 +110,7 @@ path name of the new window. .PP A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. The only features -of a frame are its background color and an optional 3-D border to make the +of a frame are its background and an optional 3-D border to make the frame appear raised or sunken. .SH "WIDGET COMMAND" .PP @@ -101,7 +120,7 @@ command may be used to invoke various operations on the widget. It has the following general form: .PP .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as @@ -14,7 +14,7 @@ grab \- Confine pointer and keyboard events to a window sub-tree .SH SYNOPSIS \fBgrab \fR?\fB\-global\fR? \fIwindow\fR .sp -\fBgrab \fIoption \fR?\fIarg arg \fR...? +\fBgrab \fIoption \fR?\fIarg \fR...? .BE .SH DESCRIPTION .PP @@ -177,7 +177,7 @@ 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. -The string can optionally contains spaces or +The string can optionally contain spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the content will .QW stick @@ -202,6 +202,14 @@ 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 .TP \fBgrid info \fIwindow\fR . @@ -235,7 +243,7 @@ Propagation is enabled by default. \fBgrid rowconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the row properties of the \fIindex\fR row of the -geometry window, \fIwindow\fR. +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 @@ -277,6 +285,14 @@ 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 .TP \fBgrid size \fIcontainer\fR . @@ -285,19 +301,17 @@ 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. .TP -\fBgrid slaves \fIwindow\fR ?\fI\-option value\fR? +\fBgrid content \fIwindow\fR ?\fI\-option value\fR? . If no options are supplied, a list of all of the content in \fIwindow\fR -are returned, most recently managed first. +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. -.VS "TIP 581" .TP -\fBgrid content \fIwindow\fR ?\fI\-option value\fR? +\fBgrid slaves \fIwindow\fR ?\fI\-option value\fR? . -Synonym for \fBgrid slaves \fIwindow\fR ?\fI\-option value\fR?. -.VE "TIP 581" +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 diff --git a/doc/image.n b/doc/image.n index 70f5acf..24b768a 100644 --- a/doc/image.n +++ b/doc/image.n @@ -12,7 +12,7 @@ .SH NAME image \- Create and manipulate images .SH SYNOPSIS -\fBimage\fR \fIoption \fR?\fIarg arg ...\fR? +\fBimage\fR \fIoption \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -93,8 +93,20 @@ See the \fBbitmap\fR manual entry for more information. Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. +.TP +\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 +\fIpressed\fR variant which is lighter in dark mode and darker in +light mode. These are for use in image buttons. See the \fBnsimage\fR +manual entry for more information. .SH "SEE ALSO" -bitmap(n), options(n), photo(n) +bitmap(n), options(n), photo(n), nsimage(n) .SH KEYWORDS height, image, types of images, width '\" Local Variables: diff --git a/doc/keysyms.n b/doc/keysyms.n index 08df32e..b9ccd84 100644 --- a/doc/keysyms.n +++ b/doc/keysyms.n @@ -12,7 +12,7 @@ keysyms \- keysyms recognized by Tk .SH DESCRIPTION .PP Tk recognizes many keysyms when specifying key bindings (e.g., -.QW "\fBbind\fR \fB. <Key-\fR\fIkeysym\fR\fB>\fR" ). +.QW "\fBbind\fR \fB. <\fR\fIkeysym\fR\fB>\fR" ). The following list enumerates the keysyms that will be recognized by Tk. Note that not all keysyms will be valid on all platforms, and some keysyms are also available on @@ -24,21 +24,21 @@ decimal and hexadecimal values. .PP .CS space 32 0x20 -exclam 33 0x21 +! (exclam) 33 0x21 quotedbl 34 0x22 numbersign 35 0x23 dollar 36 0x24 -percent 37 0x25 -ampersand 38 0x26 -apostrophe 39 0x27 -parenleft 40 0x28 -parenright 41 0x29 -asterisk 42 0x2A -plus 43 0x2B -comma 44 0x2C +% (percent) 37 0x25 +& (ampersand) 38 0x26 +' (apostrophe) 39 0x27 +( (parenleft) 40 0x28 +) (parenright) 41 0x29 +* (asterisk) 42 0x2A ++ (plus) 43 0x2B +, (comma) 44 0x2C minus 45 0x2D -period 46 0x2E -slash 47 0x2F +. (period) 46 0x2E +/ (slash) 47 0x2F 0 48 0x30 1 49 0x31 2 50 0x32 @@ -49,13 +49,13 @@ slash 47 0x2F 7 55 0x37 8 56 0x38 9 57 0x39 -colon 58 0x3A +: (colon) 58 0x3A semicolon 59 0x3B less 60 0x3C -equal 61 0x3D += (equal) 61 0x3D greater 62 0x3E -question 63 0x3F -at 64 0x40 +? (question) 63 0x3F +@ (at) 64 0x40 A 65 0x41 B 66 0x42 C 67 0x43 @@ -85,9 +85,9 @@ Z 90 0x5A bracketleft 91 0x5B backslash 92 0x5C bracketright 93 0x5D -asciicircum 94 0x5E -underscore 95 0x5F -grave 96 0x60 +^ (asciicircum) 94 0x5E +_ (underscore) 95 0x5F +` (grave) 96 0x60 a 97 0x61 b 98 0x62 c 99 0x63 @@ -115,105 +115,105 @@ x 120 0x78 y 121 0x79 z 122 0x7A braceleft 123 0x7B -bar 124 0x7C +| (bar) 124 0x7C braceright 125 0x7D -asciitilde 126 0x7E +~ (asciitilde) 126 0x7E nobreakspace 160 0xA0 -exclamdown 161 0xA1 -cent 162 0xA2 -sterling 163 0xA3 -currency 164 0xA4 -yen 165 0xA5 -brokenbar 166 0xA6 -section 167 0xA7 -diaeresis 168 0xA8 -copyright 169 0xA9 -ordfeminine 170 0xAA -guillemetleft 171 0xAB -notsign 172 0xAC +\(r! (exclamdown) 161 0xA1 +\(ct (cent) 162 0xA2 +\(Po (sterling) 163 0xA3 +\(Cs (currency) 164 0xA4 +\(Ye (yen) 165 0xA5 +\(bb (brokenbar) 166 0xA6 +\(sc (section) 167 0xA7 +\(ad (diaeresis) 168 0xA8 +\(co (copyright) 169 0xA9 +\(Of (ordfeminine) 170 0xAA +\(Fo (guillemetleft) 171 0xAB +\(no (notsign) 172 0xAC hyphen 173 0xAD -registered 174 0xAE -macron 175 0xAF -degree 176 0xB0 -plusminus 177 0xB1 -twosuperior 178 0xB2 -threesuperior 179 0xB3 -acute 180 0xB4 -mu 181 0xB5 -paragraph 182 0xB6 -periodcentered 183 0xB7 -cedilla 184 0xB8 -onesuperior 185 0xB9 -ordmasculine 186 0xBA -guillemetright 187 0xBB -onequarter 188 0xBC -onehalf 189 0xBD -threequarters 190 0xBE -questiondown 191 0xBF -Agrave 192 0xC0 -Aacute 193 0xC1 -Acircumflex 194 0xC2 -Atilde 195 0xC3 -Adiaeresis 196 0xC4 -Aring 197 0xC5 -AE 198 0xC6 -Ccedilla 199 0xC7 -Egrave 200 0xC8 -Eacute 201 0xC9 -Ecircumflex 202 0xCA -Ediaeresis 203 0xCB -Igrave 204 0xCC -Iacute 205 0xCD -Icircumflex 206 0xCE -Idiaeresis 207 0xCF -ETH 208 0xD0 -Ntilde 209 0xD1 -Ograve 210 0xD2 -Oacute 211 0xD3 -Ocircumflex 212 0xD4 -Otilde 213 0xD5 -Odiaeresis 214 0xD6 -multiply 215 0xD7 -Oslash 216 0xD8 -Ugrave 217 0xD9 -Uacute 218 0xDA -Ucircumflex 219 0xDB -Udiaeresis 220 0xDC -Yacute 221 0xDD -THORN 222 0xDE -ssharp 223 0xDF -agrave 224 0xE0 -aacute 225 0xE1 -acircumflex 226 0xE2 -atilde 227 0xE3 -adiaeresis 228 0xE4 -aring 229 0xE5 -ae 230 0xE6 -ccedilla 231 0xE7 -egrave 232 0xE8 -eacute 233 0xE9 -ecircumflex 234 0xEA -ediaeresis 235 0xEB -igrave 236 0xEC -iacute 237 0xED -icircumflex 238 0xEE -idiaeresis 239 0xEF -eth 240 0xF0 -ntilde 241 0xF1 -ograve 242 0xF2 -oacute 243 0xF3 -ocircumflex 244 0xF4 -otilde 245 0xF5 -odiaeresis 246 0xF6 -division 247 0xF7 -oslash 248 0xF8 -ugrave 249 0xF9 -uacute 250 0xFA -ucircumflex 251 0xFB -udiaeresis 252 0xFC -yacute 253 0xFD -thorn 254 0xFE -ydiaeresis 255 0xFF +\(rg (registered) 174 0xAE +\(a- (macron) 175 0xAF +\(de (degree) 176 0xB0 +\(+- (plusminus) 177 0xB1 +\(S2 (twosuperior) 178 0xB2 +\(S3 (threesuperior) 179 0xB3 +\(aa (acute) 180 0xB4 +\(mc (mu) 181 0xB5 +\(ps (paragraph) 182 0xB6 +\(pc (periodcentered) 183 0xB7 +\(ac (cedilla) 184 0xB8 +\(S1 (onesuperior) 185 0xB9 +\(Om (ordmasculine) 186 0xBA +\(Fc (guillemetright) 187 0xBB +\(14 (onequarter) 188 0xBC +\(12 (onehalf) 189 0xBD +\(34 (threequarters) 190 0xBE +\(r? (questiondown) 191 0xBF +\(`A (Agrave) 192 0xC0 +\('A (Aacute) 193 0xC1 +\(^A (Acircumflex) 194 0xC2 +\(~A (Atilde) 195 0xC3 +\(:A (Adiaeresis) 196 0xC4 +\(oA (Aring) 197 0xC5 +\(AE (AE) 198 0xC6 +\(,C (Ccedilla) 199 0xC7 +\(`E (Egrave) 200 0xC8 +\('E (Eacute) 201 0xC9 +\(^E (Ecircumflex) 202 0xCA +\(:E (Ediaeresis) 203 0xCB +\(`I (Igrave) 204 0xCC +\('I (Iacute) 205 0xCD +\(^I (Icircumflex) 206 0xCE +\(:I (Idiaeresis) 207 0xCF +\(-D (ETH) 208 0xD0 +\(~N (Ntilde) 209 0xD1 +\(`O (Ograve) 210 0xD2 +\('O (Oacute) 211 0xD3 +\(^O (Ocircumflex) 212 0xD4 +\(~O (Otilde) 213 0xD5 +\(:O (Odiaeresis) 214 0xD6 +\(mu (multiply) 215 0xD7 +\(/O (Oslash) 216 0xD8 +\(`U (Ugrave) 217 0xD9 +\('U (Uacute) 218 0xDA +\(^U (Ucircumflex) 219 0xDB +\(:U (Udiaeresis) 220 0xDC +\('Y (Yacute) 221 0xDD +\(TP (THORN) 222 0xDE +\(ss (ssharp) 223 0xDF +\(`a (agrave) 224 0xE0 +\('a (aacute) 225 0xE1 +\(^a (acircumflex) 226 0xE2 +\(~a (atilde) 227 0xE3 +\(:a (adiaeresis) 228 0xE4 +\(oa (aring) 229 0xE5 +\(ae (ae) 230 0xE6 +\(,c (ccedilla) 231 0xE7 +\(`e (egrave) 232 0xE8 +\('e (eacute) 233 0xE9 +\(^e (ecircumflex) 234 0xEA +\(:e (ediaeresis) 235 0xEB +\(`i (igrave) 236 0xEC +\('i (iacute) 237 0xED +\(^i (icircumflex) 238 0xEE +\(:i (idiaeresis) 239 0xEF +\(Sd (eth) 240 0xF0 +\(~n (ntilde) 241 0xF1 +\(`o (ograve) 242 0xF2 +\('o (oacute) 243 0xF3 +\(^o (ocircumflex) 244 0xF4 +\(~o (otilde) 245 0xF5 +\(:o (odiaeresis) 246 0xF6 +\(di (division) 247 0xF7 +\(/o (oslash) 248 0xF8 +\(`u (ugrave) 249 0xF9 +\('u (uacute) 250 0xFA +\(^u (ucircumflex) 251 0xFB +\(:u (udiaeresis) 252 0xFC +\('y (yacute) 253 0xFD +\(Tp (thorn) 254 0xFE +\(:y (ydiaeresis) 255 0xFF .CE .CS Aogonek 417 0x1A1 @@ -998,6 +998,7 @@ Korean_Won 3839 0xEFF OE 5052 0x13BC oe 5053 0x13BD Ydiaeresis 5054 0x13BE +\(eu (EuroSign) 8364 0x20AC .CE .CS ISO_Lock 65025 0xFE01 @@ -1192,16 +1193,13 @@ Prior 65365 0xFF55 Next 65366 0xFF56 End 65367 0xFF57 Begin 65368 0xFF58 -Win_L 65371 0xFF5B -Win_R 65372 0xFF5C -App 65373 0xFF5D Select 65376 0xFF60 Print 65377 0xFF61 Execute 65378 0xFF62 Insert 65379 0xFF63 Undo 65381 0xFF65 Redo 65382 0xFF66 -Menu 65383 0xFF67 +Menu (App) 65383 0xFF67 Find 65384 0xFF68 Cancel 65385 0xFF69 Help 65386 0xFF6A @@ -1288,8 +1286,8 @@ Meta_L 65511 0xFFE7 Meta_R 65512 0xFFE8 Alt_L 65513 0xFFE9 Alt_R 65514 0xFFEA -Super_L 65515 0xFFEB -Super_R 65516 0xFFEC +Super_L (Win_L) 65515 0xFFEB +Super_R (Win_R) 65516 0xFFEC Hyper_L 65517 0xFFED Hyper_R 65518 0xFFEE braille_dot_1 65521 0xFFF1 diff --git a/doc/label.n b/doc/label.n index 107175e..290ac8a 100644 --- a/doc/label.n +++ b/doc/label.n @@ -75,7 +75,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/labelframe.n b/doc/labelframe.n index 5ca5ad7..d8dd2c3 100644 --- a/doc/labelframe.n +++ b/doc/labelframe.n @@ -47,7 +47,7 @@ widget command. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will +If this option is negative or zero then the window will not request any size at all. .OP \-labelanchor labelAnchor LabelAnchor Specifies where to place the label. A label is only displayed if the @@ -71,7 +71,7 @@ widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will +If this option is negative or zero then the window will not request any size at all. .BE .SH DESCRIPTION @@ -95,7 +95,7 @@ name is the same as the path name of the labelframe's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\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 diff --git a/doc/listbox.n b/doc/listbox.n index 66b75b9..a047be6 100644 --- a/doc/listbox.n +++ b/doc/listbox.n @@ -126,6 +126,9 @@ specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no element covers that point, then the closest element to that point is used. .LP +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. @@ -136,7 +139,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following @@ -383,16 +386,18 @@ total width of the listbox text is off-screen to the left. . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +\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 \fBunits\fR, the view adjusts left or right by -\fInumber\fR character units (the width of the \fB0\fR character) -on the display; if it is \fBpages\fR then the view adjusts by +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. +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? @@ -430,14 +435,16 @@ way through the listbox, and so on. . This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR lines; if it is \fBpages\fR then +\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. +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then earlier elements become visible; if it is positive then later elements become visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by +\fInumber\fR lines. .RE .SH "DEFAULT BINDINGS" .PP @@ -560,7 +567,7 @@ In \fBextended\fR mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state. .IP [17] -Control-slash selects everything in the widget, except in +Control-/ selects everything in the widget, except in \fBsingle\fR and \fBbrowse\fR modes, in which case it selects the active element and deselects everything else. .IP [18] diff --git a/doc/man.macros b/doc/man.macros new file mode 100644 index 0000000..ddd073d --- /dev/null +++ b/doc/man.macros @@ -0,0 +1,267 @@ +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. @@ -19,7 +19,7 @@ menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars \-activebackground \-borderwidth \-foreground \-activeborderwidth \-cursor \-relief \-activeforeground \-disabledforeground \-takefocus -\-background \-font +\-background \-font \-activerelief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-postcommand postCommand Command @@ -34,12 +34,12 @@ For menu entries that are check buttons or radio buttons, this option specifies the color to display in the indicator when the check button or radio button is selected. .OP \-tearoff tearOff TearOff -This option must have a proper boolean value, which specifies -whether or not the menu should include a tear-off entry at the -top. If so, it will exist as entry 0 of the menu and the other -entries will number starting at 1. The default -menu bindings arrange for the menu to be torn off when the tear-off -entry is invoked. +This option must have a proper boolean value (default is false), +which specifies whether or not the menu should include a tear-off +entry at the top. If so, it will exist as entry 0 of the menu and +the other entries will number starting at 1. The default menu +bindings arrange for the menu to be torn off when the tear-off entry +is invoked. This option is ignored under Aqua/MacOS, where menus cannot be torn off. .OP \-tearoffcommand tearOffCommand TearOffCommand @@ -303,7 +303,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. @@ -316,34 +316,38 @@ any of the following forms: \fBactive\fR . Indicates the entry that is currently active. If no entry is -active then this form is equivalent to \fBnone\fR. This form may +active then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .TP 12 \fBend\fR . Indicates the bottommost entry in the menu. If there are no -entries in the menu then this form is equivalent to \fBnone\fR. +entries in the menu then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .TP 12 \fBlast\fR . Same as \fBend\fR. .TP 12 -\fBnone\fR +\fB{}\fR . Indicates .QW "no entry at all" ; this is used most commonly with the \fBactivate\fR option to deactivate all the entries in the -menu. In most cases the specification of \fBnone\fR causes +menu. In most cases the specification of \fB{}\fR causes nothing to happen in the widget command. -This form may not be abbreviated. +.TP 12 +\fBnone\fR +. +Same as \fB{}\fR +This form is deprecated and may not be abbreviated. .TP 12 \fB@\fIx\fB,\fIy\fR . 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 \fBnone\fR. +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. .TP 12 \fInumber\fR @@ -352,9 +356,14 @@ Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. .TP 12 +\fIid\fR +. +If the index does not satisfy one of the above forms then the menu is +searched for an entry with the specified id. +.TP 12 \fIpattern\fR . -If the index does not satisfy one of the above forms then this +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 @@ -362,6 +371,9 @@ 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: .TP @@ -370,19 +382,22 @@ The following widget commands are possible for menu widgets: Change the state of the entry indicated by \fIindex\fR to \fBactive\fR and redisplay it using its active colors. Any previously-active entry is deactivated. If \fIindex\fR -is specified as \fBnone\fR, or if the specified entry is +is specified as \fB{}\fR or \fBnone\fR, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string. .TP -\fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR? +\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 additional arguments -are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR -section below. -The \fBadd\fR widget command returns an empty string. +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. .TP \fIpathName \fBcget \fIoption\fR . @@ -443,19 +458,28 @@ If no \fIoptions\fR are specified, returns a list describing the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). .TP +\fIpathName \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. +.TP \fIpathName \fBindex \fIindex\fR . Returns the numerical index corresponding to \fIindex\fR, or -\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. +\fB{}\fR if \fIindex\fR was specified as \fB{}\fR or \fBnone\fR. .TP -\fIpathName \fBinsert \fIindex type \fR?\fIoption value option value ...\fR? +\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, \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 +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. .TP \fIpathName \fBinvoke \fIindex\fR . diff --git a/doc/menubar.n b/doc/menubar.n deleted file mode 100644 index c3be85d..0000000 --- a/doc/menubar.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" Copyright (c) 1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tk_menuBar n "" Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_menuBar, tk_bindForTraversal \- Obsolete support for menu bars -.SH SYNOPSIS -\fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR? -.sp -\fBtk_bindForTraversal \fIarg arg ... \fR -.BE -.SH DESCRIPTION -.PP -These procedures were used in Tk 3.6 and earlier releases to help -manage pulldown menus and to implement keyboard traversal of menus. -In Tk 4.0 and later releases they are no -longer needed. Stubs for these procedures have been retained for -backward compatibility, but they have no effect. You should remove -calls to these procedures from your code, since eventually the -procedures will go away. -.PP -From Tk 8.0 onwards, you should instead construct your menubar as a -normal \fBmenu\fR and then attach it to the \fBtoplevel\fR of your -choice using the \fB\-menu\fR option of that widget. -.SH "SEE ALSO" -menu(n), toplevel(n) -.SH KEYWORDS -keyboard traversal, menu, menu bar, post -'\" Local Variables: -'\" mode: nroff -'\" End: diff --git a/doc/menubutton.n b/doc/menubutton.n index 5696794..d07a8fe 100644 --- a/doc/menubutton.n +++ b/doc/menubutton.n @@ -117,7 +117,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/message.n b/doc/message.n index 280c072..a8bf6b7 100644 --- a/doc/message.n +++ b/doc/message.n @@ -57,7 +57,7 @@ The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If this option has a value greater than zero then the \fB\-aspect\fR option is ignored and the \fB\-width\fR option determines the line length. -If this option has a value less than or equal to zero, then +If this option value is negative or zero, then the \fB\-aspect\fR option determines the line length. .BE .SH DESCRIPTION @@ -106,7 +106,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/nsimage.n b/doc/nsimage.n new file mode 100644 index 0000000..8b401d7 --- /dev/null +++ b/doc/nsimage.n @@ -0,0 +1,129 @@ +'\" +'\" Copyright (c) 2022 Marc Culler +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH nsimage n 8.7 Tk "Tk Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +nsimage \- A Tk image type for macOS based on the NSImage class. +.BE +.SH DESCRIPTION +The nsimage is implemented as a Tk image type. The \fBimage\fR +command is used to create, delete, and query all images, including +images of type \fBnsimage\fR. The options that are available are +specific to the nsimage type and are described below. +.PP +The command to create an \fBnsimage\fR: +.TP +\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 +\fB\-source\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 +.TP +\fB\-as\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: +.IP +\fBname\fR +.IP +The source should be interpreted as the name of a named NSImage +provided by the system. This is the default if the -as option is not specified. +.IP +\fBfile\fR +.IP +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 +.IP +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 +.IP +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. +.TP +\fB\-width\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. +.TP +\fB\-height\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. +.TP +\fB\-radius\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. +.TP +\fB\-ring\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. +.TP +\fB\-alpha\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. +.TP +\fB\-pressed\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. +.TP +\fB\-template\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. +.SH "SEE ALSO" +image(n), options(n), photo(n) +.SH KEYWORDS +height, image, types of images, width +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/options.n b/doc/options.n index 738a1c6..71e4713 100644 --- a/doc/options.n +++ b/doc/options.n @@ -58,6 +58,9 @@ 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. @@ -221,6 +224,13 @@ internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. +.OP \-placeholder placeHolder PlaceHolder +Specifies a help text string to display if no text is otherwise displayed, +that is when the widget is empty. The placeholder text is displayed using +the values of the \fB\-font\fR and \fB\-justify\fR options. +.OP \-placeholderforeground placeholderForeground PlaceholderForeground +Specifies the foreground color to use when the placeholder text is +displayed. The default color is platform-specific. .OP \-relief relief Relief Specifies the 3-D effect desired for the widget. Acceptable values are \fBraised\fR, \fBsunken\fR, \fBflat\fR, \fBridge\fR, @@ -306,7 +316,8 @@ Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the -widget, 1 to the next character, and so on. +widget, 1 to the next character, and so on. \fBend\fR corresponds to the +last character, \fBend\fR-1 to the before last character, and so on. .OP \-wraplength wrapLength WrapLength For widgets that can perform word-wrapping, this option specifies the maximum line length. @@ -314,7 +325,7 @@ Lines that would exceed this length are wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. -If this value is less than or equal to 0 then no wrapping is done: lines +If this value is negative or zero then no wrapping is done: lines will break only at newline characters in the text. .OP \-xscrollcommand xScrollCommand ScrollCommand Specifies the prefix for a command used to communicate with horizontal diff --git a/doc/pack-old.n b/doc/pack-old.n deleted file mode 100644 index 5ef5da1..0000000 --- a/doc/pack-old.n +++ /dev/null @@ -1,195 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH pack-old n 4.0 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pack-old \- Obsolete syntax for packer geometry manager -.SH SYNOPSIS -\fBpack after \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack append \fIparent \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack before \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack unpack \fIwindow\fR -.BE -.SH DESCRIPTION -.PP -\fINote: this manual entry describes the syntax for the \fBpack\fI -command as it existed before Tk version 3.3. -Although this syntax continues to be supported for backward -compatibility, it is obsolete and should not be used anymore. -At some point in the future it may cease to be supported.\fR -.PP -The packer is a geometry manager that arranges the -children of a parent by packing them in order around the edges of -the parent. The first child is placed against one side of -the window, occupying the entire span of the window along that -side. This reduces the space remaining for other children as -if the side had been moved in by the size of the first child. -Then the next child is placed against one side of the remaining -cavity, and so on until all children have been placed or there -is no space left in the cavity. -.PP -The \fBbefore\fR, \fBafter\fR, and \fBappend\fR forms of the \fBpack\fR -command are used to insert one or more children into the packing order -for their parent. The \fBbefore\fR form inserts the children before -window \fIsibling\fR in the order; all of the other windows must be -siblings of \fIsibling\fR. The \fBafter\fR form inserts the windows -after \fIsibling\fR, and the \fBappend\fR form appends one or more -windows to the end of the packing order for \fIparent\fR. If a -\fIwindow\fR named in any of these commands is already packed in -its parent, it is removed from its current position in the packing -order and repositioned as indicated by the command. All of these -commands return an empty string as result. -.PP -The \fBunpack\fR form of the \fBpack\fR command removes \fIwindow\fR -from the packing order of its parent and unmaps it. After the -execution of this command the packer will no longer manage -\fIwindow\fR's geometry. -.PP -The placement of each child is actually a four-step process; -the \fIoptions\fR argument following each \fIwindow\fR consists of -a list of one or more fields that govern the placement of that -window. In the discussion below, the term \fIcavity\fR refers -to the space left in a parent when a particular child is placed -(i.e. all the space that was not claimed by earlier children in -the packing order). The term \fIparcel\fR refers to the space -allocated to a particular child; this is not necessarily the -same as the child window's final geometry. -.PP -The first step in placing a child is to determine which side of -the cavity it will lie against. Any one of the following options -may be used to specify a side: -.TP -\fBtop\fR -Position the child's parcel against the top of the cavity, -occupying the full width of the cavity. -.TP -\fBbottom\fR -Position the child's parcel against the bottom of the cavity, -occupying the full width of the cavity. -.TP -\fBleft\fR -Position the child's parcel against the left side of the cavity, -occupying the full height of the cavity. -.TP -\fBright\fR -Position the child's parcel against the right side of the cavity, -occupying the full height of the cavity. -.LP -At most one of these options should be specified for any given window. -If no side is specified, then the default is \fBtop\fR. -.PP -The second step is to decide on a parcel for the child. For \fBtop\fR -and \fBbottom\fR windows, the desired parcel width is normally the cavity -width and the desired parcel height is the window's requested height, -as passed to \fBTk_GeometryRequest\fR. For \fBleft\fR and \fBright\fR -windows, the desired parcel height is normally the cavity height and the -desired width is the window's requested width. However, extra -space may be requested for the window using any of the following -options: -.TP 12 -\fBpadx \fInum\fR -Add \fInum\fR pixels to the window's requested width before computing -the parcel size as described above. -.TP 12 -\fBpady \fInum\fR -Add \fInum\fR pixels to the window's requested height before computing -the parcel size as described above. -.TP 12 -\fBexpand\fR -This option requests that the window's parcel absorb any extra space left over -in the parent's cavity after packing all the children. -The amount of space left over depends on the sizes requested by the -other children, and may be zero. If several windows have all specified -\fBexpand\fR then the extra width will be divided equally among all the -\fBleft\fR and \fBright\fR windows that specified \fBexpand\fR and -the extra height will be divided equally among all the \fBtop\fR and -\fBbottom\fR windows that specified \fBexpand\fR. -.LP -If the desired width or height for a parcel is larger than the corresponding -dimension of the cavity, then the cavity's dimension is used instead. -.PP -The third step in placing the window is to decide on the window's -width and height. The default is for the window to receive either -its requested width and height or the those of the parcel, whichever -is smaller. If the parcel is larger than the window's requested -size, then the following options may be used to expand the -window to partially or completely fill the parcel: -.TP -\fBfill\fR -Set the window's size to equal the parcel size. -.TP -\fBfillx\fR -Increase the window's width to equal the parcel's width, but retain -the window's requested height. -.TP -\fBfilly\fR -Increase the window's height to equal the parcel's height, but retain -the window's requested width. -.PP -The last step is to decide the window's location within its parcel. -If the window's size equals the parcel's size, then the window simply -fills the entire parcel. If the parcel is larger than the window, -then one of -the following options may be used to specify where the window should -be positioned within its parcel: -.TP 15 -\fBframe center\fR -Center the window in its parcel. This is the default if no framing -option is specified. -.TP 15 -\fBframe n\fR -Position the window with its top edge centered on the top edge of -the parcel. -.TP 15 -\fBframe ne\fR -Position the window with its upper-right corner at the upper-right corner -of the parcel. -.TP 15 -\fBframe e\fR -Position the window with its right edge centered on the right edge of -the parcel. -.TP 15 -\fBframe se\fR -Position the window with its lower-right corner at the lower-right corner -of the parcel. -.TP 15 -\fBframe s\fR -Position the window with its bottom edge centered on the bottom edge of -the parcel. -.TP 15 -\fBframe sw\fR -Position the window with its lower-left corner at the lower-left corner -of the parcel. -.TP 15 -\fBframe w\fR -Position the window with its left edge centered on the left edge of -the parcel. -.TP 15 -\fBframe nw\fR -Position the window with its upper-left corner at the upper-left corner -of the parcel. -.PP -The packer manages the mapped/unmapped state of all the packed -children windows. It automatically maps the windows when it packs -them, and it unmaps any windows for which there was no space left -in the cavity. -.PP -The packer makes geometry requests on behalf of the parent windows -it manages. For each parent window it requests a size large enough -to accommodate all the options specified by all the packed children, -such that zero space would be leftover for \fBexpand\fR options. -.SH KEYWORDS -geometry manager, location, packer, parcel, size -'\" Local Variables: -'\" mode: nroff -'\" End: @@ -129,6 +129,14 @@ than receiving default values. 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 .TP \fBpack info \fIwindow\fR Returns a list whose elements are the current configuration state of @@ -150,17 +158,15 @@ If \fIboolean\fR is omitted then the command returns \fB0\fR or for \fIcontainer\fR. Propagation is enabled by default. .TP -\fBpack slaves \fIwindow\fR +\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. -.VS "TIP 581" .TP -\fBpack content \fIwindow\fR +\fBpack slaves \fIwindow\fR . -Synonym for \fBpack slaves \fIwindow\fR. -.VE "TIP 581" +Synonym for \fBpack content \fIwindow\fR. .SH "THE PACKER ALGORITHM" .PP For each container the packer maintains an ordered list of content diff --git a/doc/panedwindow.n b/doc/panedwindow.n index 9fb89d0..cad256a 100644 --- a/doc/panedwindow.n +++ b/doc/panedwindow.n @@ -92,7 +92,7 @@ the same as the path name of the panedwindow's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\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 diff --git a/doc/photo.n b/doc/photo.n index 84cf618..bc97319 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -24,31 +24,31 @@ photo \- Full-color images \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? \fIimageName \fBcopy \fIsourceImage\fR ?\fIoption value(s) ...\fR? \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? -\fIimageName \fBget \fIx y\fR +\fIimageName \fBget \fIx y\fR ?\fIoption\fR? \fIimageName \fBput \fIdata\fR ?\fIoption value(s) ...\fR? \fIimageName \fBread \fIfilename\fR ?\fIoption value(s) ...\fR? \fIimageName \fBredither\fR -\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? +\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? .fi .BE .SH DESCRIPTION .PP -A photo is an image whose pixels can display any color or be -transparent. A photo image is stored internally in full color (32 -bits per pixel), and is displayed using dithering if necessary. Image -data for a photo image can be obtained from a file or a string, or it -can be supplied from -C code through a procedural interface. At present, only +A photo is an image whose pixels can display any color with a varying +degree of transparency (the alpha channel). A photo image is stored +internally in full color (32 bits per pixel), and is displayed using +dithering if necessary. Image data for a photo image can be obtained +from a file or a string, or it can be supplied from C code through a +procedural interface. At present, only .VS 8.6 PNG, .VE 8.6 -GIF and PPM/PGM -formats are supported, but an interface exists to allow additional -image file formats to be added easily. A photo image is transparent -in regions where no image data has been supplied -or where it has been set transparent by the \fBtransparency set\fR -subcommand. +GIF and PPM/PGM formats are supported, but an interface exists to +allow additional image file formats to be added easily. A photo image +is (semi)transparent if the image data it was obtained from had +transparency informaton. 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 @@ -57,19 +57,25 @@ Photos support the following \fIoptions\fR: .TP \fB\-data \fIstring\fR . -Specifies the contents of the image as a string. The string should -contain binary data or, for some formats, base64-encoded data (this is +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. +format of the string must be one of those for which there is an image +file format handler that will accept string data. If both the +\fB\-data\fR and \fB\-file\fR options are specified, the \fB\-file\fR +option takes precedence. .TP -\fB\-format \fIformat-name\fR +\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. +\fB\-data\fR or \fB\-file\fR option and optional arguments passed to +the format handler. Note: 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. .TP \fB\-file \fIname\fR . @@ -95,6 +101,16 @@ 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 +.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 .TP \fB\-palette \fIpalette-spec\fR . @@ -122,7 +138,7 @@ This command may be used to invoke various operations on the image. It has the following general form: .CS -\fIimageName option \fR?\fIarg arg ...\fR? +\fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. @@ -140,7 +156,7 @@ The following commands are possible for photo images: . 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. +window it is displayed in will show through. The metadata dict of the image is not changed. .TP \fIimageName \fBcget\fR \fIoption\fR . @@ -163,6 +179,10 @@ 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: setting the \fB\-metadata\fR option without any other option +will not invoke the image format driver to recreate the bitmap. +.VE 8.7 .TP \fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? . @@ -233,8 +253,14 @@ the source image is used as-is. The default compositing rule is .TP \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? . -Returns image data in the form of a string. The following options -may be specified: +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 .TP \fB\-background\fI color\fR @@ -243,19 +269,23 @@ If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .TP -\fB\-format\fI format-name\fR -. -Specifies the name of the image file format handler to be used. -Specifically, this subcommand searches -for the first handler whose name matches an initial substring of -\fIformat-name\fR and which has the capability to write a string -containing this image data. -If this option is not given, this subcommand uses a format that -consists of a list (one element per row) of lists (one element per -pixel/column) of colors in +\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 (where \fIrr\fR is a pair of hexadecimal digits for the red -channel, \fIgg\fR for green, and \fIbb\fR for blue). +format (see \fBIMAGE FORMATS\fR below). +.VE 8.7 +Note: 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. .TP \fB\-from \fIx1 y1 x2 y2\fR . @@ -271,35 +301,59 @@ whole image. . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. -.RE +.VS 8.7 .TP -\fIimageName \fBget\fR \fIx y\fR +\fB\-metadata\fR \fImetadata\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 +\fIimageName \fBget\fR \fIx 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. +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. +.VE 8.7 .TP \fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR? . Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. -This command first searches the list of image file format handlers for +.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). -If \fIdata\fR does not match any known format, an attempt to interpret -it as a (top-to-bottom) list of scan-lines is made, with each -scan-line being a (left-to-right) list of pixel colors (see -\fBTk_GetColor\fR for a description of valid colors.) Every scan-line -must be of the same length. Note that when \fIdata\fR is a single -color name, you are instructing Tk to fill a rectangular region with -that color. The following options may be specified: +See \fBIMAGE FORMATS\fR below for details on formats for image data. +.VE 8.7 +The following options may be specified: .RS .TP -\fB\-format \fIformat-name\fR +\fB\-format\fR {\fIformat-name\fR ?\fIoption value ..\fR?} . -Specifies the format of the image data in \fIdata\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: 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 +.TP +\fB\-metadata\fR \fImetadata\fR +. +A specified \fImetadata\fR is passed to the image format driver when interpreting +the data. +Note: The current metadata of the image is not passed to the format driver +and is not changed by the command. +.VE 8.7 .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? . @@ -308,7 +362,9 @@ of the region of \fIimageName\fR into which the image data will be copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given and \fIdata\fR is not large enough to cover the rectangle specified by this option, the image data extracted will be tiled so it covers the -entire destination rectangle. Note that if \fIdata\fR specifies a +entire destination rectangle. If the region specified with this opion +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 @@ -323,12 +379,16 @@ in \fIfilename\fR, and then reads the image in \fIfilename\fR into specified: .RS .TP -\fB\-format \fIformat-name\fR +\fB\-format {\fIformat-name\fR ?\fIoption value ..\fR?} . -Specifies the format of the image data in \fIfilename\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: 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. .TP \fB\-from \fIx1 y1 x2 y2\fR . @@ -339,6 +399,15 @@ 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 +.TP +\fB\-metadata\fR \fImetadata\fR +. +A specified \fImetadata\fR is passed to the image format driver when interpreting +the data. +Note: The current metadata of the image is not passed to the format driver +and is not changed by the command. +.VE 8.7 .TP \fB\-shrink\fR . @@ -366,21 +435,31 @@ not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. .TP -\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR? +\fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? . Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS +.VS 8.7 .TP -\fIimageName \fBtransparency get \fIx y\fR +\fIimageName \fBtransparency get \fIx y\fR ?\fB-alpha\fR? . -Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is -transparent. +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 + +.VS 8.7 .TP -\fIimageName \fBtransparency set \fIx y boolean\fR +\fIimageName \fBtransparency set \fIx y\fR \fInewVal\fR ?\fB-alpha\fR? . -Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is -true, and makes that pixel opaque otherwise. +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 .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? @@ -395,15 +474,19 @@ If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .TP -\fB\-format\fI format-name\fR +\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. 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. +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: 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. .TP \fB\-from \fIx1 y1 x2 y2\fR . @@ -418,6 +501,16 @@ if this option is not given, is the whole image. . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. +.VS 8.7 +.TP +\fB\-metadata\fR \fBmetadata\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 @@ -426,20 +519,24 @@ image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF -formats, which are automatically registered on initialization. -.PP -When reading an image file or processing -string data specified with the \fB\-data\fR configuration option, the -photo image code invokes each handler in turn until one is -found that claims to be able to read the data in the file or string. -Usually this will find the correct handler, but if it does not, the -user may give a format name with the \fB\-format\fR option to specify -which handler to use. In fact the photo image code will try those -handlers whose names begin with the string specified for the -\fB\-format\fR option (the comparison is case-insensitive). For -example, if the user specifies \fB\-format gif\fR, then a handler -named GIF87 or GIF89 may be invoked, but a handler -named JPEG may not (assuming that such handlers had been +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 +the \fB\-data\fR configuration option, the photo image code invokes +each handler in turn until one is found that claims to be able to read +the data in the file or string. Usually this will find the correct +handler, but if it does not, the user may give a format name with the +\fB\-format\fR option to specify which handler to use. In this case, +the photo image code will try those handlers whose names begin with +the string specified for the \fB\-format\fR option (the comparison is +case-insensitive). For example, if the user specifies \fB\-format +gif\fR, then a handler named GIF87 or GIF89 may be invoked, but a +handler named JPEG may not (assuming that such handlers had been registered). .PP When writing image data to a file, the processing of the @@ -450,27 +547,163 @@ that, which the handler can use, for example, to specify which variant to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does. +.VS 8.7 +.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 -Some image formats support sub-options, which are specified at the time that -the image is loaded using additional words in the \fB\-format\fR option. At -the time of writing, the following are supported: +Image formats may support sub-options, wich ahre 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: +.VS 8.7 +.TP +\fBdefault \-colorformat\fI formatType\fR +. +The option is allowed when writing image data to a string with +\fIimageName\fR \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 .TP \fBgif \-index\fI indexValue\fR . -When parsing a multi-part GIF image, Tk normally only accesses the first -image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value -may be used instead. The \fIindexValue\fR must be an integer from 0 up to the -number of image parts in the GIF data. +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. .TP \fBpng \-alpha\fI alphaValue\fR . -An additional alpha filtering for the overall image, which allows the -background on which the image is displayed to show through. This usually also -has the effect of desaturating the image. The \fIalphaValue\fR must be between -0.0 and 1.0. +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. +.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. +\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 svg 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: +. +.RS +\fB elements:\fR g, path, rect, circle, ellipse, line, polyline, polygon, +linearGradient, radialGradient, stop, defs, svg, style +.PP +\fB attributes:\fR width, height, viewBox, +preserveAspectRatio with none, xMin, xMid, xMax, yMin, yMid, yMax, slice +.PP +\fB gradient attributes:\fR gradientUnits with objectBoundingBox, +gradientTransform, cx, cy, r fx, fy x1, y1, x2, y2 +spreadMethod with pad, reflect or repeat, +xlink:href +.PP +\fB poly attributes: \fR points +.PP +\fB line attributes: \fR x1, y1, x2, y2 +.PP +\fB ellipse attributes: \fR cx, cy, rx, ry +.PP +\fB circle attributes: \fR cx, cy, r +.PP +\fB rectangle attributes: \fR x, y, width, height, rx, ry +.PP +\fB path attributes: \fR d with m, M, l, L, h, H, v, V, c, C, s, S, q, Q, t, T, a, A, z, Z +.PP +\fB style 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 +. +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. .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 +available color formats are: +.IP \(bu 3 +The empty string - interpreted as full transparency, the color value +is undefined. +.IP \(bu 3 +Any value accepted by \fBTk_GetColor\fR, optionally followed by an +alpha suffix. The alpha suffix may be one of: +.RS +.TP +\fB@\fR\fIA\fR +. +The alpha value \fIA\fR must be a fractional value in the range 0.0 +(fully transparent) to 1.0 (fully opaque). +.TP +\fB#\fR\fIX\fR +. +The alpha value \fIX\fR is a hexadecimal digit that specifies an integer +alpha value in the range 0 (fully transparent) to 255 (fully opaque). +This is expanded in range from 4 bits wide to 8 bits wide by +multiplication by 0x11. +.TP +\fB#\fR\fIXX\fR +. +The alpha value \fIXX\fR is passed as two hexadecimal digits that +specify an integer alpha value in the range 0 (fully transparent) to 255 +(fully opaque). +.RE +.IP \(bu 3 +A Tcl list with three or four integers in the range 0 to 255, +specifying the values for the red, green, blue and (optionally) +alpha channels respectively. +.IP \(bu 3 +\fB#\fR\fIRGBA\fR format: a \fB#\fR followed by four hexadecimal digits, +where each digit is the value for the red, green, blue and alpha +channels respectively. Each digit will be expanded internally to +8 bits by multiplication by 0x11. +.IP \(bu 3 +\fB#\fR\fIRRGGBBAA\fR format: \fB#\fR followed by eight hexadecimal digits, +where each pair of subsequent digits represents the value for the red, +green, blue and alpha channels respectively. +.VE 8.7 .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code @@ -500,6 +733,64 @@ each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes. +.VS 8.7 +.SH "METADATA DICTIONARY" +.PP +Each image has a metadata dictionary property. +This dictionary is not relevant to the bitmap representation of the +image, but may contain additional information like resolution or +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: +.TP +DPI +. +Horizontal image resolution in DPI as a double value. +Supported by format \fBpng\fR. +.TP +aspect +. +Aspect ratio horizontal divided by vertical as double value. +Supported by formats \fBgif\fR and \fBpng\fR. +.TP +comment +. +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 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 \fI-index\fR option of an +animated \fBgif\fR file to properly display the subimage sequence. +The options are linked to each subimage selected by \fI-index\fR. +.TP +\fBdelay time\fR \fItime\fR +. +Update delay time in 10ms unit. This key is only present, if delay time is not 0. +.TP +\fBdisposal method\fR \fImethod\fR +. +Disposal method of the preceeding image, if given for the current image. +Possible values are: \fIdo not dispose\fR, \fIrestore to background color\fR, \fIrestore to previous\fR. +.TP +\fBuser interaction\fR \fIbool\fR +. +The key is present with a value of 1, if user interaction is specified. +Otherwise, the key is not present. +.TP +\fBupdate region\fR \fIX0\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, @@ -534,6 +825,23 @@ buttons: 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 +\fBimage create photo\fR foo + +# Make a simple graduated fill varying in alpha for the shadow +for {set i 14} {$i > 0} {incr i -1} { + set i2 [expr {$i + 30}] + foo \fBput\fR [format black#%x [expr {15-$i}]] -to $i $i $i2 $i2 +} + +# Put a solid green rectangle on top +foo \fBput\fR #F080 -to 0 0 30 30 +.VE 8.7 +.CE .SH "SEE ALSO" image(n) .SH KEYWORDS diff --git a/doc/place.n b/doc/place.n index c86579c..b56ad58 100644 --- a/doc/place.n +++ b/doc/place.n @@ -191,15 +191,13 @@ The list consists of \fIoption\-value\fR pairs in exactly the same form as might be specified to the \fBplace configure\fR command. .TP -\fBplace slaves \fIwindow\fR +\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. -.VS "TIP 581" .TP -\fBplace content \fIwindow\fR +\fBplace slaves \fIwindow\fR . -Synonym for \fBplace slaves \fIwindow\fR. -.VE "TIP 581" +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 diff --git a/doc/popup.n b/doc/popup.n index 6e6fd95..9543750 100644 --- a/doc/popup.n +++ b/doc/popup.n @@ -38,7 +38,7 @@ $m add command \-label "Example 2" \-command bell pack [label .l \-text "Click me!"] # Arrange for the menu to pop up when the label is clicked -bind .l <1> {\fBtk_popup\fR .popupMenu %X %Y} +bind .l <Button-1> {\fBtk_popup\fR .popupMenu %X %Y} .CE .SH "SEE ALSO" bind(n), menu(n), tk_optionMenu(n) diff --git a/doc/print.n b/doc/print.n new file mode 100644 index 0000000..91f02a7 --- /dev/null +++ b/doc/print.n @@ -0,0 +1,62 @@ +.\" Text automatically generated by txt2man +'\" +'\" Copyright (c) 2021 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 print n "" Tk "Tk Built-in Commands" +.so man.macros +.SH NAME +print \- Print canvas and text widgets using native dialogs and APIs. +.SH SYNOPSIS +\fBtk print \fIwindow\fR +. +.SH DESCRIPTION +.PP +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. +.PP +The \fBcanvas\fR widget has long supported PostScript export and both +PostScript and text files can be sent directly to a printer on Unix-like +systems using the +.QW "lp" +and +.QW "lpr" +Unix commands, and the \fBtk print\fR command does not supersede that +functionality; it builds on it. The \fBtk print\fR command is a fuller +implementation that uses native dialogs on macOS and Windows, and a Tk-based +dialog that provides parallel functionality on X11. +.SH PLATFORM NOTES +.TP +\fBmacOS\fR +. +The Mac implementation uses native print dialogs and relies on the underlying +Common Unix Printing System (CUPS) to render text output from the text widget +and PDF conversion of the canvas data to the printer or to a PDF file. +.TP +\fBWindows\fR +. +The Windows implementation is based on the GDI (Graphics Device Interface) +API. Because there are slight differences in how GDI and Tk's \fBcanvas\fR +widget display graphics, printed output from the \fBcanvas\fR on Windows may +not be identical to screen rendering. +.TP +\fBX11\fR +. +The X11 implementation uses a Tk GUI to configure print jobs for sending to a +printer via the +.QW "lpr" +or +.QW "lp" +commands. While these commands have a large number of parameters for +configuring print jobs, printers vary widely in how they support these +parameters. As a result, only printer selection and number of copies are +configured as arguments to the print command; many aspects of print rendering, +such as grayscale or color for the canvas, are instead configured when +PostScript is generated. +.SH "SEE ALSO" +canvas(n), text(n), tk(n) +.SH KEYWORDS +print, output, graphics, text, canvas diff --git a/doc/radiobutton.n b/doc/radiobutton.n index fceb1ec..2169515 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.n @@ -176,7 +176,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/scale.n b/doc/scale.n index d6407a0..86abdec 100644 --- a/doc/scale.n +++ b/doc/scale.n @@ -36,7 +36,7 @@ new value of the scale. .OP \-digits digits Digits An integer specifying how many significant digits should be retained when converting the value of the scale to a string. -If the number is less than or equal to zero, then the scale picks +If the number is negative or zero, then the scale picks the smallest value that guarantees that every possible slider position prints as a different string. .OP \-from from From @@ -56,7 +56,7 @@ it is the scale's width. A real value specifying the resolution for the scale. If this value is greater than zero then the scale's value will always be rounded to an even multiple of this value, as will -the endpoints of the scale. If the value is less than zero then no +the endpoints of the scale. If the value is negative then no rounding occurs. Defaults to 1 (i.e., the value will be integral). .OP \-showvalue showValue ShowValue Specifies a boolean value indicating whether or not the current @@ -138,7 +138,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following diff --git a/doc/scrollbar.n b/doc/scrollbar.n index eee6a63..ee6f6dd 100644 --- a/doc/scrollbar.n +++ b/doc/scrollbar.n @@ -42,8 +42,8 @@ as described in \fBSCROLLING COMMANDS\fR below. Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider). The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If this value is less than zero, the value of the \fB\-borderwidth\fR -option is used in its place. +If this value is negative (the default is -1), the value of +the \fB\-borderwidth\fR option is used in its place. .OP \-width width Width Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical @@ -103,7 +103,7 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following @@ -215,15 +215,6 @@ document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .TP -\fIprefix \fBscroll \fInumber \fBunits\fR -. -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. -.TP \fIprefix \fBscroll \fInumber \fBpages\fR . The widget should adjust its view by \fInumber\fR pages. @@ -232,47 +223,19 @@ it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. \fINumber\fR is either 1, which means the next page should become visible, or \-1, which means that the previous page should -become visible. -.SH "OLD COMMAND SYNTAX" -.PP -In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget -commands used a different form. -This form is still supported for backward compatibility, but it -is deprecated. -In the old command syntax, the \fBset\fR widget command has the -following form: +become visible. Fractional numbers are rounded away from 0, so +scrolling 0.001 pages has the same effect as scrolling 1 page. .TP -\fIpathName \fBset \fItotalUnits windowUnits firstUnit lastUnit\fR -In this form the arguments are all integers. -\fITotalUnits\fR gives the total size of the object being displayed in the -associated widget. The meaning of one unit depends on the associated -widget; for example, in a text editor widget units might -correspond to lines of -text. \fIWindowUnits\fR indicates the total number of units that -can fit in the associated window at one time. \fIFirstUnit\fR -and \fIlastUnit\fR give the indices of the first and last units -currently visible in the associated window (zero corresponds to the -first unit of the object). -.LP -Under the old syntax the \fBget\fR widget command returns a list -of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR, -\fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR -widget command. -.PP -The commands generated by scrollbars also have a different form -when the old syntax is being used: -.TP -\fIprefix\fR \fIunit\fR -\fIUnit\fR is an integer that indicates what should appear at -the top or left of the associated widget's window. -It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR -arguments to the \fBset\fR widget command. -.LP -The most recent \fBset\fR widget command determines whether or not -to use the old syntax. -If it is given two real arguments then the new syntax will be -used in the future, and if it is given four integer arguments then -the old syntax will be used. +\fIprefix \fBscroll \fInumber \fBunits\fR +. +The widget should adjust its view by \fInumber\fR units. +The units are defined in whatever way makes sense for the widget, +such as characters or lines in a text widget. +\fINumber\fR is either 1, which means one unit should scroll off +the top or left of the window, or \-1, which means that one unit +should scroll off the bottom or right of the window. Fractional +numbers are rounded away from 0, so scrolling 0.001 units has +the same effect as scrolling 1 unit. .SH BINDINGS .PP Tk automatically creates class bindings for scrollbars that give them diff --git a/doc/selection.n b/doc/selection.n index a2c5ae5..a26c5d9 100644 --- a/doc/selection.n +++ b/doc/selection.n @@ -12,7 +12,7 @@ .SH NAME selection \- Manipulate the X selection .SH SYNOPSIS -\fBselection \fIoption\fR ?\fIarg arg ...\fR? +\fBselection \fIoption\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -12,7 +12,7 @@ .SH NAME send \- Execute a command in a different application .SH SYNOPSIS -\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR? +\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/spinbox.n b/doc/spinbox.n index a2e7d05..f44d145 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -23,6 +23,7 @@ spinbox \- Create and manipulate 'spinbox' value spinner widgets \-foreground \-justify \-xscrollcommand \-highlightbackground \-relief \-highlightcolor \-repeatdelay +\-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-buttonbackground buttonBackground Background @@ -54,7 +55,8 @@ as it will format a floating-point number. A floating-point value corresponding to the lowest value for a spinbox, to be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control its -contents. This value must be less than the \fB\-to\fR option. +contents. If this value is greater than the \fB\-to\fR option, then +\fB\-from\fR and \fB\-to\fR values are automatically swapped. If \fB\-values\fR is specified, it supersedes this option. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting @@ -83,7 +85,8 @@ be displayed in a different color, depending on the values of the A floating-point value corresponding to the highest value for the spinbox, to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control -its contents. This value must be greater than the \fB\-from\fR option. +its contents. If this value is less than the \fB\-from\fR option, then +\fB\-from\fR and \fB\-to\fR values are automatically swapped. If \fB\-values\fR is specified, it supersedes this option. .OP \-validate validate Validate Specifies the mode in which validation should operate: \fBnone\fR, @@ -106,7 +109,7 @@ option has precedence over the \fB\-from\fR and \fB\-to\fR range. .OP \-width width Width Specifies an integer value indicating the desired width of the spinbox window, in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a +If the value is negative or zero, the widget picks a size just large enough to hold its current text. .OP \-wrap wrap wrap Must be a proper boolean value. If on, the spinbox will wrap around the @@ -221,7 +224,7 @@ Also, the \fB-validate\fR option will set itself to \fBnone\fR when the spinbox value gets changed because of adjustment of \fB-from\fR or \fB-to\fR and the \fB-validatecommand\fR returns false. For instance .CS - \fIspinbox pathName \-from 1 \-to 10 \-validate all \-vcmd {return 0}\fR + \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 @@ -236,7 +239,7 @@ The \fBspinbox\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. @@ -285,6 +288,9 @@ 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: @@ -467,15 +473,16 @@ way through the text appears at the left edge of the window. \fIpathName \fBxview scroll \fInumber what\fR This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +\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 \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR +screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display. .RE .SH "DEFAULT BINDINGS" .PP diff --git a/doc/sysnotify.n b/doc/sysnotify.n new file mode 100644 index 0000000..ea1ab89 --- /dev/null +++ b/doc/sysnotify.n @@ -0,0 +1,56 @@ +.\" 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 +\fBtk sysnotify\fR \fItitle\fR \fImessage\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." +.CE +.SH PLATFORM NOTES +.PP +The macOS and Windows versions are native implementations using system +API's. The X11 version has a conditional dependency on libnotify, and +falls back to a Tcl-only implementation if libnotify is not installed. On +each platform the notification includes a platform-specific default image to +accompany the text. +.TP +\fBmacOS\fR +. +The macOS version will request permission from the user to authorize +notifications. This must be activated in Apple's System Preferences +Notifications section. +.RS +.PP +If deploying an application using the standalone version of Wish.app, +setting the bundle ID in the applications Info.plist file to begin with +.QW \fBcom\fR +seems necessary for notifications to work. Using a different prefix +for the bundle ID, such as something like +.QW \fBtk.tcl.tkchat\fR , +will cause notifications to silently fail. +.RE +.TP +\fBWindows\fR +. +The image is taken from the system tray, i.e., \fBsysnotify\fR can only be +called when a \fBsystray\fR was installed. +. +.SH KEYWORDS +notify, alert diff --git a/doc/systray.n b/doc/systray.n new file mode 100644 index 0000000..c215c29 --- /dev/null +++ b/doc/systray.n @@ -0,0 +1,80 @@ +.\" 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 +\fBtk systray create \fI\-image image\fR \fI?\-text text\fR? \fI?\-button1 callback?\fR \fI?\-button3 callback?\fR +.sp +\fBtk systray configure \fI?option? ?value option value ...?\fR +.sp +\fBtk systray exists\fR +.sp +\fBtk systray destroy\fR +.BE +.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 +bound to <Button-1> and <Button-3>. +.PP +.\" METHOD: configure +The \fBtk systray configure\fR command sets one or more options of the systray +icon. Configurable options are the same as for the \fBcreate\fR subcommand. When +a single option name is given, the command returns the current value of this +option. When no option is given this command returns the list of all options and +their current value. +.PP +.\" METHOD: exists +The \fBtk systray exists\fR command checks whether a systray icon was created. +It returns a boolean. +.PP +.\" METHOD: destroy +The \fBtk systray destroy\fR command removes the icon from display and +deallocates it. +.PP +From a user-interface standpoint, only one icon per interpreter is +supported; attempts to create additional icons will return an error. The +existing tray icon can be modified with different images and +strings to indicate app state. Loading additional interpreters into a +running instance of Wish will allow additional icons to be displayed. +.SH EXAMPLE +.PP +Here is an example of the \fBtk systray\fR code: +.CS +image create photo book -data \e + R0lGODlhDwAPAKIAAP//////AP8AAMDAwICAgAAAAAAAAAAAACwAAAAADwAPAAADSQhA2u5ksPeKABKSCaya29d4WKgERFF0l1IMQCAKatvBJ0OTdzzXI1xMB3TBZAvATtB6NSLKleXi3OBoLqrVgc0yv+DVSEUuFxIAOw== +tk systray create -image book -text "tk systray sample" \e + -button1 {puts "Here is the tk systray output"} \e + -button3 {puts "here is alternate output"} +.CE +.PP +Here is an example of modifying the \fBtk systray\fR icon: +.CS +image create photo book_page -data \e + R0lGODlhCwAPAKIAAP//////AMDAwICAgAAA/wAAAAAAAAAAACwAAAAACwAPAAADMzi6CzAugiAgDGE68aB0RXgRJBFVX0SNpQlUWfahQOvSsgrX7eZJMlQMWBEYj8iQchlKAAA7 +tk systray configure -image book_page -text "Updated sample" \e + -button1 {puts "Different output from the tk systray"} \e + -button3 {puts "and more different output from the tk systray"} +.CE +.SH PLATFORM NOTES +.PP +The X11 implementation is supported on a "best efforts" basis because it is +dependent on the window manager. The "text" flag, which is implemented as +a tooltip, does not always display if the WM does not support such features; +the systray icon itself may not even display with some window managers. +.PP +On Windows, the Tk image provided in the \fB\-image\fR option must be a +photo image. On other platforms either a bitmap image or a photo image +may be provided. +.SH KEYWORDS +image, callback @@ -1056,7 +1056,7 @@ The \fBtext\fR command creates a new Tcl command whose name is the same as the path name of the text's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\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 @@ -1285,7 +1285,7 @@ must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. .RE .TP -\fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? +\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 @@ -1313,8 +1313,9 @@ of the widget to \fIboolean\fR. \fIpathName \fBedit redo\fR . When the \fB\-undo\fR option is true, reapplies the last undone edits provided -no other edits were done since then. Generates an error when the redo stack is -empty. Does nothing when the \fB\-undo\fR option is false. +no other edits were done since then, and returns a list of indices indicating +what ranges were changed by the redo operation. Generates an error when the +redo stack is empty. Does nothing when the \fB\-undo\fR option is false. .TP \fIpathName \fBedit reset\fR . @@ -1327,9 +1328,10 @@ Inserts a separator (boundary) on the undo stack. Does nothing when the .TP \fIpathName \fBedit undo\fR . -Undoes the last edit action when the \fB\-undo\fR option is true. An edit -action is defined as all the insert and delete commands that are recorded on -the undo stack in between two separators. Generates an error when the undo +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 @@ -1351,7 +1353,7 @@ given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. .TP -\fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? +\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 @@ -1416,7 +1418,7 @@ effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. .TP -\fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR? +\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 @@ -1696,7 +1698,7 @@ calculations, the scheduling is immediate. The command returns the empty string. \fBbgerror\fR is called on \fIcommand\fR failure. .RE .TP -\fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR? +\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 @@ -1735,8 +1737,8 @@ all the sequences for which bindings have been defined for \fItagName\fR. .RS .PP The only events for which bindings may be specified are those related to the -mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, -\fBMotion\fR, and \fBKeyPress\fR) or virtual events. Mouse and keyboard event +mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButton\fR, +\fBMotion\fR, and \fBKey\fR) or virtual events. Mouse and keyboard event bindings for a text widget respectively use the \fBcurrent\fR and \fBinsert\fR marks described under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag first becomes present on the @@ -1865,7 +1867,7 @@ file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. This command returns an empty string. .RE .TP -\fIpathName \fBwindow \fIoption \fR?\fIarg arg ...\fR? +\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 @@ -1934,18 +1936,18 @@ and 1. \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or -\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR -must be an integer, otherwise number may be specified in any of the forms -acceptable to \fBTk_GetPixels\fR, such as +\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBpages\fR, +\fBpixels\fR, or \fBunits\fR. If \fIwhat\fR is \fBpages\fR or +\fBunits\fR then \fInumber\fR must be an integer, otherwise number may be +specified in any of the forms acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i (the result is rounded to the nearest integer value. If no units are given, -pixels are assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts left or -right by \fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is -\fBpixels\fR then the view adjusts by \fInumber\fR pixels. If \fInumber\fR is +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 @@ -1982,10 +1984,10 @@ the bottom of the window, and some other pixel is at the top. \fIpathName \fByview scroll \fInumber what\fR . This command adjust the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBunits\fR, \fBpages\fR or -\fBpixels\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR -must be an integer, otherwise number may be specified in any of the forms -acceptable to \fBTk_GetPixels\fR, such as +\fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBpages\fR, +\fBpixels\fR, or \fBunits\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then +\fInumber\fR must be an integer, otherwise number may be specified in any of +the forms acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i @@ -2163,11 +2165,11 @@ insertion cursor without moving the insertion cursor. Meta-backspace and Meta-Delete delete the word to the left of the insertion cursor. .IP [30] -Control-x deletes whatever is selected in the text widget after copying it to -the clipboard. -.IP [31] Control-t reverses the order of the two characters to the right of the insertion cursor. +.IP [31] +Control-x deletes whatever is selected in the text widget after copying it to +the clipboard. .IP [32] Control-z undoes the last edit action if the \fB\-undo\fR option is true. Does nothing otherwise. @@ -12,7 +12,7 @@ .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS -\fBtk\fR \fIoption \fR?\fIarg arg ...\fR? +\fBtk\fR \fIoption \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -86,6 +86,13 @@ error if tried. 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 @@ -111,6 +118,18 @@ 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) @@ -127,9 +146,9 @@ Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (Mac OS X Aqua). .SH "SEE ALSO" -busy(n), fontchooser(n), send(n), winfo(n) +busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n) .SH KEYWORDS -application name, send +application name, print, send, sysnotify, systray '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/tk4.0.ps b/doc/tk4.0.ps deleted file mode 100644 index d79642d..0000000 --- a/doc/tk4.0.ps +++ /dev/null @@ -1,4602 +0,0 @@ -%! -%%BoundingBox: (atend) -%%Pages: (atend) -%%DocumentFonts: (atend) -%%EndComments -%%BeginProlog -% -% FrameMaker postscript_prolog 3.0, for use with FrameMaker 3.0 -% This postscript_prolog file is Copyright (c) 1986-1991 Frame Technology -% Corporation. All rights reserved. This postscript_prolog file may be -% freely copied and distributed in conjunction with documents created using -% FrameMaker. -% NOTE -% This file fixes the problem with NeWS printers dithering color output. -% Any questions should be sent to mickey@magickingdom.eng.sun.com -% -% Known Problems: -% Due to bugs in Transcript, the 'PS-Adobe-' is omitted from line 1 -/FMversion (3.0) def -% Set up Color vs. Black-and-White - -/FMPrintInColor { % once-thru loop gimmick - % See if we're a NeWSprint printer - /currentcanvas where { - pop systemdict /separationdict known - exit - } if -% originally had the following, which should always be false: -% /currentcanvas where { -% pop currentcanvas /Color known { -% currentcanvas /Color get -% exit -% } if -% } if - systemdict /colorimage known - systemdict /currentcolortransfer known and -exit } loop def - -% Uncomment the following line to force b&w on color printer -% /FMPrintInColor false def -/FrameDict 195 dict def -systemdict /errordict known not {/errordict 10 dict def - errordict /rangecheck {stop} put} if -% The readline in 23.0 doesn't recognize cr's as nl's on AppleTalk -FrameDict /tmprangecheck errordict /rangecheck get put -errordict /rangecheck {FrameDict /bug true put} put -FrameDict /bug false put -mark -% Some PS machines read past the CR, so keep the following 3 lines together! -currentfile 5 string readline -00 -0000000000 -cleartomark -errordict /rangecheck FrameDict /tmprangecheck get put -FrameDict /bug get { - /readline { - /gstring exch def - /gfile exch def - /gindex 0 def - { - gfile read pop - dup 10 eq {exit} if - dup 13 eq {exit} if - gstring exch gindex exch put - /gindex gindex 1 add def - } loop - pop - gstring 0 gindex getinterval true - } def - } if -/FMVERSION { - FMversion ne { - /Times-Roman findfont 18 scalefont setfont - 100 100 moveto - (FrameMaker version does not match postscript_prolog!) - dup = - show showpage - } if - } def -/FMLOCAL { - FrameDict begin - 0 def - end - } def - /gstring FMLOCAL - /gfile FMLOCAL - /gindex FMLOCAL - /orgxfer FMLOCAL - /orgproc FMLOCAL - /organgle FMLOCAL - /orgfreq FMLOCAL - /yscale FMLOCAL - /xscale FMLOCAL - /manualfeed FMLOCAL - /paperheight FMLOCAL - /paperwidth FMLOCAL -/FMDOCUMENT { - array /FMfonts exch def - /#copies exch def - FrameDict begin - 0 ne dup {setmanualfeed} if - /manualfeed exch def - /paperheight exch def - /paperwidth exch def - /yscale exch def - /xscale exch def - currenttransfer cvlit /orgxfer exch def - currentscreen cvlit /orgproc exch def - /organgle exch def /orgfreq exch def - setpapername - manualfeed {true} {papersize} ifelse - {manualpapersize} {false} ifelse - {desperatepapersize} if - end - } def - /pagesave FMLOCAL - /orgmatrix FMLOCAL - /landscape FMLOCAL -/FMBEGINPAGE { - FrameDict begin - /pagesave save def - 3.86 setmiterlimit - /landscape exch 0 ne def - landscape { - 90 rotate 0 exch neg translate pop - } - {pop pop} - ifelse - xscale yscale scale - /orgmatrix matrix def - gsave - } def -/FMENDPAGE { - grestore - pagesave restore - end - showpage - } def -/FMFONTDEFINE { - FrameDict begin - findfont - ReEncode - 1 index exch - definefont - FMfonts 3 1 roll - put - end - } def -/FMFILLS { - FrameDict begin - array /fillvals exch def - end - } def -/FMFILL { - FrameDict begin - fillvals 3 1 roll put - end - } def -/FMNORMALIZEGRAPHICS { - newpath - 0.0 0.0 moveto - 1 setlinewidth - 0 setlinecap - 0 0 0 sethsbcolor - 0 setgray - } bind def - /fx FMLOCAL - /fy FMLOCAL - /fh FMLOCAL - /fw FMLOCAL - /llx FMLOCAL - /lly FMLOCAL - /urx FMLOCAL - /ury FMLOCAL -/FMBEGINEPSF { - end - /FMEPSF save def - /showpage {} def - FMNORMALIZEGRAPHICS - [/fy /fx /fh /fw /ury /urx /lly /llx] {exch def} forall - fx fy translate - rotate - fw urx llx sub div fh ury lly sub div scale - llx neg lly neg translate - } bind def -/FMENDEPSF { - FMEPSF restore - FrameDict begin - } bind def -FrameDict begin -/setmanualfeed { -%%BeginFeature *ManualFeed True - statusdict /manualfeed true put -%%EndFeature - } def -/max {2 copy lt {exch} if pop} bind def -/min {2 copy gt {exch} if pop} bind def -/inch {72 mul} def -/pagedimen { - paperheight sub abs 16 lt exch - paperwidth sub abs 16 lt and - {/papername exch def} {pop} ifelse - } def - /papersizedict FMLOCAL -/setpapername { - /papersizedict 14 dict def - papersizedict begin - /papername /unknown def - /Letter 8.5 inch 11.0 inch pagedimen - /LetterSmall 7.68 inch 10.16 inch pagedimen - /Tabloid 11.0 inch 17.0 inch pagedimen - /Ledger 17.0 inch 11.0 inch pagedimen - /Legal 8.5 inch 14.0 inch pagedimen - /Statement 5.5 inch 8.5 inch pagedimen - /Executive 7.5 inch 10.0 inch pagedimen - /A3 11.69 inch 16.5 inch pagedimen - /A4 8.26 inch 11.69 inch pagedimen - /A4Small 7.47 inch 10.85 inch pagedimen - /B4 10.125 inch 14.33 inch pagedimen - /B5 7.16 inch 10.125 inch pagedimen - end - } def -/papersize { - papersizedict begin - /Letter {lettertray letter} def - /LetterSmall {lettertray lettersmall} def - /Tabloid {11x17tray 11x17} def - /Ledger {ledgertray ledger} def - /Legal {legaltray legal} def - /Statement {statementtray statement} def - /Executive {executivetray executive} def - /A3 {a3tray a3} def - /A4 {a4tray a4} def - /A4Small {a4tray a4small} def - /B4 {b4tray b4} def - /B5 {b5tray b5} def - /unknown {unknown} def - papersizedict dup papername known {papername} {/unknown} ifelse get - end - /FMdicttop countdictstack 1 add def - statusdict begin stopped end - countdictstack -1 FMdicttop {pop end} for - } def -/manualpapersize { - papersizedict begin - /Letter {letter} def - /LetterSmall {lettersmall} def - /Tabloid {11x17} def - /Ledger {ledger} def - /Legal {legal} def - /Statement {statement} def - /Executive {executive} def - /A3 {a3} def - /A4 {a4} def - /A4Small {a4small} def - /B4 {b4} def - /B5 {b5} def - /unknown {unknown} def - papersizedict dup papername known {papername} {/unknown} ifelse get - end - stopped - } def -/desperatepapersize { - statusdict /setpageparams known - { - paperwidth paperheight 0 1 - statusdict begin - {setpageparams} stopped pop - end - } if - } def -/savematrix { - orgmatrix currentmatrix pop - } bind def -/restorematrix { - orgmatrix setmatrix - } bind def -/dmatrix matrix def -/dpi 72 0 dmatrix defaultmatrix dtransform - dup mul exch dup mul add sqrt def -/freq dpi 18.75 div 8 div round dup 0 eq {pop 1} if 8 mul dpi exch div def -/sangle 1 0 dmatrix defaultmatrix dtransform exch atan def -/DiacriticEncoding [ -/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef /space /exclam /quotedbl -/numbersign /dollar /percent /ampersand /quotesingle /parenleft -/parenright /asterisk /plus /comma /hyphen /period /slash /zero /one -/two /three /four /five /six /seven /eight /nine /colon /semicolon -/less /equal /greater /question /at /A /B /C /D /E /F /G /H /I /J /K -/L /M /N /O /P /Q /R /S /T /U /V /W /X /Y /Z /bracketleft /backslash -/bracketright /asciicircum /underscore /grave /a /b /c /d /e /f /g /h -/i /j /k /l /m /n /o /p /q /r /s /t /u /v /w /x /y /z /braceleft /bar -/braceright /asciitilde /.notdef /Adieresis /Aring /Ccedilla /Eacute -/Ntilde /Odieresis /Udieresis /aacute /agrave /acircumflex /adieresis -/atilde /aring /ccedilla /eacute /egrave /ecircumflex /edieresis -/iacute /igrave /icircumflex /idieresis /ntilde /oacute /ograve -/ocircumflex /odieresis /otilde /uacute /ugrave /ucircumflex -/udieresis /dagger /.notdef /cent /sterling /section /bullet -/paragraph /germandbls /registered /copyright /trademark /acute -/dieresis /.notdef /AE /Oslash /.notdef /.notdef /.notdef /.notdef -/yen /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef -/ordfeminine /ordmasculine /.notdef /ae /oslash /questiondown -/exclamdown /logicalnot /.notdef /florin /.notdef /.notdef -/guillemotleft /guillemotright /ellipsis /.notdef /Agrave /Atilde -/Otilde /OE /oe /endash /emdash /quotedblleft /quotedblright -/quoteleft /quoteright /.notdef /.notdef /ydieresis /Ydieresis -/fraction /currency /guilsinglleft /guilsinglright /fi /fl /daggerdbl -/periodcentered /quotesinglbase /quotedblbase /perthousand -/Acircumflex /Ecircumflex /Aacute /Edieresis /Egrave /Iacute -/Icircumflex /Idieresis /Igrave /Oacute /Ocircumflex /.notdef /Ograve -/Uacute /Ucircumflex /Ugrave /dotlessi /circumflex /tilde /macron -/breve /dotaccent /ring /cedilla /hungarumlaut /ogonek /caron -] def -/ReEncode { - dup - length - dict begin - { - 1 index /FID ne - {def} - {pop pop} ifelse - } forall - 0 eq {/Encoding DiacriticEncoding def} if - currentdict - end - } bind def -/graymode true def - /bwidth FMLOCAL - /bpside FMLOCAL - /bstring FMLOCAL - /onbits FMLOCAL - /offbits FMLOCAL - /xindex FMLOCAL - /yindex FMLOCAL - /x FMLOCAL - /y FMLOCAL -/setpattern { - /bwidth exch def - /bpside exch def - /bstring exch def - /onbits 0 def /offbits 0 def - freq sangle landscape {90 add} if - {/y exch def - /x exch def - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - bstring yindex bwidth mul xindex 8 idiv add get - 1 7 xindex 8 mod sub bitshift and 0 ne - {/onbits onbits 1 add def 1} - {/offbits offbits 1 add def 0} - ifelse - } - setscreen - {} settransfer - offbits offbits onbits add div FMsetgray - /graymode false def - } bind def -/grayness { - FMsetgray - graymode not { - /graymode true def - orgxfer cvx settransfer - orgfreq organgle orgproc cvx setscreen - } if - } bind def - /HUE FMLOCAL - /SAT FMLOCAL - /BRIGHT FMLOCAL - /Colors FMLOCAL -FMPrintInColor - - { - /HUE 0 def - /SAT 0 def - /BRIGHT 0 def - % array of arrays Hue and Sat values for the separations [HUE BRIGHT] - /Colors - [[0 0 ] % black - [0 0 ] % white - [0.00 1.0] % red - [0.37 1.0] % green - [0.60 1.0] % blue - [0.50 1.0] % cyan - [0.83 1.0] % magenta - [0.16 1.0] % comment / yellow - ] def - - /BEGINBITMAPCOLOR { - BITMAPCOLOR} def - /BEGINBITMAPCOLORc { - BITMAPCOLORc} def - /BEGINBITMAPTRUECOLOR { - BITMAPTRUECOLOR } def - /BEGINBITMAPTRUECOLORc { - BITMAPTRUECOLORc } def - /K { - Colors exch get dup - 0 get /HUE exch store - 1 get /BRIGHT exch store - HUE 0 eq BRIGHT 0 eq and - {1.0 SAT sub setgray} - {HUE SAT BRIGHT sethsbcolor} - ifelse - } def - /FMsetgray { - /SAT exch 1.0 exch sub store - HUE 0 eq BRIGHT 0 eq and - {1.0 SAT sub setgray} - {HUE SAT BRIGHT sethsbcolor} - ifelse - } bind def - } - - { - /BEGINBITMAPCOLOR { - BITMAPGRAY} def - /BEGINBITMAPCOLORc { - BITMAPGRAYc} def - /BEGINBITMAPTRUECOLOR { - BITMAPTRUEGRAY } def - /BEGINBITMAPTRUECOLORc { - BITMAPTRUEGRAYc } def - /FMsetgray {setgray} bind def - /K { - pop - } def - } -ifelse -/normalize { - transform round exch round exch itransform - } bind def -/dnormalize { - dtransform round exch round exch idtransform - } bind def -/lnormalize { - 0 dtransform exch cvi 2 idiv 2 mul 1 add exch idtransform pop - } bind def -/H { - lnormalize setlinewidth - } bind def -/Z { - setlinecap - } bind def - /fillvals FMLOCAL -/X { - fillvals exch get - dup type /stringtype eq - {8 1 setpattern} - {grayness} - ifelse - } bind def -/V { - gsave eofill grestore - } bind def -/N { - stroke - } bind def -/M {newpath moveto} bind def -/E {lineto} bind def -/D {curveto} bind def -/O {closepath} bind def - /n FMLOCAL -/L { - /n exch def - newpath - normalize - moveto - 2 1 n {pop normalize lineto} for - } bind def -/Y { - L - closepath - } bind def - /x1 FMLOCAL - /x2 FMLOCAL - /y1 FMLOCAL - /y2 FMLOCAL - /rad FMLOCAL -/R { - /y2 exch def - /x2 exch def - /y1 exch def - /x1 exch def - x1 y1 - x2 y1 - x2 y2 - x1 y2 - 4 Y - } bind def -/RR { - /rad exch def - normalize - /y2 exch def - /x2 exch def - normalize - /y1 exch def - /x1 exch def - newpath - x1 y1 rad add moveto - x1 y2 x2 y2 rad arcto - x2 y2 x2 y1 rad arcto - x2 y1 x1 y1 rad arcto - x1 y1 x1 y2 rad arcto - closepath - 16 {pop} repeat - } bind def -/C { - grestore - gsave - R - clip - } bind def - /FMpointsize FMLOCAL -/F { - FMfonts exch get - FMpointsize scalefont - setfont - } bind def -/Q { - /FMpointsize exch def - F - } bind def -/T { - moveto show - } bind def -/RF { - rotate - 0 ne {-1 1 scale} if - } bind def -/TF { - gsave - moveto - RF - show - grestore - } bind def -/P { - moveto - 0 32 3 2 roll widthshow - } bind def -/PF { - gsave - moveto - RF - 0 32 3 2 roll widthshow - grestore - } bind def -/S { - moveto - 0 exch ashow - } bind def -/SF { - gsave - moveto - RF - 0 exch ashow - grestore - } bind def -/B { - moveto - 0 32 4 2 roll 0 exch awidthshow - } bind def -/BF { - gsave - moveto - RF - 0 32 4 2 roll 0 exch awidthshow - grestore - } bind def -/G { - gsave - newpath - normalize translate 0.0 0.0 moveto - dnormalize scale - 0.0 0.0 1.0 5 3 roll arc - closepath fill - grestore - } bind def -/A { - gsave - savematrix - newpath - 2 index 2 div add exch 3 index 2 div sub exch - normalize 2 index 2 div sub exch 3 index 2 div add exch - translate - scale - 0.0 0.0 1.0 5 3 roll arc - restorematrix - stroke - grestore - } bind def - /x FMLOCAL - /y FMLOCAL - /w FMLOCAL - /h FMLOCAL - /xx FMLOCAL - /yy FMLOCAL - /ww FMLOCAL - /hh FMLOCAL - /FMsaveobject FMLOCAL - /FMoptop FMLOCAL - /FMdicttop FMLOCAL -/BEGINPRINTCODE { - /FMdicttop countdictstack 1 add def - /FMoptop count 4 sub def - /FMsaveobject save def - userdict begin - /showpage {} def - FMNORMALIZEGRAPHICS - 3 index neg 3 index neg translate - } bind def -/ENDPRINTCODE { - count -1 FMoptop {pop pop} for - countdictstack -1 FMdicttop {pop end} for - FMsaveobject restore - } bind def -/gn { - 0 - { 46 mul - cf read pop - 32 sub - dup 46 lt {exit} if - 46 sub add - } loop - add - } bind def - /str FMLOCAL -/cfs { - /str sl string def - 0 1 sl 1 sub {str exch val put} for - str def - } bind def -/ic [ - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 - 0 - {0 hx} {1 hx} {2 hx} {3 hx} {4 hx} {5 hx} {6 hx} {7 hx} {8 hx} {9 hx} - {10 hx} {11 hx} {12 hx} {13 hx} {14 hx} {15 hx} {16 hx} {17 hx} {18 hx} - {19 hx} {gn hx} {0} {1} {2} {3} {4} {5} {6} {7} {8} {9} {10} {11} {12} - {13} {14} {15} {16} {17} {18} {19} {gn} {0 wh} {1 wh} {2 wh} {3 wh} - {4 wh} {5 wh} {6 wh} {7 wh} {8 wh} {9 wh} {10 wh} {11 wh} {12 wh} - {13 wh} {14 wh} {gn wh} {0 bl} {1 bl} {2 bl} {3 bl} {4 bl} {5 bl} {6 bl} - {7 bl} {8 bl} {9 bl} {10 bl} {11 bl} {12 bl} {13 bl} {14 bl} {gn bl} - {0 fl} {1 fl} {2 fl} {3 fl} {4 fl} {5 fl} {6 fl} {7 fl} {8 fl} {9 fl} - {10 fl} {11 fl} {12 fl} {13 fl} {14 fl} {gn fl} - ] def - /sl FMLOCAL - /val FMLOCAL - /ws FMLOCAL - /im FMLOCAL - /bs FMLOCAL - /cs FMLOCAL - /len FMLOCAL - /pos FMLOCAL -/ms { - /sl exch def - /val 255 def - /ws cfs - /im cfs - /val 0 def - /bs cfs - /cs cfs - } bind def -400 ms -/ip { - is - 0 - cf cs readline pop - { ic exch get exec - add - } forall - pop - - } bind def -/wh { - /len exch def - /pos exch def - ws 0 len getinterval im pos len getinterval copy pop - pos len - } bind def -/bl { - /len exch def - /pos exch def - bs 0 len getinterval im pos len getinterval copy pop - pos len - } bind def -/s1 1 string def -/fl { - /len exch def - /pos exch def - /val cf s1 readhexstring pop 0 get def - pos 1 pos len add 1 sub {im exch val put} for - pos len - } bind def -/hx { - 3 copy getinterval - cf exch readhexstring pop pop - } bind def - /h FMLOCAL - /w FMLOCAL - /d FMLOCAL - /lb FMLOCAL - /bitmapsave FMLOCAL - /is FMLOCAL - /cf FMLOCAL -/wbytes { - dup - 8 eq {pop} {1 eq {7 add 8 idiv} {3 add 4 idiv} ifelse} ifelse - } bind def -/BEGINBITMAPBWc { - 1 {} COMMONBITMAPc - } bind def -/BEGINBITMAPGRAYc { - 8 {} COMMONBITMAPc - } bind def -/BEGINBITMAP2BITc { - 2 {} COMMONBITMAPc - } bind def -/COMMONBITMAPc { - /r exch def - /d exch def - gsave - translate rotate scale /h exch def /w exch def - /lb w d wbytes def - sl lb lt {lb ms} if - /bitmapsave save def - r - /is im 0 lb getinterval def - ws 0 lb getinterval is copy pop - /cf currentfile def - w h d [w 0 0 h neg 0 h] - {ip} image - bitmapsave restore - grestore - } bind def -/BEGINBITMAPBW { - 1 {} COMMONBITMAP - } bind def -/BEGINBITMAPGRAY { - 8 {} COMMONBITMAP - } bind def -/BEGINBITMAP2BIT { - 2 {} COMMONBITMAP - } bind def -/COMMONBITMAP { - /r exch def - /d exch def - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - r - /is w d wbytes string def - /cf currentfile def - w h d [w 0 0 h neg 0 h] - {cf is readhexstring pop} image - bitmapsave restore - grestore - } bind def - /proc1 FMLOCAL - /proc2 FMLOCAL - /newproc FMLOCAL -/Fmcc { - /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx -} bind def -/ngrayt 256 array def -/nredt 256 array def -/nbluet 256 array def -/ngreent 256 array def - /gryt FMLOCAL - /blut FMLOCAL - /grnt FMLOCAL - /redt FMLOCAL - /indx FMLOCAL - /cynu FMLOCAL - /magu FMLOCAL - /yelu FMLOCAL - /k FMLOCAL - /u FMLOCAL -/colorsetup { - currentcolortransfer - /gryt exch def - /blut exch def - /grnt exch def - /redt exch def - 0 1 255 { - /indx exch def - /cynu 1 red indx get 255 div sub def - /magu 1 green indx get 255 div sub def - /yelu 1 blue indx get 255 div sub def - /k cynu magu min yelu min def - /u k currentundercolorremoval exec def - nredt indx 1 0 cynu u sub max sub redt exec put - ngreent indx 1 0 magu u sub max sub grnt exec put - nbluet indx 1 0 yelu u sub max sub blut exec put - ngrayt indx 1 k currentblackgeneration exec sub gryt exec put - } for - {255 mul cvi nredt exch get} - {255 mul cvi ngreent exch get} - {255 mul cvi nbluet exch get} - {255 mul cvi ngrayt exch get} - setcolortransfer - {pop 0} setundercolorremoval - {} setblackgeneration - } bind def - /tran FMLOCAL -/fakecolorsetup { - /tran 256 string def - 0 1 255 {/indx exch def - tran indx - red indx get 77 mul - green indx get 151 mul - blue indx get 28 mul - add add 256 idiv put} for - currenttransfer - {255 mul cvi tran exch get 255.0 div} - exch Fmcc settransfer -} bind def -/BITMAPCOLOR { - /d 8 def - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - colorsetup - /is w d wbytes string def - /cf currentfile def - w h d [w 0 0 h neg 0 h] - {cf is readhexstring pop} {is} {is} true 3 colorimage - bitmapsave restore - grestore - } bind def -/BITMAPCOLORc { - /d 8 def - gsave - translate rotate scale /h exch def /w exch def - /lb w d wbytes def - sl lb lt {lb ms} if - /bitmapsave save def - colorsetup - /is im 0 lb getinterval def - ws 0 lb getinterval is copy pop - /cf currentfile def - w h d [w 0 0 h neg 0 h] - {ip} {is} {is} true 3 colorimage - bitmapsave restore - grestore - } bind def -/BITMAPTRUECOLORc { - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - - /is w string def - - ws 0 w getinterval is copy pop - /cf currentfile def - w h 8 [w 0 0 h neg 0 h] - {ip} {gip} {bip} true 3 colorimage - bitmapsave restore - grestore - } bind def -/BITMAPTRUECOLOR { - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - /is w string def - /gis w string def - /bis w string def - /cf currentfile def - w h 8 [w 0 0 h neg 0 h] - { cf is readhexstring pop } - { cf gis readhexstring pop } - { cf bis readhexstring pop } - true 3 colorimage - bitmapsave restore - grestore - } bind def -/BITMAPTRUEGRAYc { - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - - /is w string def - - ws 0 w getinterval is copy pop - /cf currentfile def - w h 8 [w 0 0 h neg 0 h] - {ip gip bip w gray} image - bitmapsave restore - grestore - } bind def -/ww FMLOCAL -/r FMLOCAL -/g FMLOCAL -/b FMLOCAL -/i FMLOCAL -/gray { - /ww exch def - /b exch def - /g exch def - /r exch def - 0 1 ww 1 sub { /i exch def r i get .299 mul g i get .587 mul - b i get .114 mul add add r i 3 -1 roll floor cvi put } for - r - } bind def -/BITMAPTRUEGRAY { - gsave - translate rotate scale /h exch def /w exch def - /bitmapsave save def - /is w string def - /gis w string def - /bis w string def - /cf currentfile def - w h 8 [w 0 0 h neg 0 h] - { cf is readhexstring pop - cf gis readhexstring pop - cf bis readhexstring pop w gray} image - bitmapsave restore - grestore - } bind def -/BITMAPGRAY { - 8 {fakecolorsetup} COMMONBITMAP - } bind def -/BITMAPGRAYc { - 8 {fakecolorsetup} COMMONBITMAPc - } bind def -/ENDBITMAP { - } bind def -end - /ALDsave FMLOCAL - /ALDmatrix matrix def ALDmatrix currentmatrix pop -/StartALD { - /ALDsave save def - savematrix - ALDmatrix setmatrix - } bind def -/InALD { - restorematrix - } bind def -/DoneALD { - ALDsave restore - } bind def -%%EndProlog -%%BeginSetup -(3.0) FMVERSION -1 1 612 792 0 1 13 FMDOCUMENT -0 0 /Helvetica-Bold FMFONTDEFINE -1 0 /Times-Bold FMFONTDEFINE -2 0 /Times-Italic FMFONTDEFINE -3 0 /Times-Roman FMFONTDEFINE -4 0 /Helvetica FMFONTDEFINE -5 0 /Courier FMFONTDEFINE -6 0 /Courier-Oblique FMFONTDEFINE -32 FMFILLS -0 0 FMFILL -1 0.1 FMFILL -2 0.3 FMFILL -3 0.5 FMFILL -4 0.7 FMFILL -5 0.9 FMFILL -6 0.97 FMFILL -7 1 FMFILL -8 <0f1e3c78f0e1c387> FMFILL -9 <0f87c3e1f0783c1e> FMFILL -10 <cccccccccccccccc> FMFILL -11 <ffff0000ffff0000> FMFILL -12 <8142241818244281> FMFILL -13 <03060c183060c081> FMFILL -14 <8040201008040201> FMFILL -16 1 FMFILL -17 0.9 FMFILL -18 0.7 FMFILL -19 0.5 FMFILL -20 0.3 FMFILL -21 0.1 FMFILL -22 0.03 FMFILL -23 0 FMFILL -24 <f0e1c3870f1e3c78> FMFILL -25 <f0783c1e0f87c3e1> FMFILL -26 <3333333333333333> FMFILL -27 <0000ffff0000ffff> FMFILL -28 <7ebddbe7e7dbbd7e> FMFILL -29 <fcf9f3e7cf9f3f7e> FMFILL -30 <7fbfdfeff7fbfdfe> FMFILL -%%EndSetup -%%Page: "1" 1 -%%BeginPaperSize: Letter -%%EndPaperSize -612 792 0 FMBEGINPAGE -98.1 675 512.1 675 2 L -7 X -0 K -V -2 H -0 Z -0 X -N -98.1 450 512.1 450 2 L -7 X -V -2 Z -0 X -N -98.1 108 512.1 126 R -7 X -V -0 10 Q -0 X -(1) 506.54 119.33 T -1 24 Q --0.48 (Tk4.0 Overview and Porting Guide) 152.1 605 S -2 12 Q -(John Ouster) 152.1 563 T -(hout) 210.84 563 T -98.1 135 512.1 423 R -7 X -V -3 10 Q -0 X -(Tk version 4.0 is a major new release with many improvements, new features, and bug) 152.1 416.33 T -(\336xes. This document provides an introduction to the new features and describes the most) 152.1 404.33 T --0.18 (common problems you are likely to encounter when porting scripts from Tk 3.6, the previ-) 152.1 392.33 P -(ous release. This is) 152.1 380.33 T -2 F -(not) 230.66 380.33 T -3 F -( an introduction to Tk: I assume that you are already familiar with) 243.43 380.33 T -(Tk 3.6 as described in the book) 152.1 368.33 T -2 F -(T) 279.79 368.33 T -(cl and the Tk T) 284.43 368.33 T -(oolkit) 343.48 368.33 T -3 F -(.) 366.24 368.33 T --0.26 (The good news about Tk 4.0 is that it has many improvements over Tk 3.6. Here are a) 170.1 356.33 P -(few of the most important new features:) 152.1 344.33 T -3 12 Q -(\245) 152.1 329.33 T -3 10 Q -(Tk 4.0 includes a general-purpose mechanism for manipulating color images \050Tk 3.6) 162.9 329.33 T -(supports only monochrome images\051.) 162.9 317.33 T -3 12 Q -(\245) 152.1 302.33 T -3 10 Q --0.17 (The text widget in Tk 4.0 includes many new features such as tab stops, embedded win-) 162.9 302.33 P -(dows, horizontal scrolling, and many new formatting options.) 162.9 290.33 T -3 12 Q -(\245) 152.1 275.33 T -3 10 Q -(The binding mechanism in Tk 4.0 is much more powerful in Tk 3.6.) 162.9 275.33 T -3 12 Q -(\245) 152.1 260.33 T -3 10 Q -(Motif compliance is much better) 162.9 260.33 T -(. For example, there is now support for keyboard tra-) 292.82 260.33 T -(versal and focus highlights.) 162.9 248.33 T -3 12 Q -(\245) 152.1 233.33 T -3 10 Q -(Many widgets have been improved. For example, buttons and labels can display multi-) 162.9 233.33 T -(line justi\336ed text, and scales can handle real values.) 162.9 221.33 T -(The bad news about Tk 4.0 is that it contains several incompatibilities with Tk 3.6.) 170.1 206.33 T -(Ever since the \336rst release of Tk I have assumed that there would eventually be a major) 152.1 194.33 T -(new release of Tk with substantial incompatibilities. I knew that I wouldn\325) 152.1 182.33 T -(t be able to get) 450.06 182.33 T -(all of the features of Tk right the \336rst time; rather than live forever with all of my early) 152.1 170.33 T -(mistakes, I wanted to have a chance to correct them. Tk 4.0 is that correction. I apologize) 152.1 158.33 T --0.05 (for the incompatibilities, but I hope they improve Tk enough to justify the dif) 152.1 146.33 P --0.05 (\336culties you) 460.55 146.33 P -44.1 351 98.1 423 C -35.1 360 197.1 414 R -7 X -0 K -V -1 9 Q -0 X -(FIGURE 1) 35.1 408 T -(T) 35.1 387 T -(ABLE 1) 40.43 387 T -26.1 351 125.1 423 R -7 X -V -40.5 63 571.5 729 C -FMENDPAGE -%%EndPage: "1" 2 -%%Page: "2" 2 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(2) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X -(encounter during porting. Tk 4.0 is a one-time correction: we will try very hard to avoid) 152.1 632.33 T -(substantial incompatibilities \050especially in Tk\325) 152.1 620.3 T -(s T) 337 620.3 T -(cl-level interfaces\051 in future releases.) 348.79 620.3 T --0.4 (Sections 1-1) 170.1 608.3 P --0.4 (1 cover the major areas of change in Tk 4.0: bindings, focus, text widgets,) 219.02 608.3 P --0 (Motif compliance, other widget changes, images, color management, event handling, sup-) 152.1 596.26 P -(port for multiple displays, the) 152.1 584.23 T -5 F -(send) 273.14 584.23 T -3 F -( command, and the selection. Section 12 summarizes) 297.13 584.23 T -(several smaller changes. Section 13 lists all of the incompatibilities that af) 152.1 572.19 T -(fect T) 448.4 572.19 T -(cl scripts,) 471.29 572.19 T --0.02 (along with suggestions for how to deal with them. The explanations here are not intended) 152.1 560.16 P -(to be comprehensive, but rather to introduce you to the issues; for complete information) 152.1 548.12 T -(on new or modi\336ed commands, refer to the reference documentation that comes with the) 152.1 536.09 T -(distribution.) 152.1 524.05 T -98.1 480.7 512.1 483.72 C -152.1 481.92 512.1 481.92 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 482.21 143.1 482.21 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(1) 134.63 487.72 T -(Bindings) 152.1 487.72 T -3 10 Q --0.35 (The changes for Tk 4.0 that are most likely to af) 152.1 464.03 P --0.35 (fect existing T) 341.31 464.03 P --0.35 (cl scripts are those related to) 397.64 464.03 P -(bindings. The new binding mechanism in Tk 4.0 is much more powerful than that of Tk) 152.1 452 T -(3.6, particularly in the way it allows behaviors to be combined, but several incompatible) 152.1 439.96 T -(changes were required to implement the new features. These changes are likely to break) 152.1 427.93 T -(most Tk 3.6 scripts. Fortunately) 152.1 415.89 T -(, it is relatively easy to upgrade your bindings to work) 279.16 415.89 T -(under Tk 4.0.) 152.1 403.86 T --0.27 (The basic mechanism for bindings is the same as in Tk 3.6. A binding associates a T) 170.1 391.86 P --0.27 (cl) 502.65 391.86 P -(script with a particular event \050or sequence of events\051 occurring in one or more windows;) 152.1 379.82 T --0.11 (the script will be invoked automatically whenever the event sequence occurs in any of the) 152.1 367.79 P --0.13 (speci\336ed windows. The Tk 4.0 binding mechanism has three major feature changes. First,) 152.1 355.75 P -(there is a more general mechanism for specifying the relationship between windows and) 152.1 343.72 T -(bindings, called) 152.1 331.68 T -2 F -(binding tags) 217.89 331.68 T -3 F -(. Second, the con\337ict resolution mechanism \050which is) 267.6 331.68 T -(invoked when more than one binding matches an event\051 has been changed to allow more) 152.1 319.65 T -(than one binding script to execute for a single event. Third, the) 152.1 307.61 T -5 F -(Any) 405.81 307.61 T -3 F -( modi\336er is now) 423.8 307.61 T -(implicit in all binding patterns. These changes are discussed separately in the subsections) 152.1 295.58 T -(that follow) 152.1 283.54 T -(.) 195.04 283.54 T --0.16 (Overall, the main ef) 170.1 271.54 P --0.16 (fect of Tk 4.0\325) 249.37 271.54 P --0.16 (s binding changes is that it allows more bindings to) 306.06 271.54 P -(trigger than Tk 3.6 does. Feedback from the T) 152.1 259.51 T -(cl/Tk community about the Tk 3.6 binding) 335.71 259.51 T -(mechanism indicated that it was too conservative about triggering bindings. This caused) 152.1 247.47 T -(the system to lose behaviors relatively easily and made the binding structure fragile. It) 152.1 235.44 T --0.35 (appears to be easier to deal with too many binding invocations than too few) 152.1 223.4 P --0.35 (, so Tk 4.0 tries) 449.17 223.4 P -(to err in this direction.) 152.1 211.37 T -0 F -(1.1) 127.41 181.37 T -(Binding tags) 152.1 181.37 T -3 F -(In Tk 3.6 you specify the window\050s\051 for a binding in one of three ways:) 152.1 165.37 T -3 12 Q -(\245) 152.1 150.37 T -3 10 Q -(Y) 162.9 150.37 T -(ou give the name of a window) 169.12 150.37 T -(, such as) 289.49 150.37 T -5 F -(.a.b.c) 326.13 150.37 T -3 F -(, in which case the binding applies) 362.11 150.37 T -(only to that window) 162.9 138.33 T -(.) 242.49 138.33 T -FMENDPAGE -%%EndPage: "2" 3 -%%Page: "3" 3 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(1 Bindings) 98.1 668.33 T -0 F -(3) 506.54 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 12 Q -0 X -(\245) 152.1 632.33 T -3 10 Q --0.06 (Y) 162.9 632.33 P --0.06 (ou give the name of a class, such as) 169.12 632.33 P -5 F --0.15 (Button) 313.45 632.33 P -3 F --0.06 (, in which case the binding applies to all) 349.43 632.33 P -(the windows of that class.) 162.9 620.33 T -3 12 Q -(\245) 152.1 605.33 T -3 10 Q -(Y) 162.9 605.33 T -(ou specify) 169.12 605.33 T -5 F -(all) 212.97 605.33 T -3 F -(, in which case the binding applies to all windows.) 230.96 605.33 T --0.3 (In Tk4.0 you specify the window\050s\051 using a more general mechanism called a) 170.1 590.33 P -2 F --0.3 (binding) 479.35 590.33 P -(tag) 152.1 578.33 T -3 F -(. A binding tag may be an arbitrary string, but if it starts with a \322.\323 then it must be the) 164.87 578.33 T -(name of a window) 152.1 566.33 T -(. If you specify a class name or) 225.56 566.33 T -5 F -(all) 352.4 566.33 T -3 F -( as a binding tag, it will usually) 370.39 566.33 T --0.1 (have the same ef) 152.1 554.33 P --0.1 (fect as in Tk 3.6, but you may also specify other strings that were not per-) 218.51 554.33 P -(mitted in Tk 3.6.) 152.1 542.33 T --0.07 (Each window in Tk 4.0 has a list of binding tags. When an event occurs in a window) 170.1 530.33 P --0.07 (,) 507.17 530.33 P --0.19 (Tk fetches the window\325) 152.1 518.33 P --0.19 (s binding tags and matches the event against all of the bindings for) 245.62 518.33 P --0.09 (any of the tags. By default, the binding tags for a window consist of the window name, its) 152.1 506.33 P --0.14 (class name, the name of its nearest toplevel ancestor) 152.1 494.33 P --0.14 (, and) 359.61 494.33 P -5 F --0.33 (all) 381.26 494.33 P -3 F --0.14 (. For example, a button win-) 399.25 494.33 P -(dow named) 152.1 482.33 T -5 F -(.b) 200.95 482.33 T -3 F -( will have the tags) 212.95 482.33 T -5 9 Q -(.b Button . all) 179.1 468 T -3 10 Q -(by default and all of the following bindings will apply to the window:) 152.1 454.33 T -5 9 Q -(bind .b <Enter> {identify "press here to exit"}) 179.1 440 T -(bind Button <Button-Release-1> {%W invoke}) 179.1 430 T -(bind all <Help> {help %W}) 179.1 420 T -3 10 Q -(So far) 152.1 406.33 T -(, this mechanism produces the same behavior as in Tk 3.6 except that bindings cre-) 175.85 406.33 T -(ated for a toplevel also apply to its descendants \050see Section 1.5 for more on this issue\051.) 152.1 394.33 T -(Y) 170.1 382.33 T -(ou can use the) 176.32 382.33 T -5 F -(bindtags) 235.71 382.33 T -3 F -( command to change the binding tags for a window or) 283.69 382.33 T -(their order) 152.1 370.33 T -(. For example, the command) 193.46 370.33 T -5 9 Q -(bindtags .b {.b MyButton all}) 179.1 356 T -3 10 Q -(will change the binding tags for) 152.1 342.33 T -5 F -(.b) 281.46 342.33 T -3 F -( to the three values in the list. This provides a simple) 293.45 342.33 T -(way to make radical changes the behavior of a window) 152.1 330.33 T -(. After the above command is) 371.55 330.33 T -(invoked none of the) 152.1 318.33 T -5 F -(Button) 234.26 318.33 T -3 F -( class bindings will apply to) 270.24 318.33 T -5 F -(.b) 384.63 318.33 T -3 F -(. Instead, bindings for) 396.63 318.33 T -5 F --0.81 (MyButton) 152.1 306.33 P -3 F --0.34 ( will apply; this might give the button a totally dif) 200.07 306.33 P --0.34 (ferent set of behaviors than a) 395.88 306.33 P -(normal button. In addition, the) 152.1 294.33 T -5 F -(bindtags) 276.75 294.33 T -3 F -( command removes the \322.\323 tag, so bindings on) 324.72 294.33 T -(\322.\323 will not apply to) 152.1 282.33 T -5 F -(.b) 234.27 282.33 T -3 F -(.) 246.27 282.33 T -(Y) 170.1 270.33 T -(ou can also place additional tags on a window with the) 176.32 270.33 T -5 F -(bindtags) 397.55 270.33 T -3 F -( command to) 445.53 270.33 T -(combine a number of behaviors. For example,) 152.1 258.33 T -5 9 Q -(bindtags .b {.b MyButton Button . all}) 179.1 244 T -3 10 Q -(gives) 152.1 230.33 T -5 F -(.b) 175.7 230.33 T -3 F -( the behaviors of) 187.69 230.33 T -5 F -(MyButton) 257.08 230.33 T -3 F -( bindings as well as those speci\336ed by) 305.06 230.33 T -5 F -(Button) 459.96 230.33 T -3 F -(bindings.) 152.1 218.33 T -(Overall, binding tags are similar to the tag mechanisms already used internally by) 170.1 206.33 T -(canvas and text widgets in Tk 3.6, except that binding tags apply to windows instead of) 152.1 194.33 T -(graphical objects or textual characters.) 152.1 182.33 T -FMENDPAGE -%%EndPage: "3" 4 -%%Page: "4" 4 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(4) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -0 F -0 X -(1.2) 127.41 632.33 T -(Con\337ict resolution) 152.1 632.33 T -3 F -(It is possible for several bindings to match a particular event. In Tk 3.6 at most one event) 152.1 616.33 T -(is actually allowed to trigger: a set of con\337ict resolution rules determines the winner) 152.1 604.22 T -(. In) 488.27 604.22 T -(general, a more speci\336c binding takes precedence over a less speci\336c binding. For exam-) 152.1 592.11 T --0.27 (ple, any binding for a speci\336c widget takes precedence over any class or) 152.1 580 P -5 F --0.66 (all) 439.96 580 P -3 F --0.27 ( binding, and) 457.95 580 P -(a binding on) 152.1 567.89 T -5 F -(<Control-a>) 204.57 567.89 T -3 F -( takes precedence over a binding on) 270.54 567.89 T -5 F -(<KeyPress>.) 416.24 567.89 T -3 F --0.26 (The mechanism for con\337ict resolution is similar in Tk 4.0 except that one binding can) 170.1 555.89 P --0.35 (trigger for) 152.1 543.78 P -2 F --0.35 (each) 194.7 543.78 P -3 F --0.35 ( binding tag on the window where the event occurs. The bindings trigger in) 213.57 543.78 P -(the order of the tags. Thus if button) 152.1 531.67 T -5 F -(.b) 296.17 531.67 T -3 F -( has the default binding tags, one binding for) 308.16 531.67 T -5 F -(.b) 489.71 531.67 T -3 F -(can trigger) 152.1 519.56 T -(, followed by one for) 194.72 519.56 T -5 F -(Button) 281.32 519.56 T -3 F -(, followed by one for \322) 317.3 519.56 T -5 F -(.) 408.34 519.56 T -3 F -(\323, followed by one for) 414.34 519.56 T -5 F -(all) 152.1 507.44 T -3 F -(. If there are no matching bindings for a given tag then none will trigger) 170.09 507.44 T -(, and if there) 456.98 507.44 T -(are several matching bindings for a given tag then a single one is chosen using the same) 152.1 495.33 T -(rules as in Tk 3.6.) 152.1 483.22 T -(The philosophy behind binding tags in Tk 4.0 is that each binding tag corresponds to) 170.1 471.22 T -(an independent behavior) 152.1 459.11 T -(, so bindings with dif) 249.96 459.11 T -(ferent tags should usually be additive. Sup-) 334.46 459.11 T -(pose you de\336ned the following binding:) 152.1 447 T -5 9 Q -(bind .b <Enter> {puts "press here to exit"}) 179.1 432.67 T -3 10 Q -(This binding will add to the behavior de\336ned by the Button class binding for) 152.1 419 T -5 F -(<Enter>) 460.81 419 T -3 F -(.) 502.79 419 T -(In Tk 3.6, the widget-speci\336c binding will replace the class binding, which will break the) 152.1 406.89 T -(behavior of the button so that it no longer has normal button behavior) 152.1 394.78 T -(.) 429.71 394.78 T -(Sometimes there need to be interactions between binding tags. For example, you) 170.1 382.78 T -(might wish to keep most of the default button behavior for) 152.1 370.67 T -5 F -(.b) 388.34 370.67 T -3 F -( but replace the default) 400.33 370.67 T -(behavior for) 152.1 358.56 T -5 F -(<ButtonRelease>) 203.72 358.56 T -3 F -( with some other behavior) 293.67 358.56 T -(. T) 397.49 358.56 T -(o allow bindings to be) 407.9 358.56 T --0.17 (overridden, Tk 4.0 allows the) 152.1 346.44 P -5 F --0.41 (break) 271.44 346.44 P -3 F --0.17 ( command to be invoked from inside a binding. This) 301.43 346.44 P -(causes all remaining binding tags for that binding to be skipped. Consider the following) 152.1 334.33 T -(binding:) 152.1 322.22 T -5 9 Q -(bind .b <ButtonRelease-1> {myRelease .b; break}) 179.1 307.89 T -3 10 Q --0.21 (This will cause the) 152.1 294.22 P -5 F --0.5 (myRelease) 228.99 294.22 P -3 F --0.21 ( procedure to be invoked, then the) 282.96 294.22 P -5 F --0.5 (break) 420.28 294.22 P -3 F --0.21 ( command will) 450.26 294.22 P --0.37 (cause the class binding for the event to be skipped \050assuming that the widget name appears) 152.1 282.11 P -(before its class in the binding tags for) 152.1 270 T -5 F -(.b) 304.78 270 T -3 F -(\051, along with any bindings for other tags.) 316.77 270 T -2 F -(Note:) 119.09 254 T --0.07 (Y) 152.1 254 P --0.07 (ou cannot invoke) 156.74 254 P -6 F --0.17 (break) 227.31 254 P -2 F --0.07 ( fr) 257.29 254 P --0.07 (om within the) 266.02 254 P -6 F --0.17 (myRelease) 322.73 254 P -2 F --0.07 ( pr) 376.7 254 P --0.07 (ocedur) 387.64 254 P --0.07 (e in the above example:) 415.03 254 P --0.02 (this will generate a T) 152.1 242.89 P --0.02 (cl err) 236.05 242.89 P --0.02 (or) 257.59 242.89 P --0.02 (. However) 265.37 242.89 P --0.02 (, you can invoke the command \322) 305.31 242.89 P -6 F --0.05 (return -code) 434.25 242.89 P -(break) 152.1 231.78 T -2 F -(\323 in the pr) 182.08 231.78 T -(ocedur) 223.64 231.78 T -(e to achieve the same effect as the) 251.03 231.78 T -6 F -(break) 389.25 231.78 T -2 F -( in the binding script.) 419.23 231.78 T -0 F -(1.3) 127.41 202.78 T -(Implicit Any) 152.1 202.78 T -3 F --0.13 (In Tk 3.6 extraneous modi\336ers prevent a binding from matching an event. For example, if) 152.1 186.78 P -(a binding is de\336ned for) 152.1 174.67 T -5 F -(<Button-1>) 247.32 174.67 T -3 F -( and the mouse button is pressed with the) 307.29 174.67 T -5 F -(Num-) 474.68 174.67 T -(Lock) 152.1 162.56 T -3 F -( key down, then the binding will not match. If you want a binding to trigger even) 176.09 162.56 T -(when extraneous modi\336ers are present, you must specify the) 152.1 150.45 T -5 F -(Any) 396.37 150.45 T -3 F -( modi\336er) 414.36 150.45 T -(, as in) 450.33 150.45 T -5 F -(<Any-) 476.42 150.45 T -(Button-1>) 152.1 138.33 T -3 F -(.) 206.07 138.33 T -FMENDPAGE -%%EndPage: "4" 5 -%%Page: "5" 5 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(1 Bindings) 98.1 668.33 T -0 F -(5) 506.54 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X --0.06 (In Tk 4.0, all bindings have the) 170.1 632.33 P -5 F --0.15 (Any) 297.08 632.33 P -3 F --0.06 ( modi\336er present implicitly) 315.08 632.33 P --0.06 (. The) 423.35 632.33 P -5 F --0.15 (Any) 446.26 632.33 P -3 F --0.06 ( modi\336er is) 464.25 632.33 P -(still allowed for compatibility) 152.1 620.33 T -(, but it has no meaning. Thus a binding for) 270.55 620.33 T -5 F -(<Button-1>) 443.23 620.33 T -3 F -(will match a button press event even if) 152.1 608.33 T -5 F -(NumLock) 309.21 608.33 T -3 F -(,) 351.19 608.33 T -5 F -(Shift) 356.19 608.33 T -3 F -(,) 386.17 608.33 T -5 F -(Control) 391.17 608.33 T -3 F -(, or any combina-) 433.15 608.33 T -(tion of them. If you wish for a binding not to trigger when a modi\336er is present, you can) 152.1 596.33 T -(just de\336ne an empty binding for that modi\336er combination. For example,) 152.1 584.33 T -5 9 Q -(bind .b <Control-ButtonPress-1> {# this script is a no-op}) 179.1 570 T -3 10 Q -(creates a binding that will trigger on mouse button presses when the) 152.1 556.33 T -5 F -(Control) 426.36 556.33 T -3 F -( key is) 468.34 556.33 T --0.22 (down. If there is also a) 152.1 544.33 P -5 F --0.52 (<ButtonPress-1>) 244.35 544.33 P -3 F --0.22 ( binding for) 334.3 544.33 P -5 F --0.52 (.b) 383.35 544.33 P -3 F --0.22 (, it will no longer be invoked) 395.34 544.33 P --0.02 (if the) 152.1 532.33 P -5 F --0.05 (Control) 175.37 532.33 P -3 F --0.02 ( key is down, due to the con\337ict resolution rules. The script for the above) 217.35 532.33 P -(binding is just a T) 152.1 520.33 T -(cl comment, so it has no ef) 223.59 520.33 T -(fect when it is invoked. Alternatively) 330.84 520.33 T -(, you) 478.98 520.33 T -(could use) 152.1 508.33 T -5 F -(%s) 192.63 508.33 T -3 F -( in the binding script to extract the modi\336er state, then test to see that only) 204.62 508.33 T -(desired modi\336ers are present.) 152.1 496.33 T -0 F -(1.4) 127.41 466.33 T -(Porting problems: widget bindings vs. class bindings) 152.1 466.33 T -3 F --0.38 (Y) 152.1 450.33 P --0.38 (ou are likely to encounter two problems with bindings when you port Tk 3.6 scripts to Tk) 158.32 450.33 P --0.18 (4.0: widget bindings vs. class bindings, and events on top-level windows. This section dis-) 152.1 438.33 P -(cusses the \336rst problem and the following section discusses the second problem.) 152.1 426.33 T -(In Tk 3.6, if a widget-speci\336c binding matches an event then no class binding will) 170.1 414.33 T --0.15 (trigger for the event; in Tk 4.0 both bindings will trigger) 152.1 402.33 P --0.15 (. Because of this change, you will) 375.75 402.33 P --0.09 (need to modify most of your widget-speci\336c bindings in one of two ways. If a widget-spe-) 152.1 390.33 P -(ci\336c binding in Tk 3.6 was intended to supplement the class binding, this could only be) 152.1 378.33 T -(done by duplicating the code of the class binding in the widget binding script. This dupli-) 152.1 366.33 T --0.02 (cated code is no longer necessary in Tk 4.0 and will probably interfere with the new class) 152.1 354.33 P -(bindings in Tk 4.0; you should remove the duplicated class code, leaving only the widget-) 152.1 342.33 T -(speci\336c code in the binding script. If a widget-speci\336c binding in Tk 3.6 was intended to) 152.1 330.33 T --0.17 (override the class binding, this will no longer occur by default in Tk 4.0; you should add a) 152.1 318.33 P -5 F --0.54 (break) 152.1 306.33 P -3 F --0.22 ( command at the end of the binding script to prevent the class binding from trigger-) 182.08 306.33 P -(ing. If a widget binding in Tk 3.6 didn\325) 152.1 294.33 T -(t con\337ict with a class binding, then you will not) 308.49 294.33 T -(need to modify it for Tk 4.0. For example, a widget binding for) 152.1 282.33 T -5 F -(<Help>) 407.49 282.33 T -3 F -( in a text widget) 443.47 282.33 T -(would not need to be modi\336ed, since it doesn\325) 152.1 270.33 T -(t con\337ict with a class binding.) 336.53 270.33 T -0 F -(1.5) 127.41 240.33 T -(Porting problems: events on top-levels) 152.1 240.33 T -3 F --0.26 (The second binding problem you are likely to encounter in porting Tk 3.6 scripts to Tk 4.0) 152.1 224.33 P -(is that in Tk 4.0 a binding on a toplevel will match events on any of the internal windows) 152.1 212.33 T -(within that top-level. For example, suppose you have a binding created as follows:) 152.1 200.33 T -5 9 Q -(toplevel .t) 179.1 186 T -(button .t.b1 ...) 179.1 176 T -(button .t.b2 ...) 179.1 166 T -(bind .t <Enter> action) 179.1 156 T -FMENDPAGE -%%EndPage: "5" 6 -%%Page: "6" 6 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(6) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X --0.27 (This binding will trigger not only when the mouse enters) 152.1 632.33 P -5 F --0.64 (.t) 379.29 632.33 P -3 F --0.27 (, but also when it enters either) 391.28 632.33 P -5 F -(.t.b1) 152.1 620.33 T -3 F -( or) 182.08 620.33 T -5 F -(.t.b2) 195.41 620.33 T -3 F -(. This is because the binding tags for a window include its nearest) 225.39 620.33 T -(ancestor toplevel by default. The toplevel is present in the binding tags to make it easy to) 152.1 608.33 T -(set up accelerator keys that apply in all the windows of a panel. For example,) 152.1 596.33 T -5 9 Q -(bind .t <Control-a> {controlAProc %W}) 179.1 582 T -3 10 Q -(will cause) 152.1 568.33 T -5 F -(controlAProc) 194.85 568.33 T -3 F -( to be invoked whenever) 266.81 568.33 T -5 F -(Control-a) 367.56 568.33 T -3 F -( is typed in any of the) 421.53 568.33 T --0.12 (windows in) 152.1 556.33 P -5 F --0.29 (.t) 200.72 556.33 P -3 F --0.12 (. The procedure will receive the name of the focus window as its ar) 212.71 556.33 P --0.12 (gument.) 479.62 556.33 P -(Unfortunately) 170.1 544.33 T -(, if you have created bindings on toplevel windows in your Tk 3.6) 225.52 544.33 T --0.16 (scripts, they probably expect to trigger only for events in the toplevel, so the bindings will) 152.1 532.33 P -(misbehave under Tk 4.0. Fortunately you can reproduce the behavior of Tk 3.6 by using) 152.1 520.33 T -(the) 152.1 508.33 T -5 F -(%W) 166.81 508.33 T -3 F -( substitution in the binding script. For example, to ensure that) 178.8 508.33 T -5 F -(action) 427.28 508.33 T -3 F -( is invoked) 463.26 508.33 T -(only for) 152.1 496.33 T -5 F -(Enter) 186.52 496.33 T -3 F -( events in a toplevel window itself, create the following binding in place) 216.51 496.33 T -(of the one above:) 152.1 484.33 T -5 9 Q -(bind .t <Enter> {) 179.1 470 T -(if {"%W" == ".t"} {) 200.63 460 T -(action) 222.23 450 T -(}) 200.63 440 T -(}) 179.1 430 T -3 10 Q --0.01 (When an) 152.1 416.33 P -5 F --0.03 (Enter) 190.38 416.33 P -3 F --0.01 ( event occurs in a descendant of) 220.36 416.33 P -5 F --0.03 (.t) 350.45 416.33 P -3 F --0.01 ( such as) 362.45 416.33 P -5 F --0.03 (.t.x) 396.56 416.33 P -3 F --0.01 (, a binding for) 420.54 416.33 P -5 F --0.03 (Enter) 479.63 416.33 P -3 F -(in) 152.1 404.33 T -5 F -(.t.x) 162.37 404.33 T -3 F -( will trigger \336rst, if there is one. Then the above binding will trigger) 186.36 404.33 T -(. Since) 457.58 404.33 T -5 F -(%W) 487.29 404.33 T -3 F -(will be substituted with) 152.1 392.33 T -5 F -(.t.x) 248.17 392.33 T -3 F -(, the) 272.15 392.33 T -5 F -(if) 291.86 392.33 T -3 F -( condition will not be satis\336ed and the binding will) 303.86 392.33 T -(not do anything.) 152.1 380.33 T --0.14 ( An alternative solution is to remove the toplevel window from the binding tags of all) 170.1 368.33 P --0.12 (its internal windows. However) 152.1 356.33 P --0.12 (, this means that you won\325) 274.03 356.33 P --0.12 (t be able to take advantage of the) 378.73 356.33 P -(tag to create key bindings that apply everywhere within the toplevel.) 152.1 344.33 T -0 F -(1.6) 127.41 314.33 T -(Internal bindings in canvases and texts) 152.1 314.33 T -3 F -(The same changes in con\337ict resolution described in Section 1.2 also apply to bindings) 152.1 298.33 T --0.05 (created internally for the items of a canvas or the tags of a text widget. If a canvas item or) 152.1 286.33 P --0.29 (character of text has multiple tags, then one binding can trigger for each tag on each event.) 152.1 274.33 P --0.32 (The bindings trigger in the priority order of the tags. Similar porting problems are likely to) 152.1 262.33 P --0.19 (occur as described in Section 1.4; if a binding for one tag needs to override that of another) 152.1 250.33 P -(tag, you\325ll need to add a) 152.1 238.33 T -5 F -(break) 251.2 238.33 T -3 F -( command under Tk 4.0; if a binding for one tag dupli-) 281.18 238.33 T --0.28 (cated the code from another tag\325) 152.1 226.33 P --0.28 (s binding, so that they will compose in Tk 3.6, you\325ll have) 279.76 226.33 P -(to remove the duplicated code in Tk 4.0.) 152.1 214.33 T -FMENDPAGE -%%EndPage: "6" 7 -%%Page: "7" 7 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(2 Focus management) 98.1 668.33 T -0 F -(7) 506.54 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -98.1 623.98 512.1 627 C -152.1 625.2 512.1 625.2 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 625.49 143.1 625.49 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(2) 134.63 631 T -(Focus management) 152.1 631 T -3 10 Q -(The input focus is another area where Tk 4.0 contains major changes. Fortunately) 152.1 607.31 T -(, the) 477.87 607.31 T --0.09 (focus changes should not require as many modi\336cations to your Tk 3.6 scripts as the bind-) 152.1 595.31 P -(ing changes.) 152.1 583.31 T -0 F -(2.1) 127.41 553.31 T -(One focus window per toplevel) 152.1 553.31 T -3 F -(Tk 3.6 only keeps track of a single focus window for each application, and this results in) 152.1 537.31 T -(two problems. First, it doesn\325) 152.1 525.31 T -(t allow an application to use multiple displays since this) 269.64 525.31 T --0.16 (could result in multiple simultaneous focus windows, one on each display) 152.1 513.31 P --0.16 (. Second, the Tk) 444.99 513.31 P -(3.6 model doesn\325) 152.1 501.31 T -(t work very well for applications that have multiple toplevels: when the) 221.04 501.31 T -(mouse moves from one toplevel to another) 152.1 489.31 T -(, the focus window should switch to whatever) 322.7 489.31 T --0.24 (window had the focus the last time the mouse was in the new toplevel, but Tk 3.6 does not) 152.1 477.31 P -(remember this information.) 152.1 465.31 T -(Tk 4.0 corrects both of these problems. It remembers one focus window for each) 170.1 453.31 T -(toplevel, which can be queried with the) 152.1 441.31 T -5 F -(focus -lastfor) 311.98 441.31 T -3 F -( command. When the win-) 395.94 441.31 T -(dow manager gives the focus to a toplevel window \050because the mouse entered the win-) 152.1 429.31 T -(dow or because you clicked on the window) 152.1 417.31 T -(, depending on the focus model being used by) 324.38 417.31 T -(the window manager\051, Tk passes the focus on to the remembered window) 152.1 405.31 T -(. Several win-) 446.23 405.31 T -(dows in an application can have the focus at the same time, one on each display the appli-) 152.1 393.31 T -(cation is using. When asking for the current focus window in the) 152.1 381.31 T -5 F -(focus) 413.31 381.31 T -3 F -( command, you) 443.29 381.31 T -(can use the) 152.1 369.31 T -5 F -(-displayof) 199 369.31 T -3 F -( switch to specify a particular display) 258.97 369.31 T -(.) 407.66 369.31 T -(When you set the focus to a window with the) 170.1 357.31 T -5 F -(focus) 353.31 357.31 T -3 F -( command, Tk remembers that) 383.29 357.31 T -(window as the most recent focus window for its toplevel. In addition, if the application) 152.1 345.31 T -(currently has the focus for the window\325) 152.1 333.31 T -(s display) 309.2 333.31 T -(, Tk moves the focus to the speci\336ed win-) 343.82 333.31 T --0.35 (dow; this can be used, for example to move the focus to a dialog when the dialog is posted,) 152.1 321.31 P -(or to perform keyboard traversal among the toplevels of an application. If the application) 152.1 309.31 T -(doesn\325) 152.1 297.31 T -(t currently have the focus for the display) 178.57 297.31 T -(, then Tk will not normally take the focus) 339.74 297.31 T -(from its current owner) 152.1 285.31 T -(. However) 241.2 285.31 T -(, you can specify the) 282.43 285.31 T -5 F -(-force) 367.36 285.31 T -3 F -( ar) 403.34 285.31 T -(gument to) 413.43 285.31 T -5 F -(focus) 456.18 285.31 T -3 F -( to) 486.17 285.31 T -(insist that Tk grab the focus for this application \050in general this is probably not a good) 152.1 273.31 T -(idea, since it may clash with the window manager) 152.1 261.31 T -(\325) 352.05 261.31 T -(s focus policy\051.) 354.83 261.31 T -0 F -(2.2) 127.41 231.31 T -(Keyboard traversal) 152.1 231.31 T -3 F --0.38 (Tk 4.0 has a much more complete implementation of keyboard traversal than Tk 3.6. In Tk) 152.1 215.31 P -(3.6 there is built-in support only for keyboard traversal of menus. In Tk 4.0 keyboard tra-) 152.1 203.31 T -(versal is implemented for all widgets. Y) 152.1 191.31 T -(ou can type) 311.27 191.31 T -5 F -(Tab) 359.85 191.31 T -3 F -( to move the focus among the) 377.84 191.31 T --0.4 (windows within a toplevel and) 152.1 179.31 P -5 F --0.95 (Shift+Tab) 275.31 179.31 P -3 F --0.4 ( to move in the reverse direction. The order of) 329.28 179.31 P --0.11 (traversal is de\336ned by the stacking order of widgets, with the lowest widget \336rst in the tra-) 152.1 167.31 P -(versal order) 152.1 155.31 T -(. All Tk widgets now provide a) 199 155.31 T -5 F -(-takefocus) 326.14 155.31 T -3 F -( option, which determines) 386.11 155.31 T -FMENDPAGE -%%EndPage: "7" 8 -%%Page: "8" 8 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(8) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X -(whether the window should accept the focus during traversal or be skipped. This option) 152.1 632.33 T -(has several features; see the) 152.1 620.33 T -5 F -(options.n) 265.61 620.33 T -3 F -( manual entry for details.) 319.58 620.33 T -(All of the Tk widgets provide a traversal highlight ring as required by Motif. The) 170.1 608.33 T -(highlight ring turns dark when the widget has the input focus. Its size and colors are con-) 152.1 596.33 T -(trolled by the) 152.1 584.33 T -5 F -(-highlightthickness) 207.9 584.33 T -3 F -(,) 321.84 584.33 T -5 F -(-highlightbackground) 326.83 584.33 T -3 F -(, and) 446.77 584.33 T -5 F -(-) 152.1 572.33 T -(highlightcolor) 158.1 572.33 T -3 F -( options. Y) 242.05 572.33 T -(ou may notice that widgets appear to have extra space) 285.2 572.33 T -(around them in Tk 4.0; this is due to the traversal highlight ring, which is normally the) 152.1 560.33 T -(same color as the background for widgets.) 152.1 548.33 T -0 F -(2.3) 127.41 518.33 T -(Support for focus-follows-mouse) 152.1 518.33 T -3 F -(Both Tk 3.6 and Tk 4.0 use an) 152.1 502.33 T -2 F -(explicit focus model) 275.91 502.33 T -3 F -( within a toplevel. This means that) 355.86 502.33 T -(moving the mouse among the windows of a toplevel does not normally move the focus;) 152.1 490.33 T --0.06 (you have to click or perform some other action \050such as pressing) 152.1 478.33 P -5 F --0.15 (Tab) 412.26 478.33 P -3 F --0.06 (\051 to move the focus.) 430.25 478.33 P -(Tk 3.6 has no support for an) 152.1 466.33 T -2 F -(implicit focus model) 267.58 466.33 T -3 F -( where the window under the mouse) 348.64 466.33 T -(always has the focus. In Tk 4.0 you can invoke the library procedure) 152.1 454.33 T -5 F -(tk_focusFol-) 428.83 454.33 T -(lowsMouse) 152.1 442.33 T -3 F -( to switch to an implicit focus model; in this mode whenever the mouse) 206.07 442.33 T -(enters a new window the focus will switch to that window) 152.1 430.33 T -(.) 384.07 430.33 T -0 F -(2.4) 127.41 400.33 T -(No default focus window) 152.1 400.33 T -(, no \322none\323 focus.) 269.45 400.33 T -3 F --0.16 (Tk 3.6 has the notion of a default focus window) 152.1 384.33 P --0.16 (, which receives the focus if the focus win-) 341.56 384.33 P -(dow is deleted. It is also possible for an application to abandon the input focus by setting) 152.1 372.33 T -(the focus to) 152.1 360.33 T -5 F -(none) 201.23 360.33 T -3 F -(. In Tk 4.0 both of these features have been eliminated. There is no) 225.22 360.33 T -(default focus window) 152.1 348.33 T -(, and the focus can never be explicitly abandoned. If the focus win-) 238.05 348.33 T -(dow is destroyed, Tk resets the input focus to the toplevel containing the old focus win-) 152.1 336.33 T -(dow) 152.1 324.33 T -(. If the toplevel is destroyed, the window manager will reclaim the focus and move it) 168.66 324.33 T -(elsewhere.) 152.1 312.33 T --0.18 (If you really want to abandon the focus in Tk 4.0 so that keyboard events are ignored,) 170.1 300.33 P -(you can create a dummy window with no key bindings \050set its binding tags to an empty) 152.1 288.33 T -(string to be sure\051, make sure that is never mapped, and give it the input focus.) 152.1 276.33 T -0 F -(2.5) 127.41 246.33 T -(Better focus events) 152.1 246.33 T -3 F --0.13 (Tk 3.6 has a quirky event model for) 152.1 230.33 P -5 F --0.32 (FocusIn) 296.77 230.33 P -3 F --0.13 ( and) 338.75 230.33 P -5 F --0.32 (FocusOut) 357.92 230.33 P -3 F --0.13 ( events: when the window) 405.89 230.33 P --0.23 (manager gives the focus to a toplevel, Tk generates a) 152.1 218.33 P -5 F --0.55 (FocusIn) 364.36 218.33 P -3 F --0.23 ( event for the toplevel and) 406.33 218.33 P -(another) 152.1 206.33 T -5 F -(FocusIn) 184.57 206.33 T -3 F -( event for the focus window) 226.55 206.33 T -(, but no events for any other windows.) 337.76 206.33 T -(When the window manager moves the focus somewhere else,) 152.1 194.33 T -5 F -(FocusOut) 400.79 194.33 T -3 F -( events are gen-) 448.77 194.33 T --0 (erated for these same two windows. In Tk 4.0,) 152.1 182.33 P -5 F --0 (FocusIn) 339.73 182.33 P -3 F --0 ( and) 381.71 182.33 P -5 F --0 (FocusOut) 401.13 182.33 P -3 F --0 ( events are gen-) 449.11 182.33 P --0.26 (erated in the same way as) 152.1 170.33 P -5 F --0.63 (Enter) 255.43 170.33 P -3 F --0.26 ( and) 285.41 170.33 P -5 F --0.63 (Leave) 304.31 170.33 P -3 F --0.26 ( events: when the focus arrives, a) 334.29 170.33 P -5 F --0.63 (FocusIn) 467.89 170.33 P -3 F --0.05 (event is generated for each window from the toplevel down to the focus window) 152.1 158.33 P --0.05 (, with dif-) 472.5 158.33 P -FMENDPAGE -%%EndPage: "8" 9 -%%Page: "9" 9 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(3 T) 98.1 668.33 T -(ext widgets) 111.43 668.33 T -0 F -(9) 506.54 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X --0.33 (ferent detail \336elds for dif) 152.1 632.33 P --0.33 (ferent windows \050see Xlib documentation for information on these) 250.53 632.33 P -(values\051. The reverse happens when the focus leaves a window) 152.1 620.33 T -(.) 399.57 620.33 T -0 F -(2.6) 127.41 590.33 T -(Porting issues) 152.1 590.33 T -3 F -(If you didn\325) 152.1 574.33 T -(t have any special focus-related code in Tk 3.6, then you shouldn\325) 199.66 574.33 T -(t need to) 462.9 574.33 T -(make any changes for 4.0; things will just work better) 152.1 562.33 T -(. If you wrote code in Tk 3.6 to get) 366.96 562.33 T -(around the weaknesses with its focus mechanism, then you should remove most or all of) 152.1 550.33 T -(that code. For example, if you implemented keyboard traversal yourself, or if you built) 152.1 538.33 T -(your own mechanism to remember a separate focus window for each toplevel and give it) 152.1 526.33 T -(the input focus whenever the toplevel gets the focus, you can simply remove this code,) 152.1 514.33 T --0.33 (since Tk 4.0 performs these functions for you. If you wrote code that depends on the weird) 152.1 502.33 P --0.03 (event model in Tk 3.6, that code will need to be rewritten for Tk 4.0. The Tk 4.0 model is) 152.1 490.33 P -(general enough to duplicate any ef) 152.1 478.33 T -(fects that were possible in Tk 3.6.) 289.86 478.33 T -98.1 434.98 512.1 438 C -152.1 436.2 512.1 436.2 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 436.49 143.1 436.49 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(3) 134.63 442 T -(T) 152.1 442 T -(ext widgets) 158.54 442 T -3 10 Q -(T) 152.1 418.31 T -(ext widgets have under) 157.51 418.31 T -(gone a major overhaul for Tk 4.0 and they have improved in) 249.76 418.31 T -(many ways. The changes to text widgets are almost entirely upward-compatible from Tk) 152.1 406.31 T -(3.6.) 152.1 394.31 T -0 F -(3.1) 127.41 364.31 T -(Embedded windows.) 152.1 364.31 T -3 F -(Tk 3.6 supported two kinds of annotations in texts: marks and tags. In Tk 4.0 a third kind) 152.1 348.31 T --0.04 (of annotation is available: an embedded window) 152.1 336.31 P --0.04 (. This allows you to embed other widgets) 344.99 336.31 P -(inside a text widget, mixed in with the text. The text widget acts as a geometry manager) 152.1 324.31 T -(for these windows, laying them out and wrapping them just as if each embedded window) 152.1 312.31 T -(were a single character in the text. Y) 152.1 300.31 T -(ou can even have texts with nothing in them but) 297.64 300.31 T -(embedded windows. The) 152.1 288.31 T -5 F -(window) 254.8 288.31 T -3 F -( widget command for text widgets provides several) 290.78 288.31 T -(options to manage embedded windows.) 152.1 276.31 T -0 F -(3.2) 127.41 246.31 T -(More options for tags.) 152.1 246.31 T -3 F -(In Tk 4.0 tags support many new options providing additional control over how informa-) 152.1 230.31 T -(tion is displayed. Here is a summary of the new options:) 152.1 218.31 T -3 12 Q -(\245) 152.1 203.31 T -3 10 Q -(Y) 162.9 203.31 T -(ou can now specify tab stops with the) 169.12 203.31 T -5 F -(-tabs) 321.79 203.31 T -3 F -( option. Each tab stop can use left, cen-) 351.78 203.31 T -(ter) 162.9 191.31 T -(, right, or numeric justi\336cation. T) 173.04 191.31 T -(ab stops can also be speci\336ed for the widget as a) 305.6 191.31 T -(whole.) 162.9 179.31 T -3 12 Q -(\245) 152.1 164.31 T -3 10 Q -(Y) 162.9 164.31 T -(ou can specify justi\336cation \050left, center or right\051 with the) 169.12 164.31 T -5 F -(-justify) 398.12 164.31 T -3 F -( option.) 446.09 164.31 T -FMENDPAGE -%%EndPage: "9" 10 -%%Page: "10" 10 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(10) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 12 Q -0 X -(\245) 152.1 632.33 T -3 10 Q -(Y) 162.9 632.33 T -(ou can now specify line spacing with three options,) 169.12 632.33 T -5 F -(-spacing1) 376.75 632.33 T -3 F -(,) 430.72 632.33 T -5 F -(-spacing2) 435.72 632.33 T -3 F -(, and) 489.69 632.33 T -5 F -(-) 162.9 620.2 T -(spacing3) 168.9 620.2 T -3 F -(, which control the spacing above a line, between wrapped lines, and) 216.87 620.2 T -(below a line.) 162.9 608.06 T -3 12 Q -(\245) 152.1 593.06 T -3 10 Q -(Y) 162.9 593.06 T -(ou can now specify mar) 169.12 593.06 T -(gins with the) 264.41 593.06 T -5 F -(-lmargin1) 318.55 593.06 T -3 F -(,) 372.52 593.06 T -5 F -(-lmargin2) 377.52 593.06 T -3 F -(, and) 431.49 593.06 T -5 F -(-rmargin) 453.42 593.06 T -3 F -(options.) 162.9 580.92 T -3 12 Q -(\245) 152.1 565.92 T -3 10 Q --0.25 (Y) 162.9 565.92 P --0.25 (ou can now adjust the vertical position of text \050e.g. for superscripts or subscripts\051 with) 169.12 565.92 P -(the) 162.9 553.79 T -5 F -(-offset) 177.61 553.79 T -3 F -( option.) 219.59 553.79 T -3 12 Q -(\245) 152.1 538.79 T -3 10 Q --0.03 (Y) 162.9 538.79 P --0.03 (ou can now specify the wrapping style \050word wrapping, character wrapping, or none\051) 169.12 538.79 P -(with the) 162.9 526.65 T -5 F -(-wrap) 197.88 526.65 T -3 F -( option.) 227.86 526.65 T -3 12 Q -(\245) 152.1 511.65 T -3 10 Q -(Y) 162.9 511.65 T -(ou can now request overstriking with the) 169.12 511.65 T -5 F -(-overstrike) 334.83 511.65 T -3 F -( option.) 400.8 511.65 T -0 F -(3.3) 127.41 481.65 T -(Bindings) 152.1 481.65 T -3 F --0.19 (The default bindings for text widgets have been completely rewritten in Tk 4.0. They now) 152.1 465.65 P -(support almost all of the Motif behavior \050everything except add mode and secondary) 152.1 453.52 T --0.36 (selections\051. They also include a substantial subset of the Emacs bindings for cursor motion) 152.1 441.38 P -(and basic editing. The) 152.1 429.24 T -5 F -(tk_strictMotif) 242.87 429.24 T -3 F -( variable disables the Emacs bindings.) 326.82 429.24 T -0 F -(3.4) 127.41 399.24 T -(Miscellaneous new features) 152.1 399.24 T -3 F -(In addition to the major changes described above, text widgets also include the following) 152.1 383.24 T -(new features:) 152.1 371.11 T -1 F -(Horizontal scr) 162.9 356.11 T -(olling) 224.07 356.11 T -3 F -(. T) 247.95 356.11 T -(ext widgets can now be scrolled horizontally as well as verti-) 258.36 356.11 T -(cally) 162.9 343.97 T -(, using the) 181.68 343.97 T -5 F -(-) 225.55 343.97 T -(xscrollcommand) 231.54 343.97 T -3 F -( option and the) 315.5 343.97 T -5 F -(xview) 377.68 343.97 T -3 F -( widget command.) 407.67 343.97 T -1 F -(Sear) 162.9 328.97 T -(ching) 182.15 328.97 T -3 F -(. T) 205.48 328.97 T -(ext widgets have a new) 215.88 328.97 T -5 F -(search) 311.64 328.97 T -3 F -( widget command, which provides ef) 347.62 328.97 T -(\336-) 495.67 328.97 T --0.19 (cient searching of text widgets using either exact matching, glob-style matching, or reg-) 162.9 316.83 P -(ular expressions. Y) 162.9 304.7 T -(ou can search forwards or backwards.) 238.79 304.7 T -1 F -(Mark gravity) 162.9 289.7 T -3 F -(. In Tk 3.6 marks always had \322right gravity\323, which means they stick to) 219.71 289.7 T -(the character on the right side of the mark; if you insert at the position of a mark, the) 162.9 277.56 T --0.1 (new character goes before the mark. In Tk 4.0 you can specify whether marks have left) 162.9 265.42 P -(or right gravity) 162.9 253.29 T -(.) 222.77 253.29 T -1 F -(Scr) 162.9 238.29 T -(een information) 177.15 238.29 T -3 F -(. In Tk 4.0 there are two new widget commands for text widgets) 245.16 238.29 T -(that return information about the screen layout. The) 162.9 226.15 T -5 F -(dlineinfo) 371.92 226.15 T -3 F -( widget command) 425.89 226.15 T -(returns the bounding box of a display line \050all the information displayed on one line of) 162.9 214.02 T -(the window) 162.9 201.88 T -(, which may be either a whole line of text or a partial line if wrapping has) 209.16 201.88 T -(occurred\051. The) 162.9 189.74 T -5 F -(bbox) 224.23 189.74 T -3 F -( widget command returns the screen area occupied by a single) 248.21 189.74 T -(character) 162.9 177.61 T -(.) 198.97 177.61 T -1 F -(Extended insert command) 162.9 162.61 T -3 F -(. The) 275.06 162.61 T -5 F -(insert) 298.1 162.61 T -3 F -( widget command now supports an addi-) 334.08 162.61 T --0.32 (tional ar) 162.9 150.47 P --0.32 (gument giving a list of tags to apply to the new characters. Y) 195.43 150.47 P --0.32 (ou can also include) 434 150.47 P -(several text and tag ar) 162.9 138.33 T -(guments in a single) 250.42 138.33 T -5 F -(insert) 330.38 138.33 T -3 F -( command.) 366.36 138.33 T -FMENDPAGE -%%EndPage: "10" 11 -%%Page: "11" 11 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(4 Better Motif compliance) 98.1 668.33 T -0 F -(1) 501.54 668.33 T -(1) 506.54 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -1 F -0 X -(See command) 162.9 632.33 T -3 F -(. There is a new) 222.03 632.33 T -5 F -(see) 288.08 632.33 T -3 F -( widget command, which adjusts the view in the) 306.07 632.33 T -(widget if needed to ensure that a particular character is visible in the window) 162.9 620.29 T -(.) 470.07 620.29 T -0 F -(3.5) 127.41 590.29 T -(Porting issues: tag stickiness, change in end) 152.1 590.29 T -3 F -(There are two changes in text widgets that may require modi\336cations to Tk 3.6 scripts.) 152.1 574.29 T --0.06 (The \336rst change has to do with tag stickiness. In Tk 3.6, tags are sticky to the right: if you) 152.1 562.24 P -(insert new text just after a tagged range, the new text acquires the tags of the preceding) 152.1 550.19 T -(character) 152.1 538.14 T -(. If you insert text before a tagged range in Tk 3.6, the new characters do not) 188.17 538.14 T --0.34 (acquire the tags of the range. In Tk 4.0, tags are not sticky on either side: new text acquires) 152.1 526.09 P -(a tag from surrounding characters only if the tag is present on both sides of the insertion) 152.1 514.05 T -(position. The sticky behavior in Tk 3.6 was rarely useful and special code was often) 152.1 502 T -(needed to work around it. Y) 152.1 489.95 T -(ou should be able to eliminate this code in Tk 4.0.) 263.24 489.95 T -(The second incompatible change in text widgets is that the index) 170.1 477.95 T -5 F -(end) 431.32 477.95 T -3 F -( now refers to) 449.31 477.95 T --0.14 (the position just after the \336nal newline in the text, whereas in Tk 3.6 it referred to the posi-) 152.1 465.9 P --0.1 (tion just before the \336nal newline. This makes it possible to apply tags to the \336nal newline,) 152.1 453.86 P -(which was not possible in Tk 3.6, but you may need to modify your scripts if you depend) 152.1 441.81 T -(on the old position of) 152.1 429.76 T -5 F -(end) 240.11 429.76 T -3 F -(.) 258.1 429.76 T -98.1 386.4 512.1 389.43 C -152.1 387.63 512.1 387.63 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 387.92 143.1 387.92 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(4) 134.63 393.43 T -(Better Motif compliance) 152.1 393.43 T -3 10 Q -(All of the widgets have been modi\336ed in Tk 4.0 to improve their Motif compliance. This) 152.1 369.74 T --0.3 (was done by adding features that were missing and reworking the bindings to comply with) 152.1 357.69 P -(Motif conventions. I believe that the widgets are now completely Motif compliant except) 152.1 345.64 T -(for the following missing features:) 152.1 333.6 T -3 12 Q -(\245) 152.1 318.6 T -3 10 Q -(There is no support for secondary selections.) 162.9 318.6 T -3 12 Q -(\245) 152.1 303.6 T -3 10 Q -(There is no support for \322add mode\323 in widgets such as texts and listboxes.) 162.9 303.6 T -3 12 Q -(\245) 152.1 288.6 T -3 10 Q -(There is no support for drag and drop.) 162.9 288.6 T --0.02 (Please let me know if you \336nd any other discrepancies between the Tk widgets and Motif) 152.1 273.59 P -(widgets. W) 152.1 261.55 T -(e plan to eliminate the remaining incompatibilities over the next year or two.) 196.82 261.55 T -98.1 218.19 512.1 221.21 C -152.1 219.41 512.1 219.41 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 219.7 143.1 219.7 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(5) 134.63 225.21 T -(W) 152.1 225.21 T -(idget changes) 163.31 225.21 T -3 10 Q --0.07 (All of the Tk 4.0 widgets have been improved over their 3.6 counterparts, mostly in small) 152.1 201.52 P --0.23 (and backwards compatible ways. Here is a summary of the widget improvements; see Sec-) 152.1 189.48 P -(tion 13 for information about incompatible changes.) 152.1 177.43 T -3 12 Q -(\245) 152.1 162.43 T -3 10 Q -(All widgets now have a) 162.9 162.43 T -5 F -(cget) 259.78 162.43 T -3 F -( command, which provides an easier way to retrieve the) 283.76 162.43 T -(value of a con\336guration option. In other situations where con\336guration options are) 162.9 150.38 T -(used, such as for menu entries or text tags, a) 162.9 138.33 T -5 F -(cget) 342.21 138.33 T -3 F -( command is also available.) 366.2 138.33 T -FMENDPAGE -%%EndPage: "11" 12 -%%Page: "12" 12 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(12) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 12 Q -0 X -(\245) 152.1 632.33 T -3 10 Q --0.22 (All widgets now have) 162.9 632.33 P -5 F --0.53 (-highlightthickness) 251.96 632.33 P -3 F --0.22 (,) 365.9 632.33 P -5 F --0.53 (-highlightbackground) 370.68 632.33 P -3 F --0.22 (, and) 490.61 632.33 P -5 F -(-) 162.9 620.33 T -(highlightcolor) 168.9 620.33 T -3 F -( options for displaying a highlight ring when the widget \050or one) 252.85 620.33 T -(of its descendants\051 has the input focus.) 162.9 608.33 T -3 12 Q -(\245) 152.1 593.33 T -3 10 Q -(Entry widgets now support justi\336cation and provide a) 162.9 593.33 T -5 F -(-show) 379.99 593.33 T -3 F -( option for \050not\051 display-) 409.97 593.33 T -(ing passwords. They will autosize to \336t their text if) 162.9 581.33 T -5 F -(-width 0) 369.17 581.33 T -3 F -( is speci\336ed.) 417.14 581.33 T -3 12 Q -(\245) 152.1 566.33 T -3 10 Q --0.16 (The label/button family of widgets now supports multiline text and justi\336cation, includ-) 162.9 566.33 P -(ing new options) 162.9 554.33 T -5 F -(-wraplength) 229.25 554.33 T -3 F -( and) 295.22 554.33 T -5 F -(-justify) 314.65 554.33 T -3 F -(. These features make the message) 361.97 554.33 T --0.04 (widget obsolete. There is also a new) 162.9 542.33 P -5 F --0.1 (-underline) 310.27 542.33 P -3 F --0.04 ( option for highlighting a character) 370.23 542.33 P -(for keyboard traversal.) 162.9 530.33 T -3 12 Q -(\245) 152.1 515.33 T -3 10 Q --0.23 (Listboxes now support all of the Motif selection modes, including single selection, mul-) 162.9 515.33 P -(tiple selection, and multiple disjoint selections, via the) 162.9 503.33 T -5 F -(-selectmode) 382.78 503.33 T -3 F -( option. They) 448.74 503.33 T -(will autosize to \336t their contents if) 162.9 491.33 T -5 F -(-width 0) 302.54 491.33 T -3 F -( or) 350.52 491.33 T -5 F -(-height 0) 363.84 491.33 T -3 F -( is speci\336ed. There are) 417.81 491.33 T -(new) 162.9 479.33 T -5 F -(see) 182.05 479.33 T -3 F -(,) 200.04 479.33 T -5 F -(bbox) 205.04 479.33 T -3 F -(, and) 229.02 479.33 T -5 F -(activate) 250.95 479.33 T -3 F -( widget commands.) 298.92 479.33 T -3 12 Q -(\245) 152.1 464.33 T -3 10 Q -(Canvas polygons now support) 162.9 464.33 T -5 F -(-outline) 286.16 464.33 T -3 F -( and) 334.14 464.33 T -5 F -(-width) 353.57 464.33 T -3 F -( options for drawing outlines.) 389.55 464.33 T -3 12 Q -(\245) 152.1 449.33 T -3 10 Q --0.03 (Scale widgets now support real values as well as integers \050see the) 162.9 449.33 P -5 F --0.08 (-resolution) 426.77 449.33 P -3 F --0.03 ( and) 492.73 449.33 P -5 F --0.54 (-digits) 162.9 437.33 P -3 F --0.22 ( options\051, and they have a) 204.88 437.33 P -5 F --0.54 (-variable) 308.73 437.33 P -3 F --0.22 ( option to link to a T) 362.7 437.33 P --0.22 (cl variable. They) 442.83 437.33 P --0.28 (have two new widget commands,) 162.9 425.33 P -5 F --0.67 (coords) 297.52 425.33 P -3 F --0.28 ( and) 333.5 425.33 P -5 F --0.67 (identify) 352.37 425.33 P -3 F --0.28 (, and their bindings are now) 399.69 425.33 P -(de\336ned in T) 162.9 413.33 T -(cl rather than being hardwired in C code as in Tk 3.6.) 210.5 413.33 T -3 12 Q -(\245) 152.1 398.33 T -3 10 Q -(Scrollbar widgets now have a new interface to the controlling widget, which provides) 162.9 398.33 T --0.04 (more \337exibility than the old style \050but the old style is still supported for compatibility\051.) 162.9 386.33 P -(There is a new option) 162.9 374.33 T -5 F -(-jump) 252 374.33 T -3 F -( to prevent continuous updates while dragging the slider) 281.98 374.33 T -(,) 505.88 374.33 T --0.24 (and a new option) 162.9 362.33 P -5 F --0.59 (-elementborderwidth) 232.98 362.33 P -3 F --0.24 ( to control the border width of the arrows) 346.92 362.33 P -(and slider separately from the widget\325) 162.9 350.33 T -(s outer border) 314.18 350.33 T -(. There are four new widget com-) 369.14 350.33 T -(mands,) 162.9 338.33 T -5 F -(activate) 193.99 338.33 T -3 F -(,) 241.97 338.33 T -5 F -(delta) 246.96 338.33 T -3 F -(,) 276.95 338.33 T -5 F -(fraction) 281.95 338.33 T -3 F -(, and) 329.92 338.33 T -5 F -(identify) 351.85 338.33 T -3 F -(, and the default bindings) 399.17 338.33 T -(are now de\336ned in T) 162.9 326.33 T -(cl rather than being hardwired in C code as in Tk 3.6.) 244.91 326.33 T -3 12 Q -(\245) 152.1 311.33 T -3 10 Q --0.13 (Menu entries now have several new con\336guration options such as) 162.9 311.33 P -5 F --0.31 (-foreground) 426.97 311.33 P -3 F --0.13 ( and) 492.93 311.33 P -5 F --0.41 (-) 162.9 299.33 P --0.41 (indicatoron) 168.9 299.33 P -3 F --0.17 (, and tear) 234.86 299.33 P --0.17 (-of) 271.23 299.33 P --0.17 (f menus have been reimplemented to be more Motif-like.) 282.7 299.33 P -(New menu entries can be created in the middle of a menu using the) 162.9 287.33 T -5 F -(insert) 434.36 287.33 T -3 F -( widget) 470.34 287.33 T -(command, and there is a) 162.9 275.33 T -5 F -(type) 262.83 275.33 T -3 F -( widget command that returns the type of a menu entry) 286.81 275.33 T -(.) 505.45 275.33 T -3 12 Q -(\245) 152.1 260.33 T -3 10 Q -(Menubuttons now have a) 162.9 260.33 T -5 F -(-indicatoron) 266.16 260.33 T -3 F -( option for displaying an option menu indi-) 338.12 260.33 T --0.38 (cator) 162.9 248.33 P --0.38 (. There is now support for option menus via the) 182.33 248.33 P -5 F --0.91 (tk_optionMenu) 370.9 248.33 P -3 F --0.38 ( procedure, and) 448.86 248.33 P -(popups are simpli\336ed with the) 162.9 236.33 T -5 F -(tk_popup) 286.44 236.33 T -3 F -( procedure.) 334.42 236.33 T -3 12 Q -(\245) 152.1 221.33 T -3 10 Q --0.03 (The variable) 162.9 221.33 P -5 F --0.07 (tk_strictMotif) 215.57 221.33 P -3 F --0.03 ( is used in more places to enforce even stricter Motif) 299.53 221.33 P -(compliance.) 162.9 209.33 T -FMENDPAGE -%%EndPage: "12" 13 -%%Page: "13" 13 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(6 Images) 98.1 668.33 T -0 F -(13) 500.99 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -98.1 623.98 512.1 627 C -152.1 625.2 512.1 625.2 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 625.49 143.1 625.49 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(6) 134.63 631 T -(Images) 152.1 631 T -3 10 Q -(Tk 4.0 contains a general-purpose image mechanism for displaying color pictures and) 152.1 607.31 T -(other complex objects. There is a new command,) 152.1 595.26 T -5 F -(image) 350.84 595.26 T -3 F -(, which may be used to create) 380.82 595.26 T -(image objects. For example, the command) 152.1 583.21 T -5 9 Q -(image create photo myFace -f) 179.1 568.88 T -(ile picture.ppm) 330.09 568.88 T -3 10 Q -(creates a new image named) 152.1 555.21 T -5 F -(myFace) 264.5 555.21 T -3 F -(. The image is of type) 300.48 555.21 T -5 F -(photo) 390.14 555.21 T -3 F -( \050a full-color represen-) 420.12 555.21 T -(tation that dithers on monochrome or color) 152.1 543.17 T -(-mapped displays\051 and the source data for the) 323.46 543.17 T -(image is in the \336le named) 152.1 531.12 T -5 F -(picture.ppm) 257.59 531.12 T -3 F -(. Once an image has been created, it can be) 323.56 531.12 T --0.15 (used in many dif) 152.1 519.07 P --0.15 (ferent places by specifying a) 218.37 519.07 P -5 F --0.36 (-image) 334.46 519.07 P -3 F --0.15 ( option. For example, the command) 370.44 519.07 P -5 9 Q -(label .l -image myFace) 179.1 504.74 T -3 10 Q -(will create a label widget that displays the image, and if) 152.1 491.07 T -5 F -(.c) 377.5 491.07 T -3 F -( is a canvas widget the com-) 389.49 491.07 T -(mand) 152.1 479.02 T -5 9 Q -(.c create image 400 200 -image myFace) 179.1 464.69 T -3 10 Q -(will create an image item in the canvas that displays) 152.1 451.02 T -5 F -(myFace) 363.06 451.02 T -3 F -(.) 399.04 451.02 T -(The image mechanism provides a great deal of \337exibility:) 170.1 439.02 T -3 12 Q -(\245) 152.1 424.02 T -3 10 Q --0.18 (Once an image has been de\336ned, it can be used in many dif) 162.9 424.02 P --0.18 (ferent places, even on dif) 397.84 424.02 P --0.18 (fer-) 497.68 424.02 P -(ent displays.) 162.9 411.98 T -3 12 Q -(\245) 152.1 396.98 T -3 10 Q -(Images provide image commands, analogous to widget commands, that can be used to) 162.9 396.98 T -(manipulate the image; any changes in an image are automatically re\337ected in all of its) 162.9 384.93 T -(instances.) 162.9 372.88 T -3 12 Q -(\245) 152.1 357.88 T -3 10 Q --0.21 (There can be many dif) 162.9 357.88 P --0.21 (ferent types of images. Tk 4.0 has two built-in types,) 251.78 357.88 P -5 F --0.51 (photo) 463.11 357.88 P -3 F --0.21 ( and) 493.1 357.88 P -5 F -(bitmap) 162.9 345.83 T -3 F -(. Other image types can be de\336ned in C as extensions \050see the documentation) 198.88 345.83 T --0.16 (for the) 162.9 333.79 P -5 F --0.39 (Tk_CreateImageType) 191.44 333.79 P -3 F --0.16 ( library procedure\051. The photo image type was imple-) 299.38 333.79 P -(mented by Paul Mackerras, based on his earlier photo widget.) 162.9 321.74 T -3 12 Q -(\245) 152.1 306.74 T -3 10 Q -(W) 162.9 306.74 T -(ithin the photo image type, there can be many dif) 171.93 306.74 T -(ferent \336le formats. In Tk 4.0, only) 368.29 306.74 T --0.11 (PPM, PGM, and GIF formats are built-in, but other formats can be added as extensions) 162.9 294.69 P -(\050see the documentation for the) 162.9 282.64 T -5 F -(Tk_CreatePhotoImageFormat) 286.97 282.64 T -3 F -( library proce-) 436.89 282.64 T -(dure\051. Readers for XPM, TIFF) 162.9 270.59 T -(, and others are available from the T) 284.23 270.59 T -(cl community) 428.41 270.59 T -(.) 483.01 270.59 T -98.1 227.24 512.1 230.26 C -152.1 228.46 512.1 228.46 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 228.75 143.1 228.75 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(7) 134.63 234.26 T -(Color management) 152.1 234.26 T -3 10 Q -(Tk 3.6 suf) 152.1 210.57 T -(fers from a relatively weak mechanism for managing colors. It uses only the) 192.73 210.57 T -(default colormap for a screen, and if all the entries in that colormap \336ll up then Tk) 152.1 198.52 T -(switches to monochrome mode and \322rounds\323 all future colors to black or white. This) 152.1 186.48 T -(approach is becoming increasingly unpleasant because of applications such as Frame and) 152.1 174.43 T -(W) 152.1 162.38 T -(eb browsers that use up all the entries in the default colormap.) 160.74 162.38 T -(Tk 4.0 has a much more powerful color management mechanism. If a colormap \336lls) 170.1 150.38 T -(up, Tk allocates future colors by picking the closest match from the available colors, so) 152.1 138.33 T -FMENDPAGE -%%EndPage: "13" 14 -%%Page: "14" 14 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(14) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X -(that it need not revert to monochrome mode. Tk also manages colors better by delaying) 152.1 632.33 T --0.3 (color allocation until colors are actually needed; in many cases, such as 3D borders, colors) 152.1 620.33 P -(are never needed. When colors are scarce Tk changes the way it displays beveled borders) 152.1 608.33 T --0.38 (so that it uses stippling instead of additional colors for the light and dark shadows. Y) 152.1 596.33 P --0.38 (ou can) 484.01 596.33 P -(\336nd out whether a colormap has \336lled up using the new command) 152.1 584.33 T -5 F -(winfo colormap-) 418.59 584.33 T -(full) 152.1 572.33 T -3 F -(.) 176.09 572.33 T --0.26 (Tk 4.0 also allows you to allocate new colormaps for toplevel and frame widgets with) 170.1 560.33 P -(the) 152.1 548.33 T -5 F -(-colormap) 166.81 548.33 T -3 F -( option, and you change the visual type in these widgets \050with the) 220.78 548.33 T -5 F -(-) 152.1 536.33 T -(visual) 158.1 536.33 T -3 F -( option\051 to take advantage of visuals other than the default visual for a screen.) 194.08 536.33 T -(New commands) 152.1 524.33 T -5 F -(winfo visualsavailable) 219.27 524.33 T -3 F -( and) 351.2 524.33 T -5 F -(wm colormapwindows) 370.63 524.33 T -3 F -( have) 478.57 524.33 T -(been added to help manage colormaps and visuals.) 152.1 512.33 T -(The default color scheme in Tk 4.0 has changed from a tan palette \050\322bisque\323\051 to a) 170.1 500.33 T -(gray palette, which seems to becoming standard for Motif. There is a new T) 152.1 488.33 T -(cl procedure) 454.78 488.33 T -5 F --0.36 (tk_setPalette) 152.1 476.33 P -3 F --0.15 ( that changes the palette of an application on the \337y) 230.06 476.33 P --0.15 (, and there is also a) 433.89 476.33 P -(procedure) 152.1 464.33 T -5 F -(tk_bisque) 194.56 464.33 T -3 F -( to restore the palette to the old bisque colors.) 248.53 464.33 T -(The Tk 3.6 color model mechanism is no longer necessary so it has been removed in) 170.1 452.33 T -(Tk 4.0. If you want to \336nd out whether a screen is monochrome or color) 152.1 440.33 T -(, you cannot use) 440.38 440.33 T -(the) 152.1 428.33 T -5 F -(tk colormodel) 166.81 428.33 T -3 F -( command anymore; use) 244.77 428.33 T -5 F -(winfo depth) 345.25 428.33 T -3 F -( instead.) 411.22 428.33 T -98.1 384.98 512.1 388 C -152.1 386.2 512.1 386.2 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 386.49 143.1 386.49 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(8) 134.63 392 T -(Event handling: \336leevent and after) 152.1 392 T -3 10 Q -(Tk 4.0 contains several improvements in the area of event handling besides those already) 152.1 368.31 T -(mentioned for bindings:) 152.1 356.31 T -3 12 Q -(\245) 152.1 341.31 T -3 10 Q -(There is a new command) 162.9 341.31 T -5 F -(f) 265.87 341.31 T -(ileevent) 271.87 341.31 T -3 F -( for performing event-driven I/O to and from) 319.84 341.31 T --0.12 (\336les. The) 162.9 329.31 P -5 F --0.29 (f) 202.35 329.31 P --0.29 (ileevent) 208.35 329.31 P -3 F --0.12 ( command is modelled very closely after Mark Diekhans\325) 256.33 329.31 P -5 F --0.29 (add-) 488.11 329.31 P -(input) 162.9 317.31 T -3 F -( extension, which has been used widely with Tk 3.6.) 192.88 317.31 T -3 12 Q -(\245) 152.1 302.31 T -3 10 Q --0.34 (The) 162.9 302.31 P -5 F --0.82 (after) 180.6 302.31 P -3 F --0.34 ( command has two new options,) 210.58 302.31 P -5 F --0.82 (idle) 339.82 302.31 P -3 F --0.34 ( and) 363.81 302.31 P -5 F --0.82 (cancel) 382.55 302.31 P -3 F --0.34 (.) 418.53 302.31 P -5 F --0.82 (After idle) 423.19 302.31 P -3 F --0.34 ( can be) 482.33 302.31 P --0.2 (used to schedule a script as an \322idle handler\323, which means it runs the next time that Tk) 162.9 290.31 P -(enters the event loop and \336nds no work to do.) 162.9 278.31 T -5 F -(After cancel) 348.06 278.31 T -3 F -( may be used to delete) 420.02 278.31 T -(a previously-scheduled) 162.9 266.31 T -5 F -(after) 257.83 266.31 T -3 F -( script, so that it will no longer be invoked.) 287.81 266.31 T -98.1 222.95 512.1 225.98 C -152.1 224.18 512.1 224.18 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 224.46 143.1 224.46 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(9) 134.63 229.98 T -(Multiple displays) 152.1 229.98 T -3 10 Q -(Although Tk has always allowed a single application to open windows on several dis-) 152.1 206.29 T -(plays, the support for multiple displays is weak in Tk 3.6. For example, many of the bind-) 152.1 194.29 T -(ings break if users work simultaneously in windows on dif) 152.1 182.29 T -(ferent displays, and) 385.94 182.29 T -(mechanisms like the selection and the input focus have insuf) 152.1 170.29 T -(\336cient support for multiple) 394.26 170.29 T -(displays.) 152.1 158.29 T -FMENDPAGE -%%EndPage: "14" 15 -%%Page: "15" 15 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(10 The send command) 98.1 668.33 T -0 F -(15) 500.99 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X --0.33 (Tk 4.0 contains numerous modi\336cations to improve the handling of multiple displays.) 170.1 632.33 P --0.18 (Several commands, such as) 152.1 620.24 P -5 F --0.44 (selection) 263.78 620.24 P -3 F --0.18 (,) 317.76 620.24 P -5 F --0.44 (send) 322.57 620.24 P -3 F --0.18 (, and) 346.55 620.24 P -5 F --0.44 (focus) 368.12 620.24 P -3 F --0.18 (, have a new) 398.1 620.24 P -5 F --0.44 (-displayof) 449.82 620.24 P -3 F -(ar) 152.1 608.15 T -(gument so that you can select a particular display) 159.69 608.15 T -(. In addition, the bindings have been) 356.12 608.15 T -(reworked to handle interactions occurring simultaneously on dif) 152.1 596.05 T -(ferent displays. W) 408.13 596.05 T -(ith Tk) 480.73 596.05 T -(4.0 it should be possible to create applications that really use multiple displays gracefully) 152.1 583.96 T -(.) 508.44 583.96 T -98.1 540.6 512.1 543.63 C -152.1 541.83 512.1 541.83 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 542.12 143.1 542.12 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(10) 127.96 547.63 T -(The send command) 152.1 547.63 T -3 10 Q --0.2 (The) 152.1 523.94 P -5 F --0.48 (send) 169.94 523.94 P -3 F --0.2 ( command has been completely overhauled for Tk 4.0 to eliminate several prob-) 193.93 523.94 P -(lems in Tk 3.6 and add a number of new features:) 152.1 511.85 T -3 12 Q -(\245) 152.1 496.85 T -3 10 Q -(Tk 3.6 aborts a) 162.9 496.85 T -5 F -(send) 225.36 496.85 T -3 F -( command if no response is received within 5 seconds; this made) 249.34 496.85 T -(it very dif) 162.9 484.75 T -(\336cult to invoke long-running commands. Tk 4.0 eliminates the timeout and) 202.14 484.75 T -(uses a dif) 162.9 472.66 T -(ferent mechanism to tell if the tar) 200.47 472.66 T -(get application has crashed.) 333.53 472.66 T -3 12 Q -(\245) 152.1 457.66 T -3 10 Q --0.36 (The) 162.9 457.66 P -5 F --0.87 (winfo interps) 180.58 457.66 P -3 F --0.36 ( command no longer returns the names of applications that have) 257.66 457.66 P -(exited or crashed.) 162.9 445.57 T -3 12 Q -(\245) 152.1 430.57 T -3 10 Q -(Asynchronous sends are possible using the) 162.9 430.57 T -5 F -(-async) 336.67 430.57 T -3 F -( switch.) 372.65 430.57 T -3 12 Q -(\245) 152.1 415.57 T -3 10 Q -(Commands can be sent to displays other than that of the root window) 162.9 415.57 T -(, using the) 439.3 415.57 T -5 F -(-) 162.9 403.47 T -(displayof) 168.9 403.47 T -3 F -( switch.) 222.87 403.47 T -3 12 Q -(\245) 152.1 388.47 T -3 10 Q -(W) 162.9 388.47 T -(indow server security is now checked on each) 171.93 388.47 T -5 F -(send) 357.89 388.47 T -3 F -(, so Tk 4.0 deals better with) 381.88 388.47 T -(changes in the security of the server) 162.9 376.38 T -(.) 306.12 376.38 T -3 12 Q -(\245) 152.1 361.38 T -3 10 Q -(More complete error information \050including the) 162.9 361.38 T -5 F -(errorCode) 356.09 361.38 T -3 F -( and) 410.06 361.38 T -5 F -(errorInfo) 429.49 361.38 T -3 F -( vari-) 483.46 361.38 T -(ables\051 is propagated back to the sender after errors.) 162.9 349.29 T -3 12 Q -(\245) 152.1 334.29 T -3 10 Q -(Y) 162.9 334.29 T -(ou can query and change the name of an application with the) 169.12 334.29 T -5 F -(tk appname) 414.48 334.29 T -3 F -( com-) 474.45 334.29 T -(mand.) 162.9 322.19 T -(Unfortunately the improvements to the Tk 4.0) 152.1 307.19 T -5 F -(send) 338.65 307.19 T -3 F -( mechanism required substantial) 362.63 307.19 T -(changes to the transport protocol for sends; this makes it impossible for Tk 4.0 applica-) 152.1 295.1 T -(tions to communicate with Tk 3.6 applications via) 152.1 283.01 T -5 F -(send) 355.04 283.01 T -3 F -(. The new transport protocol is) 379.02 283.01 T -(more \337exible than the old protocol, so it should be possible to make protocol improve-) 152.1 270.91 T -(ments in an upward-compatible way) 152.1 258.82 T -(.) 296.9 258.82 T -98.1 215.47 512.1 218.49 C -152.1 216.69 512.1 216.69 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 216.98 143.1 216.98 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(1) 128.62 222.49 T -(1) 134.63 222.49 T -(The selection and clipboard) 152.1 222.49 T -3 10 Q -(In Tk 3.6 the selection mechanism can deal only with the display of the root window and) 152.1 198.8 T --0.13 (with the primary selection; there is no support for multiple displays, secondary selections,) 152.1 186.71 P -(or the clipboard. Tk 4.0 eliminates all of these shortcomings. The) 152.1 174.61 T -5 F -(-displayof) 415.82 174.61 T -3 F -( option) 475.78 174.61 T --0.12 (can be used to specify a particular display in the selection command, and there is now full) 152.1 162.52 P -(access to all of the X selection types. Tk 4.0 also includes a new) 152.1 150.43 T -5 F -(clipboard) 411.36 150.43 T -3 F -( command) 465.33 150.43 T -(for manipulating the clipboard.) 152.1 138.33 T -FMENDPAGE -%%EndPage: "15" 16 -%%Page: "16" 16 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(16) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -98.1 623.98 512.1 627 C -152.1 625.2 512.1 625.2 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 625.49 143.1 625.49 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(12) 127.96 631 T -(Miscellaneous changes) 152.1 631 T -3 10 Q -(Here is a quick summary of the remaining changes in Tk 4.0:) 152.1 607.31 T -3 12 Q -(\245) 152.1 592.31 T -3 10 Q --0.17 (The) 162.9 592.31 P -5 F --0.42 (wish) 180.76 592.31 P -3 F --0.17 ( application has been modi\336ed so that the) 204.75 592.31 P -5 F --0.42 (-f) 371.58 592.31 P --0.42 (ile) 383.57 592.31 P -3 F --0.17 ( switch is no longer needed) 401.56 592.31 P -(or recommended. This makes) 162.9 580.31 T -5 F -(wish) 283.64 580.31 T -3 F -( just like) 307.63 580.31 T -5 F -(tclsh) 344.56 580.31 T -3 F -(, where you specify the script \336le) 374.54 580.31 T -(as the \336rst ar) 162.9 568.31 T -(gument to the program, e.g.) 214.07 568.31 T -5 F -(wish foo.tcl) 327.33 568.31 T -3 F -(. The) 399.29 568.31 T -5 F -(-f) 422.33 568.31 T -(ile) 434.32 568.31 T -3 F -( switch is still) 452.31 568.31 T -(permitted for backward compatibility) 162.9 556.31 T -(, but its use is deprecated.) 311.87 556.31 T -3 12 Q -(\245) 152.1 541.31 T -5 10 Q -(Wish) 162.9 541.31 T -3 F -( now sets the application\325) 186.89 541.31 T -(s class from the application name \050what appears in the) 288.49 541.31 T --0.37 (title bar of the window by default\051, rather than always using) 162.9 529.31 P -5 F --0.88 (Tk) 400.9 529.31 P -3 F --0.37 ( as the class as in Tk 3.6.) 412.89 529.31 P -(This makes application-speci\336c options easier to use.) 162.9 517.31 T -3 12 Q -(\245) 152.1 502.31 T -3 10 Q -(T) 162.9 502.31 T -(oplevel windows are now resizable by default, whereas in Tk 3.6 they were not. Y) 168.31 502.31 T -(ou) 496.22 502.31 T -(can use the) 162.9 490.31 T -5 F -(wm resizable) 209.8 490.31 T -3 F -( command to make windows non-reiszable.) 281.77 490.31 T -3 12 Q -(\245) 152.1 475.31 T -3 10 Q -(Tk 4.0 patches around an Xlib bug whereby long-running applications tended to reach) 162.9 475.31 T -(the end of the space of X resource ids, wrap around to 0 again, and then crash. Tk now) 162.9 463.31 T -(reuses resource identi\336ers so that wrap-around should never occur) 162.9 451.31 T -(.) 427.14 451.31 T -3 12 Q -(\245) 152.1 436.31 T -3 10 Q --0.13 (There is a new) 162.9 436.31 P -5 F --0.31 (winfo manager) 223.43 436.31 P -3 F --0.13 ( command that tells which geometry manager is con-) 301.08 436.31 P -(trolling a particular widget.) 162.9 424.31 T -3 12 Q -(\245) 152.1 409.31 T -3 10 Q -(There is a new) 162.9 409.31 T -5 F -(bell) 223.96 409.31 T -3 F -( command that does what its name suggests.) 247.94 409.31 T -3 12 Q -(\245) 152.1 394.31 T -3 10 Q -(There are new) 162.9 394.31 T -5 F -(winfo pointerx) 222.56 394.31 T -3 F -(,) 306.51 394.31 T -5 F -(winfo pointery) 311.51 394.31 T -3 F -(, and) 394.81 394.31 T -5 F -(winfo pointerxy) 416.74 394.31 T -3 F -(commands that can be used to query the position of the mouse pointer) 162.9 382.31 T -(.) 442.17 382.31 T -98.1 338.95 512.1 341.98 C -152.1 340.18 512.1 340.18 2 L -0.5 H -2 Z -0 X -0 K -N -98.1 340.46 143.1 340.46 2 L -0 Z -N -40.5 63 571.5 729 C -0 12 Q -0 X -0 K -(13) 127.96 345.98 T -(Summary of Incompatibilites) 152.1 345.98 T -3 10 Q --0.24 (This section lists all of the incompatible changes in Tk 4.0 that may require changes in T) 152.1 322.29 P --0.24 (cl) 502.62 322.29 P --0.22 (scripts written for T) 152.1 310.29 P --0.22 (cl 3.6. Each incompatibility is described in terms of the problem it pro-) 230.42 310.29 P -(duces when you run your Tk 3.6 script under Tk 4.0 and a possible work-around. Only) 152.1 298.29 T -(T) 152.1 286.29 T -(cl-level incompatibilities are covered here. For incompatible changes at the C level, see) 157.51 286.29 T -(the) 152.1 274.29 T -5 F -(README) 166.81 274.29 T -3 F -( and) 202.79 274.29 T -5 F -(changes) 222.22 274.29 T -3 F -( \336les in the distribution. The problems and solutions are) 264.2 274.29 T -(roughly in order of importance, with the most important problems \336rst.) 152.1 262.29 T -1 F -(Pr) 152.1 247.29 T -(oblem #1:) 162.46 247.29 T -3 F -(When you change the background color of a widget, a small ring in the) 206.88 247.29 T -(default background color remains around the edge of the widget.) 152.1 235.29 T -2 F -(Solution:) 170.1 223.29 T -3 F -(This is the focus traversal highlight, whose color is speci\336ed separately) 209.25 223.29 T -(from) 170.1 211.29 T -5 F -(-background) 192.03 211.29 T -3 F -(; use the) 257.99 211.29 T -5 F -(-highlightbackground) 293.8 211.29 T -3 F -( option to change the) 413.74 211.29 T -(color of the highlight. Or) 170.1 199.29 T -(, you can set) 269.92 199.29 T -5 F -(-highlightthickness) 322.38 199.29 T -3 F -( to 0 to eliminate) 436.31 199.29 T -(the traversal highlight altogether) 170.1 187.29 T -(.) 299.74 187.29 T -1 F -(Pr) 152.1 172.29 T -(oblem #2:) 162.46 172.29 T -3 F -(Bindings de\336ned for a widget no longer replace the corresponding class) 206.88 172.29 T -(bindings, so unwanted class bindings get invoked in addition to the widget bindings.) 152.1 160.29 T -FMENDPAGE -%%EndPage: "16" 17 -%%Page: "17" 17 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(13 Summary of Incompatibilites) 98.1 668.33 T -0 F -(17) 500.99 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -2 F -0 X -(Solution:) 170.1 632.33 T -3 F -(Add a) 209.25 632.33 T -5 F -(break) 235.89 632.33 T -3 F -( command at the end of the widget binding, or rework the) 265.88 632.33 T -(widget binding so that it\325) 170.1 620.33 T -(s OK for the class binding to execute.) 270.05 620.33 T -1 F -(Pr) 152.1 605.33 T -(oblem #3:) 162.46 605.33 T -3 F -(Bindings on toplevel windows are invoked when events occur for internal) 206.88 605.33 T -(windows inside the toplevels.) 152.1 593.33 T -2 F -(Solution:) 170.1 581.33 T -3 F -(Use the) 209.25 581.33 T -5 F -(%W) 242 581.33 T -3 F -( substitution to extract the name of the window where the event) 253.99 581.33 T -(actually occurred, and only execute the rest of the binding script if this matches the) 170.1 569.33 T -(name of the toplevel.) 170.1 557.33 T -1 F --0.15 (Pr) 152.1 542.33 P --0.15 (oblem #4:) 162.46 542.33 P -3 F --0.15 (The) 206.58 542.33 P -5 F --0.37 (-command) 224.46 542.33 P -3 F --0.15 ( option for a cascade menu entry is no longer invoked when) 272.44 542.33 P -(the submenu is posted.) 152.1 530.33 T -2 F -(Solution:) 170.1 518.33 T -3 F -(Use the) 209.25 518.33 T -5 F -(-postcommand) 242 518.33 T -3 F -( option for the submenu instead.) 313.96 518.33 T -1 F -(Pr) 152.1 503.33 T -(oblem #5:) 162.46 503.33 T -3 F -(The) 206.88 503.33 T -5 F -(-geometry) 224.92 503.33 T -3 F -( option is no longer supported by listboxes, frames, and) 278.89 503.33 T -(toplevels.) 152.1 491.33 T -2 F -(Solution:) 170.1 479.33 T -3 F -(Use the) 209.25 479.33 T -5 F -(-width) 242 479.33 T -3 F -( and) 277.98 479.33 T -5 F -(-height) 297.41 479.33 T -3 F -( options instead.) 339.39 479.33 T -1 F -(Pr) 152.1 464.33 T -(oblem #6:) 162.46 464.33 T -3 F -(The procedure) 206.88 464.33 T -5 F -(tk_listboxSingleSelect) 267.38 464.33 T -3 F -( no longer exists.) 399.3 464.33 T -2 F -(Solution:) 170.1 452.33 T -3 F -(Use the) 209.25 452.33 T -5 F -(-selectmode) 242 452.33 T -3 F -( option on the listbox instead.) 307.96 452.33 T -1 F -(Pr) 152.1 437.33 T -(oblem #7:) 162.46 437.33 T -3 F -(Canvases no longer have a) 206.88 437.33 T -5 F -(-scrollincrement) 315.96 437.33 T -3 F -( option.) 411.91 437.33 T -2 F -(Solution:) 170.1 425.33 T -3 F -(Use the new) 209.25 425.33 T -5 F -(-xscrollincrement) 261.15 425.33 T -3 F -( and) 363.09 425.33 T -5 F -(-yscrollincrement) 382.52 425.33 T -3 F -(options instead.) 170.1 413.33 T -1 F -(Pr) 152.1 398.33 T -(oblem #8:) 162.46 398.33 T -3 F -(The) 206.88 398.33 T -5 F -(tk colormodel) 224.92 398.33 T -3 F -( command no longer exists.) 302.88 398.33 T -2 F --0.28 (Solution:) 170.1 386.33 P -3 F --0.28 (T) 208.97 386.33 P --0.28 (o \336nd out whether a window is monochrome or color) 214.37 386.33 P --0.28 (, use) 424.34 386.33 P -5 F --0.68 (winfo depth) 444.6 386.33 P -3 F -(to extract the window\325) 170.1 374.33 T -(s depth; a depth of 1 means monochrome.) 259.76 374.33 T -1 F --0.08 (Pr) 152.1 359.33 P --0.08 (oblem #9:) 162.46 359.33 P -3 F --0.08 (The class of Tk applications is no longer) 206.72 359.33 P -5 F --0.19 (Tk) 370.97 359.33 P -3 F --0.08 (, so options speci\336ed for the) 382.96 359.33 P -5 F --0.19 (Tk) 497.69 359.33 P -3 F -(class in your) 152.1 347.33 T -5 F -(.Xdefaults) 205.12 347.33 T -3 F -( \336le are no longer used.) 265.09 347.33 T -2 F -(Solution:) 170.1 335.33 T -3 F -(Modify your) 209.25 335.33 T -5 F -(.Xdefaults) 262.55 335.33 T -3 F -( \336le \050and any T) 322.52 335.33 T -(cl code that sets options\051 to) 382.88 335.33 T -(specify the name of the application \050with the \336rst letter capitalized\051 as the class) 170.1 323.33 T -(instead of) 170.1 311.33 T -5 F -(Tk) 211.74 311.33 T -3 F -(.) 223.73 311.33 T -1 F --0.15 (Pr) 152.1 296.33 P --0.15 (oblem #10:) 162.46 296.33 P -3 F --0.15 (When text is added to a text widget just after a tagged area, the new text no) 211.57 296.33 P -(longer receives the tag.) 152.1 284.33 T -2 F --0.1 (Solution:) 170.1 272.33 P -3 F --0.1 (Explicitly tag the new text with the desired tags. If you want the tags on the) 209.15 272.33 P --0.08 (new text to be the same as those at some other point in the text, you can use the) 170.1 260.33 P -5 F --0.2 (tag) 488.31 260.33 P -(names) 170.1 248.33 T -3 F -( widget command to query existing tags.) 200.08 248.33 T -1 F -(Pr) 152.1 233.33 T -(oblem #1) 162.46 233.33 T -(1:) 200.5 233.33 T -3 F -(W) 211.33 233.33 T -(idgets appear lar) 220.36 233.33 T -(ger than they did in Tk 3.6.) 286.24 233.33 T -2 F -(Solution:) 170.1 221.33 T -3 F -(There are two issues here. The \336rst is that all widgets now have a focus tra-) 209.25 221.33 T --0.24 (versal highlight ring that turns dark when the widget has the focus; this is required for) 170.1 209.33 P -(Motif compliance but you can eliminate it by specifying a 0 value for the) 170.1 197.33 T -5 F -( -high-) 462.4 197.33 T -(lightthickness) 170.1 185.33 T -3 F -( option. The second issue is that the default padding for buttons) 254.05 185.33 T --0.17 (and menubuttons has been increased to match the sizes of Motif widgets. If you don\325) 170.1 173.33 P --0.17 (t) 506.99 173.33 P -(mind being dif) 170.1 161.33 T -(ferent from Motif, you can set the) 228.78 161.33 T -5 F -(-padx) 366.45 161.33 T -3 F -( and) 396.44 161.33 T -5 F -(-) 415.86 161.33 T -(pady) 421.86 161.33 T -3 F -( options back to) 445.85 161.33 T -FMENDPAGE -%%EndPage: "17" 18 -%%Page: "18" 18 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(18) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -3 F -0 X -(their Tk 3.6 values \050use the) 170.1 632.33 T -5 F -(conf) 281.41 632.33 T -(igure) 305.4 632.33 T -3 F -( widget command in Tk 3.6 to see what the) 335.38 632.33 T -(old values were\051.) 170.1 620.33 T -1 F -(Pr) 152.1 605.33 T -(oblem #12:) 162.46 605.33 T -3 F -(Listboxes now return the selection as a string with newlines separating the) 211.88 605.33 T -(values, rather than a T) 152.1 593.33 T -(cl, list.) 240.49 593.33 T -2 F -(Solution:) 170.1 581.33 T -3 F -(Modify your code to handle the new format. Y) 209.25 581.33 T -(ou can convert the selection) 395.06 581.33 T -(back into the old list format with a script like the following:) 170.1 569.33 T -5 9 Q -(split [selection get] \134n) 179.1 555 T -1 10 Q -(Pr) 152.1 541.33 T -(oblem #13:) 162.46 541.33 T -3 F -(Tk 4.0 applications cannot) 211.88 541.33 T -5 F -(send) 320.42 541.33 T -3 F -( to or be sent from Tk 3.6 applications.) 344.4 541.33 T -2 F -(Solution:) 170.1 529.33 T -3 F -(The only solution is to upgrade all your applications to Tk 4.0.) 209.25 529.33 T -1 F --0.17 (Pr) 152.1 514.33 P --0.17 (oblem #14:) 162.46 514.33 P -3 F --0.17 (In texts,) 211.54 514.33 P -5 F --0.4 (end) 245.91 514.33 P -3 F --0.17 ( now refers to a position just after the \336nal newline, instead of) 263.9 514.33 P -(the \336nal newline.) 152.1 502.33 T -2 F --0.08 (Solution:) 170.1 490.33 P -3 F --0.08 (If you wish to refer to the \336nal newline, use the index) 209.17 490.33 P -5 F --0.19 (end-1char) 424.98 490.33 P -3 F --0.08 ( instead) 478.95 490.33 P -(of) 170.1 478.33 T -5 F -(end) 180.92 478.33 T -3 F -(.) 198.91 478.33 T -1 F -(Pr) 152.1 463.33 T -(oblem #15:) 162.46 463.33 T -3 F -(In entry widgets,) 211.88 463.33 T -5 F -(sel.last) 281.83 463.33 T -3 F -( now refers to the character just after the last) 329.8 463.33 T -(selected one, rather than the last selected one. The second index for the) 152.1 451.33 T -5 F -(delete) 438.81 451.33 T -3 F -( widget) 474.79 451.33 T -(command has changed in the same way) 152.1 439.33 T -(.) 309.66 439.33 T -2 F -(Solution:) 170.1 427.33 T -3 F -(Add one to the values used in your scripts.) 209.25 427.33 T -1 F -(Pr) 152.1 412.33 T -(oblem #16:) 162.46 412.33 T -3 F -(Because) 211.88 412.33 T -5 F -(Any) 247.68 412.33 T -3 F -( is implicit in all bindings, bindings trigger when extra modi-) 265.67 412.33 T -(\336ers are present, whereas they didn\325) 152.1 400.33 T -(t trigger in Tk 3.6.) 296.24 400.33 T -2 F -(Solution:) 170.1 388.33 T -3 F -(In most cases it\325) 209.25 388.33 T -(s probably \336ne to ignore the extra modi\336ers. If you really) 273.93 388.33 T --0.12 (don\325) 170.1 376.33 P --0.12 (t want any actions to be taken when extra modi\336ers are present, create additional) 188.24 376.33 P -(bindings for the cases with extra modi\336ers, and specify a single blank character \050or) 170.1 364.33 T -(any script that does nothing\051 as the script for those bindings. Alternatively) 170.1 352.33 T -(, you can) 465.93 352.33 T -(use the) 170.1 340.33 T -5 F -(%s) 200.63 340.33 T -3 F -( substitution to extract the mouse and modi\336er state in the event binding,) 212.63 340.33 T -(then you can test this value for modi\336ers you do or don\325) 170.1 328.33 T -(t want.) 394.5 328.33 T -1 F -(Pr) 152.1 313.33 T -(oblem #17:) 162.46 313.33 T -3 F -(In scrollbars there is no longer a) 211.88 313.33 T -5 F -(-foreground) 343.17 313.33 T -3 F -( or) 409.13 313.33 T -5 F -(-activefore-) 422.45 313.33 T -(ground) 152.1 301.33 T -3 F -( option, and) 188.08 301.33 T -5 F -(-background) 238.05 301.33 T -3 F -( has a dif) 304.02 301.33 T -(ferent meaning.) 340.2 301.33 T -2 F --0.4 (Solution:) 170.1 289.33 P -3 F --0.4 (Use) 208.85 289.33 P -5 F --0.96 (-troughcolor) 226.49 289.33 P -3 F --0.4 ( everywhere that you used) 298.45 289.33 P -5 F --0.96 (-background) 403.87 289.33 P -3 F --0.4 ( in Tk 3.6,) 469.83 289.33 P -5 F -(-background) 170.1 277.33 T -3 F -( everywhere you used to use) 236.06 277.33 T -5 F -(-foreground) 352.08 277.33 T -3 F -(, and) 418.04 277.33 T -5 F -(-activeback-) 439.97 277.33 T -(ground) 170.1 265.33 T -3 F -( everywhere you used to use) 206.08 265.33 T -5 F -(-activeforeground) 322.1 265.33 T -3 F -(.) 424.04 265.33 T -1 F -(Pr) 152.1 250.33 T -(oblem #18:) 162.46 250.33 T -3 F -(Options for colors seem to have changed in scale widgets.) 211.88 250.33 T -2 F -(Solution:) 170.1 238.33 T -3 F -(Use) 209.25 238.33 T -5 F -(-background) 227.29 238.33 T -3 F -( where you used to use) 293.25 238.33 T -5 F -(-sliderforeground) 387.07 238.33 T -3 F -(,) 489.02 238.33 T -5 F -(-) 170.1 226.33 T -(troughcolor) 176.1 226.33 T -3 F -( where you used to use) 242.06 226.33 T -5 F -(-background) 335.88 226.33 T -3 F -(, and) 401.84 226.33 T -5 F -( -activeback-) 421.27 226.33 T -(ground) 170.1 214.33 T -3 F -( everywhere you used to use) 206.08 214.33 T -5 F -(-activeforeground) 322.1 214.33 T -3 F -(.) 424.04 214.33 T -1 F -(Pr) 152.1 199.33 T -(oblem #19:) 162.46 199.33 T -3 F -(Scale widgets no longer accept hexadecimal or octal numbers in the) 211.88 199.33 T -5 F -(set) 485.84 199.33 T -3 F -(command or the) 152.1 187.33 T -5 F -(-from) 219.55 187.33 T -3 F -( and) 249.54 187.33 T -5 F -(-to) 268.97 187.33 T -3 F -( options.) 286.96 187.33 T -2 F -(Solution:) 170.1 175.33 T -3 F -(Use) 209.25 175.33 T -5 F -(format) 227.29 175.33 T -3 F -( or) 263.27 175.33 T -5 F -(expr) 276.59 175.33 T -3 F -( to convert the values to decimal.) 300.58 175.33 T -1 F -(Pr) 152.1 160.33 T -(oblem #20:) 162.46 160.33 T -3 F -(In checkbuttons, radiobuttons, and menu entries, the) 211.88 160.33 T -5 F -(-selector) 423.4 160.33 T -3 F -( option) 477.37 160.33 T -(no longer exists.) 152.1 148.33 T -FMENDPAGE -%%EndPage: "18" 19 -%%Page: "19" 19 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(13 Summary of Incompatibilites) 98.1 668.33 T -0 F -(19) 500.99 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -2 F -0 X -(Solution:) 170.1 632.33 T -3 F -(Use) 209.25 632.33 T -5 F -(-selectcolor) 227.29 632.33 T -3 F -( instead of) 299.25 632.33 T -5 F -(-select) 343.39 632.33 T -3 F -(. T) 385.36 632.33 T -(o specify that no indicator) 395.77 632.33 T -(should be drawn at all, use the) 170.1 620.33 T -5 F -(-indicatoron) 293.9 620.33 T -3 F -( option instead of setting) 365.86 620.33 T -5 F -(-select) 467.2 620.33 T -3 F -(to an empty string.) 170.1 608.33 T -1 F --0.12 (Pr) 152.1 593.33 P --0.12 (oblem #21:) 162.46 593.33 P -3 F --0.12 (The indices of menu entries have changed, and operations on menu entry 0) 211.64 593.33 P -(no longer work.) 152.1 581.33 T -2 F -(Solution:) 170.1 569.33 T -3 F -(This is because menus now have a tearof) 209.25 569.33 T -(f entry at the top by default, and) 372.55 569.33 T -(this occupies entry 0, so your \336rst entry is now entry 1. Y) 170.1 557.33 T -(ou can either set the) 398.95 557.33 T -5 F -(-) 170.1 545.33 T -(tearoff) 176.1 545.33 T -3 F -( option to 0 to eliminate the tearof) 218.07 545.33 T -(f entry or add 1 to all the indices you) 354.2 545.33 T -(use in your scripts.) 170.1 533.33 T -1 F --0.22 (Pr) 152.1 518.33 P --0.22 (oblem #22:) 162.46 518.33 P -3 F --0.22 (The) 211.44 518.33 P -5 F --0.53 (enable) 229.26 518.33 P -3 F --0.22 ( and) 265.24 518.33 P -5 F --0.53 (disable) 284.23 518.33 P -3 F --0.22 ( widget commands are no longer supported by) 326.21 518.33 P -(menus.) 152.1 506.33 T -2 F -(Solution:) 170.1 494.33 T -3 F -(Use the) 209.25 494.33 T -5 F -(-state) 242 494.33 T -3 F -( con\336guration option instead.) 277.98 494.33 T -1 F -(Pr) 152.1 479.33 T -(oblem #23:) 162.46 479.33 T -3 F -(The) 211.88 479.33 T -5 F -(activate) 229.92 479.33 T -3 F -( and) 277.89 479.33 T -5 F -(deactivate) 297.32 479.33 T -3 F -( widget commands are no longer sup-) 357.29 479.33 T -(ported by buttons, checkbuttons, radiobuttons, and menus.) 152.1 467.33 T -2 F -(Solution:) 170.1 455.33 T -3 F -(Use the) 209.25 455.33 T -5 F -(-state) 242 455.33 T -3 F -( con\336guration option instead.) 277.98 455.33 T -1 F -(Pr) 152.1 440.33 T -(oblem #24:) 162.46 440.33 T -3 F -(Canvas arc items no longer use the) 211.88 440.33 T -5 F -(-f) 353.72 440.33 T -(ill) 365.71 440.33 T -3 F -( and) 383.7 440.33 T -5 F -(-stipple) 403.13 440.33 T -3 F -( options for) 451.11 440.33 T -(drawing when the) 152.1 428.33 T -5 F -(-style) 226.21 428.33 T -3 F -( option is) 262.19 428.33 T -5 F -(arc) 301.9 428.33 T -3 F -(.) 319.89 428.33 T -2 F -(Solution:) 170.1 416.33 T -3 F -(Use the) 209.25 416.33 T -5 F -(-outline) 242 416.33 T -3 F -( and) 289.97 416.33 T -5 F -(-outlinestipple) 309.4 416.33 T -3 F -( options instead.) 399.35 416.33 T -1 F --0.29 (Pr) 152.1 401.33 P --0.29 (oblem #25:) 162.46 401.33 P -3 F --0.29 (The variable) 211.29 401.33 P -5 F --0.7 (tkVersion) 263.43 401.33 P -3 F --0.29 ( no longer exists \050it has been obsolete for several) 317.4 401.33 P -(releases\051.) 152.1 389.33 T -2 F -(Solution:) 170.1 377.33 T -3 F -(Use) 209.25 377.33 T -5 F -(tk_version) 227.29 377.33 T -3 F -( instead.) 287.26 377.33 T -1 F -(Pr) 152.1 362.33 T -(oblem #26:) 162.46 362.33 T -3 F -(The syntax of the) 211.88 362.33 T -5 F -(scan) 284.05 362.33 T -3 F -( widget commands for texts has changed.) 308.03 362.33 T -2 F -(Solution:) 170.1 350.33 T -3 F -(Modify your code to use the new syntax.) 209.25 350.33 T -1 F -(Pr) 152.1 335.33 T -(oblem #27:) 162.46 335.33 T -5 F -(wish) 211.88 335.33 T -3 F -( no longer recognizes the) 235.86 335.33 T -5 F -(-help) 338.84 335.33 T -3 F -( option.) 368.82 335.33 T -2 F -(Solution:) 170.1 323.33 T -3 F -(Implement this option yourself in your) 209.25 323.33 T -5 F -(wish) 366.38 323.33 T -3 F -( scripts.) 390.37 323.33 T -1 F -(Pr) 152.1 308.33 T -(oblem #28:) 162.46 308.33 T -3 F -(Tk 4.0 always prints real numbers such as canvas coordinates with a deci-) 211.88 308.33 T -(mal point. This can cause syntax errors if you later use them in situations where integers) 152.1 296.33 T -(are expected.) 152.1 284.33 T -2 F -(Solution:) 170.1 272.33 T -3 F -(Change your code so that real numbers work OK, or use the) 209.25 272.33 T -5 F -(expr) 451.57 272.33 T -3 F -( com-) 475.55 272.33 T -(mand \050with the) 170.1 260.33 T -5 F -(round) 233.12 260.33 T -3 F -( function\051 to convert the numbers to integers.) 263.1 260.33 T -1 F -(Pr) 152.1 245.33 T -(oblem #29:) 162.46 245.33 T -3 F -(The) 211.88 245.33 T -5 F -(pack info) 229.92 245.33 T -3 F -( command returns dif) 283.89 245.33 T -(ferent information, and) 369.48 245.33 T -5 F -(pack) 464.41 245.33 T -(newinfo) 152.1 233.33 T -3 F -( no longer exists.) 194.08 233.33 T -2 F -(Solution:) 170.1 221.33 T -3 F -(Use) 209.25 221.33 T -5 F -(pack info) 227.29 221.33 T -3 F -( where you used to use) 281.26 221.33 T -5 F -(pack newinfo) 375.08 221.33 T -3 F -(.) 447.04 221.33 T -5 F -(Pack info) 452.04 221.33 T -3 F -(was obsolete, so it has been eliminated.) 170.1 209.33 T -1 F -(Pr) 152.1 194.33 T -(oblem #30:) 162.46 194.33 T -3 F -(The) 211.88 194.33 T -5 F -(view) 229.92 194.33 T -3 F -( widget command for entries no longer exists, nor does the) 253.9 194.33 T -5 F -(-) 152.1 182.33 T -(scrollcommand) 158.1 182.33 T -3 F -( option.) 236.05 182.33 T -2 F --0.29 (Solution:) 170.1 170.33 P -3 F --0.29 (Use) 208.96 170.33 P -5 F --0.69 (xview) 226.71 170.33 P -3 F --0.29 ( where you used to use) 256.7 170.33 P -5 F --0.69 (view) 348.8 170.33 P -3 F --0.29 (; use) 372.78 170.33 P -5 F --0.69 (-xscrollcommand) 393.31 170.33 P -3 F --0.29 ( where) 483.26 170.33 P -(you used to use) 170.1 158.33 T -5 F -(-scrollcommand) 234.51 158.33 T -3 F -(.) 318.46 158.33 T -FMENDPAGE -%%EndPage: "19" 20 -%%Page: "20" 20 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(20) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -1 F -0 X -(Pr) 152.1 632.33 T -(oblem #31:) 162.46 632.33 T -3 F -(The) 211.88 632.33 T -5 F -(-padx) 229.92 632.33 T -3 F -( and) 259.9 632.33 T -5 F -(-pady) 279.33 632.33 T -3 F -( options are ignored for the button family of wid-) 309.31 632.33 T -(gets if a bitmap or image is being displayed: the padding is always 0.) 152.1 620.02 T -2 F --0.27 (Solution:) 170.1 608.02 P -3 F --0.27 (Pack the button inside a frame, with extra padding in the frame. Or) 208.98 608.02 P --0.27 (, redo the) 472.94 608.02 P -(image or bitmap to incorporate padding into it.) 170.1 595.71 T -1 F -(Pr) 152.1 580.71 T -(oblem #32:) 162.46 580.71 T -3 F -(In radiobuttons, the) 211.88 580.71 T -5 F -(-value) 292.38 580.71 T -3 F -( option no longer defaults to the name of the) 328.36 580.71 T -(widget; it defaults to an empty string.) 152.1 568.4 T -2 F -(Solution:) 170.1 556.4 T -3 F -(Specify the widget\325) 209.25 556.4 T -(s name explicitly as the value of the option.) 286.98 556.4 T -1 F -(Pr) 152.1 541.4 T -(oblem #33:) 162.46 541.4 T -3 F -(The) 211.88 541.4 T -5 F -(-menu) 229.92 541.4 T -3 F -( option for menubuttons and cascade menu entries may refer) 259.9 541.4 T -(only to a child of the menubutton or menu.) 152.1 529.08 T -2 F -(Solution:) 170.1 517.08 T -3 F -(Rename menus to meet this requirement.) 209.25 517.08 T -1 F -(Pr) 152.1 502.08 T -(oblem #34:) 162.46 502.08 T -3 F -(The interpretation of) 211.88 502.08 T -5 F -(@y) 297.09 502.08 T -3 F -( in menus has changed: it never returns) 309.08 502.08 T -5 F -(none) 467.86 502.08 T -3 F -(,) 491.84 502.08 T -(even if the y-coordinate is outside the menu \050it returns the index of the closest entry\051.) 152.1 489.77 T -2 F -(Solution:) 170.1 477.77 T -3 F -(If you care about this distinction, check the y-coordinate explicitly to see if) 209.25 477.77 T --0.17 (it is less than 0 or greater than or equal to the window\325) 170.1 465.46 P --0.17 (s height \050use) 385.7 465.46 P -5 F --0.41 (winfo height) 438.21 465.46 P -3 F -(to get the height\051.) 170.1 453.15 T -1 F --0.13 (Pr) 152.1 438.15 P --0.13 (oblem #35:) 162.46 438.15 P -3 F --0.13 (The) 211.62 438.15 P -5 F --0.3 (invoke) 229.54 438.15 P -3 F --0.13 ( and) 265.52 438.15 P -5 F --0.3 (activate) 284.7 438.15 P -3 F --0.13 ( widget commands for menus no longer post) 332.67 438.15 P -(cascaded submenus.) 152.1 425.83 T -2 F -(Solution:) 170.1 413.83 T -3 F -(Use the) 209.25 413.83 T -5 F -(postcascade) 242 413.83 T -3 F -( widget command to post submenus.) 307.96 413.83 T -1 F -(Pr) 152.1 398.83 T -(oblem #36:) 162.46 398.83 T -3 F -(The selection tar) 211.88 398.83 T -(gets) 278.31 398.83 T -5 F -(APPLICATION) 296.91 398.83 T -3 F -( and) 362.87 398.83 T -5 F -(WINDOW_NAME) 382.3 398.83 T -3 F -( are no longer) 448.27 398.83 T -(supported.) 152.1 386.52 T -2 F -(Solution:) 170.1 374.52 T -3 F -(Use tar) 209.25 374.52 T -(gets) 237.65 374.52 T -5 F -(TK_APPLICATION) 256.25 374.52 T -3 F -( and) 340.21 374.52 T -5 F -(TK_WINDOW) 359.64 374.52 T -3 F -( instead.) 413.61 374.52 T -1 F -(Pr) 152.1 359.52 T -(oblem #37:) 162.46 359.52 T -3 F -(There is no longer a default focus.) 211.88 359.52 T -2 F -(Solution:) 170.1 347.52 T -3 F -(None: modify your code not to depend on this feature.) 209.25 347.52 T -1 F -(Pr) 152.1 332.52 T -(oblem #38:) 162.46 332.52 T -3 F -(The) 211.88 332.52 T -5 F -(focus) 229.92 332.52 T -3 F -( command now returns an empty string to indicate that the) 259.9 332.52 T -(application doesn\325) 152.1 320.21 T -(t have the input focus, instead of) 225.48 320.21 T -5 F -(none) 358.17 320.21 T -3 F -(.) 382.15 320.21 T -2 F -(Solution:) 170.1 308.21 T -3 F -(Modify your code to check for an empty string instead of) 209.25 308.21 T -5 F -(none) 440.47 308.21 T -3 F -(.) 464.46 308.21 T -1 F -(Pr) 152.1 293.21 T -(oblem #39:) 162.46 293.21 T -5 F -(FocusIn) 211.88 293.21 T -3 F -( and) 253.85 293.21 T -5 F -(FocusOut) 273.28 293.21 T -3 F -( events are delivered to more windows than) 321.26 293.21 T -(they used to be.) 152.1 280.9 T -2 F --0.02 (Solution:) 170.1 268.9 P -3 F --0.02 (Modify your code to use the new set of events. The old event set was some-) 209.23 268.9 P -(what bizarre, and the new set matches more closely what happens elsewhere, such as) 170.1 256.58 T -(with) 170.1 244.27 T -5 F -(Enter) 190.37 244.27 T -3 F -( and) 220.35 244.27 T -5 F -(Leave) 239.78 244.27 T -3 F -( events.) 269.77 244.27 T -1 F --0.28 (Pr) 152.1 229.27 P --0.28 (oblem #40:) 162.46 229.27 P -5 F --0.67 (wm maxsize) 211.32 229.27 P -3 F --0.28 ( and) 270.62 229.27 P -5 F --0.67 (wm minsize) 289.49 229.27 P -3 F --0.28 ( no longer accept empty ar) 348.79 229.27 P --0.28 (guments. This) 453.52 229.27 P -(means that you cannot use these commands to make windows non-resizable.) 152.1 216.96 T -2 F -(Solution:) 170.1 204.96 T -3 F -(Use the) 209.25 204.96 T -5 F -(wm resizable) 242 204.96 T -3 F -( command to make windows resizable.) 313.96 204.96 T -1 F -(Pr) 152.1 189.96 T -(oblem #41:) 162.46 189.96 T -3 F -(In the placer) 211.88 189.96 T -(, if you specify both) 261.43 189.96 T -5 F -(-x) 344.15 189.96 T -3 F -( and) 356.15 189.96 T -5 F -(-relx) 375.58 189.96 T -3 F -( then they add, instead of) 405.56 189.96 T -(the most recent speci\336cation replacing the earlier one. Ditto for) 152.1 177.65 T -5 F -(-y) 407.74 177.65 T -3 F -( and) 419.73 177.65 T -5 F -(-rely) 439.16 177.65 T -3 F -(,) 468.5 177.65 T -5 F -(-width) 473.49 177.65 T -3 F -(and) 152.1 165.33 T -5 F -(-relwidth) 169.03 165.33 T -3 F -(, and) 223 165.33 T -5 F -(-height) 244.93 165.33 T -3 F -( and) 286.91 165.33 T -5 F -(-relheight) 306.33 165.33 T -3 F -(.) 366.3 165.33 T -2 F -(Solution:) 170.1 153.33 T -3 F -(If you no longer want one of these options to be used, set it to 0 explicitly) 209.25 153.33 T -(.) 503.14 153.33 T -1 F -(Pr) 152.1 138.33 T -(oblem #42:) 162.46 138.33 T -3 F -(The command \322) 211.88 138.33 T -5 F -(focus none) 276.27 138.33 T -3 F -(\323 doesn\325) 336.24 138.33 T -(t work in Tk 4.0.) 369.64 138.33 T -FMENDPAGE -%%EndPage: "20" 21 -%%Page: "21" 21 -612 792 0 FMBEGINPAGE -4 10 Q -0 X -0 K -(13 Summary of Incompatibilites) 98.1 668.33 T -0 F -(21) 500.99 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -2 F -0 X -(Solution:) 170.1 632.33 T -3 F -(Create a dummy widget that is never mapped and set the focus to that wid-) 209.25 632.33 T -(get.) 170.1 620.33 T -1 F -(Pr) 152.1 605.33 T -(oblem #43:) 162.46 605.33 T -5 F -(%D) 211.88 605.33 T -3 F -( substitutions are no longer supported in bindings, nor are the event) 223.87 605.33 T -(types) 152.1 593.33 T -5 F -(CirculateRequest) 175.7 593.33 T -3 F -(,) 271.64 593.33 T -5 F -(Conf) 276.64 593.33 T -(igureRequest) 300.63 593.33 T -3 F -(,) 372.59 593.33 T -5 F -(MapRequest) 377.59 593.33 T -3 F -(, and) 437.55 593.33 T -5 F -(Resiz-) 459.48 593.33 T -(eRequest) 152.1 581.33 T -3 F -(.) 200.07 581.33 T -2 F --0.25 (Solution:) 170.1 569.33 P -3 F --0.25 (Use the name of the display instead of %D to identify a display; you can get) 209 569.33 P -(the display name with the) 170.1 557.33 T -5 F -(winfo screen) 275.31 557.33 T -3 F -( command. The desupported event types) 347.27 557.33 T -(never really worked anyway) 170.1 545.33 T -(, so there should be no code that depends on them.) 282.96 545.33 T -1 F -(Pr) 152.1 530.33 T -(oblem #44:) 162.46 530.33 T -5 F -(%) 211.88 530.33 T -3 F -( binding substitutions that return window identi\336ers, such as) 217.87 530.33 T -5 F -(%a) 461.63 530.33 T -3 F -( and) 473.62 530.33 T -5 F -(%S) 493.05 530.33 T -3 F -(,) 505.05 530.33 T -(now produce hexadecimal results instead of decimal.) 152.1 518.33 T -2 F -(Solution:) 170.1 506.33 T -3 F -(Use the) 209.25 506.33 T -5 F -(format) 242 506.33 T -3 F -( command to turn them back to decimal.) 277.98 506.33 T -1 F -(Pr) 152.1 491.33 T -(oblem #45:) 162.46 491.33 T -5 F -(Enter) 211.88 491.33 T -3 F -(,) 241.46 491.33 T -5 F -(Leave) 246.46 491.33 T -3 F -(,) 276.44 491.33 T -5 F -(FocusIn) 281.44 491.33 T -3 F -(, and) 323.42 491.33 T -5 F -(FocusOut) 345.34 491.33 T -3 F -( events with detail) 393.32 491.33 T -5 F -(Notify-) 468.83 491.33 T -(Inferior) 152.1 479.33 T -3 F -( are now ignored by the binding mechanism, so they\325re not visible to T) 200.07 479.33 T -(cl) 483.08 479.33 T -(scripts.) 152.1 467.33 T -2 F --0.13 (Solution:) 170.1 455.33 P -3 F --0.13 (In most cases, T) 209.12 455.33 P --0.13 (cl scripts work better if these bindings are ignored. Y) 273 455.33 P --0.13 (ou can) 483.49 455.33 P -(still use C code to access these events if you really need them. Or) 170.1 443.33 T -(, create bindings on) 431.18 443.33 T --0.33 (the inferior windows and use) 170.1 431.33 P -5 F --0.8 (NotifyAncestor) 286.96 431.33 P -3 F --0.33 ( bindings on the children instead of) 370.91 431.33 P -5 F -(NotifyInferior) 170.1 419.33 T -3 F -( bindings on the parent.) 254.05 419.33 T -FMENDPAGE -%%EndPage: "21" 22 -%%Page: "22" 22 -612 792 0 FMBEGINPAGE -0 10 Q -0 X -0 K -(22) 98.1 668.33 T -4 F -(Tk4.0 Overview and Porting Guide) 359.34 668.33 T -98.1 660.6 512.1 660.6 2 L -0.25 H -0 Z -N -98.1 135 512.1 639 R -7 X -V -FMENDPAGE -%%EndPage: "22" 23 -%%Trailer -%%BoundingBox: 0 0 612 792 -%%Pages: 22 1 -%%DocumentFonts: Helvetica-Bold -%%+ Times-Bold -%%+ Times-Italic -%%+ Times-Roman -%%+ Helvetica -%%+ Courier -%%+ Courier-Oblique diff --git a/doc/tkvars.n b/doc/tkvars.n index 5ffa40a..e211575 100644 --- a/doc/tkvars.n +++ b/doc/tkvars.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -geometry, tk_library, tk_patchLevel, tk_strictMotif, tk_version \- Variables used or set by Tk +geometry, tk_library, tk_patchLevel, tk::scalingPct, tk_strictMotif, tk::svgFmt, tk_version \- Variables used or set by Tk .BE .SH DESCRIPTION .PP @@ -50,7 +50,42 @@ 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" . +.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 +widgets and their components, as well as the sizes of the images used by +Tk are chosen according to the scaling percentage, and this is +recommended for applications and library packages, too. +.RS +.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::scalingPct\fR is automatically updated. +.PP +On the windowing systems \fBwin32\fR and \fBaqua\fR the scaling +percentage is computed by rounding [\fBtk scaling\fR] * 75 to the +nearest multiple of 25 that is at least 100. (On \fBaqua\fR the result +is always 100, and the desktop engine automatically scales everything as +needed.) On \fBx11\fR, deriving the scaling percentage from +[\fBtk scaling\fR] is done as fallback method only, because the +implementation of display scaling is highly dependent on the desktop +environment and it mostly manipulates system resources that are resident +outside of Xlib, which Tk is based on. Moreover, for technical reasons, +the value assigned to the variable \fBtk::scalingPct\fR can be different +from the one selected in the system settings (e.g., 200 rather than 125, +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 @@ -61,7 +96,30 @@ closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. Modern applications should not normally set this variable. -.TP 15 +.TP +\fBtk::svgFmt\fR +. +This variable is set at Tk initialization time to +.RS +.RS 4 +.PP +[\fBlist svg \-scale\fR [\fBexpr\fR {$\fBtk::scalingPct\fR / 100.0}]] +.RE +.PP +Typical values are {\fBsvg \-scale\fR 1.0}, {\fBsvg \-scale\fR 1.25}, +{\fBsvg \-scale\fR 2.0}, etc. It is recommended to pass the value of +this variable to the commands \fBimage create photo\fR, \fIimageName\fB +configure\fR, \fIimageName\fB put\fR, and \fIimageName\fB read\fR as the +value of their \fB\-format\fR option when creating or manipulating SVG +images, to make sure that their sizes will correspond to the display's +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. @@ -96,7 +154,7 @@ used by Tk's test suite. The following variables are only guaranteed to exist in \fBwish\fR executables; the Tk library does not define them itself but many Tk environments do. -.TP 6 +.TP \fBgeometry\fR . If set, contains the user-supplied geometry specification to use for diff --git a/doc/toplevel.n b/doc/toplevel.n index 95fab5b..6e5ec0e 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -25,6 +25,17 @@ except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. +.VS "8.7, TIP262" +An empty background will disable drawing the background image. +.OP \-backgroundimage backgroundImage BackgroundImage +This specifies an image to display on the toplevel's background within +the border of the toplevel (i.e., the image will be clipped by the +toplevel's highlight ring and border, if either are present) on top of +the background; +subwidgets of the toplevel will be drawn on top. The image must have +been created with the \fBimage create\fR command. If specified as the +empty string, no image will be displayed. +.VE "8.7, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for @@ -57,7 +68,7 @@ widget command. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will +If this option is negative or zero then the window will not request any size at all. .OP \-menu menu Menu Specifies a menu widget to be used as a menubar. On the Macintosh, the @@ -73,6 +84,15 @@ Defaults to the same screen as its parent. This option is special in that it may not be specified via the option database, and it may not be modified with the \fBconfigure\fR widget command. +.OP \-tile tile Tile +.VS "8.7, TIP262" +This specifies how to draw the background image (see +\fB\-backgroundimage\fR) on the toplevel. +If true (according to \fBTcl_GetBoolean\fR), the image will be tiled +to fill the whole toplevel, with the origin of the first copy of the +image being the top left of the interior of the toplevel. +If false (the default), the image will be centered within the toplevel. +.VE "8.7, TIP262" .OP \-use use Use This option is used for embedding. If the value is not an empty string, it must be the window identifier of a container window, specified as @@ -93,7 +113,7 @@ widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will +If this option is negative or zero then the window will not request any size at all. .BE .SH DESCRIPTION @@ -111,7 +131,7 @@ top-level window: its X parent is the root window of a screen rather than the logical parent from its Tk path name. The primary purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only visible features -of a toplevel are its background color and an optional 3-D border +of a toplevel are its background and an optional 3-D border to make the toplevel appear raised or sunken. .SH "WIDGET COMMAND" .PP @@ -121,7 +141,7 @@ command may be used to invoke various operations on the widget. It has the following general form: .PP .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 index 0f8a171..20295d1 100644 --- a/doc/ttk_Geometry.3 +++ b/doc/ttk_Geometry.3 @@ -100,7 +100,8 @@ A bitmask containing one or more of the bits \fBTTK_STICK_E\fR (east, or right), \fBTTK_STICK_N\fR (north, or top), and \fBTTK_STICK_S\fR (south, or bottom). -\fBTTK_FILL_X\fR is defined as a synonym for (\fBTTK_STICK_W\fR|\fBTTK_STICK_E\fR), +\fBTTK_FILL_X\fR is defined as a synonym for +(\fBTTK_STICK_W\fR|\fBTTK_STICK_E\fR), \fBTTK_FILL_Y\fR is a synonym for (\fBTTK_STICK_N\fR|\fBTTK_STICK_S\fR), and \fBTTK_FILL_BOTH\fR is a synonym for (\fBTTK_FILL_X\fR|\fBTTK_FILL_Y\fR). diff --git a/doc/ttk_button.n b/doc/ttk_button.n index cf42e28..4c24a45 100644 --- a/doc/ttk_button.n +++ b/doc/ttk_button.n @@ -10,14 +10,14 @@ .SH NAME ttk::button \- Widget that issues a command when pressed .SH SYNOPSIS -\fBttk::button\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::button\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION A \fBttk::button\fR widget displays a textual label and/or image, and evaluates a command when pressed. .SO ttk_widget \-class \-compound \-cursor -\-image \-state \-style +\-image \-justify \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE @@ -48,15 +48,26 @@ with an extra highlight ring, or with a different border color. .SH "WIDGET COMMAND" .PP In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, buttons support the following additional widget commands: +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +button widgets support the following additional commands: +.\" METHOD: invoke .TP \fIpathName \fBinvoke\fR +. Invokes the command associated with the button. .SH "STANDARD STYLES" .PP \fBTtk::button\fR widgets support the \fBToolbutton\fR style in all standard themes, which is useful for creating widgets for toolbars. +.PP +In the Aqua theme there are several other styles which can be used to +produce replicas of many of the different button types that are +discussed in Apple's Human Interface Guidelines. These include +\fBDisclosureButton\fR, \fBDisclosureTriangle\fR, \fBHelpButton\fR, +\fBImageButton\fR, \fBInlineButton\fR, \fBGradientButton\fR, +\fBRoundedRectButton\fR, and \fBRecessedButton\fR. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::button\fP is \fBTButton\fP. @@ -94,7 +105,7 @@ are: .RS \fB\-shiftrelief\fP specifies how far the button contents are shifted down and right in the \fIpressed\fP state. -This action provides additional skeumorphic feedback. +This action provides additional skeuomorphic feedback. .RE \fB\-width\fP \fIamount\fP .PP diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n index c78dc0e..e49b414 100644 --- a/doc/ttk_checkbutton.n +++ b/doc/ttk_checkbutton.n @@ -10,7 +10,7 @@ .SH NAME ttk::checkbutton \- On/off widget .SH SYNOPSIS -\fBttk::checkbutton\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::checkbutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION A \fBttk::checkbutton\fR widget is used to show or change a setting. @@ -37,11 +37,14 @@ Defaults to the widget pathname if not specified. .SH "WIDGET COMMAND" .PP In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, checkbuttons support the following additional -widget commands: +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +checkbutton widgets support the following additional commands: +.\" METHOD: invoke .TP \fIpathname\fB invoke\fR +. Toggles between the selected and deselected states and evaluates the associated \fB\-command\fR. If the widget is currently selected, sets the \fB\-variable\fR diff --git a/doc/ttk_combobox.n b/doc/ttk_combobox.n index 37b91aa..3c88f84 100644 --- a/doc/ttk_combobox.n +++ b/doc/ttk_combobox.n @@ -10,7 +10,7 @@ .SH NAME ttk::combobox \- text field with popdown selection list .SH SYNOPSIS -\fBttk::combobox\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::combobox\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -19,7 +19,7 @@ the user may select the value of the text field from among the values in the list. .SO ttk_widget \-class \-cursor \-takefocus -\-style +\-style \-placeholder \-placeholderforeground .SE .\" ALSO: Other entry widget options .SH "WIDGET-SPECIFIC OPTIONS" @@ -55,57 +55,42 @@ Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. .SH "WIDGET COMMAND" .PP -The following subcommands are possible for combobox widgets: -'\".TP -'\"\fIpathName \fBcget\fR \fIoption\fR -'\"Returns the current value of the specified \fIoption\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -'\"Modify or query widget options. -'\"See \fIttk::widget(n)\fR. +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +combobox widgets support the following additional commands: +.\" METHOD: current .TP \fIpathName \fBcurrent\fR ?\fInewIndex\fR? +. If \fInewIndex\fR is supplied, sets the combobox value to the element at position \fInewIndex\fR in the list of \fB\-values\fR (in addition to integers, the \fBend\fR index is supported and indicates -the last element of the list). +the last element of the list, moreover the same simple interpretation as +for the command \fBstring index\fR is supported, with simple integer index +arithmetic and indexing relative to \fBend\fR). Otherwise, returns the index of the current value in the list of -\fB\-values\fR or \fB\-1\fR if the current value does not appear in the list. +\fB\-values\fR or \fB{}\fR if the current value does not appear in the list. +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the current value of the combobox. -'\".TP -'\"\fIpathName \fBidentify \fIx y\fR -'\"Returns the name of the element at position \fIx\fR, \fIy\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBinstate \fIstateSpec\fR ?\fIscript\fR? -'\"Test the widget state. -'\"See \fIttk::widget(n)\fR. +.\" METHOD: set .TP -\fIpathName \fBset\fR \fIvalue\fR +\fIpathName \fBset\fI value\fR +. Sets the value of the combobox to \fIvalue\fR. -'\".TP -'\"\fIpathName \fBstate\fR ?\fIstateSpec\fR? -'\"Modify or query the widget state. -'\"See \fIttk::widget(n)\fR. .PP The combobox widget also supports the following \fBttk::entry\fR -widget subcommands (see \fIttk::entry(n)\fR for details): +widget commands: .DS .ta 5.5c 11c \fBbbox\fR \fBdelete\fR \fBicursor\fR \fBindex\fR \fBinsert\fR \fBselection\fR \fBxview\fR .DE -The combobox widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR \fBidentify\fR -\fBinstate\fR \fBstate\fR -.DE .SH "VIRTUAL EVENTS" .PP The combobox widget generates a \fB<<ComboboxSelected>>\fR virtual event @@ -150,6 +135,8 @@ Can only be changed when using non-native and non-graphical themes. .br \fB\-padding\fP \fIpadding\fP .br +\fB\-placeholderforeground\fP \fIcolor\fP +.br \fB\-postoffset\fP \fIpadding\fP .br \fB\-selectbackground\fP \fIcolor\fP diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index da183f7..4f8e0a3 100644 --- a/doc/ttk_entry.n +++ b/doc/ttk_entry.n @@ -12,7 +12,7 @@ .SH NAME ttk::entry \- Editable text field widget .SH SYNOPSIS -\fBttk::entry\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::entry\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -26,7 +26,7 @@ standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. \-class \-cursor \-font \-foreground \-style -\-takefocus \-xscrollcommand +\-takefocus \-xscrollcommand \-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection @@ -82,7 +82,7 @@ See \fBVALIDATION\fR below. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. -.\" Not in ttk: If the value is less than or equal to zero, the widget picks a +.\" Not in ttk: If the value is negative or zero, the widget picks a .\" Not in ttk: size just large enough to hold its current text. .SH NOTES .PP @@ -137,11 +137,20 @@ or .QW \fBsel.l\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. .SH "WIDGET COMMAND" .PP -The following subcommands are possible for entry widgets: +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR, \fBstyle\fR and \fBxview\fR +commands (see \fBttk::widget\fR), +entry widgets support the following additional commands: +.\" 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 @@ -150,16 +159,10 @@ the upper-left corner of the screen area covered by the character the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. -'\".TP -'\"\fIpathName \fBcget\fR \fIoption\fR -'\"Returns the current value of the specified \fIoption\fR. -'\"See \fIttk::widget(n)\fR. -'\".TP -'\"\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -'\"Modify or query widget options. -'\"See \fIttk::widget(n)\fR. +.\" 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 @@ -167,69 +170,64 @@ one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns the empty string. +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the entry's string. +.\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR +. Arrange for the insert cursor to be displayed just before the character given by \fIindex\fR. Returns the empty string. -'\".TP -'\"\fIpathName \fBidentify \fIx y\fR -'\"Returns the name of the element at position \fIx\fR, \fIy\fR, -'\"or the empty string if the coordinates are outside the window. +.\" 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 \fIstring\fR just before the character indicated by \fIindex\fR. Returns the empty string. -'\".TP -'\"\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -'\"Test the widget state. -'\"See \fIttk::widget(n)\fR. +.\" 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 clear\fR +. Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns the empty string. .TP \fIpathName \fBselection present\fR +. Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. .TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR +\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. .RE -'\".TP -'\"\fIpathName \fBstate\fR ?\fIstateSpec\fR? -'\"Modify or query the widget state. -'\"See \fIttk::widget(n)\fR. +.\" METHOD: validate .TP \fIpathName \fBvalidate\fR +. Force revalidation, independent of the conditions specified by the \fB\-validate\fR option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the \fBinvalid\fR state accordingly. See \fBVALIDATION\fR below for more details. -.PP -The entry widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR \fBidentify\fR -\fBinstate\fR \fBstate\fR \fBxview\fR -.DE .SH VALIDATION .PP The \fB\-validate\fR, \fB\-validatecommand\fR, and \fB\-invalidcommand\fR @@ -444,7 +442,8 @@ value is specified for \fB\-fieldbackground\fP. Otherwise it is ignored. .br \fB\-fieldbackground\fP \fIcolor\fP .RS -Some themes use a graphical background and their field background colors cannot be changed. +Some themes use a graphical background and their field background colors +cannot be changed. .RE \fB\-foreground\fP \fIcolor\fP .br @@ -456,6 +455,8 @@ Some themes use a graphical background and their field background colors cannot .br \fB\-padding\fP \fIpadding\fP .br +\fB\-placeholderforeground\fP \fIcolor\fP +.br \fB\-relief\fP \fIrelief\fP .br \fB\-selectbackground\fP \fIcolor\fP diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n index ee52bed..8095016 100644 --- a/doc/ttk_frame.n +++ b/doc/ttk_frame.n @@ -10,7 +10,7 @@ .SH NAME ttk::frame \- Simple container widget .SH SYNOPSIS -\fBttk::frame\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::frame\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -35,9 +35,10 @@ If specified, the widget's requested width in pixels. If specified, the widget's requested height in pixels. .SH "WIDGET COMMAND" .PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. +Frame widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .SH "NOTES" .PP Note that if the \fBpack\fR, \fBgrid\fR, or other geometry managers diff --git a/doc/ttk_image.n b/doc/ttk_image.n index 34dbabb..300a0e4 100644 --- a/doc/ttk_image.n +++ b/doc/ttk_image.n @@ -10,7 +10,7 @@ .SH NAME ttk_image \- Define an element based on an image .SH SYNOPSIS -\fBttk::style element create \fIname\fR \fBimage\fR \fIimageSpec\fR ?\fIoptions\fR? +\fBttk::style element create \fIname \fBimage\fI imageSpec\fR ?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -25,24 +25,30 @@ in a particular state or combination of states. .SH OPTIONS .PP Valid \fIoptions\fR are: +.\" OPTION: -border .TP -\fB\-border\fR \fIpadding\fR +\fB\-border\fI padding\fR +. \fIpadding\fR is a list of up to four integers, specifying the left, top, right, and bottom borders, respectively. If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right border; -a list of two numbers specify the horizontal and the vertical border; +In other words, a list of three numbers specify the left, vertical, and right +border; a list of two numbers specify the horizontal and the vertical border; a single number specifies the same border all the way around the element. See \fBIMAGE STRETCHING\fR, below. +.\" OPTION: -height .TP \fB\-height \fIheight\fR +. Specifies a minimum height for the element. -If less than zero, the base image's height is used as a default. +If negative, the base image's height is used as a default. +.\" OPTION: -padding .TP -\fB\-padding\fR \fIpadding\fR +\fB\-padding\fI padding\fR +. Specifies the element's interior padding. The padding is a list of up to four length specifications \fIleft top right bottom\fR. @@ -50,12 +56,14 @@ If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; +In other words, a list of three numbers specify the left, vertical, and right +padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. Defaults to \fB\-border\fR if not specified. +.\" OPTION: -sticky .TP -\fB\-sticky\fR \fIspec\fR +\fB\-sticky\fI spec\fR +. Specifies how the image is placed within the final parcel. \fIspec\fR contains zero or more characters .QW n , @@ -63,10 +71,12 @@ Specifies how the image is placed within the final parcel. .QW w , or .QW e . +.\" OPTION: -width .TP \fB\-width \fIwidth\fR +. Specifies a minimum width for the element. -If less than zero, the base image's width is used as a default. +If negative, the base image's width is used as a default. .SH "IMAGE STRETCHING" .PP If the element's allocated parcel is larger than the image, @@ -85,12 +95,12 @@ as a background image) should use \fB\-width 0\fR and \fB\-height 0\fR. .SH "EXAMPLE" .PP .CS -set img1 [image create photo \-file button.png] -set img2 [image create photo \-file button-pressed.png] -set img3 [image create photo \-file button-active.png] +set img1 [image create photo -file button.png] +set img2 [image create photo -file button-pressed.png] +set img3 [image create photo -file button-active.png] ttk::style element create Button.button image \e [list $img1 pressed $img2 active $img3] \e - \-border {2 4} \-sticky we + -border {2 4} -sticky we .CE .SH "SEE ALSO" ttk::intro(n), ttk::style(n), ttk_vsapi(n), image(n), photo(n) diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n index f93cbe3..783ebb6 100644 --- a/doc/ttk_intro.n +++ b/doc/ttk_intro.n @@ -83,10 +83,10 @@ For example, the layout for a horizontal scrollbar is: .PP .CS ttk::\fBstyle layout\fR Horizontal.TScrollbar { - Scrollbar.trough \-children { - Scrollbar.leftarrow \-side left \-sticky w - Scrollbar.rightarrow \-side right \-sticky e - Scrollbar.thumb \-sticky ew + Scrollbar.trough -children { + Scrollbar.leftarrow -side left -sticky w + Scrollbar.rightarrow -side right -sticky e + Scrollbar.thumb -sticky ew } } .CE @@ -121,7 +121,7 @@ widget are: .CS bind TButton <Enter> { %W state active } bind TButton <Leave> { %W state !active } -bind TButton <ButtonPress-1> { %W state pressed } +bind TButton <Button-1> { %W state pressed } bind TButton <Button1-Leave> { %W state !pressed } bind TButton <Button1-Enter> { %W state pressed } bind TButton <ButtonRelease-1> \e @@ -151,9 +151,9 @@ For example: .PP .CS ttk::\fBstyle configure\fR TButton \e - \-background #d9d9d9 \e - \-foreground black \e - \-relief raised \e + -background #d9d9d9 \e + -foreground black \e + -relief raised \e ; .CE .PP @@ -165,9 +165,9 @@ for a particular style: .PP .CS ttk::\fBstyle map\fR TButton \e - \-background [list disabled #d9d9d9 active #ececec] \e - \-foreground [list disabled #a3a3a3] \e - \-relief [list {pressed !disabled} sunken] \e + -background [list disabled #d9d9d9 active #ececec] \e + -foreground [list disabled #a3a3a3] \e + -relief [list {pressed !disabled} sunken] \e ; .CE .SH "SEE ALSO" diff --git a/doc/ttk_label.n b/doc/ttk_label.n index 271c711..49f6d6c 100644 --- a/doc/ttk_label.n +++ b/doc/ttk_label.n @@ -10,7 +10,7 @@ .SH NAME ttk::label \- Display a text string and/or image .SH SYNOPSIS -\fBttk::label\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::label\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -18,31 +18,17 @@ A \fBttk::label\fR widget displays a textual label and/or image. The label may be linked to a Tcl variable to automatically change the displayed text. .SO ttk_widget -\-class \-compound \-cursor -\-image \-padding \-state -\-style \-takefocus \-text -\-textvariable \-underline \-width +\-anchor \-class \-compound +\-cursor \-font \-foreground +\-image \-justify \-padding +\-state \-style \-takefocus +\-text \-textvariable \-underline +\-width \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" -.OP \-anchor anchor Anchor -Specifies how the information in the widget is positioned -relative to the inner margins. Legal values are -\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR. -See also \fB\-justify\fR. .OP \-background frameColor FrameColor The widget's background color. If unspecified, the theme default is used. -.OP \-font font Font -Font to use for label text. -.OP \-foreground textColor TextColor -The widget's foreground color. -If unspecified, the theme default is used. -.OP \-justify justify Justify -If there are multiple lines of text, specifies how -the lines are laid out relative to one another. -One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -See also \fB\-anchor\fR. .OP \-relief relief Relief .\" Rewrite this: Specifies the 3-D effect desired for the widget border. @@ -51,15 +37,16 @@ Valid values are and \fBsunken\fR. .OP \-wraplength wrapLength WrapLength Specifies the maximum line length (in pixels). -If this option is less than or equal to zero, +If this option is negative or zero, then automatic wrapping is not performed; otherwise the text is split into lines such that no line is longer than the specified value. .SH "WIDGET COMMAND" .PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. +Label widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .SH "STYLING OPTIONS" .PP The class name for a \fBttk::label\fP is \fBTLabel\fP. diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n index 5797690..8423da3 100644 --- a/doc/ttk_labelframe.n +++ b/doc/ttk_labelframe.n @@ -10,7 +10,7 @@ .SH NAME ttk::labelframe \- Container widget with optional label .SH SYNOPSIS -\fBttk::labelframe\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::labelframe\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -62,9 +62,10 @@ sets the keyboard focus to the first child of the \fBttk::labelframe\fR widget. If specified, the widget's requested width in pixels. .SH "WIDGET COMMAND" .PP -Supports the standard widget commands -\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; -see \fIttk::widget(n)\fR. +Labelframe widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .SH "STYLING OPTIONS" .PP The class name for a \fBttk::labelframe\fP is \fBTLabelframe\fP. diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n index 0d80c1e..5578835 100644 --- a/doc/ttk_menubutton.n +++ b/doc/ttk_menubutton.n @@ -10,7 +10,7 @@ .SH NAME ttk::menubutton \- Widget that pops down a menu when pressed .SH SYNOPSIS -\fBttk::menubutton\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::menubutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -38,9 +38,10 @@ menubutton. .\" .OP \-padding padding Pad .SH "WIDGET COMMAND" .PP -Menubutton widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. +Menubutton widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .SH "STANDARD STYLES" .PP \fBTtk::menubutton\fR widgets support the \fBToolbutton\fR style in all diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index 293f018..b7844a7 100644 --- a/doc/ttk_notebook.n +++ b/doc/ttk_notebook.n @@ -11,10 +11,10 @@ ttk::notebook \- Multi-paned container widget .SH SYNOPSIS .nf -\fBttk::notebook\fR \fIpathname \fR?\fIoptions...\fR? +\fBttk::notebook\fI pathname \fR?\fIoptions...\fR? .br -\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBadd\fI window\fR ?\fIoptions...\fR? +\fIpathname \fBinsert\fI index window\fR ?\fIoptions...\fR? .fi .BE .SH DESCRIPTION @@ -41,8 +41,8 @@ If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; +In other words, a list of three numbers specify the left, vertical, and right +padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. .OP \-width width Width If present and greater than zero, @@ -101,70 +101,86 @@ The literal string which returns the number of tabs (only valid for .QW "\fIpathname \fBindex\fR" ). +.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. .SH "WIDGET COMMAND" +.PP +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +notebook widgets support the following additional commands: +.\" METHOD: add .TP \fIpathname \fBadd \fIwindow\fR ?\fIoptions...\fR? +. Adds a new tab to the notebook. See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR. If \fIwindow\fR is currently managed by the notebook but hidden, it is restored to its previous position. -.TP -\fIpathname \fBconfigure\fR ?\fIoptions\fR? -See \fIttk::widget(n)\fR. -.TP -\fIpathname \fBcget \fIoption\fR -See \fIttk::widget(n)\fR. +.\" METHOD: forget .TP \fIpathname \fBforget \fItabid\fR +. Removes the tab specified by \fItabid\fR, unmaps and unmanages the associated window. +.\" METHOD: hide .TP \fIpathname \fBhide \fItabid\fR +. Hides the tab specified by \fItabid\fR. The tab will not be displayed, but the associated window remains managed by the notebook and its configuration remembered. Hidden tabs may be restored with the \fBadd\fR command. +.\" METHOD: identify .TP \fIpathname \fBidentify\fI component x y\fR +. Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. The following subcommands are supported: .RS .TP -\fIpathname \fBidentify element\fR \fIx y\fR +\fIpathname \fBidentify element\fI x y\fR +. Returns the name of the element at the specified location. .TP -\fIpathname \fBidentify tab\fR \fIx y\fR +\fIpathname \fBidentify tab\fI x y\fR +. Returns the index of the tab at the specified location. .RE +.\" METHOD: index .TP \fIpathname \fBindex \fItabid\fR +. Returns the numeric index of the tab specified by \fItabid\fR, or the total number of tabs if \fItabid\fR is the string .QW \fBend\fR . +.\" METHOD: insert .TP \fIpathname \fBinsert \fIpos subwindow options...\fR +. Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. If \fIsubwindow\fR is already managed by the notebook, moves it to the specified position. See \fBTAB OPTIONS\fR for the list of available options. -.TP -\fIpathname \fBinstate \fIstatespec \fR?\fIscript...\fR? -See \fIttk::widget(n)\fR. +.\" METHOD: select .TP \fIpathname \fBselect\fR ?\fItabid\fR? +. Selects the specified tab. The associated content window will be displayed, and the previously-selected window (if different) is unmapped. If \fItabid\fR is omitted, returns the widget name of the currently selected pane. -.TP -\fIpathname \fBstate\fR ?\fIstatespec\fR? -See \fIttk::widget(n)\fR. +.\" METHOD: tab .TP \fIpathname \fBtab \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR +. Query or modify the options of the specific tab. If no \fI\-option\fR is specified, returns a dictionary of the tab option values. @@ -172,8 +188,10 @@ If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. See \fBTAB OPTIONS\fR for the available options. +.\" METHOD: tabs .TP \fIpathname \fBtabs\fR +. Returns the list of windows managed by the notebook, in the index order of their associated tabs. .SH "KEYBOARD TRAVERSAL" @@ -203,8 +221,8 @@ virtual event after a new tab is selected. .SH "EXAMPLE" .CS pack [\fBttk::notebook\fR .nb] -\&.nb add [frame .nb.f1] \-text "First tab" -\&.nb add [frame .nb.f2] \-text "Second tab" +\&.nb add [frame .nb.f1] -text "First tab" +\&.nb add [frame .nb.f2] -text "Second tab" \&.nb select .nb.f2 ttk::notebook::enableTraversal .nb .CE @@ -285,8 +303,10 @@ Some themes (e.g., \fBclam\fP) use a different \fIpadding\fP for the selected tab. For example, the Ttk library file \fBclamTheme.tcl\fP contains the lines .CS -ttk::style configure TNotebook.Tab -padding {6 2 6 2} -ttk::style map TNotebook.Tab -padding {selected {6 4 6 2}} +ttk::style configure TNotebook.Tab \\ + -padding {4.5p 1.5p 4.5p 1.5p} +ttk::style map TNotebook.Tab \\ + -padding {selected {4.5p 3p 4.5p 1.5p}} .CE which are valid for the default value \fBnw\fP of the \fB\-tabposition\fP style option. Again, for a different tab position you will have to adapt diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index 5b6f728..d834ecb 100644 --- a/doc/ttk_panedwindow.n +++ b/doc/ttk_panedwindow.n @@ -11,10 +11,10 @@ ttk::panedwindow \- Multi-pane container window .SH SYNOPSIS .nf -\fBttk::panedwindow\fR \fIpathname \fR?\fIoptions\fR? +\fBttk::panedwindow\fI pathname \fR?\fIoptions\fR? .br -\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBadd\fI window\fR ?\fIoptions...\fR? +\fIpathname \fBinsert\fI index window\fR ?\fIoptions...\fR? .fi .BE .SH DESCRIPTION @@ -48,19 +48,28 @@ An integer specifying the relative stretchability of the pane. When the paned window is resized, the extra space is added or subtracted to each pane proportionally to its \fB\-weight\fR. .SH "WIDGET COMMAND" -Supports the standard \fBconfigure\fR, \fBcget\fR, \fBstate\fR, -and \fBinstate\fR commands; see \fIttk::widget(n)\fR for details. -Additional commands: +.PP +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +panedwindow widgets support the following additional commands: +.\" METHOD: add .TP \fIpathname \fBadd \fIsubwindow options...\fR +. Adds a new pane to the window. See \fBPANE OPTIONS\fR for the list of available options. +.\" METHOD: forget .TP \fIpathname \fBforget \fIpane\fR +. Removes the specified subpane from the widget. \fIpane\fR is either an integer index or the name of a managed subwindow. +.\" METHOD: identify .TP \fIpathname \fBidentify \fIcomponent x y\fR +. Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. If \fIcomponent\fR is omitted, it defaults to \fBsash\fR. @@ -68,33 +77,43 @@ The following subcommands are supported: .RS .TP \fIpathname \fBidentify element \fIx y\fR +. Returns the name of the element at the specified location. .TP \fIpathname \fBidentify sash \fIx y\fR +. Returns the index of the sash at the specified location. .RE +.\" METHOD: insert .TP \fIpathname \fBinsert \fIpos subwindow options...\fR +. Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. If \fIsubwindow\fR is already managed by the paned window, moves it to the specified position. See \fBPANE OPTIONS\fR for the list of available options. +.\" METHOD: pane .TP \fIpathname \fBpane \fIpane \-option \fR?\fIvalue \fR?\fI\-option value...\fR +. Query or modify the options of the specified \fIpane\fR, where \fIpane\fR is either an integer index or the name of a managed subwindow. If no \fI\-option\fR is specified, returns a dictionary of the pane option values. If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. +.\" METHOD: panes .TP \fIpathname \fBpanes\fR +. Returns the list of all windows managed by the widget, in the index order of their associated panes. +.\" METHOD: sashpos .TP \fIpathname \fBsashpos \fIindex\fR ?\fInewpos\fR? +. If \fInewpos\fR is specified, sets the position of sash number \fIindex\fR. May adjust the positions of adjacent sashes @@ -106,14 +125,6 @@ and the total size of the widget. .\" depending on which changed most recently. Returns the new position of sash number \fIindex\fR. .\" Full story: new position may be different than the requested position. -.PP -The panedwindow widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBcget\fR \fBconfigure\fR -\fBinstate\fR \fBstate\fR -.DE .SH "VIRTUAL EVENTS" .PP The panedwindow widget generates an \fB<<EnteredChild>>\fR virtual event on diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n index 5d6316a..aae3f46 100644 --- a/doc/ttk_progressbar.n +++ b/doc/ttk_progressbar.n @@ -10,7 +10,7 @@ .SH NAME ttk::progressbar \- Provide progress feedback .SH SYNOPSIS -\fBttk::progressbar\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::progressbar\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -19,14 +19,22 @@ operation. They can operate in two modes: \fIdeterminate\fR mode shows the amount completed relative to the total amount of work to be done, and \fIindeterminate\fR mode provides an animated display to let the user know that something is happening. +.PP +If the value of \fB\-orient\fR is \fBhorizontal\fR a text string can be +displayed inside the progressbar. This string can be configured using +the \fB\-anchor\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-justify\fR, +\fB\-text\fR and \fB\-wraplength\fR options. If the value of \fB\-orient\fR +is \fBvertical\fR then these options are ignored. .SO ttk_widget -\-class \-cursor \-takefocus -\-style +\-anchor \-class \-cursor +\-font \-foreground \-justify \-style +\-takefocus \-text \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-length length Length Specifies the length of the long axis of the progress bar -(width if horizontal, height if vertical). +(width if horizontal, height if vertical). The value may have any of the forms +acceptable to \fBTk_GetPixels\fR. .OP \-maximum maximum Maximum A floating point number specifying the maximum \fB\-value\fR. Defaults to 100. @@ -58,34 +66,29 @@ automatically set to the value of the variable whenever the latter is modified. .SH "WIDGET COMMAND" .PP -.TP -\fIpathName \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +progressbar widgets support the following additional commands: +.\" METHOD: start .TP \fIpathName \fBstart\fR ?\fIinterval\fR? +. Begin autoincrement mode: schedules a recurring timer event that calls \fBstep\fR every \fIinterval\fR milliseconds. If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. +.\" METHOD: step .TP \fIpathName \fBstep\fR ?\fIamount\fR? +. Increments the \fB\-value\fR by \fIamount\fR. \fIamount\fR defaults to 1.0 if omitted. +.\" METHOD: stop .TP \fIpathName \fBstop\fR +. Stop autoincrement mode: cancels any recurring timer event initiated by \fIpathName \fBstart\fR. .SH "STYLING OPTIONS" diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n index 2dc84be..74777dc 100644 --- a/doc/ttk_radiobutton.n +++ b/doc/ttk_radiobutton.n @@ -10,7 +10,7 @@ .SH NAME ttk::radiobutton \- Mutually exclusive option widget .SH SYNOPSIS -\fBttk::radiobutton\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::radiobutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -37,11 +37,14 @@ Default value is \fB::selectedButton\fR. .SH "WIDGET COMMAND" .PP In addition to the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -commands, radiobuttons support the following additional -widget commands: +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +radiobutton widgets support the following additional commands: +.\" METHOD: invoke .TP \fIpathname\fB invoke\fR +. Sets the \fB\-variable\fR to the \fB\-value\fR, selects the widget, and evaluates the associated \fB\-command\fR. Returns the result of the \fB\-command\fR, or the empty diff --git a/doc/ttk_scale.n b/doc/ttk_scale.n index 32686a6..c9f0298 100644 --- a/doc/ttk_scale.n +++ b/doc/ttk_scale.n @@ -51,29 +51,19 @@ Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. .SH "WIDGET COMMAND" .PP -.TP -\fIpathName \fBcget \fIoption\fR -. -Returns the current value of the specified \fIoption\fR; see -\fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Modify or query widget options; see \fIttk::widget(n)\fR. +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +scale widgets support the following additional commands: +.\" METHOD: get .TP \fIpathName \fBget \fR?\fIx y\fR? . Get the current value of the \fB\-value\fR option, or the value corresponding to the coordinates \fIx,y\fR if they are specified. \fIX\fR and \fIy\fR are pixel coordinates relative to the scale widget origin. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -. -Test the widget state; see \fIttk::widget(n)\fR. +.\" METHOD: see .TP \fIpathName \fBset \fIvalue\fR . @@ -81,12 +71,9 @@ Set the value of the widget (i.e. the \fB\-value\fR option) to \fIvalue\fR. The value will be clipped to the range given by the \fB\-from\fR and \fB\-to\fR options. Note that setting the linked variable (i.e. the variable named in the \fB\-variable\fR option) does not cause such clipping. -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -. -Modify or query the widget state; see \fIttk::widget(n)\fR. .SH "INTERNAL COMMANDS" .PP +.\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index bd80760..406d70d 100644 --- a/doc/ttk_scrollbar.n +++ b/doc/ttk_scrollbar.n @@ -11,7 +11,7 @@ .SH NAME ttk::scrollbar \- Control the viewport of a scrollable widget .SH SYNOPSIS -\fBttk::scrollbar\fR \fIpathName \fR?\fIoptions...\fR? +\fBttk::scrollbar\fI pathName \fR?\fIoptions...\fR? .BE .SH DESCRIPTION .PP @@ -47,38 +47,33 @@ One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the scrollbar. .SH "WIDGET COMMAND" .PP -.TP -\fIpathName \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +commands (see \fBttk::widget\fR), +scrollbar widgets support the following additional commands: +.\" 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. -.TP -\fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. +.\" METHOD: set .TP \fIpathName \fBset \fIfirst last\fR +. This command is normally invoked by the scrollbar's associated widget from an \fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. Specifies the visible range to be displayed. \fIfirst\fR and \fIlast\fR are real fractions between 0 and 1. -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. .SH "INTERNAL COMMANDS" .PP The following widget commands are used internally by the \fBTScrollbar\fP widget class bindings. +.\" 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 thumb position. For example, if the scrollbar is horizontal, @@ -88,8 +83,10 @@ ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the thumb \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. +.\" 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, where 0.0 corresponds to the top or left of the trough @@ -110,6 +107,7 @@ In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like \fB.t yview\fR .TP \fIprefix \fBmoveto \fIfraction\fR +. \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. @@ -118,15 +116,8 @@ document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .TP -\fIprefix \fBscroll \fInumber \fBunits\fR -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. -.TP \fIprefix \fBscroll \fInumber \fBpages\fR +. The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there @@ -134,6 +125,15 @@ is a slight overlap between the old and new views. \fINumber\fR is either 1, which means the next page should become visible, or \-1, which means that the previous page should become visible. +.TP +\fIprefix \fBscroll \fInumber \fBunits\fR +. +The widget should adjust its view by \fInumber\fR units. +The units are defined in whatever way makes sense for the widget, +such as characters or lines in a text widget. +\fINumber\fR is either 1, which means one unit should scroll off +the top or left of the window, or \-1, which means that one unit +should scroll off the bottom or right of the window. .SH "WIDGET STATES" .PP The scrollbar automatically sets the \fBdisabled\fR state bit. @@ -145,14 +145,14 @@ of individual elements, based on the position and state of the mouse pointer. .PP .CS set f [frame .f] -ttk::scrollbar $f.hsb \-orient horizontal \-command [list $f.t xview] -ttk::scrollbar $f.vsb \-orient vertical \-command [list $f.t yview] -text $f.t \-xscrollcommand [list $f.hsb set] \-yscrollcommand [list $f.vsb set] -grid $f.t \-row 0 \-column 0 \-sticky nsew -grid $f.vsb \-row 0 \-column 1 \-sticky nsew -grid $f.hsb \-row 1 \-column 0 \-sticky nsew -grid columnconfigure $f 0 \-weight 1 -grid rowconfigure $f 0 \-weight 1 +\fBttk::scrollbar\fR $f.hsb -orient horizontal -command [list $f.t xview] +\fBttk::scrollbar\fR $f.vsb -orient vertical -command [list $f.t yview] +text $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set] +grid $f.t -row 0 -column 0 -sticky nsew +grid $f.vsb -row 0 -column 1 -sticky nsew +grid $f.hsb -row 1 -column 0 -sticky nsew +grid columnconfigure $f 0 -weight 1 +grid rowconfigure $f 0 -weight 1 pack $f .CE .SH "STYLING OPTIONS" diff --git a/doc/ttk_separator.n b/doc/ttk_separator.n index 4befb0a..dacd10e 100644 --- a/doc/ttk_separator.n +++ b/doc/ttk_separator.n @@ -10,7 +10,7 @@ .SH NAME ttk::separator \- Separator bar .SH SYNOPSIS -\fBttk::separator\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::separator\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -26,9 +26,10 @@ One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the separator. .SH "WIDGET COMMAND" .PP -Separator widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. +Separator widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .PP .SH "STYLING OPTIONS" .PP diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index 707a17e..050d0bf 100644 --- a/doc/ttk_sizegrip.n +++ b/doc/ttk_sizegrip.n @@ -10,7 +10,7 @@ .SH NAME ttk::sizegrip \- Bottom-right corner resize widget .SH SYNOPSIS -\fBttk::sizegrip\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::sizegrip\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -23,9 +23,10 @@ by pressing and dragging the grip. .SE .SH "WIDGET COMMAND" .PP -Sizegrip widgets support the standard -\fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR -methods. No other widget methods are used. +Sizegrip widgets support the standard commands +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR and \fBstyle\fR +(see \fBttk::widget\fR). .SH "PLATFORM-SPECIFIC NOTES" .PP On Mac OSX, toplevel windows automatically include a built-in @@ -36,14 +37,14 @@ the built-in grip will just mask the widget. .PP Using pack: .CS -pack [ttk::frame $top.statusbar] \-side bottom \-fill x -pack [\fBttk::sizegrip\fR $top.statusbar.grip] \-side right \-anchor se +pack [ttk::frame $top.statusbar] -side bottom -fill x +pack [\fBttk::sizegrip\fR $top.statusbar.grip] -side right -anchor se .CE .PP Using grid: .CS grid [\fBttk::sizegrip\fR $top.statusbar.grip] \e - \-row $lastRow \-column $lastColumn \-sticky se + -row $lastRow -column $lastColumn -sticky se # ... optional: add vertical scrollbar in $lastColumn, # ... optional: add horizontal scrollbar in $lastRow .CE diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n index 5b6d42a..4c7d23a 100644 --- a/doc/ttk_spinbox.n +++ b/doc/ttk_spinbox.n @@ -10,7 +10,7 @@ .SH NAME ttk::spinbox \- Selecting text field widget .SH SYNOPSIS -\fBttk::spinbox\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::spinbox\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -23,6 +23,7 @@ to a Tcl variable. .SO ttk_widget \-class \-cursor \-state \-style \-takefocus \-xscrollcommand +\-placeholder \-placeholderforeground .SE .SO ttk_entry \-validate \-validatecommand @@ -36,15 +37,15 @@ when using the \fB\-from\fR and \fB\-to\fR range. This must be a format specifier of the form \fB%<pad>.<pad>f\fR, as it will format a floating-point number. .OP \-from from From -A floating\-point value specifying the lowest value for the spinbox. This is +A floating-point value specifying the lowest value for the spinbox. This is used in conjunction with \fB\-to\fR and \fB\-increment\fR to set a numerical range. .OP \-increment increment Increment -A floating\-point value specifying the change in value to be applied each +A floating-point value specifying the change in value to be applied each time one of the widget spin buttons is pressed. The up button applies a positive increment, the down button applies a negative increment. .OP \-to to To -A floating\-point value specifying the highest permissible value for the +A floating-point value specifying the highest permissible value for the widget. See also \fB\-from\fR and \fB\-increment\fR. range. .OP \-values values Values @@ -66,11 +67,15 @@ See the \fBttk::entry\fR manual for information about using the .PP The following subcommands are possible for spinbox widgets in addition to the commands described for the \fBttk::entry\fR widget: +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the spinbox's current value. +.\" METHOD: set .TP \fIpathName \fBset \fIvalue\fR +. Set the spinbox string to \fIvalue\fR. If a \fB\-format\fR option has been configured then this format will be applied. If formatting fails or is not set or the \fB\-values\fR option has been used then the value @@ -115,6 +120,8 @@ value is specified for \fB\-fieldbackground\fP. Otherwise it is ignored. .br \fB\-padding\fP \fIpadding\fP .br +\fB\-placeholderforeground\fP \fIcolor\fP +.br \fB\-selectbackground\fP \fIcolor\fP .br \fB\-selectforeground\fP \fIcolor\fP diff --git a/doc/ttk_style.n b/doc/ttk_style.n index 5d7b5d1..85d6a06 100644 --- a/doc/ttk_style.n +++ b/doc/ttk_style.n @@ -10,7 +10,7 @@ .SH NAME ttk::style \- Manipulate style database .SH SYNOPSIS -\fBttk::style\fR \fIoption\fR ?\fIargs\fR? +\fBttk::style\fI option\fR ?\fIargs\fR? .BE .SH NOTES .PP @@ -27,17 +27,29 @@ this may be overridden by the \fB\-style\fR option. .PP A \fItheme\fR is a collection of elements and styles which controls the overall look and feel of an application. +The +.QW . +style is the theme root style on which derived styles are based. .SH DESCRIPTION .PP The \fBttk::style\fR command takes the following arguments: +.\" METHOD: configure .TP \fBttk::style configure \fIstyle\fR ?\fI\-option\fR ?\fIvalue option value...\fR? ? +. Sets the default value of the specified option(s) in \fIstyle\fR. -.TP -\fBttk::style element\fR \fIargs\fR +If \fIstyle\fR does not exist, it is created. +If only \fIstyle\fR and \fI\-option\fR are specified, get the default value +for option \fI\-option\fR of style \fIstyle\fR. +If only \fIstyle\fR is specified, get the default value for all options +of style \fIstyle\fR. +.\" METHOD: element +.TP +\fBttk::style element\fI args\fR .RS .TP -\fBttk::style element create\fR \fIelementName\fR \fItype\fR ?\fIargs...\fR? +\fBttk::style element create\fI elementName type\fR ?\fIargs...\fR? +. Creates a new element in the current theme of type \fItype\fR. The only cross-platform built-in element type is \fIimage\fR (see \fBttk_image\fR(n)) but themes may define other element types @@ -46,19 +58,25 @@ an element factory is registered to create Windows theme elements (see \fBttk_vsapi\fR(n)). .TP \fBttk::style element names\fR +. Returns the list of elements defined in the current theme. .TP \fBttk::style element options \fIelement\fR +. Returns the list of \fIelement\fR's options. .RE +.\" METHOD: layout .TP \fBttk::style layout \fIstyle\fR ?\fIlayoutSpec\fR? +. Define the widget layout for style \fIstyle\fR. See \fBLAYOUTS\fR below for the format of \fIlayoutSpec\fR. If \fIlayoutSpec\fR is omitted, return the layout specification for style \fIstyle\fR. +.\" METHOD: lookup .TP -\fBttk::style lookup \fIstyle\fR \fI\-option \fR?\fIstate \fR?\fIdefault\fR?? +\fBttk::style lookup \fIstyle \-option \fR?\fIstate \fR?\fIdefault\fR?? +. Returns the value specified for \fI\-option\fR in style \fIstyle\fR in state \fIstate\fR, using the standard lookup rules for element options. \fIstate\fR is a list of state names; if omitted, @@ -68,17 +86,27 @@ state). If the \fIdefault\fR argument is present, it is used as a fallback value in case no specification for \fI\-option\fR is found. .\" Otherwise -- signal error? return empty string? Leave unspecified for now. +If \fIstyle\fR does not exist, it is created. +.\" METHOD: map .TP \fBttk::style map \fIstyle\fR ?\fI\-option\fB { \fIstatespec value...\fB }\fR? -Sets dynamic values of the specified option(s) in \fIstyle\fR. +. +Sets dynamic (state dependent) values of the specified option(s) in \fIstyle\fR. Each \fIstatespec / value\fR pair is examined in order; the value corresponding to the first matching \fIstatespec\fR is used. -.TP -\fBttk::style theme\fR \fIargs\fR +If \fIstyle\fR does not exist, it is created. +If only \fIstyle\fR and \fI\-option\fR are specified, get the dynamic values +for option \fI\-option\fR of style \fIstyle\fR. +If only \fIstyle\fR is specified, get the dynamic values for all options +of style \fIstyle\fR. +.\" METHOD: theme +.TP +\fBttk::style theme\fI args\fR .RS .TP -\fBttk::style theme create\fR \fIthemeName\fR ?\fB\-parent \fIbasedon\fR? ?\fB\-settings \fIscript...\fR ? +\fBttk::style theme create\fI themeName\fR ?\fB\-parent \fIbasedon\fR? ?\fB\-settings \fIscript...\fR ? +. Creates a new theme. It is an error if \fIthemeName\fR already exists. If \fB\-parent\fR is specified, the new theme will inherit styles, elements, and layouts from the parent theme \fIbasedon\fR. @@ -86,15 +114,23 @@ If \fB\-settings\fR is present, \fIscript\fR is evaluated in the context of the new theme as per \fBttk::style theme settings\fR. .TP \fBttk::style theme names\fR +. Returns a list of all known themes. .TP -\fBttk::style theme settings \fIthemeName\fR \fIscript\fR +\fBttk::style theme settings \fIthemeName script\fR +. Temporarily sets the current theme to \fIthemeName\fR, evaluate \fIscript\fR, then restore the previous theme. Typically \fIscript\fR simply defines styles and elements, though arbitrary Tcl code may appear. .TP +\fBttk::style theme styles\fR ?\fIthemeName\fR? +. +Returns a list of all styles in \fIthemeName\fR. If \fIthemeName\fR +is omitted, the current theme is used. +.TP \fBttk::style theme use\fR ?\fIthemeName\fR? +. Without an argument the result is the name of the current theme. Otherwise this command sets the current theme to \fIthemeName\fR, and refreshes all widgets. @@ -111,18 +147,25 @@ the allocated parcel. Valid options are: .\" -border should remain undocumented for now (dubious usefulness) .\" .TP -.\" \fB\-border\fR \fIboolean\fR +.\" \fB\-border\fI boolean\fR +.\" . .\" Specifies whether the element is drawn after its children. Defaults to 0. +.\" OPTION: -children .TP \fB\-children { \fIsublayout...\fB }\fR +. Specifies a list of elements to place inside the element. +.\" OPTION: -expand .TP -\fB\-expand\fR \fIboolean\fR +\fB\-expand\fI boolean\fR +. Specifies whether the allocated parcel is the entire cavity. If so, simultaneous specification of \fB\-side\fR is ignored. Defaults to 0. +.\" OPTION: -side .TP \fB\-side \fIside\fR +. Specifies which side of the cavity to place the element; one of \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. For instance, \fB\-side top\fR allocates the parcel along the top of @@ -130,27 +173,57 @@ the cavity having width and height respectively the width of the cavity and the height of the element. If omitted, the allocated parcel is the entire cavity (same effect as \fB\-expand\fR 1). +.\" OPTION: -sticky .TP \fB\-sticky\fR \fB[\fInswe\fB]\fR +. Specifies the actual parcel position and size inside the allocated parcel. If specified as an empty string then the actual parcel is centered in the allocated parcel. Default is \fBnswe\fR. .\" -unit should remain undocumented for now (dubious usefulness) .\" .TP -.\" \fB\-unit\fR \fIboolean\fR +.\" \fB\-unit\fI boolean\fR +.\" . .\" Specifies whether the element propagates its state to its children. .\" Defaults to 0. .PP For example: .CS ttk::style layout Horizontal.TScrollbar { - Scrollbar.trough \-children { - Scrollbar.leftarrow \-side left - Scrollbar.rightarrow \-side right - Horizontal.Scrollbar.thumb \-side left \-sticky ew + Scrollbar.trough -children { + Scrollbar.leftarrow -side left + Scrollbar.rightarrow -side right + Horizontal.Scrollbar.thumb -side left -sticky ew } } .CE +.SH ROOT STYLE +.PP +The +.QW . +theme root style can be configured like any other style, providing defaults +for its derived styles. In addition to the usual options, +.QW . +styling options configurable with \fBttk::style\fP are: +.PP +\fB\-insertofftime\fP \fIamount\fP +.RS +Specifies a non-negative integer value indicating the number of milliseconds +the insertion cursor should remain +.QW off +in each blink cycle. If this option is zero then the cursor does not blink: +it is on all the time. Defaults to 300 ms, unless overriden with a +\fBRESOURCE_MANAGER\fR property or \fB.Xdefaults\fR file. +.RE +.PP +\fB\-insertontime\fP \fIamount\fP +.RS +Specifies a non-negative integer value indicating the number of milliseconds +the insertion cursor should remain +.QW on +in each blink cycle. Defaults to 600 ms, unless overriden with a +\fBRESOURCE_MANAGER\fR property or \fB.Xdefaults\fR file. +.RE .SH "SEE ALSO" ttk::intro(n), ttk::widget(n), photo(n), ttk_image(n) .SH KEYWORDS diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index b10e0f8..2531772 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -62,7 +62,7 @@ If set to \fB#all\fP (the default), all columns are shown in the order given. .OP \-height height Height Specifies the number of rows which should be visible. -Note: +Note that the requested width is determined from the sum of the column widths. .OP \-selectmode selectMode SelectMode Controls how the built-in class bindings manage the selection. @@ -76,6 +76,9 @@ If \fBnone\fR, the selection will not be changed. Note that application code and tag bindings can set the selection however they wish, regardless of the value of \fB\-selectmode\fR. .RE +.OP \-selecttype selectType SelectType +Controls how the built-in class bindings manage the selection. +One of \fBitem\fR or \fBcell\fR. .OP \-show show Show A list containing zero or more of the following values, specifying which elements of the tree to display. @@ -85,27 +88,91 @@ Display tree labels in column #0. .IP \fBheadings\fR Display the heading row. .PP -The default is \fBtree headings\fR, i.e., show all elements. +The default is \fBtree headings\fR. .PP \fBNOTE:\fR Column #0 always refers to the tree column, even if \fB\-show tree\fR is not specified. .RE +.OP \-striped striped Striped +Boolean specifying zebra striped item coloring. +Note that +striped items uses the \fB\-stripedbackground\fR option if set by the theme or +a tag. If not supported by the current theme, it will not show. +.OP \-titlecolumns titleColumns TitleColumns +Number of display columns at the left that should not be scrolled. The tree +column counts, even if \fB\-show tree\fR is not specified. Thus for value N of +this option, column #N is the first one that is scrollable. Default is 0. +.OP \-titleitems titleItems TitleItems +Number of items at the top that should not be vertically scrolled. Default is 0. .SH "WIDGET COMMAND" .PP +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, +\fBstate\fR, \fBstyle\fR, \fBxview\fR and \fByview\fR +commands (see \fBttk::widget\fR), +treeview widgets support the following additional commands: +.\" METHOD: bbox .TP \fIpathname \fBbbox \fIitem\fR ?\fIcolumn\fR? +. Returns the bounding box (relative to the treeview widget's window) -of the specified \fIitem\fR -in the form \fIx y width height\fR. -If \fIcolumn\fR is specified, returns the bounding box of that cell. +of the specified \fIitem\fR in the form \fIx y width height\fR. If the \fIitem\fR is not visible -(i.e., if it is a descendant of a closed item or is scrolled offscreen), -returns the empty list. +(i.e., if it is a descendant of a closed item or is vertically scrolled +offscreen), returns the empty list. +If \fIcolumn\fR is specified and is not hidden (by the \fB\-displaycolumns\fR +option), returns the bounding box of that cell within \fIitem\fR +(even if the cell is horizontally scrolled offscreen). +.\" METHOD: cellselection +.TP +\fIpathname \fBcellselection\fR ?\fIselop arg ...\fR? +. +Manages cell selection. Cell selection is independent from item selection +handled by the \fBselection\fR command. A cell is given by a list of two +elements, item and column. +For the rectangle versions of commands, the cells must be in displayed columns. +Any change to \fB\-columns\fR clears the cell selection. +A \fIcellList\fR argument may be a single cell or a list of cells. +If \fIselop\fR is not specified, returns the list of selected cells. +Otherwise, \fIselop\fR is one of the following: +.RS +.TP +\fIpathname \fBcellselection set \fIcellList\fR +. +\fIcellList\fR becomes the new cell selection. +.TP +\fIpathname \fBcellselection set \fIfirstCell lastCell\fR +. +The rectangle defined becomes the new cell selection. +.TP +\fIpathname \fBcellselection add \fIcellList\fR +. +Add \fIcellList\fR to the cell selection. .TP -\fIpathname \fBcget \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. +\fIpathname \fBcellselection add \fIfirstCell lastCell\fR +. +The rectangle defined is added to the cell selection. +.TP +\fIpathname \fBcellselection remove \fIcellList\fR +. +Remove \fIcellList\fR from the cell selection. +.TP +\fIpathname \fBcellselection remove \fIfirstCell lastCell\fR +. +The rectangle defined is removed from the cell selection. +.TP +\fIpathname \fBcellselection toggle \fIcellList\fR +. +Toggle the cell selection state of each cell in \fIcellList\fR. +.TP +\fIpathname \fBcellselection toggle \fIfirstCell lastCell\fR +. +Toggle the cell selection state of each cell in the rectangle defined. +.RE +.\" METHOD: children .TP \fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? +. If \fInewchildren\fR is not specified, returns the list of children belonging to \fIitem\fR. .RS @@ -117,8 +184,10 @@ are detached from the tree. None of the items in \fInewchildren\fR may be an ancestor of \fIitem\fR. .RE +.\" METHOD: column .TP \fIpathname \fBcolumn \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. Query or modify the options for the specified \fIcolumn\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. @@ -127,48 +196,66 @@ returns the value of that option. Otherwise, the options are updated with the specified values. The following options may be set on each column: .RS +.\" OPTION: -id .TP \fB\-id \fIname\fR +. The column name. This is a read-only option. For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] -returns the data column associated with display column #\fIn\fR. +returns the data column associated with display column \fIn\fR. +The tree column has \fB\-id #0\fR. +.\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR +. Specifies how the text in this column should be aligned with respect to the cell. \fIAnchor\fR is one of \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. +.\" OPTION: -minwidth .TP \fB\-minwidth \fIminwidth\fR +. The minimum width of the column in pixels. The treeview widget will not make the column any smaller than \fB\-minwidth\fR when the widget is resized or the user drags a -column separator. Default is 20 pixels. +heading column separator. Default is 20 pixels. +.\" OPTION: -separator +.TP +\fB\-separator \fIboolean\fR +. +Specifies whether or not a column separator should be drawn to the right +of the column. Default is false. +.\" OPTION: -stretch .TP \fB\-stretch \fIboolean\fR +. Specifies whether or not the column width should be adjusted -when the widget is resized or the user drags a column separator. +when the widget is resized or the user drags a heading column separator. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. By default columns are stretchable. +.\" OPTION: -width .TP \fB\-width \fIwidth\fR +. The width of the column in pixels. Default is 200 pixels. The specified column width may be changed by Tk in order to honor \fB\-stretch\fR and/or \fB\-minwidth\fR, or when the widget is resized or the user drags a -column separator. +heading column separator. .PP -Use \fIpathname column #0\fR to configure the tree column. +Use \fIpathname fBcolumn #0\fR to configure the tree column. .RE -.TP -\fIpathname \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options; see \fIttk::widget(n)\fR. +.\" METHOD: delete .TP \fIpathname \fBdelete \fIitemList\fR +. Deletes each of the items in \fIitemList\fR and all of their descendants. The root item may not be deleted. See also: \fBdetach\fR. +.\" METHOD: detach .TP \fIpathname \fBdetach \fIitemList\fR +. Unlinks all of the specified items in \fIitemList\fR from the tree. The items and all of their descendants are still present and may be reinserted at another point in the tree @@ -176,43 +263,66 @@ with the \fBmove\fR operation, but will not be displayed until that is done. The root item may not be detached. See also: \fBdelete\fR. +.\" METHOD: detached +.TP +\fIpathname \fBdetached \fR?\fIitem\fR? +. +If \fIitem\fR is provided, returns a boolean value indicating whether it is +the name of a detached item (see \fBdetach\fR). Otherwise, returns a list of +all the detached items (in an arbitrary order). The root item is never +detached. +.\" METHOD: exists .TP \fIpathname \fBexists \fIitem\fR +. Returns 1 if the specified \fIitem\fR is present in the tree, 0 otherwise. +.\" METHOD: focus .TP \fIpathname \fBfocus \fR?\fIitem\fR? +. If \fIitem\fR is specified, sets the focus item to \fIitem\fR. Otherwise, returns the current focus item, or \fB{}\fR if there is none. .\" Need: way to clear the focus item. {} works for this... +.\" +.\" METHOD: heading .TP \fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. Query or modify the heading options for the specified \fIcolumn\fR. Valid options are: .RS +.\" OPTION: -text .TP \fB\-text \fItext\fR +. The text to display in the column heading. +.\" OPTION: -image .TP \fB\-image \fIimageName\fR +. Specifies an image to display to the right of the column heading. +.\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR +. Specifies how the heading text should be aligned. One of the standard Tk anchor values. +.\" OPTION: -command .TP \fB\-command \fIscript\fR +. A script to evaluate when the heading label is pressed. .PP Use \fIpathname heading #0\fR to configure the tree column heading. .RE +.\" METHOD: identify .TP \fIpathname \fBidentify \fIcomponent x y\fR +. Returns a description of the specified \fIcomponent\fR under the point given by \fIx\fR and \fIy\fR, or the empty string if no such \fIcomponent\fR is present at that position. -The values \fIx\fR and \fIy\fR may have any of the forms acceptable to -\fBTk_GetPixels\fR. The following subcommands are supported: .RS .TP @@ -233,34 +343,48 @@ The tree area. .IP cell A data cell. .RE +.TP \fIpathname \fBidentify item \fIx y\fR +. Returns the item ID of the item at position \fIy\fR. .TP \fIpathname \fBidentify column \fIx y\fR +. Returns the display column identifier of the cell at position \fIx\fR. The tree column has ID \fB#0\fR. .TP +\fIpathname \fBidentify cell \fIx y\fR +. +Returns the cell identifier of the cell at position \fIx y\fR. +A cell identifier is a list of item ID and column ID. +.TP \fIpathname \fBidentify element \fIx y\fR +. The element at position \fIx,y\fR. .TP \fIpathname \fBidentify row \fIx y\fR +. Obsolescent synonym for \fIpathname \fBidentify item\fR. .PP See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns and data columns. .RE +.\" METHOD: index .TP \fIpathname \fBindex \fIitem\fR +. Returns the integer index of \fIitem\fR within its parent's list of children. +.\" METHOD: insert .TP \fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR +. Creates a new item. \fIparent\fR is the item ID of the parent item, or the empty string \fB{}\fR to create a new top-level item. \fIindex\fR is an integer, or the value \fBend\fR, specifying where in the list of \fIparent\fR's children to insert the new item. -If \fIindex\fR is less than or equal to zero, +If \fIindex\fR is negative or zero, the new node is inserted at the beginning; if \fIindex\fR is greater than or equal to the current number of children, it is inserted at the end. @@ -273,11 +397,10 @@ Otherwise, a new unique identifier is generated. newly created item. See \fBITEM OPTIONS\fR for the list of available options. .RE -.TP -\fIpathname \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state; see \fIttk::widget(n)\fR. +.\" METHOD: item .TP \fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. Query or modify the options for the specified \fIitem\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. @@ -285,85 +408,145 @@ If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the item's options are updated with the specified values. See \fBITEM OPTIONS\fR for the list of available options. +.\" METHOD: move .TP \fIpathname \fBmove \fIitem parent index\fR +. Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. It is illegal to move an item under one of its descendants. .RS .PP -If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved +If \fIindex\fR is negative or zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. .RE +.\" METHOD: next .TP \fIpathname \fBnext \fIitem\fR +. Returns the identifier of \fIitem\fR's next sibling, or \fB{}\fR if \fIitem\fR is the last child of its parent. +.\" METHOD: parent .TP \fIpathname \fBparent \fIitem\fR +. Returns the ID of the parent of \fIitem\fR, or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. +.\" METHOD: prev .TP \fIpathname \fBprev \fIitem\fR +. Returns the identifier of \fIitem\fR's previous sibling, or \fB{}\fR if \fIitem\fR is the first child of its parent. +.\" METHOD: see .TP \fIpathname \fBsee \fIitem\fR +. Ensure that \fIitem\fR is visible: sets all of \fIitem\fR's ancestors to \fB\-open true\fR, and scrolls the widget if necessary so that \fIitem\fR is within the visible portion of the tree. +.\" METHOD: selection .TP \fIpathname \fBselection\fR ?\fIselop itemList\fR? +. +Manages item selection. Item selection is independent from cell selection +handled by the \fBcellselection\fR command. If \fIselop\fR is not specified, returns the list of selected items. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBselection set \fIitemList\fR +. \fIitemList\fR becomes the new selection. .TP \fIpathname \fBselection add \fIitemList\fR -Add \fIitemList\fR to the selection +. +Add \fIitemList\fR to the selection. .TP \fIpathname \fBselection remove \fIitemList\fR -Remove \fIitemList\fR from the selection +. +Remove \fIitemList\fR from the selection. .TP \fIpathname \fBselection toggle \fIitemList\fR +. Toggle the selection state of each item in \fIitemList\fR. .RE +.\" METHOD: set .TP \fIpathname \fBset \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? +. With one argument, returns a dictionary of column/value pairs for the specified \fIitem\fR. With two arguments, returns the current value of the specified \fIcolumn\fR. With three arguments, sets the value of column \fIcolumn\fR in item \fIitem\fR to the specified \fIvalue\fR. See also \fBCOLUMN IDENTIFIERS\fR. -.TP -\fIpathname \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state; see \fIttk::widget(n)\fR. +.\" METHOD: tag .TP \fIpathName \fBtag \fIargs...\fR +. +Manages tags. Tags can be set on items as well as on cells. +The set of tags is shared between items and cells. However item tagging is +independent from cell tagging (for instance adding a tag on an item does +not also add this tag on the cells in that item). Cell tags take precedence +over item tags when drawing. +The following subcommands are supported: .RS .TP +\fIpathName \fBtag add \fItag items\fR +. +Adds the specified \fItag\fR to each of the listed \fIitems\fR. +If \fItag\fR is already present for a particular item, +then the \fB\-tags\fR for that item are unchanged. +.TP \fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? +. Add a Tk binding script for the event sequence \fIsequence\fR to the tag \fItagName\fR. When an X event is delivered to an item, binding scripts for each of the item's \fB\-tags\fR are evaluated in order as per \fIbindtags(n)\fR. +If the event can be associated with a cell (i.e. mouse events) any +bindings for the cell's \fB\-tags\fR are evaluated as well. .RS .PP -\fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events +\fB<Key>\fR, \fB<KeyRelease>\fR, and virtual events are sent to the focus item. -\fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events +\fB<Button>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events are sent to the item under the mouse pointer. No other event types are supported. .PP The binding \fIscript\fR undergoes \fB%\fR-substitutions before -evaluation; see \fBbind(n)\fR for details. +evaluation; see \fBbind\fR(n) for details. +.RE +.TP +\fIpathName \fBtag cell \fIsubcommand...\fR +. +Manages tags on individual cells. +A \fIcellList\fR argument may be a single cell or a list of cells. +.RS +.TP +\fIpathName \fBtag cell add \fItag cellList\fR +. +Adds the specified \fItag\fR to each of the listed \fIcellList\fR. +If \fItag\fR is already present for a particular cell, +then the tag list for that cell is unchanged. +.TP +\fIpathName \fBtag cell has \fItagName\fR ?\fIcell\fR? +. +If \fIcell\fR is specified, returns 1 or 0 +depending on whether the specified cell has the named tag. +Otherwise, returns a list of all cells which have +the specified tag. +.TP +\fIpathName \fBtag cell remove \fItag\fR ?\fIcellList\fR? +. +Removes the specified \fItag\fR from each of the listed \fIcellList\fR. +If \fIcellList\fR is omitted, removes \fItag\fR from each cell in the tree. .RE .TP \fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue option value...\fR? +. Query or modify the options for the specified \fItagName\fR. If one or more \fIoption/value\fR pairs are specified, sets the value of those options for the specified tag. @@ -374,42 +557,46 @@ With no additional arguments, returns a dictionary of the option settings for \fItagName\fR. See \fBTAG OPTIONS\fR for the list of available options. .TP +\fIpathName \fBtag delete \fItagName\fR +. +Deletes all tag information for the \fItagName\fR argument. The command +removes the tag from all items and cells in the widget and also deletes any +other information associated with the tag, such as bindings and display +information. The command returns an empty string. +.TP \fIpathName \fBtag has \fItagName\fR ?\fIitem\fR? +. If \fIitem\fR is specified, returns 1 or 0 depending on whether the specified item has the named tag. Otherwise, returns a list of all items which have the specified tag. .TP \fIpathName \fBtag names\fR +. Returns a list of all tags used by the widget. .TP -\fIpathName \fBtag add \fItag items\fR -Adds the specified \fItag\fR to each of the listed \fIitems\fR. -If \fItag\fR is already present for a particular item, -then the \fB\-tags\fR for that item are unchanged. -.TP \fIpathName \fBtag remove \fItag\fR ?\fIitems\fR? +. Removes the specified \fItag\fR from each of the listed \fIitems\fR. If \fIitems\fR is omitted, removes \fItag\fR from each item in the tree. If \fItag\fR is not present for a particular item, then the \fB\-tags\fR for that item are unchanged. .RE -.PP -The treeview widget also supports the following generic \fBttk::widget\fR -widget subcommands (see \fIttk::widget(n)\fR for details): -.DS -.ta 5.5c 11c -\fBxview\fR \fByview\fR -.DE .SH "ITEM OPTIONS" .PP The following item options may be specified for items in the \fBinsert\fR and \fBitem\fR widget commands. -.OP \-text text Text -The textual label to display for the item. -.OP \-image image Image -A Tk image, displayed to the left of the label. -.OP \-values values Values +.IP \fB\-text\fR +The textual label to display for the item in the tree column. +.IP \fB\-height\fR +The height for the item, in integer multiples of \fB\-rowheight\fP. Default is 1. +.IP \fB\-image\fR +A Tk image, displayed next to the label in the tree column, placed according +to \fB\-imageanchor\fR. +.IP \fB\-imageanchor\fR +Specifies how the \fB\-image\fR is displayed relative to the text. +Default is \fBw\fR. One of the standard Tk anchor values. +.IP \fB\-values\fR The list of values associated with the item. .RS .PP @@ -420,10 +607,14 @@ the remaining values are assumed empty. If there are more values than columns, the extra values are ignored. .RE -.OP \-open open Open +.IP \fB\-hidden\fR +A boolean value indicating whether this item +should be displayed (\fB\-hidden false\fR) or hidden (\fB\-hidden true\fR). +If a parent is hidden, all its decendants are hidden too. +.IP \fB\-open\fR A boolean value indicating whether the item's children should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). -.OP \-tags tags Tags +.IP \fB\-tags\fR A list of tags associated with this item. .SH "TAG OPTIONS" .PP @@ -434,16 +625,27 @@ Specifies the text foreground color. Specifies the cell or item background color. .IP \fB\-font\fR Specifies the font to use when drawing text. -.\" ??? Maybe: .IP \-anchor -.\" ??? Maybe: .IP \-padding -.\" ??? Maybe: .IP \-text .IP \fB\-image\fR -Specifies the item image, in case the item's \fB\-image\fR option is empty. +Specifies the cell or item image. +.IP \fB\-imageanchor\fR +Specifies the cell or item image anchor. +.IP \fB\-padding\fR +Specifies the cell padding. A data cell will have a default padding of {4 0} +.IP \fB\-stripedbackground\fR +Specifies the cell or item background color for alternate lines, +if \fB\-striped\fR is true. +.PP .\" .PP .\" \fI(@@@ TODO: sort out order of precedence for options)\fR .PP -Tag priority is decided by the creation order: tags created first receive -higher priority. +Tags on cells have precedence over tags on items. Then, tag priority is +decided by the creation order: tags created first receive higher priority. +An item's options, like \fB\-image\fR and \fB\-imageanchor\fR, have priority +over tags. +.SH "IMAGES" +The -image option on an item, and on an item tag, controls the image next to +the label in the tree column. +Other cells can have images through the cell tag -image option. .SH "COLUMN IDENTIFIERS" .PP Column identifiers take any of the following forms: @@ -455,6 +657,10 @@ An integer \fIn\fR, specifying the \fIn\fRth data column. A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, specifying the \fIn\fRth display column. .PP +Column identifiers support the same simple interpretation as +for the command \fBstring index\fR, with simple integer index +arithmetic and indexing relative to \fBend\fR. +.PP \fBNOTE:\fR Item \fB\-values\fR may be displayed in a different order than the order in which they are stored. @@ -473,7 +679,7 @@ Again, \fBcolumn #0 always refers to the tree column\fR. .PP The treeview widget generates the following virtual events. .IP <<TreeviewSelect>> -Generated whenever the selection changes. +Generated whenever the selection or cellselection changes. It might also be generated when selection is affected but not actually changed. Further, multiple selection changes could happen before events can be processed leading to multiple events with the same visible selection. @@ -509,14 +715,14 @@ are: .br \fB\-indent\fP \fIamount\fP .RS -Specifies how far items are indented from their parents. Defaults to 20 pixels. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +Specifies how many pixels items are indented from their parents. Defaults to 20. .RE .br -\fB\-rowheight\fP \fIamount\fP +\fB\-columnseparatorwidth\fP \fIpixels\fP +.br +\fB\-rowheight\fP \fIpixels\fP .RS -This is the standard height for an item. Defaults to 20 pixels. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +This is the standard height for an item. If \fB\-rowheight\fP is not set by the style, it is set by measuring an item and a cell layout with the style's settings. This thus picks up the font and @@ -524,16 +730,16 @@ any focus ring or padding from the theme's layout. The \fB\-rowheight\fP may need to be set to make sure that a row is large enough to contain any images. .PP -To adjust the \fB\-rowheight\fP for the Treeview style, use the following code -after \fBtk scaling\fP has been applied. -Note that even if you do not support or change \fBtk scaling\fP -in your program, your users may have it set in their .wishrc. +Example of how to set \fB\-rowheight\fP, adapting to a font in a similar +way to how the default value is set: .RE .PP .CS ttk::style configure Treeview \\ - \-rowheight [expr {[font metrics \fIfont\fP \-linespace] + 2}] + -rowheight [expr {[font metrics \fIfont\fP -linespace] + 2}] .CE +.br +\fB\-stripedbackground\fP \fIcolor\fP .PP \fBHeading\fP styling options configurable with \fBttk::style\fP are: diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index af63c39..4b7e3cc 100644 --- a/doc/ttk_vsapi.n +++ b/doc/ttk_vsapi.n @@ -10,7 +10,7 @@ .SH NAME ttk_vsapi \- Define a Microsoft Visual Styles element .SH SYNOPSIS -\fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR \fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR? +\fBttk::style element create \fIname \fBvsapi\fI className partId\fR ?\fIstateMap\fR? ?\fIoptions\fR? .BE .SH DESCRIPTION .PP @@ -21,13 +21,14 @@ on Windows XP and Vista. This factory permits any of the Visual Styles parts to be declared as Ttk elements that can then be included in a style layout to modify the appearance of Ttk widgets. .PP -\fIclassName\fR and \fIpartId\fR are required parameters and specify +The \fIclassName\fR and \fIpartId\fR are required parameters and specify the Visual Styles class and part as given in the Microsoft documentation. The \fIstateMap\fR may be provided to map Ttk states to Visual Styles API states (see \fBSTATE MAP\fR). .SH "OPTIONS" .PP Valid \fIoptions\fR are: +.\" OPTION: -padding .TP \fB\-padding \fIpadding\fR . @@ -38,10 +39,11 @@ If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. -In other words, a list of three numbers specify the left, vertical, and right padding; -a list of two numbers specify the horizontal and the vertical padding; +In other words, a list of three numbers specify the left, vertical, and right +padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. This option may not be mixed with any other options. +.\" OPTION: -margins .TP \fB\-margins \fIpadding\fR . @@ -49,6 +51,7 @@ Specifies the elements exterior padding. \fIpadding\fR is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options. +.\" OPTION: -width .TP \fB\-width \fIwidth\fR . @@ -57,6 +60,7 @@ the Visual Styles API will not be queried for the recommended size or the part. If this option is set then \fB\-height\fR should also be set. The \fB\-width\fR and \fB\-height\fR options cannot be mixed with the \fB\-padding\fR or \fB\-margins\fR options. +.\" OPTION: -height .TP \fB\-height \fIheight\fR . diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index f21135d..8b5732d 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -71,6 +71,12 @@ See the description of \fB\-xscrollcommand\fR above for details. .SH "LABEL OPTIONS" The following options are supported by labels, buttons, and other button-like widgets: +.OP \-anchor anchor Anchor +Specifies how the information in the widget is positioned +relative to the inner margins. Legal values are +\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, +\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR. +See also \fB\-justify\fR (for widgets supporting this option). .OP \-compound compound Compound Specifies how to display the image relative to the text, in the case both \fB\-text\fR and \fB\-image\fR are present. @@ -106,6 +112,11 @@ The rest of the list is a sequence of \fIstatespec / value\fR pairs as per \fBstyle map\fR, specifying different images to use when the widget is in a particular state or combination of states. All images in the list should have the same size. +.OP \-justify justify Justify +If there are multiple lines of text, specifies how +the lines are laid out relative to one another. +One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. +See also \fB\-anchor\fR (for widgets supporting this option). .OP \-padding padding Padding Specifies the internal padding for the widget. The padding is a list of up to four length specifications @@ -125,13 +136,31 @@ Specifies the name of a global variable whose value will be used in place of the \fB\-text\fR resource. .OP \-underline underline Underline If set, specifies the integer index (0-based) of a character to underline -in the text string. +in the text string. \fBend\fR corresponds to the last character, +\fBend\fR-1 to the before last character, and so on. The underlined character is used for mnemonic activation. .OP \-width width Width If greater than zero, specifies how much space, in character widths, to allocate for the text label. If less than zero, specifies a minimum width. If zero or unspecified, the natural width of the text label is used. +Note that some themes may specify a non-zero \fB\-width\fR +in the style. +.OP \-wraplength wrapLength WrapLength +Specifies the maximum line length. The value may have any of the forms +acceptable to \fBTk_GetPixels\fR. If this option is less than or equal +to zero, then automatic wrapping is not performed; otherwise +the text is split into lines such that no line is longer +than the specified value. +.SH "ENTRY OPTIONS" +The following options are supported by entry, spinbox and combobox: +.OP \-placeholder placeHolder PlaceHolder +Specifies a help text string to display if no text is otherwise displayed, +that is when the widget is empty. The placeholder text is displayed using +the values of the \fB\-font\fR, \fB\-justify\fR and +\fB\-placeholderforeground\fR options. +.OP \-placeholderforeground placeHolderForeground PlaceHolderForeground +Specifies the foreground color of the placeholder text. .SH "COMPATIBILITY OPTIONS" This option is only available for themed widgets that have .QW corresponding @@ -206,6 +235,11 @@ will restore \fIpathName\fR to the original state. If \fIstateSpec\fR is not specified, returns a list of the currently-enabled state flags. .RE +.\" METHOD: style +.TP +\fIpathName \fBstyle\fR +. +Return the style used by the widget. .\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR @@ -241,15 +275,17 @@ way through the content appears at the left edge of the window. . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. +\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, but we don't document that. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display. .RE .\" METHOD: yview .TP @@ -286,15 +322,17 @@ way through the content appears at the top edge of the window. . This command shifts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. +\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, but we don't document that. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR average-width characters on the display; if it is +If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then items farther to the top become visible; if it is positive then items farther to the bottom become visible. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by +\fInumber\fR average-width characters on the display. .RE .SH "WIDGET STATES" The widget state is a bitmap of independent state flags. @@ -349,7 +387,7 @@ it is used in some themes for widgets that provide distinct visual feedback for the active widget in addition to the active element within the widget. -.IP \fBuser1\fR-\fBuser3\fR +.IP \fBuser1\fR-\fBuser6\fR Freely usable for other purposes .PP A \fIstate specification\fR or \fIstateSpec\fR is a list diff --git a/doc/winfo.n b/doc/winfo.n index fed5c39..5651f2c 100644 --- a/doc/winfo.n +++ b/doc/winfo.n @@ -12,7 +12,7 @@ .SH NAME winfo \- Return window-related information .SH SYNOPSIS -\fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? +\fBwinfo\fR \fIoption \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -12,7 +12,7 @@ .SH NAME wish \- Simple windowing shell .SH SYNOPSIS -\fBwish\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? +\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. @@ -94,7 +94,32 @@ value accepted by \fBTk_GetColor\fR. If the empty string is specified 2000/XP+. Where not supported, the \fB\-transparentcolor\fR value remains at \fB{}\fR. .PP -On Mac OS X, the following attributes may be set. +On MacOS, the following attributes may be set. +.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. +.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. +.TP +\fB\-isdark\fR +. +Returns a boolean value which is true if the window is currently in +dark mode. .TP \fB\-modified\fR . @@ -106,10 +131,49 @@ proxy icon is draggable). . Specifies process notification state (bouncing of the application dock icon). .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. +.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. +.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. +.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). +Specifies the path of the file referenced as the window proxy icon +(which can be dragged and dropped in lieu of the file's finder icon). .TP \fB\-transparent\fR . @@ -407,6 +471,37 @@ specified then the command returns an empty string; otherwise it returns the path name of \fIwindow\fR's current group leader, or an empty string if \fIwindow\fR is not part of any group. .TP +\fBwm iconbadge \fIwindow\fR \fIbadge\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 +.TP \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? . If \fIbitmap\fR is specified, then it names a bitmap in the standard @@ -481,12 +576,13 @@ manager may scale provided icons to an appropriate size. .PP On Windows, the images are packed into a Windows icon structure. This will override an ico specified to \fBwm iconbitmap\fR, and -vice versa. +vice versa. This command sets the taskbar icon for the window. .PP On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. A \fBwm iconbitmap\fR may exist simultaneously. It is recommended to use not more than 2 icons, placing -the larger icon first. +the larger icon first. This command also sets the panel icon for the +application if the window manager or desktop environment supports it. .PP On Macintosh, the first image called is loaded into an OSX-native icon format, and becomes the application icon in dialogs, the Dock, and @@ -775,7 +871,8 @@ However, you can use the \fBwm minsize\fR and \fBwm maxsize\fR commands to limit the range of allowable sizes. The range set by \fBwm minsize\fR and \fBwm maxsize\fR applies to all forms of resizing, including the window's natural size as -well as manual resizes and the \fBwm geometry\fR command. +well as manual resizes and the \fBwm geometry\fR command. You +can use any value accepted by \fBTk_GetPixels\fR. You can also use the command \fBwm resizable\fR to completely disable interactive resizing in one or both dimensions. .PP |