Создание справочной системы. Часть 2

Свойства HelpFile и HelpContextID объектов Office 2000

Подведем некоторые итоги и посмотрим, как в разных приложениях Office 2000 может использоваться справочное руководство. Во многих случаях получение справок основано на технике, использующей числовые идентификаторы, связанные с разделами справочного руководства. С объектной точки зрения многие объекты, так или иначе, входящие в состав Office 2000, обладают свойствами HelpFile и HelpContextID, определяющими файл, где хранится справочное руководство и числовой идентификатор, однозначно определяющий раздел внутри этого руководства. Файл справочного руководства может быть создан различными инструментальными средствами - HTML Help Workshop или WinHelp, и может быть либо chm-файлом, либо hlp-файлом. Давайте разберемся, какие объекты Office 2000 обладают свойствами HelpFile и HelpContextID и как они используются для выдачи справок.

Объекты в Access 2000

Access, как известно, имеет свою специфику, и его объектная модель существенно отличается от других приложений Office 2000. Access не использует библиотеку MSForms и формы, создаваемые в Access, отличаются от форм, используемых в других приложениях, в том числе и по своим свойствам.

Для каждой формы или отчета Access можно создать собственное справочное руководство. Можно, конечно, иметь одно руководство для всех объектов базы данных Access. Объекты Form и Report в Access обладают свойствами HelpFile и HelpContextID, которые можно установить на этапе проектирования или программно. Элементы управления, размещаемые в формах, обладают свойством HelpContextID, задающим числовой идентификатор раздела справки, что позволяет связать каждый элемент с соответствующим разделом справочного руководства. Работая с формой, пользователю достаточно нажать клавишу F1, чтобы получить контекстную справку к тому или иному элементу управления. Зная HelpContextID элемента управления, находящегося в фокусе ввода, и файл, связанный с формой, система отображает в окне справки нужный раздел справочного руководства. Если HelpContextID для активного элемента управления не задан, то отображается раздел, связанный с формой.

Формы в Excel, Word и Power Point

В Word, Excel и Power Point формы представляются объектом UserForm, принадлежащим общей библиотеке MSForms, являющейся частью объектной модели этих приложений. В отличие от близкого по духу объекта Form в Access, объект UserForm не имеет ни свойства HelpFile ни свойства HelpContextID. Правда, на этапе проектирования для формы можно задать свойство HelpContextID. Это же свойство можно задать на этапе проектирования и для элементов управления, размещаемых в форме. С объектной точки зрения объект UserForm обладает коллекцией Controls, а каждый элемент этой коллекции - объект Control - обладает свойством HelpContextID.

Как уже говорилось ранее, с формой в этих приложениях нельзя связать отдельный файл справочного руководства. Единое справочное руководство связывается со всем программным проектом. Свойство HelpFile можно установить на этапе проектирования или программно, используя объект VBProject, входящий в общую библиотеку VBIDE. Этот объект имеет и свойство HelpContextID, которое используется в Object Browser, когда необходимо получить справку о данном проекте. О том, как работает клавиша F1 в формах, я написал выше.

Объекты инструментальных панелей

Наряду с формами, основными элементами интерфейса, создаваемого для документов Office 2000, являются пользовательские инструментальные панели. Как объект, инструментальная панель принадлежит классу CommandBar. Ее свойство Controls возвращает коллекцию класса CommandBarControls. На панелях располагаются элементы разного типа - меню и команды меню, кнопки нескольких возможных видов. Как объекты, эти элементы принадлежат следующим классам: CommandbarButton, CommandBarComboBox, CommandBarControl, CommandbarPopUp. Объекты всех этих классов обладают свойствами HelpFile и HelpContextID. Оба свойства должны быть заданы для каждого элемента. Заметьте, файл, задающий справку, не связывается ни с панелью, ни с документом, а указывается для каждого отдельного элемента. В принципе это дает некоторую свободу и позволяет, например, иметь отдельный файл для каждой инструментальной панели. Устанавливаются эти свойства программно. Вот пример установления этих свойств у первых трех элементов одной пользовательской инструментальной панели:

Public Sub AddHelpProps()
	'Добавление контекстных справок к элементам панели
	Dim panel As CommandBar
	Dim ctrl As CommandBarButton
	
	Dim HelpFilePath As String
	HelpFilePath = "e:\O2000\DsCd\WhatThisHelpToWGC\HelpToWGC.chm"
	
	Set panel = CommandBars("ButtonPanel")
	'Устанавливаем свойства элементов панели
	'Help Свойства кнопки
	Set ctrl = panel.Controls(1)
	ctrl.HelpFile = HelpFilePath
	ctrl.HelpContextId = 1000
	
	Set ctrl = panel.Controls(2)
	ctrl.HelpFile = HelpFilePath
	ctrl.HelpContextId = 1001
	
	Set ctrl = panel.Controls(3)
	ctrl.HelpFile = HelpFilePath
	ctrl.HelpContextId = 1002
End Sub

Программные объекты

Свойства HelpFile и HelpContextID имеют целый ряд программных объектов, начиная с главного программного объекта VBProject и кончая его компонентами - формами и модулями. Эти свойства имеет объект Err и метод Raise, используемые при обработке программных ошибок. Обладают этими свойствами и широко употребительные функции - MsgBox и InputBox. В конце этой лекции я чуть подробнее расскажу о том, как выдаются справки на разных этапах работы с программным проектом.

