### 3.6 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