merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,21 +1,10 @@
|
|||
#+TITLE: ui/popup
|
||||
#+DATE: January 6, 2018
|
||||
#+SINCE: v2.0.9
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :ui popup
|
||||
#+subtitle: Tame sudden yet inevitable temporary windows
|
||||
#+created: January 06, 2018
|
||||
#+since: 21.12.0
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#set-popup-rule-and-set-popup-rules][~set-popup-rule!~ and ~set-popup-rules!~]]
|
||||
- [[#disabling-hidden-mode-line-in-popups][Disabling hidden mode-line in popups]]
|
||||
- [[#appendix][Appendix]]
|
||||
- [[#commands][Commands]]
|
||||
- [[#library][Library]]
|
||||
- [[#hacks][Hacks]]
|
||||
|
||||
* Description
|
||||
* 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
|
||||
|
|
@ -23,41 +12,84 @@ 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. =ESC= or
|
||||
=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.
|
||||
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.
|
||||
|
||||
** Module Flags
|
||||
+ =+all= Enables fallback rules to ensure all temporary/special buffers (whose
|
||||
name begins with a space or asterix) are treated as popups.
|
||||
+ =+defaults= Enables reasonable default popup rules for a variety of buffers.
|
||||
** Maintainers
|
||||
- [[doom-user:][@hlissner]]
|
||||
|
||||
* Prerequisites
|
||||
This module has no external prerequisites.
|
||||
[[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
|
||||
|
||||
* Configuration
|
||||
** ~set-popup-rule!~ and ~set-popup-rules!~
|
||||
This module has two functions for defining your own rules for popups:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
#+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
|
||||
#+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 (=SPC h f set-popup-rule!=).
|
||||
~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~.
|
||||
📌 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
|
||||
#+begin_src emacs-lisp
|
||||
(set-popup-rules!
|
||||
'(("^ \\*" :slot -1) ; fallback rule for special buffers
|
||||
("^\\*" :select t)
|
||||
|
|
@ -66,7 +98,7 @@ Multiple popup rules can be defined with ~set-popup-rules!~:
|
|||
("^\\*Help" :slot -1 :size 0.2 :select t)
|
||||
("^\\*doom:"
|
||||
:size 0.35 :select t :modeline t :quit t :ttl t)))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
Omitted parameters in a ~set-popup-rules!~ will use the defaults set in
|
||||
~+popup-defaults~.
|
||||
|
|
@ -75,66 +107,55 @@ Omitted parameters in a ~set-popup-rules!~ will use the defaults set in
|
|||
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
|
||||
;; add to $DOOMDIR/config.el
|
||||
#+begin_src emacs-lisp
|
||||
;; in $DOOMDIR/config.el
|
||||
(plist-put +popup-defaults :modeline t)
|
||||
#+END_SRC
|
||||
#+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.
|
||||
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
|
||||
;; add to ~/.doom.d/config.el
|
||||
#+begin_src emacs-lisp
|
||||
;; in $DOOMDIR/config.el
|
||||
(remove-hook '+popup-buffer-mode-hook #'+popup-set-modeline-on-enable-h)
|
||||
#+END_SRC
|
||||
#+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
|
||||
|
||||
* 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~
|
||||
- ~+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~
|
||||
** 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 restore 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~. Some work has gone into reversing this.
|
||||
- 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~
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue