Фреймворк справки 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.