Function: treemacs-create-icon

treemacs-create-icon is a macro defined in treemacs-icons.el.

Signature

(treemacs-create-icon &key FILE ICON (FALLBACK " ") ICONS-DIR EXTENSIONS)

Documentation

Create an icon for the current theme.

- FILE is a file path relative to the icon directory of the current theme.
- ICON is a string of an already created icon. Mutually exclusive with FILE.
- FALLBACK is the fallback string for situations where png images are
  unavailable. Can be set to same-as-icon to use the same value as ICON.
- ICONS-DIR can optionally be used to overwrite the path used to find icons.
  Normally the current theme's icon-path is used, but it may be convenient to
  use another when calling treemacs-modify-theme.
- EXTENSIONS is a list of file extensions the icon should be used for.
  Note that treemacs has a loose understanding of what constitutes an extension:
  it's either the text past the last period or the entire filename, so names
  like ".gitignore" and "Makefile" can be matched as well.
  An extension may also be a symbol instead of a string. In this case treemacs
  will also create a variable named "treemacs-icon-%s" making it universally
  accessible.

Source Code

;; Defined in ~/.emacs.d/elpa/treemacs-20251226.1307/treemacs-icons.el
(cl-defmacro treemacs-create-icon (&key file icon (fallback " ") icons-dir extensions)
  "Create an icon for the current theme.
- FILE is a file path relative to the icon directory of the current theme.
- ICON is a string of an already created icon.  Mutually exclusive with FILE.
- FALLBACK is the fallback string for situations where png images are
  unavailable.  Can be set to `same-as-icon' to use the same value as ICON.
- ICONS-DIR can optionally be used to overwrite the path used to find icons.
  Normally the current theme's icon-path is used, but it may be convenient to
  use another when calling `treemacs-modify-theme'.
- EXTENSIONS is a list of file extensions the icon should be used for.
  Note that treemacs has a loose understanding of what constitutes an extension:
  it's either the text past the last period or the entire filename, so names
  like \".gitignore\" and \"Makefile\" can be matched as well.
  An extension may also be a symbol instead of a string.  In this case treemacs
  will also create a variable named \"treemacs-icon-%s\" making it universally
  accessible."
  (treemacs-static-assert (or (null icon) (null file))
    "FILE and ICON arguments are mutually exclusive")
  (when (and (consp extensions) (or (symbolp (car extensions))
                                    (stringp (car extensions))))
    (setf extensions `(quote (,@extensions))))
  `(let* ((xs (--map (if (stringp it) (downcase it) it) ,extensions))
          (fallback   ,(if (equal fallback (quote 'same-as-icon))
                           icon
                         fallback))
          (icons-dir  ,(if icons-dir icons-dir `(treemacs-theme->path treemacs--current-theme)))
          (icon-path  ,(if file `(treemacs-join-path icons-dir ,file) nil))
          (icon-pair  ,(if file `(treemacs--create-icon-strings icon-path fallback)
                         `(cons ,(treemacs--splice-icon icon) fallback)))
          (gui-icons  (treemacs-theme->gui-icons treemacs--current-theme))
          (tui-icons  (treemacs-theme->tui-icons treemacs--current-theme))
          (gui-icon   (car icon-pair))
          (tui-icon   (cdr icon-pair)))
     ,(unless file
        `(progn
           (ignore icon-path)
           (ignore icons-dir)))
     ;; prefer to have icons as empty strings with a display property for compatibility
     ;; in e.g. dired, where an actual text icon would break `dired-goto-file-1'
     (unless (get-text-property 0 'display gui-icon)
       (setf gui-icon (propertize " " 'display gui-icon)))
     (dolist (ext xs)
       (when (symbolp ext)
         (-let [symbol (intern (format "treemacs-icon-%s" ext))]
           (add-to-list 'treemacs--icon-symbols ext)
           (set symbol nil))))
     (--each xs
       ;; NOTE: Disable creation of GUI svg icons without getting in the way of the rest
       ;; of the icon creation process. This is good enough a workaround for Emacs versions
       ;; that don't support svg images for as long as svg icons are a minority.
       (unless (and ,file
                    (not (image-type-available-p 'svg))
                    (string= (treemacs--file-extension ,file) "svg"))
         (ht-set! gui-icons it gui-icon))
       (ht-set! tui-icons it tui-icon))))