Справочная система

• Создание тематических разделов справочной системы
• Обратная сторона тематических разделов
• Создание контекстно-зависимой справочной системы
• Создание и компиляция файла справки
• Доступ к справочной системе Windows
• Справочная система What's This

    Грубо говоря, метод использования компилятора справочной системы достаточно прост: создается текстовый файл, содержащий соответствующие коды формата, которые компилятор преобразует во внутренние ссылки, выпадающие окна и т.д. Текстовый файл должен создаваться в текстовом редакторе, поддерживающем формат RTF (rich text format) фирмы Microsoft. Большинство современных текстовых редакторов поддерживают этот формат.

    Система помощи Windows также включает в себя меню с дополнительными средствами. (При работе с Windows 95 может понадобиться создать многоуровневую систему меню.) Подобное меню содержит такие пункты, как Search, который выводит список ключевых слов и позволяет пользователю перемещаться по списку, вводя первые буквы интересующего его слова. Далее, при помощи ключевого слова можно сразу перейти к нужному разделу. Также различные части приложения (как и в Visual Basic) могут содержать контекстно-зависимую подсказку. Этот способ получения подсказки доступен при нажатии клавиши F 1 (или при помощи кнопки WhatsThisHelp в среде Windows 95) и выдает информацию о том инструменте среды, который задействован в настоящий момент.
 

Создание тематических разделов справочной системы

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

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

Обратная сторона тематических разделов

    Практически нет людей (за редким исключением), которые для создания справочной системы не использовали бы простые пакеты, основанные на макроопределениях, для расстановки управляющих символов RTF. Используя подобный пакет можно смело забыть о том, что обозначет тот или иной идентификатор формата RTF, щелкнув вместо этого несколько раз мышкой. В качестве примера можно привести внешний вид панели инструментов пакета RoboHelp, дающей доступ к некоторым из его возможностей.
    В любом случае, как об этом уже говорилось ранее, необходим текстовый редактор, поддерживающий формат RTF (rich text format) для сохранения файла, который будет впоследствии перетранслирован компилятором в справочную систему. (Это связано с тем, что большинство доступных инструментов типа RoboHelp доступны в качестве дополнительных модулей к редактору Microsoft Word, который, без сомнения, полностью поддерживает спецификацию RTF-формата.)
    Каждый тематический раздел справочной системы должен быть отделен от другого символом "разрыв страницы" (hard page break). (Этот символ надо вводить самостоятельно, в отличие от других символов разрыва, которые тестовый редактор проставляет автоматически. Символ "разрыв страницы" можно ввести путем нажатия комбинации клавиш CTRL+ENTER в семействе редакторов фирмы Microsoft.) Каждый тематический раздел должен содержать идентификатор контекстной строки, название, а также список доступных ключевых слов. Контекстная строка используется для перехода к разделу, следовательно, каждый раздел должен иметь уникальную строку. Ключевые слова используются для организации возможностей поиска в справочной системе. Естественно, несколько тематических разделов могу т иметь одинаковые ключевые слова.
    Привязка по ключевым словам, использующая идентификаторы, является основой для построения справочной системы. Например, контекстная строка выделяется при помощи идентификатора привязки "#". Контекстная строка может использовать символы от А до Z, числа, точки и символы подчеркивания. Максимальная длина строки ограничена 255 символами.
    Название тематического раздела выделяется при помощи идентификатора привязки "$" (знак доллара). Название может содержать до 127 символов из стандартного набора системы Windows. И, наконец, ключевые слова выделяются при помощи идентификатора привязки "К" (в верхнем регистре).
    (Ключевые слова не являются обязательными, однако можно назначить тематическому разделу более чем одно ключевое слово, перечислив их в списке, разделенном знаками ";". Ключевые слова могут содержать произвольные символы из стандартного набора символов системы Windows. Максимальная длина ключевого слова не должна превышать 255 символов.)
    Далее заметим, что можно организовать ссылку на файл с растровым изображением.bmp, указав его имя в фигурных скобках. При этом растровое изображение будет помещено в соответствующее место экрана помощи. Можно также поместить растровое изображение на страницу со списком тематических разделов. Если для создания справочной системы используется текстовый редактор Word for Windows, то того же результата можно достичь, воспользовавшись функцией Insert Picture. (Для вставки изображения большого размера следует воспользоваться методом вставки "By Reference".) Графическая часть справочной системы также может использоваться в качестве точек перехода к другим темам. Если не используется редактор Word for Windows, то следует создать ссылку на растровое изображение в файле тематических разделов.
    Обратим внимание, что некоторые фрагменты текста (например, "Status Area") подчеркнуты двойной линией. Такие фрагменты используются в качестве точек перехода к другим разделам. Вслед за каждым таким фрагментом следует текст, указывающий место перехода (этот текст не выводится на экран в справочной системе). Общий синтаксис подобного механизма ссылок может быть записан как:

