diff options
| author | jan.nijtmans <nijtmans@users.sourceforge.net> | 2025-10-31 19:28:42 (GMT) |
|---|---|---|
| committer | jan.nijtmans <nijtmans@users.sourceforge.net> | 2025-10-31 19:28:42 (GMT) |
| commit | c25f14940d3c7823cae0a783f34c6f147518a1b3 (patch) | |
| tree | d598543193e4ffbb2336840441fd696a854ab6cc /doc | |
| parent | 3d21e16ae679d4c1ae0b73441536c7429a72657d (diff) | |
| parent | 2f48a0563a693aeccaf7550989d0539a3c940d95 (diff) | |
| download | tk-core-tk-print-fixes.zip tk-core-tk-print-fixes.tar.gz tk-core-tk-print-fixes.tar.bz2 | |
Merge trunkcore-tk-print-fixes
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CrtItemType.3 | 8 | ||||
| -rw-r--r-- | doc/CrtPhImgFmt.3 | 16 | ||||
| -rw-r--r-- | doc/SetOptions.3 | 4 | ||||
| -rw-r--r-- | doc/attribtable.n | 154 | ||||
| -rw-r--r-- | doc/canvas.n | 8 | ||||
| -rw-r--r-- | doc/frame.n | 8 | ||||
| -rw-r--r-- | doc/photo.n | 76 | ||||
| -rw-r--r-- | doc/send.n | 5 | ||||
| -rw-r--r-- | doc/text.n | 10 | ||||
| -rw-r--r-- | doc/tk.n | 37 | ||||
| -rw-r--r-- | doc/tk_mac.n | 7 | ||||
| -rw-r--r-- | doc/toplevel.n | 8 | ||||
| -rw-r--r-- | doc/ttk_toggleswitch.n | 268 | ||||
| -rw-r--r-- | doc/ttk_vsapi.n | 4 |
14 files changed, 532 insertions, 81 deletions
diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 index a019972..6615168 100644 --- a/doc/CrtItemType.3 +++ b/doc/CrtItemType.3 @@ -85,9 +85,9 @@ typedef struct Tk_ItemType { Tk_ItemInsertProc *\fIinsertProc\fR; Tk_ItemDCharsProc *\fIdCharsProc\fR; struct Tk_ItemType *\fInextPtr\fR; -.VS "8.7, TIP164" +.VS "9.0, TIP164" Tk_ItemRotateProc *\fIrotateProc\fR; -.VE "8.7, TIP164" +.VE "9.0, TIP164" } \fBTk_ItemType\fR; .CE .PP @@ -539,7 +539,7 @@ 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" +.VS "9.0, TIP164" .PP \fItypePtr\->rotateProc\fR is invoked by Tk to rotate a canvas item during the \fBrotate\fR widget command. @@ -577,7 +577,7 @@ instead be derived from them. 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" +.VE "9.0, 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 6f89ef7..332939c 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -18,17 +18,17 @@ Tk_CreatePhotoImageFormat \- define new file format for photo images .nf \fB#include <tk.h>\fR .sp -.VS 8.7 +.VS 9.0 \fBTk_CreatePhotoImageFormatVersion3\fR(\fIformatVersion3Ptr\fR) -.VE 8.7 +.VE 9.0 .sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SH ARGUMENTS .AS "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr -.VS 8.7 +.VS 9.0 .AP "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr in Structure that defines the new file format including metadata functionality. -.VE 8.7 +.VE 9.0 .AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE @@ -56,7 +56,7 @@ 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 +.VS 9.0 .CS typedef struct { const char *\fIname\fR; @@ -68,7 +68,7 @@ typedef struct { Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR; } \fBTk_PhotoImageFormatVersion3\fR; .CE -.VE 8.7 +.VE 9.0 .PP The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be @@ -91,7 +91,7 @@ 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 +.VS 9.0 .SS FILEMATCHPROC .PP \fIformatPtr->fileMatchProc\fR provides the address of a procedure for @@ -358,7 +358,7 @@ 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 +.VE 9.0 .SH "VERSION 2 INTERFACE" .PP Version 2 Interface does not include the possibility for the driver to diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index d0c6c06..5c4b62f 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -546,7 +546,7 @@ typedef int \fBTk_CustomOptionSetProc\fR( Tk_Window \fItkwin\fR, Tcl_Obj **\fIvaluePtr\fR, char *\fIrecordPtr\fR, - int \fIinternalOffset\fR, + Tcl_Size \fIinternalOffset\fR, char *\fIsaveInternalPtr\fR, int \fIflags\fR); @@ -554,7 +554,7 @@ typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIrecordPtr\fR, - int \fIinternalOffset\fR); + Tcl_Size \fIinternalOffset\fR); typedef void \fBTk_CustomOptionRestoreProc\fR( void *\fIclientData\fR, diff --git a/doc/attribtable.n b/doc/attribtable.n new file mode 100644 index 0000000..02b5e71 --- /dev/null +++ b/doc/attribtable.n @@ -0,0 +1,154 @@ +.\" +.\" Copyright (c) 2025 Csaba Nemethi +.\" +.\" See the file "license.terms" for information on usage and redistribution +.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +.\" +.TH tk attribtable n 9.1 "" Tk "Tk Built-in Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk attribtable \- Create an attribute table, used to query and modify +arbitrary data attached to any widget. +.SH SYNOPSIS +\fBtk attribtable \fItableName\fR +.BE +.SH DESCRIPTION +.PP +This command creates an attribute table of the name \fItableName\fR, +implemented as a hash table and accessible as a command in the namespace of +the calling context if not fully qualified, and returns the fully qualified +name of the command just created. +.PP +An attribute table is used to query and modify arbitrary data attached to any +widget. These data are commonly called \fIattributes\fR. +.PP +If an attribute table of the given name already exists then it is replaced +with the new one and all the attributes of all widgets set using the old table +instance will be unset. +.PP +\fBREMARK 1:\fR When the \fItableName\fR command is deleted (via \fBrename\fR +\fItableName\fR "" or by deleting the containing namespace), all the +attributes of all widgets set using this command are automatically unset and +the underlying hash table is deleted. This will free all the memory used by +the table. +.PP +\fBREMARK 2:\fR When a widget is destroyed, all of its attributes set by all +attribute table commands are automatically unset. This will free all the +memory used by the widget's attributes. +.PP +The command \fItableName\fR created by this command has the signature +.PP +.CS +\fItableName\fR \fBset\fR|\fBget\fR|\fBunset\fR|\fBclear\fR|\fBexists\fR|\fBnames\fR|\fBpathnames\fR \fIargs\fR +.CE +.PP +In the description of the supported forms below, \fIpathName\fR specifies a +widget whose attributes are being queried or modified via the \fItableName\fR +command. +.\" METHOD: set +.TP +\fItableName\fR \fBset\fR \fIpathName name value\fR ?\fIname value\fR ...? +. +Sets (i.e., adds or updates) the attributes identified by the \fIname\fR +arguments to the values given by the \fIvalue\fR arguments. Returns an empty +string. Example: +.RS +.PP +.CS +# Save and then change the button's text +\fBtk attribtable\fR table +table \fBset\fR .btn prevText [.btn cget -text] +\&.btn configure -text "NewText" +.CE +.RE +.\" METHOD: get +.TP +\fItableName\fR \fBget\fR \fIpathName\fR ?\fIname\fR ?\fIdefaultValue\fR?? +. +If \fIname\fR is specified then returns the corresponding attribute value, or +an empty string or \fIdefaultValue\fR (if given) if no corresponding value +exists. Otherwise returns a list consisting of all attribute names and values +of the widget \fIpathName\fR. Example: +.RS +.PP +.CS +# Restore the button's previous text +\&.btn configure -text [table \fBget\fR .btn prevText] +.CE +.RE +.\" METHOD: unset +.TP +\fItableName\fR \fBunset\fR \fIpathName name\fR ?\fIname\fR ...? +. +Unsets the attributes identified by the \fIname\fR arguments. Returns an +empty string. Example: +.RS +.PP +.CS +table \fBunset\fR .btn prevText +.CE +.RE +.\" METHOD: clear +.TP +\fItableName\fR \fBclear\fR \fIpathName\fR +. +Unsets all attributes and removes \fIpathName\fR from the list of those +widgets that have attributes set via \fItableName\fR \fBset\fR. Returns an +empty string. Example: +.RS +.PP +.CS +table \fBclear\fR .btn +.CE +.RE +.\" METHOD: exists +.TP +\fItableName\fR \fBexists\fR \fIpathName\fR ?\fIname\fR? +. +If the optional argument is present then returns \fB1\fR if the attribute +identified by \fIname\fR exists and \fB0\fR otherwise. Without the optional +argument the return value is \fB1\fR if the widget \fIpathName\fR has at +least one attribute set via \fItableName\fR \fBset\fR and \fB0\fR otherwise. +Example: +.RS +.PP +.CS +if [table \fBexists\fR .btn prevText] { + # Restore the button's previous text + \&.btn configure -text [table \fBget\fR .btn prevText] +} +.CE +.RE +.\" METHOD: names +.TP +\fItableName\fR \fBnames\fR \fIpathName\fR +. +Returns a list consisting of all attribute names of the widget +\fIpathName\fR. Example: +.RS +.PP +.CS +puts "attribute names for .btn: [table \fBnames\fR .btn]" +.CE +.RE +.\" METHOD: pathnames +.TP +\fItableName\fR \fBpathnames\fR +. +Returns a list consisting of the path names of all widgets that have +attributes set via \fItableName\fR \fBset\fR. +Example: +.RS +.PP +.CS +puts "widgets in table: [table \fBpathnames\fR]" +.CE +.RE +.SH KEYWORDS +widget, attribute, attribute table +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/canvas.n b/doc/canvas.n index 2942358..986ad2a 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -221,9 +221,9 @@ Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. .PP Individual items may be moved, scaled -.VS "8.7, TIP164" +.VS "9.0, TIP164" or rotated -.VE "8.7, TIP164" +.VE "9.0, TIP164" using widget commands described below. .PP @@ -1016,7 +1016,7 @@ use as a replacement). The other items ignore this operation. .\" METHOD: rotate .TP \fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR -.VS "8.7, TIP164" +.VS "9.0, 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 @@ -1034,7 +1034,7 @@ computed center point instead of moving the bounding box coordinates directly. 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" +.VE "9.0, TIP164" .\" METHOD: scale .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR diff --git a/doc/frame.n b/doc/frame.n index 27d3b5a..e7d7eed 100644 --- a/doc/frame.n +++ b/doc/frame.n @@ -25,7 +25,7 @@ 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" +.VS "9.0, 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 @@ -34,7 +34,7 @@ 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" +.VE "9.0, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for @@ -73,14 +73,14 @@ 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" +.VS "9.0, 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" +.VE "9.0, TIP262" .OP \-visual visual Visual Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. diff --git a/doc/photo.n b/doc/photo.n index 676c70e..f5d3861 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -44,9 +44,9 @@ procedural interface. At present, only PNG, .VE 8.6 GIF, PPM/PGM, -.VS 8.7 +.VS 9.0 and (read-only) SVG -.VE 8.7 +.VE 9.0 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 @@ -63,10 +63,10 @@ Photos support the following \fIoptions\fR: \fB\-data \fIstring\fR . Specifies the contents of the image as a string. -.VS 8.7 +.VS 9.0 The string should contain data in the default list-of-lists form, -.VE 8.7 +.VE 9.0 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 @@ -110,7 +110,7 @@ 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 +.VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata \fImetadata\fR @@ -120,7 +120,7 @@ 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 +.VE 9.0 .\" OPTION: -palette .TP \fB\-palette \fIpalette-spec\fR @@ -195,10 +195,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 +.VS 9.0 Note that setting the \fB\-metadata\fR option without any other option will not invoke the image format driver to recreate the bitmap. -.VE 8.7 +.VE 9.0 .\" METHOD: copy .TP \fIimageName \fBcopy\fI sourceImage\fR ?\fIoption value(s) ...\fR? @@ -278,12 +278,12 @@ the source image is used as-is. The default compositing rule is \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? . Returns image data in the form of a string. -.VS 8.7 +.VS 9.0 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 +.VE 9.0 The following options may be specified: .RS .\" OPTION: -background @@ -302,13 +302,13 @@ 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 +.VS 9.0 If this option is not given, this subcommand uses the default format that consists of a list (one element per row) of lists (one element per pixel/column) of colors in .QW \fB#\fIrrggbb\fR format (see \fBIMAGE FORMATS\fR below). -.VE 8.7 +.VE 9.0 Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. @@ -329,7 +329,7 @@ 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 +.VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR @@ -340,7 +340,7 @@ 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 +.VE 9.0 .RE .\" METHOD: get .TP @@ -357,12 +357,12 @@ representing the alpha value of the pixel as an integer between 0 and \fIimageName \fBput\fI data\fR ?\fIoption value(s) ...\fR? . Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. -.VS 8.7 +.VS 9.0 This command searches the list of image file format handlers for a handler that can interpret the data in \fIdata\fR, and then reads the image encoded within into \fIimageName\fR (the destination image). See \fBIMAGE FORMATS\fR below for details on formats for image data. -.VE 8.7 +.VE 9.0 The following options may be specified: .RS .\" OPTION: -format @@ -377,7 +377,7 @@ format handler to read the data. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. -.VS 8.7 +.VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR @@ -386,7 +386,7 @@ A specified \fImetadata\fR is passed to the image format driver when interpretin the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. -.VE 8.7 +.VE 9.0 .\" OPTION: -to .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? @@ -436,7 +436,7 @@ 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 +.VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR @@ -445,7 +445,7 @@ A specified \fImetadata\fR is passed to the image format driver when interpretin the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. -.VE 8.7 +.VE 9.0 .\" OPTION: -shrink .TP \fB\-shrink\fR @@ -484,21 +484,21 @@ the photo image. Several subcommands are available: .RS .TP \fIimageName \fBtransparency get \fIx y\fR ?\fB\-alpha\fR? -.VS 8.7 +.VS 9.0 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 +.VE 9.0 .TP \fIimageName \fBtransparency set \fIx y newVal\fR ?\fB\-alpha\fR? -.VS 8.7 +.VS 9.0 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 +.VE 9.0 .RE .\" METHOD: write .TP @@ -545,7 +545,7 @@ 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 +.VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR @@ -555,7 +555,7 @@ 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 +.VE 9.0 .RE .SH "IMAGE FORMATS" .PP @@ -565,10 +565,10 @@ a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The standard Tk distribution comes with handlers for PPM/PGM, PNG, GIF and (read-only) SVG formats, -.VS 8.7 +.VS 9.0 as well as the \fBdefault\fR handler to encode/decode image data in a human readable form. -.VE 8.7 +.VE 9.0 These handlers are automatically registered on initialization. .PP When reading an image file or processing string data specified with @@ -592,7 +592,7 @@ 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 +.VS 9.0 .SS "THE DEFAULT IMAGE HANDLER" .PP The \fBdefault\fR image handler cannot be used to read or write data @@ -608,7 +608,7 @@ 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 +.VE 9.0 .SS "FORMAT SUBOPTIONS" .PP @@ -620,7 +620,7 @@ string. The nature and values of these options is up to the format handler. The built-in handlers support these suboptions: .\" OPTION -colorformat -.VS 8.7 +.VS 9.0 .TP \fBdefault \-colorformat\fI formatType\fR . @@ -631,7 +631,7 @@ 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 +.VE 9.0 .\" OPTION -index .TP \fBgif \-index\fI indexValue\fR @@ -732,7 +732,7 @@ format) photos is supported: Tk does not (yet) support bundling photo images in SVG vector graphics. .RE .VE 8.6 -.VS 8.7 +.VS 9.0 .SH "COLOR FORMATS" .PP The default image handler can represent/parse color and alpha values @@ -778,7 +778,7 @@ channels respectively. Each digit will be expanded internally to \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 +.VE 9.0 .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code @@ -808,7 +808,7 @@ 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 +.VS 9.0 .SH "METADATA DICTIONARY" .PP Each image has a metadata dictionary property. @@ -861,7 +861,7 @@ Otherwise, the key is not present. 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 +.VE 9.0 .SH CREDITS .PP The photo image type was designed and implemented by Paul Mackerras, @@ -897,7 +897,7 @@ button .b -image icon -disabledimage iconDisabled .CE .VE 8.6 .PP -.VS 8.7 +.VS 9.0 Create a green box with a simple shadow effect .PP .CS @@ -911,7 +911,7 @@ for {set i 14} {$i > 0} {incr i -1} { # Put a solid green rectangle on top foo \fBput\fR #F080 -to 0 0 30 30 -.VE 8.7 +.VE 9.0 .CE .SH "SEE ALSO" image(n) @@ -90,6 +90,11 @@ they use some other form of authorization such as that provide by \fBxauth\fR. Under Windows, \fBsend\fR is currently disabled. Most of the functionality is provided by the \fBdde\fR command instead. +.SH LIMITATIONS +.PP +Under macOS/aqua, the send command works only with interpreters that exist in +the same process (these are returned by "winfo interps"). Invocations that +target an interpreter that exists in another process don't accomplish anything. .SH EXAMPLE .PP This script fragment can be used to make an application that only runs @@ -35,7 +35,8 @@ the undo stack. Only meaningful when the \fB\-undo\fR option is true. .OP \-blockcursor blockCursor BlockCursor Specifies a boolean that says whether the blinking insertion cursor should be drawn as a character-sized rectangular block. If false (the default) a thin -vertical line is used for the insertion cursor. +vertical line is used for the insertion cursor. For further discussion +refer to section \fBTHE INSERTION CURSOR\fR below. .OP \-endline endLine EndLine Specifies an integer line index representing the line of the underlying textual data store that should be just after the last line contained in @@ -917,6 +918,13 @@ with the widget command. The \fBinsert\fR mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the text widget has the input focus. +.PP +The \fB\-blockcursor\fR widget option controls the drawing of the cursor. +However, drawing the cursor as a solid blinking block is not exactly +performed as in real or emulated terminals. The character at the cursor +position is always drawn in it's foreground color, i.e. not in +"reverse video", which can lead to unwanted visual effects and even +hide the character entirely, when the cursor is in its on-state. .SH "THE MODIFIED FLAG" .PP The text widget can keep track of changes to the content of the widget by @@ -45,13 +45,21 @@ be able to find some options for the application. If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. +.\" METHOD: attribtable +.TP +\fBtk attribtable \fItableName\fR +. +This command creates an attribute table of the name \fItableName\fR as a +command in the namespace of the calling context if not fully qualified. An +attribute table is used to query and modify arbitrary data attached to any +widget. For more details see the \fBattribtable\fR manual page. .\" METHOD: busy .TP \fBtk busy \fIsubcommand\fR ... . This command controls the marking of window hierarchies as .QW busy , -rendering them non-interactive while some other operation is proceeding. For +rendering them non-interactive while some other operation is proceeding. For more details see the \fBbusy\fR manual page. .\" METHOD: caret .TP @@ -71,7 +79,7 @@ of the specified \fIwindow\fR if none is given. \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? . Returns a positive integer, the number of milliseconds since the last -time the user interacted with the system. If the \fB\-displayof\fR +time the user interacted with the system. If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. @@ -81,7 +89,7 @@ main window. is not supported by the system, and in safe interpreters. .PP If the literal string \fBreset\fR is given as an additional argument, -the timer is reset and an empty string is returned. Resetting the +the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. .RE @@ -89,15 +97,15 @@ error if tried. .TP \fBtk fontchooser \fIsubcommand\fR ... . -Controls the Tk font selection dialog. For more details see the +Controls the Tk font selection dialog. For more details see the \fBfontchooser\fR manual page. .\" METHOD: print .TP \fBtk print \fIwindow\fR . The \fBtk print\fR command posts a dialog that allows users to print output -from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using -platform-native APIs and dialogs where available. For more details see the +from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using +platform-native APIs and dialogs where available. For more details see the \fBprint\fR manual page. .\" METHOD: scaling .TP @@ -127,25 +135,25 @@ accommodate the new scaling factor. .RE .\" METHOD: sysnotify .TP -\fBtk sysnotify \fP \fItitle\fP? \fImessage\fP? +\fBtk sysnotify \fItitle message\fR . The \fBtk sysnotify\fP command creates a platform-specific system -notification alert. Its intent is to provide a brief, unobtrusive +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. +corner of the screen. For more details see the \fBsysnotify\fR manual page. .\" METHOD: systray .TP -\fBtk systray create\fP \fIsubcommand...\fP +\fBtk systray \fIsubcommand\fR ... . The \fBtk systray\fP command creates an icon in the platform-specific -tray. For more details see the \fBsystray\fR manual page. +tray. For more details see the \fBsystray\fR manual page. .\" METHOD: useinputmethods .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in -some locales (i.e., Japanese, Korean), to handle special input devices. This +some locales (i.e., Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current @@ -158,9 +166,10 @@ Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (macOS Aqua). .SH "SEE ALSO" -busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n) +attribtable(n), busy(n), fontchooser(n), print(n), send(n), sysnotify(n), +systray(n), winfo(n) .SH KEYWORDS -application name, print, send, sysnotify, systray +application name, attribute, print, send, sysnotify, systray '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/tk_mac.n b/doc/tk_mac.n index 7af9606..15b1134 100644 --- a/doc/tk_mac.n +++ b/doc/tk_mac.n @@ -27,6 +27,7 @@ tk::mac \- Access Mac-Specific Functionality on macOS from Tk \fB::tk::mac::PerformService\fR \fB::tk::mac::LaunchURL \fIURL...\fR \fB::tk::mac::GetAppPath\fR +\fB::tk::mac::GetInfoAsJSON\fR \fB::tk::mac::standardAboutPanel\fR @@ -36,6 +37,7 @@ tk::mac \- Access Mac-Specific Functionality on macOS from Tk \fB::tk::mac::useThemedToplevel \fIboolean\fR \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR + .fi .BE .SH "EVENT HANDLER CALLBACKS" @@ -220,6 +222,11 @@ customized for the specific URL scheme the developer wants to support. \fB::tk::mac::GetAppPath\fR . Returns the current applications's file path. +.TP +\fB::tk::mac::GetInfoAsJSON\fR +. +Returns a JSON-encoded Tcl string which serializes the application's +\fBmainBundle.infoDictionary\fR (defined by its \fIInfo.plist\fR file). .PP .SH "ADDITIONAL DIALOGS" .PP diff --git a/doc/toplevel.n b/doc/toplevel.n index 701d383..2fee87c 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -25,7 +25,7 @@ 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" +.VS "9.0, 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 @@ -35,7 +35,7 @@ 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" +.VE "9.0, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for @@ -85,14 +85,14 @@ 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" +.VS "9.0, 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" +.VE "9.0, 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 diff --git a/doc/ttk_toggleswitch.n b/doc/ttk_toggleswitch.n new file mode 100644 index 0000000..49914ac --- /dev/null +++ b/doc/ttk_toggleswitch.n @@ -0,0 +1,268 @@ +.\" +.\" Copyright (c) 2025 Csaba Nemethi +.\" +.\" See the file "license.terms" for information on usage and redistribution +.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +.\" +.TH ttk::toggleswitch n 9.1 Tk "Tk Themed Widget" +.so man.macros +.BS +.SH NAME +ttk::toggleswitch \- Create and manipulate a toggleswitch widget +.SH SYNOPSIS +\fBttk::toggleswitch \fIpathName \fR?\fIoptions...\fR? +.BE +.SH DESCRIPTION +.PP +A \fBttk::toggleswitch\fR widget is used to show or change a binary setting. +It consists of a horizontal \fItrough\fR (a fully rounded filled rectangle) +and a \fIslider\fR (a filled circle contained in the trough). Their +dimensions depend on the display's scaling level, the current theme, and the +value of the \fB-size\fR configuration option. +.PP +Just like a light switch, a toggleswitch widget can have one of two possible +\fIswitch state\fRs: on or off. In the on state the slider is placed at the +end of the trough, and in the off state at its beginning. The user can toggle +between these two states with the mouse or the space key. +.PP +The colors used when drawing the trough and slider in the various widget +states depend on the current theme. If the theme is \fBaqua\fR then they also +depend on the system appearance (light mode or dark mode) and the accent +color, and are automatically adapted whenever one of these global system +settings changes. +.PP +The implementation creates these elements when needed with the aid of generic +code for arbitrary themes and theme-specific one for a few built-in themes. +Applications can add \fIexplicit\fR support for any theme \fItheme\fR by +providing an appropriate command of the name +\fBttk::toggleswitch::CreateElements_\fR\fItheme\fR. +.SO ttk_widget +\-class \-cursor \-style +\-takefocus +.SE +.PP +The default value of the \fB-class\fR option is \fBToggleswitch\fR. The value +of the \fB-style\fR option defaults to \fBToggleswitch2\fR, corresponding to +the \fB-size\fR option's default value \fB2\fR (see below). +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +Specifies a Tcl script to be evaluated at global scope whenever the switch +state of the widget is toggled (programmatically, by invoking the +\fBswitchstate\fR or \fBtoggle\fR subcommand, or interactively). The default +is an empty string. +.OP \-offvalue offValue OffValue +The value to store in the associated \fB\-variable\fR +when the widget's switch state is set to off. Defaults to \fB0\fR. +.OP \-onvalue onValue OnValue +The value to store in the associated \fB\-variable\fR +when the widget's switch state is set to on. Defaults to \fB1\fR. +.OP \-size size Size +Specifies the size identifier of the toggleswitch widget. The supported +values are the strings \fB1\fR, \fB2\fR (the default), and \fB3\fR. In the +case of the \fBaqua\fR theme, these size IDs correspond to the control sizes +"mini", "small", and "large" of the native toggle switches on macOS. +.RS +.PP +Note that by setting this option to a value \fIsize\fR, the \fB-style\fR +option's value will automatically change to \fBToggleswitch\fR\fIsize\fR if +its previous or requested value was \fBToggleswitch1\fR, \fBToggleswitch2\fR, +or \fBToggleswitch3\fR, and to \fIprefix\fR.\fBToggleswitch\fR\fIsize\fR if +its previous or requested value was \fIprefix\fR.\fBToggleswitch1\fR, +\fIprefix\fR.\fBToggleswitch2\fR, or \fIprefix\fR.\fBToggleswitch3\fR. +Conversely, by setting the \fB-style\fR option to a value of the form +\fBToggleswitch\fR\fIsize\fR or \fIprefix\fR.\fBToggleswitch\fR\fIsize\fR +(where \fIsize\fR is one of \fB1\fR, \fB2\fR, or \fB3\fR), the \fB-size\fR +option will automatically be set to \fIsize\fR. When configuring both options +\fB-size\fR and \fB-style\fR, the former will take precedence over the latter, +regardless of the order in which they were specified. +.PP +For example, if you create the widget with +.PP +.CS +\fBttk::toggleswitch\fR \fIpathName\fR \fB-size 3 -style\fR My.\fBToggleswitch3\fR +.CE +.PP +or invoke +.PP +.CS +\fIpathName\fR \fBconfigure -style\fR My.\fBToggleswitch3\fR +.CE +.PP +then the \fB-style\fR option will be set to My.\fBToggleswitch3\fR (and the +\fB-size\fR option will have the value \fB3\fR). On the other hand, if you +create the widget with +.PP +.CS +\fBttk::toggleswitch\fR \fIpathName\fR \fB-style\fR My.\fBToggleswitch3\fR +.CE +.PP +then the \fB-style\fR option will have the value My.\fBToggleswitch2\fR rather +than My.\fBToggleswitch3\fR, because the widget creation triggers the default +\fB-size 2\fR setting, which takes precedence over \fB-style\fR +My.\fBToggleswitch3\fR. +.RE +.OP \-variable variable Variable +The name of a global variable whose value is linked to the toggleswitch. The +widget's switch state changes to on when this variable is set to the value +specified by the \fB-onvalue\fR option and to off otherwise. Defaults to the +widget's pathname if not specified. +.RS +.PP +Note that, just like in the case of the (ttk::)checkbutton, toggling the +widget's switch state by changing the value of this variable will \fInot\fR +cause the script specified by the \fB-command\fR option to get executed. +.RE +.SH "WIDGET COMMAND" +.PP +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, +\fBstate\fR, and \fBstyle\fR commands (see \fBttk::widget\fR), toggleswitch +widgets support the following additional commands: +.\" METHOD: switchstate +.TP +\fIpathName \fBswitchstate \fR?\fIboolean\fR? +. +Modifies or inquires the widget's switch state. If the optional argument is +present then it must be a boolean (a numeric value, where 0 is false and +anything else is true, or a string such as \fBtrue\fR/\fByes\fR/\fBon\fR or +\fBfalse\fR/\fBno\fR/\fBoff\fR). If the widget's \fBdisabled\fR state flag is +set then the command returns an empty string immediately after checking the +argument. Otherwise, if the argument is true then the command sets the +widget's switch state to on by setting its \fBselected\fR flag, moving the +slider to the end of the trough, and setting the associated \fB-variable\fR to +the value specified by the \fB-onvalue\fR option; if the argument is false +then the command sets the widget's switch state to off by clearing the +\fBselected\fR flag, moving the slider to the beginning of the trough, and +setting the associated variable to the value specified by the \fB-offvalue\fR +option. +.RS +.PP +If the argument's value causes the widget's switch state to get toggled and +the script specified as the value of the \fB-command\fR option is a nonempty +string then the command evaluates that script at global scope and returns its +result; otherwise the return value is an empty string. +.PP +If the optional argument is not present then the command returns the widget's +current switch state as \fB0\fR (off) or \fB1\fR (on). When a toggleswitch +widget is created, its switch state is initialized with \fB0\fR. +.RE +.\" METHOD: toggle +.TP +\fIpathName \fBtoggle\fR +. +This convenience subcommand toggles the widget's switch state. It is +logically equivalent to invoking the \fBswitchstate\fR command with the +argument \fB0\fR if the current switch state is on and with the argument +\fB1\fR otherwise. +.SH "INTERNAL COMMANDS" +.PP +The following widget commands are used internally by the \fBToggleswitch\fR +widget class bindings. They provide a means to access the widget's internal +value, which is a real number within a certain invariant interval. +.\" METHOD: get +.TP +\fIpathName \fBget \fR?\fBmin\fR|\fBmax\fR|\fIx\fR? +. +Returns the current/minimum/maximum internal value, or the one corresponding +to the coordinate \fIx\fR relative to the widget origin if it is specified. +.\" METHOD: set +.TP +\fIpathName \fBset \fIvalue\fR +. +Sets the widget's internal value to \fIvalue\fR. The value will be clipped to +the range given by the minimum and maximum values, as returned by +\fBget min\fR and \fBget max\fR. +.PP +.\" METHOD: xcoord +.TP +\fIpathName \fBxcoord \fR?\fIvalue\fR? +. +Returns the x coordinate corresponding to \fIvalue\fR, or to the current +internal value if \fIvalue\fR is omitted. +.SH "DEFAULT BINDINGS" +.PP +The toggleswitch widget's default bindings enable the following behavior. +.PP +If the current theme is \fBaqua\fR: +.IP \0\(bu 4 +By pressing mouse button 1 over the slider and then dragging the mouse with +button 1 down until the pointer enters the trough, the slider moves smoothly +to the opposite edge of the trough and the widget's switch state gets +toggled. The same happens if mouse button 1 is pressed outside the slider and +then the pointer leaves the widget horizontally with button 1 down. +.IP \0\(bu 4 +By pressing mouse button 1 anywhere within the widget and then releasing it +over the widget without previously moving the slider, the latter moves +smoothly to the opposite edge of the trough and the widget's switch state gets +toggled. +.IP \0\(bu 4 +When the widget has the input focus, the space key causes its switch state to +get toggled. +.PP +If the current theme is different from \fBaqua\fR: +.IP \0\(bu 4 +By pressing mouse button 1 anywhere within the widget and then dragging the +mouse with button 1 down, the slider moves in the same (horizontal) direction +as the pointer. By releasing the button, the switch state is set to off or +on, depending on the slider's position relative to the middle of the widget. +.IP \0\(bu 4 +By pressing mouse button 1 anywhere within the widget and then releasing it +over the widget without previously dragging the mouse horizontally, the +widget's switch state gets toggled. +.IP \0\(bu 4 +When the widget has the input focus, the space key causes its switch state to +get toggled. +.PP +If the widget's \fBdisabled\fR state flag is set then none of the above +actions occur. +.SH "WIDGET STATES" +.PP +The widget sets the \fBselected\fR state whenever the switch state changes to +on and clears it otherwise. The widget sets the \fBinvalid\fR state whenever +the linked \fB\-variable\fR is unset. The defalt bindings set and clear the +\fBactive\fR and \fBpressed\fR state flags. +.SH "STYLING OPTIONS" +.PP +The default class name for a \fBttk::toggleswitch\fP is \fBToggleswitch\fP. +.PP +Dynamic states: \fBactive\fP, \fBbackground\fP, \fBdisabled\fP, \fBinvalid\fP, +\fBpressed\fP, \fBselected\fP. +.PP +\fBToggleswitch1\fP, \fBToggleswitch2\fP, and \fBToggleswitch3\fP styling +options configurable with \fBttk::style\fP are: +.PP +\fB\-focuscolor\fP \fIcolor\fP +.RS +The default is theme-specific. +.RE +.br +\fB\-focussolid\fP \fIboolean\fP +.RS +Defaults to true for the \fBclassic\fP theme and false for all the others. +.RE +.br +\fB\-focusthickness\fP \fIamount\fP +.RS +The default is 1. The value may have any of the forms acceptable to +\fBTk_GetPixels\fP. +.RE +.br +\fB\-padding\fP \fIpadding\fP +.RS +Defaults to 1.5p for the \fBaqua\fP theme (for which the three above-mentioned +styles have no \fBfocus\fP element) and 0.75p for all the other themes. +.RE +.PP +For the \fBaqua\fP theme only the \fB\-padding\fP option is available, the +others are simply ignored. +.PP +See the \fBttk_style\fP manual page for information on how to configure ttk +styles. +.SH "SEE ALSO" +ttk::widget(n), ttk::style(n), ttk::checkbutton(n), checkbutton(n). +.SH KEYWORDS +toggleswitch, trough, slider, widget +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index 4b7e3cc..1e0b8fa 100644 --- a/doc/ttk_vsapi.n +++ b/doc/ttk_vsapi.n @@ -16,8 +16,8 @@ ttk_vsapi \- Define a Microsoft Visual Styles element .PP The \fBvsapi\fR element factory creates a new element in the current theme whose visual appearance is drawn using the -Microsoft Visual Styles API which is responsible for the themed styles -on Windows XP and Vista. This factory permits any of the Visual +Microsoft Visual Styles API which is used in ttk for the MS-Windows +native styles. 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 |
