Жасмин Бланшет - QT 4: программирование GUI на С++
Использование QTextBrowser в качестве простого браузера системы помощи
Для больших приложений может потребоваться более сложная система помощи в отличие от той, которую обычно обеспечивают всплывающие подсказки, комментарии в строке состояния и справки «что это такое?». Простое решение состоит в применении браузера системы помощи. Приложения, которые включают в себя браузер системы помощи, обычно имеют подпункт меню Help в меню Help главного окна и кнопку Help в каждом диалоговом окне.
В данном разделе мы представим простой браузер системы помощи, показанный на рис. 16.3, и покажем, как его можно использовать в приложении. Окно приложения применяет QTextBrowser для вывода на экран страниц справки, представленных в формате HTML. QTextBrowser может обрабатывать много тегов HTML, и поэтому он идеально подходит для этих целей.
Мы начинаем с заголовочного файла:
01 #include <QWidget>
02 class QPushButton;
03 class QTextBrowser;
04 class HelpBrowser : public QWidget
05 {
06 Q_OBJECT
07 public:
08 HelpBrowser(const QString &path,
09 const QString &page, QWidget *parent = 0);
10 static void showPage(const QString &page);
11 private slots:
12 void updateWindowTitle();
13 private:
14 QTextBrowser *textBrowser;
15 QPushButton *homeButton;
16 QPushButton *backButton;
17 QPushButton *closeButton;
18 };
Класс HelpBrowser содержит статическую функцию, которую можно вызывать в любом месте в приложении. Данная функция создает окно HelpBrowser и выводит на экран заданную страницу.
Рис. 16.3. Виджет HelpBrowser.
Ниже приводится начало реализации:
01 #include <QtGui>
02 #include "helpbrowser.h"
03 HelpBrowser::HelpBrowser(const QString &path,
04 const QString &page, QWidget *parent)
05 : QWidget(parent)
06 {
07 setAttribute(Qt::WA_DeleteOnClose);
08 setAttribute(Qt::WA_GroupLeader);
09 textBrowser = new QTextBrowser;
10 homeButton = new QPushButton(tr("&Home"));
11 backButton = new QPushButton(tr("&Back"));
12 closeButton = new QPushButton(tr("Close"));
13 closeButton->setShortcut(tr("Esc"));
14 QHBoxLayout *buttonLayout = new QHBoxLayout;
15 buttonLayout->addWidget(homeButton);
16 buttonLayout->addWidget(backButton);
17 buttonLayout->addStretch();
18 buttonLayout->addWidget(closeButton);
19 QVBoxLayout *mainLayout = new QVBoxLayout;
20 mainLayout->addLayout(buttonLayout);
21 mainLayout->addWidget(textBrowser);
22 setLayout(mainLayout);
23 connect(homeButton, SIGNAL(clicked()),
24 textBrowser, SLOT(home()));
25 connect(backButton, SIGNAL(clicked()),
26 textBrowser, SLOT(backward()));
27 connect(closeButton, SIGNAL(clicked()),
28 this, SLOT(close()));
29 connect(textBrowser, SIGNAL(sourceChanged(const QUrl &)),
30 this, SLOT(updateWindowTitle()));
31 textBrowser->setSearchPaths(QStringList() << path << ":/images");
32 textBrowser->setSource(page);
33 }
Мы устанавливаем атрибут Qt::WA_GroupLeader, потому что хотим выдавать окна HelpBrowser не только из главного окна, но также из модальных диалоговых окон. Обычно модальные диалоговые окна не позволяют пользователям работать с другими окнами приложения. Однако очевидно, что после запроса помощи пользователь должен иметь возможность работать как с модальным диалоговым окном, так и с браузером системы помощи. Установка атрибута Qt::WA_GroupLeader делает возможным такой режим работы.
Мы обеспечиваем два пути поиска: первый определяет путь в файловой системе к документации приложения, а второй определяет расположение ресурсов изображений. HTML может содержать обычные ссылки на изображения в файловой системе и ссылки на ресурсы изображений, пути которых начинаются с символов :/ (двоеточие и слеш). Параметр page содержит имя файла документации с возможным указанием метки HTML (anchor).
01 void HelpBrowser::updateWindowTitle()
02 {
03 setWindowTitle(tr("Help: %1")
04 .arg(textBrowser->documentTitle()));
05 }
При всяком изменении исходной страницы вызывается слот updateWindowTitle(). Функция documentTitle() возвращает текст, содержащийся в теге <title> этой страницы.
01 void HelpBrowser::showPage(const QString &page)
02 {
03 QString path = QApplication::applicationDirPath() + "/doc";
04 HelpBrowser *browser = new HelpBrowser(path, page);
05 browser->resize(500, 400);
06 browser->show();
07 }
В статической функции showPage() мы создаем окно HelpBrowser и затем выдаем его на экран. Это окно будет удалено автоматически, когда пользователь закроет его, поскольку мы установили в конструкторе HelpBrowser атрибут Qt::WA_DeleteOnClose.
В этом примере мы предполагаем, что документация располагается в подкаталоге doc того каталога, где находится исполняемый модуль приложения. Все страницы, передаваемые функции showPage(), будут браться из этого подкаталога.
Теперь мы можем вызывать браузер системы помощи из приложения. В главном окне приложения мы могли бы создать команду Help и подсоединить ее к слоту help(), который может иметь следующий вид:
01 void MainWindow::help()
02 {
03 HelpBrowser::showPage("index.html");
04 }
Здесь предполагается, что главный файл системы помощи имеет имя index.html. Для диалоговых окон мы могли бы подсоединить кнопку Help к слоту help(), который может иметь следующий вид:
01 void EntryDialog::help()
02 {
03 HelpBrowser::showPage("forms.html#editing");
04 }
Здесь мы выводим на экран другой справочный файл, forms.html, и позиционируем браузер QTextBrowser нa метку editing.
Использование Qt Assistant для мощной интерактивной системы помощи
Qt Assistant является свободно распространяемой интерактивной системой помощи, поддерживаемой фирмой «Trolltech». Основным ее достоинством является поддержка индексации и поиск по всему тексту, а также возможность ее работы с наборами документации нескольких приложений.
Для применения Qt Assistant мы должны включить в наше приложение соответствующий программный код и указать Qt Assistant место расположения нашей документации.
Связь между приложением Qt и QtAssistant обеспечивается классом QAssistantClient, который располагается в отдельной библиотеке. Для сборки этой библиотеки с нашим приложением мы должны добавить следующую строку к файлу приложения .pro:
CONFIG += assistant
Теперь мы рассмотрим программный код нового класса HelpBrowser, который использует Qt Assistant.
01 #ifndef HELPBROWSER_H
02 #define HELPBROWSER_H
03 class QAssistantClient;
04 class QString;
05 class HelpBrowser
06 {
07 public:
08 static void showPage(const QString &page);
09 private:
10 static QAssistantClient *assistant;
11 };
12 #endif
Ниже приводится новый файл helpbrowser.cpp:
01 #include <QApplication>
02 #include <QAssistantClient>
03 #include "helpbrowser.h"
04 QAssistantClient *HelpBrowser::assistant = 0;
05 void HelpBrowser::showPage(const QString &page)
06 {
07 QString path = QApplication::applicationDirPath() + "/doc/" + page;
08 if (!assistant)
09 assistant = new QAssistantClient("");
10 assistant->showPage(path);
11 }
Конструктор QAssistantClient принимает в качестве своего первого аргумента строку пути, который используется для определения места нахождения исполняемого модуля Qt Assistant. Передавая пустой путь, мы указываем на необходимость QAssistantClient поиска исполняемого модуля в путях переменной среды PATH. QAssistantClient имеет функцию showPage(), которая принимает имя файла страницы HTML с необязательным указанием метки позиции.
На следующем этапе необходимо подготовить оглавление и предметный указатель документации. Это выполняется путем создания профиля Qt Assistant и файла .dcf, который содержит сведения о документации. Все это объясняется в документации по Qt Assistant, и поэтому мы не станем здесь повторять эти сведения.
В качестве альтернативы QTextBrowser или Qt Assistant можно спользовать зависящие от платформы методы обеспечения интерактивной помощи. Для приложений Windows можно создать файлы системы помощи Windows HTML Help и обеспечить доступ к ним при помощи Internet Explorer компании Microsoft. Вы могли бы использовать для этого класс Qt QProcess или рабочую среду ActiveQt. Для приложений X11 подходящий метод мог бы состоять в создании файлов HTML и запуске веб-браузера, с использованием QProcess. В Mac OS X подсистема Apple Help предоставляет аналогичные функциональные возможности для Qt Assistant.
