Next: , Previous: , Up: Windows   [Contents][Index]

8.5 Input Focus

The input focus defines exactly which client window will receive events generated by the keyboard.

Function: input-focus

Returns the window object of the currently focused window, or nil if no window is focused.

Function: set-input-focus window

Sets the focus to the client window associated with window.

If window is nil, then no window will have the focus.

Function: window-wants-input-p window

If you’re unsure, use window-really-wants-input-p function described below.

Return t when the window window wants input focus in X sense, i.e. if it has asked for the input focus to be assigned to, through the input field of its WM_HINTS property.

Function: window-really-wants-input-p window

Like window-wants-input-p, but in addition, this function also takes into account user option provided by Sawfish, i.e. if the window has never-focus property or not.

The window manager is responsible for switching the input focus from client window to client window. Sawfish implements several focus modes that provide this behavior. Each focus mode is bound to a symbol; the implementation is bound to that symbol’s focus-mode property slot.

Variable: focus-mode

Defines the current method of using the mouse to assign the input focus. This is a symbol from the list focus-modes.

Variable: focus-modes

A list containing all names of focus modes. The built-in values are enter-exit, enter-only, enter-click and click.

Focus mode enter-exit changes focus when the pointer enters a window or leaves the focused window. Focus mode enter-only changes focus when the pointer enters a window, but not when it leaves the focused window. Focus mode click changes focus when you click on a window. Focus mode enter-click is the union of enter-only and click, and changes focus on any of their conditions.

It is possible to add additional focus modes by defining your own handler function. The handler function must obey a “focus-mode-handler” protocol.

Function Protocol: focus-mode-handler window event-name #!optional args

A function that implements the focus-mode-handler protocol can be used to define a focus mode. A focus-mode-handler responds to events associated with windows.

Argument window is the window that received this event.

Argument event-name is one of the following symbols:


The pointer has entered or exited the window. The handler is responsible for checking whether an entered window wants input events. The desktop never receives pointer-in or pointer-out; only normal windows do.


The pointer has entered or exited the desktop (which is the window argument). Normal windows never receive enter-root or leave-root.


The window argument has gotten or lost focus. Note that the focus-in handler is not responsible for updating the window-order list.


Sawfish sends these synthetic events to each window before/after changing that window’s focus mode. When the global focus mode changes, all windows get these events.


Sawfish sends this event to every window immediately after mapping it. Handlers can use this to initialize window-internal data structures.


Warp the cursor to the window if doing so would make the cursor position “consistent” with the focus mode. For example, in enter-exit mode we warp the cursor if it is not already in this window. In enter-only mode, we warp the cursor if it is in another window, but not if it is over the desktop—a window would not lose focus when the cursor moved from it to the desktop.

This event is implemented via warp-cursor-to-window, so Sawfish will not warp unless warp-to-window-enabled is true.


The focused window has disappeared (the window argument is not used here). The focus mode may react by setting focus to some other window. If a focused transient window disappears, focus normally reverts to the window that the disappearing window was transient for. focus-revert is not invoked in that case.

The protocol allows for any number of additional arguments, but does not define any. Any handler function must be prepared to receive and ignore them.

Unsupported events may be ignored. The return value of this function is ignored.

Function: define-focus-mode name fun

Defines a new focus mode called name (a symbol). The focus-mode handler fun implements this focus mode.

See the documentation for focus-mode-handler for more information.

Function: set-focus-mode window mode

Set the focus mode of window window to mode. This triggers before-mode-change and after-mode-change focus-mode events on window.

Function: warp-pointer-if-necessary window

Generate a warp-if-necessary event and sends it to the window’s focus function.

Various functions call warp-pointer-if-necessary if they move the focused window out from underneath the pointer.

Variable: focus-click-through

When in click focus mode, the focus-assigning click is only passed through to the client window if this variable is t (the default).

This option may be set on a per-window basis by setting the focus-click-through property of the window (using the window-put function).

Variable: focus-within-click-event

When true, the current command is being called from within a click-to-focus button press event.

This is a fluid object, not an ordinary variable.

Sawfish also maintains the order in which windows were recently focused.

Function: window-order #!optional workspace allow-iconified all-viewports

Return a list of windows, in most-recently-focused order.

If workspace is an integer, then only windows on that workspace are included, otherwise all workspaces are searched.

If allow-iconified is non-nil, iconified windows are included. If all-viewports is non-nil, then all viewports of the workspace(s) are scanned.

Function: window-order-push window

Push window object window onto the top of the focus stack.

Function: window-order-pop window

Remove window object window from the focus stack.

Function: window-order-most-recent #!optional windows

Return the most-recently focused window in the current workspace. If the optional argument windows is given, it must be a list of windows. In that case, the function will return the most-recently focused window from that list.

Function: window-order-focus-most-recent

Focus the most-recently-focused window of the current workspace.

Variable: focus-dont-push

When true, focusing a window doesn’t change it’s position in the stack of most-recently focused windows.

Other focus related functions:

Function: window-in-cycle-p window &keyword ignore-cycle-skip

Returns t if the window window should be included when cycling between windows. Desktop windows and those with the cycle-skip property should normally not be included.

When t, the ignore-cycle-skip keyword argument forces the function to include windows with the cycle-skip property.

Function: focus-push-map window keymap
Function: focus-pop-map window

Maintain a two-element keymap stack for window.

focus-push-map makes keymap current for window, but saves the existing keymap. We can restore this existing keymap with focus-pop-map.

These functions are intended to support click-to-focus. They enforce certain sanity rules: pushing into a two-element stack will only overwrite the top element, while popping a one-element stack has no effect.

Function: autoload-focus-mode name func

MISSING. This does not seem to be used anywhere, and its behavior is unclear.

Function: select-window

Waits for the user to left-click on a window, and returns that window. The mouse cursor changes shape, and all normal input events are suppressed until a window is selected. For root window, nil is returned.

Variable: select-window-cursor-shape

The cursor shape to use when selecting a window. Defaults to crosshair.

Next: , Previous: , Up: Windows   [Contents][Index]