History

Henrik Lissner dcec3b9b25 feature/popup: add new autosave window parameter (autosave . CDR) This parameter determines what to do with modified buffers in closing popup windows. CDR can be a t, 'ignore, a function or nil. + If t, no prompts. Just save them automatically (if they're file-visiting buffers). + If 'ignore, no prompts, no saving. Just silently kill it. + If nil (the default), prompt the user what to do if the buffer is file-visiting and modified. + If a function, the return value must return one of the other values. It takes two arguments: the popup window and buffer.		2018-05-19 12:08:24 +02:00
..
+hacks.el	Move feature/popup => ui/popup	2018-05-14 13:05:03 +02:00
autoload.el	feature/popup: add new autosave window parameter	2018-05-19 12:08:24 +02:00
config.el	feature/popup: add new autosave window parameter	2018-05-19 12:08:24 +02:00
init.el	Move feature/popup => ui/popup	2018-05-14 13:05:03 +02:00
README.org	Move feature/popup => ui/popup	2018-05-14 13:05:03 +02:00

README.org

:feature popup

Table of Contents
Configuration
- The :popup setting
- Disabling aggressive mode-line hiding in popups
Appendix
- Commands
- Library
- Hacks

This module provides a highly customizable popup window management system.

Not all windows are created equally. Some are less important. Some I want gone once they have served their purpose, like code output or a help buffer. Others I want to stick around, like a scratch buffer or org-capture popup.

More than that, popups ought to be be the second class citizens of my editor; spawned off to the side, discarded with the simple push of a button (Escape/C-g), and easily restored if I want to see them again. Of course, this system should clean up after itself and kill off buffers I mark as transient.

Table of Contents TOC

Configuration
- The :popup setting
- Disabling aggressive mode-line hiding in popups
Appendix
- Commands
- Library
- Hacks

Configuration

The `:popup` setting

This module has one setting for defining your own rules for popups:

(set! :popup CONDITION &optional ALIST PARAMETERS)

CONDITION can be a function or regexp string. If the function returns non-nil, or the regexp string matches the buffer's name, it will be opened in a popup window.
ALIST dictates the characteristics of the popup, such as what side to spawn it on and what size to make it. See display-buffer's documentation to see what parameters are supported. This supports one custom parameter: size, which will map to window-width or window-height depending on what side you (or the defaults) specify.
PARAMETERS dictate what window parameters are set on the popup window. See +popup-window-parameters's documentation and the Window Parameters section of the Emacs manual for what parameters are supported. This supports four custom parameters: transient, quit, select and modeline. For details on these, look at the documentation for +popup-window-parameters.

Rules are added to display-buffer-alist, which instructs display-buffer calls on how to set up windows for buffers that meet certain conditions.

The switch-to-buffer command (and its switch-to-buffer-* variants) are not affected by display-buffer-alist.

Here are a couple example rules:

(set! :popup "^ \\*" '((slot . -1))) ; fallback rule for special buffers
(set! :popup "^\\*" nil '((select . t)))
(set! :popup "^\\*Completions" '((slot . -1)) '((transient . 0)))
(set! :popup "^\\*\\(?:scratch\\|Messages\\)" nil '((transient)))
(set! :popup "^\\*Help"
  '((slot . -1) (size . 0.2))
  '((select . t)))
(set! :popup "^\\*doom:"
  '((size . 0.35))
  '((select . t) (modeline . t) (quit) (transient)))

Omitted parameters in a :popup rule will use the defaults set in +popup-default-alist and +popup-default-parameters.

Disabling aggressive mode-line hiding in popups

There are two ways to go about this. You can turn on modelines by changing the default 'modeline window parameter in +popup-default-parameters:

;; put in private/$USER/config.el
(map-put +popup-default-parameters 'modeline t)

This will ensure all popups have a modeline by default, but allows you to override this on a per-popup basis.

Alternatively, you can disable modeline-hiding entirely:

;; put in private/$USER/config.el
(remove-hook '+popup-buffer-mode-hook '+popup|set-modeline)

Appendix

Commands

+popup/other (aliased to other-popup, bound to C-x p)
+popup/toggle
+popup/close
+popup/close-all
+popup/toggle
+popup/restore
+popup/raise

Library

Functions
- +popup-window-p WINDOW
- +popup-buffer-p BUFFER
- +popup-buffer BUFFER &optional ALIST
- +popup-parameter PARAMETER &optional WINDOW
- +popup-parameter-fn PARAMETER &optional WINDOW
- +popup-windows
Macros
- without-popups!
- save-popups!
Hooks
- +popup|adjust-fringes
- +popup|set-modeline
- +popup|close-on-escape
- +popup|cleanup-rules
Minor modes
- +popup-mode
- +popup-buffer-mode

Hacks

help-mode has been advised to follow file links in the buffer you were in before entering the popup, rather than in a new window.
wgrep buffers are advised to close themselves when aborting or committing changes.
persp-mode is advised to restore popup windows when loading a session from file.
Interactive calls to windmove-* commands (used by evil-window-* commands) will ignore the no-other-window window parameter, allowing you to switch to popup windows as if they're ordinary windows.
balance-windows has been advised to close popups while it does its business, then restores them afterwards.
neotree advises balance-windows, which causes major slow-downs when paired with our balance-window advice, so we removes neotree's advice.
org-mode is an ongoing (and huge) effort. It has a scorched-earth window management system I'm not fond of. ie. it kills all windows and monopolizes the frame. On top of that, it really likes to use switch-to-buffer for most of its buffer management, which completely bypasses display-buffer-alist.