Каркас Qt HelpТемыКраткий обзорСправочная система Qt включает инструменты для создания и просмотра файлов справки Qt. В дополнение, она предоставляет классы для программного доступа к содержимому справки для возможности интеграции интерактивной справки в приложения Qt. Реальные данные справки, т.е. оглавление, предметный указатель или html-документы, содержатся в сжатых файлах справки Qt. Таким образом, один файл справки представляет, обычно, одно руководство или комплект документации. Так как большинство продуктов, являются достаточно полными и состоят из различных инструментов, то одно руководство используется достаточно редко. Вместо этого существует множество руководств, которые должны быть доступны одновременно. В идеале, также должна существовать возможность ссылаться на определенные интересные места из одного руководств а в другое. Следовательно, справочная система Qt работает с файлами коллекции справки, которые включают любое количество сжатых файлов справки. Однако, наличие файлов коллекции для объединения множества комплектов документации может привести к некоторым проблемам. Например, одно ключевое слово предметного указателя может быть определено в различных документациях. Таким образом, только когда вы видите её в предметном указателе и выбираете, вы не можете быть уверены в том, что будет отображена ожидаемая документация. Следовательно, справочная система Qt предоставляет возможность фильтровать содержимое справки после определения свойств фильтра. Однако это требует, чтобы свойства были ассоциированы с содержимым справки перед генерацией сжатого файла справки. Как уже упоминалось, сжатые файлы справки Qt содержат все данные, таким образом нет никакой необходимости поставлять всё едиными html-файлами. Вместо этого, необходимо распространять только сжатые файлы справки и, возможно, файл коллекции. Файл коллекции необязателен т.к. могут быть использованы любые существующие файлы коллекции, например, из строго выпуска. В общем, существуют четыре файла взаимодействующие со справочной системой, два используются для создания справки Qt и два предназначены для распространения:
Создание справки QtСборка файлов справки для справочной системы Qt предполагает, что html-файлы документации уже существуют, т.е. справочная система Qt не предоставляет возможности создания html-файлов, как например, Doxygen. Если html-документы присутствуют, файл проекта справки Qt должен быть создан. После указания всей необходимой информации в этом файле, его необходимо скомпилировать вызвав: qhelpgenerator doc.qhp -o doc.qch Файл 'doc.qch' будет содержать все html-файлы в сжатой форме вместе с оглавлением и предметным указателем. Чтобы проверить, является ли созданный файл правильным, откройте Qt Assistant и установите файл через страницу Settings|Documentation. Создание коллекции справки QtПервый шаг - создание файла проекта коллекции справки Qt. Так как коллекция справки Qt хранит, главным образом, ссылки на сжатые файлы справки, то файл проекта 'mycollection.qhcp' выглядит неудивительно простым:
Для того, чтобы фактически создать файл коллекции, вызовите: 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Доступ к содержимому справки возможен двумя способами: Используя Qt Assistant, как просмотрщика документации, или используя QHelpEngine API для встраивания содержимого справки прямо в приложение. Использование QtQt Assistant оперирует файлом коллекции, который может быть задан перед запуском. Если файл коллекции не задан, то будет создан и использован файл по умолчанию. В другом случае, можно зарегистрировать любой сжатый файл справки Qt и получить доступ к содержимому справки. Когда Assistant используется как просмотрщик справки для приложения, желательно, чтобы он мог быть настроен, чтобы лучше соответствовать приложению и не выглядеть как независимый, самодостаточный просмотрщик справки. Чтобы добиться этого, некоторые дополнительные свойства могут быть установлены в файле коллекции Qt, например, чтобы изменить заголовок или значок приложения Qt Assistant. Для получения дополнительной информации по этой теме смотрите Руководство по Qt Assistant. Использование QHelpEngine APIВместо отображения справки во внешнем приложении подобном 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. |
Попытка перевода Qt документации. Если есть желание присоединиться, или если есть замечания или пожелания, то заходите на форум: Перевод Qt документации на русский язык... Люди внесшие вклад в перевод: Команда переводчиков |