The K Desktop Environment

Chapter 8. Help Functions

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.

8.1. Tool-Tips

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 toolbar s where your tool-tips should be kept as small as possible because toolbar s 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") );
There, the part 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") );
For more information, see the Qt -Online Reference, class QToolTip.