casual-avy

[[https://melpa.org/#/casual-avy][file:https://melpa.org/packages/casual-avy-badge.svg]]

• Casual Avy
  An opinionated [[https://github.com/magit/transient][Transient]]-based user interface for [[https://github.com/abo-abo/avy][Avy]], a GNU Emacs package for jumping to visible text using a char-based decision tree.

[[file:docs/images/casual-avy-screenshot.png]]

• Motivation
  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.

** Goals

• To provide a keyboard-driven menu UI for Avy.
• To provide casual access to the Avy command set.

** Non-Goals

• 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 Avys 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.

• Requirements
  Casual Avy requires usage of

• Emacs 29.1
• Avy 0.5.0
• Casual Lib 1.1.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

• Asks As Casual Avy is new, we are looking for early adopters! Your [[https://github.com/kickingvegas/casual-avy/discussions][feedback]] is welcome as it will likely impact Casual Avy's evolution, particularly with regards to UI.

• Install If installed via MELPA (pending) then add these lines to your Emacs initialization file with your binding of preference. #+begin_src elisp :lexical no (require 'casual-avy) ;; optional (keymap-global-set "M-g" #'casual-avy-tmenu) #+end_src

If you use use-package, here is the recipe for installing it. #+begin_src elisp :lexical no (use-package casual-avy :ensure t :bind ("M-g" . casual-avy-tmenu)) #+end_src

** A Note on Package Dependencies Casual Avy requires Casual Lib which in turn requires a recent installation of Transient 0.6.0+ from either [[https://elpa.gnu.org/packages/transient.html][ELPA]] or [[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is built-in to the Emacs release, the package manager package.el will /not/ update this package unless the customizable variable package-install-upgrade-built-in is set to t. Set this variable and proceed with installing Casual Avy. Alternately invoking package-install with a prefix (C-u) will temporarily coerce the update of the built-in package. (example: C-u M-x package-install casual-avy)

As Transient is closely tied to Magit, installing the latest version of Magit (via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or [[https://melpa.org/#/magit][MELPA]]) before installing Casual Avy can also pick up the latest version of Transient.

• Usage
  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. |

** Unicode Symbol Support 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 | |

** Imenu (index) Support The Emacs [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][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. #+begin_src elisp :lexical no (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) #+end_src

** Org Support 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.

• Common Menu Actions
  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.

• Development For users who wish to help contribute to Casual Avy or personally customize it for their own usage, please read the [[docs/developer.org][developer documentation]].

• Sponsorship If you enjoy using Casual Avy, consider making a modest financial contribution to help support its development and maintenance.

[[https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png]]

• See Also
  Casual Avy is part of a suite of user interfaces for different Emacs packages called [[https://github.com/kickingvegas/casual-suite][Casual Suite]].

Different interfaces include those for I-Search, Dired, Info, Calc, Bookmarks, RE-Builder, IBuffer, and others. Learn more about them today!

• Acknowledgments
  A heartfelt thanks to all the contributors to Avy and [[https://github.com/magit/transient][Transient]]. Casual Avy would not be possible without your efforts.