JumpString CONTEXT_SroWG

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

Создание контекстно-зависимой справочной системы.

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

• Выбрать пункт Tools\0ptions. а затем щелкнуть мышкой по странице Project.
• Ввести имя скомпилированного файла справочной системы в текстовой панели HelpFile. (Если файл находится в отличном от базового для приложения директории, то следует указать полный путь.)

• Ключевым моментом для программиста при создании контекстно-зависимой справочной системы является установка соответствующих значений HelpContextJD для рабочей формы или элементов управления. Все управляющие элементы, за исключением теневых линий, изображений и элементов управления метками, имеют в своем составе свойство HelpContextID.
• Ключевым моментом для создателя справочной системы является проверка того. чтобы значения HelpContextID соответствовали различным элементам, для которых необходима контекстно-зависимая подсказка.

Создание и компиляция файла справки

    Файл проекта справочной системы содержит всю информацию, необходимую для корректной работы компилятора. Кроме этого, он содержит таблицу (карчу) соответствий для установления связей между контекстной строкой и контекстным номером ID, которая будет использоваться в проекте (еще раз напомним, что должно существовать строгое соответствие между информацией, содержащейся в файле проекта справочной системы, и кодом приложения).
    Файл проекта справочной системы представляет собой обычный текст в формате ASCII. В качестве расширения для всех подобных файлов проекта используется.hpj. Файл проекта справочной системы содержит список всех файлов с тематическими разделами, а также может содержать растровое изображение или таблицу соответствия между контекстными строками и контекстными номерами ID. Можно также назначить две контекстные строки одному и тому же тематическому разделу, модифицировав файл проекта.
    Для установления соответствий между контекстным номером ID и определенным тематическим разделом необходимо указать имя раздела после ключевого слова [MAP], после чего через пробел (т.е. после нажатия клавиши SPACE или TAB) следует указать контекстный номер справки. Например, секция [МАР]-файла проекта справочной системы может содержать следующую информацию:

    [MAP]
    FILE_MENU 5 ;5 is the context number
                    ;Comments follow semicolons
    EDIT_MENU 10 ;10 is context number
    VIEW_MENU 15 ;15 is context number

    Теперь, если вызвать инструмент создания справочной системы со значением HelpContextID, установленным в 5, получим экран помощи для тематического раздела FILE_MENU; установив HelpContextID в 10 и вызвав инструмент создания справочной системы, получим экран EDIT MENU и т.д.
    После создания файла проекта справочной системы остается только вызвать компилятор системы помощи. (Заметим, что директорий, в котором находится компилятор, должен содержаться в системной переменной PATH, в противном случае необходимо будет указать полный путь.) Например, в системе Windws 95 можно использовать для этого диалоговую панель Run, доступную из меню Start, в которой нужно написать нечто подобное:

    C:\VB\HC\HC Named fHelpPi-ojectFile

если компилятор находится в назначенном по умолчанию директории (для версии Professional). Или же можно написать:

НС NameOfHelpProjectFile

в IUM случае, когда директорий, содержащий компилятор, содержится в переменной PATH.
    Компилятор справочной системы имеет большое количество возможностей, не рассматриваемых здесь. Например, можно компилировать только определенные части файла или управлять размерами и видом его окон. Кроме этого, можно использовать всю мощь макроопределений, написанных фирмой Microsoft, для расширения возможностей компилятора справочной системы. Эта и другая информация содержатся в Visual Basic Books Online. Также можно почерпнуть большое количество информации, внимательно изучив содержание файла Iconwrks.rtf.

Доступ к справочной системе Windows

    Для доступа к справочной системе можно использовать метод ShowHelp обычной диалоговой панели. Далее приведена последовательность действий, которые необходимо для этого выполнить:

