notes from /dev/null - elisp

Using Emacs to make phone calls and lookup map places on macOS

2023-06-20T11:13:00-07:00

I admit, I do take a perverse delight in making phone calls from my computer. On macOS, this can be achieved via the iPhone Cellular Calls feature, which proxies your computer to your iPhone’s calling capability. Tied to this feature is the ability to select a phone number in a native macOS app text field and use it to dial that number direct. An example is shown below from the Safari app.

To dial a number, the app translates the human-formatted phone number into a tel: URL scheme that is then used to open the FaceTime app to make the call.

We can emulate this behavior in Emacs. This post will show you how.

Making a Phone Call

First off is parsing the human-formatted phone number. We can do this by writing some regexps. Since I live in North America, I’ve chosen to use regexps that conform to the North American Numbering Plan (NANP). NANP formats phone numbers into the form +1 (xxx) xxx-xxxx. I've also chosen to make regexps that also accepts spaces and “.” as separators.

(defvar cc/pat-nanp-international "^+1 \
[(]*\\([0-9]\\{3\\}\\)[)]*\
[\\. -]\\([0-9]\\{3\\}\\)[\\. -]\\([0-9]\\{4\\}\\)$"
  "Regexp for North American Numbering Plan phone number including +1.")

(defvar cc/pat-nanp "^[(]*\\([0-9]\\{3\\}\\)[)]*[\\. -]\
\\([0-9]\\{3\\}\\)[\\. -]\\([0-9]\\{4\\}\\)$"
  "Regexp for North American Numbering Plan phone number without +1.")

In the above I’ve defined two separate regexps with capture groups, one to handle numbers starting with +1 and the other for those without it.

From these regexps we can write the following function to convert a phone number to a tel: URL.

(defun cc/nanp-phone-number-to-url (phone)
  "Convert PHONE number string to url \"tel:\"."
  (cond
   ((string-match cc/pat-nanp-international phone)
    (replace-regexp-in-string cc/pat-nanp-international
                              "tel:+1-\\1-\\2-\\3" phone))
   ((string-match cc/pat-nanp phone)
    (replace-regexp-in-string cc/pat-nanp "tel:+1-\\1-\\2-\\3" phone))))

It is then straightforward to write an interactive function that takes a phone number as a selected region, converts it to a tel: URL, and opens it.

(defun cc/call-nanp-phone-number (&optional start end)
  "Phone call the selected number (region) bounded between START and END"
  (interactive "r")
  (let ((phone-buf (buffer-substring start end)))
    (browse-url (cc/nanp-phone-number-to-url phone-buf))))

Putting the above code to work, we can show the following example of selecting the phone number +1 (415) 867-5309 and dialing it from Emacs.

Looking a place up in Apple Maps

A similar exercise can be done with searching for a place in the Maps app, which is accessible via the maps: URL scheme. Unlike a phone number, we will forego trying to interpret the selected region beforehand and just pass the region as the query to the maps: URL.

(defun cc/open-region-in-apple-maps (&optional start end)
  "Open region from START to END in Apple Maps"
  (interactive "r")
  (let* ((query-buf (buffer-substring start end))
         (mapURL (concat "maps://?q=" (url-encode-url query-buf))))
    (message "Searching for %s" query-buf)
    (browse-url mapURL)))

The following function lets you interactively enter an arbitrary place to search in Apple Maps.

(defun cc/search-apple-maps (search)
  "Open SEARCH query in Apple Maps"
  (interactive "MMap Search: ")
  (let ((mapURL (concat "maps://?q=" (url-encode-url search))))
    (message "Searching for %s" search)
    (browse-url mapURL)))

Putting the above code to work, we can show the following example of finding "Harlan Records, SF" in the Maps app from Emacs.

Modifying the above to work with Google Maps is left as an exercise to reader.

Context Menus

Note that all of the above examples are keyboard driven. They are not necessarily so. In fact, driving much of the above work was the desire to be able to perform these actions via a context menu. And it is very much doable, however I'll elaborate on how I've done this in a forthcoming post. For now, here's some demo screenshots of my context menu implementation that supports making a phone call or searching a location.

