Improve documentation of image-related commands
* lisp/image.el (image-map): Make it inherit from 'image-slice-map' instead of repeating the bindings. * doc/emacs/files.texi (Image Mode): Document the key bindings set by 'insert-image'. Add indexing. * doc/lispref/display.texi (Showing Images): Make the description of user commands more concise. Add index entries and cross-reference to the Emacs manual. * etc/NEWS: Rearrange entries relevant to image commands.
This commit is contained in:
Eli Zaretskii
parent
6a2863ca01
commit
96714c106b
4 changed files with 135 additions and 44 deletions
|
|
@ -2281,10 +2281,15 @@ behavior by using the options @code{image-auto-resize} and
|
|||
@code{image-auto-resize-on-window-resize}.
|
||||
|
||||
@findex image-transform-fit-to-window
|
||||
@kindex s w (Image mode)
|
||||
@findex image-transform-set-percent
|
||||
@kindex s p (Image mode)
|
||||
@findex image-transform-set-scale
|
||||
@kindex s s (Image mode)
|
||||
@findex image-transform-reset-to-initial
|
||||
@kindex s 0 (Image mode)
|
||||
@findex image-transform-reset-to-original
|
||||
@kindex s o (Image mode)
|
||||
To resize the image manually you can use the command
|
||||
@code{image-transform-fit-to-window} bound to @kbd{s w} that fits the
|
||||
image to both the window height and width. To scale the image to a
|
||||
|
|
@ -2345,6 +2350,94 @@ frames at once. You can go to a specific frame with @kbd{F}
|
|||
(@code{image-reverse-speed}) reverses it. The command @kbd{a 0}
|
||||
(@code{image-reset-speed}) resets the speed to the original value.
|
||||
|
||||
In addition to the above key bindings, which are specific to Image
|
||||
mode, images shown in any Emacs buffer have special key bindings when
|
||||
point is at or inside the image:
|
||||
|
||||
@table @kbd
|
||||
@cindex resize images
|
||||
@cindex image resize
|
||||
@findex image-increase-size
|
||||
@kindex i + (Image mode)
|
||||
@item i +
|
||||
Increase the image size (@code{image-increase-size}) by 20%. Prefix
|
||||
numeric argument controls the increment; the value of @var{n} means to
|
||||
multiply the size by the factor of @w{@code{1 + @var{n} / 10}}, so
|
||||
@w{@kbd{C-u 5 i +}} means to increase the size by 50%.
|
||||
|
||||
@findex image-decrease-size
|
||||
@kindex i - (Image mode)
|
||||
@item i -
|
||||
Decrease the image size (@code{image-increase-size}) by 20%. Prefix
|
||||
numeric argument controls the decrement; the value of @var{n} means to
|
||||
multiply the size by the factor of @w{@code{1 - @var{n} / 10}}, so
|
||||
@w{@kbd{C-u 3 i -}} means to decrease the size by 30%.
|
||||
|
||||
@cindex rotating images
|
||||
@cindex image rotation
|
||||
@findex image-rotate
|
||||
@kindex i r (Image mode)
|
||||
@item i r
|
||||
Rotate the image by 90 degrees clockwise (@code{image-rotate}).
|
||||
With the prefix argument, rotate by 90 degrees counter-clockwise instead.
|
||||
Note that this command is not available for sliced images.
|
||||
|
||||
@findex image-flip-horizontally
|
||||
@kindex i h (Image mode)
|
||||
@item i h
|
||||
Flip the image horizontally (@code{image-flip-horizontally}). This
|
||||
presents the image as if reflected in a vertical mirror.
|
||||
Note that this command is not available for sliced images.
|
||||
|
||||
@findex image-flip-vertically
|
||||
@kindex i v (Image mode)
|
||||
@item i v
|
||||
Flip the image vertically (@code{image-flip-vertically}). This
|
||||
presents the image as if reflected in a horizontal mirror.
|
||||
Note that this command is not available for sliced images.
|
||||
|
||||
@findex image-save
|
||||
@kindex i o (Image mode)
|
||||
@item i o
|
||||
Save the image to a file (@code{image-save}). This command prompts
|
||||
you for the name of the file to save the image.
|
||||
|
||||
@cindex cropping images
|
||||
@vindex image-crop-crop-command
|
||||
@findex image-crop
|
||||
@kindex i c (Image mode)
|
||||
@item i c
|
||||
Crop the image (@code{image-crop}). This command is available only if
|
||||
your system has an external program installed that can be used for
|
||||
cropping and cutting of images; the user option
|
||||
@code{image-crop-crop-command} determines what program to use, and
|
||||
defaults to the ImageMagick's @command{convert} program. The command
|
||||
displays the image with a rectangular frame superimposed on it, and
|
||||
lets you use the mouse to move and resize the frame. Type @kbd{m} to
|
||||
cause mouse movements to move the frame instead of resizing it; type
|
||||
@kbd{s} to move a square frame instead. When you are satisfied with
|
||||
the position and size of the cropping frame, type @kbd{@key{RET}} to
|
||||
actually crop the part under the frame; or type @kbd{q} to exit
|
||||
without cropping. You can then save the cropped image using @w{@kbd{i
|
||||
o}} or @w{@kbd{M-x image-save}}.
|
||||
|
||||
@findex image-cut
|
||||
@kindex i x (Image mode)
|
||||
@vindex image-cut-color
|
||||
@vindex image-crop-cut-command
|
||||
@item i x
|
||||
Cut a rectangle from the image (@code{image-cut}). This works the
|
||||
same as @code{image-crop} (and also requires an external program,
|
||||
defined by the variable @code{image-crop-cut-command}, to perform the
|
||||
image cut), but instead of cropping the image, it removes the part
|
||||
inside the frame and fills that part with the color specified by
|
||||
@code{image-cut-color}. With prefix argument, the command prompts for
|
||||
the color to use.
|
||||
@end table
|
||||
|
||||
The size and rotation commands are ``repeating'', which means that you
|
||||
can continue adjusting the image without using the @kbd{i} prefix.
|
||||
|
||||
@cindex ImageMagick support
|
||||
@vindex imagemagick-enabled-types
|
||||
@vindex imagemagick-types-inhibit
|
||||
|
|
|
|||
|
|
@ -6876,7 +6876,7 @@ This function puts image @var{image} in front of @var{pos} in the
|
|||
current buffer. The argument @var{pos} should be an integer or a
|
||||
marker. It specifies the buffer position where the image should appear.
|
||||
The argument @var{string} specifies the text that should hold the image
|
||||
as an alternative to the default.
|
||||
as an alternative to the default @samp{x}.
|
||||
|
||||
The argument @var{image} must be an image descriptor, perhaps returned
|
||||
by @code{create-image} or stored by @code{defimage}.
|
||||
|
|
@ -6889,7 +6889,7 @@ buffer's text.
|
|||
|
||||
Internally, this function creates an overlay, and gives it a
|
||||
@code{before-string} property containing text that has a @code{display}
|
||||
property whose value is the image. (Whew!)
|
||||
property whose value is the image. (Whew! that was a mouthful@dots{})
|
||||
@end defun
|
||||
|
||||
@defun remove-images start end &optional buffer
|
||||
|
|
@ -6936,41 +6936,47 @@ This function returns @code{t} if point is on an image, and @code{nil}
|
|||
otherwise.
|
||||
@end defun
|
||||
|
||||
@cindex operations on images
|
||||
Images inserted with the insertion functions above also get a local
|
||||
keymap installed in the text properties (or overlays) that span the
|
||||
displayed image. This keymap defines the following commands:
|
||||
|
||||
@table @kbd
|
||||
@findex image-increase-size
|
||||
@item i +
|
||||
Increase the image size (@code{image-increase-size}). A prefix value
|
||||
of @samp{4} means to increase the size by 40%. The default is 20%.
|
||||
Increase the image size (@code{image-increase-size})
|
||||
|
||||
@findex image-decrease-size
|
||||
@item i -
|
||||
Decrease the image size (@code{image-increase-size}). A prefix value
|
||||
of @samp{4} means to decrease the size by 40%. The default is 20%.
|
||||
Decrease the image size (@code{image-decrease-size}).
|
||||
|
||||
@findex image-rotate
|
||||
@item i r
|
||||
Rotate the image by 90 degrees clockwise (@code{image-rotate}).
|
||||
A prefix means to rotate by 90 degrees counter-clockwise instead.
|
||||
Rotate the image (@code{image-rotate}).
|
||||
|
||||
@findex image-flip-horizontally
|
||||
@item i h
|
||||
Flip the image horizontally (@code{image-flip-horizontally}).
|
||||
|
||||
@findex image-flip-vertically
|
||||
@item i v
|
||||
Flip the image vertically (@code{image-flip-vertically}).
|
||||
|
||||
@findex image-save
|
||||
@item i o
|
||||
Save the image to a file (@code{image-save}).
|
||||
|
||||
@findex image-crop
|
||||
@item i c
|
||||
Crop the image interactively (@code{image-crop}).
|
||||
Interactively crop the image (@code{image-crop}).
|
||||
|
||||
@findex image-cut
|
||||
@item i x
|
||||
Cut a rectangle from the image interactively (@code{image-cut}).
|
||||
Interactively cut a rectangle from the image (@code{image-cut}).
|
||||
@end table
|
||||
|
||||
The size and rotation commands are ``repeating'', which means that you
|
||||
can continue adjusting the image without using the @kbd{i} prefix.
|
||||
@xref{Image Mode,,, emacs, The GNU Emacs Manual}, for more details
|
||||
about these image-specific key bindings.
|
||||
|
||||
@node Multi-Frame Images
|
||||
@subsection Multi-Frame Images
|
||||
|
|
|
|||
32
etc/NEWS
32
etc/NEWS
|
|
@ -222,9 +222,9 @@ In previous Emacs versions, images have had the '+', '-' and 'r' keys
|
|||
bound when point is over an image. In Emacs 29.1, additional commands
|
||||
were added, and this made it more likely that users would trigger the
|
||||
image commands by mistake. To avoid this, all image commands have
|
||||
moved to the 'i' keymap, so '+' is now 'i +', '-' is now 'i -', and
|
||||
'r' is now 'i r'. In addition, these commands are now repeating, so
|
||||
you can rotate an image twice by saying 'i r r', for instance.
|
||||
moved to the 'i' prefix keymap, so '+' is now 'i +', '-' is now 'i -',
|
||||
and 'r' is now 'i r'. In addition, these commands are now repeating,
|
||||
so, for example, you can rotate an image twice by typing 'i r r'.
|
||||
|
||||
+++
|
||||
** Emacs now picks the correct coding-system for X input methods.
|
||||
|
|
@ -2628,11 +2628,6 @@ This controls whether or not to show a message when opening certain
|
|||
image formats saying how to edit it as text. The default is to show
|
||||
this message for SVG and XPM.
|
||||
|
||||
+++
|
||||
*** New commands: 'image-flip-horizontally' and 'image-flip-vertically'.
|
||||
These commands horizontally and vertically flip the image under point,
|
||||
and are bound to 'i h' and 'i v', respectively.
|
||||
|
||||
+++
|
||||
*** New command 'image-transform-set-percent'.
|
||||
It allows setting the image size to a percentage of its original size,
|
||||
|
|
@ -2648,6 +2643,19 @@ The old name was confusing, and is now an obsolete function alias.
|
|||
|
||||
** Images
|
||||
|
||||
+++
|
||||
** New commands 'image-crop' and 'image-cut'.
|
||||
These commands allow interactively cropping/cutting the image at
|
||||
point. The commands are bound to keys 'i c' and 'i x' (respectively)
|
||||
in the local keymap over images. They rely on external programs, by
|
||||
default "convert" from ImageMagick, to do the actual cropping/eliding
|
||||
of the image file.
|
||||
|
||||
+++
|
||||
*** New commands: 'image-flip-horizontally' and 'image-flip-vertically'.
|
||||
These commands horizontally and vertically flip the image under point,
|
||||
and are bound to 'i h' and 'i v', respectively.
|
||||
|
||||
+++
|
||||
*** Users can now add special image conversion functions.
|
||||
This is done via 'image-converter-add-handler'.
|
||||
|
|
@ -3243,14 +3251,6 @@ macro, which allows you to isolate package configuration in your init
|
|||
file in a way that is declarative, tidy, and performance-oriented.
|
||||
See the new Info manual "(use-package) Top" for more.
|
||||
|
||||
+++
|
||||
** New commands 'image-crop' and 'image-cut'.
|
||||
These commands allow interactively cropping/cutting the image at
|
||||
point. The commands are bound to keys 'i c' and 'i x' (respectively)
|
||||
in the local keymap over images. They rely on external programs, by
|
||||
default "convert" from ImageMagick, to do the actual cropping/eliding
|
||||
of the image file.
|
||||
|
||||
---
|
||||
** New package 'wallpaper'.
|
||||
This package provides the command 'wallpaper-set', which sets the
|
||||
|
|
|
|||
|
|
@ -172,22 +172,6 @@ or \"ffmpeg\") is installed."
|
|||
|
||||
(define-error 'unknown-image-type "Unknown image type")
|
||||
|
||||
(defvar-keymap image-map
|
||||
:doc "Map put into text properties on images."
|
||||
"i" (define-keymap
|
||||
"-" #'image-decrease-size
|
||||
"+" #'image-increase-size
|
||||
"r" #'image-rotate
|
||||
"o" #'image-save
|
||||
"c" #'image-crop
|
||||
"x" #'image-cut
|
||||
"h" #'image-flip-horizontally
|
||||
"v" #'image-flip-vertically)
|
||||
"C-<wheel-down>" #'image-mouse-decrease-size
|
||||
"C-<mouse-5>" #'image-mouse-decrease-size
|
||||
"C-<wheel-up>" #'image-mouse-increase-size
|
||||
"C-<mouse-4>" #'image-mouse-increase-size)
|
||||
|
||||
(defvar-keymap image-slice-map
|
||||
:doc "Map put into text properties on sliced images."
|
||||
"i" (define-keymap
|
||||
|
|
@ -201,6 +185,14 @@ or \"ffmpeg\") is installed."
|
|||
"C-<wheel-up>" #'image-mouse-increase-size
|
||||
"C-<mouse-4>" #'image-mouse-increase-size)
|
||||
|
||||
(defvar-keymap image-map
|
||||
:doc "Map put into text properties on images."
|
||||
:parent image-slice-map
|
||||
"i" (define-keymap
|
||||
"r" #'image-rotate
|
||||
"h" #'image-flip-horizontally
|
||||
"v" #'image-flip-vertically))
|
||||
|
||||
(defun image-load-path-for-library (library image &optional path no-error)
|
||||
"Return a suitable search path for images used by LIBRARY.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue