toggle it during completion with ~C-o m~.
* Customization
+:PROPERTIES:
+:CUSTOM_ID: customization
+:END:
** Faces
+:PROPERTIES:
+:CUSTOM_ID: faces
+:END:
- =ivy-current-match= ::
Highlights the currently selected candidate.
- =ivy-minibuffer-match-face-1= ::
(setq ivy-use-virtual-buffers t)
#+end_src
** Defcustoms
+:PROPERTIES:
+:CUSTOM_ID: defcustoms
+:END:
- User Option =ivy-count-format= ::
A string that describes how to show the number of candidates and
possibly the current candidate in the prompt.
you invoke the completion by mistake.
** Actions
+:PROPERTIES:
+:CUSTOM_ID: actions
+:END:
*** What are actions?
+:PROPERTIES:
+:CUSTOM_ID: what-are-actions?
+:END:
An action is a function of a single argument that gets called after
you select a candidate during completion. The selected candidate is
passed to this function as a string argument.
#+end_src
*** How can different actions be called?
+:PROPERTIES:
+:CUSTOM_ID: how-can-different-actions-be-called?
+:END:
- ~C-m~ (=ivy-done=) calls the current/default action.
- ~M-o~ (=ivy-dispatching-done=) selects among all actions, calls it
and exits.
and doesn't exit.
*** How can the action list be modified?
+:PROPERTIES:
+:CUSTOM_ID: how-can-the-action-list-be-modified?
+:END:
Currently, you can append any amount of your own actions to the
default list of actions. This can be done either for a specific
command, or for all commands at once.
equivalent to ~C-m~.
*** Example - add two actions to each command
+:PROPERTIES:
+:CUSTOM_ID: example---add-two-actions-to-each-command
+:END:
The first action inserts the current candidate into the Ivy window -
the window from which =ivy-read= was called.
~M-o y~ and =ivy-copy-to-buffer-action= with ~M-o i~.
**** How to undo adding the two actions
+:PROPERTIES:
+:CUSTOM_ID: how-to-undo-adding-the-two-actions
+:END:
=ivy-set-actions= simply modifies the internal dict with new data, so
you can set the extra actions list to =nil= by assigning =nil= value
to the =t= key:
#+end_src
**** How to add actions to a specific command
+:PROPERTIES:
+:CUSTOM_ID: how-to-add-actions-to-a-specific-command
+:END:
Use the command name as the key:
#+begin_src elisp
#+end_src
*** Example - define a new command with several actions
+:PROPERTIES:
+:CUSTOM_ID: example---define-a-new-command-with-several-actions
+:END:
#+begin_src elisp
(defun my-action-1 (x)
(message "action-1: %s" x))
action, the strings are used to describe it during the selection.
**** Testing out the above function with =ivy-occur=
+:PROPERTIES:
+:CUSTOM_ID: testing-out-the-above-function-with-ivy-occur
+:END:
To examine each action with each candidate in a key-efficient way, try:
- Call =my-command-with-3-actions=.
- Press ~j~ to move to the next candidate
- ...
** Packages
+:PROPERTIES:
+:CUSTOM_ID: packages
+:END:
- =org-mode= ::
With the most recent version, =org-mode= will obey
=completing-read-function= (which =ivy-mode= sets), so it should
#+end_src
* Commands
+:PROPERTIES:
+:CUSTOM_ID: commands
+:END:
** File Name Completion
+:PROPERTIES:
+:CUSTOM_ID: file-name-completion
+:END:
Since file name completion is so essential, ivy has a few extra
bindings that work here.
the file was opened. It also works well with TRAMP.
** Buffer Name Completion
+:PROPERTIES:
+:CUSTOM_ID: buffer-name-completion
+:END:
- User Option =ivy-use-virtual-buffers= ::
When non-nil, add =recentf-mode= and bookmarks to =ivy-switch-buffer=.
highlighted with the =ivy-virtual= face, and selecting them will
open the corresponding file.
** Counsel commands
+:PROPERTIES:
+:CUSTOM_ID: counsel-commands
+:END:
The main advantage of using =counsel-= functions over their basic
equivalents with =ivy-mode= enabled are the following:
=counsel-find-file-map=, instead of just customizing
=ivy-minibuffer-map= that applies to all completion sessions.
* API
+:PROPERTIES:
+:CUSTOM_ID: api
+:END:
The main (and only) entry point is =ivy-read= function. It has only
two required arguments and many optional arguments that you can pass
by key. Although the =:action= argument is optional, it's very
=ivy-occur= and =ivy-resume= will not be possible.
** Required arguments for =ivy-read=
+:PROPERTIES:
+:CUSTOM_ID: required-arguments-for-ivy-read
+:END:
- =prompt= ::
A format string normally ending in a colon and a space.
=all-completions=.
** Optional arguments for =ivy-read=
+:PROPERTIES:
+:CUSTOM_ID: optional-arguments-for-ivy-read
+:END:
- =predicate= ::
A function to filter the initial collection with, compatible with =all-completions=.
- =require-match= ::
=ivy-read=. This is useful in all kinds of customization
scenarios.
** Example - =counsel-describe-function=
+:PROPERTIES:
+:CUSTOM_ID: example---counsel-describe-function
+:END:
This is a typical example of a function with a non-async collection:
all the strings in the collection are known before the user does any
input.
examine =this-command=. But =this-command= would be modified if
another command called =counsel-describe-function=.
** Example - =counsel-locate=
+:PROPERTIES:
+:CUSTOM_ID: example---counsel-locate
+:END:
This is a typical example of a function with an async collection.
Since we can't pre-compute all the collection items valid for an empty
input and store them in the memory, the collection function is called