5. Windows

Command: next

Go to the next window in the window list.

Command: prev

Go to the previous window in the window list.

Command: delete-window &optional (window (current-window))

Delete a window. By default delete the current window. This is a request sent to the window. The window’s client may decide not to grant the request or may not be able to if it is unresponsive.

Command: kill-window &optional (window (current-window))

Tell X to disconnect the client that owns the specified window. Default to the current window. if delete-window didn’t work, try this.

Command: kill-windows-current-group

Kill all windows in the current group.

Command: kill-windows-other

Kill all windows in current group except the current-window

Command: echo-windows &optional (fmt *window-format*) (group (current-group)) (windows (group-windows group))

Display a list of managed windows. The optional argument fmt can be used to override the default window formatting.

Command: other-window &optional (group (current-group))

Switch to the window last focused.

Command: pull-hidden-next

Pull the next hidden window into the current frame.

Command: pull-hidden-previous

Pull the next hidden window into the current frame.

Command: pull-hidden-other

Pull the last focused, hidden window into the current frame.

Command: pull-from-windowlist

Pulls a window selected from the list of windows. This allows a behavior similar to Emacs’ switch-to-buffer when selecting another window.

Command: renumber nt &optional (group (current-group))

Change the current window’s number to the specified number. If another window is using the number, then the windows swap numbers. Defaults to current group.

Command: meta key

Send a fake key to the current window. key is a typical StumpWM key, like C-M-o.

Command: select-window query

Switch to the first window that starts with query.

Command: select-window-by-number num &optional (group (current-group))

Find the window with the given number and focus it in its frame.

Command: select-window-by-name name

Switch to the first window whose name is exactly name.

Command: repack-window-numbers &optional preserved

Ensure that used window numbers do not have gaps; ignore PRESERVED window numbers.

Command: title title

Override the current window’s title.

Command: windowlist &optional (fmt *window-format*) window-list

Allow the user to select a window from the list of windows and focus the selected window. For information of menu bindings see Menus. The optional argument fmt can be specified to override the default window formatting. The optional argument window-list can be provided to show a custom window list (see windowlist-by-class). The default window list is the list of all window in the current group. Also note that the default window list is sorted by number and if the windows-list is provided, it is shown unsorted (as-is).

Command: windowlist-by-class &optional (fmt *window-format-by-class*)

Allow the user to select a window from the list of windows (sorted by class) and focus the selected window. For information of menu bindings see Menus. The optional argument fmt can be specified to override the default window formatting. This is a simple wrapper around the command windowlist.

Command: fullscreen

Toggle the fullscreen mode of the current widnow. Use this for clients with broken (non-NETWM) fullscreen implementations, such as any program using SDL.

Command: info &optional (fmt *window-info-format*)

Display information about the current window.

Command: refresh

Refresh current window without changing its size.

Command: redisplay

Refresh current window by a pair of resizes, also make it occupy entire frame.

Command: float-this

Transforms a tile-window into a float-window

Command: unfloat-this

Transforms a float-window into a tile-window

Command: flatten-floats

Transform all floating windows in this group to tiled windows. Puts all tiled windows in the first frame of the group.

Command: unmaximize

Use the size the program requested for current window (if any) instead of maximizing it.

Command: toggle-always-on-top

Toggle whether the current window always appears over other windows. The order windows are added to this list determines priority.

Command: toggle-always-show

Toggle whether the current window is shown in all groups.

Function: window-head window

Report what window the head is currently on.

Function: window-sync window what-changed

Some window slot has been updated and the window may need to sync itself. WHAT-CHANGED is a hint at what changed.

Function: window-visible-p window

Return T if the window is visible

Variable: *xwin-to-window*

Hash table for looking up windows quickly.

Variable: *window-format*

This variable decides how the window list is formatted. It is a string with the following formatting options:

%n

Substitutes the window’s number translated via *window-number-map*, if there are more windows than *window-number-map* then will use the window-number.

%s

Substitute the window’s status. * means current window, + means last window, and - means any other window.

%t

Substitute the window’s name.

%c

Substitute the window’s class.

%i

Substitute the window’s resource ID.

%m

Draw a # if the window is marked.

Note, a prefix number can be used to crop the argument to a specified size. For instance, ‘%20t’ crops the window’s title to 20 characters.

Variable: *window-info-format*

The format used in the info command. See *window-format* for formatting details.

