The KDE Library Reference Guide: KDE Dialogs

Next Previous Table of Contents

### 6. KDE Dialogs

A very useful thing of the KDE libraries is that they provide already constructed dialogs for various purposes that are common to a lot of desktop applications. This has two reasons: a) the user feels comfortable using these dialogs if he knows them already from an application and b) lessens the programmer's work a lot. In section Keyboard Accelerators, you already got to know one of these dialogs that KDE provides to configure keybindings. For the other dialogs that are mostly part of the `kdeui` library, the usage is mostly as simple as for the `KKeyDialog` and enhances applications within seconds of coding efforts. You should always first look for an already existing solution for general value requests from the user before starting to implement a new dialog from scratch. Further, you don't have to care about internationalization as these dialogs are part of the KDE libraries and are already translated.

### 6.1 KMsgBox

The `KMsgBox` class provides a whole set of message boxes that match everyday life usage in applications. Using KMsgBox has a lot of advantages: you can use one of the static methods to retrieve results on standard questions and you can still influence the behavior by setting text, window text, symbol and button text.

- message(): providing a single message box with an OK button to inform the user
- yesNo(): provides a yes/no question box.
- yesNoCancel(): provides a yes/no/cancel box with three buttons. Used e.g. to quit an application with the question: Document has been modified. Would you like to save changes ?. Then the yes-button would mean saving changes and exiting the application, no would mean exit without saving and cancel would stop any exiting and just returns.

If this doesn't match your actual need, you could as well create a new KMsgBox instance that can have up to four buttons. This can be used by applications that have multiple open files but don't want the user to ask if he would like to save changes for each file separately; therefore these will need a button "Save All" or something. Then you could program the dialog towards your needs like the static methods and will receive the correct result.

As usual with dialogs, the return value is that what a programmer usually has to process by retrieving it into a variable and then compare with `if()` for the actions to execute.

> The KDE 2 API contains a modified version of `KMsgBox`, `KMessageBox`. It provides a similar functionality; the 1.x API is no longer available. As a replacement, you can use `QMessageBox`, providing static methods as well.

### 6.2 KQuickHelp

The `KQuickHelp` class provides a good way to add quick-help dialogs to widgets. The user can access the quick-help by a context-menu entry "Quick-Help" and is therefore easy to use and gives enough information where a Help-button for the manuals would be too much and a `QToolTip` would be too less. The reason I include `KQuickHelp` into the provided dialogs is that the class-documentation itself contains example usage, but doesn't cover all formatting possibilities, therefore these are listed in detail here.

> In KDE2, KQuickHelp is no longer available and is replaced by QWhatsThis, which has almost the same API

#### Usage

A quick-help window therefore can always be added to a widget by using the static method `add()`, also one help message can be used for more than one widget. The example shows this by adding one message that applies to two widgets that are providing a funcitionality that depends on each other:

    #include <kquickhelp.h>
    #include <kapp.h>
    #include "mydialog.h"

    MyDialog::MyDialog(QWidget* parent, const char* name): QDialog(parent, name)
    {

      file_lineedit= new QLineEdit(this, "file_lineedit");
      file_select_button= new QPushButton(this, "file_select_button");

      KQuickHelp::add(file_lineedit,
      KQuickHelp::add(file_select_button, i18n("Select the filename to process.\n"
                                               "You can use the lineedit or the\n"
                                               "button to select the filename.")));
    }

#### Text Formatting

The text inside your quick-help window can also be formatted to fit various needs, even hyperlinks. Using the KDE-FSSTD, you can also access your online-documentation to provide a link for further information by just using your html filename. This is considered a nice way to give the user the best information in some cases where the purpose of certain functions is too difficult to explain in a quick-help window.

The followindg list contains the valid tags for text formatting:

    Font Attributes           Tag                                         Short-form Tag

    bold font                 <bold></bold>                   <b></b>
    italic font               <italic></italic>               <i></i>
    underlines                <underline></underline>         <u></u>

    Font Size                 Tag                                         Short-form Tag

    increase                  <FONTSIZE +>                          <+>
    decrease                  <FONTSIZE ->                          <->

    Font Selection            Tag                                         Short-form Tag

    default font              <FONT DEFAULT>                        <DEFAULT>
    fixed font                <FONT FIXED>                          <FIXED>

    Indentation               Tag                                         Short-form Tag

    right indent              <INDENT +>                            <i+>
    left indent               <INDENT ->                            <i->

    Color

    RGB color                 <COLOR #>
    red text                  <COLOR RED>                           ><red>
    green text                <COLOR GREEN>                         <green>
    blue text                 <COLOR BLUE>                          <blue>
    white text                <COLOR WHITE>                         <white>
    yellow text               <COLOR YELLOW>                        <yellow>
    black text                <COLOR BLACK>                         <black>
    brown text                <COLOR BROWN>                         <brown>
    magenta text              <COLOR MAGENTA>                       <magenta>
    cyan text                 <COLOR CYAN>                          <cyan>

    Newline                   <br>
    Hyperlinks                <link linkname></link>

