branch: externals/ebdb
commit fbc49aae3b5fc83dde0134c6f7f5cdf098094fc6
Author: Eric Abrahamsen <e...@ericabrahamsen.net>
Commit: Eric Abrahamsen <e...@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
