qt3/examples/helpsystem/helpsystem.doc

/*!   
  \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 requires 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. 
*/