Фреймворк справки Qt

Обзор

Система справки Qt включает инструменты для генерации и просмотра файлов справки Qt. Кроме того, она предоставляет классы для программированного доступа к содержимому справки, чтобы интегрировать онлайн-справку в приложения Qt.

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

Однако, использование файлов коллекции для объединения множества наборов документации может привести к некоторым проблемам. Например, одно ключевое слово индекса может быть определено в разных наборах документации. Таким образом, когда вы видите только ключевое слово в индексе и активируете его, вы не можете быть уверены, что будет показана ожидаемая документация. Поэтому система справки Qt предлагает возможность фильтрации содержимого справки по определенным атрибутам. Однако это требует, чтобы атрибуты были назначены содержимому справки до генерации сжатого файла справки.

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

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

Генерация справки Qt

Создание файлов справки для системы справки Qt предполагает, что HTML-файлы документации уже существуют.

После размещения HTML-документов необходимо создать файл Проекта справки Qt с расширением .qhp. После указания всей необходимой информации этот файл необходимо скомпилировать, вызвав:

qhelpgenerator doc.qhp -o doc.qch

Файл doc.qch содержит все HTML-файлы в сжатом виде вместе с оглавлением и ключевыми словами индекса. Чтобы проверить правильность сгенерированного файла, откройте Qt Assistant и установите файл в Настройки > Документация.

Для стандартной сборки исходного кода Qt файл .qhp генерируется и помещается в ту же директорию, что и HTML-страницы.

Создание коллекции справки Qt

Первый шаг — создание файла проекта коллекции справки Qt. Поскольку коллекция справки Qt в первую очередь хранит ссылки на сжатые файлы справки, файл проекта mycollection.qhcp выглядит довольно просто:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <docFiles>
        <register>
            <file>doc.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

Для фактического создания файла коллекции вызовите:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Чтобы сгенерировать сразу и сжатый файл справки, и файл коллекции, измените файл проекта коллекции справки таким образом, чтобы он инструктировал генератор справки сначала создать сжатую справку:

...
<docFiles>
    <generate>
        <file>
            <input>doc.qhp</input>
            <output>doc.qch</output>
        </file>
    </generate>
    <register>
        <file>doc.qch</file>
    </register>
</docFiles>
...

Конечно, можно указать более одного файла в разделе generate или register, поэтому можно сгенерировать и зарегистрировать любое количество сжатых файлов справки за один раз.

Использование справки Qt

Доступ к содержимому справки можно получить двумя способами: используя Qt Assistant как обозреватель документации или используя API QHelpEngine для непосредственной интеграции содержимого справки в приложение.

Использование Qt Assistant

Qt Assistant работает с файлом коллекции, который можно указать перед запуском. Если файл коллекции не задан, будет создан и использован файл по умолчанию. В любом случае можно зарегистрировать любой сжатый файл справки Qt и получить доступ к содержимому справки.

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

Использование API QHelpEngine

Вместо отображения справки во внешнем приложении, например, Qt Assistant, также можно интегрировать онлайн-справку в приложение. Затем содержимое можно получить через класс QHelpEngine и отобразить практически в любом виде. Отображение справки в QTextBrowser — вероятно, самый распространенный способ, но встраивание её в справку What's This тоже вполне возможно.

Получение данных справки из файлового движка не требует много кода. Первый шаг — создание экземпляра движка справки. Затем мы запрашиваем у движка ссылки, назначенные идентификатору, в данном случае MyDialog::ChangeButton. Если ссылка найдена, то есть по данной теме существует хотя бы один документ справки, мы получаем фактическое содержимое справки, вызвав QHelpEngineCore::fileData(), и отображаем документ пользователю.

QHelpEngineCore helpEngine("mycollection.qhc");
...

// get all file references for the identifier
QMap<QString, QUrl> links =
    helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin().value());
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

Дополнительную информацию об использовании API см. в справке по классу QHelpEngine.