References

Automatically adjusting Emacs to macOS switches in appearance

2023-06-04T11:36:00-07:00

Count me among those who likes using the Auto setting when adjusting the appearance in macOS to either light or dark. Native macOS apps that are coded accordingly can automatically adjust as well, and it turns out that the Yamamoto Mitsuharu fork of Emacs (aka emacs-mac-app) can do this too. But with emacs-mac-app, just because it can detect the appearance change doesn’t mean that all the themes or faces will adjust accordingly too. As such it is typically up to the user to write a pair of custom light and dark mode functions to invoke when the appearance change happens.

For quite some time I’ve been calling these appearance mode functions manually like an animal. Then I recently learned that mac-effective-appearance-change-hook is a thing.

This hook gets invoked upon a macOS appearance change, so it becomes straightforward to write a hook function that tests for the :appearance property returned by
(mac-application-state).

(defun cc/reconfigure-nsappearance ()
  (let ((appearance (plist-get (mac-application-state) :appearance)))
    (if (string-equal appearance "NSAppearanceNameDarkAqua")
        (cc/dark-mode)
      (cc/light-mode))))

(add-hook 'mac-effective-appearance-change-hook 'cc/reconfigure-nsappearance)

A caveat though: the above code will only work with the Yamamoto fork of Emacs for macOS. As of now there seems to be no consensus on how to handle OS-level appearance changes by Emacs core. That said, if the above works for you, then no more manual appearance change calls!

References

Elisp code for cc/reconfigure-nsappearance
Where to get emacs-mac-app:
- MacPorts
- Homebrew

Beautifying Org Plot with YASnippet and Context Menus

2023-01-27T20:15:00-08:00

In using Org tables, it is a natural desire to visualize the data captured in them. Org Plot is a built-in feature in Org to do just that without having to leave Emacs. That said, a couple of caveats with using Org Plot out of the box:

Without configuration, Org Plot output is ugly.
Making Org Plot attractive requires a lot of boilerplate code with unmemorable syntax.

Given the above, it seems easier to punt and export your table data to a spreadsheet to make plots. But why bother with two sources of truth when you can just work with one? This post endeavors to show that you can have beautiful and easy to make plots with Org Plot.

Unconvinced? Come back after watching the video demo below.

Want to know more? Read on…

Background

Under the hood, Org Plot uses gnuplot to generate a graphic plot.

gnuplot is, like Emacs, a robust and highly configurable program. But like Emacs, gnuplot has many default settings that are less than desirable. The net result of this is that gnuplot without configuration produces ugly output. Don’t take my word for it - others say it here, here, here, and here.

That said, gnuplot can be easily configured to have attractive, daresay beautiful, output.

To generate a plot, the function org-plot/gnuplot is invoked via either the key binding C-c " g or calling M-x org-plot/gnuplot. When org-plot/gnuplot is first called, the gnuplot program is initialized and communicated to via the Emacs buffer ✷gnuplot✷. From there org-plot/gnuplot will translate the #+PLOT options for a table into gnuplot commands.

Org Plot Out of the Box

Here’s an example of a table taken from the Org Plot documentation.

#+PLOT: title:"Citas" ind:1 deps:(2 3) type:2d with:histograms set:"yrange [0:]"
| Sede      | Max cites | H-index |
|-----------+-----------+---------|
| Chile     |    257.72 |   21.39 |
| Leeds     |    165.77 |   19.68 |
| Sao Paolo |     71.00 |   11.50 |
| Stockholm |    134.19 |   14.33 |
| Morelia   |    257.56 |   17.67 |

Running org-plot/gnuplot will result in a GUI window plot as shown below:

A couple of observations at this point:

All the PLOT options are put into a single line, but they don’t have to be.

Options can be enumerated over multiple lines for easier comprehension and maintainability.
The key binding for org-plot/gnuplot is quite difficult to remember.

YMMV, but I'll likely never remember C-c " g.
The rendered plot is missing basic elements such as labels for the x and y axis.

There are also no affordances to change the typeface and size for different labels.
While the resultant plot is functional, thin lines and unfilled shapes is unattractive.

