summaryrefslogtreecommitdiffstats
path: root/kdeui/kdialogbase.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /kdeui/kdialogbase.h
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kdeui/kdialogbase.h')
-rw-r--r--kdeui/kdialogbase.h1632
1 files changed, 1632 insertions, 0 deletions
diff --git a/kdeui/kdialogbase.h b/kdeui/kdialogbase.h
new file mode 100644
index 000000000..fb46587ad
--- /dev/null
+++ b/kdeui/kdialogbase.h
@@ -0,0 +1,1632 @@
+/*
+ * This file is part of the KDE Libraries
+ * Copyright (C) 1999-2001 Mirko Boehm (mirko@kde.org) and
+ * Espen Sand (espen@kde.org)
+ * Holger Freyther <freyther@kde.org>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public License
+ * along with this library; see the file COPYING.LIB. If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ *
+ */
+#ifndef _KDIALOG_BASE_H_
+#define _KDIALOG_BASE_H_
+
+#include <kdialog.h>
+#include <kjanuswidget.h>
+#include <kguiitem.h>
+#include <kstdguiitem.h>
+#include <qptrlist.h>
+
+class QPushButton;
+class KSeparator;
+class KURLLabel;
+class QBoxLayout;
+class QPixmap;
+class KGuiItem;
+/**
+ * Used internally by KDialogBase.
+ * @internal
+ */
+class KDialogBaseButton;
+
+/**
+ * Used internally by KDialogBase.
+ * @internal
+ */
+class KDialogBaseTile;
+
+/**
+ * @short A dialog base class with standard buttons and predefined layouts.
+ *
+ * Provides basic functionality needed by nearly all dialogs.
+ *
+ * It offers the standard action buttons you'd expect to find in a
+ * dialog as well as the capability to define at most three configurable
+ * buttons. You can define a main widget that contains your specific
+ * dialog layout or you can use a predefined layout. Currently, @p
+ * TreeList/Paged, @p Tabbed, @p Plain, @p Swallow and @p IconList
+ * mode layouts (faces) are available.
+ *
+ * The class takes care of the geometry management. You only need to define
+ * a minimum size for the widget you want to use as the main widget.
+ *
+ * You can set a background tile (pixmap) for parts of the dialog. The
+ * tile you select is shared by all instances of this class in your
+ * application so that they all get the same look and feel.
+ *
+ * There is a tutorial available on http://developer.kde.org/ (NOT YET)
+ * that contains
+ * copy/paste examples as well a screenshots on how to use this class.
+ *
+ * <b>Standard buttons (action buttons):</b>\n
+ *
+ * You select which buttons should be displayed, but you do not choose the
+ * order in which they are displayed. This ensures a standard interface in
+ * KDE. The button order can be changed, but this ability is only available
+ * for a central KDE control tool. The following buttons are available:
+ * OK, Cancel/Close, Apply/Try, Default, Help and three user definable
+ * buttons: User1, User2 and User3. You must specify the text of the UserN
+ * buttons. Each button has a virtual slot so you can overload the method
+ * when required. The default slots emit a signal as well, so you can choose
+ * to connect a signal instead of overriding the slot.
+ * The default implementation of slotHelp() will automatically enable
+ * the help system if you have provided a path to the help text.
+ * slotCancel() and slotClose() will run QDialog::reject()
+ * while slotOk() will run QDialog::accept(). You define a default
+ * button in the constructor.
+ *
+ * If you don't want any buttons at all because your dialog is special
+ * in some way, then set the buttonMask argument in the constructor to zero
+ * (0). The optional button box separator line should not be enabled
+ * in this case. Note that the KDialogBase will animate a button press
+ * when the user press Escape. The button that is enabled is either Cancel,
+ * Close or the button that is defined by setEscapeButton() The
+ * animation will not take place when the buttonMask is zero. Your
+ * custom dialog code should reimplement the keyPressEvent and
+ * animate the cancel button so that the dialog behaves like regular
+ * dialogs. NOTE: None of the regular slots (like slotOk() ) or
+ * signals that are related to the standard action buttons will be used
+ * when you don't use these buttons.
+ *
+ * <b>Dialog shapes:</b>\n
+ *
+ * You can either use one of the prebuilt, easy to use, faces or
+ * define your own main widget. The dialog provides ready to use
+ * TreeList, Tabbed, Plain, Swallow and IconList faces. KDialogBase uses
+ * the KJanusWidget class internally to accomplish this. If you
+ * use TreeList, Tabbed or IconList mode, then add pages with addPage().
+ *
+ * Pages that have been added can be removed again by simply deleting
+ * the page.
+ *
+ * If you want complete control of how the dialog contents should look,
+ * then you can define a main widget by using setMainWidget(). You
+ * only need to set the minimum size of that widget and the dialog will
+ * resize itself to fit this minimum size. The dialog is resizeable, but
+ * cannot be made smaller than its minimum size.
+ *
+ * <b>Layout:</b>\n
+ *
+ * The dialog consists of a help area on top (becomes visible if you define
+ * a help path and use enableLinkedHelp()), the main area which is
+ * the built-in dialog face or your own widget in the middle and by default
+ * a button box at the bottom. The button box can also be placed at the
+ * right edge (to the right of the main widget). Use
+ * setButtonBoxOrientation() to control this behavior. A separator
+ * can be placed above the button box (or to the left when the button box
+ * is at the right edge). Normally you specify that you want a separator
+ * in the constructor, but you can use enableButtonSeparator() as well.
+ *
+ * <b>Standard compliance:</b>\n
+ *
+ * The class is derived from KDialog, so you get automatic access to
+ * the KDialog::marginHint(), KDialog::spacingHint() and the
+ * extended KDialog::setCaption() method. NOTE: The main widget you
+ * use will be positioned inside the dialog using a margin (or border)
+ * equal to KDialog::marginHint(). You should not add a margin yourself,
+ * since one will be added automatically.
+ * The example below (from kedit) shows how you use the top level widget
+ * and its layout. The second argument (the border) to QVBoxLayout
+ * is 0. This situation is valid for addPage , addVBoxPage ,
+ * addHBoxPage , addGridPage , makeMainWidget ,
+ * makeVBoxMainWidget , makeHBoxMainWidget and
+ * makeGridMainWidget as well.
+ *
+ * Example:
+ *
+ * \code
+ * UrlDlg::UrlDlg( QWidget *parent, const QString& caption,
+ * const QString& urltext)
+ * : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true )
+ * {
+ * QWidget *page = new QWidget( this );
+ * setMainWidget(page);
+ * QVBoxLayout *topLayout = new QVBoxLayout( page, 0, spacingHint() );
+ *
+ * QLabel *label = new QLabel( caption, page, "caption" );
+ * topLayout->addWidget( label );
+ *
+ * lineedit = new QLineEdit( urltext, page, "lineedit" );
+ * lineedit->setMinimumWidth(fontMetrics().maxWidth()*20);
+ * topLayout->addWidget( lineedit );
+ *
+ * topLayout->addStretch(10);
+ * }
+ * \endcode
+ *
+ * If you use makeVBoxMainWidget(), then the dialog above can be made
+ * simpler but you lose the ability to add a stretchable area:
+ *
+ * \code
+ * UrlDlg::UrlDlg( QWidget *parent, const QString& caption,
+ * const QString& urltext)
+ * : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true )
+ * {
+ * QVBox *page = makeVBoxMainWidget();
+ * QLabel *label = new QLabel( caption, page, "caption" );
+ *
+ * lineedit = new QLineEdit( urltext, page, "lineedit" );
+ * lineedit->setMinimumWidth(fontMetrics().maxWidth()*20);
+ * }
+ * \endcode
+ *
+ * This class can be used in many ways. Note that most KDE ui widgets
+ * and many of KDE core applications use the KDialogBase so for more
+ * inspiration you should study the code for these.
+ *
+ * @author Mirko Boehm (mirko@kde.org) and Espen Sand (espen@kde.org)
+ */
+class KDEUI_EXPORT KDialogBase : public KDialog
+{
+ Q_OBJECT
+
+ public:
+
+ enum ButtonCode
+ {
+ Help = 0x00000001, ///< Show Help button.
+ Default = 0x00000002, ///< Show Default button.
+ Ok = 0x00000004, ///< Show Ok button.
+ Apply = 0x00000008, ///< Show Apply button.
+ Try = 0x00000010, ///< Show Try button.
+ Cancel = 0x00000020, ///< Show Cancel-button.
+ Close = 0x00000040, ///< Show Close-button.
+ User1 = 0x00000080, ///< Show User defined button 1.
+ User2 = 0x00000100, ///< Show User defined button 2.
+ User3 = 0x00000200, ///< Show User defined button 3.
+ No = 0x00000080, ///< Show No button.
+ Yes = 0x00000100, ///< Show Yes button.
+ Details = 0x00000400, ///< Show Details button.
+ Filler = 0x40000000, ///< @internal Ignored when used in a constructor.
+ Stretch = 0x80000000, ///< @internal Ignored when used in a constructor.
+ NoDefault ///< Used when specifying a default button; indicates that no button should be marked by default. @since 3.3
+ };
+
+ enum ActionButtonStyle
+ {
+ ActionStyle0=0, // KDE std
+ ActionStyle1,
+ ActionStyle2,
+ ActionStyle3,
+ ActionStyle4,
+ ActionStyleMAX
+ };
+
+ /**
+ * @li @p TreeList - A dialog with a tree on the left side and a
+ * representation of the contents on the right side.
+ * @li @p Tabbed - A dialog using a QTabWidget.
+ * @li @p Plain - A normal dialog. Use plainPage() as parent for widgets.
+ * @li @p Swallow - Simplifes the usage of existing widgets. You specify
+ * the widget to be displayed by setMainWidget().
+ * @li @p IconList - A dialog with an iconlist on the left side and a
+ * representation of the contents on the right side.
+ */
+ enum DialogType
+ {
+ TreeList = KJanusWidget::TreeList,
+ Tabbed = KJanusWidget::Tabbed,
+ Plain = KJanusWidget::Plain,
+ Swallow = KJanusWidget::Swallow,
+ IconList = KJanusWidget::IconList
+ };
+
+ public:
+
+ /**
+ * Constructor for the standard mode where you must specify the main
+ * widget with setMainWidget() .
+ *
+ * @param parent Parent of the dialog.
+ * @param name Dialog name (for internal use only)
+ * @param modal Controls dialog modality. If @p false, the rest of the
+ * program interface (example: other dialogs) is accessible while
+ * the dialog is open.
+ * @param caption The dialog caption. Do not specify the application name
+ * here. The class will take care of that.
+ * @param buttonMask Specifies which buttons will be visible. If zero
+ * (0) no button box will be made.
+ * @param defaultButton Specifies which button will be marked as
+ * the default. Use ButtonCode::NoDefault to indicate that no button
+ * should be marked as the default button.
+ * @param separator If @p true, a separator line is drawn between the
+ * action buttons and the main widget.
+ * @param user1 User button1 item.
+ * @param user2 User button2 item.
+ * @param user3 User button3 item.
+ */
+ KDialogBase( QWidget *parent=0, const char *name=0, bool modal=true,
+ const QString &caption=QString::null,
+ int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok,
+ bool separator=false,
+ const KGuiItem &user1=KGuiItem(),
+ const KGuiItem &user2=KGuiItem(),
+ const KGuiItem &user3=KGuiItem() );
+
+ /**
+ * In KDE4 a WFlag paramater should be added after modal and next
+ * function can be removed.
+ *
+ * Constructor for the predefined layout mode where you specify the
+ * kind of layout (face).
+ *
+ * @param dialogFace You can use TreeList, Tabbed, Plain, Swallow or
+ * IconList.
+ * @param caption The dialog caption. Do not specify the application name
+ * here. The class will take care of that.
+ * @param buttonMask Specifies which buttons will be visible. If zero
+ * (0) no button box will be made.
+ * @param defaultButton Specifies which button will be marked as
+ * the default. Use ButtonCode::NoDefault to indicate that no button
+ * should be marked as the default button.
+ * @param parent Parent of the dialog.
+ * @param name Dialog name (for internal use only).
+ * @param modal Controls dialog modality. If @p false, the rest of the
+ * program interface (example: other dialogs) is accessible while
+ * the dialog is open.
+ * @param separator If @p true, a separator line is drawn between the
+ * action buttons and the main widget.
+ * @param user1 User button1 text item.
+ * @param user2 User button2 text item.
+ * @param user3 User button3 text item.
+ */
+ KDialogBase( int dialogFace, const QString &caption,
+ int buttonMask, ButtonCode defaultButton,
+ QWidget *parent=0, const char *name=0, bool modal=true,
+ bool separator=false,
+ const KGuiItem &user1=KGuiItem(),
+ const KGuiItem &user2=KGuiItem(),
+ const KGuiItem &user3=KGuiItem() );
+
+
+ /**
+ * Constructor for the predefined layout mode where you specify the
+ * kind of layout (face).
+ *
+ * @param dialogFace You can use TreeList, Tabbed, Plain, Swallow or
+ * IconList.
+ * @param f widget flags, by default it is just set to WStyle_DialogBorder.
+ * @param caption The dialog caption. Do not specify the application name
+ * here. The class will take care of that.
+ * @param parent Parent of the dialog.
+ * @param name Dialog name (for internal use only).
+ * @param modal Controls dialog modality. If @p false, the rest of the
+ * program interface (example: other dialogs) is accessible while
+ * the dialog is open.
+ * @param buttonMask Specifies which buttons will be visible. If zero
+ * (0) no button box will be made.
+ * @param defaultButton Specifies which button will be marked as
+ * the default. Use ButtonCode::NoDefault to indicate that no button
+ * should be marked as the default button.
+ * @param separator If @p true, a separator line is drawn between the
+ * action buttons and the main widget.
+ * @param user1 User button1 text item.
+ * @param user2 User button2 text item.
+ * @param user3 User button3 text item.
+ * @since: 3.2
+ */
+
+ KDialogBase( KDialogBase::DialogType dialogFace, WFlags f,
+ QWidget *parent=0, const char *name=0, bool modal=true,
+ const QString &caption=QString::null,
+ int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok,
+ bool separator=false,
+ const KGuiItem &user1=KGuiItem(),
+ const KGuiItem &user2=KGuiItem(),
+ const KGuiItem &user3=KGuiItem() );
+
+ /**
+ * Constructor for a message box mode where the @p buttonMask can only
+ * contain Yes, No, or Cancel.
+ *
+ * If you need other names you can rename
+ * the buttons with setButtonText(). The dialog box is not resizable
+ * by default but this can be changed by setInitialSize(). If you
+ * select 'modal' to be true, the dialog will return Yes, No, or Cancel
+ * when closed otherwise you can use the signals yesClicked(),
+ * noClicked(), or cancelClicked() to determine the state.
+ *
+ * @param caption The dialog caption. Do not specify the application name
+ * here. The class will take care of that.
+ * @param buttonMask Specifies which buttons will be visible. If zero
+ * (0) no button box will be made.
+ * @param defaultButton Specifies which button will be marked as
+ * the default. Use ButtonCode::NoDefault to indicate that no button
+ * should be marked as the default button.
+ * @param escapeButton Specifies which button will be activated by
+ * when the dialog receives a @p Key_Escape keypress.
+ * @param parent Parent of the dialog.
+ * @param name Dialog name (for internal use only).
+ * @param modal Controls dialog modality. If @p false, the rest of the
+ * program interface (example: other dialogs) is accessible
+ * while the dialog is open.
+ * @param separator If @p true, a separator line is drawn between the
+ * action buttons and the main widget.
+ * @param yes Text to use for the first button (defaults to i18n("Yes"))
+ * @param no Text to use for the second button (defaults to i18n("No"))
+ * @param cancel Text to use for the third button (defaults to i18n("Cancel"))
+ */
+ KDialogBase( const QString &caption, int buttonMask=Yes|No|Cancel,
+ ButtonCode defaultButton=Yes, ButtonCode escapeButton=Cancel,
+ QWidget *parent=0, const char *name=0,
+ bool modal=true, bool separator=false,
+ const KGuiItem &yes = KStdGuiItem::yes(), // i18n("&Yes")
+ const KGuiItem &no = KStdGuiItem::no(), // i18n("&No"),
+ const KGuiItem &cancel = KStdGuiItem::cancel() // i18n("&Cancel")
+ );
+
+ /**
+ * Destructor.
+ */
+ ~KDialogBase();
+
+ /**
+ * Sets the orientation of the button box.
+ *
+ * It can be @p Vertical or @p Horizontal. If @p Horizontal
+ * (default), the button box is positioned at the bottom of the
+ * dialog. If @p Vertical it will be placed at the right edge of the
+ * dialog.
+ *
+ * @param orientation The button box orientation.
+ */
+ void setButtonBoxOrientation( int orientation );
+
+ /**
+ * Sets the button that will be activated when the Escape key
+ * is pressed.
+ *
+ * Normally you should not use this function. By default,
+ * the Escape key is mapped to either the Cancel or the Close button
+ * if one of these buttons are defined. The user expects that Escape will
+ * cancel an operation so use this function with caution.
+ *
+ * @param id The button code.
+ */
+ void setEscapeButton( ButtonCode id );
+
+
+ /**
+ * Adjust the size of the dialog to fit the contents just before
+ * QDialog::exec() or QDialog::show() is called.
+ *
+ * This method will not be called if the dialog has been explicitly
+ * resized before showing it.
+ **/
+ virtual void adjustSize();
+ virtual QSize sizeHint() const;
+ virtual QSize minimumSizeHint() const;
+
+ /**
+ * Retrieve the empty page when the predefined layout is used in @p Plain
+ * mode.
+ *
+ * This widget must be used as the toplevel widget of your dialog
+ * code.
+ *
+ * @return The widget or 0 if the predefined layout mode is not @p Plain
+ * or if you don't use any predefined layout.
+ */
+ QFrame *plainPage();
+
+ /**
+ * Add a page to the dialog when the class is used in @p TreeList ,
+ * @p IconList or @p Tabbed mode.
+ *
+ * The returned widget must be used as the
+ * toplevel widget for this particular page.
+ * Note: The returned frame widget has no
+ * layout manager associated with it. In order to use it you must
+ * create a layout yourself as the example below illustrates:
+ *
+ * \code
+ * QFrame *page = addPage( i18n("Layout") );
+ * QVBoxLayout *topLayout = new QVBoxLayout( page, 0, KDialog::spacingHint() );
+ * QLabel *label = new QLabel( i18n("Layout type"), page );
+ * topLayout->addWidget( label );
+ * ..
+ * \endcode
+ *
+ * @param itemName String used in the list or as tab item name.
+ * @param header Header text use in the list modes. Ignored in @p Tabbed
+ * mode. If empty, the item text is used instead.
+ * @param pixmap Used in @p IconList mode. You should prefer a pixmap
+ * with size 32x32 pixels.
+ *
+ * @return The page widget which must be used as the toplevel widget for
+ * the page.
+ */
+ QFrame *addPage( const QString &itemName,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * This is like addPage() just above, with the difference that the first
+ * element is a list of strings.
+ *
+ * These strings are used to form a path
+ * of folders down to the given page. The initial elements are names
+ * for the folders, while the last element is the name of the page.
+ * Note: This does yet only work for the @p TreeList face. Later this may
+ * be added for the @p IconList face too. In other faces than the
+ * @p TreeList, all the strings except the last one is ignored.
+ **/
+ QFrame *addPage( const QStringList &items,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * Add a page to the dialog when the class is used in @p TreeList,
+ * @p IconList or @p Tabbed mode.
+ *
+ * The returned widget must be used as the toplevel widget for
+ * this particular page. The widget contains a QVBoxLayout
+ * layout so the widget children are lined up vertically. You can
+ * use it as follows:
+ *
+ * \code
+ * QVBox *page = addVBoxPage( i18n("Layout") );
+ * QLabel *label = new QLabel( i18n("Layout type"), page );
+ * ..
+ * \endcode
+ *
+ * @param itemName String used in the list or as tab item name.
+ * @param header Header text use in the list modes. Ignored in @p Tabbed
+ * mode. If empty, the item text is used instead.
+ * @param pixmap Used in @p IconList mode. You should prefer a pixmap
+ * with size 32x32 pixels.
+ *
+ * @return The page widget which must be used as the toplevel widget for
+ * the page.
+ */
+ QVBox *addVBoxPage( const QString &itemName,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * This is like addVBoxPage() just above, with the difference
+ * that the first element is a list of strings.
+ *
+ * These strings are used to form a path
+ * of folders down to the given page. The initial elements are names
+ * for the folders, while the last element is the name of the page.
+ * Note: This does yet only work for the @p TreeList face. Later this may
+ * be added for the @p IconList face too. In other faces than the
+ * @p TreeList, all the strings except the last one is ignored.
+ **/
+ QVBox *addVBoxPage( const QStringList &items,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * Add a page to the dialog when the class is used in @p TreeList,
+ * @p IconList or @p Tabbed mode.
+ *
+ * The returned widget must be used as the
+ * toplevel widget for this particular page. The widget contains a
+ * QHBoxLayout layout so the widget children are lined up horizontally.
+ * You can use it as follows:
+ *
+ * @param itemName String used in the list or as tab item name.
+ * @param header Header text use in the list modes. Ignored in Tabbed
+ * mode. If empty, the item text is used instead.
+ * @param pixmap Used in IconList mode. You should prefer a pixmap
+ * with size 32x32 pixels.
+ *
+ * @return The page widget which must be used as the toplevel widget for
+ * the page.
+ */
+ QHBox *addHBoxPage( const QString &itemName,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * This is like addHBoxPage() just above, with the
+ * difference that the first element is a list of strings.
+ *
+ * These strings are used to form a path
+ * of folders down to the given page. The initial elements are names
+ * for the folders, while the last element is the name of the page.
+ * Note: This does yet only work for the @p TreeList face. Later this may
+ * be added for the @p IconList face too. In other faces than the
+ * @p TreeList, all the strings except the last one is ignored.
+ **/
+ QHBox *addHBoxPage( const QStringList &items,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+ /**
+ * Add a page to the dialog when the class is used in @p TreeList,
+ * @p IconList or @p Tabbed mode.
+ *
+ * The returned widget must be used as the
+ * toplevel widget for this particular page. The widget contains a
+ * QGridLayout layout so the widget children are positioned in a grid.
+ *
+ * @param n Specifies the number of columns if @p dir is Qt::Horizontal
+ * or the number of rows if @p dir is Qt::Vertical.
+ * @param dir Can be Qt::Horizontal or Qt::Vertical.
+ * @param itemName String used in the list or as tab item name.
+ * @param header Header text use in the list modes @p Ignored in @p Tabbed
+ * mode. If empty, the item text is used instead.
+ * @param pixmap Used in @p IconList mode. You should prefer a pixmap
+ * with size 32x32 pixels.
+ *
+ * @return The page widget which must be used as the toplevel widget for
+ * the page.
+ */
+ QGrid *addGridPage( int n, Orientation dir,
+ const QString &itemName,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+
+ /**
+ * This is like addGridPage() just above, with the difference
+ * that the first element is a list of strings.
+ *
+ * These strings are used to form a path
+ * of folders down to the given page. The initial elements are names
+ * for the folders, while the last element is the name of the page.
+ * Note: This does yet only work for the @p TreeList face. Later this may
+ * be added for the @p IconList face too. In other faces than the
+ * @p TreeList, all the strings except the last one is ignored.
+ **/
+ QGrid *addGridPage( int n, Orientation dir,
+ const QStringList &items,
+ const QString &header=QString::null,
+ const QPixmap &pixmap=QPixmap() );
+
+
+ /**
+ * Sets the icon used in @p TreeList Mode for the given path.
+ *
+ * @param path The path for which this icon should be shown.
+ * @param pixmap The icon used.
+ **/
+ void setFolderIcon(const QStringList &path,const QPixmap &pixmap);
+
+ /**
+ * Make a main widget.
+ *
+ * The function will make a QFrame widget
+ * and use setMainWidget() to register it. You can @em not use this
+ * function more than once, @em not if you have already defined a
+ * main widget with setMainWidget() and @em not if you have used the
+ * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
+ * @p TreeList).
+ *
+ * @return The main widget or 0 if any of the rules described above
+ * were broken.
+ */
+ QFrame *makeMainWidget();
+
+ /**
+ * Make a main widget.
+ *
+ * The function will make a QVBox widget
+ * and use setMainWidget() to register it. You @em can use this
+ * function more than once, but @em not if you have already defined a
+ * main widget with setMainWidget() and @em not if you have used the
+ * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
+ * @p TreeList, @p IconList).
+ *
+ * @return The main widget or 0 if any of the rules described above
+ * were broken.
+ */
+ QVBox *makeVBoxMainWidget();
+
+ /**
+ * Make a main widget.
+ *
+ * The function will make a QHBox widget
+ * and use setMainWidget() to register it. You can @em not use this
+ * function more than once, @em not if you have already defined a
+ * main widget with setMainWidget() and @p not if you have used the
+ * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
+ * @p TreeList, @p IconList).
+ *
+ * @return The main widget or 0 if any of the rules described above
+ * were broken.
+ */
+ QHBox *makeHBoxMainWidget();
+
+ /**
+ * Make a main widget.
+ *
+ * The function will make a QGrid widget
+ * and use setMainWidget() to register it. You can @em not use this
+ * function more than once, @em not if you have already defined a
+ * main widget with setMainWidget and @em not if you have used the
+ * constructor where you define the face (Plain, Swallow, Tabbed,
+ * TreeList, IconList).
+ *
+ * @param n Specifies the number of columns if 'dir' is Qt::Horizontal
+ * or the number of rows if 'dir' is Qt::Vertical.
+ * @param dir Can be Qt::Horizontal or Qt::Vertical.
+ *
+ * @return The main widget or 0 if any of the rules described above
+ * were broken.
+ */
+ QGrid *makeGridMainWidget( int n, Orientation dir );
+
+
+ /**
+ * Hide or display the a separator line drawn between the action
+ * buttons an the main widget.
+ */
+ void enableButtonSeparator( bool state );
+
+ /**
+ * Hide or display a general action button.
+ *
+ * Only buttons that have
+ * been created in the constructor can be displayed. This method will
+ * not create a new button.
+ *
+ * @param id Button identifier.
+ * @param state true display the button(s).
+ */
+ void showButton( ButtonCode id, bool state );
+
+ /**
+ * Hide or display the OK button.
+ *
+ * The OK button must have
+ * been created in the constructor to be displayed.
+ *
+ * @param state If @p true, display the button(s).
+ */
+ void showButtonOK( bool state );
+
+ /**
+ * Hide or display the Apply button.
+ *
+ * The Apply button must have
+ * been created in the constructor to be displayed.
+ *
+ * @param state true display the button(s).
+ */
+ void showButtonApply( bool state );
+
+ /**
+ * Hide or display the Cancel button. The Cancel button must have
+ * been created in the constructor to be displayed.
+ *
+ * @param state @p true display the button(s).
+ */
+ void showButtonCancel( bool state );
+
+ /**
+ * Sets the page with @p index to be displayed.
+ *
+ * This method will only
+ * work when the dialog is using the predefined shape of TreeList,
+ * IconList or Tabbed.
+ *
+ * @param index Index of the page to be shown.
+ * @return @p true if the page is shown, @p false otherwise.
+ */
+ bool showPage( int index );
+
+ /**
+ * Returns the index of the active page.
+ *
+ * This method will only work when the dialog is using the
+ * predefined shape of Tabbed, TreeList or IconList.
+ *
+ * @return The page index or -1 if there is no active page.
+ */
+ int activePageIndex() const;
+
+
+ /**
+ * Returns the index of a page created with addPage(),
+ * addVBoxPage(), addHBoxPage() or addGridPage().
+ * You can can compare this index with the value returned from
+ * activePageIndex() if you need to do some page specific actions
+ * in your code.
+ *
+ * The returned index will never change so you can safely use this
+ * function once and save the value.
+ *
+ * @param widget The widget returned by addPage(), addVBoxPage(),
+ * addHBoxPage() or addGridPage().
+ *
+ * @return The index or -1 if the face is not Tabbed, TreeList or
+ * IconList
+ */
+ int pageIndex( QWidget *widget ) const;
+
+
+ /**
+ * Sets the main user definable widget.
+ *
+ * If the dialog is using the predefined Swallow mode, the widget will
+ * be reparented to the internal swallow control widget. If the dialog
+ * is being used in the standard mode then the @p widget must have the
+ * dialog as parent.
+ *
+ * @param widget The widget to be displayed as main widget. If it
+ * is 0, then the dialog will show an empty space of 100x100 pixels
+ * instead.
+ */
+ void setMainWidget( QWidget *widget );
+
+ /**
+ * Returns the main widget if any.
+ *
+ * @return The current main widget. Can be 0 if no widget has been defined.
+ */
+ QWidget *mainWidget();
+
+ /**
+ * Convenience method.
+ *
+ * Freezes the dialog size using the minimum size
+ * of the dialog. This method should only be called right before
+ * show() or exec().
+ */
+ void disableResize();
+
+ /**
+ * Convenience method. Sets the initial dialog size.
+ *
+ * This method should
+ * only be called right before show() or exec(). The initial
+ * size will be
+ * ignored if smaller than the dialog's minimum size.
+ *
+ * @param s Startup size.
+ * @param noResize If @p true the dialog cannot be resized.
+ */
+ void setInitialSize( const QSize &s, bool noResize=false );
+
+ /**
+ * Convenience method. Add a size to the default minimum size of a
+ * dialog.
+ *
+ * This method should only be called right before show() or
+ * exec().
+ *
+ * @param s Size added to minimum size.
+ * @param noResize If @p true the dialog cannot be resized.
+ */
+ void incInitialSize( const QSize &s, bool noResize=false );
+
+ /**
+ * read the dialogs size from the configuration according to the screen size.
+ * If no size is saved for one dimension of the screen, sizeHint() is returned.
+ *
+ * @param groupName Name of the group to read from. The old group
+ * of KGlobal::config is preserved.
+ */
+ QSize configDialogSize( const QString& groupName ) const;
+
+ /**
+ * read the dialogs size from the configuration according to the screen size.
+ * If no size is saved for one dimension of the screen, sizeHint() is returned.
+ *
+ * @param config The KConfig object to read from
+ * @param groupName Name of the group to read from. The old group
+ * of KGlobal::config is preserved.
+ * @since 3.2
+ */
+ QSize configDialogSize( KConfig& config, const QString& groupName ) const;
+
+ /**
+ * save the dialogs size dependant on the screen dimension either to the
+ * global or application config file.
+ *
+ * @param groupName The group to which the dialogs size is saved. See configDialogSize
+ * to read the size.
+ * @param global Set to true if the entry should go to the global config rather
+ * than to the applications config. Default is false.
+ */
+ void saveDialogSize( const QString& groupName, bool global=false );
+
+ /**
+ * save the dialogs size dependant on the screen dimension.
+ *
+ * @param config The KConfig object to write to.
+ * @param groupName The group to which the dialogs size is saved. See
+ * configDialogSize to read the size.
+ * @param global Set to true if the entry should go to the global config.
+ * Default is false.
+ * @since 3.2
+ */
+ void saveDialogSize( KConfig& config, const QString& groupName,
+ bool global=false ) const;
+
+ /**
+ * Sets the appearance of the OK button.
+ *
+ * If the default parameters are used
+ * (that is, if no KGuiItem is given) KStdGuiItem::ok() is used.
+ *
+ * @param item KGuiItem.
+ * @since 3.2
+ */
+ void setButtonOK( const KGuiItem &item = KStdGuiItem::ok() );
+
+ /**
+ * @deprecated. Use setButtonOk() instead.
+ *
+ * Sets the text of the OK button.
+ *
+ * If the default parameters are used
+ * (that is, if no parameters are given) the standard texts are set:
+ * The button shows "OK", the tooltip contains "Accept settings."
+ * (internationalized) and the quickhelp text explains the standard
+ * behavior of the OK button in settings dialogs.
+ *
+ * @param text Button text.
+ * @param tooltip Tooltip text.
+ * @param quickhelp Quick help text.
+ */
+ void setButtonOKText( const QString &text=QString::null,
+ const QString &tooltip=QString::null,
+ const QString &quickhelp=QString::null ) KDE_DEPRECATED;
+
+ /**
+ * Sets the appearance of the Apply button.
+ *
+ * If the default parameters are used
+ * (that is, if no KGuiItem is given) KStdGuiItem::apply() is used.
+ *
+ * @param item KGuiItem.
+ * @since 3.2
+ */
+ void setButtonApply( const KGuiItem &item = KStdGuiItem::apply() );
+
+ /**
+ * @deprecated. Use setButtonApply() instead.
+ *
+ * Sets the text of the Apply button.
+ *
+ * If the default parameters are
+ * used (that is, if no parameters are given) the standard texts are set:
+ * The button shows "Apply", the tooltip contains "Apply settings."
+ * (internationalized) and the quickhelp text explains the standard
+ * behavior of the apply button in settings dialogs.
+ *
+ * @param text Button text.
+ * @param tooltip Tooltip text.
+ * @param quickhelp Quick help text.
+ */
+ void setButtonApplyText( const QString &text=QString::null,
+ const QString &tooltip=QString::null,
+ const QString &quickhelp=QString::null ) KDE_DEPRECATED;
+
+ /**
+ * Sets the appearance of the Cancel button.
+ *
+ * If the default parameters are used
+ * (that is, if no KGuiItem is given) KStdGuiItem::cancel() is used.
+ *
+ * @param item KGuiItem.
+ * @since 3.2
+ */
+ void setButtonCancel( const KGuiItem &item = KStdGuiItem::cancel() );
+
+ /**
+ * @deprecated. Use setButtonCancel() instead.
+ *
+ * Sets the text of the Cancel button.
+ *
+ * If the default parameters are
+ * used (that is, if no parameters are given) the standard texts are set:
+ * The button shows "Cancel", everything else will not be set.
+ *
+ * @param text Button text.
+ * @param tooltip Tooltip text.
+ * @param quickhelp Quick help text.
+ */
+ void setButtonCancelText( const QString &text=QString::null,
+ const QString &tooltip=QString::null,
+ const QString &quickhelp=QString::null ) KDE_DEPRECATED;
+
+ /**
+ * Sets the text of any button.
+ *
+ * @param id The button identifier.
+ * @param text Button text.
+ */
+ void setButtonText( ButtonCode id, const QString &text );
+
+ /**
+ * Sets the tooltip text of any button.
+ *
+ * @param id The button identifier.
+ * @param text Button text.
+ */
+ void setButtonTip( ButtonCode id, const QString &text );
+
+ /**
+ * Sets the "What's this?" text of any button.
+ *
+ * @param id The button identifier.
+ * @param text Button text.
+ */
+ void setButtonWhatsThis( ButtonCode id, const QString &text );
+
+ /**
+ * Sets the KGuiItem directly for the button instead of using 3 methods to
+ * set the text, tooltip and whatsthis strings. This also allows to set an
+ * icon for the button which is otherwise not possible for the extra
+ * buttons beside Ok, Cancel and Apply.
+ *
+ * @param id The button identifier.
+ * @param item The KGuiItem for the button.
+ *
+ * @since 3.3
+ */
+ void setButtonGuiItem( ButtonCode id, const KGuiItem &item );
+
+ /**
+ * This function has only effect in TreeList mode.
+ *
+ * Defines how the tree list widget is resized when the dialog is
+ * resized horizontally. By default the tree list keeps its width
+ * when the dialog becomes wider.
+ *
+ * @param state The resize mode. If false (default) the tree list keeps
+ * its current width when the dialog becomes wider.
+ */
+ void setTreeListAutoResize( bool state );
+
+ /**
+ * This function has only effect in TreeList mode.
+ *
+ * This tells the widgets whether the icons given in the addPage,
+ * addVBoxPage, addHBoxPage, or addGridPage methods should
+ * be shown in the TreeList.
+ *
+ * Note: This method must be called before calling any of the methods
+ * which add icons to the page.
+ *
+ * @param state If true the icons are shown.
+ **/
+ void setShowIconsInTreeList(bool state);
+
+ /**
+ * This function has only effect in TreeList mode.
+ *
+ * This tells the widgets whether the root should be decorated.
+ * For details see QListView::setRootIsDecorated
+ *
+ * @param state Root will be decorated if true.
+ **/
+ void setRootIsDecorated( bool state );
+
+ /**
+ * This function has only effect in TreeList mode.
+ *
+ * This tells the TreeList to unfold the whole tree so that all entries
+ * are visible.
+ *
+ * If the list is empty when you call this method newly created entries
+ * will not automatically be opened. If the @p persist flag is set opened
+ * entries cannot be closed again, though.
+ *
+ * @param persist If true the tree always stays unfolded.
+ * @since 3.2
+ */
+ void unfoldTreeList( bool persist = false );
+
+ /**
+ * Add a widget at the bottom of the TreeList/IconList.
+ *
+ * @param widget The widget to be added. It will be reparented into the
+ * KJanusWidget, therefor it will be deleted with the
+ * KJanusWidget, too. To be on the save side just don't keep
+ * the pointer to this widget.
+ */
+ void addWidgetBelowList( QWidget * widget );
+
+ /**
+ * Add a button at the bottom of the TreeList/IconList.
+ *
+ * @param text The text on the PushButton.
+ * @param recv The object that is to receive the signal when the button
+ * is clicked.
+ * @param slot The slot to connect to the clicked signal of the button.
+ *
+ * @since 3.2
+ */
+ void addButtonBelowList( const QString & text, QObject * recv, const char * slot );
+
+ /**
+ * The same as the above function, but with a KGuiItem providing the text
+ * and icon for the button at the bottom of the TreeList/IconList.
+ *
+ * @param guiitem The text and icon on the PushButton.
+ * @param recv The object that is to receive the signal when the button
+ * is clicked.
+ * @param slot The slot to connect to the clicked signal of the button.
+ *
+ * @since 3.2
+ */
+ void addButtonBelowList( const KGuiItem & guiitem, QObject * recv, const char * slot );
+
+ /**
+ * This function has only effect in IconList mode.
+ *
+ * Defines how the icon list widget is displayed. By default it is
+ * the widgets in the dialog pages that decide the minimum height
+ * of the dialog. A vertical scrollbar can be used in the icon list
+ * area.
+ *
+ * @param state The visibility mode. If true, the minimum height is
+ * adjusted so that every icon in the list is visible at the
+ * same time. The vertical scrollbar will never be visible.
+ */
+ void setIconListAllVisible( bool state );
+
+ /**
+ * Check whether the background tile is set or not.
+ *
+ * @return @p true if there is defined a background tile.
+ */
+ static bool haveBackgroundTile();
+
+ /**
+ * Returns a pointer to the background tile if there is one.
+ *
+ * @return The tile pointer or 0 if no tile is defined.
+ *
+ **/
+ static const QPixmap *backgroundTile();
+ /**
+ * @deprecated
+ * Use backgroundTile() instead.
+ */
+ static const QPixmap *getBackgroundTile() KDE_DEPRECATED;
+
+ /**
+ * Sets the background tile.
+ *
+ * If it is Null (0), the background image is deleted.
+ *
+ * @param pix The background tile.
+ */
+ static void setBackgroundTile( const QPixmap *pix );
+
+ /**
+ * Enable hiding of the background tile (if any).
+ *
+ * @param state @p true will make the tile visible.
+ */
+ void showTile( bool state );
+
+ /**
+ * @deprecated
+ * Do not use this method. It is included for compatibility reasons.
+ *
+ * This method returns the border widths in all directions the dialog
+ * needs for itself. Respect this, or get bad looking results.
+ * The references are upper left x (@p ulx), upper left y (@p uly),
+ * lower right x (@p lrx), and lower left y (@p lly).
+ * The results are differences in pixels from the
+ * dialogs corners.
+ */
+ void getBorderWidths( int& ulx, int& uly, int& lrx, int& lry ) const KDE_DEPRECATED;
+
+ /**
+ * @deprecated
+ * Do not use this method. It is included for compatibility reasons.
+ *
+ * This method returns the contents rectangle of the work area. Place
+ * your widgets inside this rectangle, and use it to set up
+ * their geometry. Be careful: The rectangle is only valid after
+ * resizing the dialog, as it is a result of the resizing process.
+ * If you need the "overhead" the dialog needs for its elements,
+ * use getBorderWidths().
+ */
+ QRect getContentsRect() const KDE_DEPRECATED;
+
+ /**
+ * Calculate the size hint for the dialog.
+ *
+ * With this method it is easy to calculate a size hint for a
+ * dialog derived from KDialogBase if you know the width and height of
+ * the elements you add to the widget. The rectangle returned is
+ * calculated so that all elements exactly fit into it. Thus, you may
+ * set it as a minimum size for the resulting dialog.
+ *
+ * You should not need to use this method and never if you use one of
+ * the predefined shapes.
+ *
+ * @param w The width of you special widget.
+ * @param h The height of you special widget.
+ * @return The minimum width and height of the dialog using @p w and @p h
+ * as the size of the main widget.
+ */
+ QSize calculateSize( int w, int h ) const;
+
+ /**
+ * Returns the help link text.
+ *
+ * If no text has been defined,
+ * "Get help..." (internationalized) is returned.
+ *
+ * @return The help link text.
+ */
+ QString helpLinkText() const;
+
+ /**
+ * Returns the action button that corresponds to the @p id.
+ *
+ * Normally
+ * you should not use this function. @em Never delete the object returned
+ * by this function. See also enableButton(), showButton(),
+ * setButtonTip(), setButtonWhatsThis(), and setButtonText().
+ *
+ * @param id Integer identifier of the button.
+ * @return The action button or 0 if the button does not exists.
+ *
+ * FIXME KDE 4: Return the actual KPushButton instead of QPushButton (Martijn)
+ */
+ QPushButton *actionButton( ButtonCode id );
+
+ public slots:
+ /**
+ * Enable or disable (gray out) a general action button.
+ *
+ * @param id Button identifier.
+ * @param state @p true enables the button(s).
+ */
+ void enableButton( ButtonCode id, bool state );
+
+ /**
+ * Enable or disable (gray out) the OK button.
+ *
+ * @param state @p true enables the button.
+ */
+ void enableButtonOK( bool state );
+
+ /**
+ * Enable or disable (gray out) the Apply button.
+ *
+ * @param state true enables the button.
+ */
+ void enableButtonApply( bool state );
+
+ /**
+ * Enable or disable (gray out) the Cancel button.
+ *
+ * @param state true enables the button.
+ */
+ void enableButtonCancel( bool state );
+
+ /**
+ * Display or hide the help link area on the top of the dialog.
+ *
+ * @param state @p true will display the area.
+ */
+ void enableLinkedHelp( bool state );
+
+ /**
+ * Destruct the Dialog delayed.
+ *
+ * You can call this function from
+ * slots like closeClicked() and hidden().
+ * You should not use the dialog any more after
+ * calling this function.
+ * @since 3.1
+ */
+ void delayedDestruct();
+
+ /**
+ * Sets the text that is shown as the linked text.
+ *
+ * If text is empty,
+ * the text "Get help..." (internationalized) is used instead.
+ *
+ * @param text The link text.
+ */
+ void setHelpLinkText( const QString &text );
+
+ /**
+ * Sets the help path and topic.
+ *
+ * @param anchor Defined anchor in your docbook sources
+ * @param appname Defines the appname the help belongs to
+ * If empty it's the current one
+ *
+ * @note The help button works differently for the class
+ * KCMultiDialog, so it does not make sense to call this
+ * function for Dialogs of that type. See
+ * KCMultiDialog::slotHelp() for more information.
+ */
+ void setHelp( const QString &anchor,
+ const QString &appname = QString::null );
+
+ /**
+ * Connected to help link label.
+ */
+ void helpClickedSlot( const QString & );
+
+ /**
+ * Sets the status of the Details button.
+ */
+ void setDetails(bool showDetails);
+
+ /**
+ * Sets the widget that gets shown when "Details" is enabled.
+ *
+ * The dialog takes over ownership of the widget.
+ * Any previously set widget gets deleted.
+ */
+ void setDetailsWidget(QWidget *detailsWidget);
+
+ /**
+ * This method is called automatically whenever the background has
+ * changed. You do not need to use this method.
+ */
+ void updateBackground();
+
+ /**
+ * Force closing the dialog, setting its result code to the one Esc would set.
+ * You shouldn't use this, generally (let the user make his choice!)
+ * but it can be useful when you need to make a choice after a timeout
+ * has happened, or when the parent widget has to go somewhere else
+ * (e.g. html redirections).
+ * @since 3.1
+ */
+ void cancel();
+
+ signals:
+ /**
+ * The Help button was pressed. This signal is only emitted if
+ * slotHelp() is not replaced.
+ */
+ void helpClicked();
+
+ /**
+ * The Default button was pressed. This signal is only emitted if
+ * slotDefault() is not replaced.
+ */
+ void defaultClicked();
+
+
+ /**
+ * The User3 button was pressed. This signal is only emitted if
+ * slotUser3() is not replaced.
+ */
+ void user3Clicked();
+
+ /**
+ * The User2 button was pressed. This signal is only emitted if
+ * slotUser2() is not replaced.
+ */
+ void user2Clicked();
+
+ /**
+ * The User1 button was pressed. This signal is only emitted if
+ * slotUser1() is not replaced.
+ */
+ void user1Clicked();
+
+ /**
+ * The Apply button was pressed. This signal is only emitted if
+ * slotApply() is not replaced.
+ */
+ void applyClicked();
+
+ /**
+ * The Try button was pressed. This signal is only emitted if
+ * slotTry() is not replaced.
+ */
+ void tryClicked();
+
+ /**
+ * The OK button was pressed. This signal is only emitted if
+ * slotOk() is not replaced.
+ */
+ void okClicked();
+
+ /**
+ * The Yes button was pressed. This signal is only emitted if
+ * slotYes() is not replaced.
+ */
+ void yesClicked();
+
+ /**
+ * The No button was pressed. This signal is only emitted if
+ * slotNo() is not replaced.
+ */
+ void noClicked();
+
+ /**
+ * The Cancel button was pressed. This signal is only emitted if
+ * slotCancel() is not replaced.
+ */
+ void cancelClicked();
+
+ /**
+ * The Close button was pressed. This signal is only emitted if
+ * slotClose() is not replaced.
+ */
+ void closeClicked();
+
+ /**
+ * Do not use this signal. Is is kept for compatibility reasons.
+ * @deprecated Use applyClicked() instead.
+ */
+ void apply();
+
+ /**
+ * The background tile has changed.
+ */
+ void backgroundChanged();
+
+ /**
+ * The dialog is about to be hidden.
+ *
+ * A dialog is hidden after a user clicks a button that ends
+ * the dialog or when the user switches to another desktop or
+ * minimizes the dialog.
+ */
+ void hidden();
+
+ /**
+ * The dialog has finished.
+ *
+ * A dialog emits finished after a user clicks a button that ends
+ * the dialog.
+ *
+ * This signal is also emitted when you call hide()
+ *
+ * If you have stored a pointer to the
+ * dialog do @em not try to delete the pointer in the slot that is
+ * connected to this signal.
+ *
+ * You should use delayedDestruct() instead.
+ */
+ void finished();
+
+ /**
+ * The detailsWidget is about to get shown. This is your last chance
+ * to call setDetailsWidget if you haven't done so yet.
+ */
+ void aboutToShowDetails();
+
+ /**
+ * A page is about to be shown. This signal is only emitted for the TreeList
+ * and IconList faces.
+ */
+ void aboutToShowPage(QWidget *page);
+
+ protected:
+ /**
+ * Maps some keys to the actions buttons. F1 is mapped to the Help
+ * button if present and Escape to the Cancel or Close if present. The
+ * button action event is animated.
+ */
+ virtual void keyPressEvent( QKeyEvent *e );
+
+ /**
+ * Emits the #hidden signal. You can connect to that signal to
+ * detect when a dialog has been closed.
+ */
+ virtual void hideEvent( QHideEvent * );
+
+ /**
+ * Detects when a dialog is being closed from the window manager
+ * controls. If the Cancel or Close button is present then the button
+ * is activated. Otherwise standard QDialog behavior
+ * will take place.
+ */
+ virtual void closeEvent( QCloseEvent *e );
+
+ protected slots:
+ /**
+ * Activated when the Help button has been clicked. If a help
+ * text has been defined, the help system will be activated.
+ */
+ virtual void slotHelp();
+
+ /**
+ * Activated when the Default button has been clicked.
+ */
+ virtual void slotDefault();
+
+ /**
+ * Activated when the Details button has been clicked.
+ * @see detailsClicked(bool)
+ */
+ virtual void slotDetails();
+
+ /**
+ * Activated when the User3 button has been clicked.
+ */
+ virtual void slotUser3();
+
+ /**
+ * Activated when the User2 button has been clicked.
+ */
+ virtual void slotUser2();
+
+ /**
+ * Activated when the User1 button has been clicked.
+ */
+ virtual void slotUser1();
+
+ /**
+ * Activated when the Ok button has been clicked. The
+ * QDialog::accept() is activated.
+ */
+ virtual void slotOk();
+
+ /**
+ * Activated when the Apply button has been clicked.
+ */
+ virtual void slotApply();
+
+ /**
+ * Activated when the Try button has been clicked.
+ */
+ virtual void slotTry();
+
+ /**
+ * Activated when the Yes button has been clicked. The
+ * QDialog::done( Yes ) is activated.
+ */
+ virtual void slotYes();
+
+ /**
+ * Activated when the Yes button has been clicked. The
+ * QDialog::done( No ) is activated.
+ */
+ virtual void slotNo();
+
+ /**
+ * Activated when the Cancel button has been clicked. The
+ * QDialog::reject() is activated in regular mode and
+ * QDialog::done( Cancel ) when in message box mode.
+ */
+ virtual void slotCancel();
+
+ /**
+ * Activated when the Close button has been clicked. The
+ * QDialog::reject() is activated.
+ */
+ virtual void slotClose();
+
+ /**
+ * @deprecated
+ * Do not use this slot. Is is kept for compatibility reasons.
+ * Activated when the Apply button has been clicked
+ */
+ virtual void applyPressed();
+
+ /**
+ * Updates the margins and spacings.
+ */
+ void updateGeometry();
+
+ /**
+ * Deletes the dialog immediately. If you want to delete the dialog
+ * delayed use delayedDestruct() or QObject::deleteLater().
+ *
+ * Attention: Do no use connect this slot to signals from user
+ * actions!
+ */
+ void slotDelayedDestruct();
+
+ private:
+ /**
+ * Prepares the layout that manages the widgets of the dialog
+ */
+ void setupLayout();
+
+ /**
+ * Prepares a relay that is used to send signals between
+ * all KDialogBase instances of a program. Should only be used in the
+ * constructor.
+ */
+ void makeRelay();
+
+ /**
+ * Makes the button box and all the buttons in it. This method must
+ * only be ran once from the constructor.
+ *
+ * @param buttonMask Specifies what buttons will be made.
+ * @param defaultButton Specifies which button will be marked as
+ * the default. Use ButtonCode::NoDefault to indicate that no button
+ * should be marked as the default button.
+ * @param user1 User button1 item.
+ * @param user2 User button2 item.
+ * @param user2 User button3 item.
+ */
+ void makeButtonBox( int mask, ButtonCode defaultButton,
+ const KGuiItem &user1 = KGuiItem(),
+ const KGuiItem &user2 = KGuiItem(),
+ const KGuiItem &user3 = KGuiItem() );
+
+ /**
+ * Sets the action button that is marked as default and has focus.
+ *
+ * @param p The action button.
+ * @param isDefault If true, make the button default
+ * @param isFocus If true, give the button focus.
+ */
+ void setButtonFocus( QPushButton *p, bool isDefault, bool isFocus );
+
+ /**
+ * Prints an error message using qDebug if makeMainWidget ,
+ * makeVBoxMainWidget , makeHBoxMainWidget or
+ * makeGridMainWidget failed.
+ */
+ void printMakeMainWidgetError();
+
+ private slots:
+ /**
+ * Sets the action button order according to the 'style'.
+ *
+ * @param style The style index.
+ */
+ void setButtonStyle( int style );
+
+
+ private:
+ QBoxLayout *mTopLayout;
+ QWidget *mMainWidget;
+ KURLLabel *mUrlHelp;
+ KJanusWidget *mJanus;
+ KSeparator *mActionSep;
+
+ bool mIsActivated;
+
+ QString mAnchor;
+ QString mHelpApp;
+ QString mHelpLinkText;
+
+ static KDialogBaseTile *mTile;
+ bool mShowTile;
+
+ bool mMessageBoxMode;
+ int mButtonOrientation;
+ ButtonCode mEscapeButton;
+
+ protected:
+ virtual void virtual_hook( int id, void* data );
+ private:
+ class KDialogBasePrivate;
+ KDialogBasePrivate* const d;
+};
+
+#endif