函数 create-image、defimage 以及 find-image 提供了便捷的方式来创建图像描述符。
该函数创建并返回一个使用 file-or-data 中数据的图像描述符。file-or-data 可以是文件名,也可以是包含图像数据的字符串;对于前一种情况,data-p 应为 nil,后一种情况则为非 nil。若 file-or-data 为相对文件名,该函数会在 image-load-path 指定的目录中搜索该文件。
可选参数 type 是一个符号,用于指定图像类型。若省略 type 或其为 nil,create-image 会尝试通过文件的前几个字节或文件名来判断图像类型。
后续参数 props 用于指定额外的图像属性,例如:
(create-image "foo.xpm" 'xpm nil :mask 'heuristic)
See 图像描述符 可查看支持的属性列表。部分属性仅适用于特定图像类型,相关说明在对应类型的小节中。
若该类型图像不被支持,函数返回 nil,否则返回图像描述符。
该宏将 symbol 定义为一个图像名称。参数 specs 是一个列表,用于指定图像的显示方式。第三个参数 doc 是可选的文档字符串。
specs 中的每个参数均为属性列表形式,且每个参数至少应指定 :type 属性,以及 :file 或 :data 属性中的一个。:type 的取值为指定图像类型的符号,:file 的取值为加载图像的源文件,:data 的取值为包含实际图像数据的字符串。示例如下:
(defimage test-image ((:type xpm :file "~/test1.xpm") (:type xbm :file "~/test1.xbm")))
defimage 会逐一测试每个参数是否可用,即该类型是否被支持且对应文件存在。第一个可用的参数会被用于生成图像描述符,并存储在 symbol 中。
若所有备选方案均不可用,则 symbol 会被定义为 nil。
返回 image 中 property 属性的取值。可通过 setf 设置属性。将属性设为 nil 会从图像中移除该属性。
该函数提供了一种便捷方式,用于从图像规格列表 specs 中查找符合条件的图像。
specs 中的每个规格均为属性列表,具体内容依图像类型而定。所有规格至少需包含 :type type 属性,以及 :file file 或 :data data 中的一个。其中 type 为指定图像类型的符号(如 xbm),file 为图像加载源文件,data 为包含实际图像数据的字符串。列表中第一个类型受支持且文件存在的规格,会被用于构建并返回最终的图像规格。若无满足条件的规格,则返回 nil。
图像的搜索路径为 image-load-path。
该变量的值是一个路径列表,用于指定搜索图像文件的位置。若列表元素为字符串,或为值是字符串的变量符号,则该字符串作为待搜索的目录名。若元素为值是列表的变量符号,则该列表被视为待搜索的目录列表。
默认搜索顺序为:data-directory 指定目录下的 images 子目录、data-directory 指定的目录,最后是 load-path 中的各个目录。子目录不会被自动纳入搜索范围,因此若将图像文件置于子目录中,需显式写明子目录路径。例如,要查找 data-directory 下的 images/foo/bar.xpm 图像,应按如下方式指定:
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
该函数返回 Lisp 包 library 所用图像的合适搜索路径。
函数会先使用 image-load-path(排除 data-directory/images)搜索 image,再在 load-path 中搜索,随后在适用于 library 的路径中搜索(包括库文件自身相对路径下的 ../../etc/images 和 ../etc/images),最后在 data-directory/images 中搜索。
之后函数返回一个目录列表,首个目录为找到 image 的目录,后续为 load-path 的值。若指定了 path,则用其替代 load-path。
若 no-error 为非 nil 且未找到合适路径,不会抛出错误,而是照常返回目录列表,仅用 nil 替代图像所在目录。
以下是使用 image-load-path-for-library 的示例:
(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))
图像在创建时会依据 image-scaling-factor 变量自动缩放。该变量取值可以是浮点数(大于 1 表示放大图像,小于 1 表示缩小图像),或符号 auto(会根据字体像素尺寸自动计算缩放比例)。See 图像描述符。