diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | doc/bind.n | 266 | ||||
| -rw-r--r-- | doc/bindtags.n | 23 | ||||
| -rw-r--r-- | doc/button.n | 27 | ||||
| -rw-r--r-- | doc/canvas.n | 77 | ||||
| -rw-r--r-- | doc/checkbutton.n | 21 | ||||
| -rw-r--r-- | doc/chooseDirectory.n | 20 | ||||
| -rw-r--r-- | doc/clipboard.n | 19 | ||||
| -rw-r--r-- | doc/console.n | 20 | ||||
| -rw-r--r-- | doc/destroy.n | 13 | ||||
| -rw-r--r-- | doc/dialog.n | 10 | ||||
| -rw-r--r-- | doc/entry.n | 21 | ||||
| -rw-r--r-- | doc/event.n | 14 | ||||
| -rw-r--r-- | doc/focus.n | 32 | ||||
| -rw-r--r-- | doc/font.n | 30 | ||||
| -rw-r--r-- | doc/getOpenFile.n | 12 | ||||
| -rw-r--r-- | doc/grab.n | 18 | ||||
| -rw-r--r-- | doc/grid.n | 61 | ||||
| -rw-r--r-- | doc/image.n | 12 | ||||
| -rw-r--r-- | doc/keysyms.n | 6 | ||||
| -rw-r--r-- | doc/label.n | 24 | ||||
| -rw-r--r-- | doc/listbox.n | 8 | ||||
| -rw-r--r-- | doc/loadTk.n | 7 | ||||
| -rw-r--r-- | doc/menu.n | 37 | ||||
| -rw-r--r-- | doc/menubar.n | 9 | ||||
| -rw-r--r-- | doc/menubutton.n | 30 | ||||
| -rw-r--r-- | doc/message.n | 4 | ||||
| -rw-r--r-- | doc/messageBox.n | 7 | ||||
| -rw-r--r-- | doc/options.n | 24 | ||||
| -rw-r--r-- | doc/radiobutton.n | 28 |
30 files changed, 600 insertions, 284 deletions
@@ -1,3 +1,7 @@ +2004-10-28 Donal K. Fellows <donal.k.fellows@man.ac.uk> + + * doc/*.n: Backport of minor documentation fixes. + 2004-10-27 Don Porter <dgp@users.sourceforge.net> * library/xmfbox.tcl (MotifFDialog_BuildUI): Fix [Bug 987169] in @@ -6,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: bind.n,v 1.7.2.1 2004/02/16 23:20:02 wolfsuit Exp $ +'\" RCS: @(#) $Id: bind.n,v 1.7.2.2 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH bind n 8.0 Tk "Tk Built-In Commands" @@ -15,16 +15,10 @@ .SH NAME bind \- Arrange for X events to invoke Tcl scripts .SH SYNOPSIS -\fBbind\fI tag\fR -.sp -\fBbind\fI tag sequence\fR -.sp -\fBbind\fI tag sequence script\fR -.sp -\fBbind\fI tag sequence \fB+\fIscript\fR +\fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR? .BE -.SH INTRODUCTION +.SH "INTRODUCTION" .PP The \fBbind\fR command associates Tcl scripts with X events. If all three arguments are specified, \fBbind\fR will @@ -56,19 +50,18 @@ the window. Although the \fBbindtags\fR command may be used to assign an arbitrary set of binding tags to a window, the default binding tags provide the following behavior: -.IP +.IP \(bu 3 If a tag is the name of an internal window the binding applies to that window. -.IP +.IP \(bu 3 If the tag is the name of a toplevel window the binding applies to the toplevel window and all its internal windows. -.IP +.IP \(bu 3 If the tag is the name of a class of widgets, such as \fBButton\fR, the binding applies to all widgets in that class; -.IP +.IP \(bu 3 If \fItag\fR has the value \fBall\fR, the binding applies to all windows in the application. - .SH "EVENT PATTERNS" .PP The \fIsequence\fR argument specifies a sequence of one or more @@ -105,6 +98,10 @@ virtual event to modify it. Bindings on a virtual event may be created before the virtual event is defined, and if the definition of a virtual event changes dynamically, all windows bound to that virtual event will respond immediately to the new definition. +.PP +Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events +when their internal state is updated in some ways. Please see the +manual page for each widget for details. .VE .SH "MODIFIERS" .PP @@ -137,9 +134,9 @@ If no modifiers are specified, then any combination of modifiers may be present in the event. .PP \fBMeta\fR and \fBM\fR refer to whichever of the -\fBM1\fR through \fBM5\fR modifiers is associated with the meta +\fBM1\fR through \fBM5\fR modifiers is associated with the Meta key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). -If there are no meta keys, or if they are not associated with any +If there are no Meta keys, or if they are not associated with any modifiers, then \fBMeta\fR and \fBM\fR will not match any events. Similarly, the \fBAlt\fR modifier refers to whichever modifier is associated with the alt key(s) on the keyboard (keysyms @@ -163,7 +160,7 @@ couple non-standard X event types that were added to better support the Macintosh and Windows platforms. Below is a list of all the valid types; where two names appear together, they are synonyms. .DS -.ta 5c 10c +.ta \w'ButtonPress, Button\0\0\0'u +\w'KeyPress, Key\0\0\0'u \fBActivate Destroy Map ButtonPress, Button Enter MapRequest ButtonRelease Expose Motion @@ -175,7 +172,6 @@ ConfigureRequest KeyRelease Unmap Create Leave Visibility Deactivate\fR .DE -.PP .VS Most of the above events have the same fields and behaviors as events in the X Windowing system. You can find more detailed descriptions of @@ -183,8 +179,7 @@ these events in any X window programming book. A couple of the events are extensions to the X event system to support features unique to the Macintosh and Windows platforms. We provide a little more detail on these events here. These include: -.IP \fBActivate\fR 5 -.IP \fBDeactivate\fR 5 +.IP "\fBActivate\fR, \fBDeactivate\fR" 5 These two events are sent to every sub-window of a toplevel when they change state. In addition to the focus Window, the Macintosh platform and Windows platforms have a notion of an active window (which often @@ -200,11 +195,12 @@ Some mice on the Windows platform support a mouse wheel which is used for scrolling documents without using the scrollbars. By rolling the wheel, the system will generate \fBMouseWheel\fR events that the application can use to scroll. On Windows, the event is -always routed to the window that currently has focus. On Mac OS X, +always routed to the window that currently has focus (like \fBKey\fR +events.) On Mac OS X, the event is routed to the window under the pointer. When the event is received you can use the \fB%D\fR substitution to get the -\fIdelta\fR field for the event which is a integer value of motion -that the mouse wheel has moved. The smallest value for which the +\fIdelta\fR field for the event, which is a integer value describing how +the mouse wheel has moved. The smallest value for which the system will report is defined by the OS. On Windows 95 & 98 machines this value is at least 120 before it is reported. However, higher resolution devices may be available in the future. On Mac OS X, the value is @@ -212,6 +208,144 @@ not scaled by 120, but a value of 1 corresponds to roughly one text line. The sign of the value determines which direction your widget should scroll. Positive values should scroll up and negative values should scroll down. .VE +.IP "\fBKeyPress\fP, \fBKeyRelease\fP" 5 +The \fBKeyPress\fP and \fBKeyRelease\fP events are generated +whenever a key is pressed or released. \fBKeyPress\fP and \fBKeyRelease\fP +events are sent to the window which currently has the keyboard focus. +.IP "\fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP" 5 +The \fBButtonPress\fP and \fBButtonRelease\fP events +are generated when the user presses or releases a mouse button. +\fBMotion\fP events are generated whenever the pointer is moved. +\fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP events are +normally sent to the window containing the pointer. +.RS +.PP +When a mouse button is pressed, the window containing the pointer +automatically obtains a temporary pointer grab. +Subsequent \fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP +events will be sent to that window, +regardless of which window contains the pointer, +until all buttons have been released. +.RE +.IP \fBConfigure\fP 5 +A \fBConfigure\fP event is sent to a window whenever its +size, position, or border width changes, and sometimes +when it has changed position in the stacking order. +.IP "\fBMap\fP, \fBUnmap\fP" 5 +The \fBMap\fP and \fBUnmap\fP events are generated whenever the mapping +state of a window changes. +.RS +.PP +Windows are created in the unmapped state. +Top-level windows become mapped when they transition to the +\fBnormal\fP state, and are unmapped in the \fBwithdrawn\fP +and \fBiconic\fP states. +Other windows become mapped when they are placed under control +of a geometry manager (for example \fBpack\fP or \fBgrid\fP). +.PP +A window is \fIviewable\fP only if it and all of its ancestors are mapped. +Note that geometry managers typically do not map their children until +they have been mapped themselves, and unmap all children +when they become unmapped; hence in Tk \fBMap\fP and \fBUnmap\fP +events indicate whether or not a window is viewable. +.RE +.IP \fBVisibility\fP 5 +A window is said to be \fIobscured\fP when another window +above it in the stacking order fully or partially overlaps it. +\fBVisibility\fP events are generated whenever a window's +obscurity state changes; the \fIstate\fP field (\fB%s\fP) +specifies the new state. +.IP \fBExpose\fP 5 +An \fBExpose\fP event is generated whenever all or part of a +window should be redrawn (for example, when a window is +first mapped or if it becomes unobscured). +It is normally not necessary for client applications to +handle \fBExpose\fP events, since Tk handles them internally. +.IP \fBDestroy\fP 5 +A \fBDestroy\fP event is delivered to a window when +it is destroyed. +.RS +.PP +When the \fBDestroy\fP event is delivered +to a widget, it is in a ``half-dead'' state: the widget still exists, +but most operations on it will fail. +.RE +.IP "\fBFocusIn\fP, \fBFocusOut\fP" 5 +The \fBFocusIn\fP and \fBFocusOut\fP events are generated +whenever the keyboard focus changes. +A \fBFocusOut\fP event is sent to the old focus window, +and a \fBFocusIn\fP event is sent to the new one. +.RS +.PP +In addition, +if the old and new focus windows do not share a common parent, +``virtual crossing'' focus events are sent to the intermediate +windows in the hierarchy. +Thus a \fBFocusIn\fP event indicates +that the target window or one of its descendants has acquired the focus, +and a \fBFocusOut\fP event indicates that the focus +has been changed to a window outside the target window's hierarchy. +.PP +The keyboard focus may be changed explicitly by a call to \fBfocus\fP, +or implicitly by the window manager. +.RE +.IP "\fBEnter\fP, \fBLeave\fP" 5 +An \fBEnter\fP event is sent to a window when the pointer +enters that window, and a \fBLeave\fP event is sent when +the pointer leaves it. +.RS +.PP +If there is a pointer grab in effect, \fBEnter\fP and \fBLeave\fP +events are only delivered to the window owning the grab. +.PP +In addition, when the pointer moves +between two windows, \fBEnter\fP and \fBLeave\fP +``virtual crossing'' events are sent to intermediate windows +in the hierarchy in the same manner as for \fBFocusIn\fP and +\fBFocusOut\fP events. +.RE +.IP \fBProperty\fP +A \fBProperty\fP event is sent to a window whenever an X property +belonging to that window is changed or deleted. +\fBProperty\fP events are not normally delivered to Tk applications as +they are handled by the Tk core. +.IP \fBColormap\fP +A \fBColormap\fP event is generated whenever the colormap +associated with a window has been changed, installed, or uninstalled. +.RS +.PP +Widgets may be assigned a private colormap by +specifying a \fB-colormap\fP option; the window manager +is responsible for installing and uninstalling colormaps +as necessary. +.PP +Note that Tk provides no useful details for this event type. +.RE +'\" The following events were added in TIP#47 +.IP "\fBMapRequest\fP, \fBCirculateRequest\fP, \fBResizeRequest\fP, \fBConfigureRequest\fP, \fBCreate\fP" 5 +These events are not normally delivered to Tk applications. +They are included for completeness, to make it possible to +write X11 window managers in Tk. +(These events are only delivered when a client has +selected \fBSubstructureRedirectMask\fP on a window; +the Tk core does not use this mask.) +.IP "\fBGravity\fP, \fBReparent\fP, \fBCirculate\fP" 5 +The events \fBGravity\fP and \fBReparent\fP +are not normally delivered to Tk applications. +They are included for completeness. +.RS +.PP +A \fBCirculate\fP event indicates that the window has moved +to the top or to the bottom of the stacking order as +a result of an \fBXCirculateSubwindows\fP protocol request. +Note that the stacking order may be changed for other reasons +which do not generate a \fBCirculate\fP event, and that +Tk does not use \fBXCirculateSubwindows()\fP internally. +This event type is included only for completeness; +there is no reliable way to track changes to a window's +position in the stacking order. +.RE +.SH "EVENT DETAILS" .PP The last part of a long event specification is \fIdetail\fR. In the case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the @@ -233,7 +367,7 @@ they include all the alphanumeric ASCII characters (e.g. ``a'' is the keysym for the ASCII character ``a''), plus descriptions for non-alphanumeric characters (``comma'' is the keysym for the comma character), plus descriptions for all the non-ASCII keys on the -keyboard (``Shift_L'' is the keysm for the left shift key, and +keyboard (``Shift_L'' is the keysym for the left shift key, and ``F1'' is the keysym for the F1 function key, if it exists). The complete list of keysyms is not presented here; it is available in other X documentation and may vary from system to @@ -244,7 +378,6 @@ If a keysym \fIdetail\fR is given, then the \fItype\fR field may be omitted; it will default to \fBKeyPress\fR. For example, \fB<Control-comma>\fR is equivalent to \fB<Control-KeyPress-comma>\fR. - .SH "BINDING SCRIPTS AND SUBSTITUTIONS" .PP The \fIscript\fR argument to \fBbind\fR is a Tcl script, @@ -274,11 +407,16 @@ types. The \fIabove\fR field from the event, formatted as a hexadecimal number. Valid only for \fBConfigure\fR events. +Indicates the sibling window immediately below the receiving window +in the stacking order, or \fB0\fP if the receiving window is at the +bottom. .IP \fB%b\fR 5 The number of the button that was pressed or released. Valid only for \fBButtonPress\fR and \fBButtonRelease\fR events. .IP \fB%c\fR 5 The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. +Indicates that there are \fIcount\fP pending \fBExpose\fP events which have not +yet been delivered to the window. .IP \fB%d\fR 5 The \fIdetail\fR field from the event. The \fB%d\fR is replaced by a string identifying the detail. For \fBEnter\fR, @@ -303,16 +441,19 @@ For events other than these, the substituted string is undefined. .RE .IP \fB%f\fR 5 The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only -for \fBEnter\fR and \fBLeave\fR events. +for \fBEnter\fR and \fBLeave\fR events. \fB1\fP if the receiving +window is the focus window or a descendant of the focus window, +\fB0\fP otherwise. .IP \fB%h\fR 5 .VS The \fIheight\fR field from the event. Valid for the \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and \fBExpose\fR events. +Indicates the new or requested height of the window. .VE .IP \fB%i\fR 5 The \fIwindow\fR field from the event, represented as a hexadecimal -integer. +integer. Valid for all event types. .IP \fB%k\fR 5 The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. @@ -337,21 +478,33 @@ The \fIstate\fR field from the event. For \fBButtonPress\fR, is substituted. For \fBVisibility\fR, one of the strings \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, and \fBVisibilityFullyObscured\fR is substituted. +For \fBProperty\fP events, substituted with +either the string \fBNewValue\fP (indicating that the property +has been created or modified) or \fBDelete\fP (indicating that +the property has been removed). .IP \fB%t\fR 5 -The \fItime\fR field from the event. Valid only for events that -contain a \fItime\fR field. +The \fItime\fR field from the event. +This is the X server timestamp (typically the time since +the last server reset) in milliseconds, when the event occurred. +Valid for most events. .IP \fB%w\fR 5 -The \fIwidth\fR field from the event. Valid only for +The \fIwidth\fR field from the event. +Indicates the new or requested width of the window. +Valid only for .VS \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and \fBExpose\fR events. .VE -.IP \fB%x\fR 5 -The \fIx\fR field from the event. Valid only for events containing -an \fIx\fR field. -.IP \fB%y\fR 5 -The \fIy\fR field from the event. Valid only for events containing -a \fIy\fR field. +.IP "\fB%x\fR, \fB%y\fR" 5 +The \fIx\fR and \fIy\fR fields from the event. +For \fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP, +\fBKeyPress\fP, \fBKeyRelease\fP, and \fBMouseWheel\fP events, +\fB%x\fP and \fB%y\fP indicate the position of the mouse pointer +relative to the receiving window. +For \fBEnter\fP and \fBLeave\fP events, the position where the +mouse pointer crossed the window, relative to the receiving window. +For \fBConfigure\fP and \fBCreate\fP requests, the \fIx\fP and \fIy\fP +coordinates of the window relative to its parent window. .IP \fB%A\fR 5 Substitutes the UNICODE character corresponding to the event, or the empty string if the event doesn't correspond to a UNICODE character @@ -362,8 +515,8 @@ Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. .IP \fB%B\fR 5 The \fIborder_width\fR field from the event. Valid only for \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events. -.VS .IP \fB%D\fR 5 +.VS This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The \fIdelta\fR value represents the rotation units the mouse wheel has been moved. On Windows 95 & 98 systems the smallest value for the @@ -373,12 +526,18 @@ wheel was scrolled. .VE .IP \fB%E\fR 5 The \fIsend_event\fR field from the event. Valid for all event types. +\fB0\fP indicates that this is a ``normal'' event, \fB1\fP indicates +that it is a ``synthetic'' event generated by \fBSendEvent\fP. .IP \fB%K\fR 5 The keysym corresponding to the event, substituted as a textual string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. .IP \fB%N\fR 5 The keysym corresponding to the event, substituted as a decimal number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +.IP \fB%P\fR 5 +The name of the property being updated or deleted (which +may be converted to an XAtom using \fBwinfo atom\fR.) Valid +only for \fBProperty\fP events. .IP \fB%R\fR 5 The \fIroot\fR window identifier from the event. Valid only for events containing a \fIroot\fR field. @@ -398,6 +557,7 @@ value is the corresponding x-coordinate in the virtual root. Valid only for \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, and \fBMotion\fR events. +Same meaning as \fB%x\fP, except relative to the (virtual) root window. .IP \fB%Y\fR 5 The \fIy_root\fR field from the event. If a virtual-root window manager is being used then the substituted @@ -405,6 +565,7 @@ value is the corresponding y-coordinate in the virtual root. Valid only for \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, and \fBMotion\fR events. +Same meaning as \fB%y\fP, except relative to the (virtual) root window. .LP The replacement string for a %-replacement is formatted as a proper Tcl list element. @@ -430,7 +591,6 @@ This will cause the \fBinsert\fR to receive the original replacement string (open square bracket) as its first argument. If the extra backslash hadn't been added, Tcl would not have been able to parse the script correctly. - .SH "MULTIPLE MATCHES" .PP It is possible for several bindings to match a given X event. @@ -483,8 +643,8 @@ be picked at random: event add <<Paste>> <Control-y> event add <<Paste>> <Button-2> event add <<Scroll>> <Button-2> -bind Entry <<Paste>> {puts Paste} -bind Entry <<Scroll>> {puts Scroll} +\fBbind\fR Entry <<Paste>> {puts Paste} +\fBbind\fR Entry <<Scroll>> {puts Scroll} .CE If the user types Control-y, the \fB<<Paste>>\fR binding will be invoked, but if the user presses button 2 then one of @@ -494,7 +654,6 @@ be invoked, but exactly which one gets invoked is undefined. If an X event does not match any of the existing bindings, then the event is ignored. An unbound event is not considered to be an error. - .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" .PP When a \fIsequence\fR specified in a \fBbind\fR command contains @@ -519,16 +678,33 @@ key, and a press of the \fBb\fR key: the press of \fBShift\fR is ignored because it is a modifier key. Finally, if several \fBMotion\fR events occur in a row, only the last one is used for purposes of matching binding sequences. - -.SH ERRORS +.SH "ERRORS" .PP If an error occurs in executing the script for a binding then the \fBbgerror\fR mechanism is used to report the error. The \fBbgerror\fR command will be executed at global level (outside the context of any Tcl procedure). +.SH "EXAMPLES" +Arrange for a string describing the motion of the mouse to be printed +out when the mouse is double-clicked: +.CS +\fBbind\fR . <Double-1> { + puts "hi from (%x,%y)" +} +.CE +.PP +A little GUI that displays what the keysym name of the last key +pressed is: +.CS +set keysym "Press any key" +pack [label .l -textvariable keysym -padx 2m -pady 1m] +\fBbind\fR . <Key> { + set keysym "You pressed %K" +} +.CE .SH "SEE ALSO" -bgerror, keysyms +bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n) .SH KEYWORDS -form, manual +binding, event diff --git a/doc/bindtags.n b/doc/bindtags.n index 7314dc3..ec69f31 100644 --- a/doc/bindtags.n +++ b/doc/bindtags.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: bindtags.n,v 1.2 1998/09/14 18:22:54 stanton Exp $ +'\" RCS: @(#) $Id: bindtags.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH bindtags n 4.0 Tk "Tk Built-In Commands" @@ -73,6 +73,27 @@ This means that the default widget bindings for buttons, which are associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR, but any bindings associated with \fBTrickyButton\fR (perhaps some new button behavior) will apply. +.SH EXAMPLE +If you have a set of nested \fBframe\fR widgets and you want events +sent to a \fBbutton\fR widget to also be delivered to all the widgets +up to the current \fBtoplevel\fR (in contrast to Tk's default +behavior, where events are not delivered to those intermediate +windows) to make it easier to have accelerators that are only active +for part of a window, you could use a helper procedure like this to +help set things up: +.CS +proc setupBindtagsForTreeDelivery {widget} { + set tags [list $widget [winfo class $widget]] + set w $widget + set t [winfo toplevel $w] + while {$w ne $t} { + set w [winfo parent $w] + lappend tags $w + } + lappend tags all + \fBbindtags\fR $widget $tags +} +.CE .SH "SEE ALSO" bind diff --git a/doc/button.n b/doc/button.n index d2818fd..237d888 100644 --- a/doc/button.n +++ b/doc/button.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: button.n,v 1.6 2000/08/25 06:58:31 ericm Exp $ +'\" RCS: @(#) $Id: button.n,v 1.6.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH button n 4.4 Tk "Tk Built-In Commands" @@ -16,31 +16,21 @@ button \- Create and manipulate button widgets .SH SYNOPSIS \fBbutton\fR \fIpathName \fR?\fIoptions\fR? .SO -\-activebackground \-foreground \-repeatdelay -\-activeforeground \-highlightbackground \-repeatinterval -\-anchor \-highlightcolor \-takefocus -\-background \-highlightthickness \-text -\-bitmap \-image \-textvariable -\-borderwidth \-justify \-underline +\-activebackground \-font \-relief +\-activeforeground \-foreground \-repeatdelay +\-anchor \-highlightbackground \-repeatinterval +\-background \-highlightcolor \-takefocus +\-bitmap \-highlightthickness \-text +\-borderwidth \-image \-textvariable +\-compound \-justify \-underline \-cursor \-padx \-wraplength \-disabledforeground \-pady -\-font \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. -.VS 8.4 -.OP \-compound compound Compound -Specifies whether the button should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -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. -.VE .OP \-default default Default .VS Specifies one of three states for the default ring: \fBnormal\fR, @@ -53,7 +43,6 @@ the same size. In disabled state, the button is drawn with the non-default button appearance without leaving space for the default appearance. The disabled state may result in a smaller button than the active state. -ring. .VE .OP \-height height Height Specifies a desired height for the button. diff --git a/doc/canvas.n b/doc/canvas.n index c8ead38..3371596 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -6,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: canvas.n,v 1.13 2002/08/08 04:54:01 hobbs Exp $ +'\" RCS: @(#) $Id: canvas.n,v 1.13.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH canvas n 8.3 Tk "Tk Built-In Commands" @@ -39,14 +39,14 @@ be constrained within the scroll region. .OP \-height height Height Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any -of the forms described in the COORDINATES section below. +of the forms described in the \fBCOORDINATES\fR section below. .OP \-scrollregion scrollRegion ScrollRegion Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified -in any of the forms given in the COORDINATES section below. +in any of the forms given in the \fBCOORDINATES\fR section below. .OP \-state state State Modifies the default state of the canvas where \fIstate\fR may be set to one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas @@ -60,7 +60,7 @@ the appearence when the state is disabled. Canvas items which are .OP \-width width width Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any -of the forms described in the COORDINATES section below. +of the forms described in the \fBCOORDINATES\fR section below. .OP \-xscrollincrement xScrollIncrement ScrollIncrement Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater @@ -106,7 +106,6 @@ so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Tcl scripts bound to them. - .SH "DISPLAY LIST" .PP The items in a canvas are ordered for purposes of display, @@ -125,12 +124,11 @@ window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas widget commands; you must use the \fBraise\fR and \fBlower\fR Tk commands instead. - .SH "ITEM IDS AND TAGS" .PP Items in a canvas widget may be named in either of two ways: by id or by tag. -Each item has a unique identifying number which is assigned to +Each item has a unique identifying number, which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget. @@ -166,7 +164,7 @@ an argument specifies either an id that selects a single item or a tag that selects zero or more items. .PP \fItagOrId\fR may contain a logical expressions of -tags by using operators: '&&', '||', '^' '!', and parenthezised +tags by using operators: '&&', '||', '^' '!', and parenthesized subexpressions. For example: .CS .c find withtag {(a&&!b)||(!a&&b)} @@ -184,7 +182,6 @@ the command to use the first (lowest) of these items in the display list that is suitable for the command. Exceptions are noted in the widget command descriptions below. - .SH "COORDINATES" .PP All coordinates related to canvases are stored as floating-point @@ -203,7 +200,6 @@ Coordinates can be specified either as an even number of parameters, or as a single list parameter containing an even number of x and y coordinate values. .VE - .SH TRANSFORMATIONS .PP Normally the origin of the canvas coordinate system is at the @@ -217,7 +213,16 @@ system relative to the window coordinate system. .PP Individual items may be moved or scaled using widget commands described below, but they may not be rotated. - +.PP +Note that the default origin of the canvas's visible area is +coincident with the origin for the whole window as that makes bindings +using the mouse position easier to work with; you only need to use the +\fBcanvasx\fR and \fBcanvasy\fR widget commands if you adjust the +origin of the visible area. However, this also means that any focus +ring (as controlled by the \fB\-highlightthickness\fR option) and +window border (as controlled by the \fB\-borderwidth\fR option) must +be taken into account before you get to the visible area of the +canvas. .SH "INDICES" .PP Text items support the notion of an \fIindex\fR for identifying @@ -236,7 +241,7 @@ Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons don't support the insertion cursor -and the selection. Their indixes are supposed to be even +and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. .TP 10 \fInumber\fR @@ -249,7 +254,7 @@ A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater then the length -of the coordinate list will be adjusted by adding or substracting +of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. .TP 10 @@ -277,15 +282,14 @@ system of the canvas. If \fIx\fR and \fIy\fR lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. - .SH "DASH PATTERNS" .PP -Many items support the notion of an dash pattern for outlines. +Many items support the notion of a dash pattern for outlines. .PP The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the "outline" color. The other segments -are drawn transparant. +are drawn transparent. .PP The second possible syntax is a character list containing only 5 possible characters \fB[.,-_ ]\fR. The space can be used @@ -299,7 +303,7 @@ occur as the first position in the string. Some examples: -dash , = -dash {4 4} .PP The main difference of this syntax with the previous is that it -it shape-conserving. This means that all values in the dash +is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that "." will always be displayed as a dot and "-" always as a dash regardless of the line width. @@ -309,7 +313,6 @@ pattern will be displayed as the closest dash pattern that is available. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically to the first one. - .SH "WIDGET COMMAND" .PP The \fBcanvas\fR command creates a new Tcl command whose @@ -613,7 +616,7 @@ operations (in display list order). For each of the items given by \fItagOrId\fR, if the item supports text or coordinate, insertion then \fIstring\fR is inserted into the item's text just before the character, or coordinate, whose index is \fIbeforeThis\fR. -Text items interpret \fIbeforethis\fR as an index to a character, +Text items interpret \fIbeforeThis\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the \fIstring\fR must be a valid coordinate sequence. @@ -1006,7 +1009,6 @@ If \fInumber\fR is negative then higher information becomes visible; if it is positive then lower information becomes visible. .RE - .SH "OVERVIEW OF ITEM TYPES" .PP The sections below describe the various types of items supported @@ -1022,7 +1024,6 @@ in the descriptions below. At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. - .SH "COMMON ITEM OPTIONS" .PP Many items share a common set of options. These options are @@ -1044,7 +1045,7 @@ See "DASH PATTERNS" for more information. The starting \fIoffset\fR in pixels into the pattern provided by the \fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no \fB-dash\fR pattern. The \fIoffset\fR may have any of the forms described -in the COORDINATES section above. +in the \fBCOORDINATES\fR section above. .TP \fB\-fill \fIcolor\fR .TP @@ -1054,7 +1055,7 @@ in the COORDINATES section above. Specifies the color to be used to fill item's area. in its normal, active, and disabled states, \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -If \fIcolor\fR is an empty string (the default), then +If \fIcolor\fR is an empty string (the default), then the item will not be filled. For the line item, it specifies the color of the line drawn. For the text item, it specifies the foreground color of the text. @@ -1102,7 +1103,7 @@ in a solid fashion. \fB\-activestipple \fIbitmap\fR .TP \fB\-disabledstipple \fIbitmap\fR -This option specifies stipple patterns that should be used to fill the +This option specifies stipple patterns that should be used to fill the item in its normal, active and disabled states. \fIbitmap\fR specifies the stipple pattern to use, in any of the forms accepted by \fBTk_GetBitmap\fR. @@ -1129,13 +1130,12 @@ existing tags for the item. \fITagList\fR may be an empty list. \fB\-disabledwidth \fIoutlineWidth\fR Specifies the width of the outline to be drawn around the item's region, in its normal, active and disabled states. -\fIoutlineWidth\fR may be in any of the forms described in the COORDINATES -section above. +\fIoutlineWidth\fR may be in any of the forms described in the +\fBCOORDINATES\fR section above. If the \fB\-outline\fR option has been specified as an empty string then this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region. - .SH "ARC ITEMS" .PP Items of type \fBarc\fR appear on the display as arc-shaped regions. @@ -1208,7 +1208,6 @@ connecting the two end points of the perimeter section. If \fItype\fR is \fBarc\fR then the arc's region consists of a section of the perimeter alone. In this last case the \fB\-fill\fR option is ignored. - .SH "BITMAP ITEMS" .PP Items of type \fBbitmap\fR appear on the display as images with @@ -1273,7 +1272,6 @@ Specifies the color to use for each of the bitmap's '1' valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and defaults to \fBblack\fR. - .SH "IMAGE ITEMS" .PP Items of type \fBimage\fR are used to display images on a @@ -1317,7 +1315,6 @@ Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the \fBimage create\fR command. - .SH "LINE ITEMS" .PP Items of type \fBline\fR appear on the display as one or more connected @@ -1371,7 +1368,7 @@ This option defaults to \fBnone\fR. This option indicates how to draw arrowheads. The \fIshape\fR argument must be a list with three elements, each specifying a distance in any of the forms described in -the COORDINATES section above. +the \fBCOORDINATES\fR section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the @@ -1462,7 +1459,6 @@ The following standard options are supported by ovals: \-activewidth \-disabledwidth .CE - .SH "POLYGON ITEMS" .PP Items of type \fBpolygon\fR appear as polygonal or curved filled regions @@ -1520,7 +1516,7 @@ of the outline. If this option isn't specified then it defaults to \fBmiter\fR. .TP \fB\-smooth \fIboolean\fR -\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR +\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR. It indicates whether or not the polygon should be drawn with a curved perimeter. If so, the outline of the polygon becomes a set of parabolic splines, @@ -1542,7 +1538,6 @@ interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead. - .SH "RECTANGLE ITEMS" .PP Items of type \fBrectangle\fR appear as rectangular regions on @@ -1588,7 +1583,6 @@ The following standard options are supported by rectangles: \-activewidth \-disabledwidth .CE - .SH "TEXT ITEMS" .PP A text item displays a string of characters on the screen in one @@ -1658,7 +1652,7 @@ This option defaults to an empty string. .TP \fB\-width \fIlineLength\fR Specifies a maximum line length for the text, in any of the forms -described in the COORDINATES section above. +described in the \fBCOORDINATES\fR section above. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would @@ -1666,7 +1660,6 @@ be longer than \fIlineLength\fR is broken just before a space character to make the line shorter than \fIlineLength\fR; the space character is treated as if it were a newline character. - .SH "WINDOW ITEMS" .PP Items of type \fBwindow\fR cause a particular window to be displayed @@ -1704,14 +1697,14 @@ This option defaults to \fBcenter\fR. \fB\-height \fIpixels\fR Specifies the height to assign to the item's window. \fIPixels\fR may have any of the -forms described in the COORDINATES section above. +forms described in the \fBCOORDINATES\fR section above. If this option isn't specified, or if it is specified as an empty string, then the window is given whatever height it requests internally. .TP \fB\-width \fIpixels\fR Specifies the width to assign to the item's window. \fIPixels\fR may have any of the -forms described in the COORDINATES section above. +forms described in the \fBCOORDINATES\fR section above. If this option isn't specified, or if it is specified as an empty string, then the window is given whatever width it requests internally. .TP @@ -1725,19 +1718,16 @@ Note: due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. - .SH "APPLICATION-DEFINED ITEM TYPES" .PP It is possible for individual applications to define new item types for canvas widgets using C code. See the documentation for \fBTk_CreateItemType\fR. - .SH BINDINGS .PP In the current implementation, new canvases are not given any default behavior: you'll have to execute explicit Tcl commands to give the canvas its behavior. - .SH CREDITS .PP Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's @@ -1746,5 +1736,8 @@ environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases. +.SH "SEE ALSO" +bind(n), font(n), image(n), scrollbar(n) + .SH KEYWORDS canvas, widget diff --git a/doc/checkbutton.n b/doc/checkbutton.n index 9e83699..089c21b 100644 --- a/doc/checkbutton.n +++ b/doc/checkbutton.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: checkbutton.n,v 1.6 2002/08/28 01:08:06 drh Exp $ +'\" RCS: @(#) $Id: checkbutton.n,v 1.6.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH checkbutton n 4.4 Tk "Tk Built-In Commands" @@ -16,14 +16,14 @@ checkbutton \- Create and manipulate checkbutton widgets .SH SYNOPSIS \fBcheckbutton\fI pathName \fR?\fIoptions\fR? .SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline +\-activebackground \-disabledforeground \-padx +\-activeforeground \-font \-pady +\-anchor \-foreground \-relief +\-background \-highlightbackground \-takefocus +\-bitmap \-highlightcolor \-text +\-borderwidth \-highlightthickness \-textvariable +\-compound \-image \-underline \-cursor \-justify \-wraplength -\-disabledforeground \-padx .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command @@ -165,7 +165,6 @@ itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's ``on'' value. - .SH "WIDGET COMMAND" .PP The \fBcheckbutton\fR command creates a new Tcl command whose @@ -225,7 +224,6 @@ value. \fIpathName \fBtoggle\fR Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. - .SH BINDINGS .PP Tk automatically creates class bindings for checkbuttons that give them @@ -256,5 +254,8 @@ actions occur: the checkbutton is completely non-responsive. The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. +.SH "SEE ALSO" +button(n), options(n), radiobutton(n) + .SH KEYWORDS checkbutton, widget diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index 42bf636..c531739 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: chooseDirectory.n,v 1.1 2000/01/27 00:23:10 ericm Exp $ +'\" RCS: @(#) $Id: chooseDirectory.n,v 1.1.10.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" @@ -40,13 +40,21 @@ 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. .TP \fB\-mustexist\fR \fIboolean\fR -Specifies whether the user may specify non-existant directories. If +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. -.LP +.SH EXAMPLE +.CS +set dir [\fBtk_chooseDirectory\fR \\ + \-initialdir ~ \-title "Choose a directory"] +if {$dir eq ""} { + label .l -text "No directory selected" +} else { + label .l -text "Selected $dir" +} +.CE .SH "SEE ALSO" -tk_getOpenFile, tk_getSaveFile - +tk_getOpenFile(n), tk_getSaveFile(n) .SH KEYWORDS -directory selection dialog +directory, selection, dialog, platform-specific diff --git a/doc/clipboard.n b/doc/clipboard.n index f36a219..340fb8b 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.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: clipboard.n,v 1.5 2002/07/04 01:09:47 hobbs Exp $ +'\" RCS: @(#) $Id: clipboard.n,v 1.5.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH clipboard n 8.4 Tk "Tk Built-In Commands" @@ -78,17 +78,30 @@ This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE .TP +\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR? .VS 8.4 -\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR? Retrieve data from the clipboard on \fIwindow\fR's display. \fIwindow\fR defaults to ".". \fIType\fR specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. \fIType\fR defaults to STRING. This command is equivalent to \fBselection get -selection CLIPBOARD\fR. .VE 8.4 +.SH EXAMPLES +Get the current contents of the clipboard. +.CS +if {[catch {\fBclipboard get\fR} contents]} { + # There were no clipboard contents at all +} +.CE +.PP +Set the clipboard to contain a fixed string. +.CS +\fBclipboard clear\fR +\fBclipboard append\fR "some fixed string" +.CE .SH "SEE ALSO" -selection +selection(n) .SH KEYWORDS clear, format, clipboard, append, selection, type diff --git a/doc/console.n b/doc/console.n index 005aef2..e37a6e0 100644 --- a/doc/console.n +++ b/doc/console.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: console.n,v 1.4 2002/03/29 02:25:06 davygrvy Exp $ +'\" RCS: @(#) $Id: console.n,v 1.4.4.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH console n 8.4 Tk "Tk Built-In Commands" @@ -13,13 +13,7 @@ .SH NAME console \- Control the console on systems without a real console .SH SYNOPSIS -\fBconsole title \fR?\fIstring\fR? -.sp -\fBconsole hide\fR -.sp -\fBconsole show\fR -.sp -\fBconsole eval \fIscript\fR +\fBconsole\fR \fIsubcommand\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION @@ -52,7 +46,6 @@ not specified, queries the title of the console window, and sets the title of the console window to \fIstring\fR otherwise. Precisely equivalent to using the \fBwm title\fR command in the console interpreter. - .SH "ACCESS TO THE MAIN INTERPRETER" .PP The \fBconsoleinterp\fR command in the console interpreter allows @@ -68,7 +61,6 @@ interpreter. Records and evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter as if \fIscript\fR had been typed in at the console. - .SH "ADDITIONAL TRAP CALLS" .PP There are several additional commands in the console interpreter that @@ -88,7 +80,6 @@ When the \fB.\fR window of the main interpreter is destroyed, the \fBtk::ConsoleExit\fR command in the console interpreter is called (assuming the console interpreter has not already been deleted itself, that is.) - .SH "DEFAULT BINDINGS" .PP The default script creates a console window (implemented using a text @@ -134,6 +125,13 @@ and reloading the Tcl script that defined the console's behaviour. Most other behaviour is the same as a conventional text widget except for the way that the \fI<<Cut>>\fR event is handled identically to the \fI<<Copy>>\fR event. +.SH EXAMPLE +Not all platforms have the \fBconsole\fR command, so debugging code +often has the following code fragment in it so output produced by +\fBputs\fR can be seen while during development: +.CS +catch {\fBconsole show\fR} +.CE .SH KEYWORDS console, interpreter, window, interactive, output channels diff --git a/doc/destroy.n b/doc/destroy.n index e2cde3d..6240068 100644 --- a/doc/destroy.n +++ b/doc/destroy.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: destroy.n,v 1.2 1998/09/14 18:22:55 stanton Exp $ +'\" RCS: @(#) $Id: destroy.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH destroy n "" Tk "Tk Built-In Commands" @@ -29,6 +29,17 @@ in destroying a window the command aborts without destroying the remaining windows. No error is returned if \fIwindow\fR does not exist. .VE +.SH EXAMPLE +Destroy all checkbuttons that are direct children of the given widget: +.CS +proc killCheckbuttonChildren {parent} { + foreach w [winfo children $parent] { + if {[winfo class $w] eq "Checkbutton"} { + \fBdestroy\fR $w + } + } +} +.CE .SH KEYWORDS application, destroy, window diff --git a/doc/dialog.n b/doc/dialog.n index 0e93888..12f2e7c 100644 --- a/doc/dialog.n +++ b/doc/dialog.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: dialog.n,v 1.2 1998/09/14 18:22:55 stanton Exp $ +'\" RCS: @(#) $Id: dialog.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH tk_dialog n 4.1 Tk "Tk Built-In Commands" @@ -60,6 +60,14 @@ of the buttons, then -1 is returned. While waiting for the user to respond, \fBtk_dialog\fR sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. +.SH EXAMPLE +.CS +set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \\ + questhead 0 Yes No "I'm not sure"] +.CE + +.SH "SEE ALSO" +tk_messageBox(n) .SH KEYWORDS bitmap, dialog, modal diff --git a/doc/entry.n b/doc/entry.n index 084457b..10eb70d 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -6,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: entry.n,v 1.11 2003/02/19 18:52:13 mdejong Exp $ +'\" RCS: @(#) $Id: entry.n,v 1.11.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH entry n 8.3 Tk "Tk Built-In Commands" @@ -78,8 +78,8 @@ state which mode you wish to use. See \fBValidation\fR below for more. .OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand Specifies a script to eval when you want to validate the input into the entry widget. Setting it to {} disables this feature (the default). -This command must return a valid tcl boolean value. If it returns 0 (or -the valid tcl boolean equivalent) then it means you reject the new edition +This command must return a valid Tcl boolean value. If it returns 0 (or +the valid Tcl boolean equivalent) then it means you reject the new edition and it will not occur and the \fBinvalidCommand\fR will be evaluated if it is set. If it returns 1, then the new edition occurs. See \fBValidation\fR below for more information. @@ -123,9 +123,8 @@ may be used to change the view in the window. Entries use the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). They also support scanning, as described below. - -.VS 8.3 .SH VALIDATION +.VS 8.3 .PP Validation works by setting the \fBvalidateCommand\fR option to a script which will be evaluated according to the \fBvalidate\fR @@ -156,11 +155,11 @@ or -1 for focus, forced or textvariable validation. .IP \fB%i\fR 5 Index of char string to be inserted/deleted, if any, otherwise -1. .IP \fB%P\fR 5 -The value of the entry should edition occur. If you are configuring the +The value of the entry if the edit is allowed. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable. .IP \fB%s\fR 5 -The current value of entry before edition. +The current value of entry prior to editing. .IP \fB%S\fR 5 The text string being inserted/deleted, if any, {} otherwise. .IP \fB%v\fR 5 @@ -183,7 +182,7 @@ when an error occurs evaluating the \fBvalidateCommand\fR. .PP Primarily, an error will occur when the \fBvalidateCommand\fR or \fBinvalidCommand\fR encounters an error in its script while evaluating or -\fBvalidateCommand\fR does not return a valid tcl boolean value. The +\fBvalidateCommand\fR does not return a valid Tcl boolean value. The \fBvalidate\fR option will also set itself to \fBnone\fR when you edit the entry widget from within either the \fBvalidateCommand\fR or the \fBinvalidCommand\fR. Such editions will override the one that was being @@ -191,14 +190,13 @@ validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the \fBvalidate\fR option set, you should include the command .CS - \fIafter idle {%W config -validate %v}\fR +after idle {%W config -validate %v} .CE in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you were editing the entry widget from). It is also recommended to not set an associated \fBtextVariable\fR during validation, as that can cause the entry widget to become out of sync with the \fBtextVariable\fR. .VE - .SH "WIDGET COMMAND" .PP The \fBentry\fR command creates a new Tcl command whose @@ -334,7 +332,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 entry, then a new selection is created to @@ -424,7 +422,6 @@ If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE - .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for entries that give them diff --git a/doc/event.n b/doc/event.n index 1d0ead2..ae3a1ad 100644 --- a/doc/event.n +++ b/doc/event.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: event.n,v 1.6 2000/11/03 01:13:51 hobbs Exp $ +'\" RCS: @(#) $Id: event.n,v 1.6.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH event n 8.3 Tk "Tk Built-In Commands" @@ -79,7 +79,6 @@ If \fB<<\fIvirtual\fB>>\fR is specified then the return value is a list whose elements are the physical event sequences currently defined for the given virtual event; if the virtual event is not defined then an empty string is returned. - .SH "EVENT FIELDS" .PP The following options are supported for the \fBevent generate\fR @@ -197,7 +196,7 @@ Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, events. Corresponds to the \fB%X\fR substitution for binding scripts. .TP \fB\-rooty\fI coord\fR -\fICoord\fR must be a screen distance; it specifies th \fIy_root\fR +\fICoord\fR must be a screen distance; it specifies the \fIy_root\fR field for the event. Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR @@ -205,7 +204,7 @@ events. Corresponds to the \fB%Y\fR substitution for binding scripts. .TP \fB\-sendevent\fI boolean\fR -\fBBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR +\fIBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR field for the event. Valid for all events. Corresponds to the \fB%E\fR substitution for binding scripts. .TP @@ -280,7 +279,7 @@ Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. -Corresponds to the the \fB%x\fR substitution for binding scripts. +Corresponds to the \fB%x\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%X\fR substitution for binding scripts. @@ -292,7 +291,7 @@ Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. -Corresponds to the the \fB%y\fR substitution for binding scripts. +Corresponds to the \fB%y\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%Y\fR substitution for binding scripts. @@ -300,7 +299,6 @@ for binding scripts. Any options that are not specified when generating an event are filled with the value 0, except for \fIserial\fR, which is filled with the next X event serial number. - .SH "VIRTUAL EVENT EXAMPLES" .PP In order for a virtual event binding to trigger, two things must @@ -360,7 +358,7 @@ but instead invoke the virtual event \fB<<Paste>>\fR. Second, pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding. .SH "SEE ALSO" -bind +bind(n) .SH KEYWORDS event, binding, define, handle, virtual event diff --git a/doc/focus.n b/doc/focus.n index bcc11e1..b7107bb 100644 --- a/doc/focus.n +++ b/doc/focus.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: focus.n,v 1.2 1998/09/14 18:22:56 stanton Exp $ +'\" RCS: @(#) $Id: focus.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH focus n 4.0 Tk "Tk Built-In Commands" @@ -14,11 +14,11 @@ .SH NAME focus \- Manage the input focus .SH SYNOPSIS +.nf \fBfocus\fR -.sp \fBfocus \fIwindow\fR -.sp \fBfocus \fIoption\fR ?\fIarg arg ...\fR? +.fi .BE .SH DESCRIPTION @@ -97,7 +97,6 @@ if the most recent focus window has been deleted, then the name of the top-level is returned. The return value is the window that will receive the input focus the next time the window manager gives the focus to the top-level. - .SH "QUIRKS" .PP When an internal window receives the input focus, Tk doesn't actually @@ -108,6 +107,31 @@ focus were on the internal window. This approach gets around a number of problems that would occur if the X focus were actually moved; the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. +.SH "EXAMPLE" +To make a window that only participates in the focus traversal ring +when a variable is set, add the following bindings to the widgets +\fIbefore\fR and \fIafter\fR it in that focus ring: +.CS +button .before -text "Before" +button .middle -text "Middle" +button .after -text "After" +checkbutton .flag -variable traverseToMiddle -takefocus 0 +pack .flag -side left +pack .before .middle .after +bind .before <Tab> { + if {!$traverseToMiddle} { + \fBfocus\fR .after + break + } +} +bind .after <Shift-Tab> { + if {!$traverseToMiddle} { + \fBfocus\fR .before + break + } +} +\fBfocus\fR .before +.CE .SH KEYWORDS events, focus, keyboard, top-level, window manager @@ -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: font.n,v 1.3 2000/07/25 21:14:35 jenglish Exp $ +'\" RCS: @(#) $Id: font.n,v 1.3.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH font n 8.0 Tk "Tk Built-In Commands" @@ -24,7 +24,7 @@ first argument. The following forms are currently supported: .TP \fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? . -Returns information about the the actual attributes that are obtained when +Returns information about the actual attributes that are obtained when \fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained may differ from the attributes requested due to platform-dependant limitations, such as the availability of font families and pointsizes. @@ -76,7 +76,7 @@ Measures the amount of space the string \fItext\fR would use in the given \fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is omitted, it defaults to the main window. The return value is the total width in pixels -of \fItext\fR, not including the extra pixels used by highly exagerrated +of \fItext\fR, not including the extra pixels used by highly exaggerated characters such as cursive ``f''. If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. @@ -192,7 +192,7 @@ above the baseline line plus the descent below the baseline. \fB\-fixed \0\fR . Returns a boolean flag that is ``\fB1\fR'' if this is a fixed-width font, -where each normal character is the the same width as all the other +where each normal character is the same width as all the other characters, or is ``\fB0\fR'' if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not @@ -258,7 +258,6 @@ font should be underlined. The default value for underline is \fBfalse\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. - .SH "PLATFORM-SPECIFIC ISSUES" .LP The following named system fonts are supported: @@ -280,8 +279,27 @@ Macintosh: \fBsystem application\fR .DE .RE +.SH EXAMPLE +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 +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 {} \\ + "This is a simple sampler\\n" f$count + set w [\fBfont measure\fR [.t cget -font] ${family}:] + if {$w+5 > $tabwidth} { + set tabwidth [expr {$w+5}] + .t configure -tabs $tabwidth + } +} +.CE + .SH "SEE ALSO" -options +options(n) .SH KEYWORDS font diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index 18ac2ca..e167bf9 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.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: getOpenFile.n,v 1.10 2002/04/19 22:16:02 jenglish Exp $ +'\" RCS: @(#) $Id: getOpenFile.n,v 1.10.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" @@ -24,7 +24,7 @@ The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a dialog box for the user to select a file to open or save. The \fBtk_getOpenFile\fR command is usually associated with the \fBOpen\fR command in the \fBFile\fR menu. Its purpose is for the user to select an -existing file \fIonly\fR. If the user enters an non-existent file, the +existing file \fIonly\fR. If the user enters a non-existent file, the dialog box gives the user an error prompt and requires the user to give an alternative selection. If an application allows the user to create new files, it should do so by providing a separate \fBNew\fR menu command. @@ -39,7 +39,7 @@ arguments to these two commands: .TP \fB\-defaultextension\fR \fIextension\fR Specifies a string that will be appended to the filename if the user -enters a filename without an extension. The defaut value is the empty +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 the Macintosh platform, which does not require extensions to filenames, @@ -55,7 +55,7 @@ the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the 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 SPECIFYING FILE PATTERNS below for a +types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. .TP \fB\-initialdir\fR \fIdirectory\fR @@ -128,7 +128,7 @@ in the sample code matches files that EITHER have a \fB\.gif\fR extension OR belong to the \fImacType\fR \fBGIFF\fR. .PP On the Unix and Windows platforms, a file matches a file pattern -if its name matches at at least one of the \fIextension\fR(s) of +if its name matches at least one of the \fIextension\fR(s) of the file pattern. The \fImacType\fRs are ignored. .SH "SPECIFYING EXTENSIONS" .PP @@ -144,7 +144,7 @@ card characters (* and ?). Due to the different pattern matching rules on the various platforms, to ensure portability, wild card characters are not allowed in the extensions, except as in the special extension *. Extensions -without a full stop character (e.g, ~) are allowed but may not +without a full stop character (e.g. ~) are allowed but may not work on all platforms. .SH EXAMPLE @@ -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: grab.n,v 1.2 1998/09/14 18:22:56 stanton Exp $ +'\" RCS: @(#) $Id: grab.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH grab n "" Tk "Tk Built-In Commands" @@ -102,7 +102,11 @@ does nothing. Returns an empty string. Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. - +.SH WARNING +It is very easy to use global grabs to render a display completely +unusable (e.g. by setting a grab on a widget which does not respond to +events and not providing any mechanism for releasing the grab). Take +\fIextreme\fR care when using them! .SH BUGS .PP It took an incredibly complex and gross implementation to produce @@ -117,6 +121,16 @@ If a single process is managing several different Tk applications, only one of those applications can have a local grab for a given display at any given time. If the applications are in different processes, this restriction doesn't exist. +.SH EXAMPLE +Set a grab so that only one button may be clicked out of a group. The +other buttons are unresponsive to the mouse until the middle button is +clicked. +.CS +pack [button .b1 \-text "Click me! #1" \-command {destroy .b1}] +pack [button .b2 \-text "Click me! #2" \-command {destroy .b2}] +pack [button .b3 \-text "Click me! #3" \-command {destroy .b3}] +\fBgrab\fR .b2 +.CE .SH KEYWORDS grab, keyboard events, pointer events, window @@ -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: grid.n,v 1.5 2001/09/30 19:01:58 pspjuth Exp $ +'\" RCS: @(#) $Id: grid.n,v 1.5.4.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH grid n 8.4 Tk "Tk Built-In Commands" @@ -28,7 +28,7 @@ on the \fIoption\fR argument: If the first argument to \fBgrid\fR is suitable as the first slave argument to \fBgrid configure\fR, either a window name (any value starting with \fB.\fP) or one of the characters \fBx\fP or \fB^\fP -(see the ``RELATIVE PLACEMENT'' section below), then the command is +(see the \fBRELATIVE PLACEMENT\fR section below), then the command is processed in the same way as \fBgrid configure\fR. .TP \fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? @@ -49,9 +49,9 @@ geometry master, \fImaster\fP. .VS 8.4 The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP and \fB-pad\fP. -.VE +.VE 8.4 If one or more options are provided, then \fIindex\fP may be given as -a list of column indeces to which the configuration options will operate on. +a list of column indices to which the configuration options will operate on. The \fB\-minsize\fP option sets the minimum size, in screen units, that will be permitted for this column. The \fB\-weight\fP option (an integer value) @@ -67,15 +67,15 @@ the column in a \fIuniform group\fP with other columns that have the same value for \fB-uniform\fP. The space for columns belonging to a uniform group is allocated so that their sizes are always in strict proportion to their \fB-weight\fP values. See -``THE GRID ALGORITHM'' below for further details. -.VE +\fBTHE GRID ALGORITHM\fR below for further details. +.VE 8.4 The \fB-pad\fP option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings -are returned in an list of "-option value" pairs. +are returned in a list of "-option value" pairs. .TP \fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? The arguments consist of the names of one or more slave windows @@ -83,7 +83,7 @@ followed by pairs of arguments that specify how to manage the slaves. The characters \fB\-\fP, \fBx\fP and \fB^\fP, can be specified instead of a window name to alter the default -location of a \fIslave\fP, as described in the ``RELATIVE PLACEMENT'' +location of a \fIslave\fP, as described in the \fBRELATIVE PLACEMENT\fR section, below. The following options are supported: .RS @@ -117,7 +117,7 @@ It defaults to 0. .TP \fB\-ipady \fIamount\fR The \fIamount\fR specifies how much vertical internal padding to -leave on on the top and bottom of the slave(s). +leave on the top and bottom of the slave(s). This space is added inside the slave(s) border. The \fIamount\fR defaults to 0. .TP @@ -192,7 +192,7 @@ For locations that are above or to the left of the grid, \fB-1\fP is returned. \fBgrid propagate \fImaster\fR ?\fIboolean\fR? If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fImaster\fR, which must be a window -name (see ``GEOMETRY PROPAGATION'' below). +name (see \fBGEOMETRY PROPAGATION\fR below). If \fIboolean\fR has a false boolean value then propagation is disabled for \fImaster\fR. In either of these cases an empty string is returned. @@ -207,9 +207,9 @@ geometry master, \fImaster\fP. .VS 8.4 The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP and \fB-pad\fP. -.VE +.VE 8.4 If one or more options are provided, then \fIindex\fP may be given as -a list of row indeces to which the configuration options will operate on. +a list of row indices to which the configuration options will operate on. The \fB\-minsize\fP option sets the minimum size, in screen units, that will be permitted for this row. The \fB\-weight\fP option (an integer value) @@ -225,15 +225,15 @@ the row in a \fIuniform group\fP with other rows that have the same value for \fB-uniform\fP. The space for rows belonging to a uniform group is allocated so that their sizes are always in strict proportion to their \fB-weight\fP values. See -``THE GRID ALGORITHM'' below for further details. -.VE +\fBTHE GRID ALGORITHM\fR below for further details. +.VE 8.4 The \fB-pad\fP option specifies the number of screen units that will be added to the largest window contained completely in that row when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings -are returned in an list of "-option value" pairs. +are returned in a list of "-option value" pairs. .TP \fBgrid remove \fIslave \fR?\fIslave ...\fR? Removes each of the \fIslave\fRs from grid for its @@ -336,7 +336,7 @@ For masters whose size is smaller than the requested layout, space is taken away from columns and rows according to their weights. However, once a column or row shrinks to its minsize, its weight is taken to be zero. If more space needs to be removed from a layout than would be permitted, as -when all the rows or columns are at there minimum sizes, the layout is +when all the rows or columns are at their minimum sizes, the layout is clipped on the bottom and right. .SH "GEOMETRY PROPAGATION" .PP @@ -352,7 +352,6 @@ If propagation is disabled then grid will not set the requested width and height of the master window. 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 @@ -375,5 +374,33 @@ will be highest in the stacking order. The \fBgrid\fP command is based on ideas taken from the \fIGridBag\fP geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry manager, written by George Howlett. +.SH EXAMPLES +A toplevel window containing a text widget and two scrollbars: +.CS +# Make the widgets +toplevel .t +text .t.txt \-wrap none \-xscroll {.t.h set} \-yscroll {.t.v set} +scrollbar .t.v \-orient vertical \-command {.t.txt xview} +scrollbar .t.h \-orient horizontal \-command {.t.txt xview} +# Lay them out +\fBgrid\fR .t.txt .t.v \-sticky nsew +\fBgrid\fR .t.h \-sticky nsew +# Tell the text widget to take all the extra room +\fBgrid rowconfigure\fR .t .t.txt -weight 1 +\fBgrid columnconfigure\fR .t .t.txt -weight 1 +.CE +.PP +Three widgets of equal width, despite their different "natural" widths: +.CS +button .b \-text "Foo" +entry .e \-variable foo +label .l \-text "This is a fairly long piece of text" +\fBgrid\fR .b .e .l \-sticky ew +\fBgrid columnconfigure\fR . {0 1 2} \-uniform allTheSame +.CE + +.SH "SEE ALSO" +pack(n), place(n) + .SH KEYWORDS geometry manager, location, grid, cell, propagation, size, pack diff --git a/doc/image.n b/doc/image.n index 2d28b08..afad619 100644 --- a/doc/image.n +++ b/doc/image.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: image.n,v 1.6 2001/04/03 04:33:58 hobbs Exp $ +'\" RCS: @(#) $Id: image.n,v 1.6.4.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH image n 4.0 Tk "Tk Built-In Commands" @@ -24,7 +24,7 @@ It can take several different forms, depending on the \fIoption\fR argument. The legal forms are: .TP \fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? -Creates a new image and returns its name. +Creates a new image and a command with the same name and returns its name. \fItype\fR specifies the type of the image, which must be one of the types currently defined (e.g., \fBbitmap\fR). \fIname\fR specifies the name for the image; if it is omitted then @@ -77,7 +77,10 @@ argument to \fBimage create\fR). \fBimage width \fIname\fR Returns a decimal string giving the width of image \fIname\fR in pixels. - +.PP +Additional operations (e.g. writing the image to a file) may be +available as subcommands of the image instance command. See the manual +page for the particular image type for details. .SH "BUILT-IN IMAGE TYPES" .PP The following image types are defined by Tk so they will be available @@ -94,5 +97,8 @@ Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. +.SH "SEE ALSO" +bitmap(n), options(n), photo(n) + .SH KEYWORDS height, image, types of images, width diff --git a/doc/keysyms.n b/doc/keysyms.n index 25c5677..e79a2ee 100644 --- a/doc/keysyms.n +++ b/doc/keysyms.n @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: keysyms.n,v 1.3 2000/06/30 20:33:44 ericm Exp $ +'\" RCS: @(#) $Id: keysyms.n,v 1.3.8.1 2004/10/28 10:19:29 dkf Exp $ '\" '\" .so man.macros @@ -15,13 +15,13 @@ keysyms \- keysyms recognized by Tk .SH DESCRIPTION .PP -Tk recognizes many keysyms when specifying key bindings (eg, +Tk recognizes many keysyms when specifying key bindings (e.g. \fBbind . <Key-\fR\fIkeysym\fR\fB>\fR). The following list enumerates the keysyms that will be recognized by Tk. Note that not all keysyms will be valid on all platforms. For example, on Unix systems, the presence of a particular keysym is dependant on the configuration of the keyboard modifier map. This list shows keysyms along with their -decimal and hexidecimal values. +decimal and hexadecimal values. .PP .CS space 32 0x0020 diff --git a/doc/label.n b/doc/label.n index 4b53889..847d363 100644 --- a/doc/label.n +++ b/doc/label.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: label.n,v 1.6 2002/12/18 21:46:48 tmh Exp $ +'\" RCS: @(#) $Id: label.n,v 1.6.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH label n 4.0 Tk "Tk Built-In Commands" @@ -16,24 +16,16 @@ label \- Create and manipulate label widgets .SH SYNOPSIS \fBlabel\fR \fIpathName \fR?\fIoptions\fR? .SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline +\-activebackground \-disabledforeground \-padx +\-activeforeground \-font \-pady +\-anchor \-foreground \-relief +\-background \-highlightbackground \-takefocus +\-bitmap \-highlightcolor \-text +\-borderwidth \-highlightthickness \-textvariable +\-compound \-image \-underline \-cursor \-justify \-wraplength -\-disabledforeground \-padx .SE .SH "WIDGET-SPECIFIC OPTIONS" -.OP \-compound compound Compound -Specifies whether the label should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the label will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. .OP \-height height Height Specifies a desired height for the label. If an image or bitmap is being displayed in the label then the value is in diff --git a/doc/listbox.n b/doc/listbox.n index 7326497..e3dcb4f 100644 --- a/doc/listbox.n +++ b/doc/listbox.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: listbox.n,v 1.9 2002/06/21 02:38:54 hobbs Exp $ +'\" RCS: @(#) $Id: listbox.n,v 1.9.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH listbox n 8.4 Tk "Tk Built-In Commands" @@ -30,7 +30,7 @@ listbox \- Create and manipulate listbox widgets .OP \-activestyle activeStyle ActiveStyle Specifies the style in which to draw the active element. This must be one of \fBdotbox\fR (show a focus ring around the active element), -\fBnone\fR (nospecial indication of active element) or +\fBnone\fR (no special indication of active element) or \fBunderline\fR (underline the active element). The default is \fBunderline\fR. .VS 8.4 @@ -509,11 +509,11 @@ by one page (the height of the window). The Home and End keys scroll the listbox horizontally to the left and right edges, respectively. .IP [10] -Control-Home sets the location cursor to the the first element in +Control-Home sets the location cursor to the first element in the listbox, selects that element, and deselects everything else in the listbox. .IP [11] -Control-End sets the location cursor to the the last element in +Control-End sets the location cursor to the last element in the listbox, selects that element, and deselects everything else in the listbox. .IP [12] diff --git a/doc/loadTk.n b/doc/loadTk.n index 3327678..cff018d 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -1,10 +1,11 @@ +'\" -*- nroff -*- '\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: loadTk.n,v 1.5 2003/01/19 07:51:15 hobbs Exp $ +'\" RCS: @(#) $Id: loadTk.n,v 1.5.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" @@ -35,7 +36,7 @@ dependent identifier \fIwindowId\fR is used to contain the ``.'' window of the safe interpreter; it can be any valid id, eventually referencing a window belonging to another application. As a convenience, if the window you plan to use is a Tk Window of the application you -can use the window name (eg: \fB.x.y\fR) instead of its window Id +can use the window name (e.g. \fB.x.y\fR) instead of its window Id (\fB[winfo id .x.y]\fR). When \fB\-use\fR is not specified, a new toplevel window is created for the ``.'' window of @@ -60,7 +61,7 @@ registers the slave's name so when the Tk initialization (\fBTk_SafeInit\fR) is called and in turn calls the master's \fB::safe::InitTk\fR it will return the desired \fBargv\fR equivalent (\fB\-use\fR -\fIwindowId\fR, correct \fB\-display\fR, etc...). +\fIwindowId\fR, correct \fB\-display\fR, etc.) .PP When \fB\-use\fR is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes @@ -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: menu.n,v 1.8 2003/01/19 07:46:43 hobbs Exp $ +'\" RCS: @(#) $Id: menu.n,v 1.8.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH menu n 4.1 Tk "Tk Built-In Commands" @@ -29,10 +29,10 @@ menu, tk_menuSetFocus \- Create and manipulate menu widgets .OP \-postcommand postCommand Command If this option is specified then it provides a Tcl command to execute each time the menu is posted. The command is invoked by the \fBpost\fR -widget command before posting the menu. Note that in 8.0 on Macintosh -and Windows, all commands in a menu systems are executed before any -are posted. This is due to the limitations in the individual platforms' -menu managers. +widget command before posting the menu. Note that in Tk 8.0 on Macintosh +and Windows, all post-commands in a system of menus are executed before any +of those menus are posted. +This is due to the limitations in the individual platforms' menu managers. .VE .OP \-selectcolor selectColor Background For menu entries that are check buttons or radio buttons, this option @@ -151,7 +151,7 @@ the entry is deselected another value (determined by the \fB\-offvalue\fR option) is stored in the global variable. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed -in the color given by the \fB-selectcolor\fR option for the entry; +in the color given by the \fB\-selectcolor\fR option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a \fB\-command\fR option is specified for a checkbutton entry, then its value is evaluated as a Tcl command each time the entry @@ -236,7 +236,7 @@ Any menu can be set as a menubar for a toplevel window (see \fBtoplevel\fR command for syntax). On the Macintosh, whenever the toplevel is in front, this menu's cascade items will appear in the menubar across the top of the main monitor. On Windows and Unix, this -menu's items will be displayed in a menubar accross the top of the +menu's items will be displayed in a menubar across the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made. See the \fBCLONES\fR section for more information. @@ -277,7 +277,7 @@ the tearoff item displayed as "(TearOff)". When Tk see a Help menu on the Macintosh, the menu's contents are appended to the standard help menu on the right of the user's menubar whenever the user's menubar is in front. The first items in the menu -are provided by Apple. Similar to the Apple Menu, cusomization in this +are provided by Apple. Similar to the Apple Menu, customization in this menu is limited to what the system provides. .PP When Tk sees a System menu on Windows, its items are appended to the @@ -410,18 +410,20 @@ This option is not available for separator or tear-off entries. \fB\-bitmap \fIvalue\fR Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by \fBTk_GetBitmap\fR. -This option overrides the \fB\-label\fR option but may be reset +This option overrides the \fB\-label\fR option +(as controlled by the \fB\-compound\fR option) +but may be reset 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. -.VS 8.0 .TP \fB\-columnbreak \fIvalue\fR -When this option is zero, the appears below the previous entry. When -this option is one, the menu appears at the top of a new column in the +.VS 8.0 +When this option is zero, the entry appears below the previous entry. When +this option is one, the entry appears at the top of a new column in the menu. -.VE +.VE 8.0 .TP \fB\-command \fIvalue\fR Specifies a Tcl command to execute when the menu entry is invoked. @@ -462,10 +464,11 @@ the entry is hidden; 0 means that the margin is used. .TP \fB\-image \fIvalue\fR Specifies an image to display in the menu instead of a text string -or bitmap +or bitmap. The image must have been created by some previous invocation of \fBimage create\fR. This option overrides the \fB\-label\fR and \fB\-bitmap\fR options +(as controlled by the \fB\-compound\fR option) 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. @@ -654,8 +657,8 @@ This is the \fItype\fR argument passed to the \fBadd\fR widget command when the entry was created, such as \fBcommand\fR or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. .TP -.VS \fIpathName \fBunpost\fR +.VS 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 @@ -676,7 +679,7 @@ This is the most command case. You create a menu widget that will become the menu bar. You then add cascade entries to this menu, specifying the pull down menus you wish to use in your menu bar. You then create all of the pulldowns. Once you have done this, specify the menu using the -\fB-menu\fR option of the toplevel's widget command. See the +\fB\-menu\fR option of the toplevel's widget command. See the \fBtoplevel\fR manual entry for details. .VE .TP @@ -731,7 +734,7 @@ The Space and Return keys invoke the active entry and unpost the menu. .IP [5] If any of the entries in a menu have letters underlined with -with \fB\-underline\fR option, then pressing one of the underlined +the \fB\-underline\fR option, then pressing one of the underlined letters (or its upper-case or lower-case equivalent) invokes that entry and unposts the menu. .IP [6] diff --git a/doc/menubar.n b/doc/menubar.n index bedd287..7edcd37 100644 --- a/doc/menubar.n +++ b/doc/menubar.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: menubar.n,v 1.2 1998/09/14 18:22:57 stanton Exp $ +'\" RCS: @(#) $Id: menubar.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH tk_menuBar n "" Tk "Tk Built-In Commands" @@ -28,6 +28,13 @@ longer needed. Stubs for these procedures have been retained for backward compatibility, but they have no effect. You should remove calls to these procedures from your code, since eventually the procedures will go away. +.PP +From Tk 8.0 onwards, you should instead construct your menubar as a +normal \fBmenu\fR and then attach it to the \fBtoplevel\fR of your +choice using the \fB\-menu\fR option of that widget. + +.SH "SEE ALSO" +menu(n), toplevel(n) .SH KEYWORDS keyboard traversal, menu, menu bar, post diff --git a/doc/menubutton.n b/doc/menubutton.n index 64cb5d7..98eb0e7 100644 --- a/doc/menubutton.n +++ b/doc/menubutton.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: menubutton.n,v 1.4 2001/05/21 14:07:32 tmh Exp $ +'\" RCS: @(#) $Id: menubutton.n,v 1.4.4.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH menubutton n 4.0 Tk "Tk Built-In Commands" @@ -16,32 +16,24 @@ menubutton \- Create and manipulate menubutton widgets .SH SYNOPSIS \fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? .SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline -\-cursor \-justify \-wraplength -\-disabledforeground \-padx +\-activebackground \-disabledforeground \-padx +\-activeforeground \-font \-pady +\-anchor \-foreground \-relief +\-background \-highlightbackground \-takefocus +\-bitmap \-highlightcolor \-text +\-borderwidth \-highlightthickness \-textvariable +\-cursor \-image \-underline +\-compound \-justify \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" -.OP \-compound compound Compound -Specifies whether the menubutton should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the menubutton will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. -.VS .OP \-direction direction Height Specifies where the menu is going to be popup up. \fBabove\fR tries to pop the menu above the menubutton. \fBbelow\fR tries to pop the menu below the menubutton. \fBleft\fR tries to pop the menu to the left of the menubutton. \fBright\fR tries to pop the menu to the right of the menu button. \fBflush\fR pops the menu directly over the menubutton. -.VE +In the case of \fBabove\fR or \fBbelow\fR, the direction will be +reversed if the menu would show offscreen. .OP \-height height Height Specifies a desired height for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in diff --git a/doc/message.n b/doc/message.n index 70a412b..135375c 100644 --- a/doc/message.n +++ b/doc/message.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: message.n,v 1.3 2000/08/25 06:58:32 ericm Exp $ +'\" RCS: @(#) $Id: message.n,v 1.3.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH message n 4.0 Tk "Tk Built-In Commands" @@ -50,7 +50,7 @@ rectangular region. For example, suppose \fBanchor\fR is \fBe\fR and \fBjustify\fR is \fBleft\fR, and that the message window is much larger than needed for the text. -The the text will displayed so that the left edges of all the lines +The text will be displayed so that the left edges of all the lines line up and the right edge of the longest line is \fBpadX\fR from the right side of the window; the entire text block will be centered in the vertical span of the window. diff --git a/doc/messageBox.n b/doc/messageBox.n index 4e6eead..140b166 100644 --- a/doc/messageBox.n +++ b/doc/messageBox.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: messageBox.n,v 1.5 2000/04/27 18:28:58 ericm Exp $ +'\" RCS: @(#) $Id: messageBox.n,v 1.5.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH tk_messageBox n 4.2 Tk "Tk Built-In Commands" @@ -78,10 +78,11 @@ and \fBcancel\fR. .PP .SH EXAMPLE .CS -set answer [tk_messageBox \-message "Really quit?" \-type yesno \-icon question] +set answer [\fBtk_messageBox\fR \-message "Really quit?" \-type yesno \-icon question] switch -- $answer { yes exit - no {tk_messageBox \-message "I know you like this application!" \-type ok} + no {\fBtk_messageBox\fR \-message "I know you like this application!" \e + \-type ok} } .CE diff --git a/doc/options.n b/doc/options.n index 1801a42..42e54e3 100644 --- a/doc/options.n +++ b/doc/options.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: options.n,v 1.6 2000/07/25 21:14:35 jenglish Exp $ +'\" RCS: @(#) $Id: options.n,v 1.6.8.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH options n 4.4 Tk "Tk Built-In Commands" @@ -31,7 +31,7 @@ command .CS \&\fB.a.b.c\0\0configure\0\0\-foreground black\fR .CE -may be used to specify the value \fBblack\fR for the option in the +may be used to specify the value \fBblack\fR for the option in the widget \fB.a.b.c\fR. Command-line switches may be abbreviated, as long as the abbreviation is unambiguous. ``Database Name'' refers to the option's name in the option database (e.g. @@ -75,7 +75,8 @@ acceptable to \fBTk_GetBitmap\fR. The exact way in which the bitmap is displayed may be affected by other options such as \fBanchor\fR or \fBjustify\fR. Typically, if this option is specified then it overrides other -options that specify a textual value to display in the widget; +options that specify a textual value to display in the widget +but this is controlled by the \fBcompound\fR option; the \fBbitmap\fR option may be reset to an empty string to re-enable a text display. In widgets that support both \fBbitmap\fR and \fBimage\fR options, @@ -90,6 +91,18 @@ The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-cursor cursor Cursor Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to \fBTk_GetCursor\fR. +.OP \-compound compound Compound +.VS 8.4 +Specifies if the widget should display text and bitmaps/images at the +same time, and if so, where the bitmap/image should be placed relative +to the text. Must be one of the values \fBnone\fR, \fBbottom\fR, +\fBtop\fR, \fBleft\fR, \fBright\fR, or \fBcenter\fR. For example, the +(default) value \fBnone\fR specifies that the bitmap or image should +(if defined) be displayed instead of the text, the value \fBleft\fR +specifies that the bitmap or image should be displayed to the left of +the text, and the value \fBcenter\fR specifies that the bitmap or +image should be displayed on top of the text. +.VE 8.4 .OP \-disabledforeground disabledForeground DisabledForeground Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the @@ -127,7 +140,8 @@ If the value is zero, no focus highlight is drawn around the widget. Specifies an image to display in the widget, which must have been created with the \fBimage create\fR command. Typically, if the \fBimage\fR option is specified then it overrides other -options that specify a bitmap or textual value to display in the widget; +options that specify a bitmap or textual value to display in the +widget, though this is controlled by the \fBcompound\fR option; the \fBimage\fR option may be reset to an empty string to re-enable a bitmap or text display. .OP \-insertbackground insertBackground Foreground @@ -240,7 +254,7 @@ communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. -See the section GRIDDED GEOMETRY MANAGEMENT in the \fBwm\fR manual +See the section \fBGRIDDED GEOMETRY MANAGEMENT\fR in the \fBwm\fR manual entry for more details. .OP \-takefocus takeFocus TakeFocus Determines whether the window accepts the focus during keyboard diff --git a/doc/radiobutton.n b/doc/radiobutton.n index 2cc08e2..ee64e1e 100644 --- a/doc/radiobutton.n +++ b/doc/radiobutton.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: radiobutton.n,v 1.6 2002/08/28 01:08:06 drh Exp $ +'\" RCS: @(#) $Id: radiobutton.n,v 1.6.2.1 2004/10/28 10:19:29 dkf Exp $ '\" .so man.macros .TH radiobutton n 4.4 Tk "Tk Built-In Commands" @@ -16,14 +16,14 @@ radiobutton \- Create and manipulate radiobutton widgets .SH SYNOPSIS \fBradiobutton\fR \fIpathName \fR?\fIoptions\fR? .SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline +\-activebackground \-disabledforeground \-padx +\-activeforeground \-font \-pady +\-anchor \-foreground \-relief +\-background \-highlightbackground \-takefocus +\-bitmap \-highlightcolor \-text +\-borderwidth \-highlightthickness \-textvariable +\-compound \-image \-underline \-cursor \-justify \-wraplength -\-disabledforeground \-padx .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command @@ -53,8 +53,8 @@ for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. -.VS 8.4 .OP \-offrelief offRelief OffRelief +.VS 8.4 Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is "raised". By setting this option to "flat" and setting -indicatoron to false and -overrelief to raised, @@ -63,10 +63,9 @@ of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a word-processor, for example. - .VE 8.4 -.VS 8.4 .OP \-overrelief overRelief OverRelief +.VS 8.4 Specifies an alternative relief for the radiobutton, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring \fB\-relief flat \-overrelief @@ -166,7 +165,6 @@ on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a radiobutton is configured to select itself on button clicks. - .SH "WIDGET COMMAND" .PP The \fBradiobutton\fR command creates a new Tcl command whose @@ -224,13 +222,12 @@ This command is ignored if the radiobutton's state is \fBdisabled\fR. \fIpathName \fBselect\fR Selects the radiobutton and sets the associated variable to the value corresponding to this widget. - .SH BINDINGS .PP Tk automatically creates class bindings for radiobuttons that give them the following default behavior: -.VS .IP [1] +.VS On Unix systems, a radiobutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radiobutton. On Mac and Windows systems, when mouse button 1 is pressed over a @@ -252,5 +249,8 @@ actions occur: the radiobutton is completely non-responsive. The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. +.SH "SEE ALSO" +checkbutton(n), labelframe(n), listbox(n), options(n), scale(n) + .SH KEYWORDS radiobutton, widget |