Търсене на информация
Да се направиСъздаване на help система за Вашия проект
Страницата е създадена на:15 април 2019 и редактирана на:15 април 2019
От версия 4.5.3 на Qt е създадена нова организация за представяне на документация. Форматът на файловете при новата организация е променен и е несъвместим с формата от предишните версии. За преминаване от старата към новата организация е предвидена програма помощник: qhelpconverter, която се намира в bin директорията на Qt. Новата организация е описана в раздела: Key Technologies -> QtHelp Module в документацията на Qt.
Дадена програма може да извлича и представя на потребителя информация от документацията си по два начина: чрез използване на класа QHelpEngine или чрез използване на програмата Qt Assistant. При новата организация документацията се съхранява в компресирани Qt help (.qch) файлове. Тези файлове се създават чрез генериране от файлове с .html формат. Така че първата стъпка за снабдяване на даден проект с документация е да се напише тя във вид на един или повече .html файлове.
Qt help проектен файл
За посочване на това кои .html файлове да се компресират в един Qt help файл се съставя Qt help проектен файл. Това е текстов файл с разширение .qhp и XML структура. Проектният файл за документация, състояща се от един единствен файл index.html изглежда така:
Предназначението на елементите е следното:
namespace -
Използване на Qt Assistant като help система за Вашия проект
В Програмите Assistant и Examples and Demos беше спомената програмата Assistent, която показва документацията на Qt. Същата програма може да използвате и Вие, за да показвате с нея документацията за проекта, който създавате.
Пример как може да се използва Qt Assistant в друга програма има в директорията с примери:
В Windows: C:qt4.5.3examplesassistantsimpletextviewer
А в Mac OS X и Linux: /usr/local/Trollteck/Qt-4.5.3/examples/assistant/simpletextviewer
Компилирайте и пробвайте тази примерна програма за да добиете представа какъв би бил резултата, ако решите да се възползвате.
Важно! В Windows, след като компилирате примера, копирайте директория documentation в поддиректория release. В противен случай разположението на директориите не е такова, каквото е зададено и програмата не функционира.
Създаване на документация
Help информацията за Вашия проект трябва да е записана в един или няколко .html файлове. Организационната структура на документацията е дървовидна. – Състои се от групи секции. Секциите могат да имат подсекции, подсекциите – свои подсекции и т.н., без ограничение в броя на нивата за вложеност. Тази структура на документацията се показва в навигационния прозорец "Contents" на Qt Assistant. При щракване върху заглавието на секция, Assistant показва текста от главния .html файл на тази секция в дясната част на прозореца си, предназначена за представяне на документация. Описаната организационна структура на документацията изобщо не е свързана с физическото разположение на .html файловете в директории върху диска. Тя се описва в отделен профилен файл - текстов файл с разширение .adp и XML формат:
name – име на профила, което трябва да е уникално и да го отличава от профила с документация на други проекти.
title – заглавие на документацията, което се показва на заглавната лента на прозореца на Assistant. Ако искате да напишете заглавие на кирилица, използвайте UTF-8 кодиране.
applicationicon – икона на приложението. Тази икона ще се покаже и в прозореца на Assistant, когато той показва документацията на проекта.
startpage – стартова .html страница на документацията.
aboutmenutext – текст в help -> about… менюто, което показва Assistant и при избор на което се показва "Относно…" информацията за проекта.
abouturl – адрес на файла с "Относно…" информацията за проекта. За да се показва текст от този файл на кирилица, трябва да е с unicode UTF-8 кодиране.
assistantdocs – относителен, спрямо директорията, в която се намира .adp файла път до директорията с документация на Assistant. Във файловете от тази директория Assistant ще търси информация чрез Search функцията си, ако потребителя прибегне до тази функция.
ref – .html файл с главната страница на групата секции.
icon – файл с икона, която се показва върху "Go" лентата с бутони на Assistant.
title – Заглавие, което се показва в съдържанието.
Един
Създаване и инициализиране на QAssistantClient обект
За да покажете .html файлове с документация за във Вашия проект с Assistant, трябва да използвате класа QAssistantClient. Този клас не е част от Qt библиотеката и за да го използвате трябва да го обявите в .pro файла на Вашия проект, като добавите в този файл реда:
CONFIG += assistant
Не забравяйте, че след като сте променяли ръчно .pro файла трябва да изпълните qmake, преди да компилирате отново проекта си с make.
В началото на файла с изходен код, в който ще използвате обект от типа QAssistantClient е необходимо да добавите реда:
#include
Една добра идея, както е направено и в примерната програма simpletextviewer, е да отделите създаването и настройването на QAssistantClient обекта в отделна член-функция.
Обект от типа QAssistantClient се създава, например, така:
QAssistantClient *assistantClient;
assistantClient = new QAssistantClient(
QLibraryInfo::location(QLibraryInfo::BinariesPath), this
);
Първият параметър в конструктора QAssistantClient(…) е от типа QString и представлява пътя до директорията с help файлове, които трябва да показва Assistant. Тук е посочена директорията с изпълними файлове на Qt: QlibraryInfo::location(QLibraryInfo::BinariesPath).
Вторият параметър, който тук е this е родителският обект на създавания нов обект.
На създадения QAssistantClient обект трябва да се посочи .adp профил файла на документацията. Това става с помощта на член-функцията:
void setArguments ( const QStringList & arguments )
Аргумент на тази функция е списък от редове текст, които се предават като командни аргументи на Assistent при отварянето му. Списъкът се създава и попълва, например така:
QStringList arguments;
arguments << "-profile"
<< QString("help") + QDir::separator() + QString("typing3.adp");
с което за Assistant се приготвят аргументите: "-profile" и "help/typing3.adp".
Съставеният списък командни аргументи arguments се задава на QAssistantClient обекта:
assistantClient->setArguments(arguments);
с което той вече е готов за използване.
Използване на QAssistantClient обект
Важни член-функции на класа QAssistantClient са:
void openAssistant()
която предизвика отваряне на Assistant, на подразбиращата се help страница и
void showPage ( const QString & page )
която предизвиква отваряне на посочена help страница.
Тези функции се извикват от подходящи слот-функции, които приемат сигнали, изпратени при различни действия на потребителя – щракване в менюто, върху бутон, или др.
Предишна страница: Програмиране на Интернет операции
Следваща страница: Разпространяване на направени с Qt програми