In the next section, we’ll show how to address these observations to get more attractive output from Org Plot.

Objectives

Let’s sanity check the things we want to achieve with this post:

Support quick creation of plots from an Org table that you can use and share with colleagues without embarrassment.
Support line and column (called histogram in gnuplot) style plots.
Support configuring basic plot features:
- plot title
- x and y axis labels
- typeface and sizes of the above
Use context-menu-mode as the primary UI to Org Plot.
Not require associative recall of gnuplot commands and options to achieve the above.

Prerequisites

An understanding of Org Plot
A basic understanding of gnuplot
An understanding of YASnippet

Beautifying Org Plot

Set the typeface, and typeface size

Org Plot provides a pass-through interface for the gnuplot command set, which is used to set a multitude of gnuplot options. The line below shows how the typeface and typeface size can be configured via the <typeface> and <typeface-size> parameters. Setting these values will apply to all labels used in the plot.

1	`#+PLOT: set:"termoption font '<typeface>,<typeface-size>'"`

For my taste, I’ll use Futura for <typeface> and 12pt for the <typeface-size>.

Alternately, one could configure the gnuplot terminal and set graphic device, size, and font in a single command. For example on macOS:

1	`#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"`

Setting the <typeface> and <typeface-size> for the x and y axis labels are done via the gnuplot options xtics and ytics respectively.

#+PLOT: set:"xtics font '<typeface>,<typeface-size>'"
#+PLOT: set:"ytics font '<typeface>,<typeface-size>'"

If <typeface> is omitted, then the current font option value will be used.

Set the histogram (column) style

We’ll configure the style of the histogram with the following code. Refer to the gnuplot documentation on histograms for more detail on syntax.

#+PLOT: set:"style histogram clustered gap 2"
#+PLOT: set:"style fill solid 1.0 border -1"

Set the Legend

The gnuplot option key controls how the legend is rendered. Refer to the gnuplot documentation on key placement and key for more detail on syntax.

1	`#+PLOT: set:"key right top"`

Set the Axis Labels

The options xlabel and ylabel can be set with the appropriate string values for the plot at hand. Replace <xlabel> and <ylabel> accordingly.

#+PLOT: set:"xlabel '<xlabel>'"
#+PLOT: set:"ylabel '<ylabel>'"

Bring it all together

The following code brings all of the above together. The output result from running org-plot/gnuplot is shown below.

#+PLOT: title:"Citas"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram clustered gap 1"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Cities'"
#+PLOT: set:"ylabel 'Metrics'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:1 deps:(2 3)
| Sede      | Max cites | H-index |
|-----------+-----------+---------|
| Chile     |    257.72 |   21.39 |
| Leeds     |    165.77 |   19.68 |
| Sao Paolo |     71.00 |   11.50 |
| Stockholm |    134.19 |   14.33 |
| Morelia   |    257.56 |   17.67 |

Line Plot Example

If the plot is using line style, you can specify the linewidth to use. Here it is specified the value of 3 px.

1	`#+PLOT: with:"lines linewidth 3"`

Adjusting the PLOT header accordingly, the source and resultant plot output is shown below.

#+PLOT: title:"Line Example"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Some x metric'"
#+PLOT: set:"ylabel 'Some y metrics'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: ind:1 deps:(2 3)
#+PLOT: with:"linespoints linewidth 3 pointsize 2.0"
| x | y | z |
|---+---+---|
| 0 | 0 | 8 |
| 1 | 3 | 2 |
| 2 | 8 | 3 |
| 3 | 7 | 9 |
| 4 | 2 | 8 |
| 5 | 4 | 8 |

So much boilerplate to type. Can we do something about that?

So at this point we have the desired control and aesthetics but at the cost of a lot of boilerplate PLOT statements. To alleviate typing, we'll use YASnippet, a template system that supports dynamic expansion. Among the key features it provides is the ability to prompt the user to choose different values and based on that value dynamically generate the expanded output.

For the histogram example above, the YASnippet template can be as follows:

