Before you start designing a new dialog or a widget that is intended to be used in a dialog or elsewhere, make sure it has not already been made by someone else. The KDE user-interface library (kdeui) is a collection of widgets that extends the functionality of the standard Qt widget set. Generally, widgets have been added to the kdeui because the functionality they provide is not present in the Qt widget library. Another reason is that the widget code would otherwise be duplicated in many applications, and because the widgets support the KDE look and feel for issues such as dialog titles, margins, and keyboard accelerators to the interface.
The most commonly used ready-to-use dialogs are the following:
File selector (KFileDialog)—This dialog is actually not in kdeui but is in its own library.
Font selector (KFontDialog).
Keyboard bindings selector (KKeyDialog).
Color selector (KColorDialog).
Icon selector (KIconLoaderDialog).
Single line input dialog with browsing capability (KLineEditDlg).
Message boxes for warning, error, and information (KMessageBox).
Some of these dialogs have counterparts in the Qt library that can be used for the same task. The reason for this duality is that the KDE versions match better with the accepted KDE style guidelines. Use the KDE version when in doubt because it will improve your program's compliance with the KDE-style-guide recommendations.
If there is a dialog that serves your requirements, then use it instead of making your own! The benefits are several: The users don't have to learn a new dialog and how it works; you save a lot of time; and most of the dialogs are really easy to use, as Listing 8.10 illustrates. The code uses the font selector to pick a font and install it in the widget.
Example 8.10. Using a Dialog from the kdeui Library
1
2 1: void
3 2: Editor::selectFont()
4 3: {
5 4: QFont fnt = font(); // Get current font
6 5: KFontDialog::getFont(fnt); // Select a new, default is current font
7 6: setFont(fnt); // Install new font
8 7: }
9 |
Nevertheless, if you decide that you really need a dialog or a widget that is similar to an existing one, but one with an extended feature set, you should not hesitate to contact the author of the code and ask whether your requirements can be fulfilled by improving the current dialog. If you can provide code that can be merged into the existing library code without breaking compatibility, your chances for acceptance increase.
 | You should also know that a widget or dialog that is used by several applications or that is generally useful might be incorporated into the library. |
The kdeui library provides some very important manager widgets that you must know when you make a dialog. This will greatly simplify your task and make maintaining a lot easier. The KDialogBase class has already been mentioned. Here is a short summary:
KButtonBox—Manages a set of action buttons. You can add as many buttons as you want, and the widget will position and resize them as required. To use this widget, you must specify the text and the accelerators of the buttons. An example showing how the KButtonBox can be used is in Listing 8.11. Note that if you derive your dialog from the KDialogBase class, the buttons will be prepared automatically as other examples have shown.
Example 8.11. Usage of KButtonBox in a Dialog
1
2 1: MyDialog::MyDialog( QWidget *parent, const char *name, bool modal)
3 2: : KDialog( parent, name, modal )
4 3:{
5 4: QVBoxLayout *topLayout = new QVBoxLayout( this, marginHint(),
6 5: spacingHint() );
7 6: CHECK_PTR( topLayout );
8 7:
9 8: // Main body of the dialog is not shown here, just the button
10 9: // box
11 10:
12 11: KButtonBox *bbox = new KButtonBox( this, KButtonBox::HORIZONTAL,
13 12: 0, spacingHint() );
14 13: CHECK_PTR( bbox );
15 14: topLayout->addWidget( bbox );
16 15:
17 16: buttonBox->addStretch();
18 17: QPushButton *ok = bbox->addButton( i18n("&Ok"), false );
19 18: QPushButton *cancel = bbox->addButton( i18n("&Cancel"), false );
20 19: buttonBox->layout();
21 20: ok->setDefault( true );
22 21: connect( ok , SIGNAL(clicked()), this, SLOT(accept()) );
23 22: connect( cancel , SIGNAL(clicked()), this, SLOT(reject()) );
24 23:}
25 |
KJanusWidget—This is a widget that provides a number of faces (thereby the name) or layouts. Depending on how it is initialized, it can display widgets in a tabbed fashion, in a paged tree list in a paged icon list, or on a single page. Its main use is as an internal widget in KDialogBase, but it can be used as a standalone widget as well. Figure 8.4 shows a KJanusWidget widget in Tabbed mode.
KDialog (derived from QDialog)—This dialog widget provides resources that give you easy access to global properties concerning style settings. At the moment, you can get access to the spacing and margin sizes you should use between widgets in your dialog and a redefined setCaption() so that your dialog uses the proper dialog title style. If your code uses these methods, any change in the future (for example, a new margin setting as a part of a theme selection) will automatically be used in your dialog as well. See Listing 8.11 for a typical example on how to use a KDialog dialog widget.
KDialogBase (derived from KDialog)—This is a dialog frame widget. It is designed to take care of a lot of work that you would otherwise spend much time getting right for each dialog you create. It provides access to the resources of KDialog; it takes care of the action buttons; it draws a separator above the buttons (if you tell it to do so); it resizes itself automatically to fit the contents when shown; and it uses the KJanusWidget to support various dialog types. The philosophy is that you only need to worry about the contents of the dialog that performs your specific task.