The ancient art of cross‑stitch is one of the most popular forms of embroidery.
The artist pulls a soft cotton canvas taught in a hoop, equips a needle, gathers reams of coloured threads and sets to work stitching row after row to create an intricate pattern of crosses. The more elaborate pieces contain different shapes of stitches, each with their own threading technique.
At the beginning of it all, before the threads are assembled or needle is put to canvas, is the careful study of a pattern.
A cross‑stitch pattern is a printed grid depicting exactly where each stitch should be made, its colour and the technique used to form it.
Most patterns are sold as images: printed coloured charts with legends to accompany them. The patterns we’ll be working with are humble text files. You should have downloaded a bank of these when setting up.
Windows and buffers
You’ll notice that Emacs is unphased by the
extension. It treats the pattern as it would treat any other text file.
It opens the file contents in a buffer called
, and displays it in the current window.
A window is a portion of the Emacs screen. The screen can be split into multiple windows, both horizontally and vertically.
A window is a view onto a buffer. Buffers contain the contents that we edit. They exist even when we’re not viewing them.
We can tell which buffer a window views by looking at its label.
This window is labelled
A pattern is composed of a title, a legend and a grid.
The grid depicts the stitches that must be made. Each letter code represents a different kind of stitch.
The legend above it shows what each of these codes mean: the colour of thread, how many strands to thread through the needle, and what technique to use when making the stitch.
A text file like this is hardly a good view of the pattern. It
is, at first glance, much more difficult to interpret than an image. In later chapters we’ll write an
xx‑mode function that displays it properly.
Let’s have a peek at that function now.
As part of your setup, you should have downloaded a bunch of
functions prefixed by
coe‑xx, the acronym for “Craft of
Emacs cross-stitch”. These functions are identical to the ones you will write
Let’s call the
Hold down the Alt and x keys.
Your minibuffer will look like this:
The M stands for Meta. At Emacs’s birth in the 1970s, the Meta key was commonplace on keyboards. It has since been replaced by Alt, but Emacs keeps to its traditions.
The minibuffer is the area used to call functions like so:
coe‑xx‑mode and press the Return key.
From now on, we’ll denote these key presses as follows:
This means “hold down the Alt and x keys to use the minibuffer; type
coe‑xx‑mode and press Return”
The pattern buffer is now much more colourful.
coe‑xx‑mode do, aside from colouring in the
grid? Did it change anything else? And where exactly did it come
Emacs has a helpful function for finding out. It’s called
You’ll see a “Describe function:” prompt. We need to input a function name.
coe‑xx‑mode and press Return.
Describe function: coe-xx-mode
We’ll denote calling functions with inputs like so:
M‑x describe‑function coe‑xx‑mode
Describing the function opens up a new window with a
coe-xx-mode is an interactive Lisp function in `/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'. (coe-xx-mode) Major mode for viewing cross stitch patterns. Each cross stitch in the pattern is displayed as a 'x' coloured according to its thread colour. key binding --- ------- C-c Prefix Command <mouse-1> coe-xx-code-select C-c a coe-xx-basket-add C-c c coe-xx-code-select C-c r coe-xx-ruler-mode . This mode runs the hook `coe-xx-mode-hook', as the final or penultimate step during initialization.
The function description is very detailed, quite possibly you won’t understand it all yet. Let’s pick out the important points:
coe‑xx‑modeis a function.
coe‑xx‑modeis also a major mode.
It added some new keybindings to the
Loosely speaking, a major mode is a function that governs a buffer. It may alter the way it is displayed, and will usually add keybindings to it.
A keybinding is a mapping from a key, or combination of keys, to a function.
coe‑xx‑mode added several keybindings:
<mouse-1> coe-xx-code-select C-c a coe-xx-basket-add C-c c coe-xx-code-select C-c r coe-xx-ruler-mode
The left mouse click <mouse-1> is also considered a key.
Left click on a red cross in the
The red crosses are the only ones displayed. According to the
*Help* text, a mouse click is bound to
coe‑xx‑code‑select. What does it do?
coe-xx-code-select is an interactive Lisp function in `/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'. It is bound to <mouse-1>, C-c c. (coe-xx-code-select) Displays stitches with the thread colour and stitch type at point. All other stitches are hidden. Displays the entire pattern if called when a code (a thread colour and stitch type) is already selected. Use this to focus on the stitches you care about when filling in the pattern.
Cross-stitchers fill in their patterns one colour at a time, so displaying a single colour is useful.
The point mentioned in the text is the position of the cursor, usually denoted by a shaded rectangle. Left clicking on a red cross moved the point to it, hence a red stitch type was selected.
According to the description, calling
again will show stitches of all colours. Let’s give it a try.
There are other keybindings to explore. Let’s take a look at the
Hold down the Control and c keys, then type r.
This keybinding is denoted as C‑c r where C stands for Control.
coe‑xx‑ruler‑mode added a ruler to either side of the
grid, useful for counting stitches.
How can you learn more about
Describing the function shows that it is a minor mode.
coe-xx-ruler-mode is an interactive Lisp function in `/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'. It is bound to C-c r. (coe-xx-ruler-mode &optional ARG) Minor mode for measuring cross stitch patterns. ...
A minor mode can be thought of as a function that adds extra behaviour. In this case, the function added rulers.
Let’s try clicking on a stitch with the ruler present.
Left click on a red cross.
You’ll notice that it does something else. Did it even call
coe‑xx‑code‑select? We can find out by describing the key.
M‑x describe‑key and left click.
<mouse-1> at that spot runs the command coe-xx-ruler-focus (found in coe-xx-ruler-mode-map), which is an interactive Lisp function in `/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'. It is bound to <mouse-1>, C-c f. (coe-xx-ruler-focus) Not documented. [back]
A mouse click is now bound to the
function; it adds ticks on the ruler to indicate the point. This must have been bound by
Let’s examine some more keybindings.
Call the keybinding C‑c a.
That didn’t seem to do anything. What did it call?
Describe the keybinding C‑c a.
C-c a runs the command coe-xx-basket-add (found in coe-xx-mode-map), which is an interactive Lisp function in `/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'. It is bound to C-c a. (coe-xx-basket-add) Adds a pattern's materials to a 'shopping basket'. This is used to calculate materials for multiple patterns at once. See also `coe-xx-basket-clear' and `coe-xx-basket-view'
It is indeed still bound and working, and altered an invisible “basket”.
The description references a couple of other functions:
This shows the materials we need for the pattern. A skein is a length of thread wound in a ball. An artist needs to know how many to buy, or fish out from their closet, before starting to stitch.
M‑x coe‑xx‑basket‑clear removes all skeins from
Verify this by calling
M‑x coe‑xx‑basket‑clear then
Exploring source code
The basket manipulation functions weren’t listed in the description
coe‑xx‑mode. There might be more functions we haven’t found out
about. How can we know what they are?
The last place to look is the Emacs Lisp source code. We can do this by finding the function.
M‑x find‑function xx‑basket‑view.
You’ll be launched into a rather lengthy
file. This has many other functions within it, most of which aren’t
relevant at the moment.
The Elisp code probably contains a lot of constructs you’re unfamiliar with. Over the course of the book you’ll write each one of these yourself, and we’ll take the time to thoroughly explore them.
We’re now familiar with all the main functions of the pattern viewer.
Next, we’ll make a function of our own.
Let’s compose a sequence of
coe‑xx functions to
create a specific view. We’ll code these up into a
function in the next section.
Take a look at the demo to see what we’ll create:
M‑x normal‑mode to put
logo.xx in its original state.
The demo displays a pattern grid with rulers and adds a single pattern to the basket .
Create the same view as the demo by calling a sequence of
coe‑xx functions. You can reset the buffers by calling
M‑x normal‑mode and
Write down the sequence of functions you called.
Next, we’ll turn this sequence into a proper function.