Elisp and overlay, how to show an image

Elisp and overlay, how to show an image

[Sébastien Gendre]

Hello,

I am trying to show an image on the top of a buffer, before the first
line of text, and put a small margin at the bottom of the image.


I have read the Overlay manual [1] and the source code of the function
`org-display-inline-images`, but I have difficulties to understand how
to use overlay beginning and end parameters.


Here is the source code my first try:


    ;; Create an overlay at the first char of the buffer
    (setq ov1 (make-overlay 1 1))
    
    ;; Create the image from a file
    (setq my_image (create-image "~/Path/to/my/image.jpg"))
    
    ;; Put a new line, to avoid aving the image replacing the first char
    (overlay-put ov1 'before-string "\n")
    
    ;; Put the image on the overlay
    (overlay-put ov1 'display my_image)


When I evaluate this code, for example on the *scratch* buffer, I got a
new line before the first buffer char, but the image do not display.

Should I need to create, on the overlay, an empty space big enough to
put the image in it ? Or did I miss something on the manual ?



Best regards.


[1] https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html

Re: Elisp and overlay, how to show an image

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1081 bytes --]

On Sat, Jul 06, 2024 at 11:12:23PM +0200, Sébastien Gendre wrote:
> Hello,
> 
> I am trying to show an image on the top of a buffer, before the first
> line of text, and put a small margin at the bottom of the image.
> 
> 
> I have read the Overlay manual [1] and the source code of the function
> `org-display-inline-images`, but I have difficulties to understand how
> to use overlay beginning and end parameters.
> 
> 
> Here is the source code my first try:
> 
> 
>     ;; Create an overlay at the first char of the buffer
>     (setq ov1 (make-overlay 1 1))

I think you have to give the overlay some width. Possibly you'll
have to insert some text (one char will be enough) to slap the
overlay on.

>     
>     ;; Create the image from a file
>     (setq my_image (create-image "~/Path/to/my/image.jpg"))
>     
>     ;; Put a new line, to avoid aving the image replacing the first char
>     (overlay-put ov1 'before-string "\n")

I'm not quite sure the before-string is displayed when the overlay has
a 'display property.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Elisp and overlay, how to show an image

[Stefan Monnier via Users list for the GNU Emacs text editor]

> Here is the source code my first try:
>
>     ;; Create an overlay at the first char of the buffer
>     (setq ov1 (make-overlay 1 1))

Please use (point-min) rather than 1.

>     ;; Create the image from a file
>     (setq my_image (create-image "~/Path/to/my/image.jpg"))
>     
>     ;; Put a new line, to avoid aving the image replacing the first char
>     (overlay-put ov1 'before-string "\n")
>     
>     ;; Put the image on the overlay
>     (overlay-put ov1 'display my_image)

As Tomas points out, the `display` property is obeyed only if it covers
characters.  The usual way to "insert" an image without disrupting the
content of the buffer (e.g. in `put-image`) is to put the image (with
`display` property) on a *string* and then put that string in the
`before-string` (or `after-string`) property of an overlay.

    (let ((ol (put-image (create-image "~/Path/to/my/image.jpg")
                         (point-min))))
      (overlay-put ol 'after-string "\n"))


- Stefan

Re: Elisp and overlay, how to show an image

[Sébastien Gendre]

Stefan Monnier via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:
> As Tomas points out, the `display` property is obeyed only if it covers
> characters.  The usual way to "insert" an image without disrupting the
> content of the buffer (e.g. in `put-image`) is to put the image (with
> `display` property) on a *string* and then put that string in the
> `before-string` (or `after-string`) property of an overlay.
>
>     (let ((ol (put-image (create-image "~/Path/to/my/image.jpg")
>                          (point-min))))
>       (overlay-put ol 'after-string "\n"))
>
>
> - Stefan
<#secure method=pgpmime mode=sign>

Thank you, to Tomas and you, for your replies. It help me a lot.

I didn't know that (put-image) will return the overlay it created.

Is there a way to set a bottom margin to the added overlay, or to the
image, like with CSS on a web page ? Or do I need to add more "\n" with
(overlay-put) ?


I need to found a way to modify the way the image is shown. Controlling
the zoom, on which part it's centered and how the image is cut. I will
read more carefully the section "41.17 Images" of the elisp manual.
Until now, I was started by the overlays section of the manual. 

Re: Elisp and overlay, how to show an image

[Stefan Monnier via Users list for the GNU Emacs text editor]

> I didn't know that (put-image) will return the overlay it created.

Indeed, I see that the docstring doesn't mention it, although the code
does it quite explicitly (i.e. not by accident).  Seems like a docstring bug.

> Is there a way to set a bottom margin to the added overlay, or to the
> image, like with CSS on a web page ? Or do I need to add more "\n" with
> (overlay-put) ?

I'm not very knowledgeable about images, to be honest.  If that doesn't
offer any useful options, you should be able to "similate" a bottom
margin by putting a `face` property on the "\n" string with an
appropriate `:height`, something like

    (overlay-put ol 'affer-string
                    (propertize "\n" 'face '(:height 2.5)))


- Stefan

Re: Elisp and overlay, how to show an image

[Michael Heerdegen via Users list for the GNU Emacs text editor]

Sébastien Gendre <seb@k-7.ch> writes:

> Is there a way to set a bottom margin to the added overlay, or to the
> image, like with CSS on a web page ? Or do I need to add more "\n" with
> (overlay-put) ?
>
> I need to found a way to modify the way the image is shown. Controlling
> the zoom, on which part it's centered and how the image is cut. I will
> read more carefully the section "41.17 Images" of the elisp manual.
> Until now, I was started by the overlays section of the manual. 

Have a look at (info "(elisp) Image Descriptors") - in particular,
:scale, :ascent, :margin.  AFAIU you are allowed to manipulate the data
structure of an already created image "object".  But note that not every
image type supports or implements all descriptors.


Michael.