Variable: *window-name-source*

This variable controls what is used for the window’s name. The default is :title.

:title

Use the window’s title given to it by its owner.

:class

Use the window’s resource class.

:resource-name

Use the window’s resource name.

Variable: *new-window-preferred-frame*

This variable controls what frame a new window appears in. It is a list of preferences. The first preference that is satisfied is used. Valid list elements are as follows:

:focused

Choose the focused frame.

:last

Choose the last focused frame.

:empty

Choose any empty frame.

:unfocused

Choose any unfocused frame.

Alternatively, it can be set to a function that takes one argument, the new window, and returns the preferred frame or a list of the above preferences.

Variable: *hidden-window-color*

Color command for hidden windows when using the fmt-head-window-list-hidden-windows formatter. To disable coloring hidden windows, set this to an empty string.

5.1 Window Marks

Windows can be marked. A marked window has a # beside it in the window list. Some commands operate only on marked windows.

Command: mark

Toggle the current window’s mark.

Command: clear-window-marks &optional (group (current-group)) (windows (group-windows group))

Clear all marks in the current group.

Command: pull-marked

Pull all marked windows into the current frame and clear the marks.

5.2 Customizing Window Appearance

Variable: *maxsize-border-width*

The width in pixels given to the borders of windows with maxsize or ratio hints.

Variable: *transient-border-width*

The width in pixels given to the borders of transient or pop-up windows.

Variable: *normal-border-width*

The width in pixels given to the borders of regular windows.

Variable: *window-border-style*

This controls the appearance of the border around windows. valid values are:

:thick

All space within the frame not used by the window is dedicated to the border.

:thin

Only the border width as controlled by *maxsize-border-width* *normal-border-width* and *transient-border-width* is used as the border. The rest is filled with the unfocus color.

:tight

The same as :thin but the border surrounds the window and the wasted space within the frame is not obscured, revealing the background.

:none

Like :tight but no border is ever visible.

After changing this variable you may need to call sync-all-frame-windows to see the change.

See Colors for an explanation of how to set these color variables.

Function: set-win-bg-color color

Set the background color of the window. The background color will only be visible for windows with size increment hints such as ‘emacs’ and ‘xterm’.

Function: set-focus-color color

Set the border color for focused windows. This is only used when there is more than one frame.

Function: set-unfocus-color color

Set the border color for windows without focus. This is only used when there is more than one frame.

Function: set-float-focus-color color

Set the border color for focused windows in a float group.

Function: set-float-unfocus-color color

Set the border color for windows without focus in a float group.

Function: set-normal-gravity gravity

Set the default gravity for normal windows. Possible values are :center :top :left :right :bottom :top-left :top-right :bottom-left and :bottom-right.

Function: set-maxsize-gravity gravity

Set the default gravity for maxsize windows.

Function: set-transient-gravity gravity

Set the default gravity for transient/pop-up windows.

Command: gravity gravity

Set a window’s gravity within its frame. Gravity controls where the window will appear in a frame if it is smaller that the frame. Possible values are:

center

top

right

bottom

left

top-right

top-left

bottom-right

bottom-left

5.3 Controlling Raise And Map Requests

It is sometimes handy to deny a window’s request to be focused. The following variables determine such behavior.

A map request occurs when a new or withdrawn window requests to be mapped for the first time.

A raise request occurs when a client asks the window manager to give an existing window focus.

Variable: *deny-map-request*

A list of window properties that stumpwm should deny matching windows’ requests to become mapped for the first time.

Variable: *deny-raise-request*

Exactly the same as *deny-map-request* but for raise requests.

Note that no denial message is displayed if the window is already visible.

Variable: *suppress-deny-messages*

For complete focus on the task at hand, set this to T and no raise/map denial messages will be seen.

Some examples follow.

