README.org

Centaur tabs

Contents

• What is this?
• Installation
• Customization
  • Headline face
  • Tab Styles
  • Tab height
  • Tab icons
  • Graying out icons
  • Selected tab bar
  • Customize the close button
  • Customize the modified marker
  • Inherit tabbar faces:
  • Disable centaur-tabs in selected buffers
  • Buffer groups
  • Show buffer groups names instead of buffer names in tabs
  • Enable Vim like tab motions
  • Prevent the access to specified buffers
  • Tab cycling
  • Buffer reordering
  • Helm integration
  • Ivy integration
  • Projectile integration
• TO DO
• My personal configuration
• Known supported theme plugins
  • Currently Themed
  • Sent Pull Request
• How to contribute

What is this?

This projects aims to become an aesthetic, functional and efficient tabs plugin for Emacs with a lot of customization options. Although this is a fork from awesome-tab (that I forked with the permission from the author and it’s also based on tabbar) it’s been heavily modified so now it may be considered a different package. Also this package integrates functionalities from tabbar-ruler.

It currently looks like this (although there’s a ton of possible configurations):

Installation

You can download this package from MELPA. This is a basic use-package configuration:

(use-package centaur-tabs
  :demand
  :config
  (centaur-tabs-mode t)
  :bind
  ("C-<prior>" . centaur-tabs-backward)
  ("C-<next>" . centaur-tabs-forward))

Or if you use require:

