---

3.3 Modelines ¶

A Buffer may specify a modeline, a line of text which is displayed across the bottom of a window to indicate status information. Modelines are described as a list of modeline-field objects which have individual update functions and are optionally fixed-width. These have an eql name for convenience in referencing and updating, but the name must be unique for all created modeline-field objects. When creating a modeline-field with a specified width, the result of the update function is either truncated or padded on the right to meet the constraint. All modeline-field functions must return simple strings with standard characters, and these take a buffer and a window as arguments. Modeline-field objects are typically shared amongst, or aliased by, different buffers’ modeline fields lists. These lists are unique allowing fields to behave the same wherever they occur, but different buffers may display these fields in different arrangements.

Whenever one of the following changes occurs, all of a buffer’s modeline fields are updated:

• A buffer’s major mode is set.
• One of a buffer’s minor modes is turned on or off.
• A buffer is renamed.
• A buffer’s pathname changes.
• A buffer’s modified status changes.
• A window’s buffer is changed.

The policy is that whenever one of these changes occurs, it is guaranteed that the modeline will be updated before the next trip through redisplay. Furthermore, since the system cannot know what modeline-field objects the user has added whose update functions rely on these values, or how he has changed Default Modeline Fields, we must update all the fields. When any but the last occurs, the modeline-field update function is invoked once for each window into the buffer. When a window’s buffer changes, each modeline-field update function is invoked once; other windows’ modeline fields should not be affected due to a given window’s buffer changing.

The user should note that modelines can be updated at any time, so update functions should be careful to avoid needless delays (for example, waiting for a local area network to determine information).

Function: make-modeline-field &key :name :width :function ¶

Function: modeline-field-p modeline-field ¶

Function: modeline-field-name modeline-field ¶

make-modeline-field returns a modeline-field object with name, width, and function. Width defaults to nil meaning that the field is variable width; otherwise, the programmer must supply this as a positive integer. Function must take a buffer and window as arguments and return a simple-string containing only standard characters. If name already names a modeline-field object, then this signals an error.

modeline-field-name returns the name field of a modeline-field object. If this is set with setf, and the new name already names a modeline-field, then the setf method signals an error.

modeline-field-p returns t or nil, depending on whether its argument is a modeline-field object.

Function: modeline-field name ¶

This returns the modeline-field object named name. If none exists, this returns nil.

Function: modeline-field-function modeline-field ¶

Returns the function called when updating the modeline-field. When this is set with setf, the setf method updates modeline-field for all windows on all buffers that contain the given field, so the next trip through redisplay will reflect the change. All modeline-field functions must return simple strings with standard characters, and they take a buffer and a window as arguments.

Function: modeline-field-width modeline-field ¶

Returns the width to which modeline-field is constrained, or nil indicating that it is variable width. When this is set with setf, the setf method updates all modeline-fields for all windows on all buffers that contain the given field, so the next trip through redisplay will reflect the change. All the fields for any such modeline display must be updated, which is not the case when setting a modeline-field’s function.

Function: buffer-modeline-fields buffer ¶

Returns a copy of the list of buffer’s modeline-field objects. This list can be destructively modified without affecting display of buffer’s modeline, but modifying any particular field’s components (for example, width or function) causes the changes to be reflected the next trip through redisplay in every modeline display that uses the modified modeline-field. When this is set with setf, update-modeline-fields is called for each window into buffer.

Function: buffer-modeline-field-p buffer field ¶

If field, a modeline-field or the name of one, is in buffer’s list of modeline-field objects, it is returned; otherwise, this returns nil.

Function: update-modeline-fields buffer window ¶

This invokes each modeline-field object’s function from buffer’s list, passing buffer and window. The results are collected regarding each modeline-field object’s width as appropriate, and the window is marked so the next trip through redisplay will reflect the changes. If window does not display modelines, then no computation occurs.

Function: update-modeline-field buffer window field-or-name ¶

This invokes the modeline-field object’s function for field-or-name, which is a modeline-field object or the name of one for buffer. This passes buffer and window to the update function. The result is applied to the window’s modeline display using the modeline-field object’s width, and the window is marked so the next trip through redisplay will reflect the changes. If the window does not display modelines, then no computation occurs. If field-or-name is not found in buffer’s list of modeline-field objects, then this signals an error. See buffer-modeline-field-p above.