procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Fix doc strings in lisp/image/ directory

Browse source 
* lisp/image/wallpaper.el (wallpaper-setter)
(wallpaper--find-command, wallpaper--x-monitor-name)
(wallpaper--format-arg):
* lisp/image/image-dired-util.el
(image-dired-associated-dired-buffer)
(image-dired--with-dired-buffer):
* lisp/image/image-dired-tags.el (image-dired--with-db-file)
(image-dired-remove-tag, image-dired-list-tags)
(image-dired-tag-files, image-dired-write-comments)
(image-dired-update-property):
* lisp/image/image-dired-external.el (image-dired-cmd-pngnq-options)
(image-dired-cmd-pngcrush-program)
(image-dired-cmd-pngcrush-options)
(image-dired-cmd-optipng-options)
(image-dired-cmd-create-standard-thumbnail-options)
(image-dired-cmd-rotate-original-program)
(image-dired-cmd-rotate-original-options)
(image-dired-cmd-write-exif-data-options, image-dired-queue)
(image-dired-queue-active-limit, image-dired-pngnq-thumb)
(image-dired-pngcrush-thumb, image-dired-optipng-thumb)
(image-dired-thumb-queue-run, image-dired-get-exif-file-name)
(image-dired-thumbnail-set-image-description):
* lisp/image/image-dired.el (image-dired-thumbnail-storage)
(image-dired-tags-db-file)
(image-dired-rotate-original-ask-before-overwrite)
(image-dired-line-up-method, image-dired-track-movement)
(image-dired-display-properties-format)
(image-dired-external-viewer)
(image-dired-show-all-from-dir-max-files)
(image-dired-insert-image)
(image-dired-dired-with-window-configuration)
(image-dired-restore-window-configuration)
(image-dired-track-original-file)
(image-dired-toggle-movement-tracking)
(image-dired-format-properties-string)
(image-dired--on-file-in-dired-buffer)
(image-dired-thumbnail-display-external)
(image-dired-display-image, image-dired-copy-filename-as-kill):
* lisp/image/image-dired-dired.el
(image-dired-dired-toggle-marked-thumbs)
(image-dired-dired-after-readin-hook)
(image-dired-next-line-and-display)
(image-dired-previous-line-and-display)
(image-dired-mark-and-display-next, image-dired-track-thumbnail)
(image-dired-dired-next-line, image-dired-dired-previous-line)
(image-dired-dired-display-external)
(image-dired-copy-with-exif-file-name)
(image-dired-mark-tagged-files)
(image-dired-dired-display-properties):
* lisp/image/image-crop.el (image-crop-exif-rotate)
(image-crop-resize-command, image-crop-cut-command)
(image-crop-crop-command, image-crop-rotate-command)
(image-crop-buffer-text-function, image-cut-color):
* lisp/image/image-converter.el (image-converter)
(image-convert-to-format, image-converter-regexp)
(image-converter--converters, image-convert-p, image-convert)
(image-converter--value, image-converter--probe)
(image-converter--find-converter, image-converter--convert)
(image-converter-add-handler):
* lisp/image/exif.el (exif-parse-buffer, exif-field)
(exif-orientation, exif--direct-ascii-value)
(exif--process-value, exif--read-chunk, exif--read-number-be)
(exif--read-number-le, exif--read-number): Fix doc strings.
This commit is contained in:
Eli Zaretskii 2023-02-11 16:49:54 +02:00
parent 2d1e43436d
commit 074008ee2d
9 changed files with 197 additions and 181 deletions
Download patch file Download diff file Expand all files Collapse all files

47
lisp/image/exif.el
View file

