Использование QTextBrowser в качестве простого браузера системы помощи
Использование 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.