Helpsystem

This example demonstrates the different Qt classes that can be used to provide context sensitive help in an application.

It uses QToolTip and QWhatsThis to provide both static and dynamic balloon help for the widgets in the application, and QToolTipGroup to display extended information for each tooltip in the statusbar. QAssistantClient is used to display help pages using Qt Assistant.

The application has a user interface based on a QMainWindow with a menubar, statusbar and a toolbar, and uses a QTable as the central widget.

    class HeaderToolTip : public QToolTip
    {
    public:
        HeaderToolTip( QHeader *header, QToolTipGroup *group = 0 );

    protected:
        void maybeTip ( const QPoint &p );
    };

Two QToolTip subclasses implement dynamic tooltips for QHeader and QTable by reimplementing maybeTip(). The constructors differ from the QToolTip constructor in having a QHeader and a QTable respectively as the first parameter for the constructor instead of a QWidget. This is because we want to ensure that only headers and tables can be passed as arguments. A QToolTipGroup can be provided as the second argument to show tooltips in, for example a statusbar.

    class TableToolTip : public QToolTip
    {
    public:
        TableToolTip( QTable* table, QToolTipGroup *group = 0  );

    protected:
        void maybeTip( const QPoint &p );

    private:
        QTable *table;
    };

The TableToolTip class keeps a reference to the QTable as a member for easier access of the QTable object later on.

    HeaderToolTip::HeaderToolTip( QHeader *header, QToolTipGroup *group )
    : QToolTip( header, group )
    {
    }

The HeaderToolTip constructor propagates the parameters to the QToolTip constructor.

    void HeaderToolTip::maybeTip ( const QPoint& p )
    {
        QHeader *header = (QHeader*)parentWidget();

        int section = 0;

        if ( header->orientation() == Horizontal )
            section= header->sectionAt( p.x() );
        else
            section= header->sectionAt( p.y() );

        QString tipString = header->label( section );
        tip( header->sectionRect( section ), tipString, "This is a section in a header" );
    }

The implementation of maybeTip() uses the QHeader API to get the section at the requested position and uses QToolTip::tip() to display the section's label in a tooltip. The second string is used by QToolTipGroup and will show up in the statusbar.

    TableToolTip::TableToolTip( QTable *tipTable, QToolTipGroup *group )
    : QToolTip( tipTable->viewport(), group ), table( tipTable )
    {
    }

Since QTable is a QScrollView all user interaction happens on QTable's viewport() . The TableToolTip constructor passes the viewport() and the tooltip group to the QToolTip constructor, and initializes the table member with the QTable pointer itself.

    void TableToolTip::maybeTip ( const QPoint &p )
    {
        QPoint cp = table->viewportToContents( p );
        int row = table->rowAt( cp.y() );
        int col = table->columnAt( cp.x() );

        QString tipString = table->text( row, col );

        QRect cr = table->cellGeometry( row, col );

The implementation of maybeTip() uses the QTable API to get information about the cell at the requested position. The QTable API expects contents coordinates, and since the requested point is relative to the viewport we need to translate the coordinates before we can use QTable's functions.

        cr.moveTopLeft( table->contentsToViewport( cr.topLeft() ) );
        tip( cr, tipString, "This is a cell in a table" );
    }

We translate the cell's geometry back to viewport coordinates so that the tooltip disappears when the mouse cursor leaves the cell, and use QToolTip::tip() to display the cell's label in a tooltip and to provide text for the QToolTipGroup as before.

    class WhatsThis : public QObject, public QWhatsThis
    {
        Q_OBJECT
    public:
        WhatsThis( QWidget *w, QWidget *watch = 0 );

        bool clicked( const QString &link );
        QWidget *parentWidget() const;

    signals:
        void linkClicked( const QString &link );

    private:
        QWidget *widget;
    };

The WhatsThis class is a subclass of both QObject and QWhatsThis and serves as a base class for the HeaderWhatsThis and TableWhatsThis classes. ⁽¹⁾ WhatsThis reimplements clicked() which will be called when the user clicks inside the "What's this?" window. It also declares a signal linkClicked() which will be emitted when a hyperlink is clicked.

    WhatsThis::WhatsThis( QWidget *w, QWidget *watch )
    : QWhatsThis( watch ? watch : w ), widget( w )
    {
    }

The WhatsThis constructor takes two parameters, the first is the widget we want to provide WhatsThis for, and the second is the one which receives the events. Normally this is the same widget, but some widgets, like QTable, are more complex and have a viewport() widget which receives the events. If such a widget is passed to the constructor it will propagate the parameter to the QWhatsThis constructor and store the QWidget pointer itself in it's member variable to allow easier use of the QWidget API later on.

    bool WhatsThis::clicked( const QString &link )
    {
        if ( !link.isEmpty() )
            emit linkClicked( link );

        return TRUE;
    }

