---

33.19.2 Изменение текстовых свойств

Примитивы для изменения свойств применяются к указанному диапазону текста в буфере или строке. Функция 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 (см. Свойства со специальным значением), например, именем лица или анонимным лицом (см. Лица).

Если какой-либо текст в регионе уже имеет не-nil свойство face, эти лица сохраняются. Эта функция устанавливает свойство 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. См. Модификация буфера.