Каркас Qt Help
|
Имя | Расширение | Краткое описание |
---|---|---|
Проект справки Qt (Qt Help Project) | .qhp | Исходный файл генератора справки, состоящий из таблицы оглавления, индексов и ссылок на реальные файлы документации (*.html); также этот файл определяет уникальное пространство имён для документации, на которую он ссылается. |
Сжатая справка Qt (Qt Compressed Help) | .qch | Выходной файл генератора справки. Это двоичный файл, содержащий всю информацию, расположенную в файле проекта-справки, вместе со сжатыми файлами документации. |
Проект коллекции справки Qt (Qt Help Collection Project) | .qhcp | Исходный файл для генератора коллекции справки. Содержит ссылки на сжатые файлы справки, которые нужно включить в коллекцию; также может содержать информацию о пользовательских настройках (customizing) программы Qt Assistant. |
Коллекция справки Qt (Qt Help Collection) | .qhc | Выходной файл генератора коллекции. Это файл, с которым взаимодействует класс QHelpEngine. Содержит ссылки на любое количество сжатых файлов справки и дополнительную информацию, например пользовательские фильтры. |
Сборка файлов справки для справочной системы Qt предполагает, что html-файлы документации уже существуют, т.е. справочная система Qt не предоставляет возможности создания html-файлов, как например, Doxygen.
Если html-документы присутствуют, файл проекта справки Qt должен быть создан. После указания всей необходимой информации в этом файле, его необходимо скомпилировать вызвав:
qhelpgenerator doc.qhp -o doc.qch
Файл 'doc.qch' будет содержать все html-файлы в сжатой форме вместе с оглавлением и предметным указателем. Чтобы проверить, является ли созданный файл правильным, откройте Qt Assistant и установите файл через страницу Settings|Documentation.
Первый шаг - создание файла проекта коллекции справки Qt. Так как коллекция справки Qt хранит, главным образом, ссылки на сжатые файлы справки, то файл проекта 'mycollection.qhcp' выглядит неудивительно простым:
<QHelpCollectionProject version="1.0"> <docFiles> <register> <file>doc.qch</file> </register> </docFiles> </QHelpCollectionProject>
Для того, чтобы фактически создать файл коллекции, вызовите:
qcollectiongenerator mycollection.qhcp -o mycollection.qhc
Вместо запуска двух инструментов, один для создания сжатой справки, а другой для создания файла коллекции, также возможно просто запустить инструмент qcollectiongenerator со слегка изменённым файлом проекта, информируя генератор о том, чтобы необходимо сначала создать сжатую справку.
... <docFiles> <generate> <file> <input>doc.qhp</input> <output>doc.qch</output> </file> </generate> <register> <file>doc.qch</file> </register> </docFiles> ...
Конечно, можно определить более одного файла в секции 'generate' или 'register', так что любое количество сжатых файлов справки может быть создано и зарегистрировано сразу.
Доступ к содержимому справки возможен двумя способами: Используя Qt Assistant, как просмотрщика документации, или используя QHelpEngine API для встраивания содержимого справки прямо в приложение.
Qt Assistant оперирует файлом коллекции, который может быть задан перед запуском. Если файл коллекции не задан, то будет создан и использован файл по умолчанию. В другом случае, можно зарегистрировать любой сжатый файл справки Qt и получить доступ к содержимому справки.
Когда Assistant используется как просмотрщик справки для приложения, желательно, чтобы он мог быть настроен, чтобы лучше соответствовать приложению и не выглядеть как независимый, самодостаточный просмотрщик справки. Чтобы добиться этого, некоторые дополнительные свойства могут быть установлены в файле коллекции Qt, например, чтобы изменить заголовок или значок приложения Qt Assistant. Для получения дополнительной информации по этой теме смотрите Руководство по Qt Assistant.
Вместо отображения справки во внешнем приложении подобном Qt Assistant, также можно встроить интерактивную справку в приложение. Содержимое, затем, может быть получено через класс QHelpEngine и может быть отображено практически в любой форме. Отображение содержимого в QTextBrowser, вероятно, наиболее общий способ, но также возможно и встраивание его в подсказку "Что это".
Извлечение данных справки из механизма справки не требует много кода. Первый шаг - создание экземпляра механизма справки. Затем мы запрашиваем у механизма справки ссылки, ассоциированные с идентификатором, в нашем случае "MyDialog::ChangeButton". Если ссылка была найдена, значит, как минимум один документ существует в этой теме, мы получаем реальное содержимое справки, вызывая fileData() и отображаем документ пользователю.
QHelpEngineCore helpEngine("mycollection.qhc"); ... // получим все ссылки на файлы для этого идентификатора QMap<QString, QUrl> links = helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton")); // Если справка доступна для этого ключевого слова, получим справочные данные // первой ссылки на файл. if (links.count()) { QByteArray helpData = helpEngine->fileData(links.constBegin().value()); // отобразим документацию пользователю if (!helpData.isEmpty()) displayHelp(helpData); }
Для получения дополнительной информации о том как использовать API, ищите в описании класса QHelpEngine.
Авторские права © 2010 Nokia Corporation и/или её дочерние компании | Торговые марки | Qt 4.6.4 |
Попытка перевода Qt документации. Если есть желание присоединиться, или если есть замечания или пожелания, то заходите на форум: Перевод Qt документации на русский язык... Люди внесшие вклад в перевод: Команда переводчиков |