Читать онлайн «QT 4: программирование GUI на С++». Страница 89

Использование 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 является свободно распространяемой интерактивной системой помощи, поддерживаемой фирмой «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.