Image overlay: what does `defimage` do and how to make it work as expected?

Question

After solving the problem with appropriate height of placement of the as overlay inserted image ( see here "Image overlay: how to change the relative image insert position within the buffer text?" ):

I wanted to improve the code and replaced setq img (create-image ... with defimage img ... but it does not work as expected. If I use the img symbol from defimage I am not getting the image displayed.

The documentation, if I understand it right, tells me that defimage sets the symbols value to image description which is the same as what it tells to be returned by create-image, but somehow it seems that the effect when using it is another one.

What does defimage actually do and how to make the symbol it sets to work as an image?

Below code you can copy/paste to the Scratch buffer and run it to see yourself that changing the variable name representing the image to this one set by defimage results in not displaying the overlay image anymore (see ;; <<<### remove '-var' here in the below code how to activate use of the not working symbol from defimage).

;; =====================================================================
;;    Replace special Unicode character "ä" with an Emacs logo image
;; ---------------------------------------------------------------------
;; ______________________________
;; Emacs ämacs ämacs ämacs Emacs
;; ------------------------------
;; ä y^T ä Q^g ä Ö_É ä j_ą ä Xy
;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(defvar regex-UnicodeEmacsLogoChar "ä")
(setq-default case-fold-search nil);; nil -> sensitive  t -> ignore case
(setq imgFileName "emacs_logo-round_icon_16x16.png")
;; ---------------------------------
(setq max-image-size 128);; load images up to size of 128x128 pixel
;;   'max-image-size' <- variable <- src/image.c (default 10.0) 
;;       ^-- if float -> % of frame width/height 
;;       ^-- if int   -> width/height pixel
;;       ^-- if nil   -> no size limit
(defvar img-emacsLogo-16x16-var 
  (create-image imgFileName  
  ;  v-- TYPE  v--DATA-P : infer type from ".png" : no img data symbol 
    nil       nil    
    :transform-smoothing t 
    :ascent  'center ;; 'center or value in range 0-100 (%)
    :scale   1.0     ;; -> scales :width/height (keeps max-width/height)
    ;; :pointer 'hourglasss ;; text or nil ("I"-like shape) arrow vdrag
    )
);defvar img-emacsLogo-16x16-var
;; ---
(defimage img-emacsLogo-16x16 ((
    :type png ;; ( pbm xbm xpm gif jpeg tiff png svg ) or imagemagick  
    :file imgFileName ;; looks for the file in 'image-load-path'
    ;; :file XOR :data <- a string with image data
    :transform-smoothing t 
    :ascent center ;; symb. 'center or 0-100(% height) default 50
    ;; :margin     ;; around -> int (horiz . vert) in pixels (0 . 0)  
    ;; :relief     ;; shadow in pixel 0, minus -> pressed button look
    ;; :width      ;; scale the image to given values preserving
    ;; :height     ;; ... the aspect ratio if it is necessary to 
    ;; :max-width  ;; ... limit its size to given values of maximal
    ;; :max-height ;; ... width and height
    :scale   1.0   ;; -> scales :width/height (keeps max-width/height)
    ;; :rotation   ;; 90,180,270 deg or any value if imagemagick type
    ;; :index      ;; frame See Multi-Frame images
    ;; :conversion ;; algorithm: laplace emboss disabled ...
    ;;          (edge-detection :matrix matrix :color-adjust adjust)
    ;; :mask       ;; mask (see: Image-Descriptors.html for details)
    :pointer hourglasss ;; text or nil ("I"-like shape) arrow vdrag
    ;;                      modeline hand hdrag nhdrag hourglasss
    ;; :map ;; alist -> (area id plist) see Image-Descriptors.html 
    ;;      define mouse pointer interaction areas and responses
    ;;      avail.: rect, circle, poly
)));defimage img-emacsLogo-16x16
;; ---
(defun font-lock-add-keywords_UnicodeEmacsLogoChar (&optional limit)
  (when (re-search-forward  regex-UnicodeEmacsLogoChar  limit    t )
    ;;   ^-- start at point  regex_string --^          BOUND  NO-ERROR  COUNT=1
    (setq  beg  (match-beginning  0) ;; 0 -> which regex capt. group? 
           end  (match-end        0)
           str  (match-string     0)
    );set the above values first then create an overlay
    (setq        ov (make-overlay  beg end))
    (overlay-put ov 'display       img-emacsLogo-16x16-var) ;; <<<### remove '-var' here
    (overlay-put ov 'face          'default)
    (overlay-put ov 'evaporate     1   )
    (message "nextOverlay for \"%s\" beg %s  end %s "  str beg end)
  )
)
(font-lock-add-keywords 
    nil ;; 'emacs-lisp-mode ;; MODE: nil -> curr. buffer ( lisp-mode emacs-lisp-mode python-mode ... )  
    ;; KEYWORDS -> here list with keyword MATCHER function:
    '((font-lock-add-keywords_UnicodeEmacsLogoChar (0 'font-lock-keyword-face t)))
    t ;; HOW
)

Here the logo image you see in the upper image.

Be warned that there are many other issues related to the code above which need to be fixed:

• It works only from the cursor position down "on demand"
• If I specify only the image name setting appropriate image search path it does not load the image (use a full path image name if the code above does not show the overlay with the image).
• It generates probably unnecessary a huge amount of overlays overlying present ones (does it?) on each redraw of the screen
• ... and so on ... but ... one question per question so let's fix the issue with defimage img first (which is in my eyes much cleaner syntax compared to (setq img create-image).

By the way: you can use the code above as a kind of documentation. It puts together the essence of all the information in the documentation and demonstrates how it works (or doesn't).

---

% UPDATE: I have changed the code back to what I had started with seeing that it does not work. Now the code is updated with the in the comments and the answer suggested changes. Sorry for the inconvenience.

%% UPDATE: I have changed 'ascent to ascent and 'hourglass to hourglass as defimage did else not work in other context provided in comments and the answer, but the problem with not displayed image is still not solved by these changes.

Answer 1

[Expanding the comment]

The doc string of defimage says: All specifications must at least contain the properties ‘:type TYPE’ and either ‘:file FILE’ or ‘:data DATA’, but :type is commented out above. You are also missing a set of parens: it should be:

(defimage img-emacsLogo-16x16 ((:type png
                                :file imgFileName         
                                :transform-smoothing t 
                                :ascent 'center
                                :scale   1.0
                                :pointer 'hourglass)))

The SPECS parameter is a list of property lists: Each image specification in SPECS is a property list.

Untested.

EDIT: The testing harness that you have is much too heavy. You should start with something lighter. E.g.

(defimage img-emacsLogo-16x16 ((
    :type png
    :file "/tmp/emacs-logo.png"
    :transform-smoothing t)))


(insert-image img-emacsLogo-16x16)

works for me. But when I add :ascent 'center to the property list, it does not work any more. That's because of the quote: :ascent center works. I haven't checked, but that's probably because defimage is a macro that does not evaluate the SPECS argument.