[elpa] externals/ebdb fbc49aae3b 6/7: Fix, document and improve record image display

[Eric Abrahamsen]

branch: externals/ebdb
commit fbc49aae3b5fc83dde0134c6f7f5cdf098094fc6
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Eric Abrahamsen <eric@ericabrahamsen.net>

    Fix, document and improve record image display
    
    * ebdb-com.el (ebdb-fmt-field): Fix plain old bug in call to
    `propertize' (girzel/ebdb#100).
    (ebdb-image-additional-plist): Add and use a new option allowing users
    to mess with image size (and other properties).
    * ebdb.el (ebdb-field-image-get): Fix this function to do what it says
    it does.
    * ebdb.org: Document image display in manual.
---
 ebdb-com.el |  25 ++++++++-
 ebdb.el     |  15 ++++--
 ebdb.info   | 169 +++++++++++++++++++++++++++++++++++++-----------------------
 ebdb.org    |  31 +++++++++++
 ebdb.texi   |  42 +++++++++++++++
 5 files changed, 212 insertions(+), 70 deletions(-)

diff --git a/ebdb-com.el b/ebdb-com.el
index ca482125c7..860ea12ee5 100644
--- a/ebdb-com.el
+++ b/ebdb-com.el
@@ -81,6 +81,25 @@ the *EBDB* buffer."
   :type '(choice (const :tag "Always fill" nil)
                  (const :tag "Never fill" t)))
 
+(defcustom ebdb-image-additional-plist '(:max-width (6 . em))
+  "Property list added to image data before display.
+The value should be a property list containing keys meaningful
+for image display; see the info node `(elisp)Image Descriptors'
+for details.
+
+Most often this option will be used to control the sizing of
+displayed images, using one or more of the :width, :height,
+:max-width, :max-height or :scale keys.  The first four keys take
+either an integer value, representing number of pixels, or a pair
+\"(VALUE . em)\", meaning a number of units relative to the
+current font size.  The :scale value should be a number (greater
+than or less than 1) representing a multiple of the original
+image size."
+  :type 'plist
+  :options '(:width :height :max-width :max-height :scale
+                   :ascent :margin :relief :rotation
+                   :transform-smoothing :mask))
+
 (defcustom ebdb-user-menu-commands nil
   "User defined menu entries which should be appended to the EBDB menu.
 This should be a list of menu entries.
@@ -702,10 +721,12 @@ record that actually owns the field."
   (if (display-images-p)
       (progn
        (require 'image)
-       (propertize
+       (apply
+        #'propertize
         " "
         ;; Cribbed from `insert-image'.
-        (list 'display (ebdb-field-image-get field record)
+        (list 'display (append (ebdb-field-image-get field record)
+                               ebdb-image-additional-plist)
                'rear-nonsticky '(display)
                'keymap image-map)))
     "<img>"))
diff --git a/ebdb.el b/ebdb.el
index c64cf2e8a7..9f88bdb7b7 100644
--- a/ebdb.el
+++ b/ebdb.el
@@ -320,6 +320,7 @@ called with two arguments: the image field and the record.  
The
 function should return either a filename, or actual image data."
   :group 'ebdb-record-edit
   :type '(choice (const :tag "Use built-in function" nil)
+                (string :tag "File name")
                  (const name)
                 (const fl-name)
                 (const lf-name)))
@@ -3277,13 +3278,21 @@ there is no timezone value."
 This function returns an actual image, suitable for display with
 `insert-image'."
   (let* ((image-slot (slot-value field 'image))
+        (name-instance (slot-value record 'name))
         (image
          (cond ((stringp image-slot)
                 image-slot)
-               ((eq image-slot 'name)
-                (ebdb-string record))
+               ((memq image-slot '(name fl-name lf-name))
+                (cond ((or (eq image-slot 'name)
+                           (null (cl-typep name-instance
+                                           'ebdb-field-name-complex)))
+                       (ebdb-string name-instance))
+                      ((eq image-slot 'lf-name)
+                       (ebdb-name-lf name-instance))
+                      ((eq image-slot 'fl-name)
+                       (ebdb-name-fl name-instance))))
                (t
-                (ebdb-field-image-function ebdb-image record)))))
+                (ebdb-field-image-function field record)))))
     (when image
       (create-image
        (if (stringp image)
diff --git a/ebdb.info b/ebdb.info
index 8bf5fbefb1..f17ca9b158 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -118,6 +118,7 @@ EBDB Buffers
 * The Basics of ebdb-mode::
 * Customizing Record Display::
 * Marking::
+* Image Display::
 * Exporting/Formatting::
 
 Searching
@@ -1181,6 +1182,7 @@ existing EBDB buffers.
 * The Basics of ebdb-mode::
 * Customizing Record Display::
 * Marking::
+* Image Display::
 * Exporting/Formatting::
 
 
@@ -1503,7 +1505,7 @@ to get things exactly right, but the general signature 
looks like:
 ‘compact’, and ‘collapse’.
 
 
-File: ebdb.info,  Node: Marking,  Next: Exporting/Formatting,  Prev: 
Customizing Record Display,  Up: EBDB Buffers
+File: ebdb.info,  Node: Marking,  Next: Image Display,  Prev: Customizing 
Record Display,  Up: EBDB Buffers
 
 7.4 Marking
 ===========
@@ -1514,9 +1516,40 @@ records in the buffer, and ‘C-#’ unmarks all records in 
the buffer.
 Many editing commands can act on multiple marked records.
 
 
-File: ebdb.info,  Node: Exporting/Formatting,  Prev: Marking,  Up: EBDB Buffers
+File: ebdb.info,  Node: Image Display,  Next: Exporting/Formatting,  Prev: 
Marking,  Up: EBDB Buffers
 
-7.5 Exporting/Formatting
+7.5 Image Display
+=================
+
+Records can have an image associated with them, by adding an instance of
+‘ebdb-field-image’.  The actual image is not stored in the database, but
+in some external location which the field instance points to.  This
+pointer can be:
+
+   • An absolute file path
+   • A relative file path, in which case the function ‘locate-file’ will
+     be used to find the image, in conjunction with ‘ebdb-image-path’
+     and ‘ebdb-image-suffixes’
+   • One of the symbols ‘name’, ‘lf-name’, or ‘fl-name’, in which case
+     the record’s name will be used to construct a relative file path,
+     to be used as above.
+   • Any other value, in which case the function
+     ‘ebdb-field-image-function’ will be called with the image field and
+     record as arguments.  This function is a generic method, and is
+     unimplemented by default.
+
+   The option ‘ebdb-image’ controls which of these methods to use by
+default, though separate methods can be chosen for each field instance.
+
+   Lastly, display of the image can be controlled with the option
+‘ebdb-image-addition-plist’.  The value should be a plist suitable for
+merging with Emacs’ image data, see *note Image Descriptors:
+(elisp)Image%20Descriptors. for more information.
+
+
+File: ebdb.info,  Node: Exporting/Formatting,  Prev: Image Display,  Up: EBDB 
Buffers
+
+7.6 Exporting/Formatting
 ========================
 
 It is possible to export (referred to as “formatting”) records in
@@ -2423,6 +2456,7 @@ File: ebdb.info,  Node: Index,  Prev: Hacking EBDB,  Up: 
Top
                                                               (line   6)
 * Diary integration:                     Diary Integration.   (line   6)
 * disabled of Database:                  The EBDB Database.   (line  31)
+* Displaying images:                     Image Display.       (line   6)
 * e:                                     Editing Existing Fields.
                                                               (line   6)
 * E:                                     Editing Existing Fields.
@@ -2533,6 +2567,10 @@ File: ebdb.info,  Node: Index,  Prev: Hacking EBDB,  Up: 
Top
                                                               (line  47)
 * ebdb-ignore-header-list:               Auto-Updating Records.
                                                               (line  73)
+* ebdb-image:                            Image Display.       (line   6)
+* ebdb-image-additional-plist:           Image Display.       (line   6)
+* ebdb-image-path:                       Image Display.       (line   6)
+* ebdb-image-suffixes:                   Image Display.       (line   6)
 * ebdb-info:                             The Basics of ebdb-mode.
                                                               (line 118)
 * ebdb-init-field:                       Init and Delete Methods.
@@ -2764,68 +2802,69 @@ File: ebdb.info,  Node: Index,  Prev: Hacking EBDB,  
Up: Top
 
 Tag Table:
 Node: Top807
-Node: Getting Started2680
-Node: Starting a New Database4630
-Node: Migration from BBDB5454
-Node: Record Migration5697
-Node: Variables and Options6759
-Node: Migration from Org Contacts7246
-Node: The EBDB Database8006
-Node: Creating Records12167
-Node: Record classes13248
-Node: Record names13593
-Node: Record Fields14268
-Node: Inserting New Fields14512
-Node: Editing Existing Fields15308
-Node: Deleting Records and Fields15908
-Node: Field Types16304
-Node: Role fields18590
-Node: Tag field20956
-Node: Mail folder field21525
-Node: MUA Interaction21853
-Node: Loading MUA Code22406
-Node: Display and Updating23119
-Node: Pop-up Buffers23885
-Node: Auto-Updating Records26735
-Node: Noticing and Automatic Rules31529
-Node: Interactive Commands33351
-Node: EBDB and MUA summary buffers35825
-Node: Sender name display36343
-Node: Summary buffer marks37570
-Node: Mail Address Completion38749
-Node: A Note on Completion41258
-Node: Specific MUAs41881
-Node: Gnus42029
-Node: Posting Styles42251
-Node: EBDB Buffers43807
-Node: Searching45018
-Node: Changing Search Behavior46732
-Node: The Basics of ebdb-mode47979
-Node: Customizing Record Display52327
-Node: Marking56647
-Node: Exporting/Formatting57074
-Node: Completion58009
-Node: Snarfing58805
-Node: Internationalization60822
-Node: Diary Integration63523
-Node: Mail Aliases64216
-Node: vCard Support64930
-Node: Org Integration65429
-Node: Citing Records67463
-Node: Hacking EBDB68221
-Node: Field Classes70814
-Node: Init and Delete Methods73995
-Node: Manipulating Field Data Programmatically75519
-Node: The Labeled Field Class77231
-Node: The Singleton Field Class78102
-Node: Actions78540
-Node: Custom Field Searching79212
-Node: Fast Lookups82079
-Node: Formatting in the EBDB Buffer83889
-Node: Writing Internationalization Libraries85965
-Node: Writing Integration For New MUAs90381
-Node: Article snarfing93829
-Node: Index94547
+Node: Getting Started2698
+Node: Starting a New Database4648
+Node: Migration from BBDB5472
+Node: Record Migration5715
+Node: Variables and Options6777
+Node: Migration from Org Contacts7264
+Node: The EBDB Database8024
+Node: Creating Records12185
+Node: Record classes13266
+Node: Record names13611
+Node: Record Fields14286
+Node: Inserting New Fields14530
+Node: Editing Existing Fields15326
+Node: Deleting Records and Fields15926
+Node: Field Types16322
+Node: Role fields18608
+Node: Tag field20974
+Node: Mail folder field21543
+Node: MUA Interaction21871
+Node: Loading MUA Code22424
+Node: Display and Updating23137
+Node: Pop-up Buffers23903
+Node: Auto-Updating Records26753
+Node: Noticing and Automatic Rules31547
+Node: Interactive Commands33369
+Node: EBDB and MUA summary buffers35843
+Node: Sender name display36361
+Node: Summary buffer marks37588
+Node: Mail Address Completion38767
+Node: A Note on Completion41276
+Node: Specific MUAs41899
+Node: Gnus42047
+Node: Posting Styles42269
+Node: EBDB Buffers43825
+Node: Searching45054
+Node: Changing Search Behavior46768
+Node: The Basics of ebdb-mode48015
+Node: Customizing Record Display52363
+Node: Marking56683
+Node: Image Display57103
+Node: Exporting/Formatting58511
+Node: Completion59452
+Node: Snarfing60248
+Node: Internationalization62265
+Node: Diary Integration64966
+Node: Mail Aliases65659
+Node: vCard Support66373
+Node: Org Integration66872
+Node: Citing Records68906
+Node: Hacking EBDB69664
+Node: Field Classes72257
+Node: Init and Delete Methods75438
+Node: Manipulating Field Data Programmatically76962
+Node: The Labeled Field Class78674
+Node: The Singleton Field Class79545
+Node: Actions79983
+Node: Custom Field Searching80655
+Node: Fast Lookups83522
+Node: Formatting in the EBDB Buffer85332
+Node: Writing Internationalization Libraries87408
+Node: Writing Integration For New MUAs91824
+Node: Article snarfing95272
+Node: Index95990
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index d7943380cd..54f24ee93c 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -1449,6 +1449,37 @@ toggle the mark of the record under point.  
{{{kbd(M-#)}}} will toggle
 the marks of all the records in the buffer, and {{{kbd(C-#)}}} unmarks
 all records in the buffer.  Many  editing commands can act on multiple
 marked records.
+** Image Display
+#+CINDEX: Displaying images
+#+VINDEX: ebdb-image-path
+#+VINDEX: ebdb-image-suffixes
+#+VINDEX: ebdb-image-additional-plist
+#+VINDEX: ebdb-image
+Records can have an image associated with them, by adding an instance
+of ~ebdb-field-image~.  The actual image is not stored in the
+database, but in some external location which the field instance
+points to.  This pointer can be:
+
+- An absolute file path
+- A relative file path, in which case the function ~locate-file~ will
+  be used to find the image, in conjunction with ~ebdb-image-path~ and
+  ~ebdb-image-suffixes~
+- One of the symbols ~name~, ~lf-name~, or ~fl-name~, in which case
+  the record's name will be used to construct a relative file path, to
+  be used as above.
+- Any other value, in which case the function
+  ~ebdb-field-image-function~ will be called with the image field and
+  record as arguments.  This function is a generic method, and is
+  unimplemented by default.
+
+The option ~ebdb-image~ controls which of these methods to use by
+default, though separate methods can be chosen for each field
+instance.
+
+Lastly, display of the image can be controlled with the option
+~ebdb-image-addition-plist~.  The value should be a plist suitable for
+merging with Emacs' image data, see [[info:elisp#Image%20Descriptors][Image 
Descriptors]] for more
+information.
 ** Exporting/Formatting
 :PROPERTIES:
 :ID:       0f72cc06-99e4-45b1-aa32-14e909f0765e
diff --git a/ebdb.texi b/ebdb.texi
index 3283a711a5..c712915b68 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -141,6 +141,7 @@ EBDB Buffers
 * The Basics of ebdb-mode::
 * Customizing Record Display::
 * Marking::
+* Image Display::
 * Exporting/Formatting::
 
 Searching
@@ -1256,6 +1257,7 @@ recreated next time the MUA requests another pop up.
 * The Basics of ebdb-mode::
 * Customizing Record Display::
 * Marking::
+* Image Display::
 * Exporting/Formatting::
 @end menu
 
@@ -1680,6 +1682,46 @@ the marks of all the records in the buffer, and 
@kbd{C-#} unmarks
 all records in the buffer.  Many  editing commands can act on multiple
 marked records.
 
+@node Image Display
+@section Image Display
+
+@cindex Displaying images
+@vindex ebdb-image-path
+@vindex ebdb-image-suffixes
+@vindex ebdb-image-additional-plist
+@vindex ebdb-image
+Records can have an image associated with them, by adding an instance
+of @code{ebdb-field-image}.  The actual image is not stored in the
+database, but in some external location which the field instance
+points to.  This pointer can be:
+
+@itemize
+@item
+An absolute file path
+@item
+A relative file path, in which case the function @code{locate-file} will
+be used to find the image, in conjunction with @code{ebdb-image-path} and
+@code{ebdb-image-suffixes}
+@item
+One of the symbols @code{name}, @code{lf-name}, or @code{fl-name}, in which 
case
+the record's name will be used to construct a relative file path, to
+be used as above.
+@item
+Any other value, in which case the function
+@code{ebdb-field-image-function} will be called with the image field and
+record as arguments.  This function is a generic method, and is
+unimplemented by default.
+@end itemize
+
+The option @code{ebdb-image} controls which of these methods to use by
+default, though separate methods can be chosen for each field
+instance.
+
+Lastly, display of the image can be controlled with the option
+@code{ebdb-image-addition-plist}.  The value should be a plist suitable for
+merging with Emacs' image data, see @ref{Image%20Descriptors,Image 
Descriptors,,elisp,} for more
+information.
+
 @node Exporting/Formatting
 @section Exporting/Formatting