From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/helpsystem-example.html | 494 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 494 insertions(+) create mode 100644 doc/html/helpsystem-example.html (limited to 'doc/html/helpsystem-example.html') diff --git a/doc/html/helpsystem-example.html b/doc/html/helpsystem-example.html new file mode 100644 index 0000000..19b34c7 --- /dev/null +++ b/doc/html/helpsystem-example.html @@ -0,0 +1,494 @@ + + + + + +Helpsystem + + + + + + + +

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( header->offset() + p.x() );
+        else
+            section = header->sectionAt( header->offset() + 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. + +

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