Window Commander User Manual

Next:   [Contents][Index]

Window Commander User Manual

Window Commander provides a minor mode for switching to windows or performing actions on them using IDs assigned to them automatically.

This manual is for Window Commander version 3.0.2.

Copyright © 2023-2024 Free Software Foundation, Inc.

You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Table of Contents


1 Introduction

Window Commander provides a minor mode for switching to windows or performing actions on them using IDs assigned to them automatically. The implementation is simple and extensible, providing various advanced customization features for users, while keeping the code base small and easy to hack on.


2 Installation

Window Commander can be installed from GNU ELPA:

M-x package-install RET window-commander RET

3 Usage

In order to use any feature of the package, wincom-mode must be enabled:

M-x wincom-mode RET

You can also add (wincom-mode) to your initialization file, or enable it through the customize interface.

When wincom-mode is enabled, window IDs are shown as mode line lighters of the form <ID> (by default, See ID display), and other-window (C-x o) is remapped to wincom-select (it is also available, alongside all other window commands, through the “Windows” menu added by the minor mode).

wincom-select, and any other window command, starts window selection. When there are less than wincom-minimum (3 by default) tracked windows in the current wincom-scope (all frames by default), the “next” window is selected. Otherwise, any window in scope can be selected by pressing the sequence of keys corresponding to its displayed ID. Alternatively, any binding in wincom-command-map can be used (unless it is overwritten by a window ID).

The following window commands are available in wincom-command-map by default:

C-x o ID, C-x o o ID

Select the window corresponding to ID in the current scope (wincom-select).

C-x o 0 ID

Delete the window corresponding to ID in the current scope (wincom-delete).

C-x o 1 ID

Make the window corresponding to ID in the current scope the sole window of its frame (wincom-delete-other).

C-x o 2 ID

Split the window corresponding to ID in the current scope from below (wincom-split-window-below). This window command accepts a prefix argument (with the same semantics as split-window-below).

C-x o 3 ID

Split the window corresponding to ID in the current scope from the right (wincom-split-window-right). This window command accepts a prefix argument (with the same semantics as split-window-right).

C-x o 4 ID

Display the buffer of the next command in the window corresponding to ID in the current scope (wincom-selected-window-prefix). This window command is only available when display-buffer-override-next-command is available (Emacs 28+).

C-x o t ID

Swap the states of the current window and the window corresponding to ID in the current scope (wincom-swap).

See Window commands for information regarding defining new commands.

The following commands are available in wincom-command-map by default, but are not window commands:

C-x o m

Switch to the minibuffer if it’s active (wincom-select-minibuffer).

C-x o r

Select the most recently used window. (wincom-select-most-recently-used).


4 Customization

All customization, except for defining custom display functions and custom window commands, can be done through the customize interface:

M-x customize-group RET window-commander RET
User Option: wincom-id-chars

Base set of character from which window IDs are constructed. This should be a list of characters. By default, the home row (a s d f g h j k l) is used.

User Option: wincom-scope

Scope of all window operations. Used to determine on which frames to track windows. A value of t means consider all windows on all frames, 0 (the number zero) means consider all windows on all visible and iconified frames, visible means consider all windows on all visible frames and current means consider only the currently selected frame. By default, t is used.


4.1 ID display

By default, the ID of each tracked window is displayed as a mode line lighter. This behavior is controlled by wincom-display-lighter.

Additionally, (custom) display functions could be added to wincom-mode-hook. These functions should enable ID display when wincom-mode is enabled, and disable ID display when wincom-mode is disabled. They can also make use of wincom-before-command-hook and wincom-after-command-hook (See Window commands) to display IDs only during window selection. See the description and implementation of wincom-display-mode-line and wincom-display-mode-line-conditional below for more information.

It is also possible to use wincom-format-id directly in e.g. mode-line-format, although details vary depending on how and where you want the IDs to be displayed.

User Option: wincom-display-lighter

Whether or not to show a mode line lighter. A non-nil value means show a mode line lighter. A value of nil means don’t show a mode line lighter. By default, t is used.

User Option: wincom-mode-hook

Hook run when enabling or disabling wincom-mode.

User Option: wincom-id-format

Format string for the window ID. Used in the mode line lighter, and display functions may use this format string to display the ID, but they can also ignore it. The string should contain a single occurrence of %s, which will be replaced by the ID. By default, " <%s>" is used.

