Control
*******

after
=====

after - Execute a command after a time delay

Synopsis
--------

after ms ?arg1 arg2 arg3 ...?

Description
-----------

This command is used to delay execution of the program or to execute a command in background after a delay.  The ms argument gives a time in milliseconds. If ms is the only argument to after then the command sleeps for ms milliseconds and returns. While the command is sleeping the application does not respond to X events and other events.

If additional arguments are present after ms, then a Tcl command is formed by concatenating all the additional arguments in the same fashion as the concat command.  After returns immediately but arranges for the command to be executed ms milliseconds later in background. The command will be executed at global level (outside the context of any Tcl procedure). If an error occurs while executing the delayed command then the tkerror mechanism is used to report the error.

The after command always returns an empty string.

See tkerror

Keywords
--------

delay, sleep, time

bind
====

bind \- Arrange for X events to invoke Tcl commands

Synopsis
--------

bind windowSpec

bind windowSpec sequence

bind windowSpec sequence command

bind windowSpec sequence +command

Description
-----------

If all three arguments are specified, bind will arrange for command (a Tcl command) to be executed whenever the sequence of events given by sequence occurs in the window(s) identified by windowSpec. If command is prefixed with a ``+'', then it is appended to any existing binding for sequence;  otherwise command replaces the existing binding, if any.  If command is an empty string then the current binding for sequence is destroyed, leaving sequence unbound.  In all of the cases where a command argument is provided, bind returns an empty string.

If sequence is specified without a command, then the command currently bound to sequence is returned, or an empty string if there is no binding for sequence.  If neither sequence nor command is specified, then the return value is a list whose elements are all the sequences for which there exist bindings for windowSpec.

The windowSpec argument selects which window(s) the binding applies to. It may have one of three forms. If windowSpec is the path name for a window, then the binding applies to that particular window. If windowSpec is the name of a class of widgets, then the binding applies to all widgets in that class. Lastly, windowSpec may have the value all, in which case the binding applies to all windows in the application.

The sequence argument specifies a sequence of one or more event patterns, with optional white space between the patterns.  Each event pattern may take either of two forms.  In the simplest case it is a single printing ASCII character, such as a or [.  The character may not be a space character or the character <.  This form of pattern matches a KeyPress event for the particular character.  The second form of pattern is longer but more general. It has the following syntax:

     <modifier-modifier-type-detail>

The entire event pattern is surrounded by angle brackets. Inside the angle brackets are zero or more modifiers, an event type, and an extra piece of information (detail) identifying a particular button or keysym.  Any of the fields may be omitted, as long as at least one of type and detail is present. The fields must be separated by white space or dashes.

Modifiers may consist of any of the values in the following list:

     Control                  Any
     Shift                    Double
     Lock                     Triple
     Button1, B1              Mod1, M1, Meta, M
     Button2, B2              Mod2, M2, Alt
     Button3, B3              Mod3, M3
     Button4, B4              Mod4, M4
     Button5, B5              Mod5, M5

Where more than one value is listed, separated by commas, the values are equivalent.   All of the modifiers except Any, Double, and Triple have the obvious X meanings.  For example, Button1 requires that button 1 be depressed when the event occurs.  Under normal conditions the button and modifier state at the time of the event must match exactly those specified in the bind command.  If no modifiers are specified, then events will match only if no modifiers are present.  If the Any modifier is specified, then additional modifiers may be present besides those specified explicitly.  For example, if button 1 is pressed while the shift and control keys are down, the specifier <Any-Control-Button-1> will match the event, but the specifier <Control-Button-1> will not.

The Double and Triple modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2 or 3 times, and also place a time and space requirement on the sequence:  for a sequence of events to match a Double or Triple pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, <Double-Button-1> is equivalent to <Button-1><Button-1> with the extra time and space requirement.

The type field may be any of the standard X event types, with a few extra abbreviations.  Below is a list of all the valid types; where two name appear together, they are synonyms.

     ButtonPress, Button      Expose             Leave
     ButtonRelease            FocusIn            Map
     Circulate                FocusOut           Property
     CirculateRequest         Gravity            Reparent
     Colormap                 Keymap             ResizeRequest
     Configure                KeyPress, Key      Unmap
     ConfigureRequest         KeyRelease         Visibility
     Destroy                  MapRequest
     Enter                    Motion

The last part of a long event specification is detail.  In the case of a ButtonPress or ButtonRelease event, it is the number of a button (1-5).  If a button number is given, then only an event on that particular button will match;  if no button number is given, then an event on any button will match.  Note:  giving a specific button number is different than specifying a button modifier; in the first case, it refers to a button being pressed or released, while in the second it refers to some other button that is already depressed when the matching event occurs.  If a button number is given then type may be omitted:  if will default to ButtonPress.  For example, the specifier <1> is equivalent to <ButtonPress-1>.

If the event type is KeyPress or KeyRelease, then detail may be specified in the form of an X keysym.  Keysyms are textual specifications for particular keys on the keyboard; 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 ``F1'' is the keysym for the F1 function key, if it exists).  The complete list of keysyms is not presented here;  it should be available in other X documentation.  If necessary, you can use the %K notation described below to print out the keysym name for an arbitrary key.  If a keysym detail is given, then the type field may be omitted;  it will default to KeyPress. For example, <Control-comma> is equivalent to <Control-KeyPress-comma>.  If a keysym detail is specified then the Shift modifier need not be specified and will be ignored if specified:  each keysym already implies a particular state for the shift key.

The command argument to bind is a Tcl command string, which will be executed whenever the given event sequence occurs. Command will be executed in the same interpreter that the bind command was executed in.  If command contains any % characters, then the command string will not be executed directly.  Instead, a new command string will be generated by replacing each %, and the character following it, with information from the current event.  The replacement depends on the character following the %, as defined in the list below.  Unless otherwise indicated, the replacement string is the decimal value of the given field from the current event. Some of the substitutions are only valid for certain types of events;  if they are used for other types of events the value substituted is undefined.

%%
     Replaced with a single percent.

|%#|
     The number of the last client request processed by the server (the serial field from the event).  Valid for all event types.

|%a|
     The above field from the event. Valid only for ConfigureNotify events.

|%b|
     The number of the button that was pressed or released.  Valid only for ButtonPress and ButtonRelease events.

|%c|
     The count field from the event.  Valid only for Expose, GraphicsExpose, and MappingNotify events.

|%d|
     The detail field from the event.  The |%d| is replaced by a string identifying the detail.  For EnterNotify, LeaveNotify, FocusIn, and FocusOut events, the string will be one of the following:

          NotifyAncestor            NotifyNonlinearVirtual
          NotifyDetailNone          NotifyPointer
          NotifyInferior            NotifyPointerRoot
          NotifyNonlinear           NotifyVirtual

     For ConfigureRequest events, the substituted string will be one of the following:

          Above                     Opposite
          Below                     TopIf
          BottomIf

     For events other than these, the substituted string is undefined. .RE

|%f|
     The focus field from the event (0 or 1).  Valid only for EnterNotify and LeaveNotify events.

|%h|
     The height field from the event.  Valid only for Configure, ConfigureNotify, Expose, GraphicsExpose, and ResizeRequest events.

|%k|
     The keycode field from the event.  Valid only for KeyPress and KeyRelease events.

|%m|
     The mode field from the event.  The substituted string is one of NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed.  Valid only for EnterWindow, FocusIn, FocusOut, and LeaveWindow events.

|%o|
     The override_redirect field from the event.  Valid only for CreateNotify, MapNotify, ReparentNotify, and ConfigureNotify events.

|%p|
     The place field from the event, substituted as one of the strings PlaceOnTop or PlaceOnBottom.  Valid only for CirculateNotify and CirculateRequest events.

|%s|
     The state field from the event.  For ButtonPress, ButtonRelease, EnterNotify, KeyPress, KeyRelease, LeaveNotify, and MotionNotify events, a decimal string is substituted.  For VisibilityNotify, one of the strings VisibilityUnobscured, VisibilityPartiallyObscured, and VisibilityFullyObscured is substituted.

|%t|
     The time field from the event.  Valid only for events that contain a time field.

|%v|
     The value_mask field from the event.  Valid only for ConfigureRequest events.

|%w|
     The width field from the event.  Valid only for Configure, ConfigureRequest, Expose, GraphicsExpose, and ResizeRequest events.

|%x|
     The x field from the event.  Valid only for events containing an x field.

|%y|
     The y field from the event.  Valid only for events containing a y field.

%A
     Substitutes the ASCII character corresponding to the event, or the empty string if the event doesn't correspond to an ASCII character (e.g. the shift key was pressed).  XLookupString does all the work of translating from the event to an ASCII character. Valid only for KeyPress and KeyRelease events.

%B
     The border_width field from the event.  Valid only for ConfigureNotify and CreateWindow events.

%D
     The display field from the event.  Valid for all event types.

%E
     The send_event field from the event.  Valid for all event types.

%K
     The keysym corresponding to the event, substituted as a textual string.  Valid only for KeyPress and KeyRelease events.

%N
     The keysym corresponding to the event, substituted as a decimal number.  Valid only for KeyPress and KeyRelease events.

%R
     The root window identifier from the event.  Valid only for events containing a root field.

%S
     The subwindow window identifier from the event.  Valid only for events containing a subwindow field.

%T
     The type field from the event.  Valid for all event types.

%W
     The path name of the window to which the event was reported (the window field from the event).  Valid for all event types.

%X
     The x_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding x-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and MotionNotify events.

%Y
     The y_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding y-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and MotionNotify events.

If the replacement string for a %-replacement contains characters that are interpreted specially by the Tcl parser (such as backslashes or square brackets or spaces) additional backslashes are added during replacement so that the result after parsing is the original replacement string. For example, if command is

     insert %A

and the character typed is an open square bracket, then the command actually executed will be

     insert \e[

This will cause the insert 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 command correctly.

At most one binding will trigger for any given X event. If several bindings match the recent events, the most specific binding is chosen and its command will be executed. The following tests are applied, in order, to determine which of several matching sequences is more specific: (a) a binding whose windowSpec names a particular window is more specific than a binding for a class, which is more specific than a binding whose windowSpec is all; (b) a longer sequence (in terms of number of events matched) is more specific than a shorter sequence; (c) an event pattern that specifies a specific button or key is more specific than one that doesn't;  (e) an event pattern that requires a particular modifier is more specific than one that doesn't require the modifier; (e) an event pattern specifying the Any modifier is less specific than one that doesn't.  If the matching sequences contain more than one event, then tests (c)-(e) are applied in order from the most recent event to the least recent event in the sequences.  If these tests fail to determine a winner, then the most recently registered sequence is the winner.

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).