# -*- mode: snippet -*-
# name: org-plot histogram
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term `(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))` size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram ${2:$$(yas-choose-value '("clustered" "rowstacked"))}${2:$(when (equal yas-text "clustered") " gap 1")}"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:${5:1} deps:(${6:2})$0

The above snippet has logic to 1) dynamically choose the terminal type (term), 2) tab key to different fields to populate the plot’s title, axis labels, and histogram style, and 3) define which table column is independent (ind) and which columns are dependent (deps).

Note that different YASnippet templates can be created for different plot types. For this post we’ll only concentrate on variants of lines and histograms.

# -*- mode: snippet -*-
# name: org-plot lines
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term `(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))` size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: ind:${5:1} deps:(${6:2})
#+PLOT: with:"${7:$$(yas-choose-value '("lines" "linespoints" "impulses"))} linewidth 3${7:$(when (equal yas-text "linespoints") " pointsize 2.0")}"$0

At this point we have some snippets but have yet to define a way to invoke them. I don’t intend to frequently make plots but for the times that I do I want it to be easy. Context menus (aka right mouse button menus) offer low cognitive load so let’s go with that.

Integrating Org Plot with Context Menu Mode

Introduced in Emacs 28, context-menu-mode provides built-in conventions for using and customizing right mouse button menus. For this post, I’ll just capture the Elisp that I used to integrate Org Plot into context menus. For further elaboration on how customizing context menus works, please read up my earlier post on it.

Here’s a screenshot showing my Org Plot context menu at work.

At the top level, the menu items are:

The cell reference the pointer is in

Selecting this item will put the cell reference (in this case the string @4$2) into the kill ring.
A sub-menu labeled Insert Plot
Run gnuplot which invokes org-plot/gnuplot

Note that the Org Plot context menu is only shown if the pointer is within the bounds of a table.

Make the Keymap for Insert Plot sub-menu

The following code-snippet illustrates how the sub-menu for Insert Plot is implemented. The keymap variable cc/insert-org-plot-menu holds the menu-item instances, each of which holds a reference to the function that inserts the desired snippet.

(defvar cc/insert-org-plot-menu (make-sparse-keymap "Insert Org Plot"))

(define-key cc/insert-org-plot-menu [lines-interactive]
  '(menu-item "Lines - GUI" cc/org-plot-insert-lines-plot
              :help "Insert lines, linespoints, or impulses style chart for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [lines-timestamp-interactive]
  '(menu-item "Lines Timestamp - GUI" cc/org-plot-insert-lines-timestamp-plot
              :help "Insert lines, linespoints, or impulses style chart with timestamps for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [columns-interactive]
  '(menu-item "Histogram - GUI" cc/org-plot-insert-histogram-plot
              :help "Insert histogram (column) style chart for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [org-plot-menu-single-separator]
  '(menu-item "--single-line"))

(define-key-after cc/insert-org-plot-menu [lines-image]
  '(menu-item "Lines - Image" cc/org-plot-insert-lines-plot-image
              :help "Insert lines, linespoints, or impulses style chart for image creation"))

(define-key-after cc/insert-org-plot-menu [lines-timestamp-image]
  '(menu-item "Lines Timestamp - Image" cc/org-plot-insert-lines-timestamp-plot-image
              :help "Insert lines, linespoints, or impulses style chart with timestamps for image creation"))

(define-key-after cc/insert-org-plot-menu [columns-image]
  '(menu-item "Histogram - Image" cc/org-plot-insert-histogram-plot-image
              :help "Insert histogram (column) style chart for image creation"))

Attach the Insert Plot sub-menu to the Context Menu

The following code shows how to hook the above menu cc/insert-org-plot-menu into the top-level context menu via the function cc/context-menu-addons. The function cc/kill-org-table-reference is used to copy the table reference into the Emacs kill-ring.

(defun cc/context-menu-addons (menu click)
  "CC context menu additions"
  (save-excursion
    (mouse-set-point click)

    (when (org-at-table-p)
      (define-key-after menu [org-table-separator]
        '(menu-item "--single-line"))
      (define-key-after menu [org-table-field-info]
        '(menu-item (format "@%d$%d"
                            (org-table-current-dline)
                            (org-table-current-column))
                    cc/kill-org-table-reference
                    :help "Table field/cell information"))
      (define-key-after menu [org-table-insert-plot]
        (list 'menu-item "Insert Plot" cc/insert-org-plot-menu))

      (define-key-after menu [org-plot-gnuplot]
        '(menu-item "Run gnuplot" org-plot/gnuplot
                    :help "Run gnuplot"))))
  menu)

