spacemacs/layers/+window-management/spacemacs-layouts/README.org

#+TITLE: Spacemacs Layouts layer
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../../../css/readtheorg.css" />

* Table of Contents                                         :TOC_4_org:noexport:
 - [[Description][Description]]
 - [[Install][Install]]
   - [[Layer][Layer]]
 - [[Features][Features]]
   - [[Transient-states][Transient-states]]
     - [[Layouts Transient State][Layouts Transient State]]
     - [[Project Layouts][Project Layouts]]
     - [[Custom Layouts Transient State][Custom Layouts Transient State]]
 - [[Usage][Usage]]
   - [[Save/Load layouts into a file][Save/Load layouts into a file]]
   - [[Custom Layout Macro][Custom Layout Macro]]
   - [[Predefined custom layouts][Predefined custom layouts]]
     - [[Org-agenda custom layout][Org-agenda custom layout]]
     - [[RCIRC/ERC custom layout][RCIRC/ERC custom layout]]

* Description
This contribution layer adds layouts support to Spacemacs thanks to =persp-mode=.
Layouts are window configurations that have buffer isolation between each other.

* Install
** Layer
This layer is automatically included if you use the =spacemacs= distribution.

If you use =spacemacs-base= distribution then to use this configuration layer,
add it to your =~/.spacemacs=. You will need to add =spacemacs-layout= to the
existing =dotspacemacs-configuration-layers= list in this file.

* Features

** Transient-states
*** Layouts Transient State
The layouts transient-state is initiated with ~SPC l~.

| Key Binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~?~         | toggle the documentation                                   |
| ~[1..9, 0]~ | switch to nth layout                                       |
| ~<tab>~     | switch to the latest layout                                |
| ~a~         | add a buffer to the current layout                         |
| ~A~         | add all the buffers from another layout in the current one |
| ~b~         | select a buffer in the current layout                      |
| ~d~         | delete the current layout and keep its buffers             |
| ~D~         | delete the other layouts and keep their buffers            |
| ~h~         | go to default layout                                       |
| ~C-h~       | previous layout in list                                    |
| ~l~         | select/create a layout with helm                           |
| ~L~         | load layouts from file                                     |
| ~C-l~       | next layout in list                                        |
| ~n~         | next layout in list                                        |
| ~N~         | previous layout in list                                    |
| ~o~         | open a custom layout                                       |
| ~p~         | previous layout in list                                    |
| ~r~         | remove current buffer from layout                          |
| ~R~         | rename current layout                                      |
| ~s~         | save layouts                                               |
| ~t~         | display a buffer without adding it to the current layout   |
| ~w~         | workspaces transient-state (needs eyebrowse layer enabled) |
| ~x~         | kill current layout with its buffers                       |
| ~X~         | kill other layouts with their buffers                      |

*** Project Layouts
To create a layout for a specific project use ~SPC p l~.

*** Custom Layouts Transient State
The layouts transient-state is initiated with ~SPC l o~.

Example of default custom layouts that are configured in the corresponding
layers:
| Key Binding | Description                                              |
|-------------+----------------------------------------------------------|
| ~e~         | Emacs custom perspective                                 |
| ~E~         | ERC custom perspective (needs the erc layer enabled)     |
| ~i~         | RCIRC custom perspective (needs the rcirc layer enabled) |
| ~o~         | Org custom perspective                                   |

**Note:** You can add more custom perspectives by using the
~spacemacs|define-custom-layout~ macro explained further below.

* Usage
At the beginning there is only one layout called =Default=  which contains
all the buffers.

If you keep working within this layout then Emacs behaves as if layouts
don't exist so you are never forced to use them even if they are available.

They are two types of layouts:
- regular layouts which you can create dynamically or which can be bound to
  a projectile project (press ~SPC l~ to access them)
- custom layouts which are defined with the macro
 =spacemacs|define-custome-layout= and always active (press ~SPC l o~ to
  access them).

** Save/Load layouts into a file
With ~SPC l s~ and ~SPC l L~ you can save and load perspectives to a file. This
is available without configuration, support is great for emacs 24.4, but
depends on =workgroups.el= for Emacs <= 24.3.

** Custom Layout Macro
If you want to add a new custom layouts (for example if you want to have
IRC on its own perspective or maybe calendar or gnus) you have to use
the macro =spacemacs|define-custom-layout= as follows:

#+BEGIN_SRC emacs-lisp
  (spacemacs|define-custom-layout "<name-to-be-shown-in-the-modeline>"
    :binding "<bind-key>"
    :body
    (...)
    ;; (stuff to be done in the persp activating)
    ;; (a major mode like twittering-mode or whatever)
    (...))
#+END_SRC

Other example:

#+BEGIN_SRC emacs-lisp
  (spacemacs|define-custom-layout "c++"
    :binding "+"
    :body
    (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 can access this persp with ~SPC l o +~, where ~+~ is the binding.

** Predefined custom layouts
*** Org-agenda custom layout
Here we define a custom layout 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/ERC custom layout
Now you can also open IRC in a new layout to keep all the chat buffers in
one layout isolated from your work buffers.