(require 'centaur-tabs)
(centaur-tabs-mode t)
(global-set-key (kbd "C-<prior>")  'centaur-tabs-backward)
(global-set-key (kbd "C-<next>") 'centaur-tabs-forward)

Customization

This package is heavily customizable, with many options available to the user. Here are some of them:

Headline face

You can make the headline face match the centaur-tabs-default face. This makes the tabbar have an uniform appearance. In your configuration use the following function:

(centaur-tabs-headline-match)

Tab Styles

To change the tab style, modify the centaur-tabs-style variable like this:

(setq centaur-tabs-style "bar")

The options available are:

• “alternate”

• “bar”

• “box”

• “chamfer”

• “rounded”

• “slant”

• “wave”

• “zigzag”

Tab height

To change the tab height do

(setq centaur-tabs-height 32)

Tab icons

To display themed icons from all the icons

(setq centaur-tabs-set-icons t)

Graying out icons

To gray out icons for the unselected tabs:

(setq centaur-tabs-gray-out-icons 'buffer)

Implement functionality for unselected windows instead of unselected buffer.

Selected tab bar

To display a colored bar at the left of the selected tab

(setq centaur-tabs-set-bar 'left)

To display an overline over the selected tab:

(setq centaur-tabs-set-bar 'over)

The color can be customized via the centaur-active-bar-face face.

Customize the close button

To disable the close button

(setq centaur-tabs-set-close-button nil)

To change the displayed string for the close button

(setq centaur-tabs-close-button "X")

Also there are two faces to customize the close button string: centaur-tabs-close-unselected and centaur-tabs-close-selected

Customize the modified marker

To display a marker indicating that a buffer has been modified (atom-style)

(setq centaur-tabs-set-modified-marker t)

To change the displayed string for the modified-marker

(setq centaur-tabs-modified-marker "*")

Also there are two faces to customize the close button string: centaur-tabs-modified-marker-unselected and centaur-tabs-modified-marker-selected

Inherit tabbar faces:

Many theme plugins have already themed other tab plugins (doom-themes for example). This package is able to use those tab plugin faces to theme itself. In a near future, many PRs will be sent so this package gets properly themed. To use the already existing tabbar faces use:

(centaur-tabs-inherit-tabbar-faces)

Disable centaur-tabs in selected buffers

To disable the tabs in a buffer just add a hook to the centaur-tabs-local-mode function like this:

(add-hook 'dired-mode-hook 'centaur-tabs-local-mode)

or with use-package:

(use-package centaur-tabs
  ...
  :hook
  (dired-mode . centaur-tabs-local-mode)
  ...)

Buffer groups

To customize the way that the buffers are grouped modify the centaur-tabs-buffer-groups function like this:

    (defun centaur-tabs-buffer-groups ()
      "`centaur-tabs-buffer-groups' control buffers' group rules.

    Group centaur-tabs with mode if buffer is derived from `eshell-mode' `emacs-lisp-mode' `dired-mode' `org-mode' `magit-mode'.
    All buffer name start with * will group to \"Emacs\".
    Other buffer group by `centaur-tabs-get-group-name' with project name."
      (list
	(cond
	 ((or (string-equal "*" (substring (buffer-name) 0 1))
	      (memq major-mode '(magit-process-mode
				 magit-status-mode
				 magit-diff-mode
				 magit-log-mode
				 magit-file-mode
				 magit-blob-mode
				 magit-blame-mode
				 )))
	  "Emacs")
	 ((derived-mode-p 'prog-mode)
	  "Editing")
	 ((derived-mode-p 'dired-mode)
	  "Dired")
	 ((memq major-mode '(helpful-mode
			     help-mode))
	  "Help")
	 ((memq major-mode '(org-mode
			     org-agenda-clockreport-mode
			     org-src-mode
			     org-agenda-mode
			     org-beamer-mode
			     org-indent-mode
			     org-bullets-mode
			     org-cdlatex-mode
			     org-agenda-log-mode
			     diary-mode))
	  "OrgMode")
	 (t
	  (centaur-tabs-get-group-name (current-buffer))))))

Show buffer groups names instead of buffer names in tabs

If you want your tabs to display buffer groups names instead of buffer names you can put the following in your configuration:

(setq centaur-tabs--buffer-show-groups t)

You can toggle between the two options interactively with the (centaur-tabs-toggle-groups) command.

Enable Vim like tab motions

To enable Vim like tab changing binds

(define-key evil-normal-state-map (kbd "g t") 'centaur-tabs-forward)
(define-key evil-normal-state-map (kbd "g T") 'centaur-tabs-backward)

or with use-package:

(use-package centaur-tabs
  ...
  :bind
  (:map evil-normal-state-map
	     ("g t" . centaur-tabs-forward)
	     ("g T" . centaur-tabs-backward))
  ...)

Prevent the access to specified buffers

You can prevent the access to some buffers via tab motions changing the following function like this:

   (defun centaur-tabs-hide-tab (x)
     (let ((name (format "%s" x)))
	 (or
	  (string-prefix-p "*epc" name)
	  (string-prefix-p "*helm" name)
	  (string-prefix-p "*Compile-Log*" name)
	  (string-prefix-p "*lsp" name)
	  (and (string-prefix-p "magit" name)
	       (not (file-name-extension name)))
	  )))

Tab cycling

The default behaviour from the centaur-tabs-forward/backward functions is to go through all the tabs in the current group and then change the group. If this is something that is to desired to be changed the centaur-tabs-cycle-scope custom must be changed like this:

(setq centaur-tabs-cycle-scope 'tabs)

There are three options:

• ‘default: (Already described)
• ‘tabs: Cycle through visible tabs (that is, the tabs in the current group)
• ‘groups: Navigate through tab groups only

Buffer reordering

To enable an automatic buffer reordering function use the following function in your configuration:

(centaur-tabs-enable-buffer-reordering)

;; When the currently selected tab(A) is at the right of the last visited
;; tab(B), move A to the right of B. When the currently selected tab(A) is
;; at the left of the last visited tab(B), move A to the left of B
(setq centaur-tabs-adjust-buffer-order t)

;; Move the currently selected tab to the left of the the last visited tab.
(setq centaur-tabs-adjust-buffer-order 'left)

;; Move the currently selected tab to the right of the the last visited tab.
(setq centaur-tabs-adjust-buffer-order 'right)

This works the following way. If there’s a certain group of tabs like the following:

If you’re in a tab and change to another tab in the group (via Ido, Ivy or Helm) the new tab will move to the right side of the tab you were, so if you’re on tab1.el and you clicked tab4.py the tabs order will be the following:

And then if you were on tab4.py and changed to tab2.js,the tabs order will be the following:

the order doesn’t change ,because the tabs are already next to each other.

And now if you were on tab2.js and changed to tab1.el,the tabs order will be the following:

This functionality doesn’t take effect when using centaur-tabs motion functions like centaur-tabs-backward/forward.

Helm integration

You can integrate Helm with centaur-tabs for changing tab-groups. Just add helm-source-centaur-tabs-group in helm-source-list. Then you’ll be able to use (centaur-tabs-build-helm-source) function and bind it to any key you want. (I’m not a Helm user so I’ll not be able to solve problems related to this).

Ivy integration

You can integrate Ivy with centaur-tabs for changing tab-groups. Just use the (centaur-tabs-counsel-switch-group) and bind it to any key you want.

Projectile integration

You can group your tabs by Projectile’s project. Just use the following function in your configuration:

(centaur-tabs-group-by-projectile-project)

This function can be called interactively to enable Projectile grouping. To go back to centaur-tabs’s user defined (or default) buffer grouping function you can interactively call:

(centaur-tabs-group-buffer-groups)

TO DO [15/19]

• [X] Integrate all-the-icons
• [X] Improve all the icons placing
• [X] Fix all the icons background
• [X] Add selected, unselected, selected-modified and unselected-modified faces
• [X] Make function to inherit tabbar faces
• [X] Group tabs by projectile’s project (was already implemented but not for projectile)
• [X] Create PR to different theme packages for this package
• [X] Add modified marker icon option
• [X] Add sideline for selected tab (atom style)
• [X] Add overline for selected tab (atom style). It’s easy to add to the text, but not to the icon, so for any who figures it out a PR is welcome.
• [ ] Add easy tab style configuration function. (Atom, Sublime, VS Code… like (centaur-tabs-tab-theme "atom"))
• [X] Make icon insert after the separator
• [X] Add a customizable close button
• [ ] Explore if after-modifying-buffer function can be improved
• [X] Fix messages buffer icon an FontAwesome errors
• [ ] Check for Elscreen compatibility
• [X] Add this package to MELPA
• [X] Make a configuration to display buffer groups names instead of buffer names in tabs
• [ ] Add full evil-mode support with tab commands

My personal configuration

My personal configuration for reference:

 (use-package centaur-tabs
   :load-path "~/.emacs.d/other/centaur-tabs"
   :config
   (setq centaur-tabs-style "bar")
   (setq centaur-tabs-height 32)
   (setq centaur-tabs-set-icons t)
   (setq centaur-tabs-set-bar 'over)
   (setq centaur-tabs-set-modified-marker t)
   (centaur-tabs-headline-match)
   (centaur-tabs-mode t)
   (defun centaur-tabs-buffer-groups ()
     "`centaur-tabs-buffer-groups' control buffers' group rules.

 Group centaur-tabs with mode if buffer is derived from `eshell-mode' `emacs-lisp-mode' `dired-mode' `org-mode' `magit-mode'.
 All buffer name start with * will group to \"Emacs\".
 Other buffer group by `centaur-tabs-get-group-name' with project name."
     (list
      (cond
	((or (string-equal "*" (substring (buffer-name) 0 1))
	     (memq major-mode '(magit-process-mode
				magit-status-mode
				magit-diff-mode
				magit-log-mode
				magit-file-mode
				magit-blob-mode
				magit-blame-mode
				)))
	 "Emacs")
	((derived-mode-p 'prog-mode)
	 "Editing")
	((derived-mode-p 'dired-mode)
	 "Dired")
	((memq major-mode '(helpful-mode
			    help-mode))
	 "Help")
	((memq major-mode '(org-mode
			    org-agenda-clockreport-mode
			    org-src-mode
			    org-agenda-mode
			    org-beamer-mode
			    org-indent-mode
			    org-bullets-mode
			    org-cdlatex-mode
			    org-agenda-log-mode
			    diary-mode))
	 "OrgMode")
	(t
	 (centaur-tabs-get-group-name (current-buffer))))))
   :hook
   (dashboard-mode . centaur-tabs-local-mode)
   (term-mode . centaur-tabs-local-mode)
   (calendar-mode . centaur-tabs-local-mode)
   (org-agenda-mode . centaur-tabs-local-mode)
   (helpful-mode . centaur-tabs-local-mode)
   :bind
   ("C-<prior>" . centaur-tabs-backward)
   ("C-<next>" . centaur-tabs-forward)
   ("C-c t" . centaur-tabs-counsel-switch-group)
   (:map evil-normal-state-map
	  ("g t" . centaur-tabs-forward)
	  ("g T" . centaur-tabs-backward)))

Known supported theme plugins

Currently Themed

• Atom One Dark Theme
• Base16
• Doom Themes
• Kaolin Themes
• Wilmsersdorf Theme
• Zenburn

Sent Pull Request

• Spacemacs Theme

How to contribute

You can contribute by forking the repo and then creating a pull request with the changes you consider will improve the package. There’s a TO DO list with wanted features so you can start from there. I’ll be glad to receive help. Please try to keep the code as clear and documented as possible.