diff --git a/doc/busy.n b/doc/busy.n index ab2fd8a47..bcd91b51b 100644 --- a/doc/busy.n +++ b/doc/busy.n @@ -28,24 +28,21 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -busy \- confine pointer events to a window sub-tree +busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS -\fBtk busy\fR \fIwindow \fR?\fIoptions\fR? -.sp -\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR? -.sp +.nf +\fBtk busy\fI window \fR?\fIoptions\fR? +\fBtk busy hold\fI window \fR?\fIoptions\fR? \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... -.sp -\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?... -.sp +\fBtk busy forget\fI window \fR?\fIwindow \fR?... \fBtk busy current\fR ?\fIpattern\fR? -.sp \fBtk busy status \fIwindow\fR +.fi .BE .SH DESCRIPTION .PP -The \fBtk busy\fR command provides a simple means to block pointer events from -Tk widgets, while overriding the widget's cursor with a configurable busy +The \fBtk busy\fR command provides a simple means to block mouse pointer events +from Tk widgets, while overriding the widget's cursor with a configurable busy cursor. Note this command does not prevent keyboard events from being sent to the widgets made busy. .SH INTRODUCTION @@ -114,7 +111,7 @@ The busy window has a configurable cursor. You can change the busy cursor using the \fBconfigure\fR operation. .PP .CS -\fBtk busy\fR configure .top \-cursor "watch" +\fBtk busy\fR configure .top -cursor "watch" .CE .PP Destroying the widget will also clean up any resources allocated by the \fBtk @@ -127,33 +124,16 @@ 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: cget .TP -\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... -. -Makes the specified \fIwindow\fR (and its descendants in the Tk window -hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. -A transparent window is put in front of the specified window. This transparent -window is mapped the next time idle tasks are processed, and the specified -window and its descendants will be blocked from user interactions. Normally -\fBupdate\fR should be called immediately afterward to insure that the hold -operation is in effect before the application starts its processing. The -following configuration options are valid: -.RS -.TP -\fB\-cursor \fIcursorName\fR -. -Specifies the cursor to be displayed when the widget is made busy. -\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The -default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. -.RE -.TP -\fBtk busy 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?... . @@ -180,6 +160,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?... . @@ -188,12 +176,28 @@ 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 current \fR?\fIpattern\fR? +\fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... . -Returns the pathnames of all widgets that are currently busy. If a -\fIpattern\fR is given, only the path names of busy widgets matching -\fIpattern\fR are returned. +Makes the specified \fIwindow\fR (and its descendants in the Tk window +hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. +A transparent window is put in front of the specified window. This transparent +window is mapped the next time idle tasks are processed, and the specified +window and its descendants will be blocked from user interactions. Normally +\fBupdate\fR should be called immediately afterward to insure that the hold +operation is in effect before the application starts its processing. The +following configuration options are valid: +.RS +.\" OPTION: -cursor +.TP +\fB\-cursor \fIcursorName\fR +. +Specifies the cursor to be displayed when the widget is made busy. +\fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The +default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. +.RE +.\" METHOD: status .TP \fBtk busy status \fIwindow\fR . @@ -206,8 +210,8 @@ The event blocking feature is implemented by creating and mapping a transparent window that completely covers the widget. When the busy window is mapped, it invisibly shields the widget and its hierarchy from all events that may be sent. Like Tk widgets, busy windows have widget names in the Tk window -hierarchy. This means that you can use the \fBbind\fR command, to handle -events in the busy window. +hierarchy. This means that you can use the \fBbind\fR command to handle +events in the busy window: .PP .CS \fBtk busy\fR hold .frame.canvas @@ -264,7 +268,7 @@ its descendants. It also makes sure it's not possible to leave button \fB.cancel\fR using the keyboard. .SH PORTABILITY .PP -Note that the \fBtk busy\fR command does not currently have any effect on OSX +Note that the \fBtk busy\fR command does not currently have any effect on macOS when Tk is built using Aqua support. .SH "SEE ALSO" grab(n) diff --git a/doc/button.n b/doc/button.n index 233feb688..cbbd704a5 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 @@ -109,19 +109,23 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following 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. @@ -175,7 +183,7 @@ The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "PLATFORM NOTES" .PP -On Aqua/Mac OS X, some configuration options are ignored for the purpose of +On Aqua/macOS, some configuration options are ignored for the purpose of drawing of the widget because they would otherwise conflict with platform guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still manipulate the values, but do not cause any variation to the look of the @@ -188,17 +196,17 @@ This is the classic Tk demonstration: .PP .CS -\fBbutton\fR .b \-text "Hello, World!" \-command exit +\fBbutton\fR .b -text "Hello, World!" -command exit pack .b .CE .PP This example demonstrates how to handle button accelerators: .PP .CS -\fBbutton\fR .b1 \-text Hello \-underline 0 -\fBbutton\fR .b2 \-text World \-underline 0 -bind . {.b1 flash; .b1 invoke} -bind . {.b2 flash; .b2 invoke} +\fBbutton\fR .b1 -text Hello -underline 0 +\fBbutton\fR .b2 -text World -underline 0 +bind . {.b1 flash; .b1 invoke} +bind . {.b2 flash; .b2 invoke} pack .b1 .b2 .CE .SH "SEE ALSO" diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index e441d78ef..a12207bc1 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" @@ -16,15 +16,19 @@ tk_chooseDirectory \- pops up a dialog box for the user to select a directory. The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the user to select a directory. The following \fIoption\-value\fR pairs are possible as command line arguments: +.\" OPTION: -command .TP -\fB\-command\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. +is only available on macOS. +.\" OPTION: -initialdir .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 @@ -33,33 +37,41 @@ On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. +.\" OPTION: -message .TP -\fB\-message\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. +This is only available on macOS. +.\" OPTION: -mustexist .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. +.\" OPTION: -parent .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 +is displayed on top of its parent window. On macOS, this turns the file dialog into a sheet attached to the parent window. +.\" OPTION: -title .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 .PP .CS set dir [\fBtk_chooseDirectory\fR \e - \-initialdir ~ \-title "Choose a directory"] + -initialdir ~ -title "Choose a directory"] if {$dir eq ""} { - label .l \-text "No directory selected" + label .l -text "No directory selected" } else { - label .l \-text "Selected $dir" + label .l -text "Selected $dir" } .CE .SH "SEE ALSO" diff --git a/doc/colors.n b/doc/colors.n index 3747ee8b7..9d93f9a25 100644 --- a/doc/colors.n +++ b/doc/colors.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" Copyright (c) 2003 ActiveState Corporation. '\" Copyright (c) 2006-2007 Daniel A. Steffen '\" Copyright (c) 2008 Donal K. Fellows @@ -782,7 +782,7 @@ YellowGreen 154 205 50 .DE .SH "PORTABILITY ISSUES" .TP -\fBMac OS X\fR +\fBmacOS\fR . On macOS, the following additional system colors are available. This first group contains all of the HIBrush colors available in the @@ -870,7 +870,7 @@ systemWindowBody . Tk supports all of the NSColors in the macOS System ColorList. The convention for naming these colors is that the Tk name is generated by -capitalizing the macOS name and adding the prefix "system". On OSX +capitalizing the macOS name and adding the prefix "system". On macOS 10.14 (Mojave) and later many of these "semantic" colors will appear differently depending on whether the NSWindow in which they are used has the Aqua or DarkAqua appearance. The System ColorList differs between @@ -896,7 +896,7 @@ systemTextColor . The numbered systemWindowBackgroundColors below are used in the \fBttk::notebook\fR and \fBttk::labelframe\fR widgets -to provide a contrasting background. Each numbered color constrasts +to provide a contrasting background. Each numbered color contrasts with its predecessor. .RS .DS @@ -911,7 +911,6 @@ systemWindowBackgroundColor7 .DE .RE .TP - \fBWindows\fR . On Windows, the following additional system colors are available diff --git a/doc/cursors.n b/doc/cursors.n index a7287552e..df60ea3fe 100644 --- a/doc/cursors.n +++ b/doc/cursors.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" '\" Copyright (c) 2006-2007 Daniel A. Steffen @@ -101,6 +101,7 @@ The \fBnone\fR cursor can be specified to eliminate the cursor. .SH "PORTABILITY ISSUES" .TP \fBWindows\fR +. On Windows systems, the following cursors are mapped to native cursors: .RS .CS @@ -130,8 +131,9 @@ wait .CE .RE .TP -\fBMac OS X\fR -On Mac OS X systems, the following cursors are mapped to native cursors: +\fBmacOS\fR +. +On macOS, the following cursors are mapped to native cursors: .RS .CS arrow diff --git a/doc/font.n b/doc/font.n index 72f9270c5..e1bdf0502 100644 --- a/doc/font.n +++ b/doc/font.n @@ -12,7 +12,7 @@ .SH NAME font \- Create and inspect fonts. .SH SYNOPSIS -\fBfont\fI option \fR?\fIarg arg ...\fR? +\fBfont\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -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? . @@ -52,12 +54,13 @@ new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .RS .PP -Note that on Aqua/Mac OS X, the system fonts (see +Note that on Aqua/macOS, the system fonts (see \fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they are implemented by the system theme. To achieve the effect of modification, use \fBfont actual\fR to get their configuration and \fBfont create\fR to synthesize a copy of the font which can be modified. .RE +.\" METHOD: create .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . @@ -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 @@ -200,16 +209,19 @@ horizontal line where the bottom of most letters line up; certain letters, such as lower-case .QW g stick below the baseline. +.\" OPTION: -ascent .TP -\fB\-ascent \0\fR +\fB\-ascent\fR . The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. +.\" OPTION: -descent .TP -\fB\-descent \0\fR +\fB\-descent\fR . The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. +.\" OPTION: -linespace .TP \fB\-linespace\fR . @@ -217,8 +229,9 @@ Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. +.\" OPTION: -fixed .TP -\fB\-fixed \0\fR +\fB\-fixed\fR . Returns a boolean flag that is .QW \fB1\fR @@ -235,6 +248,7 @@ included when calculating this value. The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: +.\" OPTION: -family .TP \fB\-family \fIname\fR . @@ -251,6 +265,7 @@ The \fIname\fR may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. +.\" OPTION: -size .TP \fB\-size \fIsize\fR . @@ -270,6 +285,7 @@ to a fixed-size bitmap. The mapping between points and pixels is set when the application starts, based on properties of the installed monitor, but it can be overridden by calling the \fBtk scaling\fR command. .RE +.\" OPTION: -weight .TP \fB\-weight \fIweight\fR . @@ -277,20 +293,26 @@ The nominal thickness of the characters in the font. The value \fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is \fBnormal\fR. +.\" OPTION: -slant .TP \fB\-slant \fIslant\fR +. The amount the characters in the font are slanted away from the vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is \fBroman\fR. +.\" OPTION: -underline .TP \fB\-underline \fIboolean\fR +. The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is \fBfalse\fR. +.\" OPTION: -overstrike .TP \fB\-overstrike \fIboolean\fR +. The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is \fBfalse\fR. @@ -298,41 +320,23 @@ for overstrike is \fBfalse\fR. .PP The following named fonts are supported on all systems, and default to values that match appropriate system defaults. -.TP -\fBTkDefaultFont\fR -. +.IP \fBTkDefaultFont\fR This font is the default for all GUI items not otherwise specified. -.TP -\fBTkTextFont\fR -. +.IP \fBTkTextFont\fR This font should be used for user text in entry widgets, listboxes etc. -.TP -\fBTkFixedFont\fR -. +.IP \fBTkFixedFont\fR This font is the standard fixed-width font. -.TP -\fBTkMenuFont\fR -. +.IP \fBTkMenuFont\fR This font is used for menu items. -.TP -\fBTkHeadingFont\fR -. +.IP \fBTkHeadingFont\fR This font should be used for column headings in lists and tables. -.TP -\fBTkCaptionFont\fR -. +.IP \fBTkCaptionFont\fR This font should be used for window and dialog caption bars. -.TP -\fBTkSmallCaptionFont\fR -. +.IP \fBTkSmallCaptionFont\fR This font should be used for captions on contained windows or tool dialogs. -.TP -\fBTkIconFont\fR -. +.IP \fBTkIconFont\fR This font should be used for icon captions. -.TP -\fBTkTooltipFont\fR -. +.IP \fBTkTooltipFont\fR This font should be used for tooltip windows (transient information windows). .LP It is \fInot\fR advised to change these fonts, as they may be modified by Tk @@ -343,9 +347,11 @@ modify that. The following system fonts are supported: .TP \fBX Windows\fR +. All valid X font names, including those listed by xlsfonts(1), are available. .TP \fBMS Windows\fR +. The following fonts are supported, and are mapped to the user's style defaults. .RS @@ -356,7 +362,8 @@ style defaults. .DE .RE .TP -\fBMac OS X\fR +\fBmacOS\fR +. The following fonts are supported, and are mapped to the user's style defaults. .RS @@ -386,17 +393,17 @@ theme fonts: Fill a text widget with lots of font demonstrators, one for every font family installed on your system: .CS -pack [text .t \-wrap none] \-fill both \-expand 1 +pack [text .t -wrap none] -fill both -expand 1 set count 0 set tabwidth 0 -foreach family [lsort \-dictionary [\fBfont families\fR]] { - .t tag configure f[incr count] \-font [list $family 10] - .t insert end ${family}:\\t {} \e +foreach family [lsort -dictionary [\fBfont families\fR]] { + .t tag configure f[incr count] -font [list $family 10] + .t insert end ${family}:\et {} \e "This is a simple sampler\en" f$count - set w [\fBfont measure\fR [.t cget \-font] ${family}:] - if {$w+5 > $tabwidth} { - set tabwidth [expr {$w+5}] - .t configure \-tabs $tabwidth + set w [\fBfont measure\fR [.t cget -font] ${family}:] + if {$w + 5 > $tabwidth} { + set tabwidth [expr {$w + 5}] + .t configure -tabs $tabwidth } } .CE diff --git a/doc/fontchooser.n b/doc/fontchooser.n index 65aa8e7e7..3dbafa248 100644 --- a/doc/fontchooser.n +++ b/doc/fontchooser.n @@ -11,11 +11,11 @@ .SH NAME fontchooser \- control font selection dialog .SH SYNOPSIS -\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR? -.sp +.nf +\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR? \fBtk fontchooser\fR \fBshow\fR -.sp \fBtk fontchooser\fR \fBhide\fR +.fi .BE .SH DESCRIPTION .PP @@ -24,22 +24,25 @@ the native platform font selection dialog where available, or a dialog implemented in Tcl otherwise. .PP Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not -return an immediate result, as on some platforms (Mac OS X) the standard font +return an immediate result, as on some platforms (macOS) the standard font dialog is modeless while on others (Windows) it is modal. To accommodate this difference, all user interaction with the dialog will be communicated to the caller via callbacks or virtual events. .PP The \fBtk fontchooser\fR command can have one of the following forms: +.\" METHOD: configure .TP -\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR? +\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value ...\fR? . Set or query one or more of the configurations options below (analogous to Tk widget configuration). +.\" 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 . @@ -47,24 +50,32 @@ Hide the font selection dialog if it is visible and cause any pending \fBtk fontchooser\fR \fBshow\fR command to return. .PP .SH "CONFIGURATION OPTIONS" +.\" OPTION: -parent .TP \fB\-parent\fR +. Specifies/returns the logical parent window of the font selection dialog (similar to the \fB\-parent\fR option to other dialogs). The font selection dialog is hidden if it is visible when the parent window is destroyed. +.\" OPTION: -title .TP \fB\-title\fR +. Specifies/returns the title of the dialog. Has no effect on platforms where the font selection dialog does not support titles. +.\" OPTION: -font .TP \fB\-font\fR +. Specifies/returns the font that is currently selected in the dialog if it is visible, or that will be initially selected when the dialog is shown (if supported by the platform). Can be set to the empty string to indicate that no font should be selected. Fonts can be specified in any form given by the "FONT DESCRIPTION" section in the \fBfont\fR manual page. +.\" OPTION: -command .TP \fB\-command\fR +. Specifies/returns the command prefix to be called when a font selection has been made by the user. The command prefix is evaluated at the global level after having the specification of the selected font appended. On platforms @@ -74,8 +85,10 @@ evaluation. Can be set to the empty string to indicate that no callback should be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" section in the \fBfont\fR manual page (i.e. a list of the form \fI{family size style ?style ...?}\fR). +.\" OPTION: -visible .TP \fB\-visible\fR +. Read-only option that returns a boolean indicating whether the font selection dialog is currently visible. Attempting to set this option results in an error. @@ -83,6 +96,7 @@ dialog is currently visible. Attempting to set this option results in an error. .SH "VIRTUAL EVENTS" .TP \fB<>\fR +. Sent to the dialog parent whenever the visibility of the font selection dialog changes, both as a result of user action (e.g. disposing of the dialog via OK/Cancel button or close box) and of the \fBtk fontchooser\fR @@ -91,6 +105,7 @@ current visibility of the dialog by querying the \fB\-visible\fR configuration option. .TP \fB<>\fR +. Sent to the dialog parent whenever the font selection dialog is visible and the selected font changes, both as a result of user action and of the \fB\-font\fR configuration option being set. Binding scripts can determine the currently @@ -106,7 +121,7 @@ It is implementation dependent which exact user actions result in the callback being called resp. the virtual events being sent. Where an Apply or OK button is present in the dialog, that button will trigger the \fB\-command\fR callback and \fB<>\fR virtual event. On some implementations -other user actions may also have that effect; on Mac OS X for instance, the +other user actions may also have that effect; on macOS for instance, the standard font selection dialog immediately reflects all user choices to the caller. .PP @@ -139,36 +154,36 @@ to ensure its selected font matches the new value of the named font. .CS proc fontchooserDemo {} { wm title . "Font Chooser Demo" - \fBtk fontchooser\fR \fBconfigure\fR \-parent . - button .b \-command fontchooserToggle \-takefocus 0 + \fBtk fontchooser\fR \fBconfigure\fR -parent . + button .b -command fontchooserToggle -takefocus 0 fontchooserVisibility .b - bind . \fB<>\fR \\ + bind . \fB<>\fR \e [list fontchooserVisibility .b] foreach w {.t1 .t2} { - text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid + text $w -width 20 -height 4 -borderwidth 1 -relief solid bind $w [list fontchooserFocus $w] $w insert end "Text Widget $w" } - .t1 configure \-font {Courier 14} - .t2 configure \-font {Times 16} + .t1 configure -font {Courier 14} + .t2 configure -font {Times 16} pack .b .t1 .t2; focus .t1 } proc fontchooserToggle {} { \fBtk fontchooser\fR [expr { - [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "\fBhide\fR" : "\fBshow\fR"}] } proc fontchooserVisibility {w} { - $w configure \-text [expr { - [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + $w configure -text [expr { + [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "Hide Font Dialog" : "Show Font Dialog"}] } proc fontchooserFocus {w} { - \fBtk fontchooser\fR \fBconfigure\fR \-font [$w cget \-font] \\ - \-command [list fontchooserFontSelection $w] + \fBtk fontchooser\fR \fBconfigure\fR -font [$w cget -font] \e + -command [list fontchooserFontSelection $w] } proc fontchooserFontSelection {w font args} { - $w configure \-font [font actual $font] + $w configure -font [font actual $font] } fontchooserDemo .CE diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index d2323de25..70adf706b 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -34,31 +34,37 @@ whether the existing file should be overwritten or not. .PP The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: +.\" OPTION: -command .TP -\fB\-command\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. +is only available on macOS. +.\" OPTION: -confirmoverwrite .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. +.\" OPTION: -defaultextension .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 string, which means no extension will be appended to the filename in -any case. This option is ignored on Mac OS X, which +any case. This option is ignored on macOS, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. +.\" OPTION: -filetypes .TP -\fB\-filetypes\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 @@ -68,8 +74,9 @@ empty list, or if the \fBFile types\fR listbox is not supported by the particular platform then all files are listed regardless of their types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. +.\" OPTION: -initialdir .TP -\fB\-initialdir\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, @@ -79,32 +86,38 @@ On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. +.\" OPTION: -initialfile .TP -\fB\-initialfile\fR \fIfilename\fR +\fB\-initialfile\fI filename\fR . Specifies a filename to be displayed in the dialog when it pops up. +.\" OPTION: -message .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. +This is only available on macOS. +.\" OPTION: -multiple .TP -\fB\-multiple\fR \fIboolean\fR +\fB\-multiple\fI boolean\fR . Allows the user to choose multiple files from the Open dialog. +.\" OPTION: -parent .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 +dialog is displayed on top of its parent window. On macOS, this turns the file dialog into a sheet attached to the parent window. +.\" OPTION: -title .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. +.\" OPTION: -typevariable .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 @@ -192,7 +205,7 @@ set types { {{GIF Files} {} GIFF} {{All Files} * } } -set filename [\fBtk_getOpenFile\fR \-filetypes $types] +set filename [\fBtk_getOpenFile\fR -filetypes $types] if {$filename ne ""} { # Open the file ... diff --git a/doc/menu.n b/doc/menu.n index 5f084861d..76374ebe4 100644 --- a/doc/menu.n +++ b/doc/menu.n @@ -13,8 +13,9 @@ 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 +.fi .SO \-activebackground \-borderwidth \-foreground \-activeborderwidth \-cursor \-relief @@ -40,7 +41,7 @@ top. If so, it will exist as entry 0 of the menu and the other entries will number starting at 1. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. -This option is ignored under Aqua/MacOS, where menus cannot +This option is ignored under Aqua/macOS, where menus cannot be torn off. .OP \-tearoffcommand tearOffCommand TearOffCommand If this option has a non-empty value, then it specifies a Tcl command @@ -54,7 +55,7 @@ and menu \fB.x.y\fR is torn off to create a new menu \fB.x.tearoff1\fR, then the command .QW "\fBa b .x.y .x.tearoff1\fR" will be invoked. -This option is ignored under Aqua/MacOS, where menus cannot +This option is ignored under Aqua/macOS, where menus cannot be torn off. .OP \-title title Title The string will be used to title the window created when this menu is @@ -262,7 +263,7 @@ becoming the Application menu. When Tk sees a .menubar.window menu on the Macintosh, the menu's contents are inserted into the standard Window menu of the user's menubar whenever the window's menubar is in front. The first items in -the menu are provided by Mac OS X, and the names of the current +the menu are provided by macOS, and the names of the current toplevels are automatically appended after all the Tk-defined items and a separator. The Window menu on the Mac also allows toggling the window into a fullscreen state, and managing a tabbed window interface @@ -272,7 +273,7 @@ version of the operating system. When Tk sees a .menubar.help menu on the Macintosh, the menu's contents are appended to the standard Help menu of the user's menubar whenever the window's menubar is in front. The first items in the menu -are provided by Mac OS X. +are provided by macOS. .PP When Tk sees a System menu on Windows, its items are appended to the system menu that the menubar is attached to. This menu is tied to the @@ -312,25 +313,17 @@ Many of the widget commands for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called \fIindex\fRes and may be specified in any of the following forms: -.TP 12 -\fBactive\fR -. +.IP \fBactive\fR 12 Indicates the entry that is currently active. If no entry is active then this form is equivalent to \fBnone\fR. This form may not be abbreviated. -.TP 12 -\fBend\fR -. +.IP \fBend\fR 12 Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to \fBnone\fR. This form may not be abbreviated. -.TP 12 -\fBlast\fR -. +.IP \fBlast\fR 12 Same as \fBend\fR. -.TP 12 -\fBnone\fR -. +.IP \fBnone\fR 12 Indicates .QW "no entry at all" ; this is used most commonly with @@ -338,22 +331,16 @@ the \fBactivate\fR option to deactivate all the entries in the menu. In most cases the specification of \fBnone\fR causes nothing to happen in the widget command. This form may not be abbreviated. -.TP 12 -\fB@\fIx\fB,\fIy\fR -. +.IP \fB@\fIx\fB,\fIy\fR 12 Indicates the entry that covers the point in the menu's window specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no entry covers that point, then this form is equivalent to \fBnone\fR. If only a single number is specified, it is treated as the y-coordinate. -.TP 12 -\fInumber\fR -. +.IP \fInumber\fR 12 Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. -.TP 12 -\fIpattern\fR -. +.IP \fIpattern\fR 12 If the index does not satisfy one of the above forms then this form is used. \fIPattern\fR is pattern-matched against the label of each entry in the menu, in order from the top down, until a @@ -364,6 +351,7 @@ If the index could match more than one of the above forms, then the form earlier in the above list takes precedence. .PP The following widget commands are possible for menu widgets: +.\" METHOD: activate .TP \fIpathName \fBactivate \fIindex\fR . @@ -373,6 +361,7 @@ Any previously-active entry is deactivated. If \fIindex\fR is specified as \fBnone\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?\fIoption value option value ...\fR? . @@ -383,6 +372,7 @@ or a unique abbreviation of one of the above. If additional arguments are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR section below. The \fBadd\fR widget command returns an empty string. +.\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . @@ -390,6 +380,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? . @@ -399,6 +390,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? . @@ -414,6 +406,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? . @@ -422,6 +415,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 . @@ -429,6 +423,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? . @@ -442,11 +437,13 @@ 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: index .TP \fIpathName \fBindex \fIindex\fR . Returns the numerical index corresponding to \fIindex\fR, or \fBnone\fR if \fIindex\fR was specified as \fBnone\fR. +.\" METHOD: insert .TP \fIpathName \fBinsert \fIindex type \fR?\fIoption value option value ...\fR? . @@ -456,6 +453,7 @@ to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR arguments have the same interpretation as for the \fBadd\fR widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one. +.\" METHOD: invoke .TP \fIpathName \fBinvoke \fIindex\fR . @@ -468,6 +466,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? . @@ -482,6 +481,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 . @@ -491,6 +491,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 . @@ -498,6 +499,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 . @@ -505,11 +507,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 . @@ -518,17 +522,19 @@ window of the topmost pixel in the entry specified by \fIindex\fR. .SH "MENU ENTRY OPTIONS" The following options are allowed on menu entries. Most options are not supported by all entry types. +.\" OPTION: -activebackground .TP \fB\-activebackground \fIvalue\fR . Specifies a background color to use for displaying this entry when it -is active. This option is ignored on Aqua/MacOS. +is active. This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-activebackground\fR option for the overall menu is used. If the \fBtk_strictMotif\fR variable has been set to request strict Motif compliance, then this option is ignored and the \fB\-background\fR option is used in its place. This option is not available for separator or tear-off entries. +.\" OPTION: -activeforeground .TP \fB\-activeforeground \fIvalue\fR . @@ -537,6 +543,7 @@ is active. This option is ignored on Aqua/macOS. If this option is specified as an empty string (the default), then the \fB\-activeforeground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. +.\" OPTION: -accelerator .TP \fB\-accelerator \fIvalue\fR . @@ -546,6 +553,7 @@ used to invoke the same function as the menu entry. This is a display option, it does not actually set the corresponding binding (which can be achieved using the \fBbind\fR command). This option is not available for separator or tear-off entries. +.\" OPTION: -background .TP \fB\-background \fIvalue\fR . @@ -555,6 +563,7 @@ This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-background\fR option for the overall menu is used. This option is not available for separator or tear-off entries. +.\" OPTION: -bitmap .TP \fB\-bitmap \fIvalue\fR . @@ -567,6 +576,7 @@ to an empty string to enable a textual label to be displayed. If a \fB\-image\fR option has been specified, it overrides \fB\-bitmap\fR. This option is not available for separator or tear-off entries. +.\" OPTION: -columnbreak .TP \fB\-columnbreak \fIvalue\fR . @@ -575,11 +585,13 @@ this option is one, the entry appears at the top of a new column in the menu. This option is ignored on Aqua/macOS, where menus are always a single column. +.\" OPTION: -command .TP \fB\-command \fIvalue\fR . Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. +.\" OPTION: -compound .TP \fB\-compound \fIvalue\fR . @@ -590,6 +602,7 @@ Valid values for this option are \fBbottom\fR, \fBcenter\fR, is \fBnone\fR, meaning that the button will display either an image or text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR options. +.\" OPTION: -font .TP \fB\-font \fIvalue\fR . @@ -598,6 +611,7 @@ string in this entry. If this option is specified as an empty string (the default) then the \fB\-font\fR option for the overall menu is used. This option is not available for separator or tear-off entries. +.\" OPTION: -foreground .TP \fB\-foreground \fIvalue\fR . @@ -607,6 +621,7 @@ This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-foreground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. +.\" OPTION: -hidemargin .TP \fB\-hidemargin \fIvalue\fR . @@ -614,6 +629,7 @@ Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used. +.\" OPTION: -image .TP \fB\-image \fIvalue\fR . @@ -626,34 +642,40 @@ This option overrides the \fB\-label\fR and \fB\-bitmap\fR options but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries. +.\" OPTION: -indicatoron .TP \fB\-indicatoron \fIvalue\fR . Available only for checkbutton and radiobutton entries. \fIValue\fR is a boolean that determines whether or not the indicator should be displayed. +.\" OPTION: -label .TP \fB\-label \fIvalue\fR . Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries. +.\" OPTION: -menu .TP \fB\-menu \fIvalue\fR . Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu. +.\" OPTION: -offvalue .TP \fB\-offvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected. +.\" OPTION: -onvalue .TP \fB\-onvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. +.\" OPTION: -selectcolor .TP \fB\-selectcolor \fIvalue\fR . @@ -662,6 +684,7 @@ Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the \fB\-selectcolor\fR option for the menu determines the indicator color. +.\" OPTION: -selectimage .TP \fB\-selectimage \fIvalue\fR . @@ -672,6 +695,7 @@ the \fB\-image\fR option) when it is selected. by some previous invocation of \fBimage create\fR. This option is ignored unless the \fB\-image\fR option has been specified. +.\" OPTION: -state .TP \fB\-state \fIvalue\fR . @@ -689,6 +713,7 @@ In this state the entry is displayed according to the \fB\-disabledforeground\fR option for the menu and the \fB\-background\fR option from the entry. This option is not available for separator entries. +.\" OPTION: -underline .TP \fB\-underline \fIvalue\fR . @@ -699,6 +724,7 @@ implement keyboard traversal. 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries. +.\" OPTION: -value .TP \fB\-value \fIvalue\fR . @@ -706,6 +732,7 @@ Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the \fB\-label\fR option for the entry as the value to store in the variable. +.\" OPTION: -variable .TP \fB\-variable \fIvalue\fR . diff --git a/doc/menubutton.n b/doc/menubutton.n index 5696794d9..6252374b5 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 @@ -95,7 +95,7 @@ is released, the menu is unposted. .PP Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the preferred mechanism for allowing a user to select one item from a list -on Mac OS X. +on macOS. .PP Menubuttons were also typically organized into groups called menu bars that allow scanning: @@ -117,11 +117,12 @@ name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following 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/messageBox.n b/doc/messageBox.n index 4350b22bb..e630c123b 100644 --- a/doc/messageBox.n +++ b/doc/messageBox.n @@ -28,7 +28,7 @@ The following option-value pairs are supported: 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. +is only available on macOS. .TP \fB\-default\fR \fIname\fR . @@ -82,7 +82,7 @@ Displays three buttons whose symbolic names are \fBabort\fR, .TP 18 \fBok\fR . -Displays one button whose symbolic name is \fBok\fR. +Displays one button whose symbolic name is \fBok\fR. This is the default. .TP 18 \fBokcancel\fR . diff --git a/doc/tk.n b/doc/tk.n index 43ce64dd6..7621f87cf 100644 --- a/doc/tk.n +++ b/doc/tk.n @@ -12,7 +12,7 @@ .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS -\fBtk\fR \fIoption \fR?\fIarg arg ...\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: scaling .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . @@ -110,6 +117,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: useinputmethods .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . @@ -120,12 +128,13 @@ feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current state is returned. This is turned on by default for the main display. +.\" METHOD: windowingsystem .TP \fBtk windowingsystem\fR . Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), -or \fBaqua\fR (Mac OS X Aqua). +or \fBaqua\fR (macOS Aqua). .SH "SEE ALSO" busy(n), fontchooser(n), send(n), winfo(n) .SH KEYWORDS diff --git a/doc/tk_mac.n b/doc/tk_mac.n index 2ce13743e..7af960690 100644 --- a/doc/tk_mac.n +++ b/doc/tk_mac.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -tk::mac \- Access Mac-Specific Functionality on OS X from Tk +tk::mac \- Access Mac-Specific Functionality on macOS from Tk .SH SYNOPSIS .nf \fB::tk::mac::DoScriptFile\fR @@ -35,16 +35,16 @@ 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 .SH "EVENT HANDLER CALLBACKS" .PP -The Aqua/Mac OS X application environment defines a number of additional +The Aqua/macOS application environment defines a number of additional events that applications should respond to. These events are mapped by Tk to calls to commands in the \fB::tk::mac\fR namespace; unless otherwise noted, if the command is absent, no action will be taken. +.\" COMMAND: DoScriptFile .TP \fB::tk::mac::DoScriptFile\fR . @@ -52,6 +52,7 @@ The default Apple Event handler for AEDoScriptHandler. This command executes a Tcl file when an AppleScript sends a .QW "do script" command to Wish with a file path as a parameter. +.\" COMMAND: DoScriptText .TP \fB::tk::mac::DoScriptText\fR . @@ -59,6 +60,7 @@ The default Apple Event handler for AEDoScriptHandler. This command executes Tcl code when an AppleScript sends a .QW "do script" command to Wish with Tcl code or a Tcl procedure as a parameter. +.\" COMMAND: ShowPreferences .TP \fB::tk::mac::ShowPreferences\fR . @@ -77,6 +79,7 @@ proc ::tk::mac::ShowPreferences {} { } .CE .RE +.\" COMMAND: OpenApplication .TP \fB::tk::mac::OpenApplication\fR . @@ -84,6 +87,7 @@ If a proc of this name is defined, this proc fill fire when your application is initially opened. It is the default Apple Event handler for kAEOpenApplication, .QW oapp . +.\" COMMAND: ReopenApplication .TP \fB::tk::mac::ReopenApplication\fR . @@ -106,6 +110,7 @@ proc ::tk::mac::ReopenApplication {} { } .CE .RE +.\" COMMAND: OpenDocument .TP \fB::tk::mac::OpenDocument \fIfile...\fR . @@ -124,6 +129,7 @@ proc ::tk::mac::OpenDocument {args} { } .CE .RE +.\" COMMAND: PrintDocument .TP \fB::tk::mac::PrintDocument \fIfile...\fR . @@ -132,6 +138,7 @@ kAEPrintDocuments, .QW pdoc , the Apple Event sent when your application is asked to print a document. It takes a single absolute file path as an argument. +.\" COMMAND: Quit .TP \fB::tk::mac::Quit\fR . @@ -142,17 +149,20 @@ the Apple Event sent when your application is asked to be quit, e.g. via the quit menu item in the application menu, the quit menu item in the Dock menu, or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is called instead. +.\" COMMAND: OnHide .TP \fB::tk::mac::OnHide\fR . If defined, this is called when your application receives a kEventAppHidden event, e.g. via the hide menu item in the application or Dock menus. +.\" COMMAND: OnShow .TP \fB::tk::mac::OnShow\fR . If defined, this is called when your application receives a kEventAppShown event, e.g. via the show all menu item in the application menu, or by clicking the Dock icon of a hidden application. +.\" COMMAND: ShowHelp .TP \fB::tk::mac::ShowHelp\fR . @@ -162,6 +172,7 @@ platform-specific standard Help menu item performs the default Cocoa action of showing the Help Book configured in the application's Info.plist (or displaying an alert if no Help Book is set). +.\" COMMAND: PerformService .TP \fB::tk::mac::PerformService\fR . @@ -193,6 +204,7 @@ key in Wish's Info.plist file is currently set as .QW "Wish" ; if a developer changes the name of the Wish executable to something else, this key should be modified with the same name. +.\" COMMAND: LaunchURL .TP \fB::tk::mac::LaunchURL \fIURL...\fR . @@ -202,19 +214,18 @@ an RSS feed, rather than launching a default application to handle the URL, although it can defined as such. Wish includes a stub URL scheme of .QW foo:// -in the CFBundleURLSchemes key of its Info.plist file; this should be customized for the specific URL -scheme the developer wants to support. +in the CFBundleURLSchemes key of its Info.plist file; this should be +customized for the specific URL scheme the developer wants to support. .TP \fB::tk::mac::GetAppPath\fR . Returns the current applications's file path. -.TP - - +.PP .SH "ADDITIONAL DIALOGS" .PP -The Aqua/Mac OS X defines additional dialogs that applications should +Aqua/macOS defines additional dialogs that applications should support. +.\" COMMAND: standardAboutPanel .TP \fB::tk::mac::standardAboutPanel\fR . @@ -233,22 +244,26 @@ procedure will be called instead of opening the standardAboutPanel. .PP There are a number of additional global configuration options that control the details of how Tk renders by default. +.\" COMMAND: useCompatibilityMetrics .TP \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR . Preserves compatibility with older Tk/Aqua metrics; set to \fBfalse\fR for more native spacing. +.\" COMMAND: CGAntialiasLimit .TP \fB::tk::mac::CGAntialiasLimit \fIlimit\fR . Sets the antialiasing limit; lines thinner that \fIlimit\fR pixels will not be antialiased. Integer, set to 0 by default, making all lines be antialiased. +.\" COMMAND: antialiasedtext .TP \fB::tk::mac::antialiasedtext \fInumber\fR . Sets anti-aliased text. Controls text antialiasing, possible values for \fInumber\fR are -1 (default, use system default for text AA), 0 (no text AA), 1 (use text AA). +.\" COMMAND: useThemedToplevel .TP \fB::tk::mac::useThemedToplevel \fIboolean\fR . @@ -257,6 +272,7 @@ background. Equivalent to configuring the toplevel with .QW "\fB\-background systemWindowHeaderBackground\fR" , or to using a \fBttk::frame\fR. .SH "SUPPORT COMMANDS" +.\" COMMAND: iconBitmap .TP \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR . @@ -278,26 +294,32 @@ NSImage url string .PP The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define the dimensions of the image to create, and \fI\-kind\fR must be one of: +.\" OPTION: -file .TP \fB\-file\fR . icon of file at given path +.\" OPTION: -fileType .TP \fB\-fileType\fR . icon of given file type +.\" OPTION: -osType .TP \fB\-osType\fR . icon of given 4-char OSType file type +.\" OPTION: -systemType .TP \fB\-systemType\fR . icon for given IconServices 4-char OSType +.\" OPTION: -namedImage .TP \fB\-namedImage\fR . named NSImage for given name +.\" OPTION: -imageFile .TP \fB\-imageFile\fR . diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index 707a17e68..27de41a26 100644 --- a/doc/ttk_sizegrip.n +++ b/doc/ttk_sizegrip.n @@ -28,7 +28,7 @@ Sizegrip widgets support the standard methods. No other widget methods are used. .SH "PLATFORM-SPECIFIC NOTES" .PP -On Mac OSX, toplevel windows automatically include a built-in +On macOS, toplevel windows automatically include a built-in size grip by default. Adding a \fBttk::sizegrip\fR there is harmless, since the built-in grip will just mask the widget. diff --git a/doc/wm.n b/doc/wm.n index d0b137524..40a416ed0 100644 --- a/doc/wm.n +++ b/doc/wm.n @@ -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 @@ -58,6 +60,7 @@ values are as follows: .PP All platforms support the following attributes (though X11 users should see the notes below): +.\" OPTION: -alpha .TP \fB\-alpha\fR . @@ -65,26 +68,31 @@ Specifies the alpha transparency level of the toplevel. It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values outside that range will be constrained. Where not supported, the \fB\-alpha\fR value remains at \fB1.0\fR. +.\" OPTION: -fullscreen .TP \fB\-fullscreen\fR . Places the window in a mode that takes up the entire screen, has no borders, and covers the general use area (i.e. Start menu and taskbar on -Windows, dock and menubar on OSX, general window decorations on X11). +Windows, dock and menubar on macOS, general window decorations on X11). +.\" OPTION: -topmost .TP \fB\-topmost\fR . Specifies whether this is a topmost window (displays above all other windows). .PP On Windows, the following attributes may be set. +.\" OPTION: -disabled .TP \fB\-disabled\fR . Specifies whether the window is in a disabled state. +.\" OPTION: -toolwindow .TP \fB\-toolwindow\fR . Specifies a toolwindow style window (as defined in the MSDN). +.\" OPTION: -transparentcolor .TP \fB\-transparentcolor\fR . @@ -94,22 +102,26 @@ value accepted by \fBTk_GetColor\fR. If the empty string is specified 2000/XP+. Where not supported, the \fB\-transparentcolor\fR value remains at \fB{}\fR. .PP -On Mac OS X, the following attributes may be set. +On macOS, the following attributes may be set. +.\" OPTION: -modified .TP \fB\-modified\fR . Specifies the modification state of the window (determines whether the window close widget contains the modification indicator and whether the proxy icon is draggable). +.\" OPTION: -notify .TP \fB\-notify\fR . Specifies process notification state (bouncing of the application dock icon). +.\" OPTION: -titlepath .TP \fB\-titlepath\fR . -Specifies the path of the file referenced as the window proxy icon (which -can be dragged and dropped in lieu of the file's finder icon). +Specifies the path of the file referenced as the window proxy icon +(which can be dragged and dropped in lieu of the file's finder icon). +.\" OPTION: -transparent .TP \fB\-transparent\fR . @@ -121,6 +133,7 @@ color with some alpha, e.g. On X11, the following attributes may be set. These are not supported by all window managers, and will have no effect under older WMs. .\" See https://www.freedesktop.org/wiki/Specifications/wm-spec/ +.\" OPTION: -type .TP \fB\-type\fR .VS 8.6 @@ -131,87 +144,61 @@ entirely up to the window manager. A list of types may be used, in order of preference. The following values are mapped to constants defined in the EWMH specification (using others is possible, but not advised): .RS -.TP -\fBdesktop\fR -. +.IP \fBdesktop\fR indicates a desktop feature, -.TP -\fBdock\fR -. +.IP \fBdock\fR indicates a dock/panel feature, -.TP -\fBtoolbar\fR -. +.IP \fBtoolbar\fR indicates a toolbar window that should be acting on behalf of another window, as indicated with \fBwm transient\fR, -.TP -\fBmenu\fR -. +.IP \fBmenu\fR indicates a torn-off menu that should be acting on behalf of another window, as indicated with \fBwm transient\fR, -.TP -\fButility\fR -. +.IP \fButility\fR indicates a utility window (e.g., palette or toolbox) that should be acting on behalf of another window, as indicated with \fBwm transient\fR, -.TP -\fBsplash\fR -. +.IP \fBsplash\fR indicates a splash screen, displayed during application start up, -.TP -\fBdialog\fR -. +.IP \fBdialog\fR indicates a general dialog window, that should be acting on behalf of another window, as indicated with \fBwm transient\fR, -.TP -\fBdropdown_menu\fR -. +.IP \fBdropdown_menu\fR indicates a menu summoned from a menu bar, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBpopup_menu\fR -. +.IP \fBpopup_menu\fR indicates a popup menu, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBtooltip\fR -. +.IP \fBtooltip\fR indicates a tooltip window, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBnotification\fR -. +.IP \fBnotification\fR indicates a window that provides a background notification of some event, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBcombo\fR -. +.IP \fBcombo\fR indicates the drop-down list of a combobox widget, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBdnd\fR -. +.IP \fBdnd\fR indicates a window that represents something being dragged, which should usually also be set to be override-redirected (with \fBwm overrideredirect\fR), -.TP -\fBnormal\fR -. +.IP \fBnormal\fR indicates a window that has no special interpretation. .RE .VE 8.6 +.\" OPTION: -zoomed .TP \fB\-zoomed\fR . Requests that the window should be maximized. This is the same as \fBwm state -zoomed\fR on Windows and Mac OS X. +zoomed\fR on Windows and macOS. .PP On X11, changes to window attributes are performed asynchronously. Querying the value of an attribute returns the current state, which will not be the same as the value most recently set if the window manager has not yet processed the request or if it does not support the attribute. .RE +.\" METHOD: client .TP \fBwm client \fIwindow\fR ?\fIname\fR? . @@ -225,6 +212,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? . @@ -256,6 +244,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? . @@ -268,6 +257,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 . @@ -278,6 +268,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? . @@ -298,6 +289,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 . @@ -306,6 +298,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 . @@ -315,6 +308,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? . @@ -359,6 +353,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? . @@ -391,10 +386,11 @@ four elements corresponding to the current \fIbaseWidth\fR, \fIwindow\fR is not currently gridded, then an empty string is returned. .PP -Note: this command should not be needed very often, since the +Note that this command should not be needed very often, since the \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option provide easier access to the same functionality. .RE +.\" METHOD: group .TP \fBwm group \fIwindow\fR ?\fIpathName\fR? . @@ -406,6 +402,7 @@ 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: iconbitmap .TP \fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? . @@ -435,12 +432,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? . @@ -456,6 +455,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? . @@ -467,6 +467,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? . @@ -488,7 +489,7 @@ most modern window managers support. A \fBwm iconbitmap\fR may exist simultaneously. It is recommended to use not more than 2 icons, placing the larger icon first. .PP -On Macintosh, the first image called is loaded into an OSX-native icon +On Macintosh, the first image called is loaded into an OS-native icon format, and becomes the application icon in dialogs, the Dock, and other contexts. At the script level the command will accept only the first image passed in the @@ -496,6 +497,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? . @@ -506,6 +508,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? . @@ -523,7 +526,9 @@ Button press events are disabled for \fIwindow\fR as long as it is an icon window; this is needed in order to allow window managers to .QW own those events. -Note: not all window managers support the notion of an icon window. +Note that not all window managers support the notion of an icon window, and +the concept is entirely meaningless on non-X11 platforms. +.\" METHOD: manage .TP \fBwm manage \fIwidget\fR . @@ -533,6 +538,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? . @@ -548,6 +554,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? . @@ -563,6 +570,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? . @@ -583,6 +591,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? . @@ -604,6 +613,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? . @@ -651,6 +661,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? . @@ -667,6 +678,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? . @@ -685,6 +697,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? . @@ -699,18 +712,20 @@ When two window arguments separated by either \fBisabove\fR or \fBisbelow\fR are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. +.\" METHOD: state .TP \fBwm state \fIwindow\fR ?newstate? . If \fInewstate\fR is specified, the window will be set to the new state, otherwise it returns the current state of \fIwindow\fR: either -\fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and Mac -OS X only) \fBzoomed\fR. +\fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows and macOS +only) \fBzoomed\fR. The difference between \fBiconic\fR and \fBicon\fR is that \fBiconic\fR refers to a window that has been iconified (e.g., with the \fBwm iconify\fR command) while \fBicon\fR refers to a window whose only purpose is to serve as the icon for some other window (via the \fBwm iconwindow\fR command). The \fBicon\fR state cannot be set. +.\" METHOD: title .TP \fBwm title \fIwindow\fR ?\fIstring\fR? . @@ -720,6 +735,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? . @@ -738,6 +754,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 . @@ -748,7 +765,7 @@ has never been mapped, then this command causes the window to be mapped in the withdrawn state. Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. -Note: it sometimes seems to be necessary to withdraw a +Note that it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with \fBwm deiconify\fR) to get some window managers to pay attention to changes in window attributes such as group. @@ -845,10 +862,10 @@ A simple dialog-like window, centred on the screen: .CS # Create and arrange the dialog contents. toplevel .msg -label .msg.l \-text "This is a very simple dialog demo." -button .msg.ok \-text OK \-default active \-command {destroy .msg} -pack .msg.ok \-side bottom \-fill x -pack .msg.l \-expand 1 \-fill both +label .msg.l -text "This is a very simple dialog demo." +button .msg.ok -text OK -default active -command {destroy .msg} +pack .msg.ok -side bottom -fill x +pack .msg.l -expand 1 -fill both # Now set the widget up as a centred dialog. @@ -857,8 +874,8 @@ pack .msg.l \-expand 1 \-fill both # event loop with the widget hidden completely... \fBwm withdraw\fR .msg update -set x [expr {([winfo screenwidth .]\-[winfo width .msg])/2}] -set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] +set x [expr {([winfo screenwidth .] - [winfo width .msg]) / 2}] +set y [expr {([winfo screenheight .] - [winfo height .msg]) / 2}] \fBwm geometry\fR .msg +$x+$y \fBwm transient\fR .msg . \fBwm title\fR .msg "Dialog demo" @@ -867,7 +884,8 @@ set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] .SH "SEE ALSO" toplevel(n), winfo(n) .SH KEYWORDS -aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager +aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, +increments, position, size, title, top-level window, units, window manager '\" Local Variables: '\" mode: nroff '\" End: