branch: externals/kind-icon
commit c69da894374fc1c3aeb8d4d748bbc1d25b758296
Author: JD Smith <93749+jdtsm...@users.noreply.github.com>
Commit: JD Smith <93749+jdtsm...@users.noreply.github.com>
Updated docs
---
README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 44 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 13bfdf2..fa80dad 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,66 @@
# kind-icon
Supplies a _kind_ icon or short-text prefix for emacs completion in the buffer.
-This emacs package adds icon or text-based completion prefixes based on the
`:company-kind` property many completion backends (such as lsp-mode) provide.
It works by creating a custom `affixation-function` for in-buffer completion,
if the backend does not already provide one. An affixation function specifies
a prefix and suffix to go along with completion candidate text.
+This emacs package adds icon or text-based completion prefixes based on the
`:company-kind` property many completion backends (such as lsp-mode) provide.
It works either as a "kind-formatter" function (e.g. for corfu) or by wrapping
the completion function for other completion UI's which handle the Emacs 28+
`affixation-function` completion property.
## Installation
-Get it from melpa (TBD), which should install `svg-lib` as well if necessary.
Enable in any buffer with completion using `kind-icon-mode`. E.g., to enable
for the completion UI [corfu](https://github.com/minad/corfu):
+Get it from melpa (TBD), which should install `svg-lib` as well if necessary.
Enable in any buffer with completion using `kind-icon-mode`. E.g., to enable
for the completion UI [corfu](https://github.com/minad/corfu), which has a
kind-formatter configuration:
```elisp
(use-package kind-icon ;package availability TBD
:ensure t
- :hook (corfu-mode . kind-icon-mode))
+ :after corfu
+ :custom
+ (kind-icon-default-face 'corfu-background)
+ (corfu-kind-formatter #'kind-icon-formatted))
+```
+
+The more generic approach of wrapping the `completion-in-region-function`
would look like:
+
+```elisp
+(use-package kind-icon
+ :ensure t
+ :config
+ (add-hook 'my-completion-ui-mode-hook
+ (lambda ()
+ (setq completion-in-region-function
+ (kind-icon-enhance-completion
+ completion-in-region-function)))))
```
## Configuration
+The configuration defaults should work fine, but kind-icon can be customized
to change the colors, preference of icons vs. short-text (or mixed) prefixes,
and more.
+
### Variables
-The defaults should normally work fine, but some of the important
configuration variables include:
+`kind-icon` has a few customization variables that allows you to configure its
appearance. Note that since the styled icons are cached, changes to the
mapping, font size, or other variables in an initialized buffer should be
followed by `M-x kind-icon-reset-cache` (or just restart Emacs).
+
+**Key configurations:**
+
+- `kind-icon-use-icons`: If non-nil (the default), prefer icons for prefix
badges. Otherwise, use text labels. Individual kind entries can also have
their icons disabled by removing the `:icon` property in the mapping (see
below).
+
+- `kind-icon-mapping`: This is the top level configuration mapping
`:company-kind` "types" like `'variable` and `'function`. Each item in this
list has the format `(sym short-text :keyword value ...)` where `sym` is the
kind (a symbol), and `short-text` is the abbreviated text to display (if icons
are not used). The rest of the list is a property list with optional keys
`:icon` and `:face`. The latter will be used to set the text foreground and
(possibly) background colors on the badg [...]
+
+- `kind-icon-default-face`: A face from which the icon background color will
be taken and blended with the `:face` foreground color in the mapping table to
create a custom background color. If not set, the frame default background
color will be used for this purpose. Similarly, the foreground color for this
face, if set, will be used if a `:face` foreground is missing from the mapping.
+
+- `kind-icon-blend-background`: If non-nil, computes a blend between a nominal
background color (from either the background property of
`kind-icon-default-face`, if set, or frame background color) and the foreground
:face. If `kind-icon-blend-background` is nil, the background is taken from
the :face background, `kind-icon-default-face`, or frame background-color.
+
+- `kind-icon-blend-frac`: The fractional blend between custom badge `:face`
foreground and background (see above) color to use as a custom background for
each badge. A value of 0.0 simply replicates the background color. Values
should likely stay below 0.3 or so.
+
+### Colors
+
+If you don't like the default colors used to go along with the icons, you can
customize the associated face, choose another, or build your own. You can also
change how the background color is displayed.
-- `kind-icon-use-icons`: If non-nil (the default), prefer icons for prefix
badges.
+**Foreground color:**
-- `kind-icon-mapping`: This is the top level configuration mapping
`:company-kind` "types" like `'variable` and `'function`. Each item in this
list has the format `(sym short-text :keyword value ...)` where `sym` is the
kind (a symbol), and `short-text` is the abbreviated text to display (if icons
are not used). The rest of the list is a property list with optional keys
`:icon` and `:face`. The latter will be used to set the text foreground and
background colors on the badge. The for [...]
+Icon foreground colors are matched by default to the default colors in
programming modes (variables, function names, etc.). This gives consistency
with in-buffer highlighting. These colors are taken from the `:face` mapping's
`:foreground` color. If no `:face` is set, the foreground is taken from
`kind-icon-default-face` foreground, or, as a backup the default frame
foreground.
-- `kind-icon-default-face`: A face from which background color will be taken
and blended with the `:face` foreground color in the mapping table to create a
custom background color. If not set, the frame default background color will
be used for this purpose. Similarly, the foreground color for this face, if
set, will be used if a `:face` foreground is missing from the mapping.
+**Background color:**
-- `kind-icon-blend-frac`: The fractional blend between custom badge
-`:face` foreground and background (see above) color to use as a custom
-background for each badge. A value of 0.0 simply replicates the
-background color. Values should likely stay below 0.3 or so.
+By default, `kind-icon` creates a blended background color that is a mix of a
bit of the foreground color and the background. Note that if your completion
UI uses a different background color from your normal buffer, you should
configure the face it uses in `kind-icon-default-face`. If you turn off
`kind-icon-blend-background`, `kind-icon` will use both the foreground _and_
background from the configured `:face` for each kind, allowing you to configure
arbitrary colors.
-### Icons and Colors
+### Icons
-Check the [material icon library](https://materialdesignicons.com) for the SVG
icons you can use. All you need is the name of the icon! Icon colors are
matched by default to the default colors in programming modes (variables,
function names, etc.). If you don't like the default colors used to go along
with the icons, you can customize the associated face, or build your own. See
`M-x list-faces-display`. You can `M-x customize-group kind-icon` to update
the mapping.
+Check the [material icon library](https://materialdesignicons.com) for the SVG
icons you can use. All you need to "use" an icon is its name! Note that on
first use, icons are auto-downloaded by `svg-lib`, so you'll need a network
connection. After that they are cached locally.