Thereby, valid `linkname`s are:

- http://yourlink
- info://yourlink
- ftp://yourlink
- file://yourlink
- mailto:your_address@your_domain

These links will be opened using the `kfm` (KDE File Manager). All other linknames assume that you want to access your application's online-help documentation and therefore use the `linkname` as the file you want to access and tries to open it with the KDEHelp program.

### 6.3 File Dialogs

As the `kfile` library provides several dialogs for retrieving filenames as well as directories, those have to be separated towards which class and method to use for which purpose.

Generally, the `kfile` library offers:

- a `KFileDialog` class, which is a specialized `KFileBaseDialog` and provides the most needed static methods to retrieve filenames.
- the `KFileDialog` class itself, which can be subclassed but also be used for retrieving several filenames and directories.
- the `KFilePreviewDialog` class, which offers file-dialogs that can display selected files by their contents if the developer provides a preview module that is able to show a preview of the filecontents

For general file/directory services, the classes `KFileInfo` and `KDir` can be used.

The following sections will discuss the usage and handling of the according file-dialogs in applications.

#### KFileDialog

The `KFileDialog` class provides four static methods to ask the user for a filename. As the filedialog itself can handle the creation of new folders, storing bookmarks etc, the user will be thankful if you use this dialog to ask for a filename to open and a filename to save files to. The `KFileDialog` class itself is a specialized class that is based on `KFileBaseDialog`, so if the given methods don't fit your needs you can always inherit from `KFileBaseDialog` to customize the settings.

The following examples show the usage for each purpose:

> `

>     // request a filename to open

>     QString open_filename;
>     open_filename=KFileDialog::getOpenFileName()

>     if(!open_filename.isEmpty())
>     {
>       // read the file
>     }

> `

This asks the user for a filename to open. The `KFileDialog` shows and retrieves the information. If the user cancels the filedialog, the return string will be null, therefore you have to test first if `QString::isEmpty()` doesn't return `true` before opening the file actually.

The same goes with the static methods `getSaveFileName()`, `getOpenFileURL()`, `getSaveFileURL()`, whereby each function takes parameters to set the starting directory, mime-types and, as usual, the `QWidget` `parent,name` parameters.

The parallel methods for `getSaveFile` and `getOpenFile` behave identically for retrieving remote and/or local files with the URL dialogs.

#### KFileBaseDialog

The class `KFileBaseDialog` provides the basic interfaces for building filedialogs; therefore filedialogs can be customized in wide ranges towards your needs and is the most flexible way to construct filedialogs. Besides that, the class provides additional functionality for other standard cases like retrieving a directory name. Further functionality can be achieved by inheritance.

Retrieving a directory name

The class provides retrieving a directory name by the static method `getDirectory()`. The following example shows the usage:

> `

>     QString the_directory;

>     the_directory=KFileBaseDialog::getDirectory();

>     if(!the_directory.isEmpty())
>     {
>             // do something
>     }

> `

> Of course, you can also use `KFileDialog` instead of `KFileBaseDialog` if you like your API to be more consistent.

#### KFilePreviewDialog

The class `KFilePreviewDialog` provides another specialized, but more seldomly used filedialog. Its best feature is that it provides an area where the programmer can use a preview widget for his file format to open. The best usage is made within graphic programs that operate on pictures.

### 6.4 KColorDialog

The `KColorDialog` provides an easy-to use interface to receive color values from the user. Color values are always requested, if the application is a drawing or painting program to select the current brush as well as for e.g. KDevelop's dialogeditor to set color values for widgets.

The usage itself is often combined with a `KColorButton`, which is a specific `QPushButton` implemented in `kdeui` that displays a color and calls the `KColorDialog` already when the user presses the button. Anyway, you can call the color dialog from your menu bar or toolbar as well to retrieve a color value from the user.

