Customizing Flymake error types

To customize the appearance of error types, the user must set properties on the symbols associated with each diagnostic type.

The three standard diagnostic keyword symbols – :error, :warning and :note – have pre-configured appearances. However a backend may define more (see Backend functions).

The following properties can be set:

• flymake-bitmap, an image displayed in the fringe according to flymake-fringe-indicator-position. The value actually follows the syntax of flymake-error-bitmap (see Customizable variables). It is overridden by any before-string overlay property.

• flymake-margin-string, a string displayed in the margin according to flymake-margin-indicator-position. The value actually follows the syntax of flymake-margin-indicators-string (see Customizable variables). It is overridden by any before-string overlay property.

• flymake-overlay-control, an alist ((OVPROP . VALUE) ...) of further properties used to affect the appearance of Flymake annotations. With the exception of category and evaporate, these properties are applied directly to the created overlay (see Overlay Properties in The Emacs Lisp Reference Manual).

  As an example, here’s how to make diagnostics of the type :note stand out more prominently:

  (push '(face . highlight) (get :note 'flymake-overlay-control))

  If you push another alist entry in front, it overrides the previous one. So this effectively removes the face from :note diagnostics:

  (push '(face . nil) (get :note 'flymake-overlay-control))

  To restore the original look for :note types, empty or remove its flymake-overlay-control property:

  (put :note 'flymake-overlay-control '())

• severity is a non-negative integer specifying the diagnostic’s severity. The higher the value, the more serious is the error. If the overlay property priority is not specified in flymake-overlay-control, flymake-severity is used to set it and help sort overlapping overlays.

• flymake-type-name is a string used to succinctly name the error type, in case the name of the symbol associated with it is very long.

• flymake-category is a symbol whose property list is considered the default for missing values of any other properties.

• mode-line-face is a face specifier controlling the appearance of the indicator of this type of diagnostic in the mode line.

• echo-face is a face specifier controlling the appearance of the summarized description of this diagnostic when reading diagnostic messages (see Finding diagnostics).

Three default diagnostic types are predefined: :error, :warning, and :note. By default, each one of them has a flymake-category property whose value is, respectively, the category symbol flymake-error, flymake-warning and flymake-note.

These category symbols’ plist is where the values of customizable variables and faces (such as flymake-error-bitmap) are found. Thus, if you change their plists, Flymake may stop honoring these user customizations.

The flymake-category special property is especially useful for backends which create diagnostics objects with non-default types that differ from an existing type by only a few properties (see Flymake utility functions).

As an example, consider configuring a new diagnostic type :low-priority-note that behaves much like :note, but without an overlay face.

(put :low-priority-note 'flymake-overlay-control '((face . nil)))
(put :low-priority-note 'flymake-category 'flymake-note)

As you might have guessed, Flymake’s annotations are implemented as overlays (see Overlays in The Emacs Lisp Reference Manual). Along with the properties that you specify for the specific type of diagnostic, Flymake adds the property flymake-diagnostic to these overlays, and sets it to the object that the backend created with flymake-make-diagnostic.

Since overlays also support arbitrary keymaps, you can use this along with the functions flymake-diagnostics and flymake-diagnostic-text (see Flymake utility functions) to create interactive annotations, such as in the following example of binding a mouse-3 event (middle mouse button click) to an Internet search for the text of a :warning or :error.

(defun my-search-for-message (event)
  (interactive "e")
  (let* ((diags (flymake-diagnostics (posn-point (event-start event))))
         (topmost-diag (car diags)))
    (eww-browse-url
       (concat
        "https://duckduckgo.com/?q="
        (replace-regexp-in-string
          " " "+" (flymake-diagnostic-text topmost-diag)))
       t)))

(dolist (type '(:warning :error))
  (push '(mouse-face . highlight) (get type 'flymake-overlay-control))
  (push `(keymap . ,(let ((map (make-sparse-keymap)))
                      (define-key map [mouse-2]
                        'my-search-for-message)
                      map))
        (get type 'flymake-overlay-control)))