Основы офисного программирования и документы Word

Идентификаторы и разделы справки. Построение отображения


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

Для того чтобы разделы справочного руководства связать с числовыми и символьными идентификаторами, при работе в HHW требуется установить два отображения. Первое отображение задается в специальной секции MAP, оно устанавливает соответствие между двумя видами идентификаторов. Второе отображение задается в секции ALIAS, - оно связывает символьные идентификаторы с именами файлов, хранящих разделы справки. В совокупности оба отображения позволяют, зная любой из идентификаторов, найти нужный раздел справки.

Поскольку одной из наших целей является включение в справочное руководство специальных контекстных справок, то мы также рассмотрим создание в hhp-проекте секции TEXT POPUPS, в которой задается ссылка на текстовый файл, содержащий контекстные справки и устанавливается соответствие между этими справками и их идентификаторами.

Давайте перейдем к рассмотрению подробностей построения каждого из упомянутых отображений и формирования секций hhp-проекта: MAP, ALIAS, TEXT POPUPS.

Отображение между двумя видами идентификаторов - символьными и числовыми - представляется в виде определения последовательности именованных констант. Синтаксис заимствован из языка С и каждая строка в определении отображения имеет вид:

#define <символьный идентификатор> <числовой идентификатор>

Вот как выглядит отображение, задаваемое для нашего примера:

#define IDH_Man 1000 #define IDH_Wolf 1001 #define IDH_Goat 1002 #define IDH_Cabbage 1003 #define IDH_Boat 1004 #define IDH_River 1005 #define IDH_LeftBank 1006 #define IDH_RightBank 1007 #define IDH_Shark 1008 #define IDH_Island 1009


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

Для того чтобы разделы справочного руководства связать с числовыми и символьными идентификаторами, при работе в HHW требуется установить два отображения. Первое отображение задается в специальной секции MAP, оно устанавливает соответствие между двумя видами идентификаторов. Второе отображение задается в секции ALIAS, - оно связывает символьные идентификаторы с именами файлов, хранящих разделы справки. В совокупности оба отображения позволяют, зная любой из идентификаторов, найти нужный раздел справки.

Поскольку одной из наших целей является включение в справочное руководство специальных контекстных справок, то мы также рассмотрим создание в hhp-проекте секции TEXT POPUPS, в которой задается ссылка на текстовый файл, содержащий контекстные справки и устанавливается соответствие между этими справками и их идентификаторами.

Давайте перейдем к рассмотрению подробностей построения каждого из упомянутых отображений и формирования секций hhp-проекта: MAP, ALIAS, TEXT POPUPS.

Отображение между двумя видами идентификаторов - символьными и числовыми - представляется в виде определения последовательности именованных констант. Синтаксис заимствован из языка С и каждая строка в определении отображения имеет вид:

#define <символьный идентификатор> <числовой идентификатор>

Вот как выглядит отображение, задаваемое для нашего примера:

#define IDH_Man 1000 #define IDH_Wolf 1001 #define IDH_Goat 1002 #define IDH_Cabbage 1003 #define IDH_Boat 1004 #define IDH_River 1005 #define IDH_LeftBank 1006 #define IDH_RightBank 1007 #define IDH_Shark 1008 #define IDH_Island 1009



Заметьте, символьные идентификаторы начинаются префиксом IDH_. В этом случае система HHW опознает их как символьные идентификаторы и осуществляет весьма полезные проверки корректности задания отображения между идентификаторами и разделами справки. Так что рекомендуется всегда использовать этот префикс в символьных именах. Это отображение строится в обычном текстовом редакторе внутри HHW, в Блокноте или в Word, если Вы привыкли там работать. Файл сохраняется как текстовый файл с уточнением ".h". Это уточнение типично для заголовочных файлов языка C. По сути, файл таковым и является, он является частью hhp-проекта и хранится в каталоге проекта вместе с остальными файлами. Теперь несколько слов о том, как создается секция MAP.

При работе с вкладкой Project в главном окне среды HHW на левой инструментальной панели расположена специальная кнопка
HTML Help API Information. Она называется так, потому что API функция HTML Help, которая явно или неявно используется при вызове разделов справочной системы, требует в качестве информации (параметров) задания числовых или символьных идентификаторов. Но об этом мы еще поговорим позже.

Щелчок по данной кнопке открывает диалоговое окно, три вкладки которого обеспечивают создание трех секций hhp-проекта, о которых идет речь. Вот как выглядит это окно, открытое на вкладке MAP:


Рис. 9.13.  Создание секции MAP

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



