From 6eca1b073cf6f27c3170f72e1a416d6fe6cc8703 Mon Sep 17 00:00:00 2001 From: dkf Date: Thu, 28 Oct 2004 12:25:22 +0000 Subject: More backporting of doc fixes --- doc/option.n | 22 +++++++-- doc/pack.n | 28 +++++++++--- doc/panedwindow.n | 10 ++--- doc/photo.n | 27 ++++++++--- doc/place.n | 27 +++++------ doc/popup.n | 19 +++++++- doc/raise.n | 17 ++++++- doc/scale.n | 8 ++-- doc/scrollbar.n | 22 +++++---- doc/selection.n | 38 +++++++++++++++- doc/send.n | 19 +++++++- doc/spinbox.n | 6 +-- doc/text.n | 131 ++++++++++++++++++++++++++---------------------------- doc/toplevel.n | 9 ++-- doc/winfo.n | 18 +++++++- doc/wm.n | 56 +++++++++++++++++------ 16 files changed, 310 insertions(+), 147 deletions(-) diff --git a/doc/option.n b/doc/option.n index 4545eb2..9f6d48e 100644 --- a/doc/option.n +++ b/doc/option.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: option.n,v 1.2 1998/09/14 18:22:58 stanton Exp $ +'\" RCS: @(#) $Id: option.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH option n "" Tk "Tk Built-In Commands" @@ -14,13 +14,12 @@ .SH NAME option \- Add/retrieve window options to/from the option database .SH SYNOPSIS +.nf \fBoption add \fIpattern value \fR?\fIpriority\fR? -.sp \fBoption clear\fR -.sp \fBoption get \fIwindow name class\fR -.sp \fBoption readfile \fIfileName \fR?\fIpriority\fR? +.fi .BE .SH DESCRIPTION @@ -86,6 +85,21 @@ Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above. +.SH EXAMPLES +Instruct every button in the application to have red text on it unless +explicitly overridden: +.CS +\fBoption add\fR *button.foreground red startupFile +.CE +.PP +Allow users to control what happens in an entry widget when the Return +key is pressed by specifying a script in the option database and add a +default option for that which rings the bell: +.CS +entry .e +bind .e [\fBoption get\fR .e returnCommand Command] +\fBoption add\fR *.e.returnCommand bell widgetDefault +.CE .SH KEYWORDS database, option, priority, retrieve diff --git a/doc/pack.n b/doc/pack.n index ddda916..c6c3588 100644 --- a/doc/pack.n +++ b/doc/pack.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pack.n,v 1.3 2001/02/12 18:06:47 drh Exp $ +'\" RCS: @(#) $Id: pack.n,v 1.3.6.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH pack n 4.0 Tk "Tk Built-In Commands" @@ -108,7 +108,7 @@ of two values to specify padding for left and right separately. \fB\-pady \fIamount\fR \fIAmount\fR specifies how much vertical external padding to leave on each side of the slave(s). \fIAmount\fR may be a list -of two values to specify padding for top and bottom separtely. +of two values to specify padding for top and bottom separately. \fIAmount\fR defaults to 0. .TP \fB\-side \fIside\fR @@ -156,7 +156,6 @@ Returns a list of all of the slaves in the packing order for \fImaster\fR. The order of the slaves in the list is the same as their order in the packing order. If \fImaster\fR has no slaves then an empty string is returned. - .SH "THE PACKER ALGORITHM" .PP For each master the packer maintains an ordered list of slaves @@ -217,7 +216,6 @@ left in the cavity. If the cavity shrinks to zero size, then all remaining slaves on the packing list will be unmapped from the screen until the master window becomes large enough to hold them again. - .SH "EXPANSION" .PP If a master window is so large that there will be extra space @@ -228,7 +226,6 @@ Extra horizontal space is distributed among the expandable slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR, and extra vertical space is distributed among the expandable slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. - .SH "GEOMETRY PROPAGATION" .PP The packer normally computes how large a master must be to @@ -243,7 +240,6 @@ If propagation is disabled then the packer will not set the requested width and height of the packer. This may be useful if, for example, you wish for a master window to have a fixed size that you specify. - .SH "RESTRICTIONS ON MASTER WINDOWS" .PP The master for each slave must either be the slave's parent @@ -251,7 +247,6 @@ The master for each slave must either be the slave's parent This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent. - .SH "PACKING ORDER" .PP If the master for a slave is not its parent then you must make sure @@ -263,6 +258,25 @@ to create the master window first: the most recently created window will be highest in the stacking order. Or, you can use the \fBraise\fR and \fBlower\fR commands to change the stacking order of either the master or the slave. +.SH EXAMPLE +.CS +# Make the widgets +label .t \-text "This widget is at the top" \-bg red +label .b \-text "This widget is at the bottom" \-bg green +label .l \-text "Left\\nHand\\nSide" +label .r \-text "Right\\nHand\\nSide" +text .mid +\.mid insert end "This layout is like Java's BorderLayout" +# Lay them out +\fBpack\fR .t \-side top \-fill x +\fBpack\fR .b \-side bottom \-fill x +\fBpack\fR .l \-side left \-fill y +\fBpack\fR .r \-side right \-fill y +\fBpack\fR .mid \-expand 1 \-fill both +.CE + +.SH "SEE ALSO" +grid(n), place(n) .SH KEYWORDS geometry manager, location, packer, parcel, propagation, size diff --git a/doc/panedwindow.n b/doc/panedwindow.n index 20e43cf..c22718a 100644 --- a/doc/panedwindow.n +++ b/doc/panedwindow.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: panedwindow.n,v 1.2.2.1 2003/07/17 20:49:00 dkf Exp $ +'\" RCS: @(#) $Id: panedwindow.n,v 1.2.2.2 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH panedwindow n 8.4 Tk "Tk Built-In Commands" @@ -63,7 +63,6 @@ horizontally or vertically, according to the value of the \fB\-orient\fR option. Each pane contains one widget, and each pair of panes is separated by a moveable (via mouse movements) sash. Moving a sash causes the widgets on either side of the sash to be resized. - .SH "WIDGET COMMAND" .PP The \fBpanedwindow\fR command creates a new Tcl command whose name is @@ -125,7 +124,7 @@ the following forms: Return a list containing the x and y coordinates of the most recent proxy location. .TP -\fIpathname \fBproxy forget\fR +\fIpathName \fBproxy forget\fR Remove the proxy from the display. .TP \fIpathName \fBproxy place \fIx y\fR @@ -142,6 +141,7 @@ Return the current x and y coordinate pair for the sash given by \fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than the number of panes in the panedwindow. The coordinates given are those of the top left corner of the region containing the sash. +.TP \fIpathName \fBsash dragto \fIindex x y\fR This command computes the difference between the given coordinates and the coordinates given to the last \fBsash coord\fR command for the given @@ -229,16 +229,14 @@ panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .TP \fIpathName \fBpanes\fR Returns an ordered list of the widgets managed by \fIpathName\fR. - .SH "RESIZING PANES" - A pane is resized by grabbing the sash (or sash handle if present) and dragging with the mouse. This is accomplished via mouse motion bindings on the widget. When a sash is moved, the sizes of the panes on each side of the sash, and thus the widgets in those panes, are adjusted. .PP -When a pane is resized from outside (eg, it is packed to expand and +When a pane is resized from outside (e.g. it is packed to expand and fill, and the containing toplevel is resized), space is added to the final (rightmost or bottommost) pane in the window. diff --git a/doc/photo.n b/doc/photo.n index bd49def..48c99ae 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -9,7 +9,7 @@ '\" Department of Computer Science, '\" Australian National University. '\" -'\" RCS: @(#) $Id: photo.n,v 1.14.2.3 2003/07/17 22:55:27 dkf Exp $ +'\" RCS: @(#) $Id: photo.n,v 1.14.2.4 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH photo n 4.0 Tk "Tk Built-In Commands" @@ -36,7 +36,6 @@ in regions where no image data has been supplied or where it has been set transparent by the \fBtransparency set\fR subcommand. .VE 8.4 - .SH "CREATING PHOTOS" .PP Like all images, photos are created using the \fBimage create\fR @@ -93,7 +92,6 @@ Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it. - .SH "IMAGE COMMAND" .PP When a photo image is created, Tk also creates a new command @@ -216,7 +214,7 @@ the specified color. \fB\-format\fI format-name\fR Specifies the name of the image file format handler to be used. Specifically, this subcommand searches -for the first handler whose name matches a initial substring of +for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to read this image data. If this option is not given, this subcommand uses the first handler that has the capability to read the image data. @@ -347,7 +345,7 @@ the specified color. \fB\-format\fI format-name\fR Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches -for the first handler whose name matches a initial substring of +for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write an image file. If this option is not given, this subcommand uses the first handler that has the capability to write an image file. @@ -397,7 +395,6 @@ to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does. .VE 8.4 - .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code @@ -427,12 +424,28 @@ each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes. - .SH CREDITS .PP The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout. +.SH EXAMPLE +Load an image from a file and tile it to the size of a window, which +is useful for producing a tiled background: +.CS +# These lines should be called once +\fBimage create photo\fR untiled -file "theFile.ppm" +\fBimage create photo\fR tiled + +# These lines should be called whenever .someWidget changes +# size; a binding is useful here +set width [winfo width .someWidget] +set height [winfo height .someWidget] +tiled \fBcopy\fR untiled \-to 0 0 $width $height \-shrink +.CE + +.SH "SEE ALSO" +image(n) .SH KEYWORDS photo, image, color diff --git a/doc/place.n b/doc/place.n index 3a256e1..028654d 100644 --- a/doc/place.n +++ b/doc/place.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: place.n,v 1.3 2000/08/10 00:21:06 ericm Exp $ +'\" RCS: @(#) $Id: place.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH place n "" Tk "Tk Built-In Commands" @@ -14,15 +14,7 @@ .SH NAME place \- Geometry manager for fixed or rubber-sheet placement .SH SYNOPSIS -\fBplace \fIwindow option value \fR?\fIoption value ...\fR? -.sp -\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -.sp -\fBplace forget \fIwindow\fR -.sp -\fBplace info \fIwindow\fR -.sp -\fBplace slaves \fIwindow\fR +\fBplace \fIoption arg \fR?\fIarg ...\fR? .BE .SH DESCRIPTION @@ -104,7 +96,7 @@ If \fIsize\fR is an empty string, or if no \fB\-height\fR or internally by the window will be used. .TP \fB\-in \fImaster\fR -\fIMaster\fR specifes the path name of the window relative +\fIMaster\fR specifies the path name of the window relative to which \fIwindow\fR is to be placed. \fIMaster\fR must either be \fIwindow\fR's parent or a descendant of \fIwindow\fR's parent. @@ -203,13 +195,12 @@ command. \fBplace slaves \fIwindow\fR Returns a list of all the slave windows for which \fIwindow\fR is the master. If there are no slaves for \fIwindow\fR then an empty string is returned. - +.PP If the configuration of a window has been retrieved with \fBplace info\fR, that configuration can be restored later by first using \fBplace forget\fR to erase any existing information for the window and then invoking \fBplace configure\fR with the saved information. - .SH "FINE POINTS" .PP It is not necessary for the master window to be the parent @@ -245,6 +236,16 @@ the master windows or the parents of slave windows (i.e. it doesn't set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. +.SH EXAMPLE +Make the label occupy the middle bit of the toplevel, no matter how it +is resized: +.CS +label .l \-text "In the\\nMiddle!" \-bg black \-fg white +\fBplace\fR .l \-relwidth .3 \-relx .35 \-relheight .3 \-rely .35 +.CE + +.SH "SEE ALSO" +grid(n), pack(n) .SH KEYWORDS geometry manager, height, location, master, place, rubber sheet, slave, width diff --git a/doc/popup.n b/doc/popup.n index a1b49bd..2fb37d9 100644 --- a/doc/popup.n +++ b/doc/popup.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: popup.n,v 1.2 1998/09/14 18:22:59 stanton Exp $ +'\" RCS: @(#) $Id: popup.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH tk_popup n 4.0 Tk "Tk Built-In Commands" @@ -28,6 +28,23 @@ menu's upper left corner is positioned at the given point. Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and the menu will be positioned so that the entry is positioned over the given point. +.SH EXAMPLE +How to attach a simple popup menu to a widget. +.CS +# Create a menu +set m [menu .popupMenu] +$m add command \-label "Example 1" \-command bell +$m add command \-label "Example 2" \-command bell + +# Create something to attach it to +pack [label .l \-text "Click me!"] + +# Arrange for the menu to pop up when the label is clicked +bind .l <1> {\fBtk_popup\fR .popupMenu %X %Y} +.CE + +.SH "SEE ALSO" +bind(n), menu(n), tk_optionMenu(n) .SH KEYWORDS menu, popup diff --git a/doc/raise.n b/doc/raise.n index 534aa12..1a14049 100644 --- a/doc/raise.n +++ b/doc/raise.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: raise.n,v 1.2 1998/09/14 18:22:59 stanton Exp $ +'\" RCS: @(#) $Id: raise.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH raise n 3.3 Tk "Tk Built-In Commands" @@ -30,9 +30,22 @@ In this case the \fBraise\fR command will insert \fIwindow\fR into the stacking order just above \fIaboveThis\fR (or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); this could end up either raising or lowering \fIwindow\fR. +.SH EXAMPLE +Make a button appear to be in a sibling frame that was created after +it. This is is often necessary when building GUIs in the style where +you create your activity widgets first before laying them out on the +display: +.CS +button .b -text "Hi there!" +pack [frame .f -background blue] +pack [label .f.l1 -text "This is above"] +pack .b -in .f +pack [label .f.l2 -text "This is below"] +\fBraise\fR .b +.CE .SH "SEE ALSO" -lower +lower(n) .SH KEYWORDS obscure, raise, stacking order diff --git a/doc/scale.n b/doc/scale.n index ba6a124..e0077e5 100644 --- a/doc/scale.n +++ b/doc/scale.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: scale.n,v 1.3 2000/08/25 06:58:32 ericm Exp $ +'\" RCS: @(#) $Id: scale.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH scale n 4.1 Tk "Tk Built-In Commands" @@ -63,7 +63,7 @@ rounding occurs. Defaults to 1 (i.e., the value will be integral). Specifies a boolean value indicating whether or not the current value of the scale is to be displayed. .OP \-sliderlength sliderLength SliderLength -Specfies the size of the slider, measured in screen units along the slider's +Specifies the size of the slider, measured in screen units along the slider's long dimension. The value may be specified in any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-sliderrelief sliderRelief SliderRelief @@ -117,7 +117,7 @@ of real values (determined by the \fBfrom\fR, \fBto\fR, and \fBresolution\fR options), and the position of the slider selects a particular real value. The slider's position (and hence the scale's value) may be adjusted -with the mouse or keyboard as described in the BINDINGS +with the mouse or keyboard as described in the \fBBINDINGS\fR section below. Whenever the scale's value is changed, a Tcl command is invoked (using the \fBcommand\fR option) to notify other interested widgets of the change. @@ -133,7 +133,6 @@ of numerical tick marks just to the left of the current value (just below the trough for horizontal scales). Each of these three annotations may be enabled or disabled using the configuration options. - .SH "WIDGET COMMAND" .PP The \fBscale\fR command creates a new Tcl command whose @@ -197,7 +196,6 @@ This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. \fIValue\fR gives the new value for the scale. The command has no effect if the scale is disabled. - .SH BINDINGS .PP Tk automatically creates class bindings for scales that give them diff --git a/doc/scrollbar.n b/doc/scrollbar.n index 2c2d73b..6acc7e4 100644 --- a/doc/scrollbar.n +++ b/doc/scrollbar.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: scrollbar.n,v 1.3 2000/08/25 06:58:32 ericm Exp $ +'\" RCS: @(#) $Id: scrollbar.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH scrollbar n 4.1 Tk "Tk Built-In Commands" @@ -69,7 +69,7 @@ A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a \fIslider\fR in the middle portion of the scrollbar. It provides information about what is visible in an \fIassociated window\fR -that displays an document of some sort (such as a file being edited or +that displays a document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the @@ -78,9 +78,8 @@ between the two arrows, it means that the associated window displays the top third of its document. .PP Scrollbars can be used to adjust the view in the associated window -by clicking or dragging with the mouse. See the BINDINGS section +by clicking or dragging with the mouse. See the \fBBINDINGS\fR section below for details. - .SH "ELEMENTS" .PP A scrollbar displays five elements, which are referred to in the @@ -100,7 +99,6 @@ The region between the slider and \fBarrow2\fR. .TP 10 \fBarrow2\fR The bottom or right arrow in the scrollbar. - .SH "WIDGET COMMAND" .PP The \fBscrollbar\fR command creates a new Tcl command whose @@ -190,7 +188,6 @@ For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means that the first part of the document visible in the window is 20% of the way through the document, and the last visible part is 40% of the way through. - .SH "SCROLLING COMMANDS" .PP When the user interacts with the scrollbar, for example by dragging @@ -227,7 +224,6 @@ is a slight overlap between the old and new views. \fINumber\fR is either 1, which means the next page should become visible, or \-1, which means that the previous page should become visible. - .SH "OLD COMMAND SYNTAX" .PP In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget @@ -268,13 +264,11 @@ to use the old syntax. If it is given two real arguments then the new syntax will be used in the future, and if it is given four integer arguments then the old syntax will be used. - .SH BINDINGS Tk automatically creates class bindings for scrollbars that give them the following default behavior. If the behavior is different for vertical and horizontal scrollbars, the horizontal behavior is described in parentheses. - .IP [1] Pressing button 1 over \fBarrow1\fR causes the view in the associated widget to shift up (left) by one unit so that the @@ -336,6 +330,16 @@ as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. The Home key adjusts the view to the top (left edge) of the document. .IP [14] The End key adjusts the view to the bottom (right edge) of the document. +.SH EXAMPLE +Create a window with a scrollable \fBtext\fR widget: +.CS +toplevel .tl +text .tl.t -yscrollcommand {.tl.s set} +\fBscrollbar\fR .tl.s -command {.tl.t yview} +grid .tl.t .tl.s -sticky nsew +grid columnconfigure .tl 0 -weight 1 +grid rowconfigure .tl 0 -weight 1 +.CE .SH KEYWORDS scrollbar, widget diff --git a/doc/selection.n b/doc/selection.n index 44fda07..c4847e7 100644 --- a/doc/selection.n +++ b/doc/selection.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: selection.n,v 1.4 2001/06/04 03:15:20 hobbs Exp $ +'\" RCS: @(#) $Id: selection.n,v 1.4.4.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH selection n 8.1 Tk "Tk Built-In Commands" @@ -128,9 +128,43 @@ that it has lost the selection. If \fIcommand\fR is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from \fIwindow\fR. \fISelection\fR defaults to PRIMARY. +.SH EXAMPLES +On X11 platforms, one of the standard selections available is the +SECONDARY selection. Hardly anything uses it, but here is how to read +it using Tk: +.CS +set selContents [\fBselection get\fR \-selection SECONDARY] +.CE +.PP +Many different types of data may be available for a selection; the +special type TARGETS allows you to get a list of available types: +.CS +foreach type [\fBselection get\fR \-type TARGETS] { + puts "Selection PRIMARY supports type $type" +} +.CE +.PP +To claim the selection, you must first set up a handler to supply the +data for the selection. Then you have to claim the selection... +.CS +# Set up the data handler ready for incoming requests +set foo "This is a string with some data in it... blah blah" +\fBselection handle\fR \-selection SECONDARY . getData +proc getData {offset maxChars} { + puts "Retrieving selection starting at $offset" + return [string range $::foo $offset [expr {$offset+$maxChars}]] +} + +# Now we grab the selection itself +puts "Claiming selection" +\fBselection own\fR \-command lost \-selection SECONDARY . +proc lost {} { + puts "Lost selection" +} +.CE .SH "SEE ALSO" -clipboard +clipboard(n) .SH KEYWORDS clear, format, handler, ICCCM, own, selection, target, type diff --git a/doc/send.n b/doc/send.n index 7a74003..979d9de 100644 --- a/doc/send.n +++ b/doc/send.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: send.n,v 1.3 1999/04/16 01:51:09 stanton Exp $ +'\" RCS: @(#) $Id: send.n,v 1.3.20.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH send n 4.0 Tk "Tk Built-In Commands" @@ -91,6 +91,23 @@ such as that provide by \fBxauth\fR. Under Windows, \fBsend\fR is currently disabled. Most of the functionality is provided by the \fBdde\fR command instead. .VE +.SH EXAMPLE +This script fragment can be used to make an application that only runs +once on a particular display. +.CS +if {[tk appname FoobarApp] ne "FoobarApp"} { + \fBsend\fR -async FoobarApp RemoteStart $argv + exit +} +# The command that will be called remotely, which raises +# the application main window and opens the requested files +proc RemoteStart args { + raise . + foreach filename $args { + OpenFile $filename + } +} +.CE .SH KEYWORDS .VS application, dde, name, remote execution, security, send diff --git a/doc/spinbox.n b/doc/spinbox.n index 9da7b41..5876879 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: spinbox.n,v 1.3 2001/12/18 23:02:35 hobbs Exp $ +'\" RCS: @(#) $Id: spinbox.n,v 1.3.2.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH spinbox n 8.4 Tk "Tk Built-In Commands" @@ -168,7 +168,7 @@ loses focus. .IP \fBall\fR 10 \fBvalidateCommand\fR will be called for all above conditions. .PP -It is posible to perform percent substitutions on the \fBvalidateCommand\fR +It is possible to perform percent substitutions on the \fBvalidateCommand\fR and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP @@ -365,7 +365,7 @@ has several forms, depending on \fIoption\fR: \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 +(i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection isn't currently in the spinbox, then a new selection is created to diff --git a/doc/text.n b/doc/text.n index 69fb036..a663c09 100644 --- a/doc/text.n +++ b/doc/text.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: text.n,v 1.15 2003/02/19 18:52:14 mdejong Exp $ +'\" RCS: @(#) $Id: text.n,v 1.15.2.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH text n 8.4 Tk "Tk Built-In Commands" @@ -52,21 +52,21 @@ Requests additional space above each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. -This option may be overriden with \fB\-spacing1\fR options in +This option may be overridden with \fB\-spacing1\fR options in tags. .OP \-spacing2 spacing2 Spacing2 For lines that wrap (so that they cover more than one line on the display) this option specifies additional space to provide between the display lines that represent a single line of text. The value may have any of the standard forms for screen distances. -This option may be overriden with \fB\-spacing2\fR options in +This option may be overridden with \fB\-spacing2\fR options in tags. .OP \-spacing3 spacing3 Spacing3 Requests additional space below each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. -This option may be overriden with \fB\-spacing3\fR options in +This option may be overridden with \fB\-spacing3\fR options in tags. .OP \-state state State Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. @@ -75,7 +75,9 @@ and no insertion cursor will be displayed, even if the input focus is in the widget. .OP \-tabs tabs Tabs Specifies a set of tab stops for the window. The option's value consists -of a list of screen distances giving the positions of the tab stops. Each +of a list of screen distances giving the positions of the tab stops, +each of which is a distance relative to the left edge of the widget +(excluding borders, padding, etc). Each position may optionally be followed in the next list element by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, or \fBnumeric\fR, which specifies how to justify @@ -94,7 +96,9 @@ tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using -the spacing and alignment from the last tab stop in the list. +the spacing and alignment from the last tab stop in the list. Tab +distances must be strictly positive, and must always increase from one +tab stop to the next (if not, an error is thrown). The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR options in tags. If no \fB\-tabs\fR option is specified, or if it is specified as @@ -144,27 +148,26 @@ to be displayed with different fonts and colors. In addition, Tcl commands can be associated with tags so that scripts are invoked when particular actions such as keystrokes and mouse button presses occur in particular ranges of the text. -See TAGS below for more details. +See \fBTAGS\fR below for more details. .PP -The second form of annotation consists of marks, which are floating -markers in the text. +The second form of annotation consists of floating markers in the text +called "marks". Marks are used to keep track of various interesting positions in the text as it is edited. -See MARKS below for more details. +See \fBMARKS\fR below for more details. .PP The third form of annotation allows arbitrary windows to be embedded in a text widget. -See EMBEDDED WINDOWS below for more details. +See \fBEMBEDDED WINDOWS\fR below for more details. .PP The fourth form of annotation allows Tk images to be embedded in a text widget. -See EMBEDDED IMAGES below for more details. +See \fBEMBEDDED IMAGES\fR below for more details. .PP .VS 8.4 The text widget also has a built-in undo/redo mechanism. -See UNDO MECHANISM below for more details. +See \fBTHE UNDO MECHANISM\fR below for more details. .VE 8.4 - .SH INDICES .PP Many of the widget commands for texts take one or more indices @@ -289,14 +292,13 @@ left-to-right order. For example, the index ``\fBend \- 1 chars\fR'' refers to the next-to-last character in the text and ``\fBinsert wordstart \- 1 c\fR'' refers to the character just before the first one in the word containing the insertion cursor. - .SH TAGS .PP The first form of annotation in text widgets is a tag. A tag is a textual string that is associated with some of the characters in a text. Tags may contain arbitrary characters, but it is probably best to -avoid using the the characters `` '' (space), \fB+\fR, or \fB\-\fR: +avoid using the characters `` '' (space), \fB+\fR, or \fB\-\fR: these characters have special meaning in indices, so tags containing them can't be used as indices. There may be any number of tags associated with characters in a @@ -500,8 +502,7 @@ For details, see the description of the \fBtag bind\fR widget command below. .PP The third use for tags is in managing the selection. -See THE SELECTION below. - +See \fBTHE SELECTION\fR below. .SH MARKS .PP The second form of annotation in text widgets is a mark. @@ -521,7 +522,7 @@ Marks may be manipulated with the ``\fIpathName \fBmark\fR'' widget command, and their current locations may be determined by using the mark name as an index in widget commands. .PP -Each mark also has a \fIgravity\fR, which is either \fBleft\fR or +Each mark also has a "gravity", which is either \fBleft\fR or \fBright\fR. The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. @@ -538,7 +539,7 @@ to different things. .PP Two marks have special significance. First, the mark \fBinsert\fR is associated with the insertion cursor, -as described under THE INSERTION CURSOR below. +as described under \fBTHE INSERTION CURSOR\fR below. Second, the mark \fBcurrent\fR is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one @@ -546,7 +547,6 @@ exception: \fBcurrent\fR is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released). Neither of these special marks may be deleted. - .SH "EMBEDDED WINDOWS" .PP The third form of annotation in text widgets is an embedded window. @@ -616,7 +616,6 @@ stretched. .TP \fB\-window \fIpathName\fR Specifies the name of a window to display in the annotation. - .SH "EMBEDDED IMAGES" .PP The final form of annotation in text widgets is an embedded image. @@ -630,21 +629,21 @@ text is modified or scrolled. Each embedded image occupies one character's worth of index space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned -when the image is inserted into the text widget widh \fBimage create\fP. +when the image is inserted into the text widget with \fBimage create\fP. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. .PP When an embedded image is added to a text widget with the \fBimage create\fR widget command, a name unique to this instance of the image is returned. This name may then be used to refer to this image -instance. The name is taken to be the value of the \fB-name\fP option -(described below). If the \fB-name\fP option is not provided, the -\fB-image\fP name is used instead. If the \fIimageName\fP is already +instance. The name is taken to be the value of the \fB\-name\fP option +(described below). If the \fB\-name\fP option is not provided, the +\fB\-image\fP name is used instead. If the \fIimageName\fP is already in use in the text widget, then \fB#\fInn\fR is added to the end of the \fIimageName\fP, where \fInn\fP is an arbitrary integer. This insures the \fIimageName\fP is unique. Once this name is assigned to this instance of the image, it does not -change, even though the \fB-image\fP or \fB-name\fP values can be changed +change, even though the \fB\-image\fP or \fB\-name\fP values can be changed with \fBimage configure\fP. .PP When an embedded image is added to a text widget with the @@ -684,7 +683,6 @@ It may have any of the usual forms defined for a screen distance. \fIPixels\fR specifies the amount of extra space to leave on the top and on the bottom of the embedded image. It may have any of the usual forms defined for a screen distance. - .SH "THE SELECTION" .PP Selection support is implemented via tags. @@ -713,7 +711,6 @@ the text widget are tied to the \fB\-background\fR, \fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR tag: changes in either will automatically be reflected in the other. - .SH "THE INSERTION CURSOR" .PP The mark named \fBinsert\fR has special significance in text widgets. @@ -723,33 +720,30 @@ command. The \fBinsert\fR mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the text widget has the input focus. - .SH "THE MODIFIED FLAG" The text widget can keep track of changes to the content of the widget by means of the modified flag. Inserting or deleting text will set -this flag. The flag can be queried, set and cleared programatically +this flag. The flag can be queried, set and cleared programmatically as well. Whenever the flag changes state a \fB<>\fR virtual event is generated. See the \fBedit modified\fR widget command for more details. - .SH "THE UNDO MECHANISM" .PP .VS 8.4 The text widget has an unlimited undo and redo mechanism (when the -\fB-undo\fR widget option is true) which records every insert and +\fB\-undo\fR widget option is true) which records every insert and delete action on a stack. .PP -Boundaries (called "separators") are inserted between edit actions. -The purpose of these separators is to group inserts and deletes into -one compound edit action. When undoing a change everything between -two separators will be undone. The undone changes are then moved to -the redo stack, so that an undone edit can be redone again. The redo -stack is cleared whenever new edit actions are recorded on the undo -stack. The undo and redo stacks can be cleared to keep their depth -under control. +Boundaries (called "separators") are inserted between edit actions. The +purpose of these separators is to group inserts, deletes and replaces +into one compound edit action. When undoing a change everything between +two separators will be undone. The undone changes are then moved to the +redo stack, so that an undone edit can be redone again. The redo stack +is cleared whenever new edit actions are recorded on the undo stack. The +undo and redo stacks can be cleared to keep their depth under control. .PP -Separators are inserted automatically when the \fB-autoseparators\fR -widget option is true. You can insert separators programatically as +Separators are inserted automatically when the \fB\-autoseparators\fR +widget option is true. You can insert separators programmatically as well. If a separator is already present at the top of the undo stack no other will be inserted. That means that two separators on the undo stack are always separated by at least one insert or delete action. @@ -764,7 +758,6 @@ the flag has been reset again. See below for the \fBedit\fR widget command that controls the undo mechanism. .VE 8.4 - .SH "WIDGET COMMAND" .PP The \fBtext\fR command creates a new Tcl command whose @@ -860,7 +853,7 @@ The command returns an empty string. If more indices are given, multiple ranges of text will be deleted. All indices are first checked for validity before any deletions are made. They are sorted and the text is removed from the last range to the -first range to deleted text does not cause a undesired index shifting +first range to deleted text does not cause an undesired index shifting side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text @@ -932,7 +925,7 @@ Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by \fIindex2\fR. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set -of text seqments that each end with a newline. The newline is part +of text segments that each end with a newline. The newline is part of the value. .TP \fB\-window\fR @@ -958,9 +951,9 @@ user can set or clear the modified flag. If \fIboolean\fR is specified, sets the modified flag of the widget to \fIboolean\fR. .TP \fIpathName \fBedit redo\fR -When the \fB-undo\fR option is true, reapplies the last undone edits +When the \fB\-undo\fR option is true, reapplies the last undone edits provided no other edits were done since then. Generates an error when -the redo stack is empty. Does nothing when the \fB-undo\fR option is +the redo stack is empty. Does nothing when the \fB\-undo\fR option is false. .TP \fIpathName \fBedit reset\fR @@ -968,13 +961,13 @@ Clears the undo and redo stacks. .TP \fIpathName \fBedit separator\fR Inserts a separator (boundary) on the undo stack. Does nothing when -the \fB-undo\fR option is false. +the \fB\-undo\fR option is false. .TP \fIpathName \fBedit undo\fR -Undoes the last edit action when the \fB-undo\fR option is true. An +Undoes the last edit action when the \fB\-undo\fR option is true. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an -error when the undo stack is empty. Does nothing when the \fB-undo\fR +error when the undo stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE .VE 8.4 @@ -1009,7 +1002,7 @@ The following forms of the command are currently supported: Returns the value of a configuration option for an embedded image. \fIIndex\fR identifies the embedded image, and \fIoption\fR specifies a particular configuration option, which must be one of -the ones listed in the section EMBEDDED IMAGES. +the ones listed in the section \fBEMBEDDED IMAGES\fR. .TP \fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? Query or modify the configuration options for an embedded image. @@ -1023,7 +1016,7 @@ identical to the corresponding sublist of the value returned if no If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. -See EMBEDDED IMAGES for information on the options that +See \fBEMBEDDED IMAGES\fR for information on the options that are supported. .TP \fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? @@ -1033,7 +1026,7 @@ Any number of \fIoption\-value\fR pairs may be specified to configure the annotation. Returns a unique identifier that may be used as an index to refer to this image. -See EMBEDDED IMAGES for information on the options that +See \fBEMBEDDED IMAGES\fR for information on the options that are supported, and a description of the identifier returned. .TP \fIpathName \fBimage names\fR @@ -1045,7 +1038,7 @@ embedded in \fIwindow\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 INDICES above. +\fIIndex\fR may have any of the forms described under \fBINDICES\fR above. .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? Inserts all of the \fIchars\fR arguments just before the character at @@ -1185,12 +1178,13 @@ Ignore case differences between the pattern and the text. The argument following \fB\-count\fR gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no -embedded images or windows in the matching range, this is equivalent to the +embedded images or windows in the matching range (and there are no +elided characters if \fB\-elide\fR is not given), this is equivalent to the number of characters matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count chars\fR will return the entire matched text. .TP \fB\-elide\fR -Find elidden (hidden) text as well. By default only displayed text is +Find elided (hidden) text as well. By default only displayed text is searched. .TP \fB\-\|\-\fR @@ -1271,7 +1265,7 @@ The only events for which bindings may be specified are those related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. Event bindings for a text widget use the \fBcurrent\fR mark described -under MARKS above. An \fBEnter\fR event triggers for a tag when the tag +under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag first becomes present on the current character, and a \fBLeave\fR event triggers for a tag when it ceases to be present on the current character. \fBEnter\fR and \fBLeave\fR events can happen either because the @@ -1322,7 +1316,7 @@ is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s) in \fItagName\fR; in this case the command returns an empty string. -See TAGS above for details on the options available for tags. +See \fBTAGS\fR above for details on the options available for tags. .TP \fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR? Deletes all tag information for each of the \fItagName\fR @@ -1424,7 +1418,7 @@ The following forms of the command are currently supported: Returns the value of a configuration option for an embedded window. \fIIndex\fR identifies the embedded window, and \fIoption\fR specifies a particular configuration option, which must be one of -the ones listed in the section EMBEDDED WINDOWS. +the ones listed in the section \fBEMBEDDED WINDOWS\fR. .TP \fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? Query or modify the configuration options for an embedded window. @@ -1438,7 +1432,7 @@ identical to the corresponding sublist of the value returned if no If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. -See EMBEDDED WINDOWS for information on the options that +See \fBEMBEDDED WINDOWS\fR for information on the options that are supported. .TP \fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR? @@ -1446,7 +1440,7 @@ This command creates a new window annotation, which will appear in the text at the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may be specified to configure the annotation. -See EMBEDDED WINDOWS for information on the options that +See \fBEMBEDDED WINDOWS\fR for information on the options that are supported. Returns an empty string. .TP @@ -1563,7 +1557,6 @@ the one given by \fInumber\fR visible at the top of the window. \fINumber\fR must be an integer. This command used to be used for scrolling, but now it is obsolete. .RE - .SH BINDINGS .PP Tk automatically creates class bindings for texts that give them @@ -1717,18 +1710,19 @@ front of the insertion cursor without moving the insertion cursor. Meta-backspace and Meta-Delete delete the word to the left of the insertion cursor. .IP [30] -Control-x deletes whatever is selected in the text widget. +Control-x deletes whatever is selected in the text widget +after copying it to the clipboard. .IP [31] Control-t reverses the order of the two characters to the right of the insertion cursor. .IP [32] .VS 8.4 Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is -true) undoes the last edit action if the \fB-undo\fR option is true. +true) undoes the last edit action if the \fB\-undo\fR option is true. Does nothing otherwise. .IP [33] Control-Z (or Control-y on Windows) reapplies the last undone edit -action if the \fB-undo\fR option is true. Does nothing otherwise. +action if the \fB\-undo\fR option is true. Does nothing otherwise. .VE 8.4 .PP If the widget is disabled using the \fB\-state\fR option, then its @@ -1738,7 +1732,6 @@ take place. .PP The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings. - .SH "PERFORMANCE ISSUES" .PP Text widgets should run efficiently under a variety @@ -1772,5 +1765,9 @@ especially if they have many marks and tags within them. The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the \fBinsertOffTime\fP attribute to 0 avoid this. + +.SH "SEE ALSO" +entry(n), scrollbar(n) + .SH KEYWORDS text, widget, tkvars diff --git a/doc/toplevel.n b/doc/toplevel.n index 78d4e56..f40ad58 100644 --- a/doc/toplevel.n +++ b/doc/toplevel.n @@ -1,3 +1,4 @@ +'\" -*- nroff -*- '\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. @@ -5,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: toplevel.n,v 1.4 2001/09/26 21:36:19 pspjuth Exp $ +'\" RCS: @(#) $Id: toplevel.n,v 1.4.4.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH toplevel n 8.4 Tk "Tk Built-In Commands" @@ -61,8 +62,8 @@ If this option is less than or equal to zero then the window will not request any size at all. .OP \-menu menu Menu Specifies a menu widget to be used as a menubar. On the Macintosh, the -menubar will be displayed accross the top of the main monitor. On -Microsoft Windows and all UNIX platforms, the menu will appear accross +menubar will be displayed across the top of the main monitor. On +Microsoft Windows and all UNIX platforms, the menu will appear across the toplevel window as part of the window dressing maintained by the window manager. .OP \-screen "" "" @@ -75,7 +76,7 @@ database, and it may not be modified with the \fBconfigure\fR widget command. .OP \-use use Use This option is used for embedding. If the value isn't an empty string, -it must be the the window identifier of a container window, specified as +it must be the window identifier of a container window, specified as a hexadecimal string like the ones returned by the \fBwinfo id\fR command. The toplevel widget will be created as a child of the given container instead of the root window for the screen. If the container diff --git a/doc/winfo.n b/doc/winfo.n index aacdabf..0a1b06d 100644 --- a/doc/winfo.n +++ b/doc/winfo.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: winfo.n,v 1.3 2001/12/04 03:07:43 mdejong Exp $ +'\" RCS: @(#) $Id: winfo.n,v 1.3.2.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH winfo n 4.3 Tk "Tk Built-In Commands" @@ -197,7 +197,8 @@ in pixels. This is the value used by \fIwindow\fR's geometry manager to compute its geometry. .TP \fBwinfo rgb \fIwindow color\fR -Returns a list containing three decimal values, which are the +Returns a list containing three decimal values in the range 0 to +65535, which are the red, green, and blue intensities that correspond to \fIcolor\fR in the window given by \fIwindow\fR. \fIColor\fR may be specified in any of the forms acceptable for a color @@ -326,6 +327,19 @@ Returns a decimal string giving the y-coordinate, in \fIwindow\fR's parent, of the upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it has no border). +.SH EXAMPLE +Print where the mouse pointer is and what window it is currently over: +.CS +set x [\fBwinfo pointerx\fR .] +set y [\fBwinfo pointery\fR .] +puts -nonewline "Mouse pointer at ($x,$y) which is " +set win [\fBwinfo containing\fR $x $y] +if {$win eq ""} { + puts "over no window" +} else { + puts "over $win" +} +.CE .SH KEYWORDS atom, children, class, geometry, height, identifier, information, interpreters, diff --git a/doc/wm.n b/doc/wm.n index 90125a2..7edf339 100644 --- a/doc/wm.n +++ b/doc/wm.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: wm.n,v 1.11 2002/07/16 18:06:41 vincentdarley Exp $ +'\" RCS: @(#) $Id: wm.n,v 1.11.2.1 2004/10/28 12:25:22 dkf Exp $ '\" .so man.macros .TH wm n 8.4 Tk "Tk Built-In Commands" @@ -58,12 +58,13 @@ flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows: .PP -On Windows, \fB-disabled\fR gets or sets whether the window is in a -disabled state. \fB-toolwindow\fR gets or sets the style of the window -to toolwindow (as defined in the MSDN). \fB-topmost\fR gets or sets +On Windows, \fB\-disabled\fR gets or sets whether the window is in a +disabled state. \fB\-toolwindow\fR gets or sets the style of the window +to toolwindow (as defined in the MSDN). \fB\-topmost\fR gets or sets whether this is a topmost window (displays above all other windows). .PP -On Macintosh, +On Macintosh, there are currently two attribute values: +\fB\-modified\fR and \fB\-titlepath\fR. .PP On Unix, there are currently no special attribute values. .RE @@ -234,8 +235,8 @@ Otherwise it returns the name of the current icon bitmap associated with \fIwindow\fR, or an empty string if \fIwindow\fR has no icon bitmap. On the Windows operating system, an additional flag is supported: -\fBwm iconbitmap \fIwindow\fR ?\fI-default\fR? ?\fIimage\fR?. -If the \fI-default\fR +\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?. +If the \fB\-default\fR flag is given, the icon is applied to all toplevel windows (existing and future) to which no other specific icon has yet been applied. In addition to bitmap image types, a full path specification to @@ -312,8 +313,6 @@ specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the maximum width and height currently in effect. The maximum size defaults to the size of the screen. -If resizing has been disabled with the \fBwm resizable\fR command, -then this command has no effect. See the sections on geometry management below for more information. .TP \fBwm minsize \fIwindow\fR ?\fIwidth height\fR? @@ -328,8 +327,6 @@ specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the minimum width and height currently in effect. The minimum size defaults to one pixel in each dimension. -If resizing has been disabled with the \fBwm resizable\fR command, -then this command has no effect. See the sections on geometry management below for more information. .TP \fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? @@ -483,7 +480,6 @@ Note: it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with \fBwm deiconify\fR) to get some window managers to pay attention to changes in window attributes such as group. - .SH "GEOMETRY MANAGEMENT" .PP By default a top-level window appears on the screen in its @@ -510,7 +506,6 @@ all forms of resizing, including the window's natural size as well as manual resizes and the \fBwm geometry\fR command. You can also use the command \fBwm resizable\fR to completely disable interactive resizing in one or both dimensions. - .SH "GRIDDED GEOMETRY MANAGEMENT" .PP Gridded geometry management occurs when one of the widgets of an @@ -544,13 +539,46 @@ in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands are treated as grid units rather than pixel units. Interactive resizing is also carried out in even numbers of grid units rather than pixels. - .SH BUGS .PP Most existing window managers appear to have bugs that affect the operation of the \fBwm\fR command. For example, some changes won't take effect if the window is already active: the window will have to be withdrawn and de-iconified in order to make the change happen. +.SH EXAMPLES +A fixed-size window that says that it is fixed-size too: +.CS +toplevel .fixed +\fBwm title\fR .fixed "Fixed-size Window" +\fBwm resizable\fR .fixed 0 0 +.CE +.PP +A simple dialog-like window, centred on the screen: +.CS +# Create and arrange the dialog contents. +toplevel .msg +label .msg.l \-text "This is a very simple dialog demo." +button .msg.ok \-text OK \-default active \-command {destroy .msg} +pack .msg.ok \-side bottom \-fill x +pack .msg.l \-expand 1 \-fill both + +# Now set the widget up as a centred dialog. + +# But first, we need the geometry managers to finish setting +# up the interior of the dialog, for which we need to run the +# event loop with the widget hidden completely... +\fBwm withdraw\fR .msg +update +set x [expr {([winfo screenwidth .]\-[winfo width .msg])/2}] +set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}] +\fBwm geometry\fR .msg +$x+$y +\fBwm transient\fR .msg . +\fBwm title\fR .msg "Dialog demo" +\fBwm deiconify\fR .msg +.CE + +.SH "SEE ALSO" +toplevel(n), winfo(n) .SH KEYWORDS aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager -- cgit v0.12