;; Deny the firefox window from taking focus when clicked upon.
(push '(:class "gecko") stumpwm:*deny-raise-request*)

;; Deny all map requests
(setf stumpwm:*deny-map-request* t)

;; Deny transient raise requests
(push '(:transient) stumpwm:*deny-map-request*)

;; Deny the all windows in the xterm class from taking focus.
(push '(:class "Xterm") stumpwm:*deny-raise-request*)

5.4 Programming With Windows

Macro: define-window-slot attr

Create a new window attribute and corresponding get/set functions.

Function: window-send-string string &optional (window (current-window))

Send the string of characters to the current window as if they’d been typed.

Variable: *default-window-name*

The name given to a window that does not supply its own name.

Variable: *window-events*

The events to listen for on managed windows.

Variable: *window-parent-events*

The events to listen for on managed windows’ parents.

5.5 Rule Based Window Placement

Macro: define-frame-preference target-group &body frame-rules

Create a rule that matches windows and automatically places them in a specified group and frame. Each frame rule is a lambda list:

(frame-number raise lock &key create restore dump-name class instance type role title)

frame-number

The frame number to send matching windows to

raise

When non-nil, raise and focus the window in its frame

lock

When this is nil, this rule will only match when target-group matches the group designated by from-group. When non-nil, this rule matches regardless of the group and the window is sent to target-group. If lock and raise are both non-nil, then stumpwm will jump to the specified group and focus the matched window.

from-group

When lock is NIL, and this is non-NIL, this rule will only match when target-group matches from-group. This should be set to either a group name(a string), or an expression that returns a group(e.g (current-group)). When this is NIL, the rule matches if target-group matches the group the window is in, or the current group if the window has no group.

create

When non-NIL the group is created and eventually restored when the value of create is a group dump filename in *DATA-DIR*. Defaults to NIL.

restore

When non-NIL the group is restored even if it already exists. This arg should be set to the dump filename to use for forced restore. Defaults to NIL

class

The window’s class must match class.

instance

The window’s instance/resource name must match instance.

type

The window’s type must match type.

role

The window’s role must match role.

title

The window’s title must match title.

Function: clear-window-placement-rules

Clear all window placement rules.

Command: remember lock title

Make a generic placement rule for the current window. Might be too specific/not specific enough!

Command: forget

Forget the window placement rule that matches the current window.

Command: dump-window-placement-rules file

Dump *window-placement-rules* to FILE.

Command: restore-window-placement-rules file

Restore *window-placement-rules* from FILE.

Variable: *window-placement-rules*

List of rules governing window placement. Use define-frame-preference to add rules

5.6 Window Selection Expressions

Window Selection Expressions (WSE) were inspired by SQL. The intent is to allow writing consise code to select the windows you need and to act upon them (or just to get the list of selected windows). The implementation includes a set of (hopefully) consistent concisely-named wrappers for the StumpWM functionality useful for window set description and the act-on-matching-windows macro that encapsulates the logic of iterating over a window set.

If we had SQL in StumpWM, we would write select window_id from windows as w where w.title = 'XTerm'. WSE chooses to be more Lisp-style and instead uses (act-on-matching-windows (w) (titled-p w "XTerm") w)

The act-on-matching-windows function also allows performing some actions, for example getting all the windows titled XTerm into the current group: (act-on-matching-windows (w) (titled-p w "XTerm") (pull-w w))

Function: move-windows-to-group windows &optional (arggroup nil)

Move all windows from the list to the group

Macro: act-on-matching-windows (var &optional (range)) condition &rest code

Run code on all windows matching condition; var is the shared lambda variable. Range can be any screen/group/frame or :screen/:group/:frame for the current instance. Condition is just the code to evaluate.

Function: pull-w w &optional g

Pull the window w: to the current group or to the specified group g.

Function: titled-p w title

Check whether window title of the window w is equal to the string title.

Function: title-re-p w tre

Check whether the window title of the window w matches the regular expression tre.

Function: classed-p w class

Check whether the window class of the window w is equal to the string class.

Function: class-re-p w cre

Check whether the window class of the window w matches the regular expression cre.

Function: typed-p w type

Check whether the window type of the window w is equal to the string type.

Function: type-re-p w tre

Check whether the window type of the window w matches the regular expression tre.

Function: roled-p w role

Check whether the window role of the window w is equal to the string role.

Function: role-re-p w rre

Check whether the window role of the window w matches the regular expression rre.

Function: resed-p w res

Check whether the window resource of the window w is equal to the string res.

Function: res-re-p w rre

Check whether the window resource of the window w matches the regular expression rre.

Function: grouped-p w &optional name

Check whether the window w belongs to the group name or the current group if name is not specified.

Function: in-frame-p w &optional f

Check whether the window w belongs to the frame f or to the current frame if the frame is not specified.

This document was generated by Raimon Grau on May 28, 2019 using texi2html 1.82.