gitback/doomemacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

ui/popup: update README

Browse Source
This commit is contained in:
Henrik Lissner 2019-03-20 00:55:27 -04:00
parent cf4818e689
commit 47d09b3ef5
No known key found for this signature in database
GPG Key ID: 5F6C0EA160557395
1 changed files with 48 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
modules/ui/popup/README.org
View File

@ -1,50 +1,59 @@
#+TITLE: :feature popup
#+TITLE: :ui popup
This module provides a highly customizable popup window management system.
* 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-aggressive-mode-line-hiding-in-popups][Disabling aggressive mode-line hiding in popups]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
- [[#library][Library]]
- [[#hacks][Hacks]]
* Description
This module provides a customizable popup window management system.
#+begin_quote
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.
#+end_quote
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.
* Table of Contents :TOC:
- [[Configuration][Configuration]]
- [[~set-popup-rules!~][~set-popup-rules!~]]
- [[Disabling aggressive mode-line hiding in popups][Disabling aggressive mode-line hiding in popups]]
- [[Appendix][Appendix]]
- [[Commands][Commands]]
- [[Library][Library]]
- [[Hacks][Hacks]]
** 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.
* Prerequisites
This module has no external prerequisites.
* Configuration
** ~set-popup-rules!~
This module has one setting for defining your own rules for popups:
** ~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
+ ~RULESETS~ consist of a function or regexp string that matches the buffer's
name, and a list of settings. See ~display-buffer~'s,
~display-window-parameters~'s, and ~+popup-window-parameters~'s documentation
for what parameters are supported.
~PREDICATE~ is a predicate function or regexp string to match against the
buffer's name. To see what the other keywords do, check out the documentation
for ~set-popup-rule!~ (=SPC h f set-popup-rule!=).
#+begin_quote
Rules are added to ~display-buffer-alist~, which instructs ~display-buffer~
calls on how to set up windows for buffers that meet certain conditions.
#+begin_quote
The ~switch-to-buffer~ command (and its ~switch-to-buffer-*~ variants) are not
affected by ~display-buffer-alist~.
#+end_quote
Here are a couple example rules:
e.g.
#+BEGIN_SRC emacs-lisp
(set-popup-rules!
'(("^ \\*" :slot -1) ; fallback rule for special buffers
@ -57,25 +66,27 @@ Here are a couple example rules:
#+END_SRC
Omitted parameters in a ~set-popup-rules!~ will use the defaults set in
~+popup-default-alist~ and ~+popup-default-parameters~.
~+popup-defaults~.
** 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~:
There are two ways to go about this.
#+BEGIN_SRC emacs-lisp
;; put in private/$USER/config.el
(map-put +popup-default-parameters 'modeline t)
#+END_SRC
1. Turn on modelines by changing the ~:modeline~ property in ~+popup-defaults~:
This will ensure all popups have a modeline /by default/, but allows you to override this on a per-popup basis.
#+BEGIN_SRC emacs-lisp
;; put in private/$USER/config.el
(map-put +popup-defaults :modeline t)
#+END_SRC
*Alternatively*, you can disable modeline-hiding entirely:
This will ensure all popups have a modeline /by default/, but allows you to
override this on a per-popup basis.
#+BEGIN_SRC emacs-lisp
;; put in private/$USER/config.el
(remove-hook '+popup-buffer-mode-hook '+popup|set-modeline)
#+END_SRC
2. Disable modeline-hiding entirely:
#+BEGIN_SRC emacs-lisp
;; in ~/.doom.d/config.el
(remove-hook '+popup-buffer-mode-hook #'+popup|set-modeline-on-enable)
#+END_SRC
* Appendix
** Commands