Система помощи 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 — вероятно, наиболее распространенный способ, но также можно встроить его в справку What's This.

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