Next Previous Table of Contents
A very important part of the development process is to provide help functionality to the user wherever possible. Most developers tend to delay this, but you should remember that a normal user isn't necessarily a Unix-expert. He may come from the the dark side of computer software usage offering all sweets that a user may need to work himself into using an application even without ever touching the manuals. Therefore, the KDE and Qt library provide all means usually considered making an application professional in the eyes of the normal user by help functions that are ready to use. Within the application, those are:
Additionally, the application should provide means to access a HTML-based online manual directly using the standard help key F1.
As KDevelop also offers all types of help as well as the KDE framework generated by the application wizard already contains support for this, this chapter will help you find out where and how to add your help functionality.
During the development of your application you should try to be consistent whatever you're doing; therefore you should do the necessary steps directly while extending the code. This will prevent you from diving into the code again and figuring out what your application does or what you intended by certain parts of the code.
A very easy mean of providing help are tool-tips. Those are small help messages popping up while the user moves the mouse over a widget
that provides a tool-tip and disappears when the mouse moves away. The most popular usage of tool-tips is made in toolbars where your
tool-tips should be kept as small as possible because toolbars can be configured to display their contents in various ways: either
displaying the button, button with text on the right, button with text below, text only. This possibility should be made configurable
by the user, but isn't a must-be. The text is shown as a tool-tip anyway and a toolbar usually consists of buttons and other widgets
like lineedits and combo boxes. For a complete reference, see the KToolBar class reference located in the KDE-UI library.
As an example, we have a look at the the "New File" button in a generic application:
toolBar()->insertButton(Icon("filenew.xpm"), ID_FILE_NEW, true, i18n("New File") );
i18n("New File") provides a tool-tip message. It is enclosed by the i18n() macro provided by kapp.h to
translate the tool-tip towards the currently selected language.
Tool-tips can also be added to any custom widget by using the classes QToolTip and QToolTipGroup provided by Qt.
An example of that would be:
QToolTip::add( yourwidget, i18n("your Tip") );
QToolTip.
Quick-Help windows are another good example of providing help. The user can access the quick-help over a widget that it is connected to by pressing the right mousebutton and selecting "Quick-Help" in the context menu. Therefore, Quick-Help can be placed somewhere in between a detailed handbook reference help and tool-tips- the documentation would be too extensive and a tool-tip would not provide enough information. To see how Quick-Help works, open any dialog within KDevelop and press the right mouse button over a dialog item. Then select the Quick-Help menuentry and you're offered the help message. Additionally, those messages can be formatted by color, font and even can be used for containing URL's to refer a certain webpage (and therefore can refer to the documentation handbook as well).
To make use of Quick-Help, add the include file kquickhelp.h to your sourcefile containing quick-help. As the
KQuickHelp class is part of the KDE-UI library, it should already be used by your application; if not, set the linker flags
of your project to use kdeui.
An example would be:
KQuickHelp::add( yourwidget, i18n("your Tip") );
which is almost the same as with QToolTip. When constructing a dialog with the KDevelop dialogeditor, add your tool-tips and Quickhelp in the implementation file- NOT within the data sourcefile as this is rebuild by the dialogeditor every time you edit the widget.
The KQuickHelp class provides also formatting text by using tags. It allows hyperlinks including Internet protocols, colors,
font types and sizes. See the
KDE Library Reference Guide and the class
documentation for KQuickTip for more information.
As the frame applications provided by KDevelop contain a statusbar as well, it also offers a set of statusbar messages already for all
menu and toolbar items. A statusbar help message is a short message that extends the meaning of a tool-tip or can be seen as a
replacement for a tool-tip over menubar items and is (as the name suggests) displayed in the statusbar when the user enters a menu and
highlights the menu entry; therefore all menu items connect their signal highlighted(int) to the method statusCallback(int)
which selects the according message in a switch statement. Whenever you add a menuitem to already existing menus or a toolbar
item, add an according entry in this method with a short description of the action the user will cause when activating the button or
menuentry.
Example:
case ID_FILE_NEW:
slotStatusHelpMsg(i18n("Creates a new document"));
break;
This will display a statusbar message by calling the method slotStatusHelpMsg() with the according translated help string whenever
the user highlights a menu or toolbar item with the id ID_FILE_NEW that is connected to the statusCallback() method.
Toolbars connect to this method by their signal pressed(int), which allows the user to press the toolbar button and move away the
mouse when he doesn't want to invoke the command. KToolBar also offers the signal highlighted(int, bool) which can be used to
display the message whenever the user highlights the button instead of the preset signal used.
The "What's This...?" button provides help windows like Quickhelp , but with the intention that the user wants to get help about a certain widget within the working view or a toolbar item. It is placed in the toolbar and gets activated once the user hits the button. The cursor changes to an arrow cursor with a question mark like the button itself looks like. The the user can press on a visible widget item and gets a help window. As an exercise, you could try this behavior with the What's this...? button within KDevelop. To add the What's This...? button, do the following:
qwhatsthis.h into your sourcecodeQWhatsThis whats_this/ or with another member name to your KTMainWindow derived class
declaration resource.h file,e.g. #define ID_HELP_WHATS_THIS
10100initToolBar()), add at the location you want to have the button
displayed:
whats_this = new QWhatsThis;
QToolButton *btnwhat = whats_this->whatsThisButton(toolBar());
QToolTip::add(btnwhat, i18n("What's this...?"));
toolBar()->insertWidget(ID_HELP_WHATS_THIS, btnwhat->sizeHint().width(), btnwhat);
btnwhat->setFocusPolicy(QWidget::NoFocus);
whats_this->add(class_tree, i18n("Class Viewer\n\n"
"The class viewer shows all classes, methods and variables "
"of the current project files and allows switching to declarations "
"and implementations. The right button popup-menu allows more specialized "
"functionality."));
Next Previous Table of Contents