[[https://melpa.org/#/spaceline][http://melpa.org/packages/spaceline-badge.svg]] [[https://stable.melpa.org/#/spaceline][https://stable.melpa.org/packages/spaceline-badge.svg]] [[https://travis-ci.org/TheBB/spaceline][https://travis-ci.org/TheBB/spaceline.svg]] [[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
Contents :TOC_2_gh:
[[#introduction][Introduction]]
[[#the-default-themes][The default themes]]
[[#moderate-configuration][Moderate configuration]]
[[#deep-configuration][Deep configuration]]
[[#tweaking-or-defining-your-own-mode-line][Tweaking or defining your own mode-line]]
Introduction This is the package that provides [[http://spacemacs.org/][Spacemacs]] with its famous mode-line theme. It has been extracted as an independent package for general fun and profit.
This package provides features for three kinds of users.
The functionality for each are described in the following sections.
The files in this package are organized as follows. Choose which you want to load based on what you want to do.
=spaceline.el=: Contains the core library used to define segments and render the modeline. It defines no segments by itself except the =global= segment. (See below.)
=spaceline-segments.el=: Defines all the segments used by the default Spacemacs theme, but doesn’t do anything with them.
=spaceline-config.el=: Defines the default themes.
The default themes To install it, just load =spaceline-config= and call the theme function you want. E.g.
(require 'spaceline-config) (spaceline-spacemacs-theme)
The package comes bundled with two themes:
In addition, Spaceline supports custom themes for Info+ and Helm. These can be enabled through global minor modes:
These are also defined in =spaceline-config.el=.
** Optional dependencies These themes include several segments that depend on third-party packages. If these packages are not installed, these segments will be invisible and not show any output. As such, they can be considered /optional/ dependencies.
Here follows a brief list of these dependencies. For more information consult the upstream sources.
*** Persp-mode [[https://github.com/Bad-ptr/persp-mode.el][Persp-mode]] is a powerful workspace-like package. Spaceline shows the current workspace name.
*** Eyebrowse [[https://github.com/wasamasa/eyebrowse][Eyebrowse]] is a simpler workspace-like package. If it is installed, The Spacemacs theme will show the current workspace number. The Emacs theme uses the workspace number as a fallback for the perspective name: thus if persp-mode is installed, the Eyebrowse workspace will not be shown.
*** Winum [[https://github.com/deb0ch/winum.el][Winum]] shows a number for each window, and it works with both themes.
To prevent =winum= from inserting its own number in the mode-line, you have to set =winum-auto-setup-mode-line= to nil before activating =winum-mode=:
(setq winum-auto-setup-mode-line nil) (winum-mode)
*** Auto-compile [[https://github.com/tarsius/auto-compile][Auto-compile]] automatically compiles Emacs Lisp files on save if there is an older byte-compiled file. Spaceline shows warnings when they occur.
*** Anzu [[https://github.com/syohex/emacs-anzu][Anzu]] shows the current match and the total number of matches while searching.
Note that Anzu inserts itself in the modeline, to let spaceline handle the modeline, make sure to =(setq anzu-cons-mode-line-p nil)= or customize it.
*** Flycheck [[https://github.com/flycheck/flycheck/][Flycheck]] is a powerful syntax-checking package. Spaceline shows errors, warnings and notifications from it.
*** ERC [[http://www.emacswiki.org/emacs/ERC][ERC]] is an IRC client built in to Emacs. Spaceline shows channels with new messages if you have =erc-track= turned on.
*** Org Spaceline shows the currently clocking [[http://orgmode.org/][org-mode]] task.
*** Org-pomodoro Spaceline integrates with [[HTtps://github.com/lolownia/org-pomodoro][org-pomodoro]] by showing its clocks.
*** Python virtual environments The currently active environments as reported by [[https://github.com/proofit404/pyenv-mode][pyenv-mode]] or [[https://github.com/jorgenschaefer/pyvenv][pyvenv]] are shown in Spaceline.
*** Nyan cat [[https://github.com/TeMPOraL/nyan-mode][Nyan-mode]] shows the current position in the buffer with kittens and rainbows.
*** Fancy battery [[https://github.com/lunaryorn/fancy-battery.el][Fancy-battery]] shows battery information in the modeline.
*** Evil [[https://bitbucket.org/lyro/evil/wiki/Home][Evil]] makes Emacs behave like Vim. The first segment in the Spacemacs theme shows the current Evil state if all the other dependencies do not report information (i.e. no perspective, workspace or window number). The Emacs theme does not include any information from Evil.
You can color the modeline according to the current Evil state by setting =spaceline-highlight-face-func= to =spaceline-highlight-face-evil-state=.
** Troubleshooting There are a number of reasons why Spaceline might look different on your setup compared to Spacemacs proper. Some of the most important ones are addressed here.
You’re missing an optional dependency. Spacemacs includes packages that display information in the mode-line. The leftmost segment is invisible if =eyebrowse-mode=, =persp-mode=, =window-numbering-mode= and =evil= are all not present. If you don’t wish to use these packages, consider using the Emacs theme.
Consider setting or increasing the value of =powerline-height= to give your mode-line some room to breathe.
The default powerline separator is =arrow=, but Spacemacs uses =wave=. You should try out various settings of =powerline-default-separator= to find the one that works for you. Note that you need to recompile the modeline with =M-x spaceline-compile= after setting this variable.
If you’re using =eyebrowse-mode= or =window-numbering-mode=, consider setting =spaceline-workspace-numbers-unicode= and =spaceline-window-numbers-unicode= to =t= to get the nice-looking unicode numbers seen in the screenshot.
Use [[https://github.com/emacsmirror/diminish][Diminish]] to tweak the output of the minor modes segment.
To get the mode-line highlight to change color depending on the evil state, set =spaceline-highlight-face-func= to =spaceline-highlight-face-evil-state=.
Moderate configuration
** Turning segments on and off Each segment has a variable =spaceline-NAME-p= that can switch the segment off by setting it to =nil=. There are also three convenient interactive functions for toggling:
These can be bound to whichever keys you like.
Here is a complete list of segments bundled with Spacemacs.
In addition, the following segments are defined, but are not used in the default themes.
For the custom helm modeline, the following segments are used.
For the custom info modeline, the following segments are used.
** The highlight face The highlight face is the face that (by default) is a sharp orange, used e.g. by the HUD segment on the far right, and the first segment on the left (note that it may be invisible if you are using the Spacemacs theme but not some of its optional dependencies). The actual face used as a highlight face is determined by a function, which can be configured by setting the value of =spaceline-highlight-face-func=. Spaceline comes with three choices, but of course you can write your own:
Note that the highlight face is only used in the active window.
** Other faces In the active window, the mode-line will use these faces:
And in inactive windows:
To override this, you can set the variable =spaceline-face-func=. This should be a function that accepts two arguments and returns a face symbol. The arguments are:
If this function is not set, Spaceline delegates the highlight face to =spaceline-highlight-face-func= (see above), and picks the others according to the above scheme.
** Powerline separators Set =powerline-default-separator= to configure this. The docstring for that variable enumerates the choices.
Each separator comes in two directions: left and right. The variables =spaceline-separator-dir-left= and =spaceline-separator-dir-right= specify which directions to alternate between on the left and right side, respectively.
By default these variables are set to =nil=, which means Spaceline will choose the directions that look best for your chosen separator style. However, you can set to override this, for example:
(setq spaceline-separator-dir-left '(left . left)) (setq spaceline-separator-dir-right '(right . right))
Note that you must recompile the modelines after changing the separators, by calling =M-x spaceline-compile=.
** Hooks The hook =spaceline-pre-hook= is executed before rendering the modeline. Don’t put any performance-intensive functions here!
** Unicode numbers By default, Spacemacs displays window numbers and workspace numbers in nice unicode symbols. To do this in Spaceline, set =spaceline-window-numbers-unicode= or =spaceline-workspace-numbers-unicode= to true, respectively.
Spacemacs also does this with most minor modes. This is a feature that has not been ported to Spaceline. To do this, use [[https://github.com/emacsmirror/diminish][Diminish]].
** Minor modes separator To configure the separator between the minor modes, use =spaceline-minor-modes-separator=.
** Org clock The displayed value of the =org-clock= segment is determined by the function =org-clock-get-clock-string= by default. To configure another function, use =spaceline-org-clock-format-function=.
** Segments A /segment/ is any part of the mode-line that produces some kind of visible output. Typically, segments have been defined ahead of time using =spaceline-define-segment=, in which case the segment is referred to by a symbol, but segments may also be literals (strings or numbers, say) or lists of other segments.
These are all valid segments, provided =my-segment= has been defined:
my-segment "alfa" (my-segment 89)
Segments may also have properties associated with them. Spaceline supports a variety of properties. They can be applied as follows, for a ‘singleton’ segment:
(my-segment :prop-a value-a :prop-b value-b)
Or for a list of segments:
((my-segment 89) :prop-a value-a :prop-b value-b)
** Defining a segment Use =spaceline-define-segment= to define a segment and associate it to a symbol.
(spaceline-define-segment name "Docstring" ;; A single form whose value is the value of the segment. ;; It may return a string, an image or a list of such. (when condition output)
;; Additional keyword properties go here
:prop-a value-a
:prop-b value-b)In addition to storing the segment, this macro produces a variable called =spaceline-NAME-p= whose value may be set to switch the segment off or on manually. Three interactive functions are also defined:
These are convenient to bind to keys, and they do what it says on the tin.
Note that if you redefine a segment, you more than likely have to recompile the modelines with =M-x spaceline-compile= for the changes to take effect.
** Properties The valid properties are
All of these are valid both in =spaceline-define-segment= as well as directly in the segment spec, with the excption of =:when=.
Additionally, =spaceline-define-segment= allows two additional properties.
The properties which take effect for any given segment are, in order of priority:
The exceptions are =:when=, which must be true on all levels for a segment to be displayed, and =:fallback= which does not pass through from the parent segment.
** Bindings When evaluating a segment, its =:when= condition or its =:face= property, the following bindings are available for convenience.
Note that the segment code runs in an environment with many local variables, therefore it’s a good idea to write segments as pure functions that do not change state.
** Compiling a mode-line Finally, call the function =spaceline-compile=. It accepts three arguments: a modeline name, and two lists of segments, for the left and right sides.
This produces a function =spaceline-ml-NAME= that evaluates the mode-line. To use it, set =mode-line-format= to
("%e" (:eval (spaceline-ml-NAME)))
If you do not specify a name, the modeline will be installed as =main=.
If you do not specify segment lists, it will either recompile the given modeline with the segments specified last time, or recompile /all/ modelines if the name is not specified.
When called interactively, the latter behaviour takes effect, that is, all modelines are recompiled.
The variable =spaceline-byte-compile= decides whether the resulting function will be byte-compiled. This is recommended for regular usage, as it involves potentially significant performance benefits.
For instance, to use Spacemac's mode-line definition as a starting point to your own, add this to your =.emacs= or =.spacemacs= and tweak it:
(spaceline-compile ; left side '(((persp-name workspace-number window-number) :fallback evil-state :face highlight-face :priority 100) (anzu :priority 95) auto-compile ((buffer-modified buffer-size buffer-id remote-host) :priority 98) (major-mode :priority 79) (process :when active) ((flycheck-error flycheck-warning flycheck-info) :when active :priority 89) (minor-modes :when active :priority 9) (mu4e-alert-segment :when active) (erc-track :when active) (version-control :when active :priority 78) (org-pomodoro :when active) (org-clock :when active) nyan-cat) ; right side '(which-function (python-pyvenv :fallback python-pyenv) (purpose :priority 94) (battery :when active) (selection-info :priority 95) input-method ((buffer-encoding-abbrev point-position line-column) :separator " | " :priority 96) (global :when active) (buffer-position :priority 99) (hud :priority 99)))