10 files changed, 642 insertions, 0 deletions
diff --git a/examples/helpsystem/appicon.png b/examples/helpsystem/appicon.png
new file mode 100644
index 000000000..a50dc9ccb
--- /dev/null
+++ b/examples/helpsystem/appicon.png
diff --git a/examples/helpsystem/helpsystem.doc b/examples/helpsystem/helpsystem.doc
new file mode 100644
index 000000000..d44808800
--- /dev/null
+++ b/examples/helpsystem/helpsystem.doc
@@ -0,0 +1,221 @@
+/*!   
+  \page helpsystem-example.html
+
+  \ingroup examples
+  \title 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.
+  \quotefile helpsystem/tooltip.h
+  \skipto : public QToolTip
+  \printuntil };
+
+  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.
+
+  \printuntil };
+
+  The TableToolTip class keeps a reference to the QTable
+  as a member for easier access of the QTable object later on.
+
+  \quotefile helpsystem/tooltip.cpp
+  \skipto HeaderToolTip::HeaderToolTip
+  \printuntil }
+
+  The HeaderToolTip constructor propagates the parameters
+  to the QToolTip constructor.
+  \printuntil }
+
+  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.
+
+  \printuntil }
+
+  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.
+  \printto moveTopLeft
+
+  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.  
+  \printuntil }
+  \quotefile helpsystem/whatsthis.h
+  \skipto class WhatsThis
+
+  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. 
+  \printuntil };
+  \quotefile helpsystem/whatsthis.cpp
+  \skipto WhatsThis::WhatsThis
+
+
+  The WhatsThis class is a subclass of both QObject and 
+  QWhatsThis and serves as a base class for the HeaderWhatsThis
+  and TableWhatsThis classes. \footnote Note that moc retquires that QObject
+  is the first base class. \endfootnote 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.
+  \printuntil }
+  
+  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.
+  \skipto bool WhatsThis::clicked
+  \printuntil }
+  \quotefile helpsystem/whatsthis.h
+  \skipto class HeaderWhatsThis
+
+  The implementation of clicked() emits the linkClicked() signal 
+  if a hyperlink has been clicked.
+  \printuntil };
+
+  \printuntil };
+
+  \quotefile helpsystem/whatsthis.cpp
+  \skipto HeaderWhatsThis::HeaderWhatsThis
+  
+  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.
+  \printuntil }
+
+  The HeaderWhatsThis constructor propagates the parameter to the 
+  WhatsThis constructor.
+  \printto TableWhatsThis::TableWhatsThis
+
+  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.
+  \footnote
+  Note that we have to explicitly scope the orientation
+  (QObject or QWhatsThis) since HeaderWhatsThis uses multiple 
+  inheritance. \endfootnote 
+  \printuntil }
+
+  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.
+  \printuntil }
+  \printuntil }
+  \printuntil }
+  \printuntil }
+
+  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. 
+
+  \quotefile helpsystem/mainwindow.h
+  \skipto class MainWindow
+  \printuntil };
+
+  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.
+
+  \quotefile helpsystem/mainwindow.cpp
+  \skipto MainWindow::MainWindow
+  \printuntil assistant
+  
+  The MainWindow constructor creates an instance of 
+  QAssistantClient using QString::null as the first argument
+  so that the system path is used.
+  \printto QWhatsThis::whatsThisButton
+  
+  A QTable is used as the central widget and the table, the menus 
+  and the toolbar are populated.
+  \printto // create
+  
+  The static function whatsThisButton() creates a QToolButton
+  which will enter "What's this?" mode when clicked.
+  \printto // set up
+ 
+  A QToolTipGroup is created and will show and remove tooltips
+  in the statusbar as the tooltips are displayed on the widgets.
+  \printto // set up whats this
+   
+  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.
+  \printto // connections
+  
+  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.
+  \printto MainWindow::~MainWindow
+   
+  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.
+  \printuntil }
+
+  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.
+  \printuntil }  
+
+  The assistantSlot() uses applicationDirPath() to find the 
+  location of the documentation files and shows the specified page
+  in Qt Assistant.
+  \quotefile helpsystem/main.cpp
+  \skipto #include
+  \printuntil }
+
+  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. 
+*/
diff --git a/examples/helpsystem/helpsystem.pro b/examples/helpsystem/helpsystem.pro
new file mode 100644
index 000000000..5f528049a
--- /dev/null
+++ b/examples/helpsystem/helpsystem.pro
@@ -0,0 +1,8 @@
+TEMPLATE = app
+
+LIBS    += -lqassistantclient
+
+REQUIRES = full-config table
+
+SOURCES += main.cpp tooltip.cpp mainwindow.cpp whatsthis.cpp
+HEADERS += tooltip.h mainwindow.h whatsthis.h
diff --git a/examples/helpsystem/main.cpp b/examples/helpsystem/main.cpp
new file mode 100644
index 000000000..43c2b73c5
--- /dev/null
+++ b/examples/helpsystem/main.cpp
@@ -0,0 +1,22 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#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();
+}
+
diff --git a/examples/helpsystem/mainwindow.cpp b/examples/helpsystem/mainwindow.cpp
new file mode 100644
index 000000000..e7e4ef9a9
--- /dev/null
+++ b/examples/helpsystem/mainwindow.cpp
@@ -0,0 +1,118 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#include <qapplication.h>
+#include <qassistantclient.h>
+#include <qfiledialog.h>
+#include <qmenubar.h>
+#include <qpopupmenu.h>
+#include <qstatusbar.h>
+#include <qtable.h>
+#include <qtoolbar.h>
+#include <qtoolbutton.h>
+#include <qtooltip.h>
+
+#include "mainwindow.h"
+#include "tooltip.h"
+#include "whatsthis.h"
+
+MainWindow::MainWindow()
+{
+    statusBar();
+    assistant = new TQAssistantClient( TQDir("../../bin").absPath(), this );
+
+    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") );
+    TQWhatsThis::whatsThisButton( toolbar );
+
+    //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()) );
+
+    // 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 );
+
+    // 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" );
+
+    // 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&)) );
+}
+
+MainWindow::~MainWindow()
+{
+    delete horizontalTip;
+    delete verticalTip;
+    delete cellTip;
+}
+
+void MainWindow::assistantSlot()
+{
+    TQString docsPath = TQDir("../../doc").absPath();
+    assistant->showPage( TQString("%1/html/qassistantclient.html").arg(docsPath) );
+}
diff --git a/examples/helpsystem/mainwindow.h b/examples/helpsystem/mainwindow.h
new file mode 100644
index 000000000..32c7239c8
--- /dev/null
+++ b/examples/helpsystem/mainwindow.h
@@ -0,0 +1,31 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#include <qmainwindow.h>
+
+class HeaderToolTip;
+class TableToolTip;
+class TQAssistantClient;
+
+class MainWindow : public TQMainWindow
+{
+    Q_OBJECT
+public:
+    MainWindow();
+    ~MainWindow();
+
+public slots:
+    void assistantSlot();
+
+private:
+    HeaderToolTip *horizontalTip;
+    HeaderToolTip *verticalTip;    
+    TableToolTip *cellTip;
+    TQAssistantClient *assistant;
+};
diff --git a/examples/helpsystem/tooltip.cpp b/examples/helpsystem/tooltip.cpp
new file mode 100644
index 000000000..407afa84a
--- /dev/null
+++ b/examples/helpsystem/tooltip.cpp
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#include <qtooltip.h>
+#include <qtable.h>
+
+#include "tooltip.h"
+
+HeaderToolTip::HeaderToolTip( TQHeader *header, TQToolTipGroup *group ) 
+: TQToolTip( header, group )
+{
+}
+
+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" );
+}
+
+TableToolTip::TableToolTip( TQTable *tipTable, TQToolTipGroup *group ) 
+: TQToolTip( tipTable->viewport(), group ), table( tipTable )
+{
+}
+
+
+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 );
+    cr.moveTopLeft( table->contentsToViewport( cr.topLeft() ) );
+    tip( cr, tipString, "This is a cell in a table" );
+}
diff --git a/examples/helpsystem/tooltip.h b/examples/helpsystem/tooltip.h
new file mode 100644
index 000000000..69c3bb74f
--- /dev/null
+++ b/examples/helpsystem/tooltip.h
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#ifndef TOOLTIP_H
+#define TOOLTIP_H
+
+#include <qtooltip.h>
+
+
+class TQTable;
+class TQHeader;
+
+class HeaderToolTip : public TQToolTip
+{
+public:
+    HeaderToolTip( TQHeader *header, TQToolTipGroup *group = 0 );
+    
+protected:
+    void maybeTip ( const TQPoint &p );
+};
+
+class TableToolTip : public TQToolTip
+{
+public:
+    TableToolTip( TQTable* table, TQToolTipGroup *group = 0  );
+    
+protected:
+    void maybeTip( const TQPoint &p );
+    
+private:
+    TQTable *table;
+};
+
+
+#endif
diff --git a/examples/helpsystem/whatsthis.cpp b/examples/helpsystem/whatsthis.cpp
new file mode 100644
index 000000000..b8511cbe9
--- /dev/null
+++ b/examples/helpsystem/whatsthis.cpp
@@ -0,0 +1,99 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#include <qapplication.h>
+#include <qdir.h>
+#include <qheader.h>
+#include <qtable.h>
+
+#include "whatsthis.h"
+
+WhatsThis::WhatsThis( TQWidget *w, TQWidget *watch )
+: TQWhatsThis( watch ? watch : w ), widget( w )
+{
+}
+
+TQWidget *WhatsThis::parentWidget() const
+{
+    return widget;
+}
+
+bool WhatsThis::clicked( const TQString &link )
+{
+    if ( !link.isEmpty() )
+	emit linkClicked( link );
+
+    return TRUE;
+}
+
+HeaderWhatsThis::HeaderWhatsThis( TQHeader *h ) 
+: WhatsThis( h )
+{
+}
+
+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);
+}
+
+TableWhatsThis::TableWhatsThis( TQTable *t ) 
+: WhatsThis( t, t->viewport() )
+{
+}
+
+
+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.";
+}
diff --git a/examples/helpsystem/whatsthis.h b/examples/helpsystem/whatsthis.h
new file mode 100644
index 000000000..d15aad421
--- /dev/null
+++ b/examples/helpsystem/whatsthis.h
@@ -0,0 +1,50 @@
+/****************************************************************************
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of an example program for TQt.  This example
+** program may be used, distributed and modified without limitation.
+**
+*****************************************************************************/
+
+#ifndef WHATSTHIS_H
+#define WHATSTHIS_H
+
+#include <qwhatsthis.h> 
+
+class TQHeader;
+class TQTable;
+
+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;
+};
+
+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 );
+};
+
+#endif