An opinionated Transient-based user interface for Symbol Overlay.
The Symbol Overlay (symbol-overlay) package has many useful functions and bindings that if not used frequently are easy to forget. Menus are a user interface (UI) affordance that offer users discoverability and recognition that can lower its 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 Symbol Overlay endeavors to offer this as many Emacs users prefer keyboard-driven workflows.
- To provide a keyboard-driven menu UI for editing symbol-overlay.
- To provide casual access to the Symbol Overlay command set.
- Full coverage of all bookmark list commands. Casual Symbol Overlay is not intended to be a power user tool.
- Strict adherence to bookmark list command naming. While Casual Symbol Overlay is mostly in alignment with
symbol-overlaylist 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 Symbol Overlay is early in its life-cycle, expect changes to its user experience in terms of menu hierarchy and keybinding choices in future releases.
Casual Symbol Overlay requires usage of
- Emacs ≥ 29.1
- Symbol Overlay ≥ 4.2
- Casual ≥ 2.0.0
Casual Symbol Overlay has been verified with the following configuration.
- Emacs 29.4 (macOS 14.5, Ubuntu Linux 22.04.4 LTS)
As Casual Symbol Overlay is new, we are looking for early adopters! Your feedback is welcome as it will likely impact Casual Symbol Overlay’s evolution, particularly with regards to UI.
If installed via MELPA then add these lines to your Emacs initialization file with your binding of preference. For consistency with other Casual packages for different modes, use C-o.
(require 'casual-symbol-overlay) ; optional if using autoloaded menu
(keymap-set symbol-overlay-map "C-o" #'casual-symbol-overlay-tmenu)Casual Symbol Overlay 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 installing Casual. 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 Symbol Overlay can also pick up the latest version of Transient.
Given a symbol already highlighted with symbol-overlay-mode, move the point over any part of that symbol. Enter the binding C-o to raise the Transient menu casual-symbol-overlay-tmenu.
Casual Symbol Overlay 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.
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 Symbol Overlay or personally customize it for their own usage, please read the developer documentation.
If you enjoy using Casual Symbol Overlay, consider making a modest financial contribution to help support its development and maintenance.
Casual Symbol Overlay 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 Symbol Overlay and Transient. This package would not be possible without your efforts.