Emacs Lisp UI - Lesson 3: Fields

In this lesson we will study the different types of text fields we can use when creating interfaces in Emacs. Text fields are a fundamental part of any form since they let the user enter data such as text, numbers, dates, etc.

`editable-field`

It is the single-line text field.

(widget-create 'editable-field
      :format "Label: %v"
      :size 20
      "Default text")

Shown as follows:

editable-field

Some attributes we can use are:

format: Format that will be shown in the text field. %v is the default value. If I want a label-like text to appear in front, I can play with the order like Name: %v.
tag: Default text that will be shown in the text field. If not specified, the field will be empty or use the last parameter.
size: Size of the text field in characters.
help-echo: Help text that will be shown over the mouse or in the minibuffer when the field has focus. It would be the equivalent of the HTML placeholder attribute combined with title, adapted to Emacs.
value-face: Typography of the text entered by the user. By default it is widget-field-face or your configuration.
secret: If a character is set, the text entered by the user will be hidden with that character. For example, with :secret ?* it will show ***** instead of Texto.
valid-regexp: Regular expression the text entered by the user must match.
error: Text that will be given when the regular expression is not met.
notify: Function that will run when RET or C-m is pressed in the text field.
keymap: Keymap that will be used in the text field. By default it is widget-keymap.

The last parameter is the default value the text field will have. If left empty, the field will be empty.

The following example creates a classic username and password login.

(widget-create 'editable-field
           :format "Username: %v"
           :help-echo "Enter your username"
           :size 15)
(widget-create 'editable-field
           :format "Password: %v"
           :help-echo "Enter your password"
           :size 15
           :secret ?*)

If you are going to run it on your own, remember the structure mentioned earlier.

`text`

It is the multiline field or text box, similar to HTML's textarea. Its properties are the same as the editable-field field but with one subtle difference: pressing RET (or the Enter key) inserts a new line instead of moving to the next field.

(widget-create 'text
      :format "Label: %v"
      :size 20
      "Default text")

Multiline field

Let's look at an example application where we have a multiline field that transforms all of its content to uppercase.

The code is as follows:

(setq widget-resultado nil)
(widget-create 'text
           :format "Text to convert: %v"
           :size 15
           :notify (lambda (widget &rest ignore)
             (widget-value-set widget-resultado (upcase (widget-value widget)))))
(widget-insert "\n\n")
(setq widget-resultado (widget-create 'item ""))

It is important to store the references of the created widgets so we can manipulate them later. In this code, we store the reference of the item field (we will study it in more depth in the next lesson) where the uppercase result will be shown.

But a form does not live on text fields alone. In the next lesson we will learn to create selectable elements such as checkboxes, radio buttons, dropdowns and editable lists, to enrich the interface.

Activity 1

Create a contact form with the following fields:

First name
Last name
Email address
Message

The message field must be a multiline text field. It does not need to have functionality nor validate the data (we will learn that later). That said, do not forget to include a submit button.

Activity 2

Implement a form with a multiline text field and a button. When it is pressed, all the text entered in the text field must be reversed.

Activity 3

Build a concept explainer that uses the Wikipedia API.

Use the following fields.