16.2. Использование QTextBrowser для отображения текста справки.

Большие серьезные приложения могут содержать объем справочной информации, намного превышающий возможности всплывающих подсказок и даже подсказок типа "What's This?". Самое простое решение в этом случае -- создать обозреватель справочной системы. Приложение может открывать окно обозревателя справки при выборе пункта Help, в меню Help, или при нажатии на кнопку Help в панели инструментов.

В этом разделе мы рассмотрим простейший обозреватель справочной системы, внешний вид которого представлен на рисунке 16.3, и опишем, как его использовать в приложении. Для отображения текста справки используется QTextBrowser, который может обрабатывать некоторые теги HTML и идеально подходит под заданные условия.

Как обычно, начнем с заголовочного файла: #include <qwidget.h> class QPushButton; class QTextBrowser; class HelpBrowser : public QWidget { Q_OBJECT public: HelpBrowser(const QString &path, const QString &page, QWidget *parent = 0, const char *name = 0); static void showPage(const QString &page); private slots: void updateCaption(); private: QTextBrowser *textBrowser; QPushButton *homeButton; QPushButton *backButton; QPushButton *closeButton; }; HelpBrowser имеет статическую функцию, которая может вызываться из любого места в приложении. Она создает окно обозревателя и показывает запрошенную страницу.

Теперь исходный код файла реализации:

#include <qapplication.h> #include <qlayout.h> #include <qpushbutton.h> #include <qtextbrowser.h> #include "helpbrowser.h" HelpBrowser::HelpBrowser(const QString &path, const QString &page, QWidget *parent, const char *name) : QWidget(parent, name, WGroupLeader | WDestructiveClose) { textBrowser = new QTextBrowser(this); homeButton = new QPushButton(tr("&Home"), this); backButton = new QPushButton(tr("&Back"), this); closeButton = new QPushButton(tr("Close"), this); closeButton->setAccel(tr("Esc")); QVBoxLayout *mainLayout = new QVBoxLayout(this); QHBoxLayout *buttonLayout = new QHBoxLayout(mainLayout); buttonLayout->addWidget(homeButton); buttonLayout->addWidget(backButton); buttonLayout->addStretch(1); buttonLayout->addWidget(closeButton); mainLayout->addWidget(textBrowser); connect(homeButton, SIGNAL(clicked()), textBrowser, SLOT(home())); connect(backButton, SIGNAL(clicked()), textBrowser, SLOT(backward())); connect(closeButton, SIGNAL(clicked()), this, SLOT(close())); connect(textBrowser, SIGNAL(sourceChanged(const QString &)), this, SLOT(updateCaption())); textBrowser->mimeSourceFactory()->addFilePath(path); textBrowser->setSource(page); } Размещение компонентов в окне более чем простое: ряд кнопок находится над QTextBrowser. Аргумент path -- это путь к каталогу, где находятся файлы с текстом справки. Аргумент page -- имя файла справки, с необязательным названием темы (в терминах HTML -- anchor, или имя ссылки).

Мы передаем конструктору флаг WGroupLeader, потому что окно HelpBrowser может открываться из модальных диалогов. Обычно модальные диалоги не позволяют пользователю взаимодействовать с другими окнами приложения. Однако, в данном случае, после того как пользователь запросил помощь, он должен иметь возможность работать как с окном модального диалога, так и с окном обозревателя справочной системы. Флаг WGroupLeader обеспечивает такую возможность.

void HelpBrowser::updateCaption() { setCaption(tr("Help: %1").arg(textBrowser->documentTitle())); } Всякий раз, при переходе на другую страницу, вызывается слот updateCaption(). Функция documentTitle() возвращает текст, заданный в теге <title>. void HelpBrowser::showPage(const QString &page) { QString path = qApp->applicationDirPath() + "/doc"; HelpBrowser *browser = new HelpBrowser(path, page); browser->resize(500, 400); browser->show(); } В функции showPage() создается окно обозревателя и затем выводится на экран. Окно будет уничтожено автоматически, когда пользователь закроет его, поскольку в конструкторе был установлен флаг WDestructiveClose.