Using the colordialog is very easy inside applications. The class provides a static method which can be called to retrieve the color value:

    #include <kcolordlg.h>

    QColor myColor;

    int result = KColorDialog::getColor( myColor );

This creates an instance of QColor to store a color value and by calling the static method `getColor()` the color gets the selected value. The returned integer value will probably be of no interest - its the result code of `QDialog` that specifies the dialog has been exited via the OK or Cancel button.

### 6.5 KFontDialog

The `KFontDialog` will retrieve you a value for a font currently avaliable on the system. Therefore using the fontdialog will mostly only make sense where you will need a font; the most recent usage is made by text editors but could also be used to get a formatting for a text to draw inside a widget as well as into a picture.

To retrieve the font value, you probably will use the static methods of `KFontDialog`. The example shows the usage:

      QFont myFont;
      int res = KFontDialog::getFont( myFont );

This is it already - you only have to create a `QFont` instance to contain the font value. Then call the font dialog with the font and after the dialog was executed, your font will have the selected value. Then you have the methods of `QFont` to determine which type of font the user selected etc. to use the font within the application.

### 6.6 KIconLoaderDialog

For applications requiring an icon selection, KDE provides the `KIconLoaderDialog`. The main purpose is to select an icon on the system to draw it on a button for example. Usage is made by the KDE window manager to select the icons for mounted/unmounted states of device links. Then the values for the link are displayed on the according button to display the current selection; the filenames get stored in the link file and can be drawn on the desktop as a symbol by loading the icons dependent on the state of the connected device. There, an additional widget of the `kdeui` libary is used, the `KIconLoaderButton`. Like the `KColorButton`, this class will call the icon loader dialog when the user presses the button and will display the selected icon on the button.

As the `KIconLoaderDialog` class does not provide any static methods, you have to create an instance first and then call `QDialog`'s `exec()` method to display the dialog. Another possibility would be to call `selectIcon()` to execute the dialog but retrieve a `QPixmap` value instead. The selected Icon will be in your `KIconLoader` instance (depending on the used constructor which one - the standard constructor uses the application's `KIconLoader`), therefore the value can be processed with the according methods of `KIconLoader`.

### 6.7 KWizard

The `KWizard` class already contains a predefined dialog to construct wizards that lead the user through an input process. Thereby, the wizard dialog provides the necessary buttons and draws the according page numbers already, so that you only have to construct your widgets you want to use as the single pages for the dialog and insert them in the order you want the user to proceed while calling the wizard.

### 6.8 KSpellDlg

The `KSpellDlg` is part of the `kspell` library. This library contains all functionality to use the `Ispell` application for spell checking. The `KEdit` application makes a good use of this library, so you should take a look at the implementation of `KEdit` on how to implement spell checking functionality. Using the `KSpell` class should last in any case.

### 6.9 DatePickerDialog

(kab) date selection dialog

### 6.10 Qt Dialogs

In some cases, it may be needed to use dialogs provided by Qt. In fact, the only dialog where there are no replacements is a progressdialog and a printing dialog. Of course you could construct one yourself, but the Qt library offers some good solutions for these situations. The following will give you a short overview where to find what you need.

Important: When using Qt dialogs, including QTabDialog for new dialogs, you have to set the labels again with `i18n()` to enable internationalization.

Example:

    QTabDialog tabdlg = new QTabDialog();
    tabdlg->setDefaultButton(i18n("Default"));
    tabdlg->setCancelButton(i18n("Cancel"));
    tabdlg->setApplyButton(i18n("Apply"));
    tabdlg->setOkButton(i18n("OK"));

This will add all four buttons to the tabdialog, so you should only set those buttons you really need.

#### QFileDialog

Using the QFileDialog, you will have the same functionality like KFileDialog. The KDE development prefers the KFileDialog for a consistent look of applications as it offers some nice functionality as well.

#### QMessageBox

As mentioned in section KMsgBox, the QMessageBox can be used as well for messages. One situation where a QMessageBox can serve better is a messagebox containing a picture for example. Usage is provided through static methods which should cover most cases.

#### QPrintDialog

For printing support, you will most likely use the QPrintDialog. As a view-widget displays a document's contents, it will most likely offer routines for printing as well through QPainter drawing on a QPrinter instead of onto a widget.

#### QProgressDialog

When an application is processing data that may take some time to finish, the user expects a notification about that state. For those cases, Qt provides the QProgressDialog. As the class is well documented, including example code for usage, you should take a look at the according API documentation.

Next Previous Table of Contents