new repository

1 files changed, 41 insertions, 0 deletions

diff --git a/devdocs/elisp/defining-images.html b/devdocs/elisp/defining-images.html
new file mode 100644
index 00000000..51bdc4b9
--- /dev/null
+++ b/devdocs/elisp/defining-images.html
@@ -0,0 +1,41 @@
+ <h4 class="subsection">Defining Images</h4>  <p>The functions <code>create-image</code>, <code>defimage</code> and <code>find-image</code> provide convenient ways to create image descriptors. </p> <dl> <dt id="create-image">Function: <strong>create-image</strong> <em>file-or-data &amp;optional type data-p &amp;rest props</em>
+</dt> <dd>
+<p>This function creates and returns an image descriptor which uses the data in <var>file-or-data</var>. <var>file-or-data</var> can be a file name or a string containing the image data; <var>data-p</var> should be <code>nil</code> for the former case, non-<code>nil</code> for the latter case. </p> <p>The optional argument <var>type</var> is a symbol specifying the image type. If <var>type</var> is omitted or <code>nil</code>, <code>create-image</code> tries to determine the image type from the file’s first few bytes, or else from the file’s name. </p> <p>The remaining arguments, <var>props</var>, specify additional image properties—for example, </p> <div class="example"> <pre class="example">(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
+</pre>
+</div> <p>The function returns <code>nil</code> if images of this type are not supported. Otherwise it returns an image descriptor. </p>
+</dd>
+</dl> <dl> <dt id="defimage">Macro: <strong>defimage</strong> <em>symbol specs &amp;optional doc</em>
+</dt> <dd>
+<p>This macro defines <var>symbol</var> as an image name. The arguments <var>specs</var> is a list which specifies how to display the image. The third argument, <var>doc</var>, is an optional documentation string. </p> <p>Each argument in <var>specs</var> has the form of a property list, and each one should specify at least the <code>:type</code> property and either the <code>:file</code> or the <code>:data</code> property. The value of <code>:type</code> should be a symbol specifying the image type, the value of <code>:file</code> is the file to load the image from, and the value of <code>:data</code> is a string containing the actual image data. Here is an example: </p> <div class="example"> <pre class="example">(defimage test-image
+  ((:type xpm :file "~/test1.xpm")
+   (:type xbm :file "~/test1.xbm")))
+</pre>
+</div> <p><code>defimage</code> tests each argument, one by one, to see if it is usable—that is, if the type is supported and the file exists. The first usable argument is used to make an image descriptor which is stored in <var>symbol</var>. </p> <p>If none of the alternatives will work, then <var>symbol</var> is defined as <code>nil</code>. </p>
+</dd>
+</dl> <dl> <dt id="image-property">Function: <strong>image-property</strong> <em>image property</em>
+</dt> <dd><p>Return the value of <var>property</var> in <var>image</var>. Properties can be set by using <code>setf</code>. Setting a property to <code>nil</code> will remove the property from the image. </p></dd>
+</dl> <dl> <dt id="find-image">Function: <strong>find-image</strong> <em>specs</em>
+</dt> <dd>
+<p>This function provides a convenient way to find an image satisfying one of a list of image specifications <var>specs</var>. </p> <p>Each specification in <var>specs</var> is a property list with contents depending on image type. All specifications must at least contain the properties <code>:type <var>type</var></code> and either <code>:file <var>file</var></code> or <code>:data <var>data</var></code>, where <var>type</var> is a symbol specifying the image type, e.g., <code>xbm</code>, <var>file</var> is the file to load the image from, and <var>data</var> is a string containing the actual image data. The first specification in the list whose <var>type</var> is supported, and <var>file</var> exists, is used to construct the image specification to be returned. If no specification is satisfied, <code>nil</code> is returned. </p> <p>The image is looked for in <code>image-load-path</code>. </p>
+</dd>
+</dl> <dl> <dt id="image-load-path">User Option: <strong>image-load-path</strong>
+</dt> <dd>
+<p>This variable’s value is a list of locations in which to search for image files. If an element is a string or a variable symbol whose value is a string, the string is taken to be the name of a directory to search. If an element is a variable symbol whose value is a list, that is taken to be a list of directories to search. </p> <p>The default is to search in the <samp>images</samp> subdirectory of the directory specified by <code>data-directory</code>, then the directory specified by <code>data-directory</code>, and finally in the directories in <code>load-path</code>. Subdirectories are not automatically included in the search, so if you put an image file in a subdirectory, you have to supply the subdirectory explicitly. For example, to find the image <samp>images/foo/bar.xpm</samp> within <code>data-directory</code>, you should specify the image as follows: </p> <div class="example"> <pre class="example">(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="image-load-path-for-library">Function: <strong>image-load-path-for-library</strong> <em>library image &amp;optional path no-error</em>
+</dt> <dd>
+<p>This function returns a suitable search path for images used by the Lisp package <var>library</var>. </p> <p>The function searches for <var>image</var> first using <code>image-load-path</code>, excluding <samp><code>data-directory</code>/images</samp>, and then in <code>load-path</code>, followed by a path suitable for <var>library</var>, which includes <samp>../../etc/images</samp> and <samp>../etc/images</samp> relative to the library file itself, and finally in <samp><code>data-directory</code>/images</samp>. </p> <p>Then this function returns a list of directories which contains first the directory in which <var>image</var> was found, followed by the value of <code>load-path</code>. If <var>path</var> is given, it is used instead of <code>load-path</code>. </p> <p>If <var>no-error</var> is non-<code>nil</code> and a suitable path can’t be found, don’t signal an error. Instead, return a list of directories as before, except that <code>nil</code> appears in place of the image directory. </p> <p>Here is an example of using <code>image-load-path-for-library</code>: </p> <div class="example"> <pre class="example">(defvar image-load-path) ; shush compiler
+(let* ((load-path (image-load-path-for-library
+                    "mh-e" "mh-logo.xpm"))
+       (image-load-path (cons (car load-path)
+                              image-load-path)))
+  (mh-tool-bar-folder-buttons-init))
+</pre>
+</div> </dd>
+</dl>  <p>Images are automatically scaled when created based on the <code>image-scaling-factor</code> variable. The value is either a floating point number (where numbers higher than 1 means to increase the size and lower means to shrink the size), or the symbol <code>auto</code>, which will compute a scaling factor based on the font pixel size. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Images.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Images.html</a>
+  </p>
+</div>