Node: Input Focus, Next: , Previous: Window Attributes, Up: Windows


Input Focus

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

input-focus Function
Returns the window object of the currently focused window, or nil if no window is focused.

set-input-focus window Function
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.

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

focus-modes Variable
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.

focus-mode-handler window event-name &optional args Function Protocol
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.

define-focus-mode name fun Function
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.

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

warp-pointer-if-necessary window Function
Generate a warp-if-necessary event and send it to the window's focus function.

focus-click-through Variable
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).

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

focus-within-click-event Variable
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.

window-order &optional workspace allow-iconified all-viewports Function
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.

window-order-push window Function
Push window object window onto the top of the focus stack.

window-order-pop window Function
Remove window object window from the focus stack.

window-order-most-recent &optional windows Function
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.

window-order-focus-most-recent Function
Focus the most-recently-focused window of the current workspace.

focus-dont-push Variable
When true, focusing a window doesn't change it's position in the stack of most-recently focused windows.

window-in-cycle-p window &keyword ignore-cycle-skip Function
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.

focus-push-map window keymap Function
focus-pop-map window Function
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.

autoload-focus-mode name func Function
MISSING. This does not seem to be used anywhere, and its behavior is unclear.

select-window Function
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.

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