Контекстная помощь

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

Вызов контекстной помощи возможен одним из следующих способов:

В отличие от всплывающей подсказки (tooltip), появляющейся при наведении указателя мыши на интересующий элемент, контекстная подсказка

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

Идентификатор помощи

Идентификатор помощи обычно хранится в слоте help-key экземпляров класса capi::simple-element или в аналогичном слоте объектов других классов. Он представляет из собой список или другой Лисп-объект, в котором "зашито" до трёх идентификаторов

topic-id
идентификатор статьи книги помощи,
context-id
идентификатор контекстной подсказки,
tooltip
строка всплывающей подсказки в двойных кавычках.

Формально, идентификатор помощи имеет один из следующих видов.

tooltip
Простейший идентификатор, состоящий только всплывающей подсказки. Если запрашивается контекстная помощь, то это строка также может быть показана, в зависимости от настроек.
(topic-id context-id)
Отличающиеся идентификаторы статьи и контекстной подсказки.
(topic-id context-id . tooltip)
Полная спецификация, в которую "зашиты" все три идентификатора.
(id . tooltip), (id)
Сокращенная спецификация, когда один и тот же описатель id идентифицирует и статью, и контекстную подсказку, т.е. задаёт и topic-id, и context-id.
id
Сокращение для (id), применяемое для тех объектов, для которых всплывающая подсказка бессмысленна, например, для подклассов окон capi:interface.
:parent
Означает, что идентификатор помощи берётся из непосредственного родительского расклада, т.е. через capi:element-parent.

Формат файла контекстных подсказок

Исходный файл контекстных подсказок является текстовым файлом в котором собран текст для одной или нескольких контекстных подсказок. Перед текстом каждой подсказки размещается якорь-разделитель. Он отделяется переводами строк имеет один следующих форматов:

<FF>anchor

или

<!-- HELP_SEGMENT (:id anchor) -->

Здесь <FF> означает знак перевода страницы (десятичный код 12 или #\Page в языке Лисп). Причем этот знак или цепочка знаков <!-- должны начинаться в самой левой колонке.

По умолчанию типом исходного файла является txt. Из него на этапе компиляции книги

  1. создаётся результирующий бинарный файл с расширением cxt,
  2. все текстовые якоря anchor попадают в общий файл якорей книги.

Текстовые якоря, опредёленные в компонентах context-popup никак не конфликтуют с якорями, определёнными в компонентах книги помощи других типов. Т.е. текстовые и HTML-якоря собираются в два разных пространства имён. Более того, для одного элемента рекомендуется использовать одноименные якоря и для контекстной подсказки, и для статьи книги.

Сигнатура

popup-context chooser &key displayer interface book help-key x y =>

Пакет

ystok.help

Аргументы
chooser
Объект графического интерфейса: управляющий элемент или расклад (pinboard), для которого запрашивается контекстная помощь.
displayer
Уточнённый элемент интерфейса, для которого запрашивается контекстная помощь. Если не задан, либо будет совпадать с chooser, либо будет выбран текущий элемент в раскладе.
Идентификатор или дескриптор книги помощи.
interface
nil или объект-окно верхнего уровня, через которое пользователь запросил о помощи.
Идентификатор помощи; если не задан, вычисляется вызовом (capi:help-key displayer).
x, y
Координаты левого верхнего угла всплывающего окна подсказки относительно chooser. Если не заданы, определяются автоматически исходя из расположения элемента displayer.
Возвращаемые значения

Нет.

Описание

Функция ищет и показывает текст контекстной подсказки для элемента displayer окна interface. Окно подсказки "всплывает" в месте экрана, определяемом координатами x и y.

Если соответствующий текст не найден в книге, то система помощи действует в соответствии с настройкой Когда контекстная подсказка не предусмотрена.

Если аргумент book не задан, по умолчанию подсказка ищется в книге *default-book*. В качестве аргумента book может передаваться экземпляр как класса book, так book-system. Последняя возможность удобна для отладки функций помощи на этапе разработки.

Фактически, по идентификатору help-key сначала определяется локатор — строка, служащая для внутренней идентификации контекста и имеющая вид, аналогичный локатору статьи. Локатор сопоставляется с бинарными файлами подсказок *default-book* (и других зарегистрированных книг). Если ему подходит несколько бинарных файлов подсказок, выбирается текст согласно первому из удовлетворяющих дескрипторов в файле якорей.