(defun cc/kill-org-table-reference (e)
(interactive "e")
(kill-new (format "@%d$%d"
                  (org-table-current-dline)
                  (org-table-current-column))))

(add-hook 'context-menu-functions #'cc/context-menu-addons)

Functions to Insert Snippets

There is a general function cc/org-plot-insert-snippet which will insert an arbitrarily named snippet into the buffer at the start of an Org table. Its implementation checks to see if the pointer is within a table before inserting the snippet.

From there a number of helper functions invoking cc/org-plot-insert-snippet with a specific snippet name are defined. These helper functions are referenced by cc/insert-org-plot-menu above.

(defun cc/org-plot-insert-snippet (name)
  "Insert NAME snippet at top of the table.

If the point is not within an Org table then an error message
will be displayed."
  (if (org-at-table-p)
      (progn
        (org-backward-paragraph)
        (yas-expand-snippet (yas-lookup-snippet name)))
    (message "Error: not in org-table")))

(defun cc/org-plot-insert-lines-plot ()
  "Invoke snippet named \"org-plot lines\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines"))

(defun cc/org-plot-insert-lines-timestamp-plot ()
  "Invoke snippet named \"org-plot lines timestamp\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines timestamp"))

(defun cc/org-plot-insert-histogram-plot ()
  "Invoke snippet named \"org-plot histogram\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot histogram"))

(defun cc/org-plot-insert-lines-plot-image ()
  "Invoke snippet named \"org-plot lines image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines image"))

(defun cc/org-plot-insert-lines-timestamp-plot-image ()
  "Invoke snippet named \"org-plot lines timestamp image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines timestamp image"))

(defun cc/org-plot-insert-histogram-plot-image ()
  "Invoke snippet named \"org-plot histogram image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot histogram image"))

What about timestamps?

Org Plot has the ability to work with both Org-style and regular timestamps as the independent column. The snippet below shows how this is supported.

# -*- mode: snippet -*-
# name: org-plot lines timestamp
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term ${2:`(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))`} size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"xtics format '${5:%Y-%m-%d}'"
#+PLOT: set:"yrange [0:]"
#+PLOT: timeind:1
#+PLOT: ind:${6:1} deps:(${7:2})
#+PLOT: with:"${8:$$(yas-choose-value '("lines" "linespoints" "impulses"))} linewidth 3${8:$(when (equal yas-text "linespoints") " pointsize 2.0")}"$0

Note that there is a current bug in Org Mode as of 9.6.1 that requires declaring the timeind option. For timestamps to work, timeind must be set to 1.

#+PLOT: title:"Weight"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Date'"
#+PLOT: set:"ylabel 'Kg'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"xtics format '%Y-%m-%d'"
#+PLOT: set:"yrange [0:]"
#+PLOT: timeind:1
#+PLOT: ind:1 deps:(2)
#+PLOT: with:"lines linewidth 3"
| Date             |   Kg |
|------------------+------|
| <2010-02-21 Sun> | 95.0 |
| <2010-02-22 Mon> | 93.0 |
| <2010-02-23 Tue> | 92.0 |
| <2010-02-24 Wed> | 91.5 |
| <2010-02-27 Sat> | 91.0 |
| <2010-03-01 Mon> | 92.0 |

Here’s the resultant plot:

Writing to SVG, JPEG, or PNG

The above snippets are configured to output to a gnuplot GUI terminal. The snippet below is tuned to write a file to either a SVG, JPEG, or PNG format.

