*crystalline.Txt* Functions to help you make your own statusline/tabline Author: Roger Bongers License: Same as Vim (see |license|) INTRODUCTION *crystalline* vim-crystalline provides functions for creating custom statuslines and tablines using Vim's native |'statusline'| syntax. SETTINGS *crystalline-settings* Configure the following global variables before loading vim-crystalline. Define global function settings with |:function|, not |function()|. g:CrystallineStatuslineFn *g:CrystallineStatuslineFn* Sets the statusline. Accepts one argument, the |winnr()| for the statusline. g:CrystallineTablineFn *g:CrystallineTablineFn* Sets the tabline. g:CrystallineTabFn *g:CrystallineTabFn* Custom tabs/buffers for |crystalline#TabsOrBuffers()|. Arguments: `tabnr` The tab number. `bufnr` The buffer number. `max_width` The max allowed width of the tab. `is_sel` Whether the tab is selected. Return a list containing the tab content and the visible width of the tab. Defaults to |crystalline#DefaultTab()|. g:CrystallineHideBufferFn *g:CrystallineHideBufferFn* Hide buffers with |crystalline#TabsOrBuffers()|. Arguments: `bufnr` The buffer number. Returns a boolean (whether the buffer is hidden). Defaults to |crystalline#DefaultHideBuffer()|. g:crystalline_auto_prefix_groups *g:crystalline_auto_prefix_groups* Whether to automatically prefix all |crystalline-highlight-groups| with the current mode or "Inactive" when using |crystalline-functions|. g:crystalline_group_suffix *g:crystalline_group_suffix* A string to add to the end of to all |crystalline-highlight-groups| when using |crystalline-functions|. g:crystalline_theme *g:crystalline_theme* Automatically sets the theme. g:crystalline_mode_labels *g:crystalline_mode_labels* A dictionary containing labels to use for each |mode()|. Default: >vim let g:crystalline_mode_labels = { \ 'n': ' NORMAL ', \ 'c': ' COMMAND ', \ 'r': ' NORMAL ', \ '!': ' NORMAL ', \ 'i': ' INSERT ', \ 't': ' TERMINAL ', \ 'v': ' VISUAL ', \ 'V': ' VISUAL ', \ '': ' VISUAL ', \ 's': ' VISUAL ', \ 'S': ' VISUAL ', \ '': ' VISUAL ', \ 'R': ' REPLACE ', \ '': '', \ } < g:crystalline_separators *g:crystalline_separators* Separators to use with |crystalline#Sep()|. This is a list of objects containing: `ch` The separator character. `alt_ch` The separator character to use between sections with the same background. `dir` The direction the separator faces (either ">" or "<"). Default: >vim " These use powerline-style separators " If you're unable to see them, please use a powerline-compatible font let g:crystalline_separators = [ \ { 'ch': '', 'alt_ch': '', 'dir': '>' }, \ { 'ch': '', 'alt_ch': '', 'dir': '<' }, \ ] < FUNCTIONS *crystalline-functions* Documentation uses vimscript, but all functions can be called from Lua with: >lua local crystalline = require("crystalline") crystalline.fn() < *crystalline.HiItem()* crystalline#HiItem(group) *crystalline#HiItem()* Create a statusline highlight group item. Example: >vim " Returns '%#CrystallineA#' let l:group = crystalline#HiItem('A') < See also |crystalline-highlight-groups|. *crystalline.ModeGroup()* crystalline#ModeGroup(group) *crystalline#ModeGroup()* Prepend the current mode to the group. Example: >vim " Returns 'NormalModeA' let l:group = crystalline#ModeGroup('A') < You do not need to use this function if |g:crystalline_auto_prefix_groups| is defined. See also |crystalline-highlight-groups|. *crystalline.ModeHiItem()* crystalline#ModeHiItem(group) *crystalline#ModeHiItem()* Create a statusline highlight group item with the current mode and the group. Example: >vim " Returns '%#CrystallineNormalModeA#' let l:group = crystalline#ModeHiItem('A') < See also |crystalline-highlight-groups|. *crystalline.ModeLabel()* crystalline#ModeLabel() *crystalline#ModeLabel()* Get the current mode label. See also |g:crystalline_mode_labels|. *crystalline.ModeSection()* *crystalline#ModeSection()* crystalline#ModeSection(sep_index, left_group, right_group) Create a statusline section containing the current mode and a separator. Arguments: `sep_index` The index of a separator in |g:crystalline_separators| to use. `left_group` The left highlight group without the "Crystalline" prefix. When the separator is right facing, this is the mode group. `right_group` The right highlight group without the "Crystalline" prefix. When the separator is left facing, this is the mode group. Equivalent to: >vim " Right facing separator let l:section = crystalline#ModeHiItem(a:left_group) \ . crystalline#ModeLabel() \ . crystalline#Sep(a:sep_index, crystalline#ModeSepGroup(a:left_group), a:right_group) " Left facing separator let l:section = crystalline#ModeHiItem(a:mode_group) \ . crystalline#ModeLabel() \ . crystalline#Sep(a:sep_index, a:left_group, crystalline#ModeSepGroup(a:right_group)) < See also |crystalline-highlight-groups|. *crystalline.Sep()* crystalline#Sep(sep_index, left_group, right_group) *crystalline#Sep()* Create a separator between sections. Arguments: `sep_index` The index of the separaotr in |g:crystalline_separators|. `left_group` The highlight group to the left. `right_group` The highlight group to the right. Highlight groups must omit the "Crystalline" prefix. See also |crystalline-highlight-groups|. *crystalline.DefaultTab()* *crystalline#DefaultTab()* crystalline#DefaultTab(tabnr, bufnr, max_width, is_sel) The default tab/buffer. See also |g:CrystallineTabFn|. *crystalline.TabsOrBuffers()* crystalline#TabsOrBuffers(...) *crystalline#TabsOrBuffers()* Create a section with tabs or buffers. Arguments: `opts` `opts.is_buffers` Display buffers instead of tabs. Defaults to false. `opts.enable_sep` Enable separators. Defaults to false. `opts.sep_index` The index of a separator in |g:crystalline_separators| to use. Defaults to 0. `opts.enable_mouse` Enable mouse controls. Not compatible with buffers. Defaults to true. `opts.auto_prefix_groups Whether to prefix the current mode to highlight groups. Defaults to |g:crystalline_auto_prefix_group|. `opts.min_width` The minium visible width of the tabs/buffers. Takes precedence over `opts.max_width`. Defaults to 24. `opts.max_width` The maximum visible width of the tabs/buffers. This option should reflect available space. Defaults to the width of the screen. `opts.min_tab_width` The minimum width of individual tabs/buffers. Defaults to the space required for an empty buffer. `opts.min_tab_sel_width` The minimum width of the currently selected tab/buffer. Defaults to `opts.min_tab_width`. `opts.max_tabs` The maximum number of tabs. This should prevent the max possible statusline items from being exceeded. Statuslines and tablines can have at max 80 items in Vim. In the worst case, there are 3 items per tab: the mouse control item and 2 items for the separator. There may also be an item used for the right group and an item used to terminate mouse controls. You should decrease this number if |g:CrystallineTabFn| adds items to tabs. Defaults to (80 - 2) / 3 = 26, which is enough to fit the max items. Increase this amount with caution. `opts.group_suffix` A string to append to all group names. Defaults to |g:crystalline_group_suffix|. `opts.left_group` The group to the left of the tabs/buffers. A separator will be generated between the tabs/buffers and this section. To disable, set to an empty string. Defaults to "TabFill" if `sep_index` is left facing. `opts.right_group` The group to the right of the tabs/buffers. A separator will be generated between the tabs/buffers and this section. To disable, set to an empty string. Defaults to "TabFill" if `sep_index` is right facing. See also |g:CrystallineTabFn|, |g:CrystallineHideBufferFn|. See |crystalline-highlight-groups| for more info on groups. *crystalline.Tabs()* crystalline#Tabs(...) *crystalline#Tabs()* Create a section with tabs. See also |crystalline#TabsOrBuffers()|. *crystalline.Buffers()* crystalline#Buffers(...) *crystalline#Buffers()* Create a section with buffers. See also |crystalline#TabsOrBuffers()|. *crystalline.DefaultTabline()* crystalline#DefaultTabline(...) *crystalline#DefaultTabline()* Create a tabline with tabs or buffers. Buffers are shown if only one tab is present. Otherwise, tabs are shown. See also |crystalline#DefaultTablineIsBuffers()|, |crystalline#TabTypeLabel()|, |crystalline#TabsOrBuffers()|. *crystalline.DefaultTablineIsBuffers()* *crystalline#DefaultTablineIsBuffers()* crystalline#DefaultTablineIsBuffers() Returns true when |crystalline#DefaultTabline()| shows buffers. *crystalline.TabTypeLabel()* crystalline#TabTypeLabel(...) *crystalline#TabTypeLabel()* Returns a string indicating if buffers or tabs are being shown. Arguments: `is_buffers` Whether buffers are currently shown. HIGHLIGHT GROUPS *crystalline-highlight-groups* *crystalline-themes* vim-crystalline themes typically provide these highlight groups. Some themes which come with Crystalline automatically adjust to the 'background' with light/dark modes. You do not have to use any of these groups, for example if you do not which to display the current mode, use the default groups. Example of how highlight groups might be used in your statusline/tabline: > +--------------------------------------------------------+ | TabType | Tab | TabSel | Tab | TabFill | |--------------------------------------------------------| | | | | | | | | | | | | | | | | | | | | | | | | |--------------------------------------------------------| | A | B | Fill | B | A | +--------------------------------------------------------+ < CrystallineA *CrystallineA* CrystallineB *CrystallineB* The default leftmost/rightmost and second leftmost/second rightmost statusline sections. Themes may provide more sections such as `CrystallineC`, `CrystallineD`, etc. CrystallineFill *CrystallineFill* The middle statusline section. CrystallineTab *CrystallineTab* Unselected tabs in the tabline. CrystallineTabSel *CrystallineTabSel* Default selected tabs in the tabline. CrystallineTabFill *CrystallineTabFill* The middle of the tabline. CrystallineTabType *CrystallineTabType* The color of the tab type label on the tabline which reads "BUFFERS"/"TABS". *crystalline-highlight-group-variants* CrystallineA1, CrystallineA2, CrystallineB1, CrystallineB2, etc. Variants of the statusline and tabline groups. Can be used to indicate different settings and states. Themes may provide more variants such as 3, 4, 5, etc. or custom variants. *crystalline-inactive-highlight-groups* CrystallineInactiveA, CrystallineInactiveA1, CrystallineInactiveB, etc. Statusline and tabline groups in inactive windows. *crystalline-normal-mode-groups* CrystallineNormalModeA, CrystallineNormalModeA1, CrystallineNormalModeB, etc. Statusline and tabline groups in normal mode. *crystalline-command-mode-groups* CrystallineCommandModeA, CrystallineCommandModeA1, etc. Statusline and tabline groups in command mode. *crystalline-insert-mode-groups* CrystallineInsertModeA, CrystallineInsertModeA1, CrystallineInsertModeB, etc. Statusline and tabline groups in insert mode. *crystalline-visual-mode-groups* CrystallineVisualModeA, CrystallineVisualModeA1, CrystallineVisualModeB, etc. Statusline and tabline groups in visual mode. *crystalline-replace-mode-groups* CrystallineReplaceModeA, CrystallineReplaceModeA1, etc. Statusline and tabline groups in replace mode. *crystalline-terminal-mode-groups* CrystallineTerminalModeA, CrystallineTerminalModeA1, etc. Statusline and tabline groups in terminal mode. CREATING THEMES *crystalline-creating-themes* *crystalline.GenerateTheme()* *crystalline#GenerateTheme()* Define a new theme by defining an |autoload| function which calls `crystalline#GenerateTheme()`. Example: >vim " ~/.vim/autoload/theme/my_theme.vim function! crystalline#theme#my_theme#SetTheme() abort call crystalline#GenerateTheme({ \ 'A': [[17, 190], ['#00005f', '#dfff00'], 'cterm=bold gui=bold'], \ 'B': [[255, 238], ['#ffffff', '#444444'], ''], \ 'Fill': [[85, 234], ['#9cffd3', '#202020'], ''], \ }) endfunction < Each group is a list containing the following: `[[, ], [, ], ]` Undefined groups/attributes will have the following defaults: `*Tab` `CrystallineInactiveFill` or `CrystallineFill`. `*TabSel` `*A` `*TabFill` `*Fill`. `*TabType` `*B`. Where `*` is `Inactive`, `NormalMode`, `CommandMode`, etc. Variants default to non-default variants. Only variants 1-2 are supported by default. At a minimum, define all attributes for `A`, `B`, and `Fill`. For a full example of creating a custom theme, see the solarized theme: See also |crystalline-highlight-groups|. EXAMPLE *crystalline-example* More examples: Fully featured example: >vim function! g:GroupSuffix() if mode() ==# 'i' && &paste return '2' endif if &modified return '1' endif return '' endfunction function! g:CrystallineStatuslineFn(winnr) let g:crystalline_group_suffix = g:GroupSuffix() let l:curr = a:winnr == winnr() let l:s = '' if l:curr let l:s .= crystalline#ModeSection(0, 'A', 'B') else let l:s .= crystalline#HiItem('InactiveFill') endif let l:s .= ' %f%h%w%m%r ' if l:curr let l:s .= crystalline#Sep(0, 'B', 'Fill') . ' %{fugitive#Head()}' endif let l:s .= '%=' if l:curr let l:s .= crystalline#Sep(1, 'Fill', 'B') . '%{&paste ? " PASTE " : " "}' let l:s .= crystalline#Sep(1, 'B', 'A') endif if winwidth(a:winnr) > 80 let l:s .= ' %{&ft} %l/%L %2v ' else let l:s .= ' ' endif return l:s endfunction function! g:CrystallineTablineFn() let g:crystalline_group_suffix = g:GroupSuffix() let l:max_width = &columns let l:right = '%=' let l:right .= crystalline#Sep(1, 'TabFill', 'TabType') let l:max_width -= 1 let l:vimlabel = has('nvim') ? ' NVIM ' : ' VIM ' let l:right .= l:vimlabel let l:max_width -= strchars(l:vimlabel) let l:max_tabs = 23 return crystalline#DefaultTabline({ \ 'enable_sep': 1, \ 'max_tabs': l:max_tabs, \ 'max_width': l:max_width \ }) . l:right endfunction set showtabline=2 set guioptions-=e set laststatus=2 let g:crystalline_auto_prefix_groups = 1 < vim:tw=78:ts=8:ft=help