When a sequence specified in a bind command contains more than one event pattern, then its command is executed whenever the recent events (leading up to and including the current event) match the given sequence.  This means, for example, that if button 1 is clicked repeatedly the sequence <Double-ButtonPress-1> will match each button press but the first. If extraneous events that would prevent a match occur in the middle of an event sequence then the extraneous events are ignored unless they are KeyPress or ButtonPress events. For example, <Double-ButtonPress-1> will match a sequence of presses of button 1, even though there will be ButtonRelease events (and possibly MotionNotify events) between the ButtonPress events. Furthermore, a KeyPress event may be preceded by any number of other KeyPress events for modifier keys without the modifier keys preventing a match. For example, the event sequence aB will match a press of the a key, a release of the a key, a press of the Shift key, and a press of the b key:  the press of Shift is ignored because it is a modifier key. Finally, if several MotionNotify events occur in a row, only the last one is used for purposes of matching binding sequences.

If an error occurs in executing the command for a binding then the tkerror mechanism is used to report the error. The command will be executed at global level (outside the context of any Tcl procedure).

See tkerror

Keywords
--------

form, manual

destroy
=======

destroy \- Destroy one or more windows

Synopsis
--------

destroy ?window window ...?

Description
-----------

This command deletes the windows given by the window arguments, plus all of their descendants. If a window ``.'' is deleted then the entire application will be destroyed. The windows are destroyed in order, and if an error occurs in destroying a window the command aborts without destroying the remaining windows.

Keywords
--------

application, destroy, window

tk-dialog
=========

tk-dialog \- Create modal dialog and wait for response

Synopsis
--------

tk-dialog window title text bitmap default string string ...

Description
-----------

This procedure is part of the Tk script library. Its arguments describe a dialog box:

window
     Name of top-level window to use for dialog.  Any existing window by this name is destroyed.

title
     Text to appear in the window manager's title bar for the dialog.

text
     Message to appear in the top portion of the dialog box.

bitmap
     If non-empty, specifies a bitmap to display in the top portion of the dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the dialog.

default
     If this is an integer greater than or equal to zero, then it gives the index of the button that is to be the default button for the dialog (0 for the leftmost button, and so on). If less than zero or an empty string then there won't be any default button.

string
     There will be one button for each of these arguments. Each string specifies text to display in a button, in order from left to right.

     After creating a dialog box, tk-dialog waits for the user to select one of the buttons either by clicking on the button with the mouse or by typing return to invoke the default button (if any). Then it returns the index of the selected button:  0 for the leftmost button, 1 for the button next to it, and so on.

     While waiting for the user to respond, tk-dialog sets a local grab.  This prevents the user from interacting with the application in any way except to invoke the dialog box.

Keywords
--------

bitmap, dialog, modal

exit
====

exit \- Exit the process

Synopsis
--------

exit ?returnCode?

Description
-----------

Terminate the process, returning returnCode (an integer) to the system as the exit status. If returnCode isn't specified then it defaults to 0. This command replaces the Tcl command by the same name. It is identical to Tcl's exit command except that before exiting it destroys all the windows managed by the process. This allows various cleanup operations to be performed, such as removing application names from the global registry of applications.

Keywords
--------

exit, process

focus
=====

focus \- Direct keyboard events to a particular window

Synopsis
--------

focus

focus window

focus option ?arg arg ...?

Description
-----------

The focus command is used to manage the Tk input focus. At any given time, one window in an application is designated as the focus window for that application;  any key press or key release events directed to any window in the application will be redirected instead to the focus window.  If there is no focus window for an application then keyboard events are discarded. Typically, windows that are prepared to deal with the focus (e.g. entries and other widgets that display editable text) will claim the focus when mouse button 1 is pressed in them. When an application is created its main window is initially given the focus.

The focus command can take any of the following forms:

focus
     If invoked with no arguments, focus returns the path name of the current focus window, or none if there is no focus window.

focus window
     If invoked with a single argument consisting of a window's path name, focus sets the input focus to that window. The return value is an empty string.

focus :default ?window?
     If window is specified, it becomes the default focus window (the window that receives the focus whenever the focus window is deleted) and the command returns an empty string. If window isn't specified, the command returns the path name of the current default focus window, or none if there is no default. Window may be specified as none to clear its existing value. The default window is initially none.

focus :none
     Clears the focus window, so that keyboard input to this application will be discarded.

"Focus Events"
--------------

Tk's model of the input focus is different than X's model, and the focus window set with the focus command is not usually the same as the X focus window. Tk never explicitly changes the official X focus window. It waits for the window manager to direct the X input focus to and from the application's top-level windows, and it intercepts FocusIn and FocusOut events coming from the X server to detect these changes. All of the focus events received from X are discarded by Tk;  they never reach the application. Instead, Tk generates a different stream of FocusIn and FocusOut for the application. This means that FocusIn and and FocusOut events seen by the application will not obey the conventions described in the documentation for Xlib.

Tk applications receive two kinds of FocusIn and FocusOut events, which can be distinguished by their detail fields. Events with a detail of NotifyAncestor are directed to the current focus window when it becomes active or inactive. A window is the active focus whenever two conditions are simultaneously true: (a) the window is the focus window for its application, and (b) some top-level window in the application has received the X focus. When this happens Tk generates a FocusIn event for the focus window with detail NotifyAncestor. When a window loses the active focus (either because the window manager removed the focus from the application or because the focus window changed within the application) then it receives a FocusOut event with detail NotifyAncestor.

The events described above are directed to the application's focus window regardless of which top-level window within the application has received the focus. The second kind of focus event is provided for applications that need to know which particular top-level window has the X focus. Tk generates FocusIn and FocusOut events with detail NotifyVirtual for top-level windows whenever they receive or lose the X focus. These events are generated regardless of which window in the application has the Tk input focus. They do not imply that keystrokes will be directed to the window that receives the event;  they simply indicate which top-level window is active as far as the window manager is concerned. If a top-level window is also the application's focus window, then it will receive both NotifyVirtual and NotifyAncestor events when it receives or loses the X focus.

Tk does not generate the hierarchical chains of FocusIn and FocusOut events described in the Xlib documentation (e.g. a window can get a FocusIn or FocusOut event without all of its ancestors getting events too). Furthermore, the mode field in focus events is always NotifyNormal and the only values ever present in the detail field are NotifyAncestor and NotifyVirtual.

Keywords
--------

events, focus, keyboard, top-level, window manager

grab
====

grab \- Confine pointer and keyboard events to a window sub-tree

Synopsis
--------

grab ?:global? window

grab option ?arg arg ...?

Description
-----------

This command implements simple pointer and keyboard grabs for Tk. Tk's grabs are different than the grabs described in the Xlib documentation. When a grab is set for a particular window, Tk restricts all pointer events to the grab window and its descendants in Tk's window hierarchy. Whenever the pointer is within the grab window's subtree, the pointer will behave exactly the same as if there had been no grab at all and all events will be reported in the normal fashion. When the pointer is outside window's tree, button presses and releases and mouse motion events are reported to window, and window entry and window exit events are ignored. The grab subtree ``owns'' the pointer: windows outside the grab subtree will be visible on the screen but they will be insensitive until the grab is released. The tree of windows underneath the grab window can include top-level windows, in which case all of those top-level windows and their descendants will continue to receive mouse events during the grab.

Two forms of grabs are possible:  local and global. A local grab affects only the grabbing application:  events will be reported to other applications as if the grab had never occurred. Grabs are local by default. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either.

During local grabs, keyboard events (key presses and key releases) are delivered as usual:  the window manager controls which application receives keyboard events, and if they are sent to any window in the grabbing application then they are redirected to the focus window. During a global grab Tk grabs the keyboard so that all keyboard events are always sent to the grabbing application. The focus command is still used to determine which window in the application receives the keyboard events. The keyboard grab is released when the grab is released.

Grabs apply to particular displays.  If an application has windows on multiple displays then it can establish a separate grab on each display. The grab on a particular display affects only the windows on that display. It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once.

The grab command can take any of the following forms:

grab ?:global? window
     Same as grab :set, described below.

grab :current ?window?
     If window is specified, returns the name of the current grab window in this application for window's display, or an empty string if there is no such window. If window is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs.

grab :release window
     Releases the grab on window if there is one, otherwise does nothing.  Returns an empty string.

grab :set ?:global? window
     Sets a grab on window.  If :global is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on window's display then it is automatically released. If there is already a grab on window and it has the same global/local form as the requested grab, then the command does nothing.  Returns an empty string.

grab :status window
     Returns none if no grab is currently set on window, local if a local grab is set on window, and global if a global grab is set.

Bugs
----

It took an incredibly complex and gross implementation to produce the simple grab effect described above. Given the current implementation, it isn't safe for applications to use the Xlib grab facilities at all except through the Tk grab procedures. If applications try to manipulate X's grab mechanisms directly, things will probably break.

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.

Keywords
--------

grab, keyboard events, pointer events, window

tk-listbox-single-select
========================

tk-listbox-single-select \- Allow only one selected element in listbox(es)

Synopsis
--------

tk-listbox-single-select arg ?arg arg ...?

Description
-----------

This command is a Tcl procedure provided as part of the Tk script library. It takes as arguments the path names of one or more listbox widgets, or the value Listbox. For each named widget, tk-listbox-single-select modifies the bindings of the widget so that only a single element may be selected at a time (the normal configuration allows multiple elements to be selected). If the keyword Listbox is among the window arguments, then the class bindings for listboxes are changed so that all listboxes have the one-selection-at-a-time behavior.

Keywords
--------

listbox, selection

lower
=====

lower \- Change a window's position in the stacking order

Synopsis
--------

lower window ?belowThis?

Description
-----------

If the belowThis argument is omitted then the command lowers window so that it is below all of its siblings in the stacking order (it will be obscured by any siblings that overlap it and will not obscure any siblings). If belowThis is specified then it must be the path name of a window that is either a sibling of window or the descendant of a sibling of window. In this case the lower command will insert window into the stacking order just below belowThis (or the ancestor of belowThis that is a sibling of window); this could end up either raising or lowering window.

Keywords
--------

lower, obscure, stacking order

tk-menu-bar
===========

tk-menu-bar, tk_bindForTraversal \- Support for menu bars

Synopsis
--------

tk-menu-bar frame ?menu menu ...?

tk_bindForTraversal arg arg ...

Description
-----------

These two commands are Tcl procedures in the Tk script library. They provide support for menu bars. A menu bar is a frame that contains a collection of menu buttons that work together, so that the user can scan from one menu to another with the mouse: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead. Menus in a menu bar can also be accessed using keyboard traversal (i.e. by typing keystrokes instead of using the mouse). In order for an application to use these procedures, it must do three things, which are described in the paragraphs below.