The implementation of clicked() emits the linkClicked() signal if a hyperlink has been clicked.

    class HeaderWhatsThis : public WhatsThis
    {
    public:
        HeaderWhatsThis( QHeader *h );

        QString text( const QPoint &p );
    };

    class TableWhatsThis : public WhatsThis
    {
    public:
        TableWhatsThis( QTable *t );

        QString text( const QPoint &p );
    };

The HeaderWhatsThis and TableWhatsThis classes reimplement text() to make it possible to return texts depending on the mouse click's position. All the other functionality is already provided by the generic WhatsThis base class. We ensure type safety here in the same manner as in the tooltip classes.

    HeaderWhatsThis::HeaderWhatsThis( QHeader *h )
    : WhatsThis( h )
    {
    }

The HeaderWhatsThis constructor propagates the parameter to the WhatsThis constructor.

    QString HeaderWhatsThis::text( const QPoint &p )
    {
        QHeader *header = (QHeader*)parentWidget();

        QString orient;
        int section;
        if ( header->orientation() == QObject::Horizontal ) {
            orient = "horizontal";
            section = header->sectionAt( p.x() );
        } else {
            orient = "vertical";
            section = header->sectionAt( p.y() );
        }
        if( section == -1 )
            return "This is empty space.";
        QString docsPath = QDir("../../doc").absPath();
        return QString("This is section number %1 in the %2 <a href=%2/html/qheader.html>header</a>.").
            arg(section + 1).
            arg(orient).
            arg(docsPath);
    }

The implementation of text() uses the QHeader API to determine whether we have a horizontal or a vertical header and returns a string which states the header's orientation and section. ⁽²⁾

    TableWhatsThis::TableWhatsThis( QTable *t )
    : WhatsThis( t, t->viewport() )
    {
    }

Since QTable is a scrollview and has a viewport() which receives the events, we propagate the table itself and the table's viewport() to the WhatsThis constructor.

    QString TableWhatsThis::text( const QPoint &p )
    {
        QTable *table = (QTable*)parentWidget();

        QPoint cp = table->viewportToContents( p );
        int row = table->rowAt( cp.y() );
        int col = table->columnAt( cp.x() );

        if ( row == -1 || col == -1 )
            return "This is empty space.";

        QTableItem* i = table->item( row,col  );
        if ( !i )
            return "This is an empty cell.";

        QString docsPath = QDir("../../doc").absPath();

        if ( QTableItem::RTTI == i->rtti() ) {
            return QString("This is a <a href=%1/html/qtableitem.html>QTableItem</a>.").
                           arg(docsPath);
        } else if ( QComboTableItem::RTTI == i->rtti() ) {
            return QString("This is a <a href=%1/html/qcombotableitem.html>QComboTableItem</a>."
                           "<br>It can be used to provide multiple-choice items in a table.").
                           arg(docsPath);
        } else if ( QCheckTableItem::RTTI == i->rtti() ) {
            return QString("This is a <a href=%1/html/qchecktableitem.html>QCheckTableItem</a>."
                           "<br>It provide <a href=%1/html/qcheckbox.html>checkboxes</a> in tables.").
                           arg(docsPath).arg(docsPath);
        }
        return "This is a user defined table item.";
    }

The implementation of text() uses the QTable API to get information about the cell at the requested position. The QTable API expects contents coordinates, so we need to translate the point as shown earlier for the tooltip classes. We use the rtti() function to figure out the item's type and return a string accordingly.

    class MainWindow : public QMainWindow
    {
        Q_OBJECT
    public:
        MainWindow();
        ~MainWindow();

    public slots:
        void assistantSlot();

    private:
        HeaderToolTip *horizontalTip;
        HeaderToolTip *verticalTip;
        TableToolTip *cellTip;
        QAssistantClient *assistant;
    };

A QMainWindow is used to create a user interface that uses the above classes in addition to Qt Assistant to provide context sensitive help in the application.

