Writing listers

Listers provide a way to show some segments multiple times: once per each entity (buffer, tabpage, etc) lister knows. They are functions which receive the following arguments:

pl

A powerline.PowerlineLogger class instance. It must be used for logging.

segment_info

Base segment info dictionary. Lister function or class must have powerline_requires_segment_info to receive this argument.

Warning

Listers are close to useless if they do not have access to this argument.

Refer to segment_info detailed description for further details.

draw_inner_divider

If False (default) soft dividers between segments in the listed group will not be drawn regardless of actual segment settings. If True they will be drawn, again regardless of actual segment settings. Set it to None in order to respect segment settings.

And also any other argument(s) specified by user in args key (no additional arguments by default).

Listers must return a sequence of pairs. First item in the pair must contain a segment_info dictionary specific to one of the listed entities.

Second item must contain another dictionary: it will be used to modify the resulting segment. In addition to usual keys that describe segment the following keys may be present (it is advised that only the following keys will be used):

priority_multiplier

Value (usually a float) used to multiply segment priority. It is useful for finer-grained controlling which segments disappear first: e.g. when listing tab pages make first disappear directory names of the tabpages which are most far away from current tabpage, then (when all directory names disappeared) buffer names. Check out existing listers implementation in powerline/listers/vim.py.