doomemacs/modules/ui/workspaces/README.org

#+title:    :ui workspaces
#+subtitle: Tab emulation, persistence, & separate workspaces
#+created:  February 20, 2017
#+since:    2.0.0

* Description :unfold:
This module adds support for workspaces, powered by [[doom-package:tabspaces]] on
top of tab-bar-mode (built into Emacs 27+), as well as a API for manipulating
them.

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

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

** Module flags
- +auto ::
  Automatically resume the last saved workspace on startup.
- +tabs ::
  Use tab-bar to display active workspaces as tabs at the top of the frame.
  Without this, active workspaces are displayed in the echo-area instead.

** Packages
- [[doom-package:tabspaces]]

** TODO Hacks
#+begin_quote
 󱌣 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote

** 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's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Isolated buffer-list
When ~tabspaces-mode~ is active, ~doom-buffer-list~ becomes workspace-restricted.
You can overcome this by using ~buffer-list~ instead.

** Automatic workspaces
A workspace is automatically created (and switched to) when you:

- Create a new frame (with =make-frame=; bound to [[kbd:][M-N]] by default).
- Switch to a project using ~projectile-switch-project~.

** Session persistence
By default, your session is autosaved when you quit Emacs (or disable
~persp-mode~). You can load a previous session with ~M-x
+workspace/load-session~ or ~:sl[oad]~ (ex command).

You can supply either a name to load a specific session to replace your current
one.

** Workspace persistence
If you'd like to save a specific workspace, use ~M-x +workspace/save~, which can
be loaded into the current session (as another workspace) with ~M-x
+workspace/load~.

** Commands & Keybindings
Here is a list of available commands, their default keybindings (defined in
[[../../config/default/+evil-bindings.el][config/default/+bindings.el]]), and corresponding ex commands (if any -- defined
in [[../../editor/evil/+commands.el][config/default/+evil-commands.el]]).

| command                           | key / ex command     | description                                                |
|-----------------------------------+----------------------+------------------------------------------------------------|
| ~+workspace/new~                  | [[kbd:][SPC TAB n]]            | Create a new, blank workspace                              |
| ~+workspace/display~              | [[kbd:][SPC TAB TAB]]          | Display open workspaces in the mode-line                   |
| ~+workspace/load~                 | [[kbd:][SPC TAB l]]            | Load a saved workspace into the current session            |
| ~+workspace/restore-last-session~ | [[kbd:][SPC TAB R]]            | Restore last session                                       |
| ~+workspace/rename~               | [[kbd:][SPC TAB r]]            | Rename the current workspace                               |
| ~+workspace/save~                 | [[kbd:][SPC TAB s]]            | Save the current workspace to a file                       |
| ~+workspace/switch-to~            | [[kbd:][SPC TAB .]]            | Switch to an open workspace                                |
| ~+workspace/other~                | [[kbd:][SPC TAB `]]            | Switch to last workspace                                   |
| ~+workspace/switch-left~          | [[kbd:][SPC TAB []] / [[kbd:][[ w]] / [[kbd:][gT]] | Switch to previous workspace                               |
| ~+workspace/switch-right~         | [[kbd:][SPC TAB ]]] / [[kbd:][] w]] / [[kbd:][gt]] | Switch to next workspace                                   |
| ~+workspace/kill~                 | [[kbd:][SPC TAB d]]            | Delete the current workspace                               |
| ~+workspace/kill-session~         | [[kbd:][SPC TAB x]] / [[kbd:][:sclear]]  | Clears the current session (kills all windows and buffers) |

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

* 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

** API
+ ~+workspace-list~ -> list<Struct>
+ ~+workspace-list-names~ -> list<string>
+ ~+workspace-buffer-list &optional PERSP~ -> bool
+ ~+workspace-p OBJ~ -> bool
+ ~+workspace-exists-p NAME~ -> bool
+ ~+workspace-get NAME &optional NOERROR~ -> Struct
+ ~+workspace-current &optional FRAME WINDOW~ -> Struct
+ ~+workspace-current-name~ -> string
+ ~+workspace-load NAME~
+ ~+workspace-load-session NAME~
+ ~+workspace-save NAME~
+ ~+workspace-save-session NAME~
+ ~+workspace-new NAME~
+ ~+workspace-rename NAME NEW-NAME~
+ ~+workspace-kill NAME &optional INHIBIT-KILL-P~
+ ~+workspace-switch NAME &optional AUTO-CREATE-P~
+ ~+workspace-protected-p NAME~ -> bool