Next Previous Table of Contents
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.
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.
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 ofKMsgBox,KMessageBox. It provides a similar functionality; the 1.x API is no longer available. As a replacement, you can useQMessageBox, providing static methods as well.
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
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.")));
}
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 linknames are:
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.
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:
KFileDialog class, which is a specialized KFileBaseDialog and provides the most needed static methods to retrieve
filenames.KFileDialog class itself, which can be subclassed but also be used for retrieving several filenames and directories.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 filecontentsFor 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.
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.
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 useKFileDialoginstead ofKFileBaseDialogif you like your API to be more consistent.
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.
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.
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.
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.
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.
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.
(kab) date selection dialog
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"));
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.
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.
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.
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