From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- 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 000000000..2c24cfc6b --- /dev/null +++ b/doc/html/helpsystem-example.html @@ -0,0 +1,494 @@ + + + + + +Helpsystem + + + + + + + +

Helpsystem

+ + + +

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

It uses TQToolTip and TQWhatsThis to provide both static and +dynamic balloon help for the widgets in the application, and +TQToolTipGroup to display extended information for each tooltip +in the statusbar. TQAssistantClient is used to display help +pages using TQt Assistant. +

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

    class HeaderToolTip : public TQToolTip
+    {
+    public:
+        HeaderToolTip( TQHeader *header, TQToolTipGroup *group = 0 );
+
+    protected:
+        void maybeTip ( const TQPoint &p );
+    };
+

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

    class TableToolTip : public TQToolTip
+    {
+    public:
+        TableToolTip( TQTable* table, TQToolTipGroup *group = 0  );
+
+    protected:
+        void maybeTip( const TQPoint &p );
+
+    private:
+        TQTable *table;
+    };
+

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

+ +

    HeaderToolTip::HeaderToolTip( TQHeader *header, TQToolTipGroup *group )
+    : TQToolTip( header, group )
+    {
+    }
+

The HeaderToolTip constructor propagates the parameters +to the TQToolTip constructor. +

    void HeaderToolTip::maybeTip ( const TQPoint& p )
+    {
+        TQHeader *header = (TQHeader*)parentWidget();
+
+        int section = 0;
+
+        if ( header->orientation() == Horizontal )
+            section = header->sectionAt( header->offset() + p.x() );
+        else
+            section = header->sectionAt( header->offset() + p.y() );
+
+        TQString tipString = header->label( section );
+        tip( header->sectionRect( section ), tipString, "This is a section in a header" );
+    }
+

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

    TableToolTip::TableToolTip( TQTable *tipTable, TQToolTipGroup *group )
+    : TQToolTip( tipTable->viewport(), group ), table( tipTable )
+    {
+    }
+

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

    void TableToolTip::maybeTip ( const TQPoint &p )
