— Function: format-mode-line format &optional face window buffer

This function formats a line of text according to format as if it were generating the mode line for window, but instead of displaying the text in the mode line or the header line, it returns the text as a string. The argument window defaults to the selected window. If buffer is non-nil, all the information used is taken from buffer; by default, it comes from window's buffer.

The value string normally has text properties that correspond to the faces, keymaps, etc., that the mode line would have. And any character for which no face property is specified gets a default value which is usually face. (If face is t, that stands for either mode-line if window is selected, otherwise mode-line-inactive. If face is nil or omitted, that stands for no face property.)

However, if face is an integer, the value has no text properties.

For example, (format-mode-line header-line-format) returns the text that would appear in the selected window's header line ("" if it has no header line). (format-mode-line header-line-format 'header-line) returns the same text, with each character carrying the face that it will have in the header line itself.