Фреймворк справки 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 можно указать более одного файла, поэтому можно сгенерировать и зарегистрировать любое количество сжатых файлов справки за один раз.

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

QHelpEngine позволяет встраивать содержимое справки непосредственно в приложение.

Вместо отображения справки во внешнем приложении, таком как веб-браузер, также можно встроить онлайн-справку в приложение. Содержимое затем можно получить через класс QHelpEngine и отобразить практически в любом виде. Отображение справки в QTextBrowser — вероятно, наиболее распространённый способ, но встраивание её в справку «Что это?» также возможно.

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

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

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(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()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

Для получения дополнительной информации о том, как использовать API, см. справочную информацию по классу QHelpEngine.