Listings 5.12 and 5.13 show how to provide the four types of help just discussed: ToolTips, statusbar messages, What's This? help, and a Help file. This program, KHelpers, creates an empty client area and provides the user with helpful information about it.
Example 5.12. khelpers.h: Contains a Class Declaration for KHelpers, a Subclass of KTMainWindow 1
2 1: #ifndef __KHELPERS_H__
3 2: #define __KHELPERS_H__
4 3:
5 4: #include <ktmainwindow.h>
6 5:
7 6: class QPopupMenu;
8 7:
9 8: /**
10 9: * KHelpers
11 10: * Demonstrates functions of KMenuBar and QPopupMenu.
12 11: **/
13 12: class KHelpers : public KTMainWindow
14 13: {
15 14: Q_OBJECT
16 15: public:
17 16: /**
18 17: * Construct the menubar and fill it with interesting things.
19 18: **/
20 19: KHelpers (const char *name=0);
21 20:
22 21: public slots:
23 22: /**
24 23: * Provide help on menu entries in the statusbar.
25 24: **/
26 25: void slotMenuEntryHelp (int);
27 26:
28 27: /**
29 28: * View a specific HTML Help file.
30 29: **/
31 30: void slotSpecialHelp();
32 31:
33 32: protected:
34 33: int idfilenew, idfileopen, idfilesave, idfilequit;
35 34: };
36 35:
37 36: #endif
38 |
KHelpers is derived from KTMainWindow, which manages the menu and client area. The client area is just an empty QLabel, created on line 52 in Listing 5.13.
Example 5.13. khelpers.cpp: Contains a Class Definition for KHelpers 1
2 1: #include <stdio.h>
3 2:
4 3: #include <qpopupmenu.h>
5 4: #include <qToolTip.h>
6 5: #include <qwhatsthis.h>
7 6:
8 7: #include <kapp.h>
9 8: #include <kstddirs.h>
10 9: #include <kmenubar.h>
11 10:
12 11: #include "khelpers.moc"
13 12:
14 13: const int HelpMessageTime = 2000;
15 14:
16 15: KHelpers::KHelpers (const char *name) : KTMainWindow (name)
17 16: {
18 17: QPopupMenu *file = new QPopupMenu;
19 18:
20 19: idfilenew =
21 20: file->insertItem ("&New");
22 21: idfileopen =
23 22: file->insertItem ("&Open…");
24 23: idfilesave =
25 24: file->insertItem ("&Save");
26 25: idfilequit =
27 26: file->insertItem ( "&Quit", kapp, SLOT (closeAllWindows()) );
28 27:
29 28: connect ( file, SIGNAL (highlighted (int)),
30 29: this, SLOT (slotMenuEntryHelp (int)) );
31 30:
32 31: menuBar()->insertItem ("&File", file);
33 32:
34 33:
35 34: QPopupMenu *help =
36 35: helpMenu ("KHelpers\n"
37 36: "Copyright (C) 2000 By Joe Developer\n\n"
38 37: "KHelpers demonstrates a few of the ways "
39 38: "that your application can provide help to a user.");
40 39:
41 40: help->insertSeparator();
42 41: help->insertItem ( "Help on a special topic", this,
43 42: SLOT (slotSpecialHelp()) );
44 43:
45 44: menuBar()->insertItem ("&Help, help");
46 45:
47 46: //Create the statusbar.
48 47: statusBar();
49 48:
50 49: QLabel *clientarea = new QLabel (this);
51 50: clientarea->setBackgroundColor (Qt::white);
52 51:
53 52: QToolTip::add (clientarea, "Functionless client area");
54 53: QWhatsThis::add (clientarea, "This client area doesn't do anything.");
55 54:
56 55:
57 56: setView (clientarea);
58 57:
59 58: clientarea->setFocus();
60 59:
61 60: }
62 61:
63 62:
64 63: void
65 64: KHelpers::slotMenuEntryHelp (int id)
66 65: {
67 66:
68 67: if (id==idfilenew)
69 68: statusBar()->message("Create a new document.", HelpMessageTime);
70 69: else if (id==idfileopen)
71 70: statusBar()->message("Open a file.", HelpMessageTime);
72 71: else if (id==idfilesave)
73 72: statusBar()->message("Save the current document.", HelpMessageTime);
74 73: else if (id==idfilequit)
75 74: statusBar()->message("Quit the application.", HelpMessageTime);
76 75:
77 76: }
78 77:
79 78: void
80 79: KHelpers::slotSpecialHelp()
81 80: {
82 81: QString helpfilename (kapp->name());
83 82: helpfilename += "/specialhelp.html";
84 83:
85 84: kapp->invokeHTMLHelp (helpfilename, "");
86 85: }
87 |
The main() function in Listing 5.14 can be used to compile KHelper into an executable.
Example 5.14. main.cpp: Contains a main() Function That Creates and Executes KHelpers, an Application Based on KHelpers 1
2 1: #include <kapp.h>
3 2. #include "khelpers.h"
4 3:
5 4: int
6 5: main (int argc, char *argv[])
7 6: {
8 7: KApplication kapplication (argc, argv, "khelpers");
9 8: KHelpers *khelpers = new KHelpers;
10 9:
11 10: khelpers->show();
12 11: return kapplication.exec();
13 12: }
14 |
This program demonstrate four types of user help: ToolTips, statusbar messages, What's This?, and Help file access. ToolTips are short messages that give a text name or a description of a widget. They appear after the user has held the mouse pointer over a widget for a second or so. The text is usually only a few words. The message Open a file, for example, might appear over the toolbar button that performs that task. The messages appear in frameless windows. They disappear after the user moves the mouse pointer, and they won't reappear again until the pointer has left the widget and then returned and stayed motionless. See Figure 5.9 for a screen shot of the KHelpers window with the ToolTip displayed. In KHelpers, you add a ToolTip to the client area widget using the static method QToolTip::add() in line 52. What's This? help messages are longer than ToolTips—up to three paragraphs. They explain in more detail the function of a widget. They are often used to explain elements of dialog boxes (see Chapter 8, "Using Dialog Boxes", for a discussion of dialog boxes). You attach a What's This? help message to the client area in much the same way as you attach the ToolTip. Use the static function QWhatsThis::add() (line 53). To view the message, the user selects What's This? from the Help menu and then clicks the widget of interest. If a widget can accept the keyboard focus, Shift+F1 displays the What's This? message for the widget with focus. See Figure 5.10 for a screen shot of KHelpers displaying What's This? help on the client area. When short messages are not enough and users want to learn how to use your application, they can read the documentation. Documentation is provided in HTML format and is accessible through the standard Help menu entry, Contents. A standard format is used for the HTML documentation, which is described in Chapter 15, "Creating Documentation". A standard directory also exists for the documentation. These and other standard directories are discussed in Chapter 7. To create the standard Help menu, use the method KTMainWindow::helpMenu(), as shown on lines 34–38. You should always use the standard Help menu. You will see that entries have been added to it after adding a separator. This is fine as long as the standard entries are there first. The returned menu has five menu entries: Contents Starts KHelpCenter, which displays the HTML documentation for KHelpers. What's This Enter "What's This?" mode. About khelpers Displays the text passed as the first parameter to helpMenu(). In general, khelpers will be replaced with the application's name. About KDE Displays a standard dialog box describing KDE. Report bug Report a bug to http://bugs.kde.org.
To this menu, you append the entry to get "special help." Sometimes elements of the UI need special explanation. To demonstrate how to view help on specific topics, add this "special help" entry and load the Help file in slotSpecialHelp(). The Help file is loaded for viewing on line 84. Help files for KHelpers are stored in the subdirectory khelpers in the standard Help file directory, so you construct the path khelpers/ specialhelp.html. Of course, you also need to create the HTML documentation and place it there if you want to view it. Creating documentation is covered in Chapter 15. (Trying to view the documentation will give an error because the file will not be found.) | |