# -*- mode: snippet -*-
# name: org-plot histogram image
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term ${2:$$(yas-choose-value '("svg" "jpeg" "png"))} size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram ${3:$$(yas-choose-value '("clustered" "rowstacked"))}${3:$(when (equal yas-text "clustered") " gap 1")}"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${4:x label}'"
#+PLOT: set:"ylabel '${5:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:${6:1} deps:(${7:2})
#+PLOT: file:"${8:image}.${2:$(cond ((equal yas-text "svg") "svg") ((equal yas-text "jpeg") "jpg") ((equal yas-text "png") "png"))}"$0

Concluding Thoughts

Org Plot can be made much more attractive and usable with YASnippet and context menus.
The code examples (particularly the snippets) above can be refined to be both more generalized and richer in capability.
For Org Table users, one less reason to leave Emacs for a spreadsheet program. 😏

Acknowledgments

Thanks to yantar92Orgcontr on the #org-mode IRC channel for the assistance in identifying the issue with timeind.

References

Customizing the Emacs Context Menu

2023-01-03T00:53:00-08:00

Summary

(best played full screen, no audio)

Novice Elisp programmer (me) succeeds in customizing Emacs right mouse button menu behavior. Uses this knowledge to copy common actions seen in native (in particular macOS) applications.

This post captures how I got here.

Background

Context menus triggered by a right mouse button event are a commonly used GUI pattern. Emacs provides support for this via context-menu-mode which was introduced in version 28. Customizing context-menu-mode requires some understanding how menus are structured. I won’t go into too much detail describing how Emacs menus work here, but hopefully will impart enough about it to get you going.

What I Did

Requirements

Context menu should only show menu actions based on context. Different criteria for context are enumerated below and can be used in combinatorial fashion for a particular action.
- buffer mode (major and minor)
- region is selected (active) or not
- buffer-file-name is version controlled

Preconditions

My customized context menu relies on these packages being installed. YMMV. Also, you must use Emacs version ≧ 28.

osx-dictionary - Dictionary lookup using the macOS-installed dictionary
google-this - Search for term in Google
reveal-in-folder - Reveal current file in native OS folder.
Export an Org Region to RTF - Elisp snippet for using macOS command line utility textutil to convert Org markup to rich text format
ox-slack - Exports Org markup to Slack markup
- ox-gfm - dependency required by ox-slack

Turn on `context-menu-mode`

I’ve got context-menu-mode turned on in both prog-mode-hook and text-mode-hook which should cover most all my programming (Python, ObjC, Swift, Elisp, C, etc.) and text (Org, Markdown) modes via inheritance. It is also turned on for dired and shell modes.

(add-hook 'text-mode-hook 'context-menu-mode)
(add-hook 'prog-mode-hook 'context-menu-mode)
(add-hook 'shell-mode-hook 'context-menu-mode)
(add-hook 'dired-mode-hook 'context-menu-mode)

At this point, you should be able to right mouse button click anywhere on a buffer see a menu. But that menu is quite unexciting. We’ll address this next.

Let’s Make a Menu

A common context menu action is to take selected text and either capitalize, upper, or lower case it, as illustrated below.

We’ll implement the above as a sub-menu with the user-defined variable cc/transform-text-menu whose value is a sparse keymap. The code below illustrates how this is implemented.

;; Transform Text
(defvar cc/transform-text-menu (make-sparse-keymap "Transform Text"))

(define-key cc/transform-text-menu [tranform-text-uppercase]
  '(menu-item "Make Upper Case" upcase-region
              :help "Upper case region"))

(define-key-after cc/transform-text-menu [tranform-text-lowercase]
  '(menu-item "Make Lower Case" downcase-region
              :help "Lower case region"))

(define-key-after cc/transform-text-menu [tranform-text-capitalize]
  '(menu-item "Capitalize" capitalize-region
              :help "Capitalize region"))

Note that the actual commands to execute the transformations (upcase-region, downcase-region, capitalize-region) are invoked in each menu-item call.

Note that at this point cc/transform-text-menu only defines the sub-menu but it is not attached to anything yet.

Let’s Make a Menu, Part 2

Let’s make another sub-menu with the user-defined variable cc/org-emphasize-menu, this time to format (emphasize) selected text in Org-mode as shown below.

The source to achieve this is described below. Note that the actual emphasis commands (cc/org-emphasize-bold|italic|code|…) in this menu are built on-top of org-emphasize, which generalizes what type of emphasis (bold, italic, code, etc.) to use as a function argument.

