Определение кликабельного текста

Кликабельный текст — это текст, по которому можно щёлкнуть мышью или с помощью команды клавиатуры, чтобы получить определённый результат. Во многих основных режимах кликабельный текст используется для реализации текстовых гиперссылок, или просто ссылок.

Самый простой способ вставлять ссылки и управлять ими — использовать пакет button. См. раздел Кнопки. В этом разделе мы объясним, как вручную настроить кликабельный текст в буфере с помощью текстовых свойств. Для простоты мы будем называть кликабельный текст ссылкой.

Реализация ссылки включает три отдельных шага: (1) указать, что по ней можно щёлкнуть, когда указатель мыши находится над ссылкой; (2) настроить выполнение действия при нажатии RET или mouse-2 на ссылке; и (3) настроить условие follow-link, чтобы ссылка подчинялась mouse-1-click-follows-link.

Чтобы указать, что по тексту можно щёлкнуть, добавьте к тексту ссылки текстовое свойство mouse-face; тогда Emacs будет выделять ссылку, когда указатель мыши находится над ней. Кроме того, следует задать подсказку или сообщение в области эха с помощью текстового свойства help-echo. См. раздел Свойства со специальным значением. Например, вот как Dired указывает, что по именам файлов можно щёлкнуть:

 (if (dired-move-to-filename)
     (add-text-properties
       (point)
       (save-excursion
         (dired-move-to-end-of-filename)
         (point))
       '(mouse-face highlight
         help-echo "mouse-2: visit this file in other window")))

Чтобы сделать ссылку кликабельной, привяжите клавиши RET и mouse-2 к командам, выполняющим нужное действие. Каждая команда должна проверять, была ли она вызвана для ссылки, и действовать соответствующим образом. Например, карта клавиш основного режима Dired привязывает mouse-2 к следующей команде:

(defun dired-mouse-find-file-other-window (event)
  "In Dired, visit the file or directory name you click on."
  (interactive "e")
  (let ((window (posn-window (event-end event)))
        (pos (posn-point (event-end event)))
        file)
    (if (not (windowp window))
        (error "No file chosen"))
    (with-current-buffer (window-buffer window)
      (goto-char pos)
      (setq file (dired-get-file-for-visit)))
    (if (file-directory-p file)
        (or (and (cdr dired-subdir-alist)
                 (dired-goto-subdir file))
            (progn
              (select-window window)
              (dired-other-window file)))
      (select-window window)
      (find-file-other-window (file-name-sans-versions file t)))))

Эта команда использует функции posn-window и posn-point, чтобы определить, где произошёл щелчок, и dired-get-file-for-visit, чтобы определить, какой файл открыть.

Вместо привязки команды мыши в карте клавиш основного режима можно привязать её непосредственно к тексту ссылки с помощью текстового свойства keymap (см. раздел Свойства со специальным значением). Например:

(let ((map (make-sparse-keymap)))
  (keymap-set map "<mouse-2>" 'operate-this-button)
  (put-text-property link-start link-end 'keymap map))

Этот способ позволяет легко задавать разные команды для разных ссылок. Кроме того, глобальные определения RET и mouse-2 остаются доступными для остального текста в буфере.

Основная команда Emacs для щелчка по ссылкам — mouse-2. Однако для совместимости с другими графическими приложениями Emacs также распознаёт щелчки mouse-1 по ссылкам, если пользователь быстро щёлкает по ссылке, не перемещая мышь. Это поведение управляется пользовательской опцией mouse-1-click-follows-link. См. раздел Ссылки на мышь в Руководстве GNU Emacs.

Чтобы настроить ссылку так, чтобы она подчинялась mouse-1-click-follows-link, необходимо либо (1) применить к тексту ссылки текстовое свойство или свойство наложения follow-link, либо (2) привязать событие follow-link к карте клавиш (это может быть карта клавиш основного режима или локальная карта клавиш, заданная с помощью текстового свойства keymap). Значение свойства follow-link или привязка события follow-link выступает условием действия ссылки. Это условие сообщает Emacs две вещи: при каких обстоятельствах щелчок mouse-1 следует считать произошедшим внутри ссылки и как вычислить код действия, указывающий, во что преобразовать щелчок mouse-1. Условие действия ссылки может быть одним из следующих:

mouse-face

Если условием является символ mouse-face, позиция находится внутри ссылки, если в этой позиции имеется свойство mouse-face, отличное от nil. Код действия всегда равен t.

Например, вот как режим Info обрабатывает mouse-1:

(keymap-set Info-mode-map "<follow-link>" 'mouse-face)

функция

Если условием является функция func, позиция pos находится внутри ссылки, если вычисление (func pos) возвращает значение, отличное от nil. Значение, возвращаемое func, служит кодом действия.

Например, вот как pcvs позволяет с помощью mouse-1 переходить по ссылкам только в именах файлов:

(keymap-set map "<follow-link>"
            (lambda (pos)
              (eq (get-char-property pos 'face) 'cvs-filename-face)))

любое другое значение

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

Код действия указывает mouse-1, как перейти по ссылке:

строка или вектор

Если код действия — строка или вектор, событие mouse-1 преобразуется в первый элемент строки или вектора; то есть действием щелчка mouse-1 становится локальная или глобальная привязка соответствующего символа или знака. Так, если код действия равен "foo", событие mouse-1 преобразуется в f. Если он равен [foo], событие mouse-1 преобразуется в foo.

любое другое значение

Для любого другого кода действия, отличного от nil, событие mouse-1 преобразуется в событие mouse-2 в той же позиции.

Чтобы настроить mouse-1 для активации кнопки, определённой с помощью define-button-type, задайте кнопке свойство follow-link. Значение свойства должно быть условием действия ссылки, как описано выше. См. раздел Кнопки. Например, вот как режим Help обрабатывает mouse-1:

(define-button-type 'help-xref
  'follow-link t
  'action #'help-button-action)

Чтобы настроить mouse-1 для виджета, определённого с помощью define-widget, задайте виджету свойство :follow-link. Значение свойства должно быть условием действия ссылки, как описано выше. Например, вот как виджет link указывает, что щелчок mouse-1 следует преобразовать в RET:

(define-widget 'link 'item
  "An embedded link."
  :button-prefix 'widget-link-prefix
  :button-suffix 'widget-link-suffix
  :follow-link "\C-m"
  :help-echo "Follow the link."
  :format "%[%t%]")

Функция: mouse-on-link-p pos

Эта функция возвращает значение, отличное от nil, если позиция pos в текущем буфере находится на ссылке. pos также может быть местоположением события мыши, возвращаемым функцией event-start (см. раздел Доступ к событиям мыши).