(Defining Images): Add image-load-path-for-library.

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 9dbcd41f5a01983c1dfc2a6e98c9d31a16892d51..23e6b78b1302dfa49d4328c73e596741ef9e5c88 100644 (file)
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2006-03-11  Bill Wohler  <wohler@newt.com>
+
+       * display.texi (Defining Images): Add image-load-path-for-library.
+
 2006-03-11  Luc Teirlinck  <teirllm@auburn.edu>
 
        * text.texi (Adaptive Fill): Fix Texinfo usage.

diff --git a/lispref/display.texi b/lispref/display.texi
index b9d949a01ddb2f76f5b372a14ced659a2bccdf77..5053d7def3920ed86fca659fa81ca48042aca29c 100644 (file)
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -4125,6 +4125,35 @@ should specify the image as follows:
 @end example
 @end defvar
 
+@defun image-load-path-for-library library image &optional path no-error
+Return a suitable search path for images relative to @var{library}.
+
+Images for @var{library} are searched for in @file{../../etc/images}
+and @file{../etc/images} relative to the files in
+@file{lisp/@var{library}} as well as in @code{image-load-path} and
+@var{load-path}.
+
+This function returns the value of @code{load-path} augmented with the
+directory containing @var{image}. If @var{path} is given, it is used
+instead of @code{load-path}. If @code{path} is @code{t}, just return
+the directory that contains @var{image}.
+
+If @var{no-error} is non-nil, this function returns @code{nil} if a
+suitable path can't be found rather than signaling an error.
+
+Here is an example that uses a common idiom to provide compatibility
+with versions of Emacs that lack the variable @code{image-load-path}:
+
+@example
+(let ((load-path
+       (image-load-path-for-library "mh-e" "mh-logo.xpm"))
+      (image-load-path
+       (image-load-path-for-library "mh-e" "mh-logo.xpm"
+                                    'image-load-path)))
+  (mh-tool-bar-folder-buttons-init))
+@end example
+@end defun
+
 @node Showing Images
 @subsection Showing Images