Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/emacsorphanage/popwin
Popup Window Manager for Emacs
https://github.com/emacsorphanage/popwin
Last synced: 3 months ago
JSON representation
Popup Window Manager for Emacs
- Host: GitHub
- URL: https://github.com/emacsorphanage/popwin
- Owner: emacsorphanage
- Created: 2011-01-18T11:14:36.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2024-05-08T06:44:03.000Z (6 months ago)
- Last Synced: 2024-06-19T02:10:41.467Z (5 months ago)
- Language: Emacs Lisp
- Homepage:
- Size: 270 KB
- Stars: 496
- Watchers: 28
- Forks: 42
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://melpa.org/#/popwin)
[](https://stable.melpa.org/#/popwin)
# popwin.el
[](https://github.com/emacsorphanage/popwin/actions/workflows/test.yml)
popwin is a popup window manager for Emacs which makes you free from
the hell of annoying buffers such like `*Help*`, `*Completions*`,
`*compilation*`, and etc.
Take an example. When you complete file names during `find-file`, the
(annoying) `*Completions*` buffer will appear in a newly splitted
window. You might understand the necessity of the window, but you may
wonder why the window still remains after completion...
popwin resolves there problems. Windows of such temporary buffers will
be shown as a popup window, and you can close them smoothly by typing
`C-g` in anytime.
## Screenshots
| Before Popup Window | After Popup Window |
|:---------------------------------------------:|:--------------------------------------------------------:|
|||
## Installation
### Melpa
This package is on [MELPA](https://github.com/melpa/melpa), you can install it from
there! (recommended)
### Manually
Install `popwin.el` into your `load-path` directory. If you have
`install-elisp` or `auto-install`, you may install `popwin.el` like:
;; install-elisp
(install-elisp "https://raw.github.com/m2ym/popwin-el/master/popwin.el")
;; auto-install
(auto-install-from-url "https://raw.github.com/m2ym/popwin-el/master/popwin.el")
And then add the following code into your `.emacs`:
(require 'popwin)
(popwin-mode 1)
popwin is tested under GNU Emacs 22 or later.
## Basic Usage
Special buffers, for example `*Help*`, specified in
`popwin:special-display-config` will be shown in a popup window. You
can close the popup window by typing `C-g` or selecting other windows.
By default, `*Help*`, `*Completions*`, `*compilation*`, and `*Occur*`
buffers will be shown in a popup window. Try `M-x find-file` and type
`TAB TAB`. You may see a popup window at the bottom of the frame.
**File Name Completion**
Let me show other examples.
**`M-x occur`**
**`M-x compile`**
## Customization
Please do `M-x customize-group RET popwin RET` and `M-x
customize-variable RET popwin:special-display-config RET`. See the
header of `popwin.el`, source code, and docstrings for more
information.
### Default Keymap
popwin provides a default keymap named `popwin:keymap`. You can use it
like:
(global-set-key (kbd "C-z") popwin:keymap)
Keymap:
| Key | Command |
|--------+---------------------------------------|
| b | popwin:popup-buffer |
| l | popwin:popup-last-buffer |
| o | popwin:display-buffer |
| C-b | popwin:switch-to-last-buffer |
| C-p | popwin:original-pop-to-last-buffer |
| C-o | popwin:original-display-last-buffer |
| SPC | popwin:select-popup-window |
| s | popwin:stick-popup-window |
| 0 | popwin:close-popup-window |
| f, C-f | popwin:find-file |
| e | popwin:messages |
| C-u | popwin:universal-display |
| 1 | popwin:one-window |
## Special Display Config
`popwin:special-display-config` is a list of `CONFIG`. `CONFIG` may be
a form of `(PATTERN . KEYWORDS)`, where `PATTERN` is a pattern of
specifying a buffer, and `KEYWORDS` is a list of a pair of key and
value. `PATTERN` is a buffer name, a symbol specifying major-mode, or
a predicate function which takes the buffer. If `CONFIG` is a string
or a symbol, `PATTERN` will be `CONFIG` and `KEYWORDS` will be
empty. Available keywords are following:
`:regexp`
: If the value is non-nil, `PATTERN` will be used as regexp to matching buffer.
`:width`, `:height`
: Specify width or height of the popup window. If no size specified,
`popwin:popup-window-width` or `popwin:popup-window-height` will be
used. See also position keyword.
`:position`
: The value must be one of `(left top right bottom)`. The popup window
will shown at the position of the frame. If no position specified,
`popwin:popup-window-position` will be used.
`:noselect`
: If the value is non-nil, the popup window will not be selected when
it is shown.
`:dedicated`
: If the value is non-nil, the popup window will be dedicated to the
original popup buffer. In this case, when another buffer is selected
in the popup window, the popup window will be closed immedicately
and the selected buffer will be shown on the previously selected
window.
`:stick`
: If the value is non-nil, the popup window will be stuck when it is
shown.
`:tail`
: If the value is non-nil, the popup window will show the last
contents.
### Examples
;; M-x anything
(setq anything-samewindow nil)
(push '("*anything*" :height 20) popwin:special-display-config)
;; M-x dired-jump-other-window
(push '(dired-mode :position top) popwin:special-display-config)
;; M-!
(push "*Shell Command Output*" popwin:special-display-config)
;; M-x compile
(push '(compilation-mode :noselect t) popwin:special-display-config)
;; slime
(push "*slime-apropos*" popwin:special-display-config)
(push "*slime-macroexpansion*" popwin:special-display-config)
(push "*slime-description*" popwin:special-display-config)
(push '("*slime-compilation*" :noselect t) popwin:special-display-config)
(push "*slime-xref*" popwin:special-display-config)
(push '(sldb-mode :stick t) popwin:special-display-config)
(push 'slime-repl-mode popwin:special-display-config)
(push 'slime-connection-list-mode popwin:special-display-config)
;; vc
(push "*vc-diff*" popwin:special-display-config)
(push "*vc-change-log*" popwin:special-display-config)
;; undo-tree
(push '(" *undo-tree*" :width 0.3 :position right) popwin:special-display-config)
## Universal Display Config
`popwin:universal-display-config` is a special alternative value of
`popwin:special-display-config`, which will be used when executing a
command with `M-x popwin:universal-display` prefix. If you want to
show a specific buffer in a popup window at the time, for example, you
can do it with `M-x popwin:universal-display RET C-x 4 C-o BUFNAME
RET`.
The default value is `(t)`, meaning all of buffers with `M-x
popwin:universal-display` prefix will be shown in a popup window.
## Working with Other Extensions
Some extensions needs workaround for working with popwin.
#### YaTeX
`misc/popwin-yatex.el` helps you to show YaTeX related buffers in a
popup window. Add the following code into `.emacs`.
(require 'popwin-yatex)
You may write a configuration like:
(push '("*YaTeX-typesetting*") popwin:special-display-config)
#### w3m
`misc/popwin-w3m.el` helps you to show specific pages with w3m in a
popup window. Add the following code into `.emacs`.
(require 'popwin-w3m)
It is recommended to change `browse-url-browser-function` to
`popwin:w3m-browse-url`.
(setq browse-url-browser-function 'popwin:w3m-browse-url)
`popwin:w3m-browse-url` is a function (and a command) displaying w3m
buffers in a popup window if the given URL is matched with the rules.
The rules are described by `popwin:w3m-special-display-config`
variable, which has almost same structure of
`popwin:special-display-config`.
The difference is `popwin:w3m-special-display-config` takes an URL
regular expression instead of a buffer pattern.
For example, if you want to show google search pages in a popup
window, a configuration could be:
(push '("^http://www\\.google\\.com/.*$") popwin:w3m-special-display-config)
#### `term.el`
`misc/popwin-term.el` helps you to show term buffers in a popup
window. Add the following code into `.emacs`.
(require 'popwin-term)
Then write a configuration like:
(push '(term-mode :position :top :height 16 :stick t) popwin:special-display-config)
Now, you can show a term buffer in a popup window with `M-x
popwin-term:term`.
#### `browse-kill-ring.el`
`misc/browse-kill-ring.el` helps you to show `*Kill Ring*` buffer in a
popup window. Add the following code into `.emacs`.
(require 'popwin-browse-kill-ring)
Then write a configuration like:
(push "*Kill Ring*" popwin:special-display-config)
`M-x browse-kill-ring` now shows `*Kill Ring*` buffer in a popup
window.
#### `windows.el`
Do not load `windows.el` after loading `popwin.el`. Load `windows.el`
first.
## Basic Commands
### Command: `popwin:popup-buffer`
Focely show the specified buffer in a popup
window. `popwin:special-display-config` will be ignored.
### Command: `popwin:display-buffer`
Show the specified buffer in a popup window if possible, meaning there
is at least one matched configuration in
`popwin:special-display-config`. Otherwise, fallback to
`display-buffer`.
### Command: `popwin:display-last-buffer`
Show the lastly shown buffer in a popup window.
### Command: `popwin:pop-to-buffer`
Same as `popwin:display-buffer`, but behaves like `pop-to-buffer`.
### Command: `popwin:one-window`
Same like `C-x 1` except that `C-g` restore the original window
configuration. This is useful when you see the contents of the popup
window in full window temporarily.
### Command: `popup:find-file`
`find-file` in a popup window.
### Command: `popwin:messages`
Show `*Messages*` buffer in a popup window.
## Basic API
### Function: `popwin:create-popup-window`
popwin:create-popup-window &optional size position adjust => (master-window popup-window)
`popwin:create-popup-window` creates a popup window and return it with
a master window. Master window is a window which is splitted when
creating the popup window. A resposibility of closing the popup window
is on developers.
----
Copyright (C) 2011-2015 Tomohiro Matsuyama <>