changeset 31373:a3fd71daf442

help-echo stuff, find-image, image-size.

--- a/lispref/display.texi	Mon Sep 04 13:55:53 2000 +0000
+++ b/lispref/display.texi	Mon Sep 04 13:57:47 2000 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
 @c   Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/display
@@ -822,10 +822,10 @@
 
 @item help-echo
 @kindex help-echo @r{(text property)}
-If an overlay has a string as its @code{help-echo} property, then when
-you move the mouse onto the text in the overlay, Emacs displays that
-string in the echo area, or in the tooltip window.  This feature is
-available starting in Emacs 21.
+If an overlay has a @code{help-echo} property, then when you move the
+mouse onto the text in the overlay, Emacs displays a help string in the
+echo area, or in the tooltip window.  For details see @ref{Text
+help-echo}.  This feature is available starting in Emacs 21.
 
 @item modification-hooks
 @kindex modification-hooks @r{(overlay property)}
@@ -2621,8 +2621,8 @@
 @node Defining Images
 @subsection Defining Images
 
-  The functions @code{create-image} and @code{defimage} provide
-convenient ways to create image descriptors.
+  The functions @code{create-image}, @code{defimage} and
+@code{find-image} provide convenient ways to create image descriptors.
 
 @defun create-image file &optional type &rest props
 @tindex create-image
@@ -2670,6 +2670,25 @@
 as @code{nil}.
 @end defmac
 
+@defun find-image specs
+@tindex find-image
+This function provides a convenient way to find an image satisfying one
+of a list of image specifications @var{specs}.
+
+Each specification in @var{specs} is a property list with contents
+depending on image type.  All specifications must at least contain the
+properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
+or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
+image from, and @var{data} is a string containing the actual image data.
+The first specification in the list whose @var{type} is supported, and
+@var{file} exists, is used to construct the image specification to be
+returned.  If no specification is satisfied, @code{nil} is returned.
+
+The image is looked for first on @code{load-path} and then in
+@code{data-directory}.
+@end defun
+
 @node Showing Images
 @subsection Showing Images
 
@@ -2726,6 +2745,17 @@
 @code{insert-image} or in other ways.
 @end defun
 
+@defun image-size spec &optional pixels frame
+@tindex image-size
+This function returns the size of an image as a pair
+@w{@code{(@var{width} . @var{height})}}.  @var{spec} is an image
+specification.  @var{pixels} non-nil means return sizes measured in
+pixels, otherwise return sizes measured in canonical character units
+(fractions of the width/height of the frame's default font).
+@var{frame} is the frame on which the image will be displayed.
+@var{frame} null or omitted means use the selected frame.
+@end defun
+
 @node Image Cache
 @subsection Image Cache