doomemacs/modules/ui/popup/README.org

#+title:    :ui popup
#+subtitle: Tame sudden yet inevitable temporary windows
#+created:  January 06, 2018
#+since:    21.12.0

* Description :unfold:
This module provides a 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 the second class citizens of my editor;
spawned off to the side, discarded with the push of a button (e.g. [[kbd:][ESC]] or [[kbd:][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.

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +all ::
  Enable fallback rules to ensure all temporary/special buffers (whose name
  begins with a space or asterix) are treated as popups.
- +defaults ::
  Enable reasonable default popup rules for a variety of buffers.

** Packages
/This module doesn't install any packages./

** Hacks
- [[doom-package: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.
- [[doom-package:wgrep]] buffers are advised to close themselves when aborting or committing
  changes.
- [[doom-package: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 restore them afterwards.
- [[doom-package:neotree]] advises ~balance-windows~, which causes major slow-downs when paired
  with our ~balance-window~ advice, so we removes neotree's advice.
- [[doom-package: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~. Some work has gone into reversing this.

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* TODO Usage
#+begin_quote
 󱌣 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** ~set-popup-rule!~ and ~set-popup-rules!~
This module has two functions for defining your own rules for popups:
#+begin_src emacs-lisp
(set-popup-rule! PREDICATE &key IGNORE ACTIONS SIDE SIZE WIDTH HEIGHT SLOT VSLOT TTL QUIT SELECT MODELINE AUTOSAVE PARAMETERS)
(set-popup-rules! &rest RULESETS)
#+end_src

~PREDICATE~ is a predicate function or regexp string to match against the
buffer's name. You'll find comprehensive documentation on the other keywords in
~set-popup-rule!~'s docstring ([[kbd:][SPC h f set-popup-rule!]]).

#+begin_quote
 󰐃 Popup rules end up in ~display-buffer-alist~, which instructs
    ~display-buffer~ calls on how to set up windows for buffers that meet
    certain conditions. However, some plugins can avoid it entirely if they use
    ~set-buffer~ or ~switch-to-buffer~, which don't obey ~display-buffer-alist~.
#+end_quote

Multiple popup rules can be defined with ~set-popup-rules!~:
#+begin_src emacs-lisp
(set-popup-rules!
 '(("^ \\*" :slot -1) ; fallback rule for special buffers
   ("^\\*" :select t)
   ("^\\*Completions" :slot -1 :ttl 0)
   ("^\\*\\(?:scratch\\|Messages\\)" :ttl t)
   ("^\\*Help" :slot -1 :size 0.2 :select t)
   ("^\\*doom:"
    :size 0.35 :select t :modeline t :quit t :ttl t)))
#+end_src

Omitted parameters in a ~set-popup-rules!~ will use the defaults set in
~+popup-defaults~.

** Disabling hidden mode-line in popups
By default, the mode-line is hidden in popups. To disable this, you can either:

1. Change the default ~:modeline~ property in ~+popup-defaults~:
   #+begin_src emacs-lisp
   ;; in $DOOMDIR/config.el
   (plist-put +popup-defaults :modeline t)
   #+end_src

   A value of ~t~ will instruct popups to use the default mode-line. Any popup
   rule with a ~:modeline~ property can still override this.

2. Completely disable management of the mode-line in popups:
   #+begin_src emacs-lisp
   ;; in $DOOMDIR/config.el
   (remove-hook '+popup-buffer-mode-hook #'+popup-set-modeline-on-enable-h)
   #+end_src

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote

** Commands
- ~+popup/other~ (aliased to ~other-popup~, bound to [[kbd:][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-h~
  - ~+popup|set-modeline~
  - ~+popup-close-on-escape-h~
  - ~+popup-cleanup-rules-h~
- Minor modes
  - ~+popup-mode~
  - ~+popup-buffer-mode~