swsw User Manual

Table of Contents

swsw User Manual

swsw provides a minor mode for switching to windows using IDs assigned to them automatically.

This manual is for swsw version 2.3.

Copyright © 2020-2022 Daniel Semyonov

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.

— The Detailed Node Listing —

Installation

Customization

1 Introduction

swsw provides a minor mode for switching to windows using IDs assigned to them automatically. It’s 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

swsw can be installed from NonGNU ELPA:

M-x package-install RET swsw RET

2.1 Installing a release

Simply download a release (from <https://dsemy.com/projects/swsw>), and install it:

M-x package-install-file RET /path/to/download/swsw-VERSION.tar RET

2.2 Installing from the Git repository

Clone the repository and build the package archive:

$ git clone https://git.sr.ht/~dsemy/swsw
$ cd swsw
$ make

Install the package:

M-x package-install-file RET /path/to/clone/swsw-VERSION.tar RET

3 Usage

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

M-x swsw-mode RET

You can also add (swsw-mode) to your init file, instead.

When swsw-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 swsw-select.

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

Select the window corresponding to ID in the current scope (See Customization) (swsw-select).

C-x o 0 ID

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

C-x o 1 ID

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

C-x o 2 ID

Split the window corresponding to ID in the current scope from below (swsw-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 (swsw-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 (swsw-delete).

C-x o t ID

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

C-x o m

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

See Window commands for information regarding defining new commands.

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 swsw RET

User Option: swsw-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: swsw-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 swsw-display-lighter.

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

It is also possible to use swsw-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: swsw-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: swsw-mode-hook

Hook run when enabling or disabling swsw-mode.

User Option: swsw-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: swsw-format-id window

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

Function: swsw-mode-line-display-function

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

Function: swsw-mode-line-conditional-display-function

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

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 swsw-minimum (3 by default) windows are currently in scope). Alternatively, other commands available in swsw-command-map can be chosen. Not all commands in swsw-command-map are window commands (by default). For more information about included window commands, See Usage.

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

User Option: swsw-minimum

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

Variable: swsw--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: swsw-command-map

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

Variable: swsw-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: swsw-define-window-command name (window [prefix] [minibuffer]) docstring body...

Define NAME as a window command with DOCSTRING as its documentation string. PREFIX (a symbol) is passed as an argument to the command (when not omitted or nil), with it’s value being the raw prefix argument.

BODY is used as the body of an anonymous function which receives WINDOW (a symbol) as an argument, with its value being a selected window. If there are less than swsw-minimum (3 by default) windows in the current scope (See Customization), the function is called with the window returned by next-window. In this case, if MINIBUFFER is non-nil, it can be selected if it’s active. Otherwise, the function is run using swsw-run-window-command.

Function: swsw-run-window-command fun

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

Appendix A Keystroke Index

Appendix B Command Index

Appendix C Function Index

Appendix D Variable Index