---

5 Setting Up the Buffer

To show the widgets in a buffer, you have to create them. Widget creation is actually a two-step process: conversion and creation per se. With simple projects, usually the conversion step isn’t really important, and you only care about widget creation, so feel free to skip the conversion description until you really need to know it.

Widget conversion is the process that involves taking a widget specification and transforming it into a widget object, suitable to be created, queried and manipulated with other widget functions. Widget creation is the process that takes a widget object and actually inserts it in the buffer.

The simplest function to create a widget is widget-create, which gets a widget specification and returns a widget object.

Function: widget-create type [ keyword argument ]… args ¶

Create and return a widget of type type, converting it.

type is a symbol that specifies a widget type. keyword may be one of the properties supported by the widget type, and argument specify the value for that property. These keyword arguments can be used to overwrite the keyword arguments that are part of type by default, as well as to provide other properties not present in type by default. args holds additional information for the creation of type and each widget type is responsible for handling that information in a specific way.

The syntax for the type argument is described in Widget Gallery, and in more detail in every widget where it’s relevant.

There are other functions for creating widgets, useful when you work with composite widgets. That is, widgets that are part of other widgets.

Function: widget-create-child-and-convert parent type &rest args ¶

Create a widget of type type as a child of parent.

Before creating it, converts type using the keyword arguments provided in args. Adds the :indent property, unless it is already present, and sets it to the sum of the values of: :indent and :offset from parent and :extra-offset from type.

Returns a widget object, with the property :parent set to PARENT.

Function: widget-create-child parent type ¶

Create a widget of type type as a child of parent.

This function is like widget-create-child-and-convert but it doesn’t convert type, so it expects an already converted widget.

Function: widget-create-child-value parent type value ¶

Create a widget of type type as a child of parent with value value.

This function is like widget-create-child, but it lets you specify a value for the widget.

Converts value to the internal format, as specified by type, and stores it into the :value property of type. That means, value should be in the external format, as specified by type.

All these creating functions described here use the function stored in the :create property. So, to modify the creation logic for a widget, you can provide a different :create function.

When you’re done creating widgets and you’re ready for the user to interact with the buffer, use the function widget-setup.

Function: widget-setup ¶

Setup the current buffer, so that editable widgets can be edited.

This should be called after creating all the widgets and before allowing the user to edit them.

As mentioned, all these functions return a widget object. That widget object can be queried and manipulated with widget functions that take widgets as arguments, until deleting it with the widgets functions available to delete widgets. Even if you don’t save the returned widget object, you still can interact programmatically with the widget. See Working with Widgets.

Function: widget-delete widget ¶

Delete the widget widget and remove it from the buffer.

Function: widget-children-value-delete widget ¶

Delete all children and buttons in widget widget.

This function does not delete widget itself, only the widgets stored in the :children and :buttons properties. It also sets those properties to nil.

As with the creation mechanism, the function stored in :delete controls the deletion mechanism for a widget.

Additionally, the library provides a way to make a copy of a widget.

Function: widget-copy widget ¶

Makes a copy of widget widget and returns it.

It uses the function stored in the :copy property of widget and returns the widget that that function returns.

As discussed, there is a conversion step when creating a widget. To do the conversion without actually creating the widget, you can use the widget-convert function.

Function: widget-convert type &rest args ¶

Convert type to a widget object, using keyword arguments args.

Returns a widget object, suitable for creation. It calls the function stored in the :convert-widget property, after putting into the :args property the arguments that the widget in question needs. If type has a :value property, either originally or after doing the conversion, this function converts the value stored in :value to the internal format, and stores it into :value.

Apart from only creating widgets in the buffer, It’s useful to have plain text. For inserting text, the recommended way is with the widget-insert function.

Function: widget-insert &rest args ¶

Insert args, either strings or characters, at point.

Uses insert to perform the insertion, passing args as argument. See Insertion in the Emacs Lisp Reference Manual, for more information about args.

The resulting text will be read-only.