Function: wincom-format-id window

Format an ID string (according to wincom-id-format) for WINDOW.

Function: wincom-display-mode-line

Reference implementation of a “simple” display function, displaying window IDs at the beginning of the mode line. Display window IDs if wincom-mode is enabled, and disable displaying window IDs if wincom-mode is disabled. This display function respects wincom-id-format.

Function: wincom-display-mode-line-conditional

Reference implementation of a conditional display function, displaying window IDs at the beginning of the mode line during window selection. Add a hook to wincom-before-command-hook which displays window IDs on the mode line and add a hook to wincom-after-command-hook which hides window IDs from the mode line if wincom-mode is enabled, and remove those hooks if wincom-mode is disabled. This display function respects wincom-id-format.


Previous: , Up: Customization   [Contents][Index]

4.2 Window commands

Window commands are used to perform operations on specific windows, chosen by their ID (or the next window, if less than wincom-minimum (3 by default) windows are currently in scope). Alternatively, other commands available in wincom-command-map can be chosen. Not all commands in wincom-command-map are window commands (by default). For more information about included window commands, See Usage.

Window commands can easily be defined using wincom-define-window-command. For more complex use cases, the lower level wincom-run-window-command can be used.

User Option: wincom-minimum

Minimum number of tracked windows for which interactive selection occurs when using window commands. In practice, only window commands defined using wincom-define-window-command automatically adhere to this rule.

Variable: wincom--id-map

Key map which is populated automatically with elements corresponding to all tracked windows. The ID of each window is converted to a vector (to serve as a key sequence), and is bound to a command which calls last-command with the window corresponding to the ID as the sole argument. There should be no reason to modify it directly; it is reset whenever window configuration is updated.

Variable: wincom-command-map

Key map which holds bindings to window commands. This key map is set as the parent of wincom--id-map, so all window commands are available when it’s active (unless they are shadowed by a window ID).

Variable: wincom-window-count

Amount of windows currently tracked, including the minibuffer (if it’s active). It can be used to change the behavior of window commands (or display functions, See ID display).

Macro: wincom-define-window-command name (window [prefix]) [docstring] [keyword arg...] body...

Define NAME as a window command with DOCSTRING as its documentation string. Inside body, window and prefix (symbols) are bound to the selected window and the raw prefix argument, respectively. If prefix is omitted or nil, the resulting command will not accept a prefix argument. Currently, only a single KEYWORD ARG is recognized, :minibuffer: When it’s non-nil, allow the minibuffer to be selected by next-window (when there are less than wincom-minimum tracked windows).

Function: wincom-run-window-command fun

Run FUN as a window command. Run wincom-before-command-hook, set this-command to FUN, and set wincom--id-map as a transient map which runs wincom-after-command-hook on exit. The hooks run by this function are expected by Window Commander to run for any window command which requires ID selection; they should be run even if this function isn’t used when defining a new window command.


Appendix A Keystroke Index

Jump to:   C  
Index Entry  Section

C
C-x o: Usage
C-x o 0: Usage
C-x o 1: Usage
C-x o 2: Usage
C-x o 3: Usage
C-x o 4: Usage
C-x o m: Usage
C-x o o: Usage
C-x o r: Usage
C-x o t: Usage

Jump to:   C  

Appendix B Command Index

Jump to:   W  
Index Entry  Section

W
wincom-delete: Usage
wincom-delete-other: Usage
wincom-mode: Usage
wincom-select: Usage
wincom-select-minibuffer: Usage
wincom-select-most-recently-used: Usage
wincom-selected-window-prefix: Usage
wincom-split-window-below: Usage
wincom-split-window-right: Usage
wincom-swap: Usage

Jump to:   W  

Appendix C Function Index

Jump to:   W  
Index Entry  Section

W
wincom-define-window-command: Window commands
wincom-display-mode-line: ID display
wincom-display-mode-line-conditional: ID display
wincom-format-id: ID display
wincom-run-window-command: Window commands

Jump to:   W  

Appendix D Variable Index

Jump to:   W  
Index Entry  Section

W
wincom--id-map: Window commands
wincom-command-map: Window commands
wincom-display-lighter: ID display
wincom-id-chars: Customization
wincom-id-format: ID display
wincom-minimum: Window commands
wincom-mode-hook: ID display
wincom-scope: Customization
wincom-window-count: Window commands

Jump to:   W