First, each application must call tk-menu-bar to provide information about the menubar. The frame argument gives the path name of the frame that contains all of the menu buttons, and the menu arguments give path names for all of the menu buttons associated with the menu bar. Normally frame is the parent of each of the menu's. This need not be the case, but frame must be an ancestor of each of the menu's in order for grabs to work correctly when the mouse is used to pull down menus. The order of the menu arguments determines the traversal order for the menu buttons. If tk-menu-bar is called without any menu arguments, it returns a list containing the current menu buttons for frame, or an empty string if frame isn't currently set up as a menu bar. If tk-menu-bar is called with a single menu argument consisting of an empty string, any menubar information for frame is removed;  from now on the menu buttons will function independently without keyboard traversal. Only one menu bar may be defined at a time within each top-level window.

The second thing an application must do is to identify the traversal characters for menu buttons and menu entries. This is done by underlining those characters using the :underline options for the widgets. The menu traversal system uses this information to traverse the menus under keyboard control (see below).

The third thing that an application must do is to make sure that the input focus is always in a window that has been configured to support menu traversal. If the input focus is none then input characters will be discarded and no menu traversal will be possible. If you have no other place to set the focus, set it to the menubar widget:  tk-menu-bar creates bindings for its frame argument to support menu traversal.

The Tk startup scripts configure all the Tk widget classes with bindings to support menu traversal, so menu traversal will be possible regardless of which widget has the focus. If your application defines new classes of widgets that support the input focus, then you should call tk_bindForTraversal for each of these classes. Tk_bindForTraversal takes any number of arguments, each of which is a widget path name or widget class name. It sets up bindings for all the named widgets and classes so that the menu traversal system will be invoked when appropriate keystrokes are typed in those widgets or classes.

"Menu Traversal Bindings"
-------------------------

Once an application has made the three arrangements described above, menu traversal will be available. At any given time, the only menus available for traversal are those associated with the top-level window containing the input focus. Menu traversal is initiated by one of the following actions:

  [1] If <F10> is typed, then the first menu button in the list for the top-level window is posted and the first entry within that menu is selected.

  [2] If <Alt-key> is pressed, then the menu button that has key as its underlined character is posted and the first entry within that menu is selected. The comparison between key and the underlined characters ignores case differences. If no menu button matches key then the keystroke has no effect.

  [3] Clicking mouse button 1 on a menu button posts that menu and selects its first entry.

Once a menu has been posted, the input focus is switched to that menu and the following actions are possible:

  [1] Typing <ESC> or clicking mouse button 1 outside the menu button or its menu will abort the menu traversal.

  [2] If <Alt-key> is pressed, then the entry in the posted menu whose underlined character is key is invoked. This causes the menu to be unposted, the entry's action to be taken, and the menu traversal to end. The comparison between key and underlined characters ignores case differences. If no menu entry matches key then the keystroke is ignored.

  [3] The arrow keys may be used to move among entries and menus. The left and right arrow keys move circularly among the available menus and the up and down arrow keys move circularly among the entries in the current menu.

  [4] If <Return> is pressed, the selected entry in the posted menu is invoked, which causes the menu to be unposted, the entry's action to be taken, and the menu traversal to end.

When a menu traversal completes, the input focus reverts to the window that contained it when the traversal started.

Keywords
--------

keyboard traversal, menu, menu bar, post

option
======

option \- Add/retrieve window options to/from the option database

Synopsis
--------

option :add pattern value ?priority?

option :clear

option :get window name class

option :readfile fileName ?priority?

Description
-----------

The option command allows you to add entries to the Tk option database or to retrieve options from the database.  The add form of the command adds a new option to the database. Pattern contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format.  Value contains a text string to associate with pattern;  this is the value that will be returned in calls to Tk_GetOption or by invocations of the option :get command.  If priority is specified, it indicates the priority level for this option (see below for legal values);  it defaults to interactive. This command always returns an empty string.

The option :clear command clears the option database.  Default options (in the RESOURCE_MANAGER property or the .Xdefaults file) will be reloaded automatically the next time an option is added to the database or removed from it.  This command always returns an empty string.

The option :get command returns the value of the option specified for window under name and class.  If several entries in the option database match window, name, and class, then the command returns whichever was created with highest priority level.  If there are several matching entries at the same priority level, then it returns whichever entry was most recently entered into the option database.  If there are no matching entries, then the empty string is returned.

The readfile form of the command reads fileName, which should have the standard format for an X resource database such as .Xdefaults, and adds all the options specified in that file to the option database.  If priority is specified, it indicates the priority level at which to enter the options;  priority defaults to interactive.

The priority arguments to the option command are normally specified symbolically using one of the following values:

widgetDefault
     Level 20.  Used for default values hard-coded into widgets.

startupFile
     Level 40.  Used for options specified in application-specific startup files.

userDefault
     Level 60.  Used for options specified in user-specific defaults files, such as .Xdefaults, resource databases loaded into the X server, or user-specific startup files.

interactive
     Level 80.  Used for options specified interactively after the application starts running.  If priority isn't specified, it defaults to this level.

Any of the above keywords may be abbreviated.  In addition, priorities may be specified numerically using integers between 0 and 100, inclusive.  The numeric form is probably a bad idea except for new priority levels other than the ones given above.

Keywords
--------

database, option, priority, retrieve

options
=======

options \- Standard options supported by widgets

Description
-----------

This manual entry describes the common configuration options supported by widgets in the Tk toolkit.  Every widget does not necessarily support every option (see the manual entries for individual widgets for a list of the standard options supported by that widget), but if a widget does support an option with one of the names listed below, then the option has exactly the effect described below.

In the descriptions below, ``Name'' refers to the option's name in the option database (e.g. in .Xdefaults files).  ``Class'' refers to the option's class value in the option database.  ``Command-Line Switch'' refers to the switch used in widget-creation and configure widget commands to set this value.  For example, if an option's command-line switch is :foreground and there exists a widget .a.b.c, then the command

     (.a.b.c  :configure  :foreground "black")

may be used to specify the value black for the option in the the widget .a.b.c.  Command-line switches may be abbreviated, as long as the abbreviation is unambiguous.

:activebackground

     Name="activeBackground" Class="Foreground"

     Specifies background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur.

:activeborderwidth

     Name="activeBorderWidth" Class="BorderWidth"

     Specifies a non-negative value indicating the width of the 3-D border drawn around active elements.  See above for definition of active elements. The value may have any of the forms acceptable to Tk_GetPixels. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons).

:activeforeground

     Name="activeForeground" Class="Background"

     Specifies foreground color to use when drawing active elements. See above for definition of active elements.

:anchor

     Name="anchor" Class="Anchor"

     Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values n, ne, e, se, s, sw, w, nw, or center. For example, nw means display the information such that its top-left corner is at the top-left corner of the widget.

:background or :bg

     Name="background" Class="Background"

     Specifies the normal background color to use when displaying the widget.

:bitmap

     Name="bitmap" Class="Bitmap"

     Specifies a bitmap to display in the widget, in any of the forms acceptable to Tk_GetBitmap. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display.

:borderwidth or :bd

     Name="borderWidth" Class="BorderWidth"

     Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn;  the relief option typically determines this).  The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to Tk_GetPixels.

:cursor

     Name="cursor" Class="Cursor"

     Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor.

:cursorbackground

     Name="cursorBackground" Class="Foreground"

     Specifies the color to use as background in the area covered by the insertion cursor.  This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). \fIThis option is obsolete and is gradually being replaced by the insertBackground option.

:cursorborderwidth

     Name="cursorBorderWidth" Class="BorderWidth"

     Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. \fIThis option is obsolete and is gradually being replaced by the insertBorderWidth option.

:cursorofftime

     Name="cursorOffTime" Class="OffTime"

     Specifies a non-negative integer value indicating the number of milliseconds the cursor should remain ``off'' in each blink cycle. If this option is zero then the cursor doesn't blink:  it is on all the time. \fIThis option is obsolete and is gradually being replaced by the insertOffTime option.

:cursorontime

     Name="cursorOnTime" Class="OnTime"

     Specifies a non-negative integer value indicating the number of milliseconds the cursor should remain ``on'' in each blink cycle. \fIThis option is obsolete and is gradually being replaced by the insertOnTime option.

:cursorwidth

     Name="cursorWidth" Class="CursorWidth"

     Specifies a  value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. If a border has been specified for the cursor (using the cursorBorderWidth option), the border will be drawn inside the width specified by the cursorWidth option. \fIThis option is obsolete and is gradually being replaced by the insertWidth option.

:disabledforeground

     Name="disabledForeground" Class="DisabledForeground"

     Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal fooreground color but they are dimmed by drawing them with a stippled fill pattern.

:exportselection

     Name="exportSelection" Class="ExportSelection"

     Specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by Tcl_GetBoolean, such as true, false, 0, 1, yes, or no. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection.  The default is usually for widgets to export selections.

:font

     Name="font" Class="Font"

     Specifies the font to use when drawing text inside the widget.

:foreground or :fg

     Name="foreground" Class="Foreground"

     Specifies the normal foreground color to use when displaying the widget.

:geometry

     Name="geometry" Class="Geometry"

     Specifies the desired geometry for the widget's window, in the form widthxheight, where width is the desired width of the window and height is the desired height.  The units for width and height depend on the particular widget.  For widgets displaying text the units are usually the size of the characters in the font being displayed;  for other widgets the units are usually pixels.

:insertbackground

     Name="insertBackground" Class="Foreground"

     Specifies the color to use as background in the area covered by the insertion cursor.  This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection).

:insertborderwidth

     Name="insertBorderWidth" Class="BorderWidth"

     Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels.

:insertofftime

     Name="insertOffTime" Class="OffTime"

     Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``off'' in each blink cycle. If this option is zero then the cursor doesn't blink:  it is on all the time.

:insertontime

     Name="insertOnTime" Class="OnTime"

     Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``on'' in each blink cycle.

:insertwidth

     Name="insertWidth" Class="InsertWidth"

     Specifies a  value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. If a border has been specified for the insertion cursor (using the insertBorderWidth option), the border will be drawn inside the width specified by the insertWidth option.

:orient

     Name="orient" Class="Orient"

     For widgets that can lay themselves out with either a horizontal or vertical orientation, such as scrollbars, this option specifies which orientation should be used.  Must be either horizontal or vertical or an abbreviation of one of these.

:padx

     Name="padX" Class="Pad"

     Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. The value may have any of the forms acceptable to Tk_GetPixels. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget);  if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside.

