spacemacs/contrib/!window-management/perspectives/README.org

#+TITLE: Perspectives contribution layer for Spacemacs

* Table of Contents                                                   :TOC@4:
 - [[#description][Description]]
 - [[#install][Install]]
     - [[#layer][Layer]]
     - [[#custom-perspective-macro][Custom Perspective Macro]]
 - [[#predefined-custom-perspectives][Predefined custom perspectives]]
         - [[#per-project-custom-perpsective][Per project custom perpsective]]
         - [[#org-agenda-custom-perspective][Org-agenda custom perspective]]
         - [[#rcirc-custom-perspective][RCIRC custom perspective]]
 - [[#key-bindings][Key Bindings]]
     - [[#custom-perspectives-key-bindings][Custom Perspectives Key Bindings]]

* Description

This contrib layer sets up perspective-mode. And also defines custom
perspectives with a macro so that you don't have to do more steps.

* Install

** Layer

To use this contribution add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(perspectives))
#+END_SRC

** Custom Perspective Macro

If you want to add a new custom-persp (for example if you want to have
IRC on its own perspective or maybe calendar or gnus) you have to use
the macro =custom-persp= as follows:

#+BEGIN_SRC emacs-lisp
  (defun custom-persp/<persp-function-name> ()
  (interactive)
  (custom-persp "<name-to-be-shown-in-the-modeline>"
      (... stuff to be done in the persp activating a major mode like twittering or whatever ...)))
#+END_SRC

You can check out the layer's packages.el to see some examples of the
custom-perspectives. if you define something like this you may be able
to define a perspective with a layout.

#+BEGIN_SRC emacs-lisp
  (defun custom-persp/c++-project ()
  (interactive)
  (custom-persp "c++"
      (progn
          (find-file "~/path/to/first/file.cpp")
          (split-window-right)
          (find-file "~/path/to/second/file.cpp")
          (... do more stuff but be careful not to destroy the universe ...)
      )))
#+END_SRC

Then you just need to add a keybinding to your custom persp, we use
~SPC L o [your key here]~ (Perspective open <key>)

#+BEGIN_SRC emacs-lisp
  (evil-leader/set-key "Lo<your key here>" 'custom-persp/<persp-function-name>)
#+END_SRC

* Predefined custom perspectives

*** Per project custom perpsective

As the name suggests, this persp-projectile mode creates a new perspective
once you switch to a new project with ~SPC p s~. It must be said that in the
current implementation in order for this to work you must first open a
custom-perspective like ~SPC L o e~ to go to the init.el in the spacemacs.

#+BEGIN_SRC emacs-lisp 
  (setq-default dotspacemacs-configuration-layers '(
    (perspectives :variables
                  perspective-enable-persp-projectile t)))
#+END_SRC

*** Org-agenda custom perspective

Here we define a custom perspective that adds items to your org-agenda. If you
do not know what that is check the [[https://www.gnu.org/software/emacs/manual/html_node/org/Agenda-commands.html][docs]].

The cool part is that you can have many org files with todos in the agenda and
with one simple command you can gather all the todos from all the agenda files
you have and show them in a single buffer. (in evil the command starts with ~;a~)

*** RCIRC custom perspective

Now you can also open rcirc in a new layer to keep all the chat buffers in one
perspective isolated from your work buffers.

You will have to use the perspective layer as well as the rcirc layer:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(rcirc
                                                    perspectives))
#+END_SRC

* Key Bindings

Prefix command for perspective commands is ~SPC L~ (for Layout).

| Key Binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC L A~   | Add current buffer to the current perspective      |
| ~SPC L c~   | Close a perspective (kill it)                      |
| ~SPC L k~   | Remove current buffer from the current perspective |
| ~SPC L n~   | Next perspective                                   |
| ~SPC L p~   | Previous perspective                               |
| ~SPC L r~   | Rename current perspective                         |
| ~SPC L s~   | Switch to a perspective                            |

** Custom Perspectives Key Bindings

| Key Binding | Description                                              |
|-------------+----------------------------------------------------------|
| ~SPC L o e~ | Emacs custom perspective                                 |
| ~SPC L o i~ | RCIRC custom perspective (needs the rcirc layer enabled) |
| ~SPC L o o~ | Org custom perspective                                   |