diff options
| author | dkf <donal.k.fellows@manchester.ac.uk> | 2024-01-21 00:00:49 (GMT) |
|---|---|---|
| committer | dkf <donal.k.fellows@manchester.ac.uk> | 2024-01-21 00:00:49 (GMT) |
| commit | 81ac88e72f468bd35eb1eb30d6947b6feb0af48d (patch) | |
| tree | 6459c6811aa54d681c9a14888949e59a5a1e735d /doc | |
| parent | 668c3b43a9c64988d3d62ba2b75798dae2d0ed46 (diff) | |
| download | tk-81ac88e72f468bd35eb1eb30d6947b6feb0af48d.zip tk-81ac88e72f468bd35eb1eb30d6947b6feb0af48d.tar.gz tk-81ac88e72f468bd35eb1eb30d6947b6feb0af48d.tar.bz2 | |
Many small tweaks to docs
The main one is I've added a comment in to make primary subcommands ("methods") more obvious when editing.
Diffstat (limited to 'doc')
72 files changed, 1088 insertions, 309 deletions
@@ -649,9 +649,9 @@ then that script terminates and no other scripts will be invoked for the event. .PP Within a script called from the binding script, \fBreturn\fR -\fB-code ok\fR may be used to continue processing (including +\fB\-code ok\fR may be used to continue processing (including .QW + -appended scripts), or \fBreturn\fR \fB-code break\fR may be used to +appended scripts), or \fBreturn\fR \fB\-code break\fR may be used to stop processing all other binding scripts. .PP If more than one binding matches a particular event and they diff --git a/doc/bitmap.n b/doc/bitmap.n index 19716e1..8afcdfd 100644 --- a/doc/bitmap.n +++ b/doc/bitmap.n @@ -15,7 +15,7 @@ bitmap \- Images that display two colors .nf \fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? -\fIimageName \fBcget\fR \fIoption\fR +\fIimageName \fBcget\fI option\fR \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? .fi .BE @@ -95,13 +95,15 @@ It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for bitmap images: +.\" METHOD: cget .TP -\fIimageName \fBcget\fR \fIoption\fR +\fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBbitmap\fR command. +.\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -30,15 +30,15 @@ .SH NAME busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS -\fBtk busy\fR \fIwindow \fR?\fIoptions\fR? +\fBtk busy\fI window \fR?\fIoptions\fR? .sp \fBtk busy busywindow \fIwindow\fR .sp -\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR? +\fBtk busy hold\fI window \fR?\fIoptions\fR? .sp \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... .sp -\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?... +\fBtk busy forget\fI window \fR?\fIwindow \fR?... .sp \fBtk busy current\fR ?\fIpattern\fR? .sp @@ -129,20 +129,23 @@ The following operations are available for the \fBtk busy\fR command: \fBtk busy \fIwindow\fR ?\fIoption value\fR?... . Shortcut for \fBtk busy hold\fR command. +.\" METHOD: busywindow .TP \fBtk busy busywindow \fIwindow\fR . Returns the pathname of the busy window (i.e. the transparent window shielding the window appearing busy) created by the \fBtk busy hold\fR command for \fIwindow\fR, or the empty string if \fIwindow\fR is not busy. +.\" METHOD: cget .TP -\fBtk busy cget \fIwindow\fR \fIoption\fR +\fBtk busy cget \fIwindow option\fR . Queries the \fBtk busy\fR command configuration options for \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made busy by the \fBhold\fR operation. The command returns the present value of the specified \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBhold\fR operation. +.\" METHOD: configure .TP \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... . @@ -169,12 +172,14 @@ option add *frame.busyCursor gumby option add *Frame.BusyCursor gumby .CE .RE +.\" METHOD: current .TP \fBtk busy current \fR?\fIpattern\fR? . Returns the pathnames of all widgets that are currently busy. If a \fIpattern\fR is given, only the path names of busy widgets matching \fIpattern\fR are returned. +.\" METHOD: forget .TP \fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... . @@ -183,6 +188,7 @@ including the transparent window. User events will again be received by \fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. \fIWindow\fR must be the name of a widget specified in the \fBhold\fR operation, otherwise an error is reported. +.\" METHOD: hold .TP \fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... . @@ -204,6 +210,7 @@ Specifies the cursor to be displayed when the widget is made busy. \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. .RE +.\" METHOD: status .TP \fBtk busy status \fIwindow\fR . diff --git a/doc/button.n b/doc/button.n index 70e0e65..79cf14e 100644 --- a/doc/button.n +++ b/doc/button.n @@ -12,7 +12,7 @@ .SH NAME button \- Create and manipulate 'button' action widgets .SH SYNOPSIS -\fBbutton\fR \fIpathName \fR?\fIoptions\fR? +\fBbutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-font \-relief \-activeforeground \-foreground \-repeatdelay @@ -114,14 +114,18 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for button widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -134,15 +138,19 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. +.\" METHOD: flash .TP \fIpathName \fBflash\fR +. Flash the button. This is accomplished by redisplaying the button several times, alternating between the configured activebackground and background colors. At the end of the flash the button is left in the same normal/active state as when the command was invoked. This command is ignored if the button's state is \fBdisabled\fR. +.\" METHOD: invoke .TP \fIpathName \fBinvoke\fR +. Invoke the Tcl command associated with the button, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the button. diff --git a/doc/canvas.n b/doc/canvas.n index cda7706..52f27d6 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -13,7 +13,7 @@ .SH NAME canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets .SH SYNOPSIS -\fBcanvas\fR \fIpathName \fR?\fIoptions\fR? +\fBcanvas\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-highlightbackground \-highlightcolor \-highlightthickness @@ -353,6 +353,7 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following widget commands are possible for canvas widgets: +.\" METHOD: addtag .TP \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR? . @@ -406,14 +407,14 @@ select the topmost closest item that is below \fIstart\fR in the display list; if no such item exists, then the selection behaves as if the \fIstart\fR argument had not been specified. .TP -\fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +\fBenclosed\fI x1 y1 x2 y2\fR . Selects all the items completely enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP -\fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +\fBoverlapping\fI x1 y1 x2 y2\fR . Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, @@ -425,6 +426,7 @@ no greater than \fIy2\fR. . Selects all the items given by \fItagOrId\fR. .RE +.\" METHOD: bbox .TP \fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? . @@ -442,6 +444,7 @@ If no items match any of the \fItagOrId\fR arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. +.\" METHOD: bind .TP \fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? . @@ -503,6 +506,7 @@ the canvas's items using the \fBbind\fR widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. .RE +.\" METHOD: canvasx .TP \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? . @@ -510,6 +514,7 @@ Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns the canvas x-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. +.\" METHOD: canvasy .TP \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? . @@ -517,13 +522,15 @@ Given a window y-coordinate in the canvas \fIscreeny\fR this command returns the canvas y-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . @@ -539,10 +546,11 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. +.\" METHOD: coords .TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? +\fIpathName \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? .TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIcoordList\fR? +\fIpathName \fBcoords \fItagOrId \fR?\fIcoordList\fR? . Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list @@ -561,6 +569,7 @@ returned in screen units with no units (that is, in pixels). So if the original coordinates were specified for instance in centimeters or inches, the returned values will nevertheless be in pixels. .RE +.\" METHOD: create .TP \fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? .TP @@ -574,6 +583,7 @@ more item options. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. +.\" METHOD: dchars .TP \fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? . @@ -586,11 +596,13 @@ line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in \fBINDICES\fR above. If \fIlast\fR is omitted, it defaults to \fIfirst\fR. This command returns an empty string. +.\" METHOD: delete .TP \fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? . Delete each of the items given by each \fItagOrId\fR, and return an empty string. +.\" METHOD: dtag .TP \fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? . @@ -601,6 +613,7 @@ If an item does not have the tag \fItagToDelete\fR then the item is unaffected by the command. If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. This command returns an empty string. +.\" METHOD: find .TP \fIpathName \fBfind \fIsearchCommand \fR?\fIarg ...\fR? . @@ -610,6 +623,7 @@ meet the constraints specified by \fIsearchCommand\fR and \fISearchCommand\fR and \fIargs\fR have any of the forms accepted by the \fBaddtag\fR command. The items are returned in stacking order, with the lowest item first. +.\" METHOD: focus .TP \fIpathName \fBfocus \fR?\fItagOrId\fR? . @@ -639,8 +653,9 @@ In most cases it is advisable to follow the \fBfocus\fR widget command with the \fBfocus\fR command to set the focus window to the canvas (if it was not there already). .RE +.\" METHOD: gettags .TP -\fIpathName \fBgettags\fR \fItagOrId\fR +\fIpathName \fBgettags\fI tagOrId\fR . Return a list whose elements are the tags associated with the item given by \fItagOrId\fR. @@ -648,6 +663,7 @@ If \fItagOrId\fR refers to more than one item, then the tags are returned from the first such item in the display list. If \fItagOrId\fR does not refer to any items, or if the item contains no tags, then an empty string is returned. +.\" METHOD: icursor .TP \fIpathName \fBicursor \fItagOrId index\fR . @@ -662,10 +678,11 @@ that item currently has the keyboard focus (see the \fBfocus\fR widget command, above), but the cursor position may be set even when the item does not have the focus. This command returns an empty string. +.\" METHOD: image .TP \fIpathName \fBimage \fIimagename\fR ?\fIsubsample\fR? ?\fIzoom\fR? . -Draw the canvas into the Tk photo image named \fIimagename\fR. If a \fB-scrollregion\fR +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 @@ -676,6 +693,7 @@ will be filled with the canvas background colour. The canvas widget does not nee 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. +.\" METHOD: imove .TP \fIpathName \fBimove \fItagOrId index x y\fR . @@ -684,6 +702,7 @@ indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). Each item interprets \fIindex\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. +.\" METHOD: index .TP \fIpathName \fBindex \fItagOrId index\fR . @@ -698,6 +717,7 @@ of characters, or coordinates, within the item, inclusive. If \fItagOrId\fR refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order). +.\" METHOD: insert .TP \fIpathName \fBinsert \fItagOrId beforeThis string\fR . @@ -711,8 +731,9 @@ sequence. See \fBINDICES\fR above for information about the forms allowed for \fIbeforeThis\fR. This command returns an empty string. +.\" METHOD: itemcget .TP -\fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR +\fIpathName \fBitemcget\fI tagOrId option\fR . Returns the current value of the configuration option for the item given by \fItagOrId\fR whose name is \fIoption\fR. @@ -722,6 +743,7 @@ it applies to a particular item rather than the widget as a whole. widget command when the item was created. If \fItagOrId\fR is a tag that refers to more than one item, the first (lowest) such item is used. +.\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . @@ -744,6 +766,7 @@ The \fIoption\fRs and \fIvalue\fRs are the same as those permissible in the \fBcreate\fR widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. +.\" METHOD: lower .TP \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? . @@ -759,6 +782,7 @@ obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. This command returns an empty string. +.\" METHOD: move .TP \fIpathName \fBmove \fItagOrId xAmount yAmount\fR . @@ -767,6 +791,7 @@ space by adding \fIxAmount\fR to the x-coordinate of each point associated with the item and \fIyAmount\fR to the y-coordinate of each point associated with the item. This command returns an empty string. +.\" METHOD: moveto .TP \fIpathName \fBmoveto \fItagOrId xPos yPos\fR . @@ -779,6 +804,7 @@ the empty string, in which case the corresponding coordinate will be unchanged. All items matching \fItagOrId\fR remain in the same positions relative to each other. This command returns an empty string. +.\" METHOD: postscript .TP \fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? . @@ -944,6 +970,7 @@ canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. .RE +.\" METHOD: raise .TP \fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? . @@ -962,6 +989,7 @@ obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. .RE +.\" METHOD: rchars .TP \fIpathName \fBrchars \fItagOrId first last string\fR . @@ -973,6 +1001,7 @@ set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case \fIstring\fR should be a list of coordinates to use as a replacement). The other items ignore this operation. +.\" METHOD: rotate .TP \fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR .VS "8.7, TIP164" @@ -994,6 +1023,7 @@ Some items (currently \fBarc\fR and\fB text\fR) have angles in their options; this command \fIdoes not\fR affect those options. .RE .VE "8.7, TIP164" +.\" METHOD: scale .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR . @@ -1015,8 +1045,9 @@ Note that some items have only a single pair of coordinates (e.g., text, images and windows) and so scaling of them by this command can only move them around. .RE +.\" METHOD: scan .TP -\fIpathName \fBscan\fR \fIoption args\fR +\fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on canvases. It has two forms, depending on \fIoption\fR: @@ -1042,6 +1073,7 @@ with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. .RE +.\" METHOD: select .TP \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? . @@ -1108,6 +1140,7 @@ If the selection anchor point for the widget is not currently in by \fIindex\fR. Returns an empty string. .RE +.\" METHOD: type .TP \fIpathName \fBtype\fI tagOrId\fR . @@ -1117,6 +1150,7 @@ If \fItagOrId\fR refers to more than one item, then the type of the first item in the display list is returned. If \fItagOrId\fR does not refer to any items at all then an empty string is returned. +.\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR? . @@ -1160,6 +1194,7 @@ If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units of the \fBxScrollIncrement\fR option, if it is greater than zero, or in units of one-tenth the window's width otherwise. .RE +.\" METHOD: yview .TP \fIpathName \fByview ?\fIargs\fR? . @@ -1420,7 +1455,7 @@ from the 3-o'clock position; it may be either positive or negative. 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. +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 diff --git a/doc/checkbutton.n b/doc/checkbutton.n index 411045f..0f27d49 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.n @@ -197,14 +197,18 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for checkbutton widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -217,33 +221,43 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. +.\" METHOD: deselect .TP \fIpathName \fBdeselect\fR +. Deselects the checkbutton and sets the associated variable to its .QW off value. +.\" METHOD: flash .TP \fIpathName \fBflash\fR +. Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is \fBdisabled\fR. +.\" METHOD: invoke .TP \fIpathName \fBinvoke\fR +. Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the Tcl command associated with the checkbutton, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is \fBdisabled\fR. +.\" METHOD: select .TP \fIpathName \fBselect\fR +. Selects the checkbutton and sets the associated variable to its .QW on value. +.\" METHOD: toggle .TP \fIpathName \fBtoggle\fR +. Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. .SH BINDINGS diff --git a/doc/chooseColor.n b/doc/chooseColor.n index 3fa6de3..be24c8e 100644 --- a/doc/chooseColor.n +++ b/doc/chooseColor.n @@ -19,16 +19,16 @@ The procedure \fBtk_chooseColor\fR pops up a dialog box for the user to select a color. The following \fIoption\-value\fR pairs are possible as command line arguments: .TP -\fB\-initialcolor\fR \fIcolor\fR +\fB\-initialcolor\fI color\fR Specifies the color to display in the color dialog when it pops up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR function. .TP -\fB\-parent\fR \fIwindow\fR +\fB\-parent\fI window\fR Makes \fIwindow\fR the logical parent of the color dialog. The color dialog is displayed on top of its parent window. .TP -\fB\-title\fR \fItitleString\fR +\fB\-title\fI titleString\fR Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .LP diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index a5b30f5..7de09b5 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -17,14 +17,14 @@ The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the user to select a directory. The following \fIoption\-value\fR pairs are possible as command line arguments: .TP -\fB\-command\fR \fIstring\fR +\fB\-command\fI string\fR Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on Mac OS X. .TP -\fB\-initialdir\fR \fIdirname\fR +\fB\-initialdir\fI dirname\fR Specifies that the directories in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory @@ -34,21 +34,21 @@ user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .TP -\fB\-message\fR \fIstring\fR +\fB\-message\fI string\fR Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. .TP -\fB\-mustexist\fR \fIboolean\fR +\fB\-mustexist\fI boolean\fR Specifies whether the user may specify non-existent directories. If this parameter is true, then the user may only select directories that already exist. The default value is \fIfalse\fR. .TP -\fB\-parent\fR \fIwindow\fR +\fB\-parent\fI window\fR Makes \fIwindow\fR the logical parent of the dialog. The dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. .TP -\fB\-title\fR \fItitleString\fR +\fB\-title\fI titleString\fR Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .SH EXAMPLE diff --git a/doc/clipboard.n b/doc/clipboard.n index ee964df..0be7936 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.n @@ -27,8 +27,9 @@ appends should be completed before returning to the event loop. The first argument to \fBclipboard\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: +.\" METHOD: append .TP -\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR +\fBclipboard append\fR ?\fB\-displayof\fI window\fR? ?\fB\-format\fI format\fR? ?\fB\-type\fI type\fR? ?\fB\-\|\-\fR? \fIdata\fR . Appends \fIdata\fR to the clipboard on \fIwindow\fR's display in the form given by \fItype\fR with the representation given @@ -71,15 +72,17 @@ next argument will always be used as \fIdata\fR. This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE +.\" METHOD: clear .TP -\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR? +\fBclipboard clear\fR ?\fB\-displayof\fI window\fR? . Claims ownership of the clipboard on \fIwindow\fR's display and removes any previous contents. \fIWindow\fR defaults to .QW . . Returns an empty string. +.\" METHOD: get .TP -\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR? +\fBclipboard get\fR ?\fB\-displayof\fI window\fR? ?\fB\-type\fI type\fR? . Retrieve data from the clipboard on \fIwindow\fR's display. \fIWindow\fR defaults to diff --git a/doc/console.n b/doc/console.n index 0a9a794..d3b5f9d 100644 --- a/doc/console.n +++ b/doc/console.n @@ -11,7 +11,7 @@ .SH NAME console \- Control the console on systems without a real console .SH SYNOPSIS -\fBconsole\fR \fIsubcommand\fR ?\fIarg ...\fR? +\fBconsole\fI subcommand\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -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 @@ -32,21 +32,29 @@ in that case, define the environment variable \fBTK_CONSOLE\fR. This can be done by modifying the Info.plist file by adding the LSEnvironment key to the main dict and setting its value to be a dict with the key \fBTK_CONSOLE\fR. .PP +.\" METHOD: eval .TP \fBconsole eval \fIscript\fR +. Evaluate the \fIscript\fR argument as a Tcl script in the console interpreter. The normal interpreter is accessed through the \fBconsoleinterp\fR command in the console interpreter. +.\" METHOD: hide .TP \fBconsole hide\fR +. Hide the console window from view. Precisely equivalent to withdrawing the \fB.\fR window in the console interpreter. +.\" METHOD: show .TP \fBconsole show\fR +. Display the console window. Precisely equivalent to deiconifying the \fB.\fR window in the console interpreter. +.\" METHOD: title .TP \fBconsole title \fR?\fIstring\fR? +. Query or modify the title of the console window. If \fIstring\fR is not specified, queries the title of the console window, and sets the title of the console window to \fIstring\fR otherwise. Precisely @@ -58,12 +66,16 @@ The \fBconsoleinterp\fR command in the console interpreter allows scripts to be evaluated in the main interpreter. It supports two subcommands: \fBeval\fR and \fBrecord\fR. .PP +.\" METHOD: eval .TP \fBconsoleinterp eval \fIscript\fR +. Evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter. +.\" METHOD: record .TP \fBconsoleinterp record \fIscript\fR +. Records and evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter as if \fIscript\fR had been typed in at the console. diff --git a/doc/entry.n b/doc/entry.n index 80e8428..f60bc20 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -13,7 +13,7 @@ .SH NAME entry \- Create and manipulate 'entry' one-line text entry widgets .SH SYNOPSIS -\fBentry\fR \fIpathName \fR?\fIoptions\fR? +\fBentry\fI pathName \fR?\fIoptions\fR? .SO \-background \-highlightthickness \-selectbackground \-borderwidth \-insertbackground \-selectborderwidth @@ -245,8 +245,10 @@ arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for entry widgets: +.\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR +. Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of @@ -255,14 +257,18 @@ 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. +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -275,8 +281,10 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. +.\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +. Delete one or more elements of the entry. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last @@ -284,22 +292,32 @@ one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the entry's string. +.\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR +. Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. +.\" METHOD: index .TP \fIpathName \fBindex\fI index\fR +. Returns the numerical index corresponding to \fIindex\fR. +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR +. Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. +.\" METHOD: scan .TP -\fIpathName \fBscan\fR \fIoption args\fR +\fIpathName \fBscan\fI option args\fR +. This command is used to implement scanning on entries. It has two forms, depending on \fIoption\fR: .RS @@ -319,6 +337,7 @@ with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the window. The return value is an empty string. .RE +.\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR This command is used to adjust the selection within an entry. It @@ -350,7 +369,7 @@ Returns an empty string. 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. @@ -371,20 +390,25 @@ If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE +.\" METHOD: validate .TP \fIpathName \fBvalidate\fR +. This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. +.\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR +. This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR +. Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. @@ -394,16 +418,19 @@ in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP -\fIpathName \fBxview\fR \fIindex\fR +\fIpathName \fBxview\fI index\fR +. Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR +. Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then diff --git a/doc/event.n b/doc/event.n index 9f5a4c6..a77861c 100644 --- a/doc/event.n +++ b/doc/event.n @@ -20,8 +20,10 @@ The \fBevent\fR command provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. The command has several different forms, determined by the first argument. The following forms are currently supported: +.\" METHOD: add .TP \fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? +. Associates the virtual event \fIvirtual\fR with the physical event sequence(s) given by the \fIsequence\fR arguments, so that the virtual event will trigger whenever any one of the \fIsequence\fRs @@ -31,8 +33,10 @@ any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. If \fIvirtual\fR is already defined, the new physical event sequences add to the existing sequences for the event. +.\" METHOD: delete .TP -\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\fR? +\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence sequence ...\fR? +. Deletes each of the \fIsequence\fRs from those associated with the virtual event given by \fIvirtual\fR. \fIVirtual\fR may be any string value and \fIsequence\fR may have @@ -43,8 +47,10 @@ are ignored. If no \fIsequence\fR argument is provided, all physical event sequences are removed for \fIvirtual\fR, so that the virtual event will not trigger anymore. +.\" METHOD: generate .TP \fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? +. Generates a window event and arranges for it to be processed just as if it had come from the window system. \fIWindow\fR gives the path name of the window for which the event @@ -65,8 +71,10 @@ will complete before the \fBevent generate\fR command returns. If the \fB\-when\fR option is specified then it determines when the event is processed. Certain events, such as key events, require that the window has focus to receive the event properly. +.\" METHOD: info .TP \fBevent info \fR?\fB<<\fIvirtual\fB>>\fR? +. Returns information about virtual events. If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value is a list of all the virtual events that are currently defined. @@ -87,34 +95,40 @@ command. These correspond to the expansions allowed in binding scripts for the \fBbind\fR command. .TP \fB\-above\fI window\fR +. \fIWindow\fR specifies the \fIabove\fR field for the event, either as a window path name or as an integer window id. Valid for \fBConfigure\fR events. Corresponds to the \fB%a\fR substitution for binding scripts. .TP \fB\-borderwidth\fI size\fR +. \fISize\fR must be a screen distance; it specifies the \fIborder_width\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%B\fR substitution for binding scripts. .TP \fB\-button\fI number\fR +. \fINumber\fR must be an integer; it specifies the \fIdetail\fR field for a \fBButton\fR or \fBButtonRelease\fR event, overriding any button number provided in the base \fIevent\fR argument. Corresponds to the \fB%b\fR substitution for binding scripts. .TP \fB\-count\fI number\fR +. \fINumber\fR must be an integer; it specifies the \fIcount\fR field for the event. Valid for \fBExpose\fR events. Corresponds to the \fB%c\fR substitution for binding scripts. .TP \fB\-data\fI string\fR +. \fIString\fR may be any value; it specifies the \fIuser_data\fR field for the event. Only valid for virtual events. Corresponds to the \fB%d\fR substitution for virtual events in binding scripts. .TP \fB\-delta\fI number\fR +. \fINumber\fR must be an integer; it specifies the \fIdelta\fR field for the \fBMouseWheel\fR event. The \fIdelta\fR refers to the direction and magnitude the mouse wheel was rotated. Note the value @@ -126,6 +140,7 @@ behaviors for mouse wheel motion. This field corresponds to the \fB%D\fR substitution for binding scripts. .TP \fB\-detail\fI detail\fR +. \fIDetail\fR specifies the \fIdetail\fR field for the event and must be one of the following: .RS @@ -142,23 +157,27 @@ Corresponds to the \fB%d\fR substitution for binding scripts. .RE .TP \fB\-focus\fI boolean\fR +. \fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR field for the event. Valid for \fBEnter\fR and \fBLeave\fR events. Corresponds to the \fB%f\fR substitution for binding scripts. .TP \fB\-height\fI size\fR +. \fISize\fR must be a screen distance; it specifies the \fIheight\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%h\fR substitution for binding scripts. .TP \fB\-keycode\fI number\fR +. \fINumber\fR must be an integer; it specifies the \fIkeycode\fR field for the event. Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%k\fR substitution for binding scripts. .TP \fB\-keysym\fI name\fR +. \fIName\fR must be the name of a valid keysym, such as \fBg\fR, \fBspace\fR, or \fBReturn\fR; its corresponding keycode value is used as the \fIkeycode\fR field for event, overriding @@ -167,6 +186,7 @@ Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%K\fR substitution for binding scripts. .TP \fB\-mode\fI notify\fR +. \fINotify\fR specifies the \fImode\fR field for the event and must be one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or \fBNotifyWhileGrabbed\fR. @@ -175,18 +195,21 @@ Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and Corresponds to the \fB%m\fR substitution for binding scripts. .TP \fB\-override\fI boolean\fR +. \fIBoolean\fR must be a boolean value; it specifies the \fIoverride_redirect\fR field for the event. Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. Corresponds to the \fB%o\fR substitution for binding scripts. .TP \fB\-place\fI where\fR +. \fIWhere\fR specifies the \fIplace\fR field for the event; it must be either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid for \fBCirculate\fR events. Corresponds to the \fB%p\fR substitution for binding scripts. .TP \fB\-root\fI window\fR +. \fIWindow\fR must be either a window path name or an integer window identifier; it specifies the \fIroot\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -195,6 +218,7 @@ events. Corresponds to the \fB%R\fR substitution for binding scripts. .TP \fB\-rootx\fI coord\fR +. \fICoord\fR must be a screen distance; it specifies the \fIx_root\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -202,6 +226,7 @@ Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\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 \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -210,16 +235,19 @@ events. Corresponds to the \fB%Y\fR substitution for binding scripts. .TP \fB\-sendevent\fI boolean\fR +. \fIBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR field for the event. Valid for all events. Corresponds to the \fB%E\fR substitution for binding scripts. .TP \fB\-serial\fI number\fR +. \fINumber\fR must be an integer; it specifies the \fIserial\fR field for the event. Valid for all events. Corresponds to the \fB%#\fR substitution for binding scripts. .TP \fB\-state\fI state\fR +. \fIState\fR specifies the \fIstate\fR field for the event. For \fBKey\fR, \fBKeyRelease\fR, \fBButtons\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events @@ -231,6 +259,7 @@ specified in the base \fIevent\fR. Corresponds to the \fB%s\fR substitution for binding scripts. .TP \fB\-subwindow\fI window\fR +. \fIWindow\fR specifies the \fIsubwindow\fR field for the event, either as a path name for a Tk widget or as an integer window identifier. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -238,6 +267,7 @@ Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, Similar to \fB%S\fR substitution for binding scripts. .TP \fB\-time\fI integer\fR +. \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. @@ -247,6 +277,7 @@ and \fBProperty\fR events. Corresponds to the \fB%t\fR substitution for binding scripts. .TP \fB\-warp\fI boolean\fR +. \fIboolean\fR must be a boolean value; it specifies whether the screen pointer should be warped as well. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -254,12 +285,14 @@ Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, only warp to a window if it is mapped. .TP \fB\-width\fI size\fR +. \fISize\fR must be a screen distance; it specifies the \fIwidth\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%w\fR substitution for binding scripts. .TP \fB\-when\fI when\fR +. \fIWhen\fR determines when the event will be processed; it must have one of the following values: .RS @@ -280,6 +313,7 @@ be processed in order but at the front of the queue. .RE .TP \fB\-x\fI coord\fR +. \fICoord\fR must be a screen distance; it specifies the \fIx\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -292,6 +326,7 @@ screen, and this option corresponds to the \fB%X\fR substitution for binding scripts. .TP \fB\-y\fI coord\fR +. \fICoord\fR must be a screen distance; it specifies the \fIy\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, @@ -312,6 +347,7 @@ Tk defines the following virtual events for the purposes of notification: .TP \fB<<AltUnderlined>>\fR +. This is sent to widget to notify it that the letter it has underlined (as an accelerator indicator) with the \fB\-underline\fR option has been pressed in combination with the Alt key. The usual response to @@ -319,26 +355,32 @@ this is to either focus into the widget (or some related widget) or to invoke the widget. .TP \fB<<Invoke>>\fR +. This can be sent to some widgets (e.g. button, listbox, menu) as an alternative to <space>. .TP \fB<<ListboxSelect>>\fR +. This is sent to a listbox when the set of selected item(s) in the listbox is updated. .TP \fB<<MenuSelect>>\fR +. This is sent to a menu when the currently selected item in the menu changes. It is intended for use with context-sensitive help systems. .TP \fB<<Modified>>\fR +. This is sent to a text widget when the contents of the widget are changed. .TP \fB<<Selection>>\fR +. This is sent to a text widget when the selection in the widget is changed. .TP \fB<<ThemeChanged>>\fR +. This is sent to all widgets when the ttk theme changed. The ttk widgets listen to this event and redisplay themselves when it fires. The legacy widgets ignore this event. @@ -353,22 +395,26 @@ cause of the change. NOTE: all tk and ttk widgets already handle this event internally. .TP \fB<<TraverseIn>>\fR +. This is sent to a widget when the focus enters the widget because of a user-driven .QW "tab to widget" action. .TP \fB<<TraverseOut>>\fR +. This is sent to a widget when the focus leaves the widget because of a user-driven .QW "tab to widget" action. .TP \fB<<UndoStack>>\fR +. This is sent to a text widget when its undo stack or redo stack becomes empty or unempty. .TP \fB<<WidgetViewSync>>\fR +. This is sent to a text widget when its internal data become obsolete, and again when these internal data are back in sync with the widget view. The detail field (%d substitution) is either true (when the @@ -379,12 +425,15 @@ bindings across multiple platforms. Users expect them to behave in the following way: .TP \fB<<Clear>>\fR +. Delete the currently selected widget contents. .TP \fB<<Copy>>\fR +. Copy the currently selected widget contents to the clipboard. .TP \fB<<Cut>>\fR +. Move the currently selected widget contents to the clipboard. .TP \fB<<LineEnd>>\fR @@ -418,10 +467,12 @@ Move to the next group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Paste>>\fR +. Replace the currently selected widget contents with the contents of the clipboard. .TP \fB<<PasteSelection>>\fR +. Insert the contents of the selection at the mouse location. (This event has meaningful \fB%x\fR and \fB%y\fR substitutions). .TP @@ -441,6 +492,7 @@ Move to the previous paragraph in the current widget while deselecting any selected contents. .TP \fB<<PrevWindow>>\fR +. Traverse to the previous window. .TP \fB<<PrevWord>>\fR @@ -449,6 +501,7 @@ Move to the previous group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<<Redo>>\fR +. Redo one undone action. .TP \fB<<SelectAll>>\fR diff --git a/doc/focus.n b/doc/focus.n index a6b0575..2aebd53 100644 --- a/doc/focus.n +++ b/doc/focus.n @@ -55,6 +55,7 @@ things. The \fBfocus\fR command can take any of the following forms: .TP \fBfocus\fR +. Returns the path name of the focus window on the display containing the application's main window, or an empty string if no window in this application has the focus on that display. Note: it is @@ -63,6 +64,7 @@ better to specify the display explicitly using \fB\-displayof\fR displays. .TP \fBfocus \fIwindow\fR +. If the application currently has the input focus on \fIwindow\fR's display, this command resets the input focus for \fIwindow\fR's display to \fIwindow\fR and returns an empty string. @@ -72,12 +74,14 @@ for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to \fIwindow\fR. If \fIwindow\fR is an empty string then the command does nothing. .TP -\fBfocus \-displayof\fR \fIwindow\fR +\fBfocus \-displayof \fIwindow\fR +. Returns the name of the focus window on the display containing \fIwindow\fR. If the focus window for \fIwindow\fR's display is not in this application, the return value is an empty string. .TP \fBfocus \-force \fIwindow\fR +. Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if the application does not currently have the input focus for the display. This command should be used sparingly, if at all. @@ -86,7 +90,8 @@ itself; instead, it should wait for the window manager to give it the focus. If \fIwindow\fR is an empty string then the command does nothing. .TP -\fBfocus \-lastfor\fR \fIwindow\fR +\fBfocus \-lastfor \fIwindow\fR +. Returns the name of the most recent window to have the input focus among all the windows in the same top-level as \fIwindow\fR. If no window in that top-level has ever had the input focus, or @@ -20,6 +20,7 @@ The \fBfont\fR command provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: +.\" METHOD: actual .TP \fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR? . @@ -38,6 +39,7 @@ that character, which will be different from the base font if the base font does not contain the given character. If \fIchar\fR may be a hyphen, it should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled \fIoption\fR. +.\" METHOD: configure .TP \fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -58,6 +60,7 @@ are implemented by the system theme. To achieve the effect of modification, use \fBfont actual\fR to get their configuration and \fBfont create\fR to synthesize a copy of the font which can be modified. .RE +.\" METHOD: create .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . @@ -67,8 +70,9 @@ form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for the new named font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. +.\" METHOD: delete .TP -\fBfont delete\fR \fIfontname\fR ?\fIfontname ...\fR? +\fBfont delete\fI fontname\fR ?\fIfontname ...\fR? . Delete the specified named fonts. If there are widgets using the named font, the named font will not actually be deleted until all the instances are @@ -76,12 +80,14 @@ released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to \fBfont create\fR, the widgets will use the new named font and redisplay themselves using the new attributes of that font. +.\" METHOD: families .TP \fBfont families\fR ?\fB\-displayof \fIwindow\fR? . The return value is a list of the case-insensitive names of all font families that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is omitted, it defaults to the main window. +.\" METHOD: measure .TP \fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR . @@ -96,6 +102,7 @@ characters such as cursive If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. +.\" METHOD: metrics .TP \fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? . @@ -107,8 +114,10 @@ omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See \fBFONT METRICS\fR below for a list of the possible metrics. +.\" METHOD: names .TP \fBfont names\fR +. The return value is a list of all the named fonts that are currently defined. .SH "FONT DESCRIPTIONS" .PP diff --git a/doc/fontchooser.n b/doc/fontchooser.n index 465af2e..02c2d61 100644 --- a/doc/fontchooser.n +++ b/doc/fontchooser.n @@ -30,16 +30,19 @@ difference, all user interaction with the dialog will be communicated to the caller via callbacks or virtual events. .PP The \fBtk fontchooser\fR command can have one of the following forms: +.\" METHOD: configure .TP \fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value ...\fR? . Set or query one or more of the configurations options below (analogous to Tk widget configuration). +.\" METHOD: show .TP \fBtk fontchooser\fR \fBshow\fR . Show the font selection dialog. Depending on the platform, may return immediately or only once the dialog has been withdrawn. +.\" METHOD: hide .TP \fBtk fontchooser\fR \fBhide\fR . diff --git a/doc/frame.n b/doc/frame.n index 5520f32..078bac6 100644 --- a/doc/frame.n +++ b/doc/frame.n @@ -12,7 +12,7 @@ .SH NAME frame \- Create and manipulate 'frame' simple container widgets .SH SYNOPSIS -\fBframe\fR \fIpathName\fR ?\fIoptions\fR? +\fBframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief @@ -127,13 +127,15 @@ operations on the widget. It has the following general form: the frame widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBframe\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index d2323de..747145d 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -35,20 +35,20 @@ whether the existing file should be overwritten or not. The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: .TP -\fB\-command\fR \fIstring\fR +\fB\-command\fI string\fR Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on Mac OS X. .TP -\fB\-confirmoverwrite\fR \fIboolean\fR +\fB\-confirmoverwrite\fI boolean\fR Configures how the Save dialog reacts when the selected file already exists, and saving would overwrite it. A true value requests a confirmation dialog be presented to the user. A false value requests that the overwrite take place without confirmation. Default value is true. .TP -\fB\-defaultextension\fR \fIextension\fR +\fB\-defaultextension\fI extension\fR . Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty @@ -58,7 +58,7 @@ does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. .TP -\fB\-filetypes\fR \fIfilePatternList\fR +\fB\-filetypes\fI filePatternList\fR . If a \fBFile types\fR listbox exists in the file dialog on the particular platform, this option gives the \fIfiletype\fRs in this listbox. When @@ -69,7 +69,7 @@ particular platform then all files are listed regardless of their types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. .TP -\fB\-initialdir\fR \fIdirectory\fR +\fB\-initialdir\fI directory\fR . Specifies that the files in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, @@ -80,31 +80,31 @@ user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .TP -\fB\-initialfile\fR \fIfilename\fR +\fB\-initialfile\fI filename\fR . Specifies a filename to be displayed in the dialog when it pops up. .TP -\fB\-message\fR \fIstring\fR +\fB\-message\fI string\fR . Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. .TP -\fB\-multiple\fR \fIboolean\fR +\fB\-multiple\fI boolean\fR . Allows the user to choose multiple files from the Open dialog. .TP -\fB\-parent\fR \fIwindow\fR +\fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the file dialog. The file dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. .TP -\fB\-title\fR \fItitleString\fR +\fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed. .TP -\fB\-typevariable\fR \fIvariableName\fR +\fB\-typevariable\fI variableName\fR . The global variable \fIvariableName\fR is used to preselect which filter is used from \fIfilterList\fR when the dialog box is opened and is @@ -84,20 +84,26 @@ The \fBgrab\fR command can take any of the following forms: .TP \fBgrab \fR?\fB\-global\fR? \fIwindow\fR Same as \fBgrab set\fR, described below. +.\" METHOD: current .TP \fBgrab current \fR?\fIwindow\fR? +. If \fIwindow\fR is specified, returns the name of the current grab window in this application for \fIwindow\fR's display, or an empty string if there is no such window. If \fIwindow\fR is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs. +.\" METHOD: release .TP \fBgrab release \fIwindow\fR +. Releases the grab on \fIwindow\fR if there is one, otherwise does nothing. Returns an empty string. +.\" METHOD: set .TP \fBgrab set \fR?\fB\-global\fR? \fIwindow\fR +. Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on @@ -105,8 +111,10 @@ If a grab was already in effect for this application on If there is already a grab on \fIwindow\fR and it has the same global/local form as the requested grab, then the command does nothing. Returns an empty string. +.\" METHOD: status .TP \fBgrab status \fIwindow\fR +. Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. @@ -28,12 +28,14 @@ argument to \fBgrid configure\fR, either a window name (any value starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR (see the \fBRELATIVE PLACEMENT\fR section below), then the command is processed in the same way as \fBgrid configure\fR. +.\" METHOD: anchor .TP \fBgrid anchor \fIwindow\fR ?\fIanchor\fR? . The anchor value controls how to place the grid within the container window when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below for further details. The default \fIanchor\fR is \fInw\fR. +.\" METHOD: bbox .TP \fBgrid bbox \fIwindow\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? . @@ -47,6 +49,7 @@ the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR arguments are specified, then the bounding box spanning the rows and columns indicated is returned. +.\" METHOD: columnconfigure .TP \fBgrid columnconfigure \fIwindow index \fR?\fI\-option value...\fR? . @@ -84,6 +87,7 @@ If only the container window and index is specified, all the current settings are returned in a list of .QW "\-option value" pairs. +.\" METHOD: configure .TP \fBgrid configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . @@ -193,6 +197,16 @@ If any of the content is already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE +.\" METHOD: content +.TP +\fBgrid content \fIwindow\fR ?\fI\-option value\fR? +. +If no options are supplied, a list of all of the content in \fIwindow\fR +is returned, most recently managed first. +\fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which +causes only the content in the row (or column) specified by \fIvalue\fR +to be returned. +.\" METHOD: forget .TP \fBgrid forget \fIwindow \fR?\fIwindow ...\fR? . @@ -210,6 +224,7 @@ the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE +.\" METHOD: info .TP \fBgrid info \fIwindow\fR . @@ -219,6 +234,7 @@ might be specified to \fBgrid configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the windows's container window. +.\" METHOD: location .TP \fBgrid location \fIwindow x y\fR . @@ -226,6 +242,7 @@ Given \fIx\fR and \fIy\fR values in screen units relative to the container wind the column and row number at that \fIx\fR and \fIy\fR location is returned. For locations that are above or to the left of the grid, \fB\-1\fR is returned. +.\" METHOD: propagate .TP \fBgrid propagate \fIwindow\fR ?\fIboolean\fR? . @@ -239,6 +256,7 @@ If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIwindow\fR. Propagation is enabled by default. +.\" METHOD: rowconfigure .TP \fBgrid rowconfigure \fIwindow index \fR?\fI\-option value...\fR? . @@ -276,6 +294,7 @@ If only the container window and index is specified, all the current settings are returned in a list of .QW "-option value" pairs. +.\" METHOD: remove .TP \fBgrid remove \fIwindow \fR?\fIwindow ...\fR? . @@ -293,6 +312,7 @@ the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE +.\" METHOD: size .TP \fBgrid size \fIcontainer\fR . @@ -300,14 +320,7 @@ Returns the size of the grid (in columns then rows) for \fIcontainer\fR. The size is determined either by the \fIcontent\fR occupying the largest row or column, or the largest column or row with a \fB\-minsize\fR, \fB\-weight\fR, or \fB\-pad\fR that is non-zero. -.TP -\fBgrid content \fIwindow\fR ?\fI\-option value\fR? -. -If no options are supplied, a list of all of the content in \fIwindow\fR -is returned, most recently managed first. -\fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which -causes only the content in the row (or column) specified by \fIvalue\fR -to be returned. +.\" METHOD: slaves .TP \fBgrid slaves \fIwindow\fR ?\fI\-option value\fR? . diff --git a/doc/image.n b/doc/image.n index 24b768a..9946544 100644 --- a/doc/image.n +++ b/doc/image.n @@ -12,15 +12,17 @@ .SH NAME image \- Create and manipulate images .SH SYNOPSIS -\fBimage\fR \fIoption \fR?\fIarg ...\fR? +\fBimage\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBimage\fR command is used to create, delete, and query images. It can take several different forms, depending on the \fIoption\fR argument. The legal forms are: +.\" METHOD: create .TP \fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? +. Creates a new image and a command with the same name and returns its name. \fItype\fR specifies the type of the image, which must be one of the types currently defined (e.g., \fBbitmap\fR). @@ -38,8 +40,10 @@ It is important to note that the image command will silently overwrite any procedure that may currently be defined by the given name, so choose the name wisely. It is recommended to use a separate namespace for image names (e.g., \fB::img::logo\fR, \fB::img::large\fR). +.\" METHOD: delete .TP \fBimage delete \fR?\fIname name\fR ...? +. Deletes each of the named images and returns an empty string. If there are instances of the images displayed in widgets, the images will not actually be deleted until all of the instances @@ -50,28 +54,40 @@ Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated with another call to \fBimage create\fR, the existing instances will use the new image. +.\" METHOD: height .TP \fBimage height \fIname\fR +. Returns a decimal string giving the height of image \fIname\fR in pixels. +.\" METHOD: inuse .TP \fBimage inuse \fIname\fR +. Returns a boolean value indicating whether or not the image given by \fIname\fR is in use by any widgets. +.\" METHOD: names .TP \fBimage names\fR +. Returns a list containing the names of all existing images. +.\" METHOD: type .TP \fBimage type \fIname\fR +. Returns the type of image \fIname\fR (the value of the \fItype\fR argument to \fBimage create\fR when the image was created). +.\" METHOD: types .TP \fBimage types\fR +. Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the \fItype\fR argument to \fBimage create\fR). +.\" METHOD: width .TP \fBimage width \fIname\fR +. Returns a decimal string giving the width of image \fIname\fR in pixels. .PP @@ -85,16 +101,19 @@ in any Tk application. Individual applications or extensions may define additional types. .TP \fBbitmap\fR +. Each pixel in the image displays a foreground color, a background color, or nothing. See the \fBbitmap\fR manual entry for more information. .TP \fBphoto\fR +. Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. .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 diff --git a/doc/label.n b/doc/label.n index 290ac8a..5d28e31 100644 --- a/doc/label.n +++ b/doc/label.n @@ -12,7 +12,7 @@ .SH NAME label \- Create and manipulate 'label' non-interactive text or image widgets .SH SYNOPSIS -\fBlabel\fR \fIpathName \fR?\fIoptions\fR? +\fBlabel\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady @@ -80,14 +80,18 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for label widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabel\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for diff --git a/doc/labelframe.n b/doc/labelframe.n index 89f56c4..da8eab9 100644 --- a/doc/labelframe.n +++ b/doc/labelframe.n @@ -12,7 +12,7 @@ .SH NAME labelframe \- Create and manipulate 'labelframe' labelled container widgets .SH SYNOPSIS -\fBlabelframe\fR \fIpathName\fR ?\fIoptions\fR? +\fBlabelframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightbackground \-pady \-cursor \-highlightcolor \-relief @@ -101,14 +101,18 @@ operations on the widget. It has the following general form: the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabelframe\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for diff --git a/doc/listbox.n b/doc/listbox.n index a047be6..68f6e80 100644 --- a/doc/listbox.n +++ b/doc/listbox.n @@ -12,7 +12,7 @@ .SH NAME listbox \- Create and manipulate 'listbox' item list widgets .SH SYNOPSIS -\fBlistbox\fR \fIpathName \fR?\fIoptions\fR? +\fBlistbox\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-disabledforeground \-exportselection \-font @@ -144,8 +144,9 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for listbox widgets: +.\" METHOD: activate .TP -\fIpathName \fBactivate\fR \fIindex\fR +\fIpathName \fBactivate\fI index\fR . Sets the active element to the one indicated by \fIindex\fR. If \fIindex\fR is outside the range of elements in the listbox @@ -153,8 +154,9 @@ then the closest element is activated. The active element is drawn as specified by \fB\-activestyle\fR when the widget has the input focus, and its index may be retrieved with the index \fBactive\fR. +.\" METHOD: bbox .TP -\fIpathName \fBbbox\fR \fIindex\fR +\fIpathName \fBbbox\fI index\fR . Returns a list of four numbers describing the bounding box of the text in the element given by \fIindex\fR. @@ -168,13 +170,15 @@ or if \fIindex\fR refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible. +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -190,6 +194,7 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. +.\" METHOD: curselection .TP \fIpathName \fBcurselection\fR . @@ -197,6 +202,7 @@ Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. +.\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . @@ -204,6 +210,7 @@ Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR are indices specifying the first and last elements in the range to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR, i.e. a single element is deleted. +.\" METHOD: get .TP \fIpathName \fBget \fIfirst\fR ?\fIlast\fR? . @@ -215,12 +222,14 @@ are all of the listbox elements between \fIfirst\fR and \fIlast\fR, inclusive. Both \fIfirst\fR and \fIlast\fR may have any of the standard forms for indices. +.\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the integer index value that corresponds to \fIindex\fR. If \fIindex\fR is \fBend\fR the return value is a count of the number of elements in the listbox (not the index of the last element). +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? . @@ -228,12 +237,14 @@ Inserts zero or more new elements in the list just before the element given by \fIindex\fR. If \fIindex\fR is specified as \fBend\fR then the new elements are added to the end of the list. Returns an empty string. +.\" METHOD: itemcget .TP \fIpathName \fBitemcget \fIindex option\fR . Returns the current value of the item configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBitemconfigure\fR command. +.\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . @@ -272,13 +283,15 @@ item while it is selected. It may have any of the forms accepted by item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .RE +.\" METHOD: nearest .TP \fIpathName \fBnearest \fIy\fR . Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. +.\" METHOD: scan .TP -\fIpathName \fBscan\fR \fIoption args\fR +\fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on listboxes. It has two forms, depending on \fIoption\fR: @@ -302,6 +315,7 @@ with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. .RE +.\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . @@ -311,6 +325,7 @@ If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. +.\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . @@ -346,11 +361,13 @@ Selects all of the elements in the range between \fIfirst\fR and \fIlast\fR, inclusive, without affecting the selection state of elements outside that range. .RE +.\" METHOD: size .TP \fIpathName \fBsize\fR . Returns a decimal string indicating the total number of elements in the listbox. +.\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR . @@ -399,6 +416,7 @@ If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR character units (the width of the \fB0\fR character) on the display. .RE +.\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . diff --git a/doc/loadTk.n b/doc/loadTk.n index e1c93c8..122b2be 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -11,7 +11,7 @@ .SH NAME safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS -\fBsafe::loadTk \fIchild\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? +\fBsafe::loadTk \fIchild\fR ?\fB\-use\fI windowId\fR? ?\fB\-display\fI displayName\fR? .BE .SH DESCRIPTION .PP @@ -32,7 +32,7 @@ a window belonging to another application. As a convenience, if the window you plan to use is a Tk Window of the application you can use the window name (e.g., .QW \fB.x.y\fR ) -instead of its window Id (e.g., from \fBwinfo id\fR \fB.x.y\fR). +instead of its window Id (e.g., from \fBwinfo id\fB .x.y\fR). When \fB\-use\fR is not specified, a new toplevel window is created for the .QW . window of the safe interpreter. On X11 if you want the embedded window to use @@ -51,7 +51,7 @@ Tk initialization is now safe with respect to not trusting the child's state for startup. \fBsafe::loadTk\fR registers the child's name so when the Tk initialization (\fBTk_SafeInit\fR) is called and in turn calls the parent's \fBsafe::InitTk\fR it will return the desired \fBargv\fR equivalent -(\fB\-use\fR \fIwindowId\fR, correct \fB\-display\fR, etc.) +(\fB\-use\fI windowId\fR, correct \fB\-display\fR, etc.) .PP When \fB\-use\fR is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes from a @@ -13,8 +13,8 @@ menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars .SH SYNOPSIS .nf -\fBmenu\fR \fIpathName \fR?\fIoptions\fR? -\fBtk_menuSetFocus\fR \fIpathName\fR +\fBmenu\fI pathName \fR?\fIoptions\fR? +\fBtk_menuSetFocus\fI pathName\fR .SO \-activebackground \-borderwidth \-foreground \-activeborderwidth \-cursor \-relief @@ -371,6 +371,7 @@ for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .PP The following widget commands are possible for menu widgets: +.\" METHOD: activate .TP \fIpathName \fBactivate \fIindex\fR . @@ -380,6 +381,7 @@ Any previously-active entry is deactivated. If \fIindex\fR is specified as \fB{}\fR, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string. +.\" METHOD: add .TP \fIpathName \fBadd \fItype \fR?\fIid\fR? ?\fIoption value option value ...\fR? . @@ -393,6 +395,7 @@ identifier is generated. If additional arguments are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR section below. The \fBadd\fR widget command returns the id of the new entry. +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -400,6 +403,7 @@ Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. +.\" METHOD: clone .TP \fIpathName \fBclone \fInewPathname\fR ?\fIcloneType\fR? . @@ -409,6 +413,7 @@ propagated to the original menu and vice versa. \fIcloneType\fR can be \fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be called outside of the Tk library. See the \fBCLONES\fR section for more information. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -424,6 +429,7 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. +.\" METHOD: delete .TP \fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? . @@ -432,6 +438,7 @@ Delete all of the menu entries between \fIindex1\fR and If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. Attempts to delete a tear-off menu entry are ignored (instead, you should change the \fB\-tearoff\fR option to remove the tear-off entry). +.\" METHOD: entrycget .TP \fIpathName \fBentrycget \fIindex option\fR . @@ -439,6 +446,7 @@ Returns the current value of a configuration option for the entry given by \fIindex\fR. \fIOption\fR may have any of the names described in the \fBMENU ENTRY OPTIONS\fR section below. +.\" METHOD: entryconfigure .TP \fIpathName \fBentryconfigure \fIindex \fR?\fIoptions...\fR? . @@ -452,6 +460,7 @@ modified as indicated in the command and the command returns an empty string. If no \fIoptions\fR are specified, returns a list describing the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). +.\" METHOD: id .TP \fIpathName \fBid \fIindex\fR . @@ -460,11 +469,13 @@ This is the identifier that was assigned to the entry when it was created using the \fBadd\fR or \fBinsert\fR widget command. Returns an empty string for the tear-off entry, or if \fIindex\fR is equivalent to \fB{}\fR. +.\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the numerical index corresponding to \fIindex\fR, or \fB{}\fR if \fIindex\fR was specified as \fB{}\fR. +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex type \fR?\fIid\fR? ?\fIoption value option value ...\fR? . @@ -475,6 +486,7 @@ to the end of the menu. The \fItype\fR, \fIid\fR, \fIoption\fR, and widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one. The \fBinsert\fR widget command returns the id of the new entry. +.\" METHOD: invoke .TP \fIpathName \fBinvoke \fIindex\fR . @@ -487,6 +499,7 @@ command. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the \fBinvoke\fR widget command. +.\" METHOD: post .TP \fIpathName \fBpost \fIx y\fR ?\fIindex\fR? . @@ -501,6 +514,7 @@ posting the menu and the result of that script is returned as the result of the \fBpost\fR widget command. If an error returns while executing the command, then the error is returned without posting the menu. +.\" METHOD: postcascade .TP \fIpathName \fBpostcascade \fIindex\fR . @@ -510,6 +524,7 @@ If \fIindex\fR does not correspond to a cascade entry, or if \fIpathName\fR is not posted, the command has no effect except to unpost any currently posted submenu. +.\" METHOD: type .TP \fIpathName \fBtype \fIindex\fR . @@ -517,6 +532,7 @@ Returns the type of the menu entry given by \fIindex\fR. This is the \fItype\fR argument passed to the \fBadd\fR or \fBinsert\fR widget command when the entry was created, such as \fBcommand\fR or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. +.\" METHOD: unpost .TP \fIpathName \fBunpost\fR . @@ -524,11 +540,13 @@ Unmap the window so that it is no longer displayed. If a lower-level cascaded menu is posted, unpost that menu. Returns an empty string. This subcommand does not work on Windows and the Macintosh, as those platforms have their own way of unposting menus. +.\" METHOD: xposition .TP \fIpathName \fBxposition \fIindex\fR . Returns a decimal string giving the x-coordinate within the menu window of the leftmost pixel in the entry specified by \fIindex\fR. +.\" METHOD: yposition .TP \fIpathName \fByposition \fIindex\fR . diff --git a/doc/menubutton.n b/doc/menubutton.n index d07a8fe..375b69a 100644 --- a/doc/menubutton.n +++ b/doc/menubutton.n @@ -12,7 +12,7 @@ .SH NAME menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets .SH SYNOPSIS -\fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? +\fBmenubutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady @@ -122,6 +122,7 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for menubutton widgets: +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -129,6 +130,7 @@ Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . diff --git a/doc/message.n b/doc/message.n index eb83d2f..95547c4 100644 --- a/doc/message.n +++ b/doc/message.n @@ -12,7 +12,7 @@ .SH NAME message \- Create and manipulate 'message' non-interactive text widgets .SH SYNOPSIS -\fBmessage\fR \fIpathName \fR?\fIoptions\fR? +\fBmessage\fI pathName \fR?\fIoptions\fR? .SO \-anchor \-background \-borderwidth \-cursor \-font \-foreground @@ -111,6 +111,7 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for message widgets: +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -118,6 +119,7 @@ Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . diff --git a/doc/messageBox.n b/doc/messageBox.n index 4350b22..b7be4e8 100644 --- a/doc/messageBox.n +++ b/doc/messageBox.n @@ -24,13 +24,13 @@ buttons. Then it returns the symbolic name of the selected button. .PP The following option-value pairs are supported: .TP -\fB\-command\fR \fIstring\fR +\fB\-command\fI string\fR Specifies the prefix of a Tcl command to invoke when the user closes the dialog. The actual command consists of \fIstring\fR followed by a space and the name of the button clicked by the user to close the dialog. This is only available on Mac OS X. .TP -\fB\-default\fR \fIname\fR +\fB\-default\fI name\fR . \fIName\fR gives the symbolic name of the default button for this message window ( @@ -40,36 +40,36 @@ and so on). See \fB\-type\fR for a list of the symbolic names. If this option is not specified, the first button in the dialog will be made the default. .TP -\fB\-detail\fR \fIstring\fR +\fB\-detail\fI string\fR . Specifies an auxiliary message to the main message given by the \fB\-message\fR option. The message detail will be presented beneath the main message and, where supported by the OS, in a less emphasized font than the main message. .TP -\fB\-icon\fR \fIiconImage\fR +\fB\-icon\fI iconImage\fR . Specifies an icon to display. \fIIconImage\fR must be one of the following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or \fBwarning\fR. If this option is not specified, then the info icon will be displayed. .TP -\fB\-message\fR \fIstring\fR +\fB\-message\fI string\fR . Specifies the message to display in this message box. The default value is an empty string. .TP -\fB\-parent\fR \fIwindow\fR +\fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the message box. The message box is displayed on top of its parent window. .TP -\fB\-title\fR \fItitleString\fR +\fB\-title\fI titleString\fR . Specifies a string to display as the title of the message box. The default value is an empty string. .TP -\fB\-type\fR \fIpredefinedType\fR +\fB\-type\fI predefinedType\fR . Arranges for a predefined set of buttons to be displayed. The following values are possible for \fIpredefinedType\fR: diff --git a/doc/nsimage.n b/doc/nsimage.n index 8b401d7..cf2fe82 100644 --- a/doc/nsimage.n +++ b/doc/nsimage.n @@ -37,14 +37,15 @@ This option is required. .TP \fB\-as\fR .PP -There are four possible values for the \fB-as\fR option which specify +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. +provided by the system. +This is the default if the \fB\-as\fR option is not specified. .IP \fBfile\fR .IP @@ -101,7 +102,7 @@ change slightly. 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. +is 1.0, which makes the image opaque. .TP \fB\-pressed\fR .PP diff --git a/doc/option.n b/doc/option.n index 6042010..9ec408f 100644 --- a/doc/option.n +++ b/doc/option.n @@ -22,8 +22,9 @@ option \- Add/retrieve window options to/from the option database .SH DESCRIPTION .PP The \fBoption\fR command allows you to add entries to the Tk option -database or to retrieve options from the database. The \fBadd\fR -form of the command adds a new option to the database. +database or to retrieve options from the database. +.\" METHOD: add +The \fBadd\fR form of the command adds a new option to the database. \fIPattern\fR contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format (see @@ -35,6 +36,7 @@ is specified, it indicates the priority level for this option (see below for legal values); it defaults to \fBinteractive\fR. This command always returns an empty string. .PP +.\" METHOD: clear The \fBoption clear\fR command clears the option database. Default options (from the \fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR @@ -42,6 +44,7 @@ file) will be reloaded automatically the next time an option is added to the database or removed from it. This command always returns an empty string. .PP +.\" METHOD: get The \fBoption get\fR command returns the value of the option specified for \fIwindow\fR under \fIname\fR and \fIclass\fR. If several entries in the option @@ -52,6 +55,7 @@ entries at the same priority level, then it returns whichever entry was most recently entered into the option database. If there are no matching entries, then the empty string is returned. .PP +.\" METHOD: readfile The \fBreadfile\fR form of the command reads \fIfileName\fR, which should have the standard format for an X resource database such as \fB.Xdefaults\fR, and adds all the diff --git a/doc/options.n b/doc/options.n index de03ec8..913c912 100644 --- a/doc/options.n +++ b/doc/options.n @@ -60,7 +60,7 @@ 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. +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. @@ -27,8 +27,10 @@ If the first argument to \fBpack\fR is a window name (any value starting with .QW . ), then the command is processed in the same way as \fBpack configure\fR. +.\" METHOD: configure .TP \fBpack configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? +. The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. @@ -124,6 +126,15 @@ If any of the content are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE +.\" METHOD: content +.TP +\fBpack content \fIwindow\fR +. +Returns a list of all of the content windows in the packing order for \fIwindow\fR. +The order of the content windows in the list is the same as their order in +the packing order. +If \fIwindow\fR has no content then an empty string is returned. +.\" METHOD: forget .TP \fBpack forget \fIwindow \fR?\fIwindow ...\fR? Removes each of the \fIwindow\fRs from the packing order for its @@ -137,6 +148,7 @@ the virtual event \fB<<NoManagedChild>>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE +.\" METHOD: info .TP \fBpack info \fIwindow\fR Returns a list whose elements are the current configuration state of @@ -145,8 +157,10 @@ might be specified to \fBpack configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the window's container. +.\" METHOD: propagate .TP \fBpack propagate \fIcontainer\fR ?\fIboolean\fR? +. If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fIcontainer\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). @@ -157,12 +171,7 @@ If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIcontainer\fR. Propagation is enabled by default. -.TP -\fBpack content \fIwindow\fR -Returns a list of all of the content windows in the packing order for \fIwindow\fR. -The order of the content windows in the list is the same as their order in -the packing order. -If \fIwindow\fR has no content then an empty string is returned. +.\" METHOD: slaves .TP \fBpack slaves \fIwindow\fR . diff --git a/doc/panedwindow.n b/doc/panedwindow.n index cad256a..54abb8f 100644 --- a/doc/panedwindow.n +++ b/doc/panedwindow.n @@ -12,7 +12,7 @@ .SH NAME panedwindow \- Create and manipulate 'panedwindow' split container widgets .SH SYNOPSIS -\fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR? +\fBpanedwindow\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-orient \-relief @@ -38,17 +38,17 @@ version of the sash is displayed during the resizing to show where the panes will be resized to when releasing the mouse button. This .QW ghost version of the sash is the proxy. It's rendering can be configured -using the \fB-proxybackground\fR, \fB-proxyborderwidth\fR and -\fB-proxyrelief\fR options. +using the \fB\-proxybackground\fR, \fB\-proxyborderwidth\fR and +\fB\-proxyrelief\fR options. .OP \-proxybackground proxyBackground ProxyBackground Background color to use when drawing the proxy. If an empty string, the -value of the \fB-background\fR option will be used. +value of the \fB\-background\fR option will be used. .OP \-proxyborderwidth proxyBorderWidth ProxyBorderWidth Specifies the borderwidth of the proxy. May be any value accepted by \fBTk_GetPixels\fR. .OP \-proxyrelief proxyRelief ProxyRelief Relief to use when drawing the proxy. May be any of the standard Tk -relief values. If an empty string, the value of the \fB-sashrelief\fR +relief values. If an empty string, the value of the \fB\-sashrelief\fR option will be used. .OP \-sashcursor sashCursor SashCursor Mouse cursor to use when over a sash. If null, @@ -98,6 +98,7 @@ following general form: the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for panedwindow widgets: +.\" METHOD: add .TP \fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? . @@ -106,12 +107,14 @@ The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. \fIOption\fR may have any of the values accepted by the \fBconfigure\fR subcommand. +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -126,11 +129,13 @@ one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. +.\" METHOD: forget .TP \fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? . Remove the pane containing \fIwindow\fR from the panedwindow. All geometry management options for \fIwindow\fR will be forgotten. +.\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . @@ -140,11 +145,13 @@ sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. +.\" METHOD: panecget .TP \fIpathName \fBpanecget \fIwindow option\fR . Query a management option for \fIwindow\fR. \fIOption\fR may be any value allowed by the \fBpaneconfigure\fR subcommand. +.\" METHOD: paneconfigure .TP \fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -264,10 +271,12 @@ width requested internally by the window will be used initially; the width may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .RE +.\" METHOD: panes .TP \fIpathName \fBpanes\fR . Returns an ordered list of the widgets managed by \fIpathName\fR. +.\" METHOD: proxy .TP \fIpathName \fBproxy \fR?\fIargs\fR? . @@ -289,6 +298,7 @@ Remove the proxy from the display. . Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE +.\" METHOD: sash .TP \fIpathName \fBsash \fR?\fIargs\fR? This command is used to query and change the position of sashes in the diff --git a/doc/photo.n b/doc/photo.n index bc97319..d8a48df 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -43,7 +43,11 @@ procedural interface. At present, only .VS 8.6 PNG, .VE 8.6 -GIF and PPM/PGM formats are supported, but an interface exists to +GIF, PPM/PGM, +.VS 8.7 +and (read-only) SVG +.VE 8.7 +formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is (semi)transparent if the image data it was obtained from had transparency informaton. In regions where no image data has been @@ -151,19 +155,22 @@ case the width and/or height, respectively, of the image will not be changed. .PP The following commands are possible for photo images: +.\" METHOD: blank .TP \fIimageName \fBblank\fR . Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. The metadata dict of the image is not changed. +.\" METHOD: cget .TP -\fIimageName \fBcget\fR \fIoption\fR +\fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBphoto\fR command. +.\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -183,8 +190,9 @@ this case the command returns an empty string. 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 +.\" METHOD: copy .TP -\fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBcopy\fI sourceImage\fR ?\fIoption value(s) ...\fR? . Copies a region from the image called \fIsourceImage\fR (which must be a photo image) to the image called \fIimageName\fR, possibly with @@ -250,6 +258,7 @@ is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is \fIoverlay\fR. .RE +.\" METHOD: data .TP \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? . @@ -257,7 +266,7 @@ 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. +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: @@ -303,7 +312,7 @@ 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 \fImetadata\fR +\fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the returned data string. @@ -313,17 +322,19 @@ 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? +.\" METHOD: get +.TP +\fIimageName \fBget\fI x y\fR ?\fB\-withalpha\fR? . Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the image as a list of three integers between 0 and 255, representing the -red, green and blue components respectively. If the \fB-withalpha\fR +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 +.\" METHOD: put .TP -\fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR? +\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 @@ -347,7 +358,7 @@ 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 +\fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. @@ -368,8 +379,9 @@ discarded. Note that if \fIdata\fR specifies a single color value, then a region extending to the bottom-right corner represented by (\fIx2\fR,\fIy2\fR) will be filled with that color. .RE +.\" METHOD: read .TP -\fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? +\fIimageName \fBread\fI filename\fR ?\fIoption value(s) ...\fR? . Reads image data from the file named \fIfilename\fR into the image. This command first searches the list of @@ -401,7 +413,7 @@ 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 +\fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. @@ -424,6 +436,7 @@ Specifies the coordinates of the top-left corner of the region of \fIimageName\fR into which data from \fIfilename\fR are to be read. The default is (0,0). .RE +.\" METHOD: redither .TP \fIimageName \fBredither\fR . @@ -434,33 +447,32 @@ dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. +.\" METHOD: transparency .TP \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? . Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS -.VS 8.7 .TP -\fIimageName \fBtransparency get \fIx y\fR ?\fB-alpha\fR? -. +\fIimageName \fBtransparency get \fIx y\fR ?\fB\-alpha\fR? +.VS 8.7 Returns true if the pixel at (\fIx\fR,\fIy\fR) is fully transparent, -false otherwise. If the option \fB-alpha\fR is passed, returns the +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\fR \fInewVal\fR ?\fB-alpha\fR? -. +\fIimageName \fBtransparency set \fIx y newVal\fR ?\fB\-alpha\fR? +.VS 8.7 Change the transparency of the pixel at (\fIx\fR,\fIy\fR) to \fInewVal.\fR If no additional option is passed, \fInewVal\fR is interpreted as a boolean and the pixel is made fully transparent if -that value is true, fully opaque otherwise. If the \fB-alpha\fR +that value is true, fully opaque otherwise. If the \fB\-alpha\fR option is passed, \fInewVal\fR is interpreted as an integral alpha value for the pixel, which must be in the range 0 to 255. .VE 8.7 .RE +.\" METHOD: write .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? . @@ -503,7 +515,7 @@ 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 +\fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the written file. The specified \fImetadata\fR is passed to the driver for inclusion in the @@ -518,8 +530,8 @@ The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The -standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF -formats, +standard Tk distribution comes with handlers for PPM/PGM, PNG, GIF and +(read-only) SVG formats, .VS 8.7 as well as the \fBdefault\fR handler to encode/decode image data in a human readable form. @@ -555,7 +567,7 @@ 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 +\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) @@ -579,7 +591,7 @@ The built-in handlers support these suboptions: \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 +\fIimageName \fBdata\fR. Specifies the format to use for the color string of each pixel. \fIformatType\fR may be one of: \fBrgb\fR to encode pixel data in the form \fB#\fIRRGGBB\fR, \fBrgba\fR to encode pixel data in the form \fB#\fIRRGGBBAA\fR or \fBlist\fR to encode @@ -603,11 +615,13 @@ 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 +\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. +.RS +.PP \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 @@ -618,32 +632,51 @@ 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: +.TP +\fBelements:\fR . -.RS -\fB elements:\fR g, path, rect, circle, ellipse, line, polyline, polygon, +g, path, rect, circle, ellipse, line, polyline, polygon, linearGradient, radialGradient, stop, defs, svg, style -.PP -\fB attributes:\fR width, height, viewBox, +.TP +\fBattributes:\fR +. +width, height, viewBox, preserveAspectRatio with none, xMin, xMid, xMax, yMin, yMid, yMax, slice -.PP -\fB gradient attributes:\fR gradientUnits with objectBoundingBox, +.TP +\fBgradient attributes:\fR +. +gradientUnits with objectBoundingBox, gradientTransform, cx, cy, r fx, fy x1, y1, x2, y2 spreadMethod with pad, reflect or repeat, xlink:href -.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, +.TP +\fBpoly attributes:\fR +. +points +.TP +\fBline attributes:\fR +. +x1, y1, x2, y2 +.TP +\fBellipse attributes:\fR +. +cx, cy, rx, ry +.TP +\fBcircle attributes:\fR +. +cx, cy, r +.TP +\fBrectangle attributes:\fR +. +x, y, width, height, rx, ry +.TP +\fBpath attributes:\fR +. +d with m, M, l, L, h, H, v, V, c, C, s, S, q, Q, t, T, a, A, z, Z +.TP +\fBstyle attributes:\fR +. +display with none, visibility, hidden, visible, fill with nonzero and evenodd, opacity, fill-opacity, stroke, stroke-width, stroke-dasharray, stroke-dashoffset, stroke-opacity, stroke-linecap with butt, round and square, @@ -652,10 +685,11 @@ fill-rule, font-size, transform with matrix, translate, scale, rotate, skewX and skewY, stop-color, stop-opacity, offset, id, class .RE -. +.PP Currently only SVG images reading and conversion into (pixel-based format) photos is supported: Tk does not (yet) support bundling photo images in SVG vector graphics. +.RE .VE 8.6 .VS 8.7 .SH "COLOR FORMATS" @@ -747,45 +781,46 @@ parsed, or may use metadata to be included in image files or formats. Each image format driver supports an individual set of metadata dictionary keys. Predefined keys are: .TP -DPI +\fBDPI\fR . Horizontal image resolution in DPI as a double value. Supported by format \fBpng\fR. .TP -aspect +\fBaspect\fR . Aspect ratio horizontal divided by vertical as double value. Supported by formats \fBgif\fR and \fBpng\fR. .TP -comment +\fBcomment\fR . Image text comment. Supported by formats \fBgif\fR and \fBpng\fR. .PP It is valid to set any key in the metadata dict. -A format driver will ignore keys it does not handle. +A format driver will ignore keys that it does not handle. .SS "METADATA KEYS FOR ANIMATED GIF INFORMATION" .PP The following metadata keys are reported when reading a \fBgif\fR format file. -They are typically used in conjunction with the \fI-index\fR option of an +They are typically used in conjunction with the \fB\-index\fR option of an animated \fBgif\fR file to properly display the subimage sequence. -The options are linked to each subimage selected by \fI-index\fR. +The options are linked to each subimage selected by \fB\-index\fR. .TP -\fBdelay time\fR \fItime\fR +\fBdelay time\fI time\fR . -Update delay time in 10ms unit. This key is only present, if delay time is not 0. +Update delay time in 10ms units. This key is only present if the delay time is not 0. .TP -\fBdisposal method\fR \fImethod\fR +\fBdisposal method\fI method\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. +Possible values are: \fBdo not dispose\fR, \fBrestore to background color\fR, +\fBrestore to previous\fR. .TP -\fBuser interaction\fR \fIbool\fR +\fBuser interaction\fI bool\fR . The key is present with a value of 1, if user interaction is specified. Otherwise, the key is not present. .TP -\fBupdate region\fR \fIX0\fR, \fIY0\fR, \fIwidth\fR, \fIheight\fR +\fBupdate region\fI X0\fR, \fIY0\fR, \fIwidth\fR, \fIheight\fR . Update region of the current subimage, if subimage has not the same size as the full image. The pixel outside of this box are all fully transparent. diff --git a/doc/place.n b/doc/place.n index b56ad58..b1189cd 100644 --- a/doc/place.n +++ b/doc/place.n @@ -30,13 +30,16 @@ centered inside the container. .PP .TP \fBplace \fIwindow option value \fR?\fIoption value ...\fR? +. Arrange for the placer to manage the geometry of a content whose pathName is \fIwindow\fR. The remaining arguments consist of one or more \fIoption\-value\fR pairs that specify the way in which \fIwindow\fR's geometry is managed. \fIOption\fR may have any of the values accepted by the \fBplace configure\fR command. +.\" METHOD: configure .TP \fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the geometry options of the content given by \fIwindow\fR. If no \fIoption\fR is specified, this command returns a list describing the available options (see \fBTk_ConfigureInfo\fR for @@ -177,23 +180,30 @@ If the same value is specified separately with two different options, such as \fB\-x\fR and \fB\-relx\fR, then the most recent option is used and the older one is ignored. .RE +.\" METHOD: content +.TP +\fBplace content \fIwindow\fR +. +Returns a list of all the content windows for which \fIwindow\fR is the container. +If there is no content for \fIwindow\fR then an empty string is returned. +.\" METHOD: forget .TP \fBplace forget \fIwindow\fR +. Causes the placer to stop managing the geometry of \fIwindow\fR. As a side effect of this command \fIwindow\fR will be unmapped so that it does not appear on the screen. If \fIwindow\fR is not currently managed by the placer then the command has no effect. This command returns an empty string. +.\" METHOD: info .TP \fBplace info \fIwindow\fR +. Returns a list giving the current configuration of \fIwindow\fR. The list consists of \fIoption\-value\fR pairs in exactly the same form as might be specified to the \fBplace configure\fR command. -.TP -\fBplace content \fIwindow\fR -Returns a list of all the content windows for which \fIwindow\fR is the container. -If there is no content for \fIwindow\fR then an empty string is returned. +.\" METHOD: slaves .TP \fBplace slaves \fIwindow\fR . diff --git a/doc/radiobutton.n b/doc/radiobutton.n index 2169515..6033954 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.n @@ -12,7 +12,7 @@ .SH NAME radiobutton \- Create and manipulate 'radiobutton' pick-one widgets .SH SYNOPSIS -\fBradiobutton\fR \fIpathName \fR?\fIoptions\fR? +\fBradiobutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady @@ -181,13 +181,15 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for radiobutton widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -203,6 +205,7 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. +.\" METHOD: deselect .TP \fIpathName \fBdeselect\fR . @@ -210,6 +213,7 @@ Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect. +.\" METHOD: flash .TP \fIpathName \fBflash\fR . @@ -218,6 +222,7 @@ several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active state as when the command was invoked. This command is ignored if the radiobutton's state is \fBdisabled\fR. +.\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . @@ -227,6 +232,7 @@ its associated Tcl command, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is \fBdisabled\fR. +.\" METHOD: select .TP \fIpathName \fBselect\fR . diff --git a/doc/scale.n b/doc/scale.n index 0499d0a..97e0de3 100644 --- a/doc/scale.n +++ b/doc/scale.n @@ -12,7 +12,7 @@ .SH NAME scale \- Create and manipulate 'scale' value-controlled slider widgets .SH SYNOPSIS -\fBscale\fR \fIpathName \fR?\fIoptions\fR? +\fBscale\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-foreground \-relief \-background \-highlightbackground \-repeatdelay @@ -143,13 +143,15 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scale widgets: +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -165,6 +167,7 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. +.\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . @@ -172,6 +175,7 @@ Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to \fIvalue\fR. If \fIvalue\fR is omitted then the scale's current value is used. +.\" METHOD: get .TP \fIpathName \fBget\fR ?\fIx y\fR? . @@ -181,6 +185,7 @@ pixel coordinates within the widget; the command returns the scale value corresponding to the given pixel. Only one of \fIx\fR or \fIy\fR is used: for horizontal scales \fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. +.\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . @@ -193,6 +198,7 @@ and \fBtrough2\fR means that the point is over the portion of the slider below or to the right of the slider. If the point is not over one of these elements, an empty string is returned. +.\" METHOD: set .TP \fIpathName \fBset \fIvalue\fR . diff --git a/doc/scrollbar.n b/doc/scrollbar.n index fee959d..86b6214 100644 --- a/doc/scrollbar.n +++ b/doc/scrollbar.n @@ -12,7 +12,7 @@ .SH NAME scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets .SH SYNOPSIS -\fBscrollbar\fR \fIpathName \fR?\fIoptions\fR? +\fBscrollbar\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightcolor \-repeatdelay \-background \-highlightthickness \-repeatinterval @@ -108,6 +108,7 @@ operations on the widget. It has the following general form: \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scrollbar widgets: +.\" METHOD: activate .TP \fIpathName \fBactivate \fR?\fIelement\fR? . @@ -121,6 +122,7 @@ will be active. If \fIelement\fR is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active. +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -128,6 +130,7 @@ Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -143,6 +146,7 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. +.\" METHOD: delta .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR . @@ -155,6 +159,7 @@ ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. +.\" METHOD: fraction .TP \fIpathName \fBfraction \fIx y\fR . @@ -167,11 +172,13 @@ the middle, and so on. widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. +.\" METHOD: get .TP \fIpathName \fBget\fR . Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent \fBset\fR widget command. +.\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . @@ -180,6 +187,7 @@ Returns the name of the element under the point given by \fIx\fR and not lie in any element of the scrollbar. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. +.\" METHOD: set .TP \fIpathName \fBset \fIfirst last\fR . diff --git a/doc/selection.n b/doc/selection.n index a26c5d9..19117ee 100644 --- a/doc/selection.n +++ b/doc/selection.n @@ -26,8 +26,9 @@ Note that for management of the \fBCLIPBOARD\fR selection (see below), the The first argument to \fBselection\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: +.\" METHOD: clear .TP -\fBselection clear\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? +\fBselection clear\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? . If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it so that no window owns the selection anymore. \fISelection\fR @@ -37,8 +38,9 @@ Communication Conventions Manual for complete details. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . Returns an empty string. +.\" METHOD: get .TP -\fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? +\fBselection get\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? ?\fB\-type\fI type\fR? . Retrieves the value of \fIselection\fR from \fIwindow\fR's display and returns it as a result. \fISelection\fR defaults to \fBPRIMARY\fR and @@ -61,8 +63,9 @@ collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that \fBselection get\fR does not retrieve the selection in the \fBUTF8_STRING\fR format unless told to. +.\" METHOD: handle .TP -\fBselection handle\fR ?\fB\-selection\fR \fIs\fR? ?\fB\-type\fR \fIt\fR? ?\fB\-format\fR \fIf\fR? \fIwindow command\fR +\fBselection handle\fR ?\fB\-selection\fI s\fR? ?\fB\-type\fI t\fR? ?\fB\-format\fI f\fR? \fIwindow command\fR . Creates a handler for selection requests, such that \fIcommand\fR will be executed whenever selection \fIs\fR is owned by \fIwindow\fR and @@ -119,10 +122,11 @@ used to retrieve the selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .RE +.\" METHOD: own .TP -\fBselection own\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? +\fBselection own\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? .TP -\fBselection own\fR ?\fB\-command\fR \fIcommand\fR? ?\fB\-selection\fR \fIselection\fR? \fIwindow\fR +\fBselection own\fR ?\fB\-command\fI command\fR? ?\fB\-selection\fI selection\fR? \fIwindow\fR . The first form of \fBselection own\fR returns the path name of the window in this application that owns \fIselection\fR on the display @@ -142,23 +146,42 @@ some other window claims ownership of the selection away from .RE .SH WIDGET FACILITIES .PP -The \fBtext\fR, \fBentry\fR, \fBttk::entry\fR, \fBlistbox\fR, \fBspinbox\fR and \fBttk::spinbox\fR widgets have the option \fB\-exportselection\fR. If a widget has this option set to boolean \fBtrue\fR, then (in an unsafe interpreter) a selection made in the widget is automatically written to the \fBPRIMARY\fR selection. +The \fBtext\fR, \fBentry\fR, \fBttk::entry\fR, \fBlistbox\fR, \fBspinbox\fR +and \fBttk::spinbox\fR widgets have the option \fB\-exportselection\fR. If a +widget has this option set to boolean \fBtrue\fR, then (in an unsafe +interpreter) a selection made in the widget is automatically written to the +\fBPRIMARY\fR selection. .PP -A GUI event, for example \fB<<PasteSelection>>\fR, can copy the \fBPRIMARY\fR selection to certain widgets. This copy is implemented by a widget binding to the event. The binding script makes appropriate calls to the \fBselection\fR command. +A GUI event, for example \fB<<PasteSelection>>\fR, can copy the \fBPRIMARY\fR +selection to certain widgets. This copy is implemented by a widget binding to +the event. The binding script makes appropriate calls to the \fBselection\fR +command. .PP .SH PORTABILITY ISSUES .PP -On X11, the \fBPRIMARY\fR selection is a system-wide feature of the X server, allowing communication between different processes that are X11 clients. +On X11, the \fBPRIMARY\fR selection is a system-wide feature of the X server, +allowing communication between different processes that are X11 clients. .PP -On Windows, the \fBPRIMARY\fR selection is not provided by the system, but only by Tk, and so it is shared only between windows of a parent interpreter and its child interpreters. It is not shared between interpreters in different processes or different threads. Each parent interpreter has a separate \fBPRIMARY\fR selection that is shared only with its child interpreters which are not safe interpreters. +On Windows, the \fBPRIMARY\fR selection is not provided by the system, but +only by Tk, and so it is shared only between windows of a parent interpreter +and its child interpreters. It is not shared between interpreters in +different processes or different threads. Each parent interpreter has a +separate \fBPRIMARY\fR selection that is shared only with its child +interpreters which are not safe interpreters. .PP .SH SECURITY .PP -A safe interpreter cannot read from the \fBPRIMARY\fR selection because its \fBselection\fR command is hidden. For this reason the \fBPRIMARY\fR selection cannot be written to the Tk widgets of a safe interpreter. +A safe interpreter cannot read from the \fBPRIMARY\fR selection because its +\fBselection\fR command is hidden. For this reason the \fBPRIMARY\fR +selection cannot be written to the Tk widgets of a safe interpreter. .PP -A Tk widget can have its option \fB\-exportselection\fR set to boolean \fBtrue\fR, but in a safe interpreter this option has no effect: writing from the widget to the \fBPRIMARY\fR selection is disabled. +A Tk widget can have its option \fB\-exportselection\fR set to boolean +\fBtrue\fR, but in a safe interpreter this option has no effect: writing +from the widget to the \fBPRIMARY\fR selection is disabled. .PP -These are security features. A safe interpreter may run untrusted code, and it is a security risk if this untrusted code can read or write the \fBPRIMARY\fR selection used by other interpreters. +These are security features. A safe interpreter may run untrusted code, and +it is a security risk if this untrusted code can read or write the +\fBPRIMARY\fR selection used by other interpreters. .PP .SH EXAMPLES .PP @@ -39,7 +39,7 @@ and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the \fB\-async\fR option is ignored. .TP -\fB\-displayof\fR \fIpathName\fR +\fB\-displayof\fI pathName\fR Specifies that the target application's main window is on the display of the window given by \fIpathName\fR, instead of the display containing the application's main window. diff --git a/doc/spinbox.n b/doc/spinbox.n index 104ef13..d358e62 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -12,7 +12,7 @@ .SH NAME spinbox \- Create and manipulate 'spinbox' value spinner widgets .SH SYNOPSIS -\fBspinbox\fR \fIpathName \fR?\fIoptions\fR? +\fBspinbox\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightthickness \-repeatinterval \-background \-insertbackground \-selectbackground @@ -220,19 +220,19 @@ were editing the spinbox widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fB\-textvariable\fR. .PP -Also, the \fB-validate\fR option will set itself to \fBnone\fR when the -spinbox value gets changed because of adjustment of \fB-from\fR or \fB-to\fR -and the \fB-validatecommand\fR returns false. For instance +Also, the \fB\-validate\fR option will set itself to \fBnone\fR when the +spinbox value gets changed because of adjustment of \fB\-from\fR or \fB\-to\fR +and the \fB\-validatecommand\fR returns false. For instance .CS \fIspinbox pathName \-from 1 \-to 10 \-validate all \-validatecommand {return 0}\fR .CE -will in fact set the \fB-validate\fR option to \fBnone\fR because the default -value for the spinbox gets changed (due to the \fB-from\fR and \fB-to\fR +will in fact set the \fB\-validate\fR option to \fBnone\fR because the default +value for the spinbox gets changed (due to the \fB\-from\fR and \fB\-to\fR options) to a value not accepted by the validation script. .PP Moreover, forced validation is performed when invoking any spinbutton of the spinbox. If the validation script returns false in this situation, -then the \fB-validate\fR option will be automatically set to \fBnone\fR. +then the \fB\-validate\fR option will be automatically set to \fBnone\fR. .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose @@ -294,8 +294,10 @@ arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for spinbox widgets: +.\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR +. Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of @@ -304,14 +306,18 @@ 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. +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR +. Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for @@ -324,8 +330,10 @@ modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. +.\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +. Delete one or more elements of the spinbox. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last @@ -333,31 +341,45 @@ one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the spinbox's string. +.\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR +. Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. +.\" METHOD: identify .TP \fIpathName \fBidentify\fI x y\fR +. Returns the name of the window element corresponding to coordinates \fIx\fR and \fIy\fR in the spinbox. Return value is one of: \fBnone\fR, \fBbuttondown\fR, \fBbuttonup\fR, \fBentry\fR. +.\" METHOD: index .TP \fIpathName \fBindex\fI index\fR +. Returns the numerical index corresponding to \fIindex\fR. +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR +. Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. +.\" METHOD: invoke .TP \fIpathName \fBinvoke\fI element\fR +. Causes the specified element, either \fBbuttondown\fR or \fBbuttonup\fR, to be invoked, triggering the action associated with it. +.\" METHOD: scan .TP -\fIpathName \fBscan\fR \fIoption args\fR +\fIpathName \fBscan\fI option args\fR +. This command is used to implement scanning on spinboxes. It has two forms, depending on \fIoption\fR: .RS @@ -377,13 +399,16 @@ with mouse motion events in the widget, to produce the effect of dragging the spinbox at high speed through the window. The return value is an empty string. .RE +.\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR +. This command is used to adjust the selection within a spinbox. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection adjust \fIindex\fR +. Locate the end of the selection nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other @@ -395,24 +420,29 @@ selection anchor point, inclusive. Returns an empty string. .TP \fIpathName \fBselection clear\fR +. Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection element\fR ?\fIelement\fR? +. Sets or gets the currently selected element. If a spinbutton element is specified, it will be displayed depressed. .TP \fIpathName \fBselection from \fIindex\fR +. Set the selection anchor point to just before the character given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR +. Returns 1 if there is are characters selected in the spinbox, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR +. Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. @@ -420,6 +450,7 @@ If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the spinbox's selection is cleared. .TP \fIpathName \fBselection to \fIindex\fR +. If \fIindex\fR is before the anchor point, set the selection to the characters from \fIindex\fR up to but not including the anchor point. @@ -433,25 +464,32 @@ If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE +.\" METHOD: set .TP \fIpathName \fBset\fR ?\fIstring\fR? +. If \fIstring\fR is specified, the spinbox will try and set it to this value, otherwise it just returns the spinbox's string. If validation is on, it will occur when setting the string. +.\" METHOD: validate .TP \fIpathName \fBvalidate\fR +. This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. +.\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR +. This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR +. Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. @@ -462,15 +500,18 @@ These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview \fIindex\fR +. Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR +. Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then diff --git a/doc/sysnotify.n b/doc/sysnotify.n index ea1ab89..ea126b4 100644 --- a/doc/sysnotify.n +++ b/doc/sysnotify.n @@ -10,11 +10,13 @@ .SH NAME sysnotify \- Creates a notification window with a title and message. .SH SYNOPSIS -\fBtk sysnotify\fR \fItitle\fR \fImessage\fR +\fBtk sysnotify\fI title message\fR .BE .SH DESCRIPTION .PP -The \fBtk sysnotify\fR command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. +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: diff --git a/doc/systray.n b/doc/systray.n index ed89e1a..8b875d1 100644 --- a/doc/systray.n +++ b/doc/systray.n @@ -10,7 +10,7 @@ .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 +\fBtk systray create \fB\-image \fIimage\fR ?\fB\-text \fItext\fR? ?\fB\-button1 \fIcallback\fR? ?\fB\-button3 \fIcallback\fR? .sp \fBtk systray configure \fI?option? ?value option value ...?\fR .sp @@ -21,21 +21,25 @@ systray \- Creates an icon display in the platform-specific system tray. .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 - The \fBtk systray destroy\fR command removes the icon from display and +.\" 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 @@ -46,16 +50,26 @@ running instance of Wish will allow additional icons to be displayed. .SH EXAMPLE .PP Here is an example of the \fBtk systray\fR code: +.RS .CS - image create photo book -data R0lGODlhDwAPAKIAAP//////AP8AAMDAwICAgAAAAAAAAAAAACwAAAAADwAPAAADSQhA2u5ksPeKABKSCaya29d4WKgERFF0l1IMQCAKatvBJ0OTdzzXI1xMB3TBZAvATtB6NSLKleXi3OBoLqrVgc0yv+DVSEUuFxIAOw== - tk systray create -image book -text "tk systray sample" -button1 {puts "Here is the tk systray output"} -button3 {puts "here is alternate output"} +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 +.RE .PP Here is an example of modifying the \fBtk systray\fR icon: +.RS .CS - image create photo book_page -data R0lGODlhCwAPAKIAAP//////AMDAwICAgAAA/wAAAAAAAAAAACwAAAAACwAPAAADMzi6CzAugiAgDGE68aB0RXgRJBFVX0SNpQlUWfahQOvSsgrX7eZJMlQMWBEYj8iQchlKAAA7 - tk systray configure -image book_page -text "Updated sample" -button1 {puts "Different output from the tk systray"} -button3 {puts "and more different output from the tk systray"} +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 +.RE .SH PLATFORM NOTES .PP The X11 implementation is supported on a "best efforts" basis because it is @@ -63,7 +77,7 @@ 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 \fI-image\fR option must be a +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 @@ -13,10 +13,10 @@ text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets .SH SYNOPSIS .nf -\fBtext\fR \fIpathName \fR?\fIoptions\fR? -\fBtk_textCopy\fR \fIpathName\fR -\fBtk_textCut\fR \fIpathName\fR -\fBtk_textPaste\fR \fIpathName\fR +\fBtext\fI pathName \fR?\fIoptions\fR? +\fBtk_textCopy\fI pathName\fR +\fBtk_textCut\fI pathName\fR +\fBtk_textPaste\fI pathName\fR .SO \-background \-highlightthickness \-relief \-borderwidth \-insertbackground \-selectbackground @@ -493,8 +493,8 @@ contain characters because they are indented by \fB\-lmargin1\fR or \fB\-lmargin2\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the -\fB-background\fR tag option (or, if this is also unspecified, by the -\fB-background\fR widget option). +\fB\-background\fR tag option (or, if this is also unspecified, by the +\fB\-background\fR widget option). .TP \fB\-offset \fIpixels\fR . @@ -540,8 +540,8 @@ character of that display line. contain characters because they are indented by \fB\-rmargin\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color -used is specified by the \fB-background\fR tag option (or, if this is also -unspecified, by the \fB-background\fR widget option). +used is specified by the \fB\-background\fR tag option (or, if this is also +unspecified, by the \fB\-background\fR widget option). .TP \fB\-selectbackground \fIcolor\fR \fIColor\fR specifies the background color to use when displaying selected @@ -695,9 +695,9 @@ then the window is destroyed. Similarly if the text widget as a whole is deleted, then the window is destroyed. .PP Eliding an embedded window immediately after scheduling it for creation via -\fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it from being +\fIpathName \fBwindow create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded window scheduled for creation -via \fIpathName \fBwindow create \fIindex \fB-create\fR will automatically +via \fIpathName \fBwindow create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded window, the latter won't get automatically recreated. .PP @@ -774,9 +774,9 @@ containing the embedded image is deleted then that copy of the image is removed from the screen. .PP Eliding an embedded image immediately after scheduling it for creation via -\fIpathName \fBimage create \fIindex \fB-create\fR will prevent it from being +\fIpathName \fBimage create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded image scheduled for creation -via \fIpathName \fBimage create \fIindex \fB-create\fR will automatically +via \fIpathName \fBimage create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded image, the latter won't get automatically recreated. .PP @@ -978,7 +978,7 @@ In order to maintain a responsive user-experience, the text widget calculates lines metrics (line heights in pixels) asynchronously. Because of this, some commands of the text widget may return wrong results if the asynchronous calculations are not finished at the time of calling. This applies to -\fIpathName \fBcount -ypixels\fR and \fIpathName \fByview\fR. +\fIpathName \fBcount \-ypixels\fR and \fIpathName \fByview\fR. .PP Again for performance reasons, it would not be appropriate to let these commands always wait for the end of the update calculation each time they are @@ -1060,6 +1060,7 @@ operations on the widget. It has the following general form: \fIPathName\fR is the name of the command, which is the same as the text widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for text widgets: +.\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . @@ -1070,13 +1071,15 @@ and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. +.\" METHOD: cget .TP -\fIpathName \fBcget\fR \fIoption\fR +\fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. +.\" METHOD: compare .TP -\fIpathName \fBcompare\fR \fIindex1 op index2\fR +\fIpathName \fBcompare\fI index1 op index2\fR . Compares the indices given by \fIindex1\fR and \fIindex2\fR according to the relational operator given by \fIop\fR, and returns 1 if the relationship is @@ -1084,6 +1087,7 @@ satisfied and 0 if it is not. \fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. If \fIop\fR is == then 1 is returned if the two indices refer to the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR refers to an earlier character in the text than \fIindex2\fR, and so on. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . @@ -1097,6 +1101,7 @@ specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. +.\" METHOD: count .TP \fIpathName \fBcount\fR ?\fIoptions\fR? \fIindex1 index2\fR . @@ -1160,6 +1165,7 @@ supplied. For example .QW ".text count \-xpixels \-ypixels 1.3 4.5" is perfectly valid and will return a list of two elements. .RE +.\" METHOD: debug .TP \fIpathName \fBdebug \fR?\fIboolean\fR? . @@ -1180,6 +1186,7 @@ global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. .RE +.\" METHOD: delete .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? . @@ -1207,6 +1214,7 @@ side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text outside the given ranges due to text shifted during deletion. +.\" METHOD: dlineinfo .TP \fIpathName \fBdlineinfo \fIindex\fR . @@ -1223,6 +1231,7 @@ width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing \fIindex\fR is not visible on the screen then the return value is an empty list. +.\" METHOD: dump .TP \fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? . @@ -1283,6 +1292,7 @@ window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. .RE +.\" METHOD: edit .TP \fIpathName \fBedit \fIoption \fR?\fIarg ...\fR? . @@ -1333,6 +1343,7 @@ edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE +.\" METHOD: get .TP \fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? . @@ -1351,6 +1362,7 @@ order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. +.\" METHOD: image .TP \fIpathName \fBimage \fIoption \fR?\fIarg ...\fR? . @@ -1393,12 +1405,14 @@ identifier returned. Returns a list whose elements are the names of all image instances currently embedded in \fIwindow\fR. .RE +.\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR where \fIline\fR is the line number and \fIchar\fR is the character number. \fIIndex\fR may have any of the forms described under \fBINDICES\fR above. +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? . @@ -1416,6 +1430,7 @@ of the tags present around the insertion point. If multiple effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. +.\" METHOD: mark .TP \fIpathName \fBmark \fIoption \fR?\fIarg ...\fR? . @@ -1446,7 +1461,7 @@ position if there are multiple marks at the same index. These semantics mean that the \fBmark next\fR operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the \fIpathName \fBdump\fR operation. If a mark has been set to the special -\fBend\fR index, then it appears to be \fIafter\fR \fBend\fR with respect to +\fBend\fR index, then it appears to be \fIafter \fBend\fR with respect to the \fIpathName \fBmark next\fR operation. An empty string is returned if there are no marks after \fIindex\fR. .TP @@ -1478,6 +1493,7 @@ calls to .QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE +.\" METHOD: peer .TP \fIpathName \fBpeer \fIoption args\fR . @@ -1497,11 +1513,15 @@ be overridden with the standard configuration options. Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. .RE +.\" METHOD: pendingsync .TP \fIpathName \fBpendingsync\fR +. Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. +.\" METHOD: replace .TP -\fIpathName \fBreplace\fR \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR? +\fIpathName \fBreplace\fI index1 index2 chars\fR ?\fItagList chars tagList ...\fR? +. Replaces the range of characters between \fIindex1\fR and \fIindex2\fR with the given characters and tags. See the section on \fIpathName \fBinsert\fR for an explanation of the handling of the \fItagList...\fR @@ -1516,6 +1536,7 @@ the window or movement of insertion cursor occurs. In addition the undo/redo stack are correctly modified, if undo operations are active in the text widget. The command returns an empty string. .RE +.\" METHOD: scan .TP \fIpathName \fBscan \fIoption args\fR . @@ -1539,6 +1560,7 @@ coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string. .RE +.\" METHOD: search .TP \fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? . @@ -1670,6 +1692,7 @@ no wrap-around will occur. This means that, for example, if the search is \fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of minor limitations of the \fIpathName \fBsearch\fR command. .RE +.\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . @@ -1679,23 +1702,28 @@ nothing. If \fIindex\fR is a short distance out of view, the command adjusts the view just enough to make \fIindex\fR visible at the edge of the window. If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the window. +.\" METHOD: sync .TP -\fIpathName \fBsync\fR ?\fB-command \fIcommand\fR? +\fIpathName \fBsync\fR ?\fB\-command \fIcommand\fR? +. Controls the synchronization of the view of the text widget. .RS .TP \fIpathName \fBsync\fR +. Immediately brings the line metrics up-to-date by forcing computation of any outdated line heights. The command returns immediately if there is no such outdated line heights, otherwise it returns only at the end of the computation. The command returns an empty string. .TP -\fIpathName \fBsync -command \fIcommand\fR +\fIpathName \fBsync \-command \fIcommand\fR +. Schedules \fIcommand\fR to be executed (by the event loop) exactly once as soon as all line heights are up-to-date. If there are no pending line metrics calculations, the scheduling is immediate. The command returns the empty string. \fBbgerror\fR is called on \fIcommand\fR failure. .RE +.\" METHOD: tag .TP \fIpathName \fBtag \fIoption \fR?\fIarg ...\fR? . @@ -1837,7 +1865,7 @@ of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the beginning of the text. .TP -\fIpathName\fB tag raise \fItagName \fR?\fIaboveThis\fR? +\fIpathName \fBtag raise \fItagName \fR?\fIaboveThis\fR? . Changes the priority of tag \fItagName\fR so that it is just higher in priority than the tag whose name is \fIaboveThis\fR. If \fIaboveThis\fR is @@ -1865,6 +1893,7 @@ characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. This command returns an empty string. .RE +.\" METHOD: window .TP \fIpathName \fBwindow \fIoption \fR?\fIarg ...\fR? . @@ -1905,6 +1934,7 @@ information on the options that are supported. Returns an empty string. Returns a list whose elements are the names of all windows currently embedded in \fIwindow\fR. .RE +.\" METHOD: xview .TP \fIpathName \fBxview \fIoption args\fR . @@ -1950,6 +1980,7 @@ right by \fInumber\fR average-width characters on the display. If \fInumber\fR i negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE +.\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . @@ -12,7 +12,7 @@ .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS -\fBtk\fR \fIoption \fR?\fIarg ...\fR? +\fBtk\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -23,6 +23,7 @@ application as a whole, or to a screen or display, rather than to a particular window. The command can take any of a number of different forms depending on the \fIoption\fR argument. The legal forms are: +.\" METHOD: appname .TP \fBtk appname \fR?\fInewName\fR? . @@ -44,6 +45,7 @@ be able to find some options for the application. If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. +.\" METHOD: busy .TP \fBtk busy \fIsubcommand\fR ... . @@ -51,6 +53,7 @@ This command controls the marking of window hierarchies as .QW busy , rendering them non-interactive while some other operation is proceeding. For more details see the \fBbusy\fR manual page. +.\" METHOD: caret .TP \fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . @@ -63,6 +66,7 @@ the last values used for setting the caret are return in option-value pair format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and \fB\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. +.\" METHOD: inactive .TP \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? . @@ -81,10 +85,13 @@ the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. .RE +.\" METHOD: fontchooser .TP \fBtk fontchooser \fIsubcommand\fR ... +. Controls the Tk font selection dialog. For more details see the \fBfontchooser\fR manual page. +.\" METHOD: print .TP \fBtk print \fIwindow\fR . @@ -92,6 +99,7 @@ The \fBtk print\fR command posts a dialog that allows users to print output from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using platform-native APIs and dialogs where available. For more details see the \fBprint\fR manual page. +.\" METHOD: scaling .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . @@ -117,6 +125,7 @@ after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE +.\" METHOD: sysnotify .TP \fBtk sysnotify \fP \fItitle\fP? \fImessage\fP? . @@ -124,11 +133,13 @@ The \fBtk sysnotify\fP command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. For more details see the \fBsysnotify\fR manual page. +.\" METHOD: systray .TP \fBtk systray create\fP \fIsubcommand...\fP . The \fBtk systray\fP command creates an icon in the platform-specific tray. For more details see the \fBsystray\fR manual page. +.\" METHOD: useinputmethods .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . @@ -139,6 +150,7 @@ feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current state is returned. This is turned on by default for the main display. +.\" METHOD: windowingsystem .TP \fBtk windowingsystem\fR . diff --git a/doc/tk_mac.n b/doc/tk_mac.n index 2ce1374..9ea8f85 100644 --- a/doc/tk_mac.n +++ b/doc/tk_mac.n @@ -35,7 +35,6 @@ tk::mac \- Access Mac-Specific Functionality on OS X from Tk \fB::tk::mac::antialiasedtext \fInumber\fR \fB::tk::mac::useThemedToplevel \fIboolean\fR - \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR .fi .BE @@ -209,8 +208,6 @@ scheme the developer wants to support. . Returns the current applications's file path. .TP - - .SH "ADDITIONAL DIALOGS" .PP The Aqua/Mac OS X defines additional dialogs that applications should diff --git a/doc/tkwait.n b/doc/tkwait.n index 82d51ba..42d5ea6 100644 --- a/doc/tkwait.n +++ b/doc/tkwait.n @@ -23,15 +23,18 @@ tkwait \- Wait for variable to change or window to be destroyed The \fBtkwait\fR command waits for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. +.\" METHOD: variable If the first argument is \fBvariable\fR (or any abbreviation of it) then the second argument is the name of a global variable and the command waits for that variable to be modified. +.\" METHOD: visibility If the first argument is \fBvisibility\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for a change in its visibility state (as indicated by the arrival of a VisibilityNotify event). This form is typically used to wait for a newly-created window to appear on the screen before taking some action. +.\" METHOD: window If the first argument is \fBwindow\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for that window to be destroyed. diff --git a/doc/toplevel.n b/doc/toplevel.n index e946248..d37faa2 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -12,7 +12,7 @@ .SH NAME toplevel \- Create and manipulate 'toplevel' main and popup window widgets .SH SYNOPSIS -\fBtoplevel\fR \fIpathName \fR?\fIoptions\fR? +\fBtoplevel\fI pathName \fR?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief @@ -148,6 +148,7 @@ operations on the widget. It has the following general form: the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for toplevel widgets: +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -155,6 +156,7 @@ Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . diff --git a/doc/ttk_button.n b/doc/ttk_button.n index 896432f..cd54add 100644 --- a/doc/ttk_button.n +++ b/doc/ttk_button.n @@ -10,7 +10,7 @@ .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, @@ -52,8 +52,10 @@ In addition to the standard \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 diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n index d78b7fc..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. @@ -41,8 +41,10 @@ In addition to the standard \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 bd41bf1..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 @@ -60,8 +60,10 @@ In addition to the standard \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 @@ -70,11 +72,15 @@ 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{}\fR if the current value does not appear in the list. +.\" METHOD: get .TP \fIpathName \fBget\fR +. Returns the current value of the combobox. +.\" METHOD: set .TP -\fIpathName \fBset\fR \fIvalue\fR +\fIpathName \fBset\fI value\fR +. Sets the value of the combobox to \fIvalue\fR. .PP The combobox widget also supports the following \fBttk::entry\fR diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index e71bd01..7f7b202 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 @@ -147,8 +147,10 @@ In addition to the standard \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 @@ -157,8 +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. +.\" 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 @@ -166,44 +170,59 @@ 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. +.\" 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. +.\" 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 +.\" 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. diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n index 413bb09..20f642b 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 diff --git a/doc/ttk_image.n b/doc/ttk_image.n index 34dbabb..8bc1b9e 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 @@ -26,7 +26,7 @@ in a particular state or combination of states. .PP Valid \fIoptions\fR are: .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, @@ -42,7 +42,7 @@ See \fBIMAGE STRETCHING\fR, below. Specifies a minimum height for the element. If less than zero, the base image's height is used as a default. .TP -\fB\-padding\fR \fIpadding\fR +\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. @@ -55,7 +55,7 @@ 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. .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 , diff --git a/doc/ttk_label.n b/doc/ttk_label.n index 54c0f47..0d7d766 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 diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n index 593d96c..8649dae 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 diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n index b9b716f..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 diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index 84b6495..f93f234 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 @@ -112,57 +112,73 @@ In addition to the standard \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. +.\" 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. +.\" 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. +.\" 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. @@ -170,8 +186,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" diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index a6a809b..adf92bb 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 @@ -54,16 +54,22 @@ In addition to the standard \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. @@ -76,28 +82,36 @@ Returns the name of the element at the specified location. \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 diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n index 0673ca6..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 @@ -20,10 +20,10 @@ 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 +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 +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 \-anchor \-class \-cursor @@ -71,18 +71,24 @@ In addition to the standard \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). +.\" 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 45be7df..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 @@ -41,8 +41,10 @@ In addition to the standard \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 c0c351b..c9f0298 100644 --- a/doc/ttk_scale.n +++ b/doc/ttk_scale.n @@ -56,21 +56,27 @@ In addition to the standard \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. +.\" METHOD: see .TP \fIpathName \fBset \fIvalue\fR +. 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. .SH "INTERNAL COMMANDS" .PP +.\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? +. Get the coordinates corresponding to \fIvalue\fR, or the coordinates corresponding to the current value of the \fB\-value\fR option if \fIvalue\fR is omitted. diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index bd38a5c..321d101 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 @@ -52,12 +52,16 @@ In addition to the standard \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. +.\" 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. @@ -66,8 +70,10 @@ Specifies the visible range to be displayed. .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, @@ -77,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 @@ -99,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. @@ -108,6 +117,7 @@ refers to a point one-third of the way through the document, and so on. .TP \fIprefix \fBscroll \fInumber \fBpages\fR +. The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there @@ -117,6 +127,7 @@ 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. @@ -134,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 5331f3e..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 diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index fda8d07..1f63821 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 diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n index 49dc8ff..3b038f0 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 @@ -66,11 +66,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 diff --git a/doc/ttk_style.n b/doc/ttk_style.n index 7763336..dcd5567 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 @@ -33,19 +33,23 @@ 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. 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 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\fR \fIargs\fR +\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 @@ -54,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, @@ -77,22 +87,26 @@ 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 (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. 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 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\fR \fIargs\fR +\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. @@ -100,19 +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. @@ -129,13 +147,13 @@ 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. .TP \fB\-children { \fIsublayout...\fB }\fR Specifies a list of elements to place inside the element. .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. @@ -155,7 +173,7 @@ 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 diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index c819093..d2ef877 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -111,8 +111,10 @@ In addition to the standard \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. @@ -122,8 +124,10 @@ 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. @@ -135,31 +139,41 @@ 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\fR \fIlastCell\fR +\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 +. +Add \fIcellList\fR to the cell selection. .TP -\fIpathname \fBcellselection add \fIfirstCell\fR \fIlastCell\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 +. +Remove \fIcellList\fR from the cell selection. .TP -\fIpathname \fBcellselection remove \fIfirstCell\fR \fIlastCell\fR +\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\fR \fIlastCell\fR +\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 @@ -171,8 +185,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. @@ -183,48 +199,58 @@ The following options may be set on each column: .RS .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. -The tree column has -id \fB#0\fR. +returns the data column associated with display column \fIn\fR. +The tree column has \fB\-id #0\fR. .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. .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 heading column separator. Default is 20 pixels. .TP \fB\-separator \fIboolean\fR +. Specifies whether or not a column separator should be drawn to the right of the column. Default is false. .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 heading column separator. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. By default columns are stretchable. .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 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 +.\" 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 @@ -232,6 +258,7 @@ 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? . @@ -239,38 +266,51 @@ 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 .TP \fB\-text \fItext\fR +. The text to display in the column heading. .TP \fB\-image \fIimageName\fR +. Specifies an image to display to the right of the column heading. .TP \fB\-anchor \fIanchor\fR +. Specifies how the heading text should be aligned. One of the standard Tk anchor values. .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. @@ -296,30 +336,39 @@ 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 @@ -339,8 +388,10 @@ Otherwise, a new unique identifier is generated. newly created item. See \fBITEM OPTIONS\fR for the list of available options. .RE +.\" 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. @@ -348,8 +399,10 @@ 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 @@ -358,26 +411,36 @@ If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. .RE +.\" 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. @@ -385,27 +448,35 @@ 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. +.\" 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 @@ -415,11 +486,13 @@ 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 @@ -435,31 +508,36 @@ 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 \fIsubcmd...\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. @@ -471,21 +549,25 @@ 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 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, @@ -500,9 +582,9 @@ 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. +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. +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. diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index af63c39..52b18c9 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,7 +21,7 @@ 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). diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index 7605260..e286eb0 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -173,12 +173,16 @@ setting it changes the widget state, but the \fBstate\fR widget command does not affect the \fB\-state\fR option. .SH COMMANDS +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR +. Returns the current value of the configuration option given by \fIoption\fR. +.\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Query or modify the configuration options of the widget. If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) @@ -192,16 +196,20 @@ and current value. .\" Note: Ttk widgets don't use TK_OPTION_SYNONYM. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR. +.\" METHOD: identify .TP \fIpathName \fBidentify element \fIx y\fR +. Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or an empty string if the point does not lie within any element. \fIx\fR and \fIy\fR are pixel coordinates relative to the widget. Some widgets accept other \fBidentify\fR subcommands described in these widgets documentation. +.\" METHOD: instate .TP \fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +. Test the widget's state. If \fIscript\fR is not specified, returns 1 if the widget state matches \fIstatespec\fR and 0 otherwise. @@ -209,8 +217,10 @@ If \fIscript\fR is specified, equivalent to .CS if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR .CE +.\" METHOD: state .TP \fIpathName \fBstate\fR ?\fIstateSpec\fR? +. Modify or inquire widget state. If \fIstateSpec\fR is present, sets the widget state: for each flag in \fIstateSpec\fR, sets the corresponding flag @@ -225,17 +235,22 @@ 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 +. This command is used to query and change the horizontal position of the content in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR +. Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. @@ -245,16 +260,19 @@ in the window, and 40% of the content is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP -\fIpathName \fBxview\fR \fIindex\fR +\fIpathName \fBxview\fI index\fR +. Adjusts the view in the window so that the content given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR +. Adjusts the view in the window so that the character \fIfraction\fR of the way through the content appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR +. This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then @@ -269,14 +287,17 @@ 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 \fIpathName \fByview \fIargs\fR +. This command is used to query and change the vertical position of the content in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR +. Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. @@ -286,16 +307,19 @@ in the window, and 40% of the content is off-screen to the bottom. These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP -\fIpathName \fByview\fR \fIindex\fR +\fIpathName \fByview\fI index\fR +. Adjusts the view in the window so that the content given by \fIindex\fR is displayed at the top edge of the window. .TP \fIpathName \fByview moveto\fI fraction\fR +. Adjusts the view in the window so that the item \fIfraction\fR of the way through the content appears at the top edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fByview scroll \fInumber what\fR +. This command shifts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then diff --git a/doc/winfo.n b/doc/winfo.n index 5651f2c..136eaf7 100644 --- a/doc/winfo.n +++ b/doc/winfo.n @@ -12,13 +12,14 @@ .SH NAME winfo \- Return window-related information .SH SYNOPSIS -\fBwinfo\fR \fIoption \fR?\fIarg ...\fR? +\fBwinfo\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBwinfo\fR command is used to retrieve information about windows managed by Tk. It can take any of a number of different forms, depending on the \fIoption\fR argument. The legal forms are: +.\" METHOD: atom .TP \fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR Returns a decimal string giving the integer identifier for the @@ -27,6 +28,7 @@ atom whose name is \fIname\fR. If no atom exists with the name If the \fB\-displayof\fR option is given then the atom is looked up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. +.\" METHOD: atomname .TP \fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR Returns the textual name for the atom whose integer identifier is @@ -36,10 +38,12 @@ up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. This command is the inverse of the \fBwinfo atom\fR command. It generates an error if no such atom exists. +.\" METHOD: cells .TP \fBwinfo cells \fIwindow\fR Returns a decimal string giving the number of cells in the color map for \fIwindow\fR. +.\" METHOD: children .TP \fBwinfo children \fIwindow\fR Returns a list containing the path names of all the children @@ -48,9 +52,11 @@ of their logical parents. The list is in stacking order, with the lowest window first, except for Top-level windows which are not returned in stacking order. Use the \fBwm stackorder\fR command to query the stacking order of Top-level windows. +.\" METHOD: class .TP \fBwinfo class \fIwindow\fR Returns the class name for \fIwindow\fR. +.\" METHOD: colormapfull .TP \fBwinfo colormapfull \fIwindow\fR Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 @@ -60,6 +66,7 @@ to be full if the last attempt to allocate a new color on that window failed and this application has not freed any colors in the colormap since the failed allocation. +.\" METHOD: containing .TP \fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR Returns the path name for the window containing the point given @@ -79,16 +86,19 @@ or border of its highest containing toplevel in this application. In selecting the containing window, children are given higher priority than parents and among siblings the highest one in the stacking order is chosen. +.\" METHOD: depth .TP \fBwinfo depth \fIwindow\fR Returns a decimal string giving the depth of \fIwindow\fR (number of bits per pixel). +.\" METHOD: exists .TP \fBwinfo exists \fIwindow\fR Returns 1 if there exists a window named \fIwindow\fR, 0 if no such window exists. +.\" METHOD: fpixels .TP -\fBwinfo fpixels \fIwindow\fR \fInumber\fR +\fBwinfo fpixels \fIwindow number\fR Returns a floating-point value giving the number of pixels in \fIwindow\fR corresponding to the distance given by \fInumber\fR. \fINumber\fR may be specified in any of the forms acceptable @@ -98,11 +108,13 @@ or .QW 1i . The return value may be fractional; for an integer value, use \fBwinfo pixels\fR. +.\" METHOD: geometry .TP \fBwinfo geometry \fIwindow\fR Returns the geometry for \fIwindow\fR, in the form \fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are in pixels. +.\" METHOD: height .TP \fBwinfo height \fIwindow\fR Returns a decimal string giving \fIwindow\fR's height in pixels. @@ -113,12 +125,14 @@ If you need the true height immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, or use \fBwinfo reqheight\fR to get the window's requested height instead of its actual height. +.\" METHOD: id .TP \fBwinfo id \fIwindow\fR Returns a hexadecimal string giving a low-level platform-specific identifier for \fIwindow\fR. On Unix platforms, this is the X window identifier. Under Windows, this is the Windows HWND. On the Macintosh the value has no meaning outside Tk. +.\" METHOD: interps .TP \fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? Returns a list whose members are the names of all Tcl interpreters @@ -126,11 +140,14 @@ Returns a list whose members are the names of all Tcl interpreters If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. +.\" METHOD: ismapped .TP \fBwinfo ismapped \fIwindow\fR Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. +.\" METHOD: manager .TP \fBwinfo manager \fIwindow\fR +. Returns the name of the geometry manager currently responsible for \fIwindow\fR, or an empty string if \fIwindow\fR is not managed by any geometry manager. @@ -138,15 +155,18 @@ The name is usually the name of the Tcl command for the geometry manager, such as \fBpack\fR or \fBplace\fR. If the geometry manager is a widget, such as canvases or text, the name is the widget's class command, such as \fBcanvas\fR. +.\" METHOD: name .TP \fBwinfo name \fIwindow\fR Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed to its full path name). The command \fBwinfo name .\fR will return the name of the application. +.\" METHOD: parent .TP \fBwinfo parent \fIwindow\fR Returns the path name of \fIwindow\fR's parent, or an empty string if \fIwindow\fR is the main window of the application. +.\" METHOD: pathname .TP \fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR Returns the path name of the window whose X identifier is \fIid\fR. @@ -155,8 +175,9 @@ correspond to a window in the invoking application. If the \fB\-displayof\fR option is given then the identifier is looked up on the display of \fIwindow\fR; otherwise it is looked up on the display of the application's main window. +.\" METHOD: pixels .TP -\fBwinfo pixels \fIwindow\fR \fInumber\fR +\fBwinfo pixels \fIwindow number\fR Returns the number of pixels in \fIwindow\fR corresponding to the distance given by \fInumber\fR. \fINumber\fR may be specified in any of the forms acceptable @@ -166,6 +187,7 @@ or .QW 1i . The result is rounded to the nearest integer value; for a fractional result, use \fBwinfo fpixels\fR. +.\" METHOD: pointerx .TP \fBwinfo pointerx \fIwindow\fR If the mouse pointer is on the same screen as \fIwindow\fR, returns the @@ -174,6 +196,7 @@ If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. +.\" METHOD: pointerxy .TP \fBwinfo pointerxy \fIwindow\fR If the mouse pointer is on the same screen as \fIwindow\fR, returns a list @@ -183,6 +206,7 @@ If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then both of the returned coordinates are \-1. +.\" METHOD: pointery .TP \fBwinfo pointery \fIwindow\fR If the mouse pointer is on the same screen as \fIwindow\fR, returns the @@ -191,16 +215,19 @@ If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as \fIwindow\fR then -1 is returned. +.\" METHOD: reqheight .TP \fBwinfo reqheight \fIwindow\fR Returns a decimal string giving \fIwindow\fR's requested height, in pixels. This is the value used by \fIwindow\fR's geometry manager to compute its geometry. +.\" METHOD: reqwidth .TP \fBwinfo reqwidth \fIwindow\fR Returns a decimal string giving \fIwindow\fR's requested width, in pixels. This is the value used by \fIwindow\fR's geometry manager to compute its geometry. +.\" METHOD: rgb .TP \fBwinfo rgb \fIwindow color\fR Returns a list containing three decimal values in the range 0 to @@ -209,52 +236,63 @@ red, green, and blue intensities that correspond to \fIcolor\fR in the window given by \fIwindow\fR. \fIColor\fR may be specified in any of the forms acceptable for a color option. +.\" METHOD: rootx .TP \fBwinfo rootx \fIwindow\fR Returns a decimal string giving the x-coordinate, in the root window of the screen, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). +.\" METHOD: rooty .TP \fBwinfo rooty \fIwindow\fR Returns a decimal string giving the y-coordinate, in the root window of the screen, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). +.\" METHOD: screen .TP \fBwinfo screen \fIwindow\fR Returns the name of the screen associated with \fIwindow\fR, in the form \fIdisplayName\fR.\fIscreenIndex\fR. +.\" METHOD: screencells .TP \fBwinfo screencells \fIwindow\fR Returns a decimal string giving the number of cells in the default color map for \fIwindow\fR's screen. +.\" METHOD: screendepth .TP \fBwinfo screendepth \fIwindow\fR Returns a decimal string giving the depth of the root window of \fIwindow\fR's screen (number of bits per pixel). +.\" METHOD: screenheight .TP \fBwinfo screenheight \fIwindow\fR Returns a decimal string giving the height of \fIwindow\fR's screen, in pixels. +.\" METHOD: screenmmheight .TP \fBwinfo screenmmheight \fIwindow\fR Returns a decimal string giving the height of \fIwindow\fR's screen, in millimeters. +.\" METHOD: screenmmwidth .TP \fBwinfo screenmmwidth \fIwindow\fR Returns a decimal string giving the width of \fIwindow\fR's screen, in millimeters. +.\" METHOD: screenvisual .TP \fBwinfo screenvisual \fIwindow\fR Returns one of the following strings to indicate the default visual class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or \fBtruecolor\fR. +.\" METHOD: screenwidth .TP \fBwinfo screenwidth \fIwindow\fR Returns a decimal string giving the width of \fIwindow\fR's screen, in pixels. +.\" METHOD: server .TP \fBwinfo server \fIwindow\fR Returns a string containing information about the server for @@ -266,25 +304,30 @@ where \fImajor\fR and \fIminor\fR are the version and revision numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR is the name of the vendor for the server, and \fIvendorRelease\fR is an integer release number provided by the server. +.\" METHOD: toplevel .TP \fBwinfo toplevel \fIwindow\fR Returns the path name of the top-of-hierarchy window containing \fIwindow\fR. In standard Tk this will always be a \fBtoplevel\fR widget, but extensions may create other kinds of top-of-hierarchy widgets. +.\" METHOD: viewable .TP \fBwinfo viewable \fIwindow\fR Returns 1 if \fIwindow\fR and all of its ancestors up through the nearest toplevel window are mapped. Returns 0 if any of these windows are not mapped. +.\" METHOD: visual .TP \fBwinfo visual \fIwindow\fR Returns one of the following strings to indicate the visual class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or \fBtruecolor\fR. +.\" METHOD: visualid .TP \fBwinfo visualid \fIwindow\fR Returns the X identifier for the visual for \fIwindow\fR. +.\" METHOD: visualsavailable .TP \fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? Returns a list whose elements describe the visuals available for @@ -294,26 +337,31 @@ The class has the same form as returned by \fBwinfo visual\fR. The depth gives the number of bits per pixel in the visual. In addition, if the \fBincludeids\fR argument is provided, then the depth is followed by the X identifier for the visual. +.\" METHOD: vrootheight .TP \fBwinfo vrootheight \fIwindow\fR Returns the height of the virtual root window associated with \fIwindow\fR if there is one; otherwise returns the height of \fIwindow\fR's screen. +.\" METHOD: vrootwidth .TP \fBwinfo vrootwidth \fIwindow\fR Returns the width of the virtual root window associated with \fIwindow\fR if there is one; otherwise returns the width of \fIwindow\fR's screen. +.\" METHOD: vrootx .TP \fBwinfo vrootx \fIwindow\fR Returns the x-offset of the virtual root window associated with \fIwindow\fR, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for \fIwindow\fR. +.\" METHOD: vrooty .TP \fBwinfo vrooty \fIwindow\fR Returns the y-offset of the virtual root window associated with \fIwindow\fR, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for \fIwindow\fR. +.\" METHOD: width .TP \fBwinfo width \fIwindow\fR Returns a decimal string giving \fIwindow\fR's width in pixels. @@ -324,12 +372,14 @@ If you need the true width immediately after creating a widget, invoke \fBupdate\fR to force the geometry manager to arrange it, or use \fBwinfo reqwidth\fR to get the window's requested width instead of its actual width. +.\" METHOD: x .TP \fBwinfo x \fIwindow\fR Returns a decimal string giving the x-coordinate, in \fIwindow\fR's parent, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). +.\" METHOD: y .TP \fBwinfo y \fIwindow\fR Returns a decimal string giving the y-coordinate, in \fIwindow\fR's @@ -12,7 +12,7 @@ .SH NAME wm \- Communicate with window manager .SH SYNOPSIS -\fBwm\fR \fIoption window \fR?\fIargs\fR? +\fBwm\fI option window \fR?\fIargs\fR? .BE .SH DESCRIPTION .PP @@ -25,6 +25,7 @@ additional argument, \fIwindow\fR, which must be the path name of a top-level window. .PP The legal forms for the \fBwm\fR command are: +.\" METHOD: aspect .TP \fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? . @@ -42,6 +43,7 @@ a Tcl list containing four elements, which are the current values of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR (if no aspect restrictions are in effect, then an empty string is returned). +.\" METHOD: attributes .TP \fBwm attributes \fIwindow\fR .TP @@ -276,6 +278,7 @@ the value of an attribute returns the current state, which will not be the same as the value most recently set if the window manager has not yet processed the request or if it does not support the attribute. .RE +.\" METHOD: client .TP \fBwm client \fIwindow\fR ?\fIname\fR? . @@ -289,6 +292,7 @@ If \fIname\fR is not specified, the command returns the last name set in a \fBwm client\fR command for \fIwindow\fR. If \fIname\fR is specified as an empty string, the command deletes the \fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. +.\" METHOD: colormapwindows .TP \fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? . @@ -320,6 +324,7 @@ itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the \fBWM_COLORMAP_WINDOWS\fR property. .RE +.\" METHOD: command .TP \fBwm command \fIwindow\fR ?\fIvalue\fR? . @@ -332,6 +337,7 @@ If \fIvalue\fR is not specified then the command returns the last value set in a \fBwm command\fR command for \fIwindow\fR. If \fIvalue\fR is specified as an empty string, the command deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. +.\" METHOD: deiconify .TP \fBwm deiconify \fIwindow\fR . @@ -342,6 +348,7 @@ that when the window is first mapped it will be displayed in de-iconified form. On Windows, a deiconified window will also be raised and be given the focus (made the active window). Returns an empty string. +.\" METHOD: focusmodel .TP \fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? . @@ -362,6 +369,7 @@ the application may re-assign the focus among \fIwindow\fR's descendants. The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command assumes a passive model of focusing. .RE +.\" METHOD: forget .TP \fBwm forget \fIwindow\fR . @@ -370,6 +378,7 @@ be managed by \fBwm\fR. Windows created with the \fBtoplevel\fR command will be treated like \fBframe\fR windows once they are no longer managed by \fBwm\fR, however, the \fB\-menu\fR configuration will be remembered and the menus will return once the widget is managed again. +.\" METHOD: frame .TP \fBwm frame \fIwindow\fR . @@ -379,6 +388,7 @@ identifier for the outermost frame that contains \fIwindow\fR (the window whose parent is the root or virtual root). If \fIwindow\fR has not been reparented by the window manager then the command returns the platform specific window identifier for \fIwindow\fR. +.\" METHOD: geometry .TP \fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? . @@ -423,6 +433,7 @@ reflect the addition of decorative elements to \fIwindow\fR such as title bars, and window managers are not required to precisely follow the requests made through this command. .RE +.\" METHOD: grid .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? . @@ -459,6 +470,7 @@ Note: this command should not be needed very often, since the \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option provide easier access to the same functionality. .RE +.\" METHOD: group .TP \fBwm group \fIwindow\fR ?\fIpathName\fR? . @@ -470,8 +482,9 @@ remove \fIwindow\fR from any group association. If \fIpathName\fR is specified then the command returns an empty string; otherwise it returns the path name of \fIwindow\fR's current group leader, or an empty string if \fIwindow\fR is not part of any group. +.\" METHOD: iconbadge .TP -\fBwm iconbadge \fIwindow\fR \fIbadge\fR +\fBwm iconbadge \fIwindow badge\fR . Sets a badge for the icon of the \fIwindow\fR. The badge can be a positive integer number, for instance the number of new or unread messages, or @@ -501,6 +514,7 @@ Badge display on macOS is configured in the system preferences. App panel display behavior on X11 will depend on the window manager and/or desktop environment. .RE +.\" METHOD: iconbitmap .TP \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? . @@ -530,12 +544,14 @@ first test if the file contains an icon, then if it has an assigned icon, and finally, if that fails, test for a bitmap. .RE +.\" METHOD: iconify .TP \fBwm iconify \fIwindow\fR . Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped. +.\" METHOD: iconmask .TP \fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? . @@ -551,6 +567,7 @@ a bitmap of all ones). If \fIbitmap\fR is specified then the command returns an empty string. Otherwise it returns the name of the current icon mask associated with \fIwindow\fR, or an empty string if no mask is in effect. +.\" METHOD: iconname .TP \fBwm iconname \fIwindow\fR ?\fInewName\fR? . @@ -562,6 +579,7 @@ then the command returns the current icon name for \fIwindow\fR, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the \fBwm title\fR command). +.\" METHOD: iconphoto .TP \fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR? . @@ -592,6 +610,7 @@ parameters as support for multiple sizes/resolutions on macOS is outside Tk's scope. Developers should use the largest icon they can support (preferably 512 pixels) to ensure smooth rendering on the Mac. .RE +.\" METHOD: iconposition .TP \fBwm iconposition \fIwindow\fR ?\fIx y\fR? . @@ -602,6 +621,7 @@ specified as empty strings then any existing icon position hint is cancelled. If neither \fIx\fR nor \fIy\fR is specified, then the command returns a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned). +.\" METHOD: iconwindow .TP \fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? . @@ -620,6 +640,7 @@ an icon window; this is needed in order to allow window managers to .QW own those events. Note: not all window managers support the notion of an icon window. +.\" METHOD: manage .TP \fBwm manage \fIwidget\fR . @@ -629,6 +650,7 @@ window will be decorated with the window managers title bar, etc. Only with this command. Attempting to pass any other widget type will raise an error. Attempting to manage a \fItoplevel\fR widget is benign and achieves nothing. See also \fBGEOMETRY MANAGEMENT\fR. +.\" METHOD: maxsize .TP \fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? . @@ -644,6 +666,7 @@ it returns a Tcl list with two elements, which are the maximum width and height currently in effect. The maximum size defaults to the size of the screen. See the sections on geometry management below for more information. +.\" METHOD: minsize .TP \fBwm minsize \fIwindow\fR ?\fIwidth height\fR? . @@ -659,6 +682,7 @@ it returns a Tcl list with two elements, which are the minimum width and height currently in effect. The minimum size defaults to one pixel in each dimension. See the sections on geometry management below for more information. +.\" METHOD: overrideredirect .TP \fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? . @@ -679,6 +703,7 @@ when the window is first mapped or when mapped after the state is changed from withdrawn to normal. Some, but not all, platforms will take notice at additional times. .RE +.\" METHOD: positionfrom .TP \fBwm positionfrom \fIwindow\fR ?\fIwho\fR? . @@ -700,6 +725,7 @@ as equivalent to \fBprogram\fR. Tk will automatically set the position source to \fBuser\fR when a \fBwm geometry\fR command is invoked, unless the source has been set explicitly to \fBprogram\fR. +.\" METHOD: protocol .TP \fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? . @@ -747,6 +773,7 @@ Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the \fBwm protocol\fR command returns a list of all of the protocols for which handlers are currently defined for \fIwindow\fR. .RE +.\" METHOD: resizable .TP \fBwm resizable \fIwindow\fR ?\fIwidth height\fR? . @@ -763,6 +790,7 @@ If resizing is disabled, then the window's size will be the size from the most recent interactive resize or \fBwm geometry\fR command. If there has been no such operation then the window's natural size will be used. +.\" METHOD: sizefrom .TP \fBwm sizefrom \fIwindow\fR ?\fIwho\fR? . @@ -781,6 +809,7 @@ source of the window's current size, or an empty string if no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. +.\" METHOD: stackorder .TP \fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? . @@ -795,6 +824,7 @@ When two window arguments separated by either \fBisabove\fR or \fBisbelow\fR are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. +.\" METHOD: state .TP \fBwm state \fIwindow\fR ?newstate? . @@ -807,6 +837,7 @@ The difference between \fBiconic\fR and \fBicon\fR is that \fBwm iconify\fR command) while \fBicon\fR refers to a window whose only purpose is to serve as the icon for some other window (via the \fBwm iconwindow\fR command). The \fBicon\fR state cannot be set. +.\" METHOD: title .TP \fBwm title \fIwindow\fR ?\fIstring\fR? . @@ -816,6 +847,7 @@ should display this string in \fIwindow\fR's title bar). In this case the command returns an empty string. If \fIstring\fR is not specified then the command returns the current title for the \fIwindow\fR. The title for a window defaults to its name. +.\" METHOD: transient .TP \fBwm transient \fIwindow\fR ?\fIcontainer\fR? . @@ -834,6 +866,7 @@ transient of itself. The window manager may also decorate a transient window differently, removing some features normally present (e.g., minimize and maximize buttons) though this is entirely at the discretion of the window manager. +.\" METHOD: widthdraw .TP \fBwm withdraw \fIwindow\fR . |