:pady

     Name="padY" Class="Pad"

     Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. The value may have any of the forms acceptable to Tk_GetPixels. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget);  if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside.

:relief

     Name="relief" Class="Relief"

     Specifies the 3-D effect desired for the widget.  Acceptable values are raised, sunken, flat, ridge, and groove. The value indicates how the interior of the widget should appear relative to its exterior;  for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

:repeatdelay

     Name="repeatDelay" Class="RepeatDelay"

     Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat.  Used, for example, on the up- and down-arrows in scrollbars.

:repeatinterval

     Name="repeatInterval" Class="RepeatInterval"

     Used in conjunction with repeatDelay:  once auto-repeat begins, this option determines the number of milliseconds between auto-repeats.

:scrollcommand

     Name="scrollCommand" Class="ScrollCommand"

     Specifies the prefix for a command used to communicate with scrollbar widgets.  When the view in the widget's window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget's contents), the widget will generate a Tcl command by concatenating the scroll command and four numbers.  The four numbers are, in order:  the total size of the widget's contents, in unspecified units (``unit'' is a widget-specific term;  for widgets displaying text, the unit is a line);  the maximum number of units that may be displayed at once in the widget's window, given its current size;  the index of the top-most or left-most unit currently visible in the window (index 0 corresponds to the first unit); and the index of the bottom-most or right-most unit currently visible in the window.  This command is then passed to the Tcl interpreter for execution.  Typically the scrollCommand option consists of the path name of a scrollbar widget followed by ``set'', e.g. ``.x.scrollbar set'':  this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed.

     The scrollCommand option is used for widgets that support scrolling in only one direction. For widgets that support scrolling in both directions, this option is replaced with the xScrollCommand and yScrollCommand options.

:selectbackground

     Name="selectBackground" Class="Foreground"

     Specifies the background color to use when displaying selected items.

:selectborderwidth

     Name="selectBorderWidth" Class="BorderWidth"

     Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to Tk_GetPixels.

:selectforeground

     Name="selectForeground" Class="Background"

     Specifies the foreground color to use when displaying selected items.

:setgrid

     Name="setGrid" Class="SetGrid"

     Specifies a boolean value that determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the setGrid option is set to true then the widget will 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 wm manual entry for more details.

:text

     Name="text" Class="Text"

     Specifies a string to be displayed inside the widget.  The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify.

:textvariable

     Name="textVariable" Class="Variable"

     Specifies the name of a variable.  The value of the variable is a text string to be displayed inside the widget;  if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as anchor or justify.

:underline

     Name="underline" Class="Underline"

     Specifies the integer index of a character to underline in the widget. This option is typically used to indicate keyboard traversal characters in menu buttons and menu entries.  0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.

:xscrollcommand

     Name="xScrollCommand" Class="ScrollCommand"

     Specifies the prefix for a command used to communicate with horizontal scrollbars.  This option is treated in the same way as the scrollCommand option, except that it is used for horizontal scrollbars associated with widgets that support both horizontal and vertical scrolling. See the description of scrollCommand for complete details on how this option is used.

:yscrollcommand

     Name="yScrollCommand" Class="ScrollCommand"

     Specifies the prefix for a command used to communicate with vertical scrollbars.  This option is treated in the same way as the scrollCommand option, except that it is used for vertical scrollbars associated with widgets that support both horizontal and vertical scrolling. See the description of scrollCommand for complete details on how this option is used.

Keywords
--------

class, name, standard option, switch

pack-old
========

pack \- Obsolete syntax for packer geometry manager

Synopsis
--------

pack after sibling window options ?window options ...?

pack append parent window options ?window options ...?

pack before sibling window options ?window options ...?

pack info parent

pack unpack window

Description
-----------

Note: this manual entry describes the syntax for the pack\fI command as it before Tk version 3.3. Although this syntax continues to be supported for backward compatibility, it is obsolete and should not be used anymore. At some point in the future it may cease to be supported.

The packer is a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent.  The first child is placed against one side of the window, occupying the entire span of the window along that side.  This reduces the space remaining for other children as if the side had been moved in by the size of the first child. Then the next child is placed against one side of the remaining cavity, and so on until all children have been placed or there is no space left in the cavity.

The before, after, and append forms of the pack command are used to insert one or more children into the packing order for their parent.  The before form inserts the children before window sibling in the order;  all of the other windows must be siblings of sibling.  The after form inserts the windows after sibling, and the append form appends one or more windows to the end of the packing order for parent.  If a window named in any of these commands is already packed in its parent, it is removed from its current position in the packing order and repositioned as indicated by the command.  All of these commands return an empty string as result.

The unpack form of the pack command removes window from the packing order of its parent and unmaps it.  After the execution of this command the packer will no longer manage window's geometry.

