8.1.13 The editable-field Widget

Syntax:

type ::= (editable-field [keyword argument]... [ value ])

A widget that can be edited by the user. Its super is the default widget.

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the field. If not present, :value is the empty string.

Warning: In an editable-field widget, the editable field must not be adjacent to another widget—that won’t work. You must put some text in between. Either make this text part of the editable-field widget itself, or insert it with widget-insert.

This widget either overrides or adds the following properties:

:convert-widget

Just like the item widget, this function allows it to initialize :value from value.

:keymap

Keymap used in the editable field.

The default value is widget-field-keymap, which allows the user to use all the normal editing commands, even if the buffer’s major mode suppresses some of them. Pressing RET invokes the function specified by :action.

:format

By default, it specifies to insert only the widget’s value.

Warning: In an editable-field widget, the ‘%v’ escape must be preceded by some other text in the :format string (if specified).

:size

The width of the editable field.

By default the field will reach to the end of the line.

:value-face

Face used for highlighting the editable field.

Default is widget-field-face, see User Interface.

:secret

Character used to display the value.

You can set this to, e.g., ?* if the field contains a password or other secret information. By default, this is nil, and the value is not secret.

:valid-regexp

By default the :validate function will match the content of the field with the value of this attribute.

The default value is "" which matches everything.

:validate

Returns nil if the current value of the widget matches the :valid-regexp value.

:prompt-internal

A function to read a value for widget, used by the :prompt-value function.

:prompt-history

A variable that holds the history of field minibuffer edits.

:prompt-value

A function that uses the :prompt-internal function and the :prompt-history value to prompt for a string, and return the user response in the external format.

:action

When invoked, moves point to the next field.

:value-create

Function that takes care of creating the widget, respecting its :size and :value.

:value-set

Function to use to modify programmatically the current value of the widget.

:value-delete

Function that removes the widget so it cannot be edited anymore.

:value-get

Function to return the current text in the widget.

It takes an optional argument, no-truncate. If no-truncate is nil, truncates trailing spaces.

:match

Function that makes the widget match any string value.