Re: Auto-resizing of images in image-mode

[Juri Linkov]

>>   ** Image mode
>>
>>   *** 'image-mode' now on resizing the window automatically resizes the
>>       image to fit in the new dimensions of the window.
>
> Something is wrong with that sentence ;-)
>
> Also, please try to make the first line a complete sentence, so that
> reading NEWS in Outline mode could be easier.  And I think we should
> also say that the image will resize upon first display and whenever
> the window's dimensions change.  This is implied by the text you
> wrote, but it could be interpreted to mean the size is done once only,
> when the file is visited.

Please see in commit 4df8a61117 if everything is correct
according to your comments.

>> I propose to create a separate node "Images" or "Image mode".
>
> Fine with me, but then let's describe in that node much more
> image-related features than we have now.  The Image mode is nowadays
> very feature-rich, and most of those features are not in the manual.

Yes, all its features will be described in the node that I added in the
same commit.

>> >   . Moreover, the manual makes a point of describing what cursor
>> >     motion commands do when an image is displayed that is larger than
>> >     the window, but this can no longer be seen when visiting an image
>> >     file, because it is always smaller than the window.
>
>                                                      If the displayed
>   image is wider or taller than the frame, the usual point motion keys
>   (‘C-f’, ‘C-p’, and so forth) cause different parts of the image to be
>   displayed.

Oh, I looked for the word "larger" but missed its hyponyms
"wider" and "taller", sorry.

>> It's impossible to view an image in its original size even without this 
>> feature.
>> A few years ago image-mode was changed to resize the image to fit in the
>> window when visiting an image file.
>
> Maybe so, but Emacs 26 still shows the images in their original size,
> AFAICT.  So this is new in Emacs 27, at least for me.  I think that's
> because previously the automatic resizing worked only in Emacs built
> with ImageMagick, whereas in Emacs 27 we can resize natively.  I build
> my Emacs without ImageMagick, and I wonder how many others do, due to
> ImageMagick's instability.

I'm not sure how it could be new in Emacs 27 because
image-transform-resize was added in year 2014.

> Isn't it possible to have an option or a special command to visit an
> image without the automatic resizing?  E.g., "C-u C-x C-f" could do
> that for image files.

Better would be to have two ways to view an image without the
automatic resizing:

1. an option to disable automatic resizing permanently.
   There is already a defvar 'image-transform-resize'
   but its 'nil' value doesn't disable automatic resizing,
   so a new defcustom is needed.  Please see it below.

2. an easy to type key in image-mode-map to toggle automatic resizing.
   Some programs use 'F' key for "Best Fit" but 'F' is already used
   in image-mode-map for image-goto-frame.

Also there are no keys for image-transform-fit-to-width,
image-transform-fit-to-height and image-transform-reset.
I thought about using a prefix key 'f', so using 'f w' to fit width,
but 'f' is already taken too.

But anyway their docstrings say:

  This command has no effect unless Emacs is compiled with
  ImageMagick support.

So these commands should be fixed to work without ImageMagick.

>> >   . The time interval after which the idle timer resizes the image is
>> >     fixed and cannot be customized.  The 1 sec interval looks too long
>> >     to me, FWIW, but if it were customizable, my personal preferences
>> >     would not have mattered.
>>
>> A new option could be added with a name like image-transform-resize-delay.
>
> Let's do that on the emacs-27 branch, please.

Then three new defcustoms like these could be added:

(defcustom image-resize t
  "Non-nil to resize the image upon first display.
Its value should be one of the following:
 - nil, meaning no resizing.
 - t, meaning to fit the image to the window height and width.
 - `fit-height', meaning to fit the image to the window height.
 - `fit-width', meaning to fit the image to the window width.
 - A number, which is a scale factor (the default size is 1)."
  :type '(choice (const :tag "No resizing" nil)
                 (other :tag "Fit height and width" t)
                 (const :tag "Fit height" fit-height)
                 (const :tag "Fit width" fit-width)
                 (number :tag "Scale factor" 1))
  :version "27.1"
  :group 'image)

(defcustom image-window-resize t
  "Non-nil to resize the image whenever the window's dimensions change."
  :type 'boolean
  :version "27.1"
  :group 'image)

(defcustom image-window-resize-delay 1
  "Number of seconds to wait before resizing according to 
`image-window-resize'."
  :type 'integer
  :version "27.1"
  :group 'image)

If this looks good, I could send a complete patch.