Chapter 8. Using Dialog Boxes

by Espen Sand

In This Chapter

A dialog is a very important part of an application. If the dialogs are not well-designed or suited for their task, the usefulness of the application is often greatly reduced. This chapter describes how to successfully create dialogs that are easy to use, that have a distinct KDE look and feel, and that are simple to develop and later extend and maintain by the developer. The KDE interface library (kdeui) contains several building blocks and widgets that, combined with the regular widgets and layout managers of the Qt library, provide you with what you need to get an optimal result. I emphasize the use of a framework widget named KDialogBase. The use of the KDialogBase class greatly simplifies dialog writing because it takes care of much of the tedious work that has to be repeated for every dialog you make.

Although several interface builders are available that can create dialogs for you (see Chapter 18, "The KDevelop IDE: The Integrated Development Enviroment for KDE"), the KDE interface library widgets are designed to simplify a hand-coded design process. In addition, they automatically give your dialogs the look and feel recommended by the KDE style guide, which is available on the Web page: http://developer.kde.org/documentation/standards/kde/style/basics. Several examples illustrate how to use these basic widgets.

8.1. Getting Started with the Dialog Widgets

Let's start with an example. Figure 8.1 shows a very simple dialog that is used in the standard KDE hex editor—KHexEdit. The code in Listing 8.1 shows how the dialog class is derived from KDialogBase. Most of the initialization of KDialogBase class takes place in the constructor of that class. The class definition is normally placed in a separate header file, but for simplicity it is shown here together with the regular code.

Figure 8.1. This dialog is used to display the number of bytes currently selected in KHexEdit's editor window. The value is printed in decimal and hexadecimal.

Example 8.1. Simplified Listing of the SelectDialog Dialog Class

   1 
   2 1: class SelectDialog : public KDialogBase
   3 2: {
   4 3:   Q_OBJECT
   5 4:
   6 5:   public:
   7 6:     SelectDialog( QWidget *parent=0, const char *name=0,
   8 7:       bool modal=false );
   9 8:     ~SelectDialog( void );
  10 9:
  11 10:   private:
  12 11:     void setSelectionSize( uint selectionSize );
  13 12:
  14 13:   private:
  15 14:     QLineEdit *mSelectSizeEdit;
  16 15:     uint mSelectionSize;
  17 16: };
  18 17:
  19 18: SelectDialog::SelectDialog( QWidget *parent, const char *name,
  20 19:                             bool modal )
  21 20:   :KDialogBase( parent, name, modal, i18n("Select Indicator"),
  22 21:                 Cancel, Cancel )
  23 22: {
  24 23:   QWidget *page = new QWidget(this);
  25 24:   CHECK_PTR( page );
  26 25:   setMainWidget( page );
  27 26:
  28 27:   QVBoxLayout *topLayout = new QVBoxLayout( page, 0, spacingHint() );
  29 28:   CHECK_PTR( page );
  30 29:
  31 30:   QLabel *label = new QLabel( i18n("Selection size [bytes]:"), page );
  32 31:   CHECK_PTR( label );
  33 32:   topLayout->addWidget( label );
  34 33:
  35 34:   mSelectSizeEdit = new QLineEdit( page );
  36 35:   CHECK_PTR( mSelectSizeEdit );
  37 36:   mSelectSizeEdit->setMinimumWidth( fontMetrics().maxWidth()*17 );
  38 37:   mSelectSizeEdit->setFocusPolicy( QWidget::NoFocus );
  39 38:   topLayout->addWidget( mSelectSizeEdit );
  40 39:
  41 40:   topLayout->addStretch(10);
  42 41:
  43 42:   setSelectionSize(0);
  44 43: }
  45 44:
  46 45: SelectDialog::~SelectDialog()
  47 46: {
  48 47: }
  49 48:
  50 49: void
  51 50: SelectDialog::setSelectionSize( uint selectionSize )
  52 51: {
  53 52:   mSelectionSize = selectionSize;
  54 53:   QString msg;
  55 54:
  56 55:   msg.sprintf( "%08u, %04x:%04x", mSelectionSize, mSelectionSize>>16,
  57 56:                mSelectionSize&0x0000FFFF );
  58 57:   mSelectSizeEdit->setText( msg );
  59 58: }
  60 59:
  61 60: // The dialog used as the main application window
  62 61:
  63 62: #include <kcmdlineargs.h>
  64 63: int main( int argc, char **argv )
  65 64: {
  66 65:   KCmdLineArgs::init(argc, argv, "khexedit", 0, 0);
  67 66:   KApplication app;
  68 67:   SelectDialog *dialog = new SelectDialog();
  69 68:   dialog->show();
  70 69:   int result = app.exec();
  71 70:   return( result );
  72 71: }
  73

The KDialogBase widget is described in more detail in the section "Building Blocks (Manager Widgets)" later in this chapter. Notice the signature of the constructor on line 18. These are the arguments you should at least provide when making a dialog. Note as well that in the class definition (line 6), the argument has been assigned default values. The values shown in the code are the most commonly used in KDE and Qt code and is in many respects assumed to be the standard implementation. The parent widget is the widget around which the dialog is centered. Normally, you use the top-level widget or your application as the parent of a dialog. The dialog will then be positioned in the center of your main application window. If the parent is 0 (null), the dialog is centered with respect to the desktop. The name is the name of the dialog widget. It should not be used for the dialog title string (often called the caption) because it is not of type QString (the Unicode string class). The name is used to identify the widget during development and is very handy if you need to dump a widget hierarchy. You can safely assign 0 to the name if you don't need it. The last argument, modal, determines the modality of the dialog. See the section "Dialog Modality—Modal or Modeless Dialogs" later in this chapter for an extended description and a description of the implications of modal and modeless dialog behavior.