В данном примере мы исходим из предположения, что файлы справки находятся в подкаталоге doc.

Теперь можно вызвать обозреватель из приложения. Для этого, в главном окне приложения, мы создадим объект QAction -- Help и соединим его со слотом help():

void MainWindow::help() { HelpBrowser::showPage("index.html"); } Мы полагаем, что основной файл справки называется index.html. Чтобы вызвать обозреватель из диалога, нужно связать соответствующую кнопку Help со слотом help(): void EntryDialog::help() { HelpBrowser::showPage("dialogs.html#entrydialog"); } Здесь мы обращаемся уже к другому файлу справки -- dialogs.html и выполняем переход к ссылке entrydialog.

Еще одно место, откуда можно вызвать обозреватель справочной системы -- текст справки типа "What's This?". Для этого достаточно вставить в текст справки "What's This?" тег HTML <a href="...">.

Чтобы такая гипертекстовая ссылка работала, мы должны использовать класс, производный от QWhatsThis, который будет "знать", как вызвать обозреватель справочной системы. Для этого надо в классе-потомке перекрыть метод clicked(), в котором вызвать HelpBrowser:: showPage(). Ниже приводится определение класса: class MyWhatsThis : public QWhatsThis { public: MyWhatsThis(QWidget *widget, const QString &text); QString text(const QPoint &point); bool clicked(const QString &page); private: QString myText; }; Где text() и clicked() -- это методы предка, перекрываемые потомком. MyWhatsThis::MyWhatsThis(QWidget *widget, const QString &text) : QWhatsThis(widget) { myText = text; } Конструктор получает указатель на виджет и текст справки для этого виджета. Мы передаем указатель на виджет базовому конструктору и сохраняем текст справки в приватной переменной. QString MyWhatsThis::text(const QPoint &) { return myText; } Функция text() возвращает текст справки виджета, для заданных координат указателя мыши. Некоторые виджеты могут возвращать разный текст справки, в зависимости от того, где был произведен щелчок мышью, но в данном примере мы всегда будем возвращать один и тот же текст. bool MyWhatsThis::clicked(const QString &page) { if (page.isEmpty()) { return true; } else { HelpBrowser::showPage(page); return false; } } Функция clicked() вызывается в момент щелчка мышью по виджету, когда окно находится в режиме "What's This?". Если пользователь щелкает по гиперссылке, то функция получит название страницы в аргументе page. В противном случае в page будет пустая строка.

Возвращаемое значение используется базовым классом QWhatsThis для того, чтобы определить, что делать дальше -- скрыть (true) подсказку "What's This?" или оставить ее видимой (false). В данной ситуации мы хотим, чтобы текст "What's This?" оставался видимым на экране, поэтому возвращаем false. Когда пользователь щелкает по любому другому месту в тексте "What's This?", мы возвращаем true.

Ниже показан пример использования класса MyWhatsThis:

new MyWhatsThis(sourceLineEdit, tr("<img src=\"icon.png\">" "&nbsp;The meaning of the " "<a href=\"fields.html#source\">Source</a> field depends on " "the <a href=\"fields.html#type\">Type</a> field:" "<ul>" "<li><b>Books</b> have a Publisher</li>" "<li><b>Articles</b> have a Journal name with volume and " "issue number</li>" "<li><b>Thesis</b> have an Institution name and a department " "name</li>" "</ul>")); На этот раз, вместо вызова QWhatsThis::add(), мы создаем экземпляр класса MyWhatsThis для виджета, с текстом подсказки. Теперь пользователь может щелкнуть по гипертекстовой ссылке и вызвать обозреватель справочной системы.

Выглядит немного странно, так как мы создаем объект, но не связываем его с какой бы то ни было переменной. Но это только на первый взгляд, потому что Qt сама следит за создаваемыми объектами класса QWhatsThis и удаляет их, когда необходимость в них отпадает.