;; Org Emphasize
(defvar cc/org-emphasize-menu (make-sparse-keymap "Org Emphasize"))

(define-key cc/org-emphasize-menu [org-emphasize-bold]
  '(menu-item "Bold" cc/org-emphasize-bold
              :help "Bold"))

(define-key-after cc/org-emphasize-menu [org-emphasize-italic]
  '(menu-item "Italic" cc/org-emphasize-italic
              :help "Italic"))

(define-key-after cc/org-emphasize-menu [org-emphasize-code]
  '(menu-item "Code" cc/org-emphasize-code
              :help "Code"))

(define-key-after cc/org-emphasize-menu [org-emphasize-underline]
  '(menu-item "Underline" cc/org-emphasize-underline
              :help "Underline"))

(define-key-after cc/org-emphasize-menu [org-emphasize-verbatim]
  '(menu-item "Verbatim" cc/org-emphasize-verbatim
              :help "Verbatim"))

(define-key-after cc/org-emphasize-menu [org-emphasize-strike-through]
  '(menu-item "Strike Through" cc/org-emphasize-strike-through
              :help "Strike through"))

(define-key-after cc/org-emphasize-menu [org-emphasize-reset]
  '(menu-item "Reset" cc/org-emphasize-reset
              :help "Remove emphasis"))

;; Convenience functions to emphasize by type
(defun cc/org-emphasize-bold ()
  (interactive)
  (org-emphasize ?*))

(defun cc/org-emphasize-italic ()
  (interactive)
  (org-emphasize ?/))

(defun cc/org-emphasize-code ()
  (interactive)
  (org-emphasize ?~))

(defun cc/org-emphasize-underline ()
  (interactive)
  (org-emphasize ?_))

(defun cc/org-emphasize-verbatim ()
  (interactive)
  (org-emphasize ?=))

(defun cc/org-emphasize-strike-through ()
  (interactive)
  (org-emphasize ?+))

(defun cc/org-emphasize-reset ()
  ;; org bug: this won't work when org-hide-emphasis-markers is turned on.
  (interactive)
  (org-emphasize ?\s))

With the above source, we now have a variable cc/org-emphasis-menu that holds the emphasis sub-menu. We are ready to hook this into the context menu!

Customizing the Context Menu

Customizing the context menu requires:

Defining a new function (in this case cc/context-menu-addons) to capture the customized context menu behavior.

Hooking that new function (cc/context-menu-addons) into the variable context-menu-functions via the add-hook function.