+    {
+        TQPoint cp = table->viewportToContents( p );
+        int row = table->rowAt( cp.y() );
+        int col = table->columnAt( cp.x() );
+
+        TQString tipString = table->text( row, col );
+
+        TQRect cr = table->cellGeometry( row, col );
+

The implementation of maybeTip() uses the TQTable API +to get information about the cell at the requested position. +The TQTable API expects contents coordinates, and since the +requested point is relative to the viewport we need to translate +the coordinates before we can use TQTable'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 TQToolTip::tip() to display the cell's label +in a tooltip and to provide text for the TQToolTipGroup as before. +

    class WhatsThis : public TQObject, public TQWhatsThis
+    {
+        Q_OBJECT
+    public:
+        WhatsThis( TQWidget *w, TQWidget *watch = 0 );
+
+        bool clicked( const TQString &link );
+        TQWidget *parentWidget() const;
+
+    signals:
+        void linkClicked( const TQString &link );
+
+    private:
+        TQWidget *widget;
+    };
+

+ + + +

The WhatsThis class is a subclass of both TQObject and +TQWhatsThis 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( TQWidget *w, TQWidget *watch )
+    : TQWhatsThis( 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 TQTable, 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 TQWhatsThis constructor and store the TQWidget pointer itself +in it's member variable to allow easier use of the TQWidget API +later on. +

    bool WhatsThis::clicked( const TQString &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( TQHeader *h );
+
+        TQString text( const TQPoint &p );
+    };
+

    class TableWhatsThis : public WhatsThis
+    {
+    public:
+        TableWhatsThis( TQTable *t );
+
+        TQString text( const TQPoint &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( TQHeader *h )
+    : WhatsThis( h )
+    {
+    }
+

The HeaderWhatsThis constructor propagates the parameter to the +WhatsThis constructor. +

    TQString HeaderWhatsThis::text( const TQPoint &p )
+    {
+        TQHeader *header = (TQHeader*)parentWidget();
+
+        TQString orient;
+        int section;
+        if ( header->orientation() == TQObject::Horizontal ) {
+            orient = "horizontal";
+            section = header->sectionAt( p.x() );
+        } else {
+            orient = "vertical";
+            section = header->sectionAt( p.y() );
+        }
+        if( section == -1 )
+            return "This is empty space.";
+        TQString docsPath = TQDir("../../doc").absPath();
+        return TQString("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 TQHeader 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( TQTable *t )
+    : WhatsThis( t, t->viewport() )
+    {
+    }
+

Since TQTable 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. +

    TQString TableWhatsThis::text( const TQPoint &p )
+    {
+        TQTable *table = (TQTable*)parentWidget();
+
+        TQPoint 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.";
+
+        TQTableItem* i = table->item( row,col  );
+        if ( !i )
+            return "This is an empty cell.";
+
+        TQString docsPath = TQDir("../../doc").absPath();
+
+        if ( TQTableItem::RTTI == i->rtti() ) {
+            return TQString("This is a <a href=%1/html/qtableitem.html>TQTableItem</a>.").
+                           arg(docsPath);
+        } else if ( TQComboTableItem::RTTI == i->rtti() ) {
+            return TQString("This is a <a href=%1/html/qcombotableitem.html>TQComboTableItem</a>."
+                           "<br>It can be used to provide multiple-choice items in a table.").
+                           arg(docsPath);
+        } else if ( TQCheckTableItem::RTTI == i->rtti() ) {
+            return TQString("This is a <a href=%1/html/qchecktableitem.html>TQCheckTableItem</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 TQTable API to get +information about the cell at the requested position. +The TQTable 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 TQMainWindow
+    {
+        Q_OBJECT
+    public:
+        MainWindow();
+        ~MainWindow();
+
+    public slots:
+        void assistantSlot();
+
+    private:
+        HeaderToolTip *horizontalTip;
+        HeaderToolTip *verticalTip;
+        TableToolTip *cellTip;
+        TQAssistantClient *assistant;
+    };
+

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

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

+ +

    MainWindow::MainWindow()
+    {
+        statusBar();
+        assistant = new TQAssistantClient( TQDir("../../bin").absPath(), this );
+

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

        TQTable* table = new TQTable( 2, 3, this );
+        setCentralWidget( table );
+
+        // populate table
+        TQStringList comboEntries;
+        comboEntries << "one" << "two" << "three" << "four";
+        TQComboTableItem* comboItem1 = new TQComboTableItem( table, comboEntries );
+        TQComboTableItem* comboItem2 = new TQComboTableItem( table, comboEntries );
+        TQCheckTableItem* checkItem1 = new TQCheckTableItem( table, "Check me" );
+        TQCheckTableItem* checkItem2 = new TQCheckTableItem( 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
+        TQPopupMenu* fileMenu = new TQPopupMenu( this );
+        TQPopupMenu* helpMenu = new TQPopupMenu( 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
+        TQToolBar* toolbar = new TQToolBar( this );
+        TQToolButton* assistantButton = new TQToolButton( toolbar );
+        assistantButton->setIconSet( TQPixmap("appicon.png") );
+

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

        TQWhatsThis::whatsThisButton( toolbar );
+

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

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

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

        // set up tooltips
+        TQToolTip::add( assistantButton, tr ("Open Assistant"), tipGroup, "Opens TQt 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 TQToolTip subclasses, the constructor's first parameter +specifies the widget we want to add dynamic tooltips for and the +second argument specifies the TQToolTipGroup they should belong +to. +

        // set up whats this
+        TQWhatsThis::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 TQString&)), assistant,
+            SLOT(showPage(const TQString&)) );
+        connect( verticalWhatsThis, SIGNAL(linkClicked(const TQString&)), assistant,
+            SLOT(showPage(const TQString&)) );
+        connect( cellWhatsThis, SIGNAL(linkClicked(const TQString&)), assistant,
+            SLOT(showPage(const TQString&)) );
+    }
+

Signals and slots are connected, so that the relevant pages will +be displayed in TQt 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 TQToolTip is, as mentioned above, not +a subclass of TQObject and the instances of TQToolTip not will be +deleted when the widget is deleted. +

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

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

    #include <qapplication.h>
+    #include "mainwindow.h"
+
+    int main( int argc, char** argv )
+    {
+        TQApplication 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 retquires that TQObject +is the first base class. Back...
+ +Note that we have to explicitly scope the orientation +(TQObject or TQWhatsThis) since HeaderWhatsThis uses multiple +inheritance. Back...