Създаване на 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 изглежда така:

mycompany.com

product_1.0

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 на тези елементи могат да имат стойности:

name – име на профила, което трябва да е уникално и да го отличава от профила с документация на други проекти.

title – заглавие на документацията, което се показва на заглавната лента на прозореца на Assistant. Ако искате да напишете заглавие на кирилица, използвайте UTF-8 кодиране.

applicationicon – икона на приложението. Тази икона ще се покаже и в прозореца на Assistant, когато той показва документацията на проекта.

startpage – стартова .html страница на документацията.

aboutmenutext – текст в help -> about… менюто, което показва Assistant и при избор на което се показва "Относно…" информацията за проекта.

abouturl – адрес на файла с "Относно…" информацията за проекта. За да се показва текст от този файл на кирилица, трябва да е с unicode UTF-8 кодиране.

assistantdocs – относителен, спрямо директорията, в която се намира .adp файла път до директорията с документация на Assistant. Във файловете от тази директория Assistant ще търси информация чрез Search функцията си, ако потребителя прибегне до тази функция.

елемента съдържа описание на група секции. В документацията може да има няколко групи секции, които се появяват като начални (коренови) елементи на дървото от заглавия в страничния панел на Assistant. Атрибутите на елемента са:

ref – .html файл с главната страница на групата секции.

icon – файл с икона, която се показва върху "Go" лентата с бутони на Assistant.

title – Заглавие, което се показва в съдържанието.

елемента може да е празен или да съдържа

елементи.

Един

елемент има два атрибута ref и title. Може да бъде празен или да съдържа други
елементи или .

елементите имат само един атрибут ref и съдържат текст – ключова дума която се показва в Index частта на страничния панел на Assistant.

Създаване и инициализиране на 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 страница.

Тези функции се извикват от подходящи слот-функции, които приемат сигнали, изпратени при различни действия на потребителя – щракване в менюто, върху бутон, или др.

 

Направено с MyCMS. Copyright CC BY-ND 4.0.