(defun cc/context-menu-addons (menu click)
  "CC context menu additions"
  (save-excursion
    (mouse-set-point click)
    (define-key-after menu [open-in-finder]
      '(menu-item "Open in Finder" reveal-in-folder-this-buffer
                  :help "Open file (buffer) in Finder"))

    (when (region-active-p)
      (define-key-after menu [osx-dictionary-lookup]
        '(menu-item "Look up" osx-dictionary-search-word-at-point
                    :help "Look up in dictionary"))

      (define-key-after menu [occur-word-at-mouse]
        '(menu-item "Occur" occur-word-at-mouse
                    :help "Occur")))

    (when (and (bound-and-true-p buffer-file-name)
               (vc-registered (buffer-file-name)))
      (define-key-after menu [vc-separator]
        '(menu-item "--single-line"))

      (define-key-after menu [magit-status]
        '(menu-item "Magit Status" magit-status
                    :help "Magit Status"))
      (define-key-after menu [ediff-revision]
        '(menu-item "Ediff revision…" cc/ediff-revision
                    :help "Ediff this file with revision")))

    (when (region-active-p)
      (define-key-after menu [transform-text-separator]
        '(menu-item "--single-line"))
      (define-key-after menu [tranform-text]
        (list 'menu-item "Transform" cc/transform-text-menu)))

    (when (and (derived-mode-p 'org-mode) (region-active-p))
      (define-key-after menu [org-emphasize]
        (list 'menu-item "Org Emphasize" cc/org-emphasize-menu))

      (define-key-after menu [org-export-to-slack]
        '(menu-item "Copy as Slack" org-slack-export-to-clipboard-as-slack
                    :help "Copy as Slack to clipboard"))

      (define-key-after menu [copy-as-rtf]
        '(menu-item "Copy as RTF" dm/copy-as-rtf
                    :help "Copy as RTF to clipboard")))

    (when (region-active-p)
      (define-key-after menu [google-search]
        '(menu-item "Search with Google" google-this-noconfirm
                    :help "Search Google with region"))))
    menu)

;; hook into context menu
(add-hook 'context-menu-functions #'cc/context-menu-addons)

Note that the implementation of cc/context-menu-addons has logic to query context information such as buffer mode, whether text is selected (region-active-p), and source control (vc-registered) to determine if a menu-item is to be rendered.

Extras: Clean up Ediff UX

IMHO, Ediff has terrible UX out of the box, especially when quitting where it leaves a bunch of buffers strewn about. The code below helps mitigate some of that behavior thanks to this posted comment in StackExchange.

;; Pass buffer-file-name into Ediff
(defun cc/ediff-revision (e)
  "Invoke ediff-revision with buffer-file-name."
  (interactive "e")
  (ediff-revision buffer-file-name))

;; Fix Ediff quit UX behavior by closing all buffers
(defvar my-ediff-last-windows nil)

(defun my-store-pre-ediff-winconfig ()
  (setq my-ediff-last-windows (current-window-configuration)))

(defun my-restore-pre-ediff-winconfig ()
  (set-window-configuration my-ediff-last-windows))

(add-hook 'ediff-before-setup-hook #'my-store-pre-ediff-winconfig)
(add-hook 'ediff-quit-hook #'my-restore-pre-ediff-winconfig)

Also note that my Ediff variables are set as follows:

'(ediff-keep-variants nil)
'(ediff-split-window-function 'split-window-horizontally)
'(ediff-window-setup-function 'ediff-setup-windows-plain)

Observations

Going through this exercise, a couple of observations:

Customizing an Emacs menu requires a lot of boilerplate. Maybe because I’m naive to Elisp and Emacs conventions, there might be a cleaner implementation, but it seems like I gotta work too hard (both learning and implementing) to customize a menu.
I tried to implement context-dependent logic in the :visible property documented in Extended Menu Items in the function cc/context-menu-addons. Didn’t work. Elisp experts, definitely would like your feedback.
Having the function cc/context-menu-addons hooking into a global variable content-menu-functions seems like a very monolithic design. Maybe there’s a cleaner pattern here?
Embark looks awesome, but sometimes you just want a mouse.
Beyond thrilled to have gotten here. Hope you feel likewise!

Acknowledgments

Thanks to Philip Kaludercic’s post that helped considerably in my understanding of how to customize a context menu.

Thanks to deaddyfreaddy for providing informal code review on Reddit for an earlier version of this post. This current post has been amended to reflect his feedback.

notes from /dev/null - elisp

Using Emacs to make phone calls and lookup map places on macOS

Making a Phone Call

Looking a place up in Apple Maps

Context Menus

References

Automatically adjusting Emacs to macOS switches in appearance

References

Beautifying Org Plot with YASnippet and Context Menus

Background

Org Plot Out of the Box

Objectives

Prerequisites

Beautifying Org Plot

Set the typeface, and typeface size

Set the histogram (column) style

Set the Legend

Set the Axis Labels

Bring it all together

Line Plot Example

So much boilerplate to type. Can we do something about that?

Integrating Org Plot with Context Menu Mode

Make the Keymap for Insert Plot sub-menu

Attach the Insert Plot sub-menu to the Context Menu

Functions to Insert Snippets

What about timestamps?

Writing to SVG, JPEG, or PNG

Concluding Thoughts

Acknowledgments

References

Customizing the Emacs Context Menu

Summary

Background

What I Did

Requirements

Preconditions

Turn on context-menu-mode

Let’s Make a Menu

Let’s Make a Menu, Part 2

Customizing the Context Menu

Extras: Clean up Ediff UX

Observations

Acknowledgments

References

Turn on `context-menu-mode`