• Добавитъ ооычныч аналоговый управляющий элемент в то место формы, где надо использовать средство справочной системы Windows.
• Установить соответствующие значения для свойств HelpFile u HelpCommand управляющего элемента CommonDialog.

    Например, если надо использовать метод ShowHelp для получения контекстно-зависимой подсказки:
• Назначить свойству HelpFile имя скомпилированного файла справки.
• Установить для свойства HelpCommand -значение cdlHelpContext.
• Установить соответствующее значение контекстного номера ID для свойства HelpContext.
• И. наконец, можно вызвать справочную систему при номоиш метода ShowHeIn

        Declare Function WinHeip Lib "user32" Alias "WinHelpA" (ByVal hHnd As Long, ByVal IpHclpFu
        As String, ByVal wCommand As Long, ByVal dwData As Long) As Long

    Параметр hWnd ("window's handle) является параметром свойства hWnd рабочей формы. Параметр IpHelpF указывает путь к файлу справки (этот файл находится в директории, отличном от директория .ехе-файлов). Мог понадобиться следующие константы, используемые параметром wCommand:

        Global Const HELP CONTEXT = &H1          'Display topic by id number
        Global Const HELP QUIT -- &H2             'Terminate help
        Global Const HELP INDEX = &H3                 'Display index
        Global Const HELP HELPONHELP = &H4 'Display help on using help
        Global Const HELP SETINDEX = &H5 'Set an alternate Index
        Global Const HELP KEY = &H101                 'Display topic for keyword in Data
        Global Const HELP MULTIKEY = &H201 'Look up keyword in alternate table

    Например, для того, чтобы вызвать стандартную справочную систему "Help on Help", необходимо испольвать следующую процедуру:

    Public Sub DisplayHelp On Help(X As Form)
        Dim Foo As Long ' dummy variable
        Foo = WinHeip(X.hWnd,"C:\WINDOWS\HELP\WINDOWS.HLP",
        HELP HELPONHELP,CLng(O))
    End Sub

    После этого любая строка вида

    DisplayHelp_On_Help_Me

будет вызывать стандартную справочную систему Windows.

    Если для вызова справочной системы используется WinHeip API, то для того чтобы закрыть дополнительные окна справки, вам нужно снова вызвать функцию WinHeip API (т.к. справочная система Windows является отдельным приложением). Это можно сделать следующим образом (обычно для этого используется событие Form Unload). Переменные Foo и Bar должны иметь правильный тип, хотя реально они не несут никакой полезной нагрузки.

    Sub Form_Unload(Cancel As Integer)
            Dim Foo As Integer, Bar As String 'dummy variables
            Foo = WinHeip(Me.hWnd, Bar, Help_Quit, CLng(O))
    End Sub

Справочная система What's This

    Операционная система Windows 95 имеет новый тип контекстно-зависимой подсказки, который вызывается щелчком мышки над изображением небольшого вопросительного знака, расположенного на заголовке экранной формы. При этом указатель мыши изменяет свой внешний вид на вопросительный знак, после чего пользователь может щелкнуть мышкой по любому объекту. В результате этих действий на экран выводится контекстно-зависимая информация о выбранном объекте. Точно так же, как и в других вариантах контекстно-зависимой подсказки, для корректной работы подсказки "What's This" надо установить соответствие между приложением и секцией MAP в файле проекта справочной системы.

    Для встраивания контекстно-зависимой подсказки What's This в приложение доступны три способа. Но в любом случае свойство WhatsThisHelp должно быть установлено в True.

• Создать кнопку What's This на заголовке вашей формы, установив свойство WhatsThisButton в True. Теперь, если пользователь нажмет эту кнопку, указатель мышки изменит свой внешний вид на стрелку с вопросительным знаком, а после выбора объекта система Windows автоматически вызовет тематический раздел, чей контекстный номер ID соответствует свойству WhatsThisHelpID выбранного элемента.

• Вызвать метод WhatsThisMode. Синтаксис метода следующий:

• Вызвать метод ShowWhatsThis управляющего элемента. Точно так же пользователю будет выведен экран помощи, чей контекстный номер ID соответствует значению свойства WhatsThisHelpID управляющего элемента.