Working with Widgets

This section covers the more important functions needed to query and manipulate widgets in a generic way. Widgets may have additional functions for interacting with them, those are described in the description for each widget. See Widget Gallery.

Function: widgetp widget

Non-nil if widget is a widget.

Function: widget-type widget

Return the type of widget widget, a symbol.

This function is useful to find out which kind of widget widget represents, i.e., the name of the widget type when the widget was created.

Function: widget-member widget property

Non-nil if widget widget has a value (even nil) for property property.

Function: widget-get widget property

For widget widget, return the value of the property property.

property should be a keyword, and the value is what was last set by widget-put for property.

Function: widget-put widget property value

For widget widget, set the property property to value. property should be a keyword, while value can be anything.

Function: widget-at &optional pos

Return the widget at position pos, or at point if pos is nil.

Function: widget-field-at pos

Return the widget field at position POS, or nil if there is none.

Function: widget-apply widget property &rest args

Apply the function stored in property to widget, passing args as additional arguments to the function.

Returns the result of that function call.

Function: widget-value widget

Return the current value contained in widget.

Note that the value returned by this function might differ from what’s stored in the :value property of widget. This is because this function extracts the current value of widget from the buffer, taking editions into account.

The value returned is in the external format, after getting it with the :value-get function.

It is an error to call this function on an uninitialized widget.

Function: widget-value-set widget value

Set the value contained in widget to value.

Converts value to the internal format, and then sets it by applying the :value-set function.

It is an error to call this function with an invalid value, that is, a value that widget cannot represent.

Function: widget-default-get widget

Return the default external value of widget widget.

The default value is the one stored in :value or the result of applying the :default-get function to the arguments of widget, as stored in :args. A value of nil is ignored by default, so in order for a widget to respect nil as a value, it has to override the :default-get function.

Function: widget-type-default-get widget

Convert the :type attribute in widget and return its default value.

Function: widget-child-value-get widget

Return the value of the first member of :children in widget.

Function: widget-child-value-inline widget

Return the inline value of the first member of :children in widget.

The inline value is whatever the function stored in :value-inline returns.

Function: widget-type-value-create widget

Create a child widget for widget, of type stored in :type.

Creates the child widget taking the value from the :value property and stores the newly created widget in the :children property of widget.

The value stored in :type should be an unconverted widget type.

Function: widget-value-convert-widget widget

Initializes the :value property of widget from :args.

Sets :args to nil and returns the modified widget widget.

Function: widget-value-value-get widget

Return the value stored in :value for widget widget.

This is different to getting the current value for widget with widget-value, since that function extracts the value from the buffer.

Function: widget-apply-action widget &optional event

Apply the function stored in :action to widget, in response to event.

It is an error to call this function with an inactive widget.

Function: widget-parent-action widget &optional event

Tell :parent of widget to handle event.

Optional event is the event that triggered the action.

Function: widget-child-validate widget

Check that the first member of :children in widget is valid.

To be valid means that the widget value passes the checks that the function stored in :validate makes.

Function: widget-children-validate widget

Check that all :children in widget are valid.

Returns nil on success, or the first child that isn’t valid.

Function: widget-type-match widget value

Return non-nil if VALUE matches the value for the :type widget.

As with the other type functions, the widget stored in :type should be an unconverted widget.

Function: widget-types-copy widget

Copy the :args value in widget and store them in :args.

Makes the copies by calling widget-copy on each element present in :args. Returns the modified widget widget.

Function: widget-types-convert-widget widget

Convert the :args value in widget and store them in args.

Returns the modified widget widget.