Заметьте, символьные идентификаторы начинаются префиксом IDH_. В этом случае система HHW опознает их как символьные идентификаторы и осуществляет весьма полезные проверки корректности задания отображения между идентификаторами и разделами справки. Так что рекомендуется всегда использовать этот префикс в символьных именах. Это отображение строится в обычном текстовом редакторе внутри HHW, в Блокноте или в Word, если Вы привыкли там работать. Файл сохраняется как текстовый файл с уточнением ".h". Это уточнение типично для заголовочных файлов языка C. По сути, файл таковым и является, он является частью hhp-проекта и хранится в каталоге проекта вместе с остальными файлами. Теперь несколько слов о том, как создается секция MAP.

При работе с вкладкой Project в главном окне среды HHW на левой инструментальной панели расположена специальная кнопка
HTML Help API Information. Она называется так, потому что API функция HTML Help, которая явно или неявно используется при вызове разделов справочной системы, требует в качестве информации (параметров) задания числовых или символьных идентификаторов. Но об этом мы еще поговорим позже.

Щелчок по данной кнопке открывает диалоговое окно, три вкладки которого обеспечивают создание трех секций hhp-проекта, о которых идет речь. Вот как выглядит это окно, открытое на вкладке MAP:


Рис. 9.13.  Создание секции MAP

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


Рис. 9.14.  Первое окно открытия файла

В этом окне уже появилась кнопка Browse. Нажмем ее.


Рис. 9.15.  Второе окно открытия файла

Теперь прошу обратить особое внимание на два факта. Первый - в качестве шаблона для поиска файлов указан шаблон "*.h", Второй факт - в открытой папке HelpToWGC не найдено ни одного файла с таким уточнением. Могу Вас заверить, что заголовочные файлы с уточнением h присутствуют в этом каталоге. Прежде чем обсуждать данные факты, продолжим работу. Естественно я ввел известное мне имя заголовочного файла в поле имени и нажал кнопку "Открыть". В результате я получил ответ, что найти файл в каталоге не удалось:


Рис. 9.16.  Третье окно открытия файла

После этого мне осталось ничего другого, как вернуться к окну Include File (см. рис. 14) и там попытаться задать имя заголовочного файла. Диалог был продолжен и я получил следующее сообщение:


Рис. 9.17.  Четвертое окно открытия файла

После моего утвердительного ответа было сформировано предложение #include, составляющее секцию MAP. Для тех, кто знает язык C, понятно, что предложение #include обрабатывается препроцессором и вставляет заголовочный файл в текст компилируемого модуля. Несмотря на то, что это предложение, в конечном итоге, было сформировано правильно, я понимаю, что система не видит заголовочный файл, а, следовательно, не может построить нужное отображение и в нужный момент открыть требуемый раздел справки

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



Несколько слов о том, почему не виден файл с уточнением ".h". Он и не должен быть виден, поскольку это текстовый файл, и он будет отображаться, когда шаблоном будет служить уточнение ".txt". Другое дело, что в грамотной реализации нужно вначале найти все текстовые файлы и отобрать среди них те файлы, которые имеют уточнение h. Подводя итог, следует сказать, что хотя формально секция MAP была создана, но фактически процесс ее создания потерпел неудачу и файл, указанный в этой секции не будет виден системой. Выход из этой ситуации есть, но об этом чуть позже. Аналогичная ситуация с заголовочными файлами возникает и при работе с двумя другими вкладками в процессе создания секций ALIAS и TEXT POPUPS.

Прежде, чем формировать секцию ALIAS, в справочном руководстве HHW рекомендуется построить еще один заголовочный файл, задающий отображение межу символическими идентификаторами и именами файлов, содержащих соответствующие разделы справочного руководства. Я напомню, что алиасом или алиасным именем называется псевдоним, второе имя объекта. В данном случае речь идет о символических идентификаторах, являющихся псевдонимами файлов. Строки заголовочного файла, задающего алиасные имена, имеют следующий синтаксис:

Символьный идентификатор> = <Имя файла>

В нашем примере этот заголовочный файл выглядит следующим образом:

IDH_Man = Man.htm IDH_Wolf = Wolf.htm IDH_Goat = Goat.htm IDH_Cabbage = Cabbage.htm IDH_River = River.htm IDH_LeftBank = LeftBank.htm IDH_RightBank = RightBank.htm IDH_Shark = Shark.htm IDH_Boat = Boat.htm IDH_Island = Island.htm

Перейдем теперь к формированию секции ALIAS. При выборе одноименной вкладки в отличие от вкладки MAP появляются две возможности создания секции.


Рис. 9.18.  Создание секции ALIAS

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

Нажатие кнопки INCLUDE позволяет создать секцию ALIAS за один шаг, используя подготовленный в текстовом редакторе заголовочный файл. В этом случае открывается уже знакомое окно "Include File" (рис. 14) и повторяется процесс, так подробно описанный выше.


Содержание раздела