The MainWindow class declares a slot called assistantSlot() which creates an instance of Qt Assistant when it is called. The class keeps references to the tooltip classes as members because they are not QObjects and need to be deleted explicitly. The class has a reference to QAssistantClient as a member as well, to allow easier access to Qt Assistant later on.

    MainWindow::MainWindow()
    {
        statusBar();
        assistant = new QAssistantClient( QDir("../../bin").absPath(), this );

The MainWindow constructor creates an instance of QAssistantClient using QString::null as the first argument so that the system path is used.

        QTable* table = new QTable( 2, 3, this );
        setCentralWidget( table );

        // populate table
        QStringList comboEntries;
        comboEntries << "one" << "two" << "three" << "four";
        QComboTableItem* comboItem1 = new QComboTableItem( table, comboEntries );
        QComboTableItem* comboItem2 = new QComboTableItem( table, comboEntries );
        QCheckTableItem* checkItem1 = new QCheckTableItem( table, "Check me" );
        QCheckTableItem* checkItem2 = new QCheckTableItem( table, "Check me" );

        table->setItem( 0, 0, comboItem1 );
        table->setItem( 1, 0, comboItem2 );

        table->setItem( 1, 1, checkItem1  );
        table->setItem( 0, 1, checkItem2 );

        table->setText( 1, 2, "Text" );

        table->horizontalHeader()->setLabel( 0, " Combos" );
        table->horizontalHeader()->setLabel( 1, "Checkboxes" );
        table->verticalHeader()->setLabel( 0, "1" );
        table->verticalHeader()->setLabel( 1, "2" );

        // populate menubar
        QPopupMenu* fileMenu = new QPopupMenu( this );
        QPopupMenu* helpMenu = new QPopupMenu( this );

        menuBar()->insertItem( "&File", fileMenu );
        menuBar()->insertItem( "&Help", helpMenu );

        int fileId = fileMenu->insertItem( "E&xit", this, SLOT(close()) );

        int helpId = helpMenu->insertItem( "Open Assistant", this, SLOT(assistantSlot()) );

        // populate toolbar
        QToolBar* toolbar = new QToolBar( this );
        QToolButton* assistantButton = new QToolButton( toolbar );
        assistantButton->setIconSet( QPixmap("appicon.png") );

A QTable is used as the central widget and the table, the menus and the toolbar are populated.

        QWhatsThis::whatsThisButton( toolbar );

The static function whatsThisButton() creates a QToolButton which will enter "What's this?" mode when clicked.

        //create tooltipgroup
        QToolTipGroup * tipGroup = new QToolTipGroup( this );
        connect( tipGroup, SIGNAL(showTip(const QString&)), statusBar(),
            SLOT(message(const QString&)) );
        connect( tipGroup, SIGNAL(removeTip()), statusBar(), SLOT(clear()) );

A QToolTipGroup is created and will show and remove tooltips in the statusbar as the tooltips are displayed on the widgets.

        // set up tooltips
        QToolTip::add( assistantButton, tr ("Open Assistant"), tipGroup, "Opens Qt Assistant" );

        horizontalTip = new HeaderToolTip( table->horizontalHeader(), tipGroup );
        verticalTip = new HeaderToolTip( table->verticalHeader(), tipGroup );

        cellTip = new TableToolTip( table, tipGroup );

The tooltips are set up. The static function add() sets up a tooltip on the Assistant toolbutton. Tooltip objects are created using the QToolTip subclasses, the constructor's first parameter specifies the widget we want to add dynamic tooltips for and the second argument specifies the QToolTipGroup they should belong to.

        // set up whats this
        QWhatsThis::add ( assistantButton, "This is a toolbutton which opens Assistant" );

        HeaderWhatsThis *horizontalWhatsThis = new HeaderWhatsThis( table->horizontalHeader() );
        HeaderWhatsThis *verticalWhatsThis = new HeaderWhatsThis( table->verticalHeader() );

        TableWhatsThis *cellWhatsThis = new TableWhatsThis( table );

        fileMenu->setWhatsThis( fileId, "Click here to exit the application" );
        helpMenu->setWhatsThis( helpId, "Click here to open Assistant" );

The WhatsThis help is set up. The static function add() adds What's This? help for the toolbutton which opens Assistant. Instances of the two WhatsThis subclasses are created for the headers and the table. What's This? help is also added for the menu items.

        // connections
        connect( assistantButton, SIGNAL(clicked()), this, SLOT(assistantSlot()) );
        connect( horizontalWhatsThis, SIGNAL(linkClicked(const QString&)), assistant,
            SLOT(showPage(const QString&)) );
        connect( verticalWhatsThis, SIGNAL(linkClicked(const QString&)), assistant,
            SLOT(showPage(const QString&)) );
        connect( cellWhatsThis, SIGNAL(linkClicked(const QString&)), assistant,
            SLOT(showPage(const QString&)) );
    }

Signals and slots are connected, so that the relevant pages will be displayed in Qt Assistant when clicking on a hyperlink or on the assistant button.

    MainWindow::~MainWindow()
    {
        delete horizontalTip;
        delete verticalTip;
        delete cellTip;
    }

The destructor deletes the tooltips. We need to delete the tooltips explicitly since QToolTip is, as mentioned above, not a subclass of QObject and the instances of QToolTip not will be deleted when the widget is deleted.

    void MainWindow::assistantSlot()
    {
        QString docsPath = QDir("../../doc").absPath();
        assistant->showPage( QString("%1/html/qassistantclient.html").arg(docsPath) );
    }

The assistantSlot() uses applicationDirPath() to find the location of the documentation files and shows the specified page in Qt Assistant.

    #include <qapplication.h>
    #include "mainwindow.h"

    int main( int argc, char** argv )
    {
        QApplication app( argc, argv );
        MainWindow main;
        main.show();
        app.setMainWidget( &main );
        return app.exec();
    }

The main function is a standard implementation opening the application main window.

To build the example go to the helpsystem directory (QTDIR/examples/helpsystem) run qmake to generate the makefile, and use the make tool to build the library.

1. Note that moc requires that QObject is the first base class. Back...
2. Note that we have to explicitly scope the orientation (QObject or QWhatsThis) since HeaderWhatsThis uses multiple inheritance. Back...

   See also Examples.