Input Focus - sawfish Programming Manual

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.

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 and click.

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:

pointer-in
pointer-out
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.

enter-root
leave-root
The pointer has entered or exited the desktop (which is the window argument). Normal windows never receive enter-root or leave-root.
focus-in
focus-out
The window argument has gotten or lost focus. Note that the focus-in handler is not responsible for updating the window-order list.
before-mode-change
after-mode-change
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.
add-window
Sawfish sends this event to every window immediately after mapping it. Handlers can use this to initialize window-internal data structures.
warp-if-necessary
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.

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 send it to the window's focus function.

— 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-ignore-pointer-events

When true, pointer in/out events don't cause focus changes. This is independent of the current focus mode.

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

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

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

8.4 Input Focus