An opinionated Transient-based user interface for Avy, a GNU Emacs package for jumping to visible text using a char-based decision tree.
While highly functional, Avy has a steep learning curve as it has a very diverse command set. Menus are a user interface (UI) affordance that offer users discoverability and recognition that can lower Avy’s learning curve. While menus are commonly associated with mouse-driven UI, the inclusion of Transient in Emacs core allows for a menu UI that is keyboard-driven. Casual Avy endeavors to offer this as many Emacs users prefer keyboard-driven workflows.
- To provide a keyboard-driven menu UI for Avy.
- To provide casual access to the Avy command set.
- Full coverage of all Avy commands. Casual Avy is not intended to be a power user tool.
- Strict adherence to Avy command naming. While Casual Avy is mostly in alignment with Avy’s command naming, there are cases where it will make an opinionated change if the name is deemed too vague or idiomatic.
- UX Stability (for now). Given that Casual Avy is early in its life-cycle, expect changes to its user experience in terms of menu hierarchy and keybinding choices in future releases.
Casual Avy requires usage of
- Emacs ≥ 29.1
- Avy ≥ 0.5.0
- Casual ≥ 2.0.0
Casual Avy has been verified with the following configuration.
- Emacs 29.3 (macOS 14.4.1, Ubuntu Linux 22.04.4 LTS)
- Avy 0.5.0
As Casual Avy is new, we are looking for early adopters! Your feedback is welcome as it will likely impact Casual Avy’s evolution, particularly with regards to UI.
If installed via MELPA (pending) then add these lines to your Emacs initialization file with your binding of preference.
(require 'casual-avy) ;; optional if using autoloaded menu
(keymap-global-set "M-g" #'casual-avy-tmenu)If you have been using an earlier version 1.x of Casual Avy, thank you. Please use the following guidance:
Updating the package casual-avy via the package menu buffer will automatically update the casual package. However, this will not clean up older Casual 1.x packages. To migrate your existing Casual packages from 1.x to 2.x, run the following commands:
M-x load-library casual
M-x casual-upgrade-base-to-version-2Any Casual v1.x packages that have been superseded by this package will be uninstalled.
While not necessary, it is recommended to run M-x package-autoremove to purge any dangling dependent packages. Cautious readers can choose to audit any packages that are targeted to be removed.
For version 2.x going forward, I (Charles Choi) have decided to not offer any documented guidance on using use-package to configure Casual Avy due my lack of expertise in using it. I leave it to more skilled readers to determine how to best use use-package for their configuration. Please also note that this is not a prohibition on using use-package with Casual Avy. I am simply admitting that I don’t know how to use it.
That said, if you have used :ensure t to install a superseded package, you must remove that configuration. After doing so, please follow the above instructions for installing casual-avy.
Casual Avy requires a recent installation of Transient 0.6.0+ from either ELPA or MELPA. If your version of Emacs is ≤ 30 but also includes Transient as a built-in package, you will need to set the customizable variable package-install-upgrade-built-in to t to enable updating it via package.el. Set this variable and proceed with updating Casual Avy. Alternately invoking package-install with a prefix (C-u) will temporarily coerce the update of dependent built-in packages (example: C-u M-x package-install casual).
As Transient is closely tied to Magit, installing the latest version of Magit (via non-GNU ELPA or MELPA) before installing Casual Avy can also pick up the latest version of Transient.
A number of Avy commands have the option to limit the scope of candidates to the visible part of the current buffer above or below the point. Such commands are denoted with the ‘#’ or ‘⬍’ symbol. Press a to limit the scope above the point, b for below.
The commands listed under Edit Other Line/Region can perform an operation on a visible line or region while keeping the point stationary. This enables a workflow where a different visible part of the Emacs frame can be operated on without having to move the point.
The following glossary details the meaning of the menu labels.
| Menu Label | Operation |
|---|---|
| Copy | Copies the selected object (line, region) into the kill ring. |
| Kill | Kills the selected object into the kill ring. |
| Move to above current line | Moves the selected object to the line above the current point. |
| Duplicate to above current line | Duplicates the selected object to the line above the current point. |
By enabling “Use Unicode Symbols” from the Settings menu, Casual Avy will use Unicode symbols as appropriate in its menus. The following mapping is shown in the table below:
| Name | Plain | Unicode |
|---|---|---|
| Scope | # | ⬍ |
| Previous | Previous | ↑ |
| Next | Next | ↓ |
The Emacs Imenu (index menu) feature offers a way to navigate to a major definition in a file, provided that the current mode supports it. As Imenu behavior is closely related to Avy, support for it is provided here as the menu item labeled “(i) Index”. The following configuration code turns on index menus for Markdown, Org, Makefile, and programming language modes.
(add-hook 'markdown-mode-hook #'imenu-add-menubar-index)
(add-hook 'makefile-mode-hook #'imenu-add-menubar-index)
(add-hook 'prog-mode-hook #'imenu-add-menubar-index)
(add-hook 'org-mode-hook #'imenu-add-menubar-index)If the current buffer is an Org file, then two menu items are supported:
- “(o) Org heading”
- “(g) Org Goto…”
Selecting “Org heading” will invoke the avy-org-goto-heading-timer command. Note as with all other Avy commands, this will only work with Org headings that are visible. If navigation to any Org header is desired, select “Org Goto…” to invoke the command org-goto.
Casual Avy is built using Transient menus and as such adopts much of its default behavior.
Each menu item has a key and a label. The key is what is typed by the user to select the menu item. A key can be prefixed with a meta (M-) or control (C-) key.
Dismissing a menu regardless of how deep you are in sub-menus can be done by entering C-q. A menu can also be dismissed by entering C-g, but this will return you to the parent menu.
If a mouse is available, a menu item can be selected by moving the mouse cursor over its label and pressing down button 1.
Pressing the ? key will toggle help for all the menu items. Press the key of interest to get help for it.
Options such as --above and --below can be saved for future use by typing C-x C-s.
When a Transient menu is raised, a prefix argument (C-u) can be entered before selecting a menu item.
For users who wish to help contribute to Casual Avy or personally customize it for their own usage, please read the developer documentation.
If you enjoy using Casual Avy, consider making a modest financial contribution to help support its development and maintenance.
Casual Avy is part of a suite of user interfaces for different Emacs packages called Casual Suite.
Different interfaces include those for I-Search, Dired, Info, Calc, Bookmarks, RE-Builder, IBuffer, and others. Learn more about them today!
A heartfelt thanks to all the contributors to Avy and Transient. Casual Avy would not be possible without your efforts.