| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
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
{
TQ_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. (1) 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/ntqheader.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. (2)
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/tqcombotableitem.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/tqchecktableitem.html>TQCheckTableItem</a>."
"<br>It provide <a href=%1/html/tqcheckbox.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
{
TQ_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, TQ_SLOT(close()) );
int helpId = helpMenu->insertItem( "Open Assistant", this, TQ_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, TQ_SIGNAL(showTip(const TQString&)), statusBar(),
TQ_SLOT(message(const TQString&)) );
connect( tipGroup, TQ_SIGNAL(removeTip()), statusBar(), TQ_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, TQ_SIGNAL(clicked()), this, TQ_SLOT(assistantSlot()) );
connect( horizontalWhatsThis, TQ_SIGNAL(linkClicked(const TQString&)), assistant,
TQ_SLOT(showPage(const TQString&)) );
connect( verticalWhatsThis, TQ_SIGNAL(linkClicked(const TQString&)), assistant,
TQ_SLOT(showPage(const TQString&)) );
connect( cellWhatsThis, TQ_SIGNAL(linkClicked(const TQString&)), assistant,
TQ_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/ntqassistantclient.html").arg(docsPath) );
}
The assistantSlot() uses applicationDirPath() to find the location of the documentation files and shows the specified page in TQt Assistant.
#include <ntqapplication.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 (TQTDIR/examples/helpsystem) run qmake to generate the makefile, and use the make tool to build the library.
See also Examples.
| Copyright © 2007 Trolltech | Trademarks | TQt 3.3.8
|