---

42.17.8 Определение изображений

Функции create-image, defimage и find-image предоставляют удобные способы создания дескрипторов изображений.

Функция: create-image file-or-data &optional type data-p &rest props ¶

Эта функция создает и возвращает дескриптор изображения, который использует данные из 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)

См. Дескрипторы изображений для списка поддерживаемых свойств. Некоторые свойства специфичны для определенных типов изображений и описаны в подразделах, посвященных этим типам.

Функция возвращает nil, если изображения этого типа не поддерживаются. В противном случае она возвращает дескриптор изображения.

Макрос: defimage symbol specs &optional doc ¶

Этот макрос определяет 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 image property ¶

Возвращает значение property в image. Свойства можно устанавливать с помощью setf. Установка свойства в nil удалит его из изображения.

Функция: find-image specs ¶

Эта функция предоставляет удобный способ найти изображение, удовлетворяющее одному из списка спецификаций изображений specs.

Каждая спецификация в specs — это список свойств, содержимое которого зависит от типа изображения. Все спецификации должны содержать как минимум свойства :type type и либо :file file либо :data data, где type — это символ, указывающий тип изображения, например, xbm, file — это файл, из которого загружается изображение, а data — это строка, содержащая фактические данные изображения. Первая спецификация в списке, чей type поддерживается, и file существует, используется для построения спецификации изображения, которая будет возвращена. Если ни одна спецификация не удовлетворена, возвращается nil.

Поиск изображения осуществляется в image-load-path.

Пользовательский вариант: image-load-path ¶

Значение этой переменной — это список мест, в которых следует искать файлы изображений. Если элемент является строкой или символом переменной, значение которого является строкой, эта строка считается именем каталога для поиска. Если элемент — это символ переменной, значение которого является списком, то это считается списком каталогов для поиска.

По умолчанию поиск осуществляется в подкаталоге images каталога, указанного в data-directory, затем в каталоге, указанном в data-directory, и, наконец, в каталогах, указанных в load-path. Подкаталоги не включаются в поиск автоматически, поэтому, если вы поместите файл изображения в подкаталог, вам придется явно указать этот подкаталог. Например, чтобы найти изображение images/foo/bar.xpm внутри data-directory, следует указать изображение следующим образом:

(defimage foo-image '((:type xpm :file "foo/bar.xpm")))

Функция: image-load-path-for-library library image &optional path no-error ¶

Эта функция возвращает подходящий путь поиска для изображений, используемых Lisp-пакетом library.

Функция сначала ищет image с использованием image-load-path, исключая data-directory/images, а затем в 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 означают увеличение размера, а меньшие — уменьшение), либо символом auto, который вычислит коэффициент масштабирования на основе размера шрифта. См. Дескрипторы изображений.