The KDevelop Programming Handbook: Help Functions

Next Previous Table of Contents

### 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:

- Tool-Tips
- Quick-Help
- Statusbar help
- What's this...? buttons

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 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") );

> `

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`.

### 8.2 Adding Quick-help

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.

### 8.3 Extending the Statusbar Help

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.

### 8.4 The "What's This...?" Button

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:

1. include `qwhatsthis.h` into your sourcecode
2. add a private member `QWhatsThis` whats_this/ or with another member name to your `KTMainWindow` derived class declaration
3. define a resource id for your what's this button into the `resource.h` file,e.g. `#define ID_HELP_WHATS_THIS 10100`
4. in your method to create the toolbar (usually `initToolBar()`), 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);

   > `

5. finally, add the messages you want to have on a click over a certain widget like this:

   > `

   >     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