Получение справок программным путем

Я уже рассказывал в предыдущей лекции о том, как можно показать справочное руководство в ответ на запрос пользователя, нажавшего специально спроектированную командную кнопку или выбравшего команду меню, созданную для этой цели. Напомню, что для решения этой задачи в обработчике соответствующего события запускалась специальная программа HTML Help executable program (hh.exe), которой в качестве параметра передается имя chm-файла.

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

Метода Help, которым обладают объекты Application приложений Office 2000.

Функции API - HtmlHelp.

Метод Help объектов Application

Метод Help по-разному работает для разных приложений - в Word и Access он позволяет получать справки только по стандартным разделам. В приложениях Excel и Power Point метод Help позволяет получить справку к заданному разделу пользовательского справочного руководства.

В приложении Word этот метод имеет следующий синтаксис:

Help(HelpType)

Параметр HelpType задается константой типа wdHelpType. Каждая константа определяет тот или иной вид справки. Вот небольшой пример:

Public Sub CallHelp()
	'Вызов стандартной справки
	Application.Help (wdHelpAbout)
End Sub

Синтаксис метода Help в приложениях Excel и Power Point следующий: Help(HelpFile, HelpContextID)

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

Я рассмотрю сейчас пример, в котором метод Help будет использоваться для получения справок об элементах интерфейса формы. Это будет все та же форма с игрой "Волк, Коза и Капуста". Для того, чтобы она заработала в Excel, мне пришлось, конечно, выполнить операции экспорта - импорта формы и соответствующих модулей. Еще одно типичное изменение в таких случаях связано с заменой объекта ActiveDocument на ActiveWorkBook, определяющих соответственно активные документы Word и Excel.

Моя цель состоит в том, чтобы получать контекстные справки к элементам интерфейса данной формы, используя возможности метода Help в Excel. Вот как я собирался достичь этой цели. Как Вы помните, в форме для каждого визуального объекта введен дополнительный объект - надпись (Label). Надписи полезны сами по себе, но введены они были и по той причине, что графические объекты не имеют важного свойства HelpContextID. Для надписей это свойство существует и на этапе проектирования его значение можно установить. В обработчике события Click для каждой надписи я предполагал вызывать метод Help, передавая ему в качестве параметра контекстный идентификатор соответствующей надписи. Так что все выглядело достаточно логично, - всякий раз, когда пользователь щелкает мышью по надписи, ему в ответ выдается справка о визуальном элементе, связанном с этой надписью. Вот как выглядит спроектированный мной обработчик события Click для надписи:

Private Sub Label1_Click()
	'Выдача контекстной справки - не работает!!!
	'Глобальный параметр Myf задает путь к файлу справочного руководства
	'Второй параметр метода Help позволяет по HelpContextID определить нужный раздел
	
	Call Application.Help(Myf, Me.Label1.HelpContextID)

End Sub

Однако мой хорошо продуманный план потерпел неудачу из-за очередного bug'а ("жучка"). Дело в том, что, хотя надписи и имеют свойство HelpContextID, значение которого можно установить на этапе проектирования, программно работать с этим свойством для надписей невозможно. Ни установить, ни прочесть значение этого свойства программно не удается. Ошибка возникает, как при явных попытках работать с этим свойством, так и при вызовах внутри процедуры. Поэтому в приведенном примере вызов метода Help терпит неудачу из-за невозможности получить значение свойства HelpContextID для надписи. Так что Вам повезло, - Вы узнали еще об одной ошибке. А мне не повезло, поскольку пришлось в очередной раз переделать интерфейс моей формы. Надеюсь, Вы понимаете, что найти выход из данной ситуации нетрудно, - я заменил надписи другими элементами интерфейса, для которых свойство HelpContextID корректно работает как на этапе проектирования, так и программно. Вместо надписей я использовал специальные утапливаемые кнопки - объекты класса ToggleButton. Для них также существует событие Click, так что наша схема по-прежнему работает, - изменился лишь тип элементов, нажатие которых приводит к выдаче контекстной справки. Я внес лишь небольшие усовершенствования и вот как выглядит обработчик события Click для кнопки ToggleButton:

Private Sub ToggleButton1_Click()
	'Выдача контекстной справки -	работает!!!
	'Глобальный параметр Myf задает путь к файлу справочного руководства
	'Второй параметр метода Help позволяет по HelpContextID определить нужный раздел
	
	If Me.ToggleButton1.Value Then
		Call Application.Help(Myf, Me.ToggleButton1.HelpContextID)
	End If
End Sub

Прежде, чем выдать справку, я проверяю, в каком состоянии находится кнопка. Справка выдается при нажатии кнопки. Для кнопки, находящейся в утопленном состоянии, щелчок по ней не приводит к повторной выдаче справки. Надеюсь, понятно, что аналогичные процедуры написаны для всех 10 кнопок нашей формы. Взгляните, как выглядит наша форма в Excel:

Рис. 9.25. Форма для игры "Волк, Коза и Капуста", открытая в Excel