The K Desktop Environment

Next Previous Table of Contents

5. Configuring Menubars and Toolbars

Menubars and toolbars are one of the most important parts of an application to provide methods to work with a document structure. As a general rule, you should make all functions available by the menubar. Those methods that should not be available at a current stage of the application process should be disabled.

Further, an application can only contain one menubar, but several toolbars. Toolbars on the other hand should contain only the most frequently used commands by pixmap icons or provide quick access methods like combos to select values.

5.1 How does it work ?

Each entry, may it be a menuentry or a toolbar item, has a resource ID which is an integer value. As these values can't be used twice, those are set by macros, where the numeric values are replaced by a descriptive ID name that can be used in your sources then.

All resource ID's are collected in the file resource.h, where you can keep an overview over the used values. Anyway, the compiler will inform you if you've used a value twice for constructing entries. Also, the resource file should contain all menu accelerator s by IDK macro replacements. An example: 

(resource.h)

#define ID_VIEW_TOOLBAR             12010


(kscribble.cpp)

// menu entry Toolbar in the "view" menubar menu
view_menu->insertItem(i18n("&Toolbar"), ID_VIEW_TOOLBAR);

This inserts the entry Toolbar to the View popup menu of the menubar in the kscribble application. The resource ID's name is held to contain the menu name and the action's name visible. The ampersand is set in front of the letter that functions as a keyboard accelerator and the entry itself is embraced by the i18n() internationalization macro.

On activating the menu item, the commandCallback() switch is called with the ID number. There, you have to add an according comparator value with the method you want to execute on activating the menuentry: 

    case ID_VIEW_TOOLBAR:
        slotViewToolBar();
        break;

Comment

Note: you don't have to use the ID system. If no ID is given, the menu gets numbered automatically. The KDevelop framework uses this as it allows accessing menu and toolbar ID's to create switch statements that select the slot to call on activated() for menus, clicked() for toolbar buttons. The connection can also be made directly using the provided methods of the classes providing menus and toolbars.

5.2 Adding a new menu

A new menubar is added to an application by the following:

  1. add a pointer to the new menu in the App-class header
  2. call the constructor of QPopupMenu to the pointer in initMenuBar() at the location where your menubar should appear later.
  3. insert the according menu-items into the popup menu and set their resource ID's in the resource file
  4. add connects for commandCallback() and statusCallback() to the menu at the end of initMenuBar()
  5. add the methods you want to call by the menu-entries in the header and implementation file.
  6. add the switch statements for the entries to the commandCallback() and statusCallback() methods

5.3 Integrating Toolbar buttons

Toolbar buttons can be added like menu-entries with the difference that the used method is insertButton() and takes a button pixmap and tool-tip text instead of a menu text.

The icons you want to use can be loaded by KIconLoader, where KApplication offers the macros ICON() and Icon() to access the icon loader and load the icon. These macros take the filename of the pixmap as their parameter to load the icon from the KDE file system in a certain order (see KIconLoader for the search order).

The KDE libraries also offer a set of toolbar buttons that can be used for standard actions. In cases where they don't meet your needs, you will have to paint your own pixmaps. KDevelop supports this by selecting "New" from the "File" menu, then select Pixmap as the file type. Usually you will place your toolbar pixmaps in a project subdirectory "toolbar" and install them into your application specific toolbar directory.

5.4 Configuring Statusbars

The KDevelop projects already make use of the statusbar by providing statusbar messages for menu-entries and toolbar buttons. When adding a menuentry, also add your status message in the method statusCallback().

statusCallback() uses the method slotStatusHelpMsg() to display a statusbar message for two seconds. When executing a command, you should use the method slotStatusMsg() at the beginning with the string describing what your application does; before a return or method end, you should reset the statusbar message with a "Ready." string calling the same method.

5.5 Keyboard Accelerator Configuration

A very professional thing you should always add to your application are keyboard accelerator s. Those are mainly used by experienced users that want to work fast with their applications and are willing to learn shortcut s. For this, the KDE libraries provide the class KAccel, which provides the keyboard accelerator keys and access to global configured standard keyboard accelerator s.

By default, frame applications generated by KDevelop only use standard keyboard accelerator s such as F1 for accessing online-help, Ctrl+N for New File etc. You should look for the keyboard accelerator s already set in KAccel first before adding a new accelerator .

If your application contains a lot of accelerator s, you should make them configurable by an Options-menu; either it could be combined with other application configuration in a QWidget or stand alone. The KDE library already provides a KKeyChooser for use in tab dialogs, whereas KKeyDialog provides a ready-to use key-configuration dialog.

See the following classes for more information:

KAccel(kdecore), KKeyChooser, KKeyDialog (kdeui)

Next Previous Table of Contents