The placement of each child is actually a four-step process; the options argument following each window consists of a list of one or more fields that govern the placement of that window.  In the discussion below, the term cavity refers to the space left in a parent when a particular child is placed (i.e. all the space that wasn't claimed by earlier children in the packing order).  The term parcel refers to the space allocated to a particular child;  this is not necessarily the same as the child window's final geometry.

The first step in placing a child is to determine which side of the cavity it will lie against.  Any one of the following options may be used to specify a side:

top
     Position the child's parcel against the top of the cavity, occupying the full width of the cavity.

bottom
     Position the child's parcel against the bottom of the cavity, occupying the full width of the cavity.

left
     Position the child's parcel against the left side of the cavity, occupying the full height of the cavity.

right
     Position the child's parcel against the right side of the cavity, occupying the full height of the cavity.

At most one of these options should be specified for any given window. If no side is specified, then the default is top.

The second step is to decide on a parcel for the child.  For top and bottom windows, the desired parcel width is normally the cavity width and the desired parcel height is the window's requested height, as passed to Tk_GeometryRequest. For left and right windows, the desired parcel height is normally the cavity height and the desired width is the window's requested width.  However, extra space may be requested for the window using any of the following options:

padx num
     Add num pixels to the window's requested width before computing the parcel size as described above.

pady num
     Add num pixels to the window's requested height before computing the parcel size as described above.

expand
     This option requests that the window's parcel absorb any extra space left over in the parent's cavity after packing all the children. The amount of space left over depends on the sizes requested by the other children, and may be zero.  If several windows have all specified expand then the extra width will be divided equally among all the left and right windows that specified expand and the extra height will be divided equally among all the top and bottom windows that specified expand.

If the desired width or height for a parcel is larger than the corresponding dimension of the cavity, then the cavity's dimension is used instead.

The third step in placing the window is to decide on the window's width and height.  The default is for the window to receive either its requested width and height or the those of the parcel, whichever is smaller.  If the parcel is larger than the window's requested size, then the following options may be used to expand the window to partially or completely fill the parcel:

fill
     Set the window's size to equal the parcel size.

fillx
     Increase the window's width to equal the parcel's width, but retain the window's requested height.

filly
     Increase the window's height to equal the parcel's height, but retain the window's requested width.

     The last step is to decide the window's location within its parcel. If the window's size equals the parcel's size, then the window simply fills the entire parcel.  If the parcel is larger than the window, then one of the following options may be used to specify where the window should be positioned within its parcel:

frame center
     Center the window in its parcel.  This is the default if no framing option is specified.

frame n
     Position the window with its top edge centered on the top edge of the parcel.

frame ne
     Position the window with its upper-right corner at the upper-right corner of the parcel.

frame e
     Position the window with its right edge centered on the right edge of the parcel.

frame se
     Position the window with its lower-right corner at the lower-right corner of the parcel.

frame s
     Position the window with its bottom edge centered on the bottom edge of the parcel.

frame sw
     Position the window with its lower-left corner at the lower-left corner of the parcel.

frame w
     Position the window with its left edge centered on the left edge of the parcel.

frame nw
     Position the window with its upper-left corner at the upper-left corner of the parcel.

     The pack info command may be used to retrieve information about the packing order for a parent.  It returns a list in the form

          window options window options ...

     Each window is a name of a window packed in parent, and the following options describes all of the options for that window, just as they would be typed to pack append. The order of the list is the same as the packing order for parent.

     The packer manages the mapped/unmapped state of all the packed children windows.  It automatically maps the windows when it packs them, and it unmaps any windows for which there was no space left in the cavity.

     The packer makes geometry requests on behalf of the parent windows it manages.  For each parent window it requests a size large enough to accommodate all the options specified by all the packed children, such that zero space would be leftover for expand options.

Keywords
--------

geometry manager, location, packer, parcel, size

pack
====

pack \- Geometry manager that packs around edges of cavity

Synopsis
--------

pack option arg ?arg ...?

Description
-----------

The pack command is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The pack command can have any of several forms, depending on the option argument:

pack slave ?slave ...? ?options?
     If the first argument to pack is a window name (any value starting with ``.''), then the command is processed in the same way as pack configure.

pack configure slave ?slave ...? ?options?
     The arguments consist of the names of one or more slave windows followed by pairs of arguments that specify how to manage the slaves. See ``THE PACKER ALGORITHM'' below for details on how the options are used by the packer. The following options are supported:

:after other
     Other must the name of another window. Use its master as the master for the slaves, and insert the slaves just after other in the packing order.

:anchor anchor
     Anchor must be a valid anchor position such as n or sw; it specifies where to position each slave in its parcel. Defaults to center.

:before other
     Other must the name of another window. Use its master as the master for the slaves, and insert the slaves just before other in the packing order.

:expand boolean
     Specifies whether the slaves should be expanded to consume extra space in their master. Boolean may have any proper boolean value, such as 1 or no. Defaults to 0.

:fill style
     If a slave's parcel is larger than its requested dimensions, this option may be used to stretch the slave. Style must have one of the following values:

     none
          Give the slave its requested dimensions plus any internal padding requested with :ipadx or :ipady.  This is the default.

     x
          Stretch the slave horizontally to fill the entire width of its parcel (except leave external padding as specified by :padx).

     y
          Stretch the slave vertically to fill the entire height of its parcel (except leave external padding as specified by :pady).

     both
          Stretch the slave both horizontally and vertically.

:in other
     Insert the slave(s) at the end of the packing order for the master window given by other.

:ipadx amount
     Amount specifies how much horizontal internal padding to leave on each side of the slave(s). Amount must be a valid screen distance, such as 2 or .5c. It defaults to 0.

:ipady amount
     Amount specifies how much vertical internal padding to leave on each side of the slave(s). Amount  defaults to 0.

:padx amount
     Amount specifies how much horizontal external padding to leave on each side of the slave(s). Amount defaults to 0.

:pady amount
     Amount specifies how much vertical external padding to leave on each side of the slave(s). Amount defaults to 0.

:side side
     Specifies which side of the master the slave(s) will be packed against. Must be left, right, top, or bottom. Defaults to top.

If no :in, :after or :before option is specified then each of the slaves will be inserted at the end of the packing list for its parent unless it is already managed by the packer (in which case it will be left where it is). If one of these options is specified then all the slaves will be inserted at the specified point. If any of the slaves are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE

pack :forget slave ?slave ...?
     Removes each of the slaves from the packing order for its master and unmaps their windows. The slaves will no longer be managed by the packer.

pack :newinfo slave
     Returns a list whose elements are the current configuration state of the slave given by slave in the same option-value form that might be specified to pack configure. The first two elements of the list are ``:in master'' where master is the slave's master. Starting with Tk 4.0 this option will be renamed "pack info".

pack :propagate master ?boolean?
     If boolean has a true boolean value such as 1 or on then propagation is enabled for master, which must be a window name (see ``GEOMETRY PROPAGATION'' below). If boolean has a false boolean value then propagation is disabled for master. In either of these cases an empty string is returned. If boolean is omitted then the command returns 0 or 1 to indicate whether propagation is currently enabled for master. Propagation is enabled by default.

pack :slaves master
     Returns a list of all of the slaves in the packing order for master. The order of the slaves in the list is the same as their order in the packing order. If master has no slaves then an empty string is returned.

"The Packer Algorithm"
----------------------

For each master the packer maintains an ordered list of slaves called the packing list. The :in, :after, and :before configuration options are used to specify the master for each slave and the slave's position in the packing list. If none of these options is given for a slave then the slave is added to the end of the packing list for its parent.

The packer arranges the slaves for a master by scanning the packing list in order. At the time it processes each slave, a rectangular area within the master is still unallocated. This area is called the cavity;  for the first slave it is the entire area of the master.

For each slave the packer carries out the following steps:

  [1] The packer allocates a rectangular parcel for the slave along the side of the cavity given by the slave's :side option. If the side is top or bottom then the width of the parcel is the width of the cavity and its height is the requested height of the slave plus the :ipady and :pady options. For the left or right side the height of the parcel is the height of the cavity and the width is the requested width of the slave plus the :ipadx and :padx options. The parcel may be enlarged further because of the :expand option (see ``EXPANSION'' below)

  [2] The packer chooses the dimensions of the slave. The width will normally be the slave's requested width plus twice its :ipadx option and the height will normally be the slave's requested height plus twice its :ipady option. However, if the :fill option is x or both then the width of the slave is expanded to fill the width of the parcel, minus twice the :padx option. If the :fill option is y or both then the height of the slave is expanded to fill the width of the parcel, minus twice the :pady option.

  [3] The packer positions the slave over its parcel. If the slave is smaller than the parcel then the :anchor option determines where in the parcel the slave will be placed. If :padx or :pady is non-zero, then the given amount of external padding will always be left between the slave and the edges of the parcel.

Once a given slave has been packed, the area of its parcel is subtracted from the cavity, leaving a smaller rectangular cavity for the next slave. If a slave doesn't use all of its parcel, the unused space in the parcel will not be used by subsequent slaves. If the cavity should become too small to meet the needs of a slave then the slave will be given whatever space is left in the cavity. If the cavity shrinks to zero size, then all remaining slaves on the packing list will be unmapped from the screen until the master window becomes large enough to hold them again.

"Expansion"
-----------

If a master window is so large that there will be extra space left over after all of its slaves have been packed, then the extra space is distributed uniformly among all of the slaves for which the :expand option is set. Extra horizontal space is distributed among the expandable slaves whose :side is left or right, and extra vertical space is distributed among the expandable slaves whose :side is top or bottom.

"Geometry Propagation"
----------------------

The packer normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the pack propagate command may be used to turn off propagation for one or more masters. If propagation is disabled then the packer will not set the requested width and height of the packer. This may be useful if, for example, you wish for a master window to have a fixed size that you specify.

"Restrictions On Master Windows"
--------------------------------

The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent.

"Packing Order"
---------------

If the master for a slave is not its parent then you must make sure that the slave is higher in the stacking order than the master. Otherwise the master will obscure the slave and it will appear as if the slave hasn't been packed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first:  the most recently created window will be highest in the stacking order. Or, you can use the raise and lower commands to change the stacking order of either the master or the slave.

Keywords
--------

geometry manager, location, packer, parcel, propagation, size

place
=====

place \- Geometry manager for fixed or rubber-sheet placement

Synopsis
--------

place window option value ?option value ...?

place configure window option value ?option value ...?

place forget window

place info window

place slaves window

Description
-----------

The placer is a geometry manager for Tk. It provides simple fixed placement of windows, where you specify the exact size and location of one window, called the slave, within another window, called the master. The placer also provides rubber-sheet placement, where you specify the size and location of the slave in terms of the dimensions of the master, so that the slave changes size and location in response to changes in the size of the master. Lastly, the placer allows you to mix these styles of placement so that, for example, the slave has a fixed width and height but is centered inside the master.

If the first argument to the place command is a window path name or configure then the command arranges for the placer to manage the geometry of a slave whose path name is window. The remaining arguments consist of one or more option:value pairs that specify the way in which window's geometry is managed. If the placer is already managing window, then the option:value pairs modify the configuration for window. In this form the place command returns an empty string as result. The following option:value pairs are supported:

:in master
     Master specifes the path name of the window relative to which window is to be placed. Master must either be window's parent or a descendant of window's parent. In addition, master and window must both be descendants of the same top-level window. These restrictions are necessary to guarantee that window is visible whenever master is visible. If this option isn't specified then the master defaults to window's parent.

:x location
     Location specifies the x-coordinate within the master window of the anchor point for window. The location is specified in screen units (i.e. any of the forms accepted by Tk_GetPixels) and need not lie within the bounds of the master window.

:relx location
     Location specifies the x-coordinate within the master window of the anchor point for window. In this case the location is specified in a relative fashion as a floating-point number:  0.0 corresponds to the left edge of the master and 1.0 corresponds to the right edge of the master. Location need not be in the range 0.0\-1.0.

:y location
     Location specifies the y-coordinate within the master window of the anchor point for window. The location is specified in screen units (i.e. any of the forms accepted by Tk_GetPixels) and need not lie within the bounds of the master window.

:rely location
     Location specifies the y-coordinate within the master window of the anchor point for window. In this case the value is specified in a relative fashion as a floating-point number:  0.0 corresponds to the top edge of the master and 1.0 corresponds to the bottom edge of the master. Location need not be in the range 0.0\-1.0.

:anchor where
     Where specifies which point of window is to be positioned at the (x,y) location selected by the :x, :y, :relx, and :rely options. The anchor point is in terms of the outer area of window including its border, if any. Thus if where is se then the lower-right corner of window's border will appear at the given (x,y) location in the master. The anchor position defaults to nw.

:width size
     Size specifies the width for window in screen units (i.e. any of the forms accepted by Tk_GetPixels). The width will be the outer width of window including its border, if any. If size is an empty string, or if no :width or :relwidth option is specified, then the width requested internally by the window will be used.

:relwidth size
     Size specifies the width for window. In this case the width is specified as a floating-point number relative to the width of the master: 0.5 means window will be half as wide as the master, 1.0 means window will have the same width as the master, and so on.

:height size
     Size specifies the height for window in screen units (i.e. any of the forms accepted by Tk_GetPixels). The height will be the outer dimension of window including its border, if any. If size is an empty string, or if no :height or :relheight option is specified, then the height requested internally by the window will be used.

:relheight size
     Size specifies the height for window. In this case the height is specified as a floating-point number relative to the height of the master: 0.5 means window will be half as high as the master, 1.0 means window will have the same height as the master, and so on.

:bordermode mode
     Mode determines the degree to which borders within the master are used in determining the placement of the slave. The default and most common value is inside. In this case the placer considers the area of the master to be the innermost area of the master, inside any border: an option of :x 0 corresponds to an x-coordinate just inside the border and an option of :relwidth 1.0 means window will fill the area inside the master's border. If mode is outside then the placer considers the area of the master to include its border; this mode is typically used when placing window outside its master, as with the options :x 0 :y 0 :anchor ne. Lastly, mode may be specified as ignore, in which case borders are ignored:  the area of the master is considered to be its official X area, which includes any internal border but no external border.  A bordermode of ignore is probably not very useful.

     If the same value is specified separately with two different options, such as :x and :relx, then the most recent option is used and the older one is ignored.

     The place slaves command returns a list of all the slave windows for which window is the master. If there are no slaves for window then an empty string is returned.

     The place forget command causes the placer to stop managing the geometry of window.  As a side effect of this command window will be unmapped so that it doesn't appear on the screen. If window isn't currently managed by the placer then the command has no effect. Place forget returns an empty string as result.

     The place info command returns a list giving the current configuration of window. The list consists of option:value pairs in exactly the same form as might be specified to the place configure command. If the configuration of a window has been retrieved with place info, that configuration can be restored later by first using place forget to erase any existing information for the window and then invoking place configure with the saved information.

"Fine Points"
-------------

It is not necessary for the master window to be the parent of the slave window. This feature is useful in at least two situations. First, for complex window layouts it means you can create a hierarchy of subwindows whose only purpose is to assist in the layout of the parent. The ``real children'' of the parent (i.e. the windows that are significant for the application's user interface) can be children of the parent yet be placed inside the windows of the geometry-management hierarchy. This means that the path names of the ``real children'' don't reflect the geometry-management hierarchy and users can specify options for the real children without being aware of the structure of the geometry-management hierarchy.

A second reason for having a master different than the slave's parent is to tie two siblings together. For example, the placer can be used to force a window always to be positioned centered just below one of its siblings by specifying the configuration

     :in sibling :relx 0.5 :rely 1.0 :anchor n :bordermode outside

Whenever the sibling is repositioned in the future, the slave will be repositioned as well.

Unlike many other geometry managers (such as the packer) the placer does not make any attempt to manipulate the geometry of the master windows or the parents of slave windows (i.e. it doesn't set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose.

Keywords
--------

geometry manager, height, location, master, place, rubber sheet, slave, width

raise
=====

raise \- Change a window's position in the stacking order

Synopsis
--------

raise window ?aboveThis?

Description
-----------

If the aboveThis argument is omitted then the command raises window so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If aboveThis is specified then it must be the path name of a window that is either a sibling of window or the descendant of a sibling of window. In this case the raise command will insert window into the stacking order just above aboveThis (or the ancestor of aboveThis that is a sibling of window); this could end up either raising or lowering window.

Keywords
--------

obscure, raise, stacking order

selection
=========

selection \- Manipulate the X selection

Synopsis
--------

selection option ?arg arg ...?

Description
-----------

This command provides a Tcl interface to the X selection mechanism and implements the full selection functionality described in the X Inter-Client Communication Conventions Manual (ICCCM), except that it supports only the primary selection.

The first argument to selection determines the format of the rest of the arguments and the behavior of the command.  The following forms are currently supported:

selection :clear window
     If there is a selection anywhere on window's display, clear it so that no window owns the selection anymore.  Returns an empty string.

selection :get ?type?
     Retrieves the value of the primary selection and returns it as a result. Type specifies the form in which the selection is to be returned (the desired ``target'' for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME;  see the Inter-Client Communication Conventions Manual for complete details. Type defaults to STRING.  The selection :owner may choose to return the selection in any of several different representation formats, such as STRING, ATOM, INTEGER, etc. (this format is different than the selection type;  see the ICCCM for all the confusing details).  If the selection is returned in a non-string format, such as INTEGER or ATOM, the selection command converts it to string format as a collection of fields separated by spaces:  atoms are converted to their textual names, and anything else is converted to hexadecimal integers.

selection :handle window command ?type? ?format?
     Creates a handler for selection requests, such that command will be executed whenever the primary selection is owned by window and someone attempts to retrieve it in the form given by type (e.g. type is specified in the selection :get command).  Type defaults to STRING. If command is an empty string then any existing handler for window and type is removed.

     When the selection is requested and window is the selection :owner and type is the requested type, command will be executed as a Tcl command with two additional numbers appended to it (with space separators).  The two additional numbers are offset and maxBytes:  offset specifies a starting character position in the selection and maxBytes gives the maximum number of bytes to retrieve.  The command should return a value consisting of at most maxBytes of the selection, starting at position offset.  For very large selections (larger than maxBytes) the selection will be retrieved using several invocations of command with increasing offset values.  If command returns a string whose length is less than maxBytes, the return value is assumed to include all of the remainder of the selection;  if the length of command's result is equal to maxBytes then command will be invoked again, until it eventually returns a result shorter than maxBytes.  The value of maxBytes will always be relatively large (thousands of bytes).

     If command returns an error then the selection retrieval is rejected just as if the selection didn't exist at all.

     The format argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to STRING.  If format is STRING, the selection is transmitted as 8-bit ASCII characters (i.e. just in the form returned by command).  If format is ATOM, then the return value from command is divided into fields separated by white space;  each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other format, the return value from command is divided into fields separated by white space and each field is converted to a 32-bit integer;  an array of integers is transmitted to the selection requester.

     The format argument is needed only for compatibility with selection requesters that don't use Tk.  If the Tk toolkit is being used to retrieve the selection then the value is converted back to a string at the requesting end, so format is irrelevant. .RE

selection :own ?window? ?command?
     If window is specified, then it becomes the new selection :owner and the command returns an empty string as result. The existing owner, if any, is notified that it has lost the selection. If command is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from window. If neither window nor command is specified then the command returns the path name of the window in this application that owns the selection, or an empty string if no window in this application owns the selection.

Keywords
--------

clear, format, handler, ICCCM, own, selection, target, type

send
====

send \- Execute a command in a different interpreter

Synopsis
--------

send interp cmd ?arg arg ...?

Description
-----------

This command arranges for cmd (and args) to be executed in the interpreter named by interp.  It returns the result or error from that command execution.  Interp must be the name of an interpreter registered on the display associated with the interpreter in which the command is invoked;  it need not be within the same process or application.  If no arg arguments are present, then the command to be executed is contained entirely within the cmd argument.  If one or more args are present, they are concatenated to form the command to be executed, just as for the eval Tcl command.

Security
--------

The send command is potentially a serious security loophole, since any application that can connect to your X server can send scripts to your applications. These incoming scripts can use Tcl to read and write your files and invoke subprocesses under your name. Host-based access control such as that provided by xhost is particularly insecure, since it allows anyone with an account on particular hosts to connect to your server, and if disabled it allows anyone anywhere to connect to your server. In order to provide at least a small amount of security, Tk checks the access control being used by the server and rejects incoming sends unless (a) xhost-style access control is enabled (i.e. only certain hosts can establish connections) and (b) the list of enabled hosts is empty. This means that applications cannot connect to your server unless they use some other form of authorization such as that provide by xauth.

Keywords
--------

interpreter, remote execution, security, send

tk
==

tk \- Manipulate Tk internal state

Synopsis
--------

tk option ?arg arg ...?

Description
-----------

The tk command provides access to miscellaneous elements of Tk's internal state. Most of the information manipulated by this command pertains to the application as a whole, or to a screen or display, rather than to a particular window. The command can take any of a number of different forms depending on the option argument.  The legal forms are:

tk :colormodel window ?newValue?
     If newValue isn't specified, this command returns the current color model in use for window's screen, which will be either color or monochrome. If newValue is specified, then it must be either color or monochrome or an abbreviation of one of them; the color model for window's screen is set to this value.

The color model is used by Tk and its widgets to determine whether it should display in black and white only or use colors. A single color model is shared by all of the windows managed by one process on a given screen. The color model for a screen is set initially by Tk to monochrome if the display has four or fewer bit planes and to color otherwise. The color model will automatically be changed from color to monochrome if Tk fails to allocate a color because all entries in the colormap were in use. An application can change its own color model at any time (e.g. it might change the model to monochrome in order to conserve colormap entries, or it might set the model to color to use color on a four-bit display in special circumstances), but an application is not allowed to change the color model to color unless the screen has at least two bit planes. .RE

Keywords
--------

color model, internal state

tkerror
=======

tkerror \- Command invoked to process background errors

Synopsis
--------

tkerror message

Description
-----------

The tkerror command doesn't exist as built-in part of Tk.  Instead, individual applications or users can define a tkerror command (e.g. as a Tcl procedure) if they wish to handle background errors.

A background error is one that occurs in a command that didn't originate with the application.  For example, if an error occurs while executing a command specified with a bind of after command, then it is a background error.  For a non-background error, the error can simply be returned up through nested Tcl command evaluations until it reaches the top-level code in the application; then the application can report the error in whatever way it wishes.  When a background error occurs, the unwinding ends in the Tk library and there is no obvious way for Tk to report the error.

When Tk detects a background error, it invokes the tkerror command, passing it the error message as its only argument. Tk assumes that the application has implemented the tkerror command, and that the command will report the error in a way that makes sense for the application.  Tk will ignore any result returned by the tkerror command.

If another Tcl error occurs within the tkerror command then Tk reports the error itself by writing a message to stderr.

The Tk script library includes a default tkerror procedure that posts a dialog box containing the error message and offers the user a chance to see a stack trace that shows where the error occurred.

Keywords
--------

background error, reporting

tkvars
======

tkvars \- Variables used or set by Tk

Description
-----------

The following Tcl variables are either set or used by Tk at various times in its execution:

tk_library
     Tk sets this variable hold the name of a directory containing a library of Tcl scripts related to Tk.  These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors for widgets. The value of this variable is taken from the TK_LIBRARY environment variable, if one exists, or else from a default value compiled into Tk.

tk_patchLevel
     Contains a decimal integer giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk.

tk_priv
     This variable is an array containing several pieces of information that are private to Tk.  The elements of tk_priv are used by Tk library procedures and default bindings. They should not be accessed by any code outside Tk.

tk_strictMotif
     This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them.

tk_version
     Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form major.minor.  Major and minor are integers.  The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release).  The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes.

tkVersion
     Has the same value as tk_version.  This variable is obsolete and will be deleted soon.

Keywords
--------

variables, version

tkwait
======

tkwait \- Wait for variable to change or window to be destroyed

Synopsis
--------

tkwait :variable name

tkwait :visibility name

tkwait :window name

Description
-----------

The tkwait command waits for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. If the first argument is :variable (or any abbreviation of it) then the second argument is the name of a global variable and the command waits for that variable to be modified. If the first argument is :visibility (or any abbreviation of it) then the second argument is the name of a window and the tkwait command waits for a change in its visibility state (as indicated by the arrival of a VisibilityNotify event).  This form is typically used to wait for a newly-created window to appear on the screen before taking some action. If the first argument is :window (or any abbreviation of it) then the second argument is the name of a window and the tkwait command waits for that window to be destroyed. This form is typically used to wait for a user to finish interacting with a dialog box before using the result of that interaction.

While the tkwait command is waiting it processes events in the normal fashion, so the application will continue to respond to user interactions.

Keywords
--------

variable, visibility, wait, window

update
======

update \- Process pending events and/or when-idle handlers

Synopsis
--------

update ?:idletasks?

Description
-----------

This command is used to bring the entire application world ``up to date.'' It flushes all pending output to the display,  waits for the server to process that output and return errors or events, handles all pending events of any sort (including when-idle handlers), and repeats this set of operations until there are no pending events, no pending when-idle handlers, no pending output to the server, and no operations still outstanding at the server.

If the idletasks keyword is specified as an argument to the command, then no new events or errors are processed;  only when-idle idlers are invoked. This causes operations that are normally deferred, such as display updates and window layout calculations, to be performed immediately.

The update :idletasks command is useful in scripts where changes have been made to the application's state and you want those changes to appear on the display immediately, rather than waiting for the script to complete. The update command with no options is useful in scripts where you are performing a long-running computation but you still want the application to respond to user interactions;  if you occasionally call update then user input will be processed during the next call to update.

Keywords
--------

event, flush, handler, idle, update

winfo
=====

winfo \- Return window-related information

Synopsis
--------

winfo option ?arg arg ...?

Description
-----------

The winfo command is used to retrieve information about windows managed by Tk.  It can take any of a number of different forms, depending on the option argument.  The legal forms are:

winfo :atom name
     Returns a decimal string giving the integer identifier for the atom whose name is name.  If no atom exists with the name name then a new one is created.

winfo :atomname id
     Returns the textual name for the atom whose integer identifier is id. This command is the inverse of the winfo :atom command. Generates an error if no such atom exists.

winfo :cells window
     Returns a decimal string giving the number of cells in the color map for window.

winfo :children window
     Returns a list containing the path names of all the children of window.  Top-level windows are returned as children of their logical parents.

winfo :class window
     Returns the class name for window.

winfo :containing rootX rootY
     Returns the path name for the window containing the point given by rootX and rootY. RootX and rootY are specified in screen units (i.e. any form acceptable to Tk_GetPixels) in the coordinate system of the root window (if a virtual-root window manager is in use then the coordinate system of the virtual root window is used). If no window in this application contains the point then an empty string is returned. In selecting the containing window, children are given higher priority than parents and among siblings the highest one in the stacking order is chosen.

winfo :depth window
     Returns a decimal string giving the depth of window (number of bits per pixel).

winfo :exists window
     Returns 1 if there exists a window named window, 0 if no such window exists.

winfo :fpixels window number
     Returns a floating-point value giving the number of pixels in window corresponding to the distance given by number. Number may be specified in any of the forms acceptable to Tk_GetScreenMM, such as ``2.0c'' or ``1i''. The return value may be fractional;  for an integer value, use winfo :pixels.

winfo :geometry window
     Returns the geometry for window, in the form widthxheight+x+y.  All dimensions are in pixels.

winfo :height window
     Returns a decimal string giving window's height in pixels. When a window is first created its height will be 1 pixel;  the height will eventually be changed by a geometry manager to fulfill the window's needs. If you need the true height immediately after creating a widget, invoke update to force the geometry manager to arrange it, or use winfo :reqheight to get the window's requested height instead of its actual height.

winfo :id window
     Returns a hexadecimal string indicating the X identifier for window.

winfo :interps
     Returns a list whose members are the names of all Tcl interpreters (e.g. all Tk-based applications) currently registered for the display of the invoking application.

winfo :ismapped window
     Returns 1 if window is currently mapped, 0 otherwise.

winfo :name window
     Returns window's name (i.e. its name within its parent, as opposed to its full path name). The command winfo :name . will return the name of the application.

winfo :parent window
     Returns the path name of window's parent, or an empty string if window is the main window of the application.

winfo :pathname id
     Returns the path name of the window whose X identifier is id. Id must be a decimal, hexadecimal, or octal integer and must correspond to a window in the invoking application.

winfo :pixels window number
     Returns the number of pixels in window corresponding to the distance given by number. Number may be specified in any of the forms acceptable to Tk_GetPixels, such as ``2.0c'' or ``1i''. The result is rounded to the nearest integer value;  for a fractional result, use winfo :fpixels.

winfo :reqheight window
     Returns a decimal string giving window's requested height, in pixels.  This is the value used by window's geometry manager to compute its geometry.

winfo :reqwidth window
     Returns a decimal string giving window's requested width, in pixels.  This is the value used by window's geometry manager to compute its geometry.

winfo :rgb window color
     Returns a list containing three decimal values, which are the red, green, and blue intensities that correspond to color in the window given by window.  Color may be specified in any of the forms acceptable for a color option.

winfo :rootx window
     Returns a decimal string giving the x-coordinate, in the root window of the screen, of the upper-left corner of window's border (or window if it has no border).

winfo :rooty window
     Returns a decimal string giving the y-coordinate, in the root window of the screen, of the upper-left corner of window's border (or window if it has no border).

winfo :screen window
     Returns the name of the screen associated with window, in the form displayName.screenIndex.

winfo :screencells window
     Returns a decimal string giving the number of cells in the default color map for window's screen.

winfo :screendepth window
     Returns a decimal string giving the depth of the root window of window's screen (number of bits per pixel).

winfo :screenheight window
     Returns a decimal string giving the height of window's screen, in pixels.

winfo :screenmmheight window
     Returns a decimal string giving the height of window's screen, in millimeters.

winfo :screenmmwidth window
     Returns a decimal string giving the width of window's screen, in millimeters.

winfo :screenvisual window
     Returns one of the following strings to indicate the default visual type for window's screen: directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor.

winfo :screenwidth window
     Returns a decimal string giving the width of window's screen, in pixels.

winfo :toplevel window
     Returns the path name of the top-level window containing window.

winfo :visual window
     Returns one of the following strings to indicate the visual type for window: directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor.

winfo :vrootheight window
     Returns the height of the virtual root window associated with window if there is one;  otherwise returns the height of window's screen.

winfo :vrootwidth window
     Returns the width of the virtual root window associated with window if there is one;  otherwise returns the width of window's screen.

winfo :vrootx window
     Returns the x-offset of the virtual root window associated with window, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for window.

winfo :vrooty window
     Returns the y-offset of the virtual root window associated with window, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for window.

winfo :width window
     Returns a decimal string giving window's width in pixels. When a window is first created its width will be 1 pixel;  the width will eventually be changed by a geometry manager to fulfill the window's needs. If you need the true width immediately after creating a widget, invoke update to force the geometry manager to arrange it, or use winfo :reqwidth to get the window's requested width instead of its actual width.

winfo :x window
     Returns a decimal string giving the x-coordinate, in window's parent, of the upper-left corner of window's border (or window if it has no border).

winfo :y window
     Returns a decimal string giving the y-coordinate, in window's parent, of the upper-left corner of window's border (or window if it has no border).

Keywords
--------

atom, children, class, geometry, height, identifier, information, interpreters, mapped, parent, path name, screen, virtual root, width, window

wm
==

wm \- Communicate with window manager

Synopsis
--------

wm option window ?args?

Description
-----------

The wm command is used to interact with window managers in order to control such things as the title for a window, its geometry, or the increments in terms of which it may be resized.  The wm command can take any of a number of different forms, depending on the option argument.  All of the forms expect at least one additional argument, window, which must be the path name of a top-level window.

The legal forms for the wm command are:

wm :aspect window ?minNumer minDenom maxNumer maxDenom?
     If minNumer, minDenom, maxNumer, and maxDenom are all specified, then they will be passed to the window manager and the window manager should use them to enforce a range of acceptable aspect ratios for window.  The aspect ratio of window (width/length) will be constrained to lie between minNumer/minDenom and maxNumer/maxDenom. If minNumer etc. are all specified as empty strings, then any existing aspect ratio restrictions are removed. If minNumer etc. are specified, then the command returns an empty string.  Otherwise, it returns a Tcl list containing four elements, which are the current values of minNumer, minDenom, maxNumer, and maxDenom (if no aspect restrictions are in effect, then an empty string is returned).

wm :client window ?name?
     If name is specified, this command stores name (which should be the name of the host on which the application is executing) in window's WM_CLIENT_MACHINE property for use by the window manager or session manager. The command returns an empty string in this case. If name isn't specified, the command returns the last name set in a wm :client command for window. If name is specified as an empty string, the command deletes the WM_CLIENT_MACHINE property from window.

wm :command window ?value?
     If value is specified, this command stores value in window's WM_COMMAND property for use by the window manager or session manager and returns an empty string. Value must have proper list structure;  the elements should contain the words of the command used to invoke the application. If value isn't specified then the command returns the last value set in a wm :command command for window. If value is specified as an empty string, the command deletes the WM_COMMAND property from window.

wm :deiconify window
     Arrange for window to be displayed in normal (non-iconified) form. This is done by mapping the window.  If the window has never been mapped then this command will not map the window, but it will ensure that when the window is first mapped it will be displayed in de-iconified form.  Returns an empty string.

wm :focusmodel window ?active|passive?
     If active or passive is supplied as an optional argument to the command, then it specifies the focus model for window. In this case the command returns an empty string.  If no additional argument is supplied, then the command returns the current focus model for window. An active focus model means that window will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application.  Passive means that window will never claim the focus for itself:  the window manager should give the focus to window at appropriate times.  However, once the focus has been given to window or one of its descendants, the application may re-assign the focus among window's descendants. The focus model defaults to passive, and Tk's focus command assumes a passive model of focussing.

wm :frame window
     If window has been reparented by the window manager into a decorative frame, the command returns the X window identifier for the outermost frame that contains window (the window whose parent is the root or virtual root).  If window hasn't been reparented by the window manager then the command returns the X window identifier for window.

wm :geometry window ?newGeometry?
     If newGeometry is specified, then the geometry of window is changed and an empty string is returned.  Otherwise the current geometry for window is returned (this is the most recent geometry specified either by manual resizing or in a wm :geometry command).  NewGeometry has the form =widthxheight\(+-x\(+-y, where any of =, widthxheight, or \(+-x\(+-y may be omitted.  Width and height are positive integers specifying the desired dimensions of window.  If window is gridded (see GRIDDED GEOMETRY MANAGEMENT below) then the dimensions are specified in grid units;  otherwise they are specified in pixel units.  X and y specify the desired location of window on the screen, in pixels. If x is preceded by +, it specifies the number of pixels between the left edge of the screen and the left edge of window's border;  if preceded by - then x specifies the number of pixels between the right edge of the screen and the right edge of window's border.  If y is preceded by + then it specifies the number of pixels between the top of the screen and the top of window's border;  if y is preceded by - then it specifies the number of pixels between the bottom of window's border and the bottom of the screen. If newGeometry is specified as an empty string then any existing user-specified geometry for window is cancelled, and the window will revert to the size requested internally by its widgets.

wm :grid window ?baseWidth baseHeight widthInc heightInc?
     This command indicates that window is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. BaseWidth and baseHeight specify the number of grid units corresponding to the pixel dimensions requested internally by window using Tk_GeometryRequest.  WidthInc and heightInc specify the number of pixels in each horizontal and vertical grid unit. These four values determine a range of acceptable sizes for window, corresponding to grid-based widths and heights that are non-negative integers. Tk will pass this information to the window manager;  during manual resizing, the window manager will restrict the window's size to one of these acceptable sizes. Furthermore, during manual resizing the window manager will display the window's current size in terms of grid units rather than pixels. If baseWidth etc. are all specified as empty strings, then window will no longer be managed as a gridded window.  If baseWidth etc. are specified then the return value is an empty string. Otherwise the return value is a Tcl list containing four elements corresponding to the current baseWidth, baseHeight, widthInc, and heightInc;  if window is not currently gridded, then an empty string is returned. Note: this command should not be needed very often, since the Tk_SetGrid library procedure and the setGrid option provide easier access to the same functionality.

wm :group window ?pathName?
     If pathName is specified, it gives the path name for the leader of a group of related windows.  The window manager may use this information, for example, to unmap all of the windows in a group when the group's leader is iconified.  PathName may be specified as an empty string to remove window from any group association.  If pathName is specified then the command returns an empty string;  otherwise it returns the path name of window's current group leader, or an empty string if window isn't part of any group.

wm :iconbitmap window ?bitmap?
     If bitmap is specified, then it names a bitmap in the standard forms accepted by Tk (see the Tk_GetBitmap manual entry for details). This bitmap is passed to the window manager to be displayed in window's icon, and the command returns an empty string.  If an empty string is specified for bitmap, then any current icon bitmap is cancelled for window. If bitmap is specified then the command returns an empty string. Otherwise it returns the name of the current icon bitmap associated with window, or an empty string if window has no icon bitmap.

wm :iconify window
     Arrange for window to be iconified.  It window hasn't yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped.

wm :iconmask window ?bitmap?
     If bitmap is specified, then it names a bitmap in the standard forms accepted by Tk (see the Tk_GetBitmap manual entry for details). This bitmap is passed to the window manager to be used as a mask in conjunction with the iconbitmap option:  where the mask has zeroes no icon will be displayed;  where it has ones, the bits from the icon bitmap will be displayed.  If an empty string is specified for bitmap then any current icon mask is cancelled for window (this is equivalent to specifying a bitmap of all ones).  If bitmap is specified then the command returns an empty string.  Otherwise it returns the name of the current icon mask associated with window, or an empty string if no mask is in effect.

wm :iconname window ?newName?
     If newName is specified, then it is passed to the window manager;  the window manager should display newName inside the icon associated with window.  In this case an empty string is returned as result.  If newName isn't specified then the command returns the current icon name for window, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the wm :title command).

wm :iconposition window ?x y?
     If x and y are specified, they are passed to the window manager as a hint about where to position the icon for window. In this case an empty string is returned.  If x and y are specified as empty strings then any existing icon position hint is cancelled. If neither x nor y is specified, then the command returns a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned).

wm :iconwindow window ?pathName?
     If pathName is specified, it is the path name for a window to use as icon for window: when window is iconified then pathName should be mapped to serve as icon, and when window is de-iconified then pathName will be unmapped again.  If pathName is specified as an empty string then any existing icon window association for window will be cancelled.  If the pathName argument is specified then an empty string is returned.  Otherwise the command returns the path name of the current icon window for window, or an empty string if there is no icon window currently specified for window.  Note: not all window managers support the notion of an icon window.

wm :maxsize window ?width height?
     If width and height are specified, then window becomes resizable and width and height give its maximum permissible dimensions. For gridded windows the dimensions are specified in grid units;  otherwise they are specified in pixel units. During manual sizing, the window manager should restrict the window's dimensions to be less than or equal to width and height. If width and height are specified as empty strings, then the maximum size option is cancelled for window. If width and height are specified, then the command returns an empty string.  Otherwise it returns a Tcl list with two elements, which are the maximum width and height currently in effect;  if no maximum dimensions are in effect for window then an empty string is returned.  See the sections on geometry management below for more information.

wm :minsize window ?width height?
     If width and height are specified, then window becomes resizable and width and height give its minimum permissible dimensions. For gridded windows the dimensions are specified in grid units;  otherwise they are specified in pixel units. During manual sizing, the window manager should restrict the window's dimensions to be greater than or equal to width and height. If width and height are specified as empty strings, then the minimum size option is cancelled for window. If width and height are specified, then the command returns an empty string.  Otherwise it returns a Tcl list with two elements, which are the minimum width and height currently in effect;  if no minimum dimensions are in effect for window then an empty string is returned.  See the sections on geometry management below for more information.

wm :overrideredirect window ?boolean?
     If boolean is specified, it must have a proper boolean form and the override-redirect flag for window is set to that value. If boolean is not specified then 1 or 0 is returned to indicate whether or not the override-redirect flag is currently set for window. Setting the override-redirect flag for a window causes it to be ignored by the window manager;  among other things, this means that the window will not be reparented from the root window into a decorative frame and the user will not be able to manipulate the window using the normal window manager mechanisms.

wm :positionfrom window ?who?
     If who is specified, it must be either program or user, or an abbreviation of one of these two.  It indicates whether window's current position was requested by the program or by the user.  Many window managers ignore program-requested initial positions and ask the user to manually position the window;  if user is specified then the window manager should position the window at the given place without asking the user for assistance. If who is specified as an empty string, then the current position source is cancelled. If who is specified, then the command returns an empty string. Otherwise it returns user or window to indicate the source of the window's current position, or an empty string if no source has been specified yet.  Most window managers interpret ``no source'' as equivalent to program. Tk will automatically set the position source to user when a wm :geometry command is invoked, unless the source has been set explicitly to program.

wm :protocol window ?name? ?command?
     This command is used to manage window manager protocols such as WM_DELETE_WINDOW. Name is the name of an atom corresponding to a window manager protocol, such as WM_DELETE_WINDOW or WM_SAVE_YOURSELF or WM_TAKE_FOCUS. If both name and command are specified, then command is associated with the protocol specified by name. Name will be added to window's WM_PROTOCOLS property to tell the window manager that the application has a protocol handler for name, and command will be invoked in the future whenever the window manager sends a message to the client for that protocol. In this case the command returns an empty string. If name is specified but command isn't, then the current command for name is returned, or an empty string if there is no handler defined for name. If command is specified as an empty string then the current handler for name is deleted and it is removed from the WM_PROTOCOLS property on window;  an empty string is returned. Lastly, if neither name nor command is specified, the command returns a list of all the protocols for which handlers are currently defined for window.

Tk always defines a protocol handler for WM_DELETE_WINDOW, even if you haven't asked for one with wm :protocol. If a WM_DELETE_WINDOW message arrives when you haven't defined a handler, then Tk handles the message by destroying the window for which it was received. .RE

wm :sizefrom window ?who?
     If who is specified, it must be either program or user, or an abbreviation of one of these two.  It indicates whether window's current size was requested by the program or by the user.  Some window managers ignore program-requested sizes and ask the user to manually size the window;  if user is specified then the window manager should give the window its specified size without asking the user for assistance. If who is specified as an empty string, then the current size source is cancelled. If who is specified, then the command returns an empty string. Otherwise it returns user or window to indicate the source of the window's current size, or an empty string if no source has been specified yet.  Most window managers interpret ``no source'' as equivalent to program.

wm :state window
     Returns the current state of window:  either normal, iconic, or withdrawn.

wm :title window ?string?
     If string is specified, then it will be passed to the window manager for use as the title for window (the window manager should display this string in window's title bar).  In this case the command returns an empty string.  If string isn't specified then the command returns the current title for the window.  The title for a window defaults to its name.

wm :transient window ?master?
     If master is specified, then the window manager is informed that window is a transient window (e.g. pull-down menu) working on behalf of master (where master is the path name for a top-level window).  Some window managers will use this information to manage window specially.  If master is specified as an empty string then window is marked as not being a transient window any more.  If master is specified, then the command returns an empty string.  Otherwise the command returns the path name of window's current master, or an empty string if window isn't currently a transient window.

wm :withdraw window
     Arranges for window to be withdrawn from the screen.  This causes the window to be unmapped and forgotten about by the window manager.  If the window has never been mapped, then this command causes the window to be mapped in the withdrawn state.  Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. Note: it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with wm :deiconify) to get some window managers to pay attention to changes in window attributes such as group.

"Sources Of Geometry Information"
---------------------------------

Size-related information for top-level windows can come from three sources. First, geometry requests come from the widgets that are descendants of a top-level window. Each widget requests a particular size for itself by calling Tk_GeometryRequest.  This information is passed to geometry managers, which then request large enough sizes for parent windows so that they can layout the children properly. Geometry information passes upwards through the window hierarchy until eventually a particular size is requested for each top-level window. These requests are called internal requests in the discussion below. The second source of width and height information is through the wm :geometry command.  Third, the user can request a particular size for a window using the interactive facilities of the window manager. The second and third types of geometry requests are called external requests in the discussion below;  Tk treats these two kinds of requests identically.

"Ungridded Geometry Management"
-------------------------------

Tk allows the geometry of a top-level window to be managed in either of two general ways: ungridded or gridded. The ungridded form occurs if no wm :grid command has been issued for a top-level window. Ungridded management has several variants. In the simplest variant of ungridded windows, no wm :geometry, wm :minsize, or wm :maxsize commands have been invoked either. In this case, the window's size is determined totally by the internal requests emanating from the widgets inside the window:  Tk will ask the window manager not to permit the user to resize the window interactively.

If a wm :geometry command is invoked on an ungridded window, then the size in that command overrides any size requested by the window's widgets;  from now on, the window's size will be determined entirely by the most recent information from wm :geometry commands.  To go back to using the size requested by the window's widgets, issue a wm :geometry command with an empty geometry string.

To enable interactive resizing of an ungridded window, one or both of the wm :maxsize and wm :minsize commands must be issued. The information from these commands will be passed to the window manager, and size changes within the specified range will be permitted. For ungridded windows the limits refer to the top-level window's dimensions in pixels. If only a wm :maxsize command is issued then the minimum dimensions default to 1;  if only a wm :minsize command is issued then the maximum dimensions default to the size of the display. If the size of a window is changed interactively, it has the same effect as if wm :geometry had been invoked:  from now on, internal geometry requests will be ignored. To return to internal control over the window's size, issue a wm :geometry command with an empty geometry argument. If a window has been manually resized or moved, the wm :geometry command will return the geometry that was requested interactively.

"Gridded Geometry Management"
-----------------------------

The second style of geometry management is called gridded. This approach occurs when one of the widgets of an application supports a range of useful sizes. This occurs, for example, in a text editor where the scrollbars, menus, and other adornments are fixed in size but the edit widget can support any number of lines of text or characters per line. In this case, it is usually desirable to let the user specify the number of lines or characters-per-line, either with the wm :geometry command or by interactively resizing the window. In the case of text, and in other interesting cases also, only discrete sizes of the window make sense, such as integral numbers of lines and characters-per-line;  arbitrary pixel sizes are not useful.

Gridded geometry management provides support for this kind of application. Tk (and the window manager) assume that there is a grid of some sort within the application and that the application should be resized in terms of grid units rather than pixels. Gridded geometry management is typically invoked by turning on the setGrid option for a widget;  it can also be invoked with the wm :grid command or by calling Tk_SetGrid. In each of these approaches the particular widget (or sometimes code in the application as a whole) specifies the relationship between integral grid sizes for the window and pixel sizes. To return to non-gridded geometry management, invoke wm :grid with empty argument strings.

When gridded geometry management is enabled then all the dimensions specified in wm :minsize, wm :maxsize, and wm :geometry commands are treated as grid units rather than pixel units. Interactive resizing is automatically enabled, and it will be carried out in even numbers of grid units rather than pixels. By default there are no limits on the minimum or maximum dimensions of a gridded window. As with ungridded windows, interactive resizing has exactly the same effect as invoking the wm :geometry command. For gridded windows, internally- and externally-requested dimensions work together: the externally-specified width and height determine the size of the window in grid units, and the information from the last wm :grid command maps from grid units to pixel units.

Bugs
----

The window manager interactions seem too complicated, especially for managing geometry.  Suggestions on how to simplify this would be greatly appreciated.

Most existing window managers appear to have bugs that affect the operation of the wm command.  For example, some changes won't take effect if the window is already active:  the window will have to be withdrawn and de-iconified in order to make the change happen.

Keywords
--------

aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager