diff options
Diffstat (limited to 'examples/helpsystem/helpsystem.doc')
| -rw-r--r-- | examples/helpsystem/helpsystem.doc | 221 |
1 files changed, 221 insertions, 0 deletions
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. +*/ |