Изменение свойств текста

Примитивы для изменения свойств применяются к указанному диапазону текста в буфере или строке. Функция set-text-properties (см. конец раздела) устанавливает весь список свойств текста в этом диапазоне; чаще бывает полезно добавить, изменить или удалить только определенные свойства, указанные по имени.

Поскольку свойства текста считаются частью содержимого буфера (или строки) и могут влиять на то, как буфер отображается на экране, любое изменение свойств текста буфера отмечает буфер как измененный. Изменения свойств текста буфера также могут быть отменены (см. Отмена). Позиции в строке начинаются с 0, а в буфере — с 1.

Функция: put-text-property start end prop value &optional object

Эта функция устанавливает свойство prop в значение value для текста между start и end в строке или буфере object. Если object равно nil, по умолчанию используется текущий буфер.

Функция: add-text-properties start end props &optional object

Эта функция добавляет или перезаписывает свойства текста для текста между start и end в строке или буфере object. Если object равно nil, по умолчанию используется текущий буфер.

Аргумент props указывает, какие свойства добавить. Он должен иметь вид списка свойств (см. Списки свойств): список, элементы которого включают имена свойств, чередующиеся с соответствующими значениями.

Значение возврата равно t, если функция фактически изменила значение какого-либо свойства; nil, в противном случае (если props равно nil или его значения совпадают со значениями в тексте).

Например, вот как установить свойства comment и face диапазона текста:

(add-text-properties start end
                     '(comment t face highlight))

Функция: remove-text-properties start end props &optional object

Эта функция удаляет указанные свойства текста из текста между start и end в строке или буфере object. Если object равно nil, по умолчанию используется текущий буфер.

Аргумент props указывает, какие свойства удалить. Он должен иметь вид списка свойств (см. Списки свойств): список, элементы которого — имена свойств, чередующиеся с соответствующими значениями. Но важны только имена — значения, которые к ним прилагаются, игнорируются. Например, вот как удалить свойство face.

(remove-text-properties start end '(face nil))

Значение возврата равно t, если функция фактически изменила значение какого-либо свойства; nil, в противном случае (если props равно nil или ни один символ в указанном тексте не имел ни одного из этих свойств).

Чтобы удалить все свойства текста из определенного текста, используйте set-text-properties и укажите nil для нового списка свойств.

Функция: remove-list-of-text-properties start end list-of-properties &optional object

Как и remove-text-properties, за исключением того, что list-of-properties — это список только имён свойств, а не чередующийся список имён свойств и значений.

Функция: set-text-properties start end props &optional object

Эта функция полностью заменяет список свойств текста для текста между start и end в строке или буфере object. Если object равно nil, по умолчанию используется текущий буфер.

Аргумент props — новый список свойств. Он должен быть списком, элементы которого — имена свойств, чередующиеся с соответствующими значениями.

После того, как set-text-properties возвращает значение, у всех символов в указанном диапазоне одинаковые свойства.

Если props равно nil, это приводит к удалению всех свойств из указанного диапазона текста. Вот пример:

(set-text-properties start end nil)

Не полагайтесь на возвращаемое значение этой функции.

Функция: add-face-text-property start end face &optional appendp object

Эта функция действует на текст между start и end, добавляя лицо face к свойству текста face. face должно быть допустимым значением для свойства face (см. Специальные свойства), например, имя лица или анонимное лицо (см. Лица).

Если какой-либо текст в области уже имеет свойство face не равное nil, эти лица сохраняются. Эта функция устанавливает свойство face в список лиц, причём face является первым элементом (по умолчанию), а ранее существовавшие лица — остальными элементами. Если необязательный аргумент appendp отличен от nil, face добавляется в конец списка вместо этого. Обратите внимание, что в списке лиц первое встречающееся значение для каждого атрибута имеет приоритет.

Например, следующий код назначит курсивному зеленому лицу текст между start и end:

(add-face-text-property start end 'italic)
(add-face-text-property start end '(:foreground "red"))
(add-face-text-property start end '(:foreground "green"))

Необязательный аргумент object, если он отличен от nil, указывает на буфер или строку, с которой нужно работать, а не на текущий буфер. Если object является строкой, то start и end — индексы в строке с нулевым основанием.

Самый простой способ создать строку со свойствами текста — использовать propertize:

Функция: propertize string &rest properties

Эта функция возвращает копию string со свойствами текста properties, добавленными. Эти свойства применяются ко всем символам возвращаемой строки. Вот пример, который создаёт строку со свойством face и свойством mouse-face:

(propertize "foo" 'face 'italic
            'mouse-face 'bold-italic)
     ⇒ #("foo" 0 3 (mouse-face bold-italic face italic))

Чтобы поместить разные свойства в разные части строки, вы можете построить каждую часть с помощью propertize и затем объединить их с помощью concat:

(concat
 (propertize "foo" 'face 'italic
             'mouse-face 'bold-italic)
 " and "
 (propertize "bar" 'face 'italic
             'mouse-face 'bold-italic))
     ⇒ #("foo and bar"
                 0 3 (face italic mouse-face bold-italic)
                 3 8 nil
                 8 11 (face italic mouse-face bold-italic))

См. Содержимое буфера, для функции buffer-substring-no-properties, которая копирует текст из буфера, но не копирует его свойства.

Если вы хотите добавить свойства текста в буфер или удалить их, не отмечая буфер как изменённый, вы можете обернуть вышеупомянутые вызовы в макрос with-silent-modifications. См. Изменение буфера.