5.3. Standard Dialog Boxes

KDE offers several dialog boxes for common tasks, as described in Table 5.2.

Other dialog boxes are available, but they are more complex or more specialized and thus are discussed elsewhere (see Chapters 6, 8, and 10).

Using these dialog boxes makes it easier to perform the common tasks of requesting file names, fonts, and so on from the user. More importantly, it makes providing answers to these questions for your application the same as for any other. Thus, if you use these dialog boxes, the user will have less new material to learn to use your application.

In the following program (Listing 5.15), named kstandarddialogs by the call to KApplication on line 10, you see how easily the dialog boxes previously listed can be used. They all provide static methods for retrieving precisely the information you are interested in without instantiating the class, but they may also be subclassed so that their functionality can be altered or extended.

   1 
   2  1: #include <kapp.h>
   3  2: #include <kfiledialog.h>
   4  3: #include <kfontdialog.h>
   5  4: #include <kcolordlg.h>
   6  5: #include <kmessagebox.h>
   7  6: 
   8  7: int
   9  8: main (int argc, char *argv[])
  10  9: {
  11 10:   KApplication kapplication (argc, argv, "kstandarddialogs");
  12 11: 
  13 12:   if (KMessageBox::
  14 13:       warningContinueCancel (0, "Are you sure you want to see this demo?",
  15 14:                              "Demo program", "See demo") ==
  16 15:       KMessageBox::Cancel)
  17 16:     exit (0);
  18 17: 
  19 18:   QString filename = KFileDialog::getOpenFileName ();
  20 19: 
  21 20:   if (filename != "")
  22 21:     {
  23 22:       QString message;
  24 23:       message.sprintf ("The file you selected was \"/home/dsweet/KDE/BOOK/CH05/KStandardDialogs/main.cpp\,   // \>%s\".",
  25 24:                        (const char *)filename);
  26 25:       
  27 26:       KMessageBox::information (0, message, "File selected");
  28 27:     }
  29 28: 
  30 29:   QFont qfont;
  31 30:   if (KFontDialog::getFont (qfont))
  32 31:     {
  33 32:       QString message;
  34 33:       message.sprintf ("Sorry, but you selected \%d point %s\"",
  35 34:                        qfont.pointSize(),
  36 35:                        (const char *) qfont.family());
  37 36: 
  38 37: 
  39 38:       KMessageBox::sorry (0, message, "Font selected");
  40 39:     }
  41 40: 
  42 41:   QColor qcolor;
  43 42:   if (KColorDialog::getColor (qcolor))
  44 43:     {
  45 44:       QString message;
  46 45:       message.sprintf ("Oh no! The color you selected "
  47 46:                        "was (R,G,B)=(%d,%d,%d).",
  48 47:                        qcolor.red(), qcolor.green(), qcolor.blue());
  49 48:       
  50 49:       KMessageBox::error (0, message, "Error:  Color selected");
  51 50:     }      
  52 51:   
  53 52:  return 0;
  54 53: }
  55 

You have used all these dialog boxes from main(). No need exists to create a main widget or even start the application. All these dialog boxes are modal, which means that they have their own local event loops. (Before you can display a window, you still need to create a KApplication so that it can perform some initialization, however.)

Each of the dialog boxes, except for KMessageBox, works in basically the same way. You can call a static method to start the dialog box and you are given back the object selected by the user.

KFileDialog has three static methods that you will often find useful:

• getOpenFileName()—Ask for the name of a file to open.

• getSaveFileName()—Ask for the name of a file to save.

• getExistingDirectory()—Ask for the name of a directory.

These methods return a QString containing the filename or an empty string if no filename was chosen (that is, the user clicked the Cancel button). See line 18 for usage and Figure 5.11 for a screen shot of the file selector dialog box.

To use KFileDialog you must link your program with -lkfile. The other dialog boxes covered here are in part of the standard libraries.

The method KFontDialog::getFont(), used on line 30, takes a QFont object as an argument and fills it with the font chosen by the user. If the user cancels the operation, getFont() returns the constant Qt::Rejected. See Figure 5.12 for a screen shot of the font selector dialog box.

The color selector works just like the font selector. The method KFontDialog::getColor(), used on line 42, takes a QColor object as an argument and fills it with the color chosen by the user. The method returns Qt::Rejected if the user clicks the Cancel button (see Figure 5.13).

KMessageBox can display several types of messages:

   1 
   2 KMessageBox::warningContinueCancel()
   3 

Displays a warning dialog box and gives the user the option to continue with the operation or cancel it. The final argument to this method is the text string that will be placed on the Continue button. In this sample program, you ask users whether they would really like to see the demo, and you put See Demo on the Continue button.

   1 
   2 KMessageBox::information()
   3 

Tells the user something informative, but not related to an error (see Figure 5.15)

   1 
   2 KMessageBox::sorry()
   3 

Tells the user that some requested action is not allowed (see Figure 5.16).

   1 
   2 KMessageBox::error()
   3 

Tells the user that some error has occurred in the execution of a task (see Figure 5.17).