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

Функции 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, который вычисляет коэффициент масштабирования на основе размера шрифта в пикселях. См. раздел Дескрипторы изображений.