From 0883e988ac950b2da2893e64822041ca0e6133a0 Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Sat, 20 Feb 2016 17:54:05 +1100
Subject: [PATCH] New functions for getting and setting image properties

* doc/lispref/display.texi (Defining Images): Document
image-get/set-property.

* lisp/image.el (image-set-property): New function.
(image-get-property): Ditto.
---
 doc/lispref/display.texi | 17 ++++++++++++++++-
 etc/NEWS                 |  9 ++++++++-
 lisp/image.el            | 20 ++++++++++++++++++++
 3 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 17025cd1994..3758ddf72f5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5205,7 +5205,9 @@ the size, and lower means to decrease the size.  For instance, a value
 of 0.25 will make the image a quarter size of what it originally was.
 If the scaling makes the image larger than specified by
 @code{:max-width} or @code{:max-height}, the resulting size will not
-exceed those two values.
+exceed those two values.  If both @code{:scale} and
+@code{:height}/@code{:width} are specified, the height/width will be
+adjusted by the specified scaling factor.
 
 @item :format @var{type}
 The value, @var{type}, should be a symbol specifying the type of the
@@ -5442,6 +5444,19 @@ If none of the alternatives will work, then @var{symbol} is defined
 as @code{nil}.
 @end defmac
 
+@defun image-set-property image property value
+Set the value of @var{property} in @var{image} to @var{value}.  If
+@var{value} is @code{nil}, the property is removed completely.
+
+@lisp
+(image-set-property image :height 300)
+@end lisp
+@end defun
+
+@defun image-get-property image property
+Return the value of @var{property} in @var{image}.
+@end defun
+
 @defun find-image specs
 This function provides a convenient way to find an image satisfying one
 of a list of image specifications @var{specs}.
diff --git a/etc/NEWS b/etc/NEWS
index c3c3ebab94d..95ca8d35385 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -846,6 +846,7 @@ of `epg-gpg-program' (instead of gpg).
 `image-scaling-factor' variable (if Emacs supports scaling the images
 in question).
 
++++
 *** Images inserted with `insert-image' and related functions get a
 keymap put into the text properties (or overlays) that span the
 image.  This keymap binds keystrokes for manipulating size and
@@ -853,7 +854,13 @@ rotation, as well as saving the image to a file.
 
 +++
 *** A new library for creating and manipulating SVG images has been
-added.  See the "SVG Images" section in the lispref manual for details.
+added.  See the "SVG Images" section in the lispref manual for
+details.
+
++++
+*** New functions to access and set image parameters are provided:
+`image-get-property' and `image-set-property'.
+
 
 ** Lisp mode
 
diff --git a/lisp/image.el b/lisp/image.el
index 855dffad293..3522c5bc75c 100644
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -435,6 +435,26 @@ Image file names that are not absolute are searched for in the
                        (image-compute-scaling-factor image-scaling-factor)))
 	    props)))
 
+(defun image-set-property (image property value)
+  "Set PROPERTY in IMAGE to VALUE.
+If VALUE is nil, PROPERTY is removed from IMAGE.  IMAGE is
+returned."
+  (if (null value)
+      (while (cdr image)
+        ;; IMAGE starts with the symbol `image', and the rest is a
+        ;; plist.  Decouple plist entries where the key matches
+        ;; the property.
+        (if (eq (cadr image) property)
+            (setcdr image (cddr image))
+          (setq image (cddr image))))
+    ;; Just enter the new value.
+    (plist-put (cdr image) property value))
+  image)
+
+(defun image-get-property (image property)
+  "Return the value of PROPERTY in IMAGE."
+  (plist-get (cdr image) property))
+
 (defun image-compute-scaling-factor (scaling)
   (cond
    ((numberp image-scaling-factor)
-- 
2.39.5