@ -110,7 +110,7 @@ from the return value of this function."
(exif-parse-buffer))) (exif-parse-buffer)))
(defun exif-parse-buffer (&optional buffer) (defun exif-parse-buffer (&optional buffer)
"Parse BUFFER (which should be a JPEG file) and return the Exif data, if any. "Parse BUFFER (which should visit a JPEG file) and return Exif data, if any.
The return value is a list of Exif items. The return value is a list of Exif items.
If the data is invalid, an `exif-error' is signaled. If the data is invalid, an `exif-error' is signaled.
@ -134,17 +134,17 @@ from the return value of this function."
(exif--parse-exif-chunk app1)))))) (exif--parse-exif-chunk app1))))))
(defun exif-field (field data) (defun exif-field (field data)
"Return raw FIELD from EXIF. "Return raw FIELD from Exif DATA.
If FIELD is not present in the data, return nil. If FIELD is not present in the data, return nil.
FIELD is a symbol in the cdr of `exif-tag-alist'. FIELD is a symbol in the cdr of `exif-tag-alist'.
DATA is the result of calling `exif-parse-file'." DATA is the result of calling `exif-parse-file' or `exif-parse-buffer'."
(plist-get (seq-find (lambda (e) (plist-get (seq-find (lambda (e)
(eq field (plist-get e :tag-name))) (eq field (plist-get e :tag-name)))
data) data)
:value)) :value))
(defun exif-orientation (exif) (defun exif-orientation (exif)
"Return the orientation (in degrees) in EXIF. "Return the orientation (in degrees) in EXIF data.
If the orientation isn't present in the data, return nil." If the orientation isn't present in the data, return nil."
(let ((code (exif-field 'orientation exif))) (let ((code (exif-field 'orientation exif)))
(cadr (assq code exif--orientation)))) (cadr (assq code exif--orientation))))
@ -254,21 +254,24 @@ If the orientation isn't present in the data, return nil."
;; We've reached the end of the directories. ;; We've reached the end of the directories.
dir)))) dir))))
(defun exif--direct-ascii-value (value bytes le) (defun exif--direct-ascii-value (value nbytes le)
"Make VALUE into a zero-terminated string. "Make a string representing VALUE with NBYTES bytes according to LE endianness.
VALUE is an integer representing BYTES characters." VALUE is an integer value of NBYTES bytes.
The return value is a null-terminated unibyte string whose length is
NBYTES+1 bytes. If LE is non-nil, the returned string representation of
VALUE is little-endian, otherwise it is big-endian."
(with-temp-buffer (with-temp-buffer
(set-buffer-multibyte nil) (set-buffer-multibyte nil)
(if le (if le
(dotimes (i bytes) (dotimes (i nbytes)
(insert (logand (ash value (* i -8)) 255))) (insert (logand (ash value (* i -8)) 255)))
(dotimes (i bytes) (dotimes (i nbytes)
(insert (logand (ash value (* (- (1- bytes) i) -8)) 255)))) (insert (logand (ash value (* (- (1- nbytes) i) -8)) 255))))
(insert 0) (insert 0)
(buffer-string))) (buffer-string)))
(defun exif--process-value (value type le) (defun exif--process-value (value type le)
"Do type-based post-processing of the value." "Do type-based post-processing of the VALUE whose endianness is per LE."
(cl-case type (cl-case type
;; Chop off trailing zero byte. ;; Chop off trailing zero byte.
(ascii (substring value 0 (1- (length value)))) (ascii (substring value 0 (1- (length value))))
@ -281,7 +284,8 @@ VALUE is an integer representing BYTES characters."
(otherwise value))) (otherwise value)))
(defun exif--read-chunk (bytes) (defun exif--read-chunk (bytes)
"Return BYTES octets from the buffer and advance point that much." "Return BYTES octets from the current buffer and advance point that much.
This function assumes that the current buffer is unibyte."
(when (> (+ (point) bytes) (point-max)) (when (> (+ (point) bytes) (point-max))
(signal 'exif-error "Premature end of file")) (signal 'exif-error "Premature end of file"))
(prog1 (prog1
@ -289,8 +293,9 @@ VALUE is an integer representing BYTES characters."
(forward-char bytes))) (forward-char bytes)))
(defun exif--read-number-be (bytes) (defun exif--read-number-be (bytes)
"Read BYTES octets from the buffer as a chunk of big-endian bytes. "Read BYTES octets from the current buffer as a chunk of big-endian bytes.
Advance point to after the read bytes." Advance point to after the read bytes.
This function assumes that the current buffer is unibyte."
(when (> (+ (point) bytes) (point-max)) (when (> (+ (point) bytes) (point-max))
(signal 'exif-error "Premature end of file")) (signal 'exif-error "Premature end of file"))
(let ((sum 0)) (let ((sum 0))
@ -300,8 +305,9 @@ Advance point to after the read bytes."
sum)) sum))
(defun exif--read-number-le (bytes) (defun exif--read-number-le (bytes)
"Read BYTES octets from the buffer as a chunk of low-endian bytes. "Read BYTES octets from the current buffer as a chunk of little-endian bytes.
Advance point to after the read bytes." Advance point to after the read bytes.
This function assumes that the current buffer is unibyte."
(when (> (+ (point) bytes) (point-max)) (when (> (+ (point) bytes) (point-max))
(signal 'exif-error "Premature end of file")) (signal 'exif-error "Premature end of file"))
(let ((sum 0)) (let ((sum 0))
@ -310,10 +316,11 @@ Advance point to after the read bytes."
(forward-char 1)) (forward-char 1))
sum)) sum))
(defun exif--read-number (bytes lower-endian) (defun exif--read-number (bytes little-endian)
"Read BYTES octets from the buffer with endianness determined by LOWER-ENDIAN. "Read BYTES octets from current buffer with endianness given by LITTLE-ENDIAN.
Advance point to after the read bytes." Advance point to after the read bytes.
(if lower-endian This function assumes that the current buffer is unibyte."
(if little-endian
(exif--read-number-le bytes) (exif--read-number-le bytes)
(exif--read-number-be bytes))) (exif--read-number-be bytes)))

71
lisp/image/image-converter.el
View file

@ -38,9 +38,9 @@ If nil, Emacs will try to find one of the supported converters
installed on the system. installed on the system.
The actual range of image formats that will be converted depends The actual range of image formats that will be converted depends
on what image formats the chosen converter reports being able to on the image formats which the chosen converter is able to
handle. `auto-mode-alist' is then used to further filter what handle. `auto-mode-alist' is then used to further filter the
formats that are to be supported: Only the suffixes that map to formats that are to be supported: only the suffixes that map to
`image-mode' will be handled." `image-mode' will be handled."
:group 'image :group 'image
:type 'symbol :type 'symbol
@ -48,16 +48,16 @@ formats that are to be supported: Only the suffixes that map to
(defcustom image-convert-to-format "png" (defcustom image-convert-to-format "png"
"The image format to convert to. "The image format to convert to.
This should be a string like \"png\" or \"ppm\" or some This should be a string like \"png\" or \"ppm\", or some
other (preferably lossless) format that Emacs understands other (preferably lossless) format that Emacs understands
natively. The converter chosen has to support the format, and if natively. The converter chosen has to support this format; if
not, conversion will fail." not, the conversion will fail."
:group 'image :group 'image
:version "29.1" :version "29.1"
:type 'string) :type 'string)
(defvar image-converter-regexp nil (defvar image-converter-regexp nil
"A regexp that matches the file name suffixes that can be converted.") "A regexp that matches the file name suffixes which can be converted.")
(defvar image-converter-file-name-extensions nil (defvar image-converter-file-name-extensions nil
"A list of file name suffixes that can be converted.") "A list of file name suffixes that can be converted.")
@ -66,7 +66,7 @@ not, conversion will fail."
'((graphicsmagick :command ("gm" "convert") :probe ("-list" "format")) '((graphicsmagick :command ("gm" "convert") :probe ("-list" "format"))
(ffmpeg :command "ffmpeg" :probe "-decoders") (ffmpeg :command "ffmpeg" :probe "-decoders")
(imagemagick :command "convert" :probe ("-list" "format"))) (imagemagick :command "convert" :probe ("-list" "format")))
"List of supported image converters to try.") "List of supported image converters to try and required command-line switches.")
(defvar image-converter--extra-converters (make-hash-table :test #'equal)) (defvar image-converter--extra-converters (make-hash-table :test #'equal))
@ -80,8 +80,8 @@ This also determines which external formats we can parse."
"Return `image-convert' if SOURCE is an image that can be converted. "Return `image-convert' if SOURCE is an image that can be converted.
SOURCE can either be a file name or a string containing image SOURCE can either be a file name or a string containing image
data. In the latter case, DATA-P should be non-nil. If DATA-P data. In the latter case, DATA-P should be non-nil. If DATA-P
is a string, it should be a MIME format string like is a string, it should be a MIME format string specifying the image type,
\"image/gif\"." like \"image/gif\"."
(image-converter-initialize) (image-converter-initialize)
;; When image-converter was customized ;; When image-converter was customized
(when (and image-converter (not image-converter-regexp)) (when (and image-converter (not image-converter-regexp))
@ -101,22 +101,21 @@ is a string, it should be a MIME format string like
'image-convert)) 'image-convert))
(defun image-convert (image &optional image-format) (defun image-convert (image &optional image-format)
"Convert IMAGE file to an image format Emacs understands. "Convert IMAGE to an image format which Emacs understands.
This will usually be \"png\", but this is controlled by the This will usually be \"png\", but is controlled by the value
`image-convert-to-format' user option. of the `image-convert-to-format' user option.
IMAGE can either be a file name or image data. IMAGE can either be a file name, an image object returned
by `create-image', or a string with image data. In the latter
To pass in image data, IMAGE should a string containing the image case, IMAGE-FORMAT should be a symbol whose name is a MIME
data, and IMAGE-FORMAT should be a symbol with a MIME format name specification of image format, such as \"image/webp\".
like \"image/webp\". For instance: For instance:
(image-convert data-string \\='image/bmp) (image-convert data-string \\='image/bmp)
IMAGE can also be an image object as returned by `create-image'. This function converts the image to the preferred format, per
the value of `image-convert-to-format', and returns the
This function converts the image the preferred format, and the converted image data as a string."
converted image data is returned as a string."
(image-converter-initialize) (image-converter-initialize)
(unless image-converter (unless image-converter
(error "No external image converters available")) (error "No external image converters available"))
@ -152,14 +151,14 @@ converted image data is returned as a string."
(buffer-string)))) (buffer-string))))
(defun image-converter--value (type elem) (defun image-converter--value (type elem)
"Return the value of ELEM of image converter TYPE." "Return the value of property ELEM for image converter TYPE."
(let ((value (plist-get (cdr (assq type image-converter--converters)) elem))) (let ((value (plist-get (cdr (assq type image-converter--converters)) elem)))
(if (stringp value) (if (stringp value)
(list value) (list value)
value))) value)))
(cl-defmethod image-converter--probe ((type (eql 'graphicsmagick))) (cl-defmethod image-converter--probe ((type (eql 'graphicsmagick)))
"Check whether the system has GraphicsMagick installed." "Check whether the system has GraphicsMagick installed that's usable converter."
(with-temp-buffer (with-temp-buffer
(let ((command (image-converter--value type :command)) (let ((command (image-converter--value type :command))
formats) formats)
@ -177,7 +176,7 @@ converted image data is returned as a string."
(nreverse formats))))) (nreverse formats)))))
(cl-defmethod image-converter--probe ((type (eql 'imagemagick))) (cl-defmethod image-converter--probe ((type (eql 'imagemagick)))
"Check whether the system has ImageMagick installed." "Check whether the system has ImageMagick installed that's a usable converter."
(with-temp-buffer (with-temp-buffer
(let ((command (image-converter--value type :command)) (let ((command (image-converter--value type :command))
formats) formats)
@ -197,7 +196,7 @@ converted image data is returned as a string."
(nreverse formats)))) (nreverse formats))))
(cl-defmethod image-converter--probe ((type (eql 'ffmpeg))) (cl-defmethod image-converter--probe ((type (eql 'ffmpeg)))
"Check whether the system has ffmpeg installed." "Check whether the system has ffmpeg installed that's a usable converter."
(with-temp-buffer (with-temp-buffer
(let ((command (image-converter--value type :command)) (let ((command (image-converter--value type :command))
formats) formats)
@ -215,7 +214,7 @@ converted image data is returned as a string."
(nreverse formats))))) (nreverse formats)))))
(defun image-converter--find-converter () (defun image-converter--find-converter ()
"Find an installed image converter." "Find an installed image converter Emacs can use."
(catch 'done (catch 'done
(dolist (elem image-converter--converters) (dolist (elem image-converter--converters)
(when-let ((formats (image-converter--filter-formats (when-let ((formats (image-converter--filter-formats
@ -239,12 +238,12 @@ Only suffixes that map to `image-mode' are returned."
(cl-defmethod image-converter--convert ((type (eql 'graphicsmagick)) source (cl-defmethod image-converter--convert ((type (eql 'graphicsmagick)) source
image-format) image-format)
"Convert using GraphicsMagick." "Convert image in SOURCE using GraphicsMagick."
(image-converter--convert-magick type source image-format)) (image-converter--convert-magick type source image-format))
(cl-defmethod image-converter--convert ((type (eql 'imagemagick)) source (cl-defmethod image-converter--convert ((type (eql 'imagemagick)) source
image-format) image-format)
"Convert using ImageMagick." "Convert image in SOURCE using ImageMagick."
(image-converter--convert-magick type source image-format)) (image-converter--convert-magick type source image-format))
(defun image-converter--mime-type (image-format) (defun image-converter--mime-type (image-format)
@ -281,7 +280,7 @@ Only suffixes that map to `image-mode' are returned."
(cl-defmethod image-converter--convert ((type (eql 'ffmpeg)) source (cl-defmethod image-converter--convert ((type (eql 'ffmpeg)) source
image-format) image-format)
"Convert using ffmpeg." "Convert image in SOURCE using ffmpeg."
(let ((command (image-converter--value type :command)) (let ((command (image-converter--value type :command))
(coding-system-for-read 'no-conversion)) (coding-system-for-read 'no-conversion))
(unless (zerop (if image-format (unless (zerop (if image-format
@ -308,12 +307,12 @@ Only suffixes that map to `image-mode' are returned."
;;;###autoload ;;;###autoload
(defun image-converter-add-handler (suffix converter) (defun image-converter-add-handler (suffix converter)
"Make Emacs use CONVERTER to parse image files that end with SUFFIX. "Make Emacs use CONVERTER to parse image files whose names end with SUFFIX.
CONVERTER is a function with two parameters, where the first is CONVERTER is a function with two arguments, the file name or a string
the file name or a string with the image data, and the second is with the image data, and a non-nil value if the first argument is image data.
non-nil if the first parameter is image data. The converter The converter should produce the image in the current buffer, converted to
should output the image in the current buffer, converted to the format given by `image-convert-to-format'.
`image-convert-to-format'." SUFFIX should not include the leading dot."
(cl-pushnew suffix image-converter-file-name-extensions :test #'equal) (cl-pushnew suffix image-converter-file-name-extensions :test #'equal)
(setq image-converter-file-name-extensions (setq image-converter-file-name-extensions
(sort image-converter-file-name-extensions #'string<)) (sort image-converter-file-name-extensions #'string<))

48
lisp/image/image-crop.el
View file

@ -41,71 +41,71 @@
:group 'image) :group 'image)
(defvar image-crop-exif-rotate nil (defvar image-crop-exif-rotate nil
"If non-nil, rotate images by updating exif data. "If non-nil, rotate images by updating Exif data.
If nil, rotate the images \"physically\".") If nil, rotate the images \"physically\".")
(defcustom image-crop-resize-command '("convert" "-resize" "%wx" "-" "%f:-") (defcustom image-crop-resize-command '("convert" "-resize" "%wx" "-" "%f:-")
"Command to resize an image. "List of command and command-line arguments to resize an image.
The following `format-spec' elements are allowed: The following `format-spec' elements are allowed in the value:
%w: Width. %w: Width.
%f: Result file type." %f: File type to produce."
:type '(repeat string) :type '(repeat string)
:version "29.1") :version "29.1")
(defcustom image-crop-cut-command '("convert" "-draw" "rectangle %l,%t %r,%b" (defcustom image-crop-cut-command '("convert" "-draw" "rectangle %l,%t %r,%b"
"-fill" "%c" "-fill" "%c"
"-" "%f:-") "-" "%f:-")
"Command to cut a rectangle out of an image. "List of command and its command-line arguments to cut a rectangle out of image.
The following `format-spec' elements are allowed: The following `format-spec' elements are allowed in the value:
%l: Left. %l: Left.
%t: Top. %t: Top.
%r: Right. %r: Right.
%b: Bottom. %b: Bottom.
%c: Color. %c: Color.
%f: Result file type." %f: File type to produce."
:type '(repeat string) :type '(repeat string)
:version "29.1") :version "29.1")
(defcustom image-crop-crop-command '("convert" "+repage" "-crop" "%wx%h+%l+%t" (defcustom image-crop-crop-command '("convert" "+repage" "-crop" "%wx%h+%l+%t"
"-" "%f:-") "-" "%f:-")
"Command to crop an image. "List of command and its command-line arguments to crop an image.
The following `format-spec' elements are allowed: The following `format-spec' elements are allowed in the value:
%l: Left. %l: Left.
%t: Top. %t: Top.
%w: Width. %w: Width.
%h: Height. %h: Height.
%f: Result file type." %f: File type to produce."
:type '(repeat string) :type '(repeat string)
:version "29.1") :version "29.1")
(defcustom image-crop-rotate-command '("convert" "-rotate" "%r" "-" "%f:-") (defcustom image-crop-rotate-command '("convert" "-rotate" "%r" "-" "%f:-")
"Command to rotate an image. "List of command and its command-line arguments to rotate an image.
The following `format-spec' elements are allowed: The following `format-spec' elements are allowed in the value:
%r: Rotation (in degrees). %r: Rotation (in degrees).
%f: Result file type." %f: File type to produce."
:type '(repeat string) :type '(repeat string)
:version "29.1") :version "29.1")
(defvar image-crop-buffer-text-function #'image-crop--default-buffer-text (defvar image-crop-buffer-text-function #'image-crop--default-buffer-text
"Function to return the buffer text for the cropped image. "Function to return the buffer text corresponding to the cropped image.
After cropping an image, the displayed image will be updated to After cropping an image, the displayed image in the buffer will be updated
show the cropped image in the buffer. Different modes will have to show the cropped image. Different modes will have different ways to
different ways to represent this image data in a buffer. For represent this image data in a buffer, but that's up to the mode. For
instance, an HTML-based mode might want to represent the image instance, an HTML-based mode might want to represent the image with
with <img src=\"data:...base64...\">, but that's up to the mode. <img src=\"data:...base64...\">.
The default action is to not alter the buffer text at all. The default action is to not alter the image's text in the buffer, and
just return it.
The function is called with two arguments: The first is the The function is called with two arguments: the original buffer text,
original buffer text, and the second parameter is the cropped and the cropped image data.")
image data.")
(defcustom image-cut-color "black" (defcustom image-cut-color "black"
"Color to use for the rectangle cut from the image." "Color to use for the rectangle that was cut from the image."
:type 'string :type 'string
:version "29.1") :version "29.1")

52
lisp/image/image-dired-dired.el
View file

@ -57,11 +57,12 @@ Dired and you might want to turn it off."
;;;###autoload ;;;###autoload
(defun image-dired-dired-toggle-marked-thumbs (&optional arg) (defun image-dired-dired-toggle-marked-thumbs (&optional arg)
"Toggle thumbnails in front of file names in the Dired buffer. "Toggle thumbnails in front of marked file names in the Dired buffer.
If no marked file could be found, insert or hide thumbnails on the If no file is marked, toggle display of thumbnail on the current file's line.
current line. ARG, if non-nil, specifies the files to use instead ARG, if non-nil (interactively, the prefix argument), specifies the files
of the marked files. If ARG is an integer, use the next ARG (or whose thumbnail display to toggle instead of the marked files: if ARG is an
previous -ARG, if ARG<0) files." integer, use the next ARG (or previous -ARG, if ARG<0) files; any other
value of ARG means toggle thumbnail display of the current line's file."
(interactive "P" dired-mode) (interactive "P" dired-mode)
(setq image-dired--generate-thumbs-start (current-time)) (setq image-dired--generate-thumbs-start (current-time))
(dired-map-over-marks (dired-map-over-marks
@ -91,8 +92,8 @@ previous -ARG, if ARG<0) files."
(defun image-dired-dired-after-readin-hook () (defun image-dired-dired-after-readin-hook ()
"Relocate existing thumbnail overlays in Dired buffer after reverting. "Relocate existing thumbnail overlays in Dired buffer after reverting.
Move them to their corresponding files if they still exist. Move each overlay to its corresponding file if it still exists.
Otherwise, delete overlays. Otherwise, delete the overlay.
Used by `image-dired-dired-toggle-marked-thumbs'." Used by `image-dired-dired-toggle-marked-thumbs'."
(mapc (lambda (overlay) (mapc (lambda (overlay)
(when (overlay-get overlay 'put-image) (when (overlay-get overlay 'put-image)
@ -104,7 +105,7 @@ Used by `image-dired-dired-toggle-marked-thumbs'."
(overlays-in (point-min) (point-max)))) (overlays-in (point-min) (point-max))))
(defun image-dired-next-line-and-display () (defun image-dired-next-line-and-display ()
"Move to next Dired line and display thumbnail image." "Move to next Dired line and display its thumbnail image."
(interactive nil dired-mode) (interactive nil dired-mode)
(dired-next-line 1) (dired-next-line 1)
(image-dired-display-thumbs t image-dired-dired-append-when-browsing t) (image-dired-display-thumbs t image-dired-dired-append-when-browsing t)
@ -112,7 +113,7 @@ Used by `image-dired-dired-toggle-marked-thumbs'."
(image-dired-dired-display-properties))) (image-dired-dired-display-properties)))
(defun image-dired-previous-line-and-display () (defun image-dired-previous-line-and-display ()
"Move to previous Dired line and display thumbnail image." "Move to previous Dired line and display its thumbnail image."
(interactive nil dired-mode) (interactive nil dired-mode)
(dired-previous-line 1) (dired-previous-line 1)
(image-dired-display-thumbs t image-dired-dired-append-when-browsing t) (image-dired-display-thumbs t image-dired-dired-append-when-browsing t)
@ -130,7 +131,7 @@ Used by `image-dired-dired-toggle-marked-thumbs'."
"off"))) "off")))
(defun image-dired-mark-and-display-next () (defun image-dired-mark-and-display-next ()
"Mark current file in Dired and display next thumbnail image." "Mark current file in Dired and display the next thumbnail image."
(interactive nil dired-mode) (interactive nil dired-mode)
(dired-mark 1) (dired-mark 1)
(image-dired-display-thumbs t image-dired-dired-append-when-browsing t) (image-dired-display-thumbs t image-dired-dired-append-when-browsing t)
@ -148,7 +149,7 @@ Used by `image-dired-dired-toggle-marked-thumbs'."
"off"))) "off")))
(defun image-dired-track-thumbnail () (defun image-dired-track-thumbnail ()
"Track current Dired file's thumb in `image-dired-thumbnail-buffer'. "Move to thumbnail of the current Dired file in `image-dired-thumbnail-buffer'.
This is almost the same as what `image-dired-track-original-file' does, This is almost the same as what `image-dired-track-original-file' does,
but the other way around." but the other way around."
(let ((file (dired-get-filename)) (let ((file (dired-get-filename))
@ -170,18 +171,18 @@ but the other way around."
(image-dired--update-header-line)))))) (image-dired--update-header-line))))))
(defun image-dired-dired-next-line (&optional arg) (defun image-dired-dired-next-line (&optional arg)
"Call `dired-next-line', then track thumbnail. "Call `dired-next-line', while tracking the file's thumbnail.
This can safely replace `dired-next-line'. This can safely replace `dired-next-line'.
With prefix argument, move ARG lines." With prefix argument ARG, move that many lines."
(interactive "P" dired-mode) (interactive "P" dired-mode)
(dired-next-line (or arg 1)) (dired-next-line (or arg 1))
(if image-dired-track-movement (if image-dired-track-movement
(image-dired-track-thumbnail))) (image-dired-track-thumbnail)))
(defun image-dired-dired-previous-line (&optional arg) (defun image-dired-dired-previous-line (&optional arg)
"Call `dired-previous-line', then track thumbnail. "Call `dired-previous-line', while tracking the file's thumbnail.
This can safely replace `dired-previous-line'. This can safely replace `dired-previous-line'.
With prefix argument, move ARG lines." With prefix argument ARG, move that many lines."
(interactive "P" dired-mode) (interactive "P" dired-mode)
(dired-previous-line (or arg 1)) (dired-previous-line (or arg 1))
(if image-dired-track-movement (if image-dired-track-movement
@ -307,7 +308,8 @@ With prefix argument ARG, create thumbnails even if they already exist
;;;###autoload ;;;###autoload
(defun image-dired-dired-display-external () (defun image-dired-dired-display-external ()
"Display file at point using an external viewer." "Display file at point using an external viewer.
The viewer is specified by the value of `image-dired-external-viewer'."
(interactive nil dired-mode) (interactive nil dired-mode)
(let ((file (dired-get-filename))) (let ((file (dired-get-filename)))
(start-process "image-dired-external" nil (start-process "image-dired-external" nil
@ -323,15 +325,15 @@ See documentation for `image-dired-display-image' for more information."
(defun image-dired-copy-with-exif-file-name () (defun image-dired-copy-with-exif-file-name ()
"Copy file with unique name to main image directory. "Copy file with unique name to main image directory.
Copy current or all marked files in Dired to a new file in your Copy current or all files marked in Dired to new file(s) in your
main image directory, using a file name generated by main image directory, using file name(s) generated by
`image-dired-get-exif-file-name'. A typical usage for this if when `image-dired-get-exif-file-name'. A typical usage for this if when
copying images from a digital camera into the image directory. copying images from a digital camera into the image directory.
Typically, you would open up the folder with the incoming Typically, you would open up the folder with the incoming
digital images, mark the files to be copied, and execute this digital images, mark the files to be copied, and execute this
function. The result is a couple of new files in command. The result is one or more new files in
`image-dired-main-image-directory' called `image-dired-main-image-directory', named like
2005_05_08_12_52_00_dscn0319.jpg, 2005_05_08_12_52_00_dscn0319.jpg,
2005_05_08_14_27_45_dscn0320.jpg etc." 2005_05_08_14_27_45_dscn0320.jpg etc."
(interactive nil dired-mode) (interactive nil dired-mode)
@ -350,11 +352,11 @@ function. The result is a couple of new files in
;;;###autoload ;;;###autoload
(defun image-dired-mark-tagged-files (regexp) (defun image-dired-mark-tagged-files (regexp)
"Use REGEXP to mark files with matching tag. "Mark files whose tag matches REGEXP.
A `tag' is a keyword, a piece of meta data, associated with an A `tag' is a keyword, a piece of meta data, associated with an
image file and stored in image-dired's database file. This command image file and stored in image-dired's database file. This command
lets you input a regexp and this will be matched against all tags promts for a regexp, and then matches it against all the tags
on all image files in the database file. The files that have a of all the image files in the database file. The files that have a
matching tag will be marked in the Dired buffer." matching tag will be marked in the Dired buffer."
(interactive "sMark tagged files (regexp): " dired-mode) (interactive "sMark tagged files (regexp): " dired-mode)
(image-dired-sane-db-file) (image-dired-sane-db-file)
@ -386,7 +388,7 @@ matching tag will be marked in the Dired buffer."
(message "%d files with matching tag marked" hits))) (message "%d files with matching tag marked" hits)))
(defun image-dired-dired-display-properties () (defun image-dired-dired-display-properties ()
"Display properties for Dired file in the echo area." "Show in the echo area the image-related properties of a file in Dired buffer."
(interactive nil dired-mode) (interactive nil dired-mode)
(let* ((file-name (dired-get-filename)) (let* ((file-name (dired-get-filename))
(dired-buf (buffer-name (current-buffer))) (dired-buf (buffer-name (current-buffer)))

48
lisp/image/image-dired-external.el
View file

@ -86,15 +86,15 @@ using the NeuQuant algorithm."
(if (executable-find "pngquant") (if (executable-find "pngquant")
'("--ext" "-nq8.png" "%t") ; same extension as "pngnq" '("--ext" "-nq8.png" "%t") ; same extension as "pngnq"
'("-f" "%t")) '("-f" "%t"))
"Arguments to pass `image-dired-cmd-pngnq-program'. "Arguments to pass to `image-dired-cmd-pngnq-program'.
Available format specifiers are the same as in Value can use the same format specifiers as in
`image-dired-cmd-create-thumbnail-options'." `image-dired-cmd-create-thumbnail-options'."
:type '(repeat (string :tag "Argument")) :type '(repeat (string :tag "Argument"))
:version "29.1") :version "29.1")
(defcustom image-dired-cmd-pngcrush-program (executable-find "pngcrush") (defcustom image-dired-cmd-pngcrush-program (executable-find "pngcrush")
"The file name of the `pngcrush' program. "The file name of the `pngcrush' program.
It optimizes the compression of PNG images. Also it adds PNG textual chunks It optimizes the compression of PNG images. It also adds PNG textual chunks
with the information required by the Thumbnail Managing Standard." with the information required by the Thumbnail Managing Standard."
:type '(choice (const :tag "Not Set" nil) file)) :type '(choice (const :tag "Not Set" nil) file))
@ -110,7 +110,7 @@ with the information required by the Thumbnail Managing Standard."
"-text" "b" "Thumb::URI" "file://%f" "-text" "b" "Thumb::URI" "file://%f"
"%q" "%t") "%q" "%t")
"Arguments for `image-dired-cmd-pngcrush-program'. "Arguments for `image-dired-cmd-pngcrush-program'.
The available %-format specifiers are the same as in The value can use the same %-format specifiers as in
`image-dired-cmd-create-thumbnail-options', with \"%q\" for a `image-dired-cmd-create-thumbnail-options', with \"%q\" for a
temporary file name (typically generated by pnqnq)." temporary file name (typically generated by pnqnq)."
:version "26.1" :version "26.1"
@ -123,7 +123,7 @@ temporary file name (typically generated by pnqnq)."
(defcustom image-dired-cmd-optipng-options '("-o5" "%t") (defcustom image-dired-cmd-optipng-options '("-o5" "%t")
"Arguments passed to `image-dired-cmd-optipng-program'. "Arguments passed to `image-dired-cmd-optipng-program'.
Available format specifiers are described in The value can use format specifiers described in
`image-dired-cmd-create-thumbnail-options'." `image-dired-cmd-create-thumbnail-options'."
:version "26.1" :version "26.1"
:type '(repeat (string :tag "Argument")) :type '(repeat (string :tag "Argument"))
@ -139,14 +139,14 @@ Available format specifiers are described in
"-thumbnail" "%wx%h>" "png:%t"))) "-thumbnail" "%wx%h>" "png:%t")))
(if (executable-find "gm") (cons "convert" opts) opts)) (if (executable-find "gm") (cons "convert" opts) opts))
"Options for creating thumbnails according to the Thumbnail Managing Standard. "Options for creating thumbnails according to the Thumbnail Managing Standard.
The available %-format specifiers are the same as in The value can use the same %-format specifiers as in
`image-dired-cmd-create-thumbnail-options', with \"%m\" for file `image-dired-cmd-create-thumbnail-options', with \"%m\" for file
modification time." modification time."
:type '(repeat (string :tag "Argument")) :type '(repeat (string :tag "Argument"))
:version "29.1") :version "29.1")
(defcustom image-dired-cmd-rotate-original-program "jpegtran" (defcustom image-dired-cmd-rotate-original-program "jpegtran"
"Executable used to rotate original image. "Executable program used to rotate original image.
Used together with `image-dired-cmd-rotate-original-options'." Used together with `image-dired-cmd-rotate-original-options'."
:type 'file) :type 'file)
@ -154,11 +154,11 @@ Used together with `image-dired-cmd-rotate-original-options'."
'("-rotate" "%d" "-copy" "all" "-outfile" "%t" "%o") '("-rotate" "%d" "-copy" "all" "-outfile" "%t" "%o")
"Arguments of command used to rotate original image. "Arguments of command used to rotate original image.
Used with `image-dired-cmd-rotate-original-program'. Used with `image-dired-cmd-rotate-original-program'.
Available format specifiers are: %d which is replaced by the The value can use the following format specifiers:
number of (positive) degrees to rotate the image, normally 90 or %d which is replaced by the number of (positive) degrees
270 \(for 90 degrees right and left), %o which is replaced by the to rotate the image, normally 90 or 270 (for 90 degrees right and left),
original image file name and %t which is replaced by %o which is replaced by the original image file name
`image-dired-temp-image-file'." and %t which is replaced by `image-dired-temp-image-file'."
:version "26.1" :version "26.1"
:type '(repeat (string :tag "Argument"))) :type '(repeat (string :tag "Argument")))
@ -176,9 +176,10 @@ Used together with `image-dired-cmd-write-exif-data-options'."
(defcustom image-dired-cmd-write-exif-data-options '("-%t=%v" "%f") (defcustom image-dired-cmd-write-exif-data-options '("-%t=%v" "%f")
"Arguments of command used to write EXIF data. "Arguments of command used to write EXIF data.
Used with `image-dired-cmd-write-exif-data-program'. Used with `image-dired-cmd-write-exif-data-program'.
Available format specifiers are: %f which is replaced by The value can use the following format specifiers are:
the image file name, %t which is replaced by the tag name and %v %f which is replaced by the image file name,
which is replaced by the tag value." %t which is replaced by the tag name
and %v which is replaced by the tag value."
:version "26.1" :version "26.1"
:type '(repeat (string :tag "Argument"))) :type '(repeat (string :tag "Argument")))
@ -206,7 +207,7 @@ which is replaced by the tag value."
"Time when `display-thumbs' was called.") "Time when `display-thumbs' was called.")
(defvar image-dired-queue nil (defvar image-dired-queue nil
"List of items in the queue. "List of items in the Image-Dired queue.
Each item has the form (ORIGINAL-FILE TARGET-FILE).") Each item has the form (ORIGINAL-FILE TARGET-FILE).")
(defvar image-dired-queue-active-jobs 0 (defvar image-dired-queue-active-jobs 0
@ -214,13 +215,13 @@ Each item has the form (ORIGINAL-FILE TARGET-FILE).")
(defvar image-dired-queue-active-limit (min 4 (max 2 (/ (num-processors) 2))) (defvar image-dired-queue-active-limit (min 4 (max 2 (/ (num-processors) 2)))
"Maximum number of concurrent jobs permitted for generating images. "Maximum number of concurrent jobs permitted for generating images.
Increase at own risk. If you want to experiment with this, Increase at your own risk. If you want to experiment with this,
consider setting `image-dired-debug' to a non-nil value to see consider setting `image-dired-debug' to a non-nil value to see
the time spent on generating thumbnails. Run `clear-image-cache' the time spent on generating thumbnails. Run `clear-image-cache'
and remove the cached thumbnail files between each trial run.") and remove the cached thumbnail files between each trial run.")
(defun image-dired-pngnq-thumb (spec) (defun image-dired-pngnq-thumb (spec)
"Quantize thumbnail described by format SPEC with pngnq(1)." "Quantize thumbnail described by format SPEC with command `pngnq'."
(let ((process (let ((process
(apply #'start-process "image-dired-pngnq" nil (apply #'start-process "image-dired-pngnq" nil
image-dired-cmd-pngnq-program image-dired-cmd-pngnq-program
@ -243,7 +244,7 @@ and remove the cached thumbnail files between each trial run.")
process)) process))
(defun image-dired-pngcrush-thumb (spec) (defun image-dired-pngcrush-thumb (spec)
"Optimize thumbnail described by format SPEC with pngcrush(1)." "Optimize thumbnail described by format SPEC with command `pngcrush'."
;; If pngnq wasn't run, then the THUMB-nq8.png file does not exist. ;; If pngnq wasn't run, then the THUMB-nq8.png file does not exist.
;; pngcrush needs an infile and outfile, so we just copy THUMB to ;; pngcrush needs an infile and outfile, so we just copy THUMB to
;; THUMB-nq8.png and use the latter as a temp file. ;; THUMB-nq8.png and use the latter as a temp file.
@ -268,7 +269,7 @@ and remove the cached thumbnail files between each trial run.")
process)) process))
(defun image-dired-optipng-thumb (spec) (defun image-dired-optipng-thumb (spec)
"Optimize thumbnail described by format SPEC with optipng(1)." "Optimize thumbnail described by format SPEC with command `optipng'."
(let ((process (let ((process
(apply #'start-process "image-dired-optipng" nil (apply #'start-process "image-dired-optipng" nil
image-dired-cmd-optipng-program image-dired-cmd-optipng-program
@ -354,7 +355,8 @@ and remove the cached thumbnail files between each trial run.")
(defun image-dired-thumb-queue-run () (defun image-dired-thumb-queue-run ()
"Run a queued job if one exists and not too many jobs are running. "Run a queued job if one exists and not too many jobs are running.
Queued items live in `image-dired-queue'." Queued items live in `image-dired-queue'.
Number of simultaneous jobs is limited by `image-dired-queue-active-limit'."
(while (and image-dired-queue (while (and image-dired-queue
(< image-dired-queue-active-jobs (< image-dired-queue-active-jobs
image-dired-queue-active-limit)) image-dired-queue-active-limit))
@ -414,7 +416,7 @@ The new file will be named THUMBNAIL-FILE."
The file name should be unique as long as you do not take more than The file name should be unique as long as you do not take more than
one picture per second. The original file name is suffixed at the end one picture per second. The original file name is suffixed at the end
for traceability. The format of the returned file name is for traceability. The format of the returned file name is
YYYY_MM_DD_HH_MM_DD_ORIG_FILE_NAME.jpg. Used from YYYY_MM_DD_HH_MM_ss_ORIG_FILE_NAME.jpg. Used from
`image-dired-copy-with-exif-file-name'." `image-dired-copy-with-exif-file-name'."
(let (data no-exif-data-found) (let (data no-exif-data-found)
(if (not (eq 'jpeg (image-type (expand-file-name file)))) (if (not (eq 'jpeg (image-type (expand-file-name file))))
@ -434,7 +436,7 @@ YYYY_MM_DD_HH_MM_DD_ORIG_FILE_NAME.jpg. Used from
(file-name-nondirectory file)))) (file-name-nondirectory file))))
(defun image-dired-thumbnail-set-image-description () (defun image-dired-thumbnail-set-image-description ()
"Set the ImageDescription EXIF tag for the original image. "Set the ImageDescription EXIF tag for the original image at point.
If the image already has a value for this tag, it is used as the If the image already has a value for this tag, it is used as the
default value at the prompt." default value at the prompt."
(interactive nil image-dired-thumbnail-mode) (interactive nil image-dired-thumbnail-mode)

16
lisp/image/image-dired-tags.el
View file

@ -39,7 +39,7 @@
(defmacro image-dired--with-db-file (&rest body) (defmacro image-dired--with-db-file (&rest body)
"Run BODY in a temp buffer containing `image-dired-tags-db-file'. "Run BODY in a temp buffer containing `image-dired-tags-db-file'.
Return the last form in BODY." Return the value of last form in BODY."
(declare (indent 0) (debug t)) (declare (indent 0) (debug t))
`(with-temp-buffer `(with-temp-buffer
(if (file-exists-p image-dired-tags-db-file) (if (file-exists-p image-dired-tags-db-file)
@ -91,7 +91,8 @@ FILE-TAGS is an alist in the following form:
(save-buffer)))) (save-buffer))))
(defun image-dired-remove-tag (files tag) (defun image-dired-remove-tag (files tag)
"For all FILES, remove TAG from the image database." "For each file in FILES, remove TAG from the image database.
FILES can be a name of a single file (a string) or a list of file names."
(image-dired-sane-db-file) (image-dired-sane-db-file)
(image-dired--with-db-file (image-dired--with-db-file
(setq buffer-file-name image-dired-tags-db-file) (setq buffer-file-name image-dired-tags-db-file)
@ -119,7 +120,8 @@ FILE-TAGS is an alist in the following form:
(save-buffer))) (save-buffer)))
(defun image-dired-list-tags (file) (defun image-dired-list-tags (file)
"Read all tags for image FILE from the image database." "Read all tags for image FILE from the image database.
Value is a list of all tags for FILE."
(image-dired-sane-db-file) (image-dired-sane-db-file)
(image-dired--with-db-file (image-dired--with-db-file
(let (end (tags "")) (let (end (tags ""))
@ -136,7 +138,8 @@ FILE-TAGS is an alist in the following form:
;;;###autoload ;;;###autoload
(defun image-dired-tag-files (arg) (defun image-dired-tag-files (arg)
"Tag marked file(s) in Dired. With prefix ARG, tag file at point." "Tag file(s) which are marked in a Dired buffer.
With prefix ARG, tag the file at point."
(interactive "P" dired-mode) (interactive "P" dired-mode)
(let ((tag (completing-read (let ((tag (completing-read
"Tags to add (separate tags with a semicolon): " "Tags to add (separate tags with a semicolon): "
@ -187,8 +190,7 @@ With prefix argument ARG, remove tag from file at point."
'tags (image-dired-list-tags (image-dired-original-file-name)))))) 'tags (image-dired-list-tags (image-dired-original-file-name))))))
(defun image-dired-write-comments (file-comments) (defun image-dired-write-comments (file-comments)
"Write file comments to database. "Write file comments specified by FILE-COMMENTS comments to database.
Write file comments to one or more files.
FILE-COMMENTS is an alist on the following form: FILE-COMMENTS is an alist on the following form:
((FILE . COMMENT) ... )" ((FILE . COMMENT) ... )"
(image-dired-sane-db-file) (image-dired-sane-db-file)
@ -224,7 +226,7 @@ FILE-COMMENTS is an alist on the following form:
(save-buffer)))) (save-buffer))))
(defun image-dired-update-property (prop value) (defun image-dired-update-property (prop value)
"Update text property PROP with value VALUE at point." "Set text property PROP of text at point to have the given VALUE."
(let ((inhibit-read-only t)) (let ((inhibit-read-only t))
(put-text-property (put-text-property
(point) (1+ (point)) (point) (1+ (point))

4
lisp/image/image-dired-util.el
View file

@ -110,11 +110,11 @@ See also `image-dired-thumbnail-storage'."
(abbreviate-file-name f))) (abbreviate-file-name f)))
(defun image-dired-associated-dired-buffer () (defun image-dired-associated-dired-buffer ()
"Get associated Dired buffer at point." "Get associated Dired buffer for thumbnail at point."
(get-text-property (point) 'associated-dired-buffer)) (get-text-property (point) 'associated-dired-buffer))
(defmacro image-dired--with-dired-buffer (&rest body) (defmacro image-dired--with-dired-buffer (&rest body)
"Run BODY in associated Dired buffer. "Run BODY in the Dired buffer associated with thumbnail at point.
Should be used by commands in `image-dired-thumbnail-mode'." Should be used by commands in `image-dired-thumbnail-mode'."
(declare (indent defun) (debug t)) (declare (indent defun) (debug t))
(let ((file (make-symbol "file")) (let ((file (make-symbol "file"))

84
lisp/image/image-dired.el
View file

@ -171,7 +171,7 @@ thumbnails:
sharing of thumbnails across different programs. Thumbnails sharing of thumbnails across different programs. Thumbnails
will be stored in \"$XDG_CACHE_HOME/thumbnails/\" will be stored in \"$XDG_CACHE_HOME/thumbnails/\"
Set this user option to one of the following values: To use this way, set this user option to one of the following values:
- `standard' means use thumbnails sized 128x128. - `standard' means use thumbnails sized 128x128.
- `standard-large' means use thumbnails sized 256x256. - `standard-large' means use thumbnails sized 256x256.
@ -181,20 +181,20 @@ thumbnails:
2. In the Image-Dired specific directory indicated by 2. In the Image-Dired specific directory indicated by
`image-dired-dir'. `image-dired-dir'.
Set this user option to `image-dired' to use it (or To use this way, set this user option to `image-dired' (or
`use-image-dired-dir', which means the same thing for to `use-image-dired-dir', which means the same thing for
backwards-compatibility reasons). backward-compatibility reasons).
3. In a subdirectory \".image-dired\" in the same directory 3. In a subdirectory \".image-dired\" in the same directory
where the image files are. where the image files are.
Set this user option to `per-directory' to use it. To use this way, set this user option to `per-directory'.
To change the default size of thumbnails with (2) and (3) above, To control the default size of thumbnails for alternatives (2)
customize `image-dired-thumb-size'. and (3) above, customize the value of `image-dired-thumb-size'.
With Thumbnail Managing Standard, save thumbnails in the PNG With Thumbnail Managing Standard, save thumbnails in the PNG
format, as mandated by that standard, and otherwise as JPEG. format, as mandated by that standard; otherwise save them as JPEG.
For more information on the Thumbnail Managing Standard, see: For more information on the Thumbnail Managing Standard, see:
https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html" https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html"
@ -216,13 +216,13 @@ https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html
'image-dired-tags-db-file "29.1") 'image-dired-tags-db-file "29.1")
(defcustom image-dired-tags-db-file (defcustom image-dired-tags-db-file
(expand-file-name ".image-dired_db" image-dired-dir) (expand-file-name ".image-dired_db" image-dired-dir)
"Database file where file names and their associated tags are stored." "Database file where image-dired file names and associated tags are stored."
:type 'file) :type 'file)
(defcustom image-dired-rotate-original-ask-before-overwrite t (defcustom image-dired-rotate-original-ask-before-overwrite t
"Confirm overwrite of original file after rotate operation. "Confirm overwriting of original file after image-rotate operation.
If non-nil, ask user for confirmation before overwriting the If non-nil, ask user for confirmation before overwriting the
original file with `image-dired-temp-rotate-image-file'." original image file by `image-dired-temp-rotate-image-file'."
:type 'boolean) :type 'boolean)
(defcustom image-dired-thumb-size (defcustom image-dired-thumb-size
@ -261,11 +261,12 @@ deletion."
(defcustom image-dired-line-up-method 'dynamic (defcustom image-dired-line-up-method 'dynamic
"Default method for line-up of thumbnails in thumbnail buffer. "Default method for line-up of thumbnails in thumbnail buffer.
Used by `image-dired-display-thumbs' and other functions that needs Used by `image-dired-display-thumbs' and other functions that need
to line-up thumbnails. Dynamic means to use the available width of to line-up thumbnails. The value `dynamic' means to use the
the window containing the thumbnail buffer, Fixed means to use available width of the window containing the thumbnail buffer,
`image-dired-thumbs-per-row', Interactive is for asking the user, the value `fixed' means to use `image-dired-thumbs-per-row',
and No line-up means that no automatic line-up will be done." the value `interactive' means ask the user, and the
value `none' means that no automatic line-up will be done."
:type '(choice :tag "Default line-up method" :type '(choice :tag "Default line-up method"
(const :tag "Dynamic" dynamic) (const :tag "Dynamic" dynamic)
(const :tag "Fixed" fixed) (const :tag "Fixed" fixed)
@ -277,8 +278,8 @@ and No line-up means that no automatic line-up will be done."
:type 'natnum) :type 'natnum)
(defcustom image-dired-track-movement t (defcustom image-dired-track-movement t
"The current state of the tracking and mirroring. "The current state of the Image-Dired tracking and mirroring of thumbnails.
For more information, see the documentation for For more information, see the documentation of
`image-dired-toggle-movement-tracking'." `image-dired-toggle-movement-tracking'."
:type 'boolean) :type 'boolean)
@ -286,14 +287,14 @@ For more information, see the documentation for
"Display format for thumbnail properties. "Display format for thumbnail properties.
This is used for the header line in the Image-Dired buffer. This is used for the header line in the Image-Dired buffer.
The following %-specs are replaced by `format-spec' before The following %-specs in the value are replaced by `format-spec' before
displaying: displaying:
\"%f\" The file name (without a directory) of the \"%f\" The file name (without a directory) of the
original image file. original image file.
\"%n\" The number of this image out of the total (e.g. 1/10). \"%n\" The number of this image out of the total (e.g. 1/10).
\"%b\" The associated Dired buffer name. \"%b\" The associated Dired buffer name.
\"%d\" The name of the directory that the file is in. \"%d\" The name of the file's directory.
\"%s\" The image file size. \"%s\" The image file size.
\"%t\" The list of tags (from the Image-Dired database). \"%t\" The list of tags (from the Image-Dired database).
\"%c\" The comment (from the Image-Dired database)." \"%c\" The comment (from the Image-Dired database)."
@ -310,9 +311,9 @@ displaying:
((executable-find "xli") "xli") ((executable-find "xli") "xli")
((executable-find "qiv") "qiv -t") ((executable-find "qiv") "qiv -t")
((executable-find "xloadimage") "xloadimage")) ((executable-find "xloadimage") "xloadimage"))
"Name of external viewer. "Shell command to invoke the external image viewer program.
Including parameters. Used when displaying original image from Should include command-line arguments if needed. Used when displaying
`image-dired-thumbnail-mode'." original image from `image-dired-thumbnail-mode'."
:version "29.1" :version "29.1"
:type '(choice string :type '(choice string
(const :tag "Not Set" nil))) (const :tag "Not Set" nil)))
@ -325,14 +326,14 @@ Used by `image-dired-copy-with-exif-file-name'."
:version "29.1") :version "29.1")
(defcustom image-dired-show-all-from-dir-max-files 1000 (defcustom image-dired-show-all-from-dir-max-files 1000
"Maximum number of files in directory before prompting. "Maximum number of files in directory to show before prompting.
If there are more image files than this in a selected directory, If there are more image files in a selected directory than this number,
the `image-dired-show-all-from-dir' command will ask for the `image-dired-show-all-from-dir' command will ask for
confirmation before creating the thumbnail buffer. If this confirmation before creating the thumbnail buffer. If this
variable is nil, it will never ask." variable is nil, never ask."
:type '(choice integer :type '(choice integer
(const :tag "Disable warning" nil)) (const :tag "Don't ask for confirmation" nil))
:version "29.1") :version "29.1")
(defcustom image-dired-marking-shows-next t (defcustom image-dired-marking-shows-next t
@ -401,7 +402,7 @@ This affects the following commands:
(image-file-name-regexp))) (image-file-name-regexp)))
(defun image-dired-insert-image (file type relief margin) (defun image-dired-insert-image (file type relief margin)
"Insert image FILE of image TYPE, using RELIEF and MARGIN, at point." "Insert at point image FILE of image TYPE, using RELIEF and MARGIN."
(let ((i `(image :type ,type (let ((i `(image :type ,type
:file ,file :file ,file
:relief ,relief :relief ,relief
@ -495,9 +496,9 @@ by exactly one space or one newline character."
Convenience command that: Convenience command that:
- Opens Dired in folder DIR - opens Dired in folder DIR;
- Splits windows in most useful (?) way - splits windows in most useful (?) way; and
- Sets `truncate-lines' to t - sets `truncate-lines' to t
After the command has finished, you would typically mark some After the command has finished, you would typically mark some
image files in Dired and type image files in Dired and type
@ -525,7 +526,7 @@ calling `image-dired-restore-window-configuration'."
(other-window -2))))) (other-window -2)))))
(defun image-dired-restore-window-configuration () (defun image-dired-restore-window-configuration ()
"Restore window configuration. "Restore window configuration altered by Image-Dired.
Restore any changes to the window configuration made by calling Restore any changes to the window configuration made by calling
`image-dired-dired-with-window-configuration'." `image-dired-dired-with-window-configuration'."
(interactive nil image-dired-thumbnail-mode) (interactive nil image-dired-thumbnail-mode)
@ -632,7 +633,7 @@ never ask for confirmation."
;;; Movement tracking ;;; Movement tracking
(defun image-dired-track-original-file () (defun image-dired-track-original-file ()
"Track the original file in the associated Dired buffer. "Track in the associated Dired buffer the file that corresponds to thumbnail.
See `image-dired-toggle-movement-tracking'. Interactive use is See `image-dired-toggle-movement-tracking'. Interactive use is
only useful if `image-dired-track-movement' is nil." only useful if `image-dired-track-movement' is nil."
(interactive nil image-dired-thumbnail-mode image-dired-image-mode) (interactive nil image-dired-thumbnail-mode image-dired-image-mode)
@ -646,8 +647,8 @@ only useful if `image-dired-track-movement' is nil."
(defun image-dired-toggle-movement-tracking () (defun image-dired-toggle-movement-tracking ()
"Turn on and off `image-dired-track-movement'. "Turn on and off `image-dired-track-movement'.
Tracking of the movements between thumbnail and Dired buffer so that Tracking of the movements between thumbnail and Dired buffer so that
they are \"mirrored\" in the dired buffer. When this is on, moving the movements are \"mirrored\" in the Dired buffer. When this is on,
around in the thumbnail or dired buffer will find the matching moving around in the thumbnail or Dired buffer will move to the matching
position in the other buffer." position in the other buffer."
(interactive nil image-dired-thumbnail-mode image-dired-image-mode) (interactive nil image-dired-thumbnail-mode image-dired-image-mode)
(setq image-dired-track-movement (not image-dired-track-movement)) (setq image-dired-track-movement (not image-dired-track-movement))
@ -751,7 +752,9 @@ On reaching end or beginning of buffer, stop and show a message."
;;; Header line ;;; Header line
(defun image-dired-format-properties-string (buf file image-count props comment) (defun image-dired-format-properties-string (buf file image-count props comment)
"Format display properties. "Format display properties for Image-Dired.
The properties are formatted according to specification
in `image-dired-display-properties-format', which see.
BUF is the associated Dired buffer, FILE is the original image BUF is the associated Dired buffer, FILE is the original image
file name, IMAGE-COUNT is a string like \"N/M\" where N is the file name, IMAGE-COUNT is a string like \"N/M\" where N is the
number of this image and M is the total number of images, PROPS number of this image and M is the total number of images, PROPS
@ -816,7 +819,7 @@ for. The default is to look for `dired-marker-char'."
(image-dired-dired-file-marked-p dired-del-marker)) (image-dired-dired-file-marked-p dired-del-marker))
(defmacro image-dired--on-file-in-dired-buffer (&rest body) (defmacro image-dired--on-file-in-dired-buffer (&rest body)
"Run BODY with point on file at point in Dired buffer. "Run BODY in associated Dired buffer with point on current file's line.
Should be called from commands in `image-dired-thumbnail-mode'." Should be called from commands in `image-dired-thumbnail-mode'."
(declare (indent defun) (debug t)) (declare (indent defun) (debug t))
`(if-let ((file-name (image-dired-original-file-name))) `(if-let ((file-name (image-dired-original-file-name)))
@ -1192,7 +1195,8 @@ Ask user how many thumbnails should be displayed per row."
;;; Display image from thumbnail buffer ;;; Display image from thumbnail buffer
(defun image-dired-thumbnail-display-external () (defun image-dired-thumbnail-display-external ()
"Display original image for thumbnail at point using external viewer." "Display original image for thumbnail at point using external viewer.
The viewer command is specified by `image-dired-external-viewer'."
(interactive nil image-dired-thumbnail-mode) (interactive nil image-dired-thumbnail-mode)
(let ((file (image-dired-original-file-name))) (let ((file (image-dired-original-file-name)))
(if (not (image-dired-image-at-point-p)) (if (not (image-dired-image-at-point-p))
@ -1205,7 +1209,7 @@ Ask user how many thumbnails should be displayed per row."
(defun image-dired-display-image (file &optional _ignored) (defun image-dired-display-image (file &optional _ignored)
"Display image FILE in the image buffer window. "Display image FILE in the image buffer window.
If it is an image, the window will use `image-dired-image-mode' If FILE is an image, the window will use `image-dired-image-mode'
which is based on `image-mode'." which is based on `image-mode'."
(declare (advertised-calling-convention (file) "29.1")) (declare (advertised-calling-convention (file) "29.1"))
(setq file (expand-file-name file)) (setq file (expand-file-name file))
@ -1293,7 +1297,7 @@ overwritten. This confirmation can be turned off using
(defun image-dired-copy-filename-as-kill (&optional arg) (defun image-dired-copy-filename-as-kill (&optional arg)
"Copy names of marked (or next ARG) files into the kill ring. "Copy names of marked (or next ARG) files into the kill ring.
This works as `dired-copy-filename-as-kill' (which see)." This works like `dired-copy-filename-as-kill' (which see)."
(interactive "P" image-dired-thumbnail-mode) (interactive "P" image-dired-thumbnail-mode)
(image-dired--with-dired-buffer (image-dired--with-dired-buffer
(dired-copy-filename-as-kill arg))) (dired-copy-filename-as-kill arg)))

8
lisp/image/wallpaper.el
View file

@ -109,7 +109,7 @@ COMMAND is the executable to run to set the wallpaper.
ARGS is the default list of command line arguments for COMMAND. ARGS is the default list of command line arguments for COMMAND.
PREDICATE is a function that will be called without any arguments PREDICATE is a function that will be called without any arguments
and returns non-nil if this setter should be used. and should return non-nil if this setter should be used.
INIT-ACTION is a function that will be called without any INIT-ACTION is a function that will be called without any
arguments before trying to set the wallpaper. arguments before trying to set the wallpaper.
@ -304,7 +304,7 @@ order in which they appear.")
(throw 'found setter)))))))) (throw 'found setter))))))))
(defun wallpaper--find-command () (defun wallpaper--find-command ()
"Return a valid command to set the wallpaper in this environment." "Return the appropriate command to set the wallpaper."
(when-let ((setter (wallpaper--find-setter))) (when-let ((setter (wallpaper--find-setter)))
(wallpaper-setter-command setter))) (wallpaper-setter-command setter)))
@ -437,7 +437,7 @@ See also `wallpaper-default-width'.")
On a graphical display, try using the same monitor as the current On a graphical display, try using the same monitor as the current
frame. frame.
On a non-graphical display, try to get the name by connecting to On a non-graphical display, try to get the name by connecting to
the display server directly, and run \"xrandr\" if that doesn't the display server directly, or run \"xrandr\" if that doesn't
work. Prompt for the monitor name if neither method works. work. Prompt for the monitor name if neither method works.
This function is meaningful only on X and is used only there." This function is meaningful only on X and is used only there."
@ -469,7 +469,7 @@ This function is meaningful only on X and is used only there."
(read-string (format-prompt "Monitor name" nil))))) (read-string (format-prompt "Monitor name" nil)))))
(defun wallpaper--format-arg (format file) (defun wallpaper--format-arg (format file)
"Format a `wallpaper-command-args' argument ARG. "Format a `wallpaper-command-args' argument ARG using FORMAT.
FILE is the image file name." FILE is the image file name."
(format-spec (format-spec
format format