kdeui/kdialog.h

   1 /*  This file is part of the KDE Libraries
   2  *  Copyright (C) 1998 Thomas Tanghus (tanghus@earthling.net)
   3  *  Additions 1999-2000 by Espen Sand (espen@kde.org)
   4  *
   5  *  This library is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Library General Public
   7  *  License as published by the Free Software Foundation; either
   8  *  version 2 of the License, or (at your option) any later version.
   9  *
  10  *  This library is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  Library General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Library General Public License
  16  *  along with this library; see the file COPYING.LIB.  If not, write to
  17  *  the Free Software Foundation, Inc., 51 Franklin Steet, Fifth Floor,
  18  *  Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef _KDIALOG_H_
  22 #define _KDIALOG_H_
  23
  24 class QLayoutItem;
  25
  26 #include <qdialog.h>
  27
  28 #include <kdelibs_export.h>
  29
  30 /**
  31  * Dialog with extended non-modal support and methods for %KDE standard
  32  * compliance.
  33  *
  34  * Generally, you should not use this class directly, but KDialogBase
  35  * which inherits KDialog.
  36  *
  37  * If the dialog is non-modal and has a parent, the default keybindings
  38  * (@p escape = @p reject(), @p enter = @p accept(), etc.) are disabled.
  39  *
  40  * The marginHint() and spacingHint() sizes shall be used
  41  * whenever you layout the interior of a dialog. One special note. If
  42  * you make your own action buttons (OK, Cancel etc), the space
  43  * beteween the buttons shall be spacingHint(), whereas the space
  44  * above, below, to the right and to the left shall be marginHint().
  45  * If you add a separator line above the buttons, there shall be a
  46  * marginHint() between the buttons and the separator and a
  47  * marginHint() above the separator as well.
  48  *
  49  * @see KDialogBase
  50  * @author Thomas Tanghus <tanghus@earthling.net>, Espen Sand <espensa@online.no>
  51  */
  52 class KDEUI_EXPORT KDialog : public QDialog
  53 {
  54   Q_OBJECT
  55
  56   public:
  57
  58     /**
  59      * Constructor.
  60      *
  61      * Takes the same arguments as QDialog.
  62      */
  63     KDialog(QWidget *parent = 0, const char *name = 0,
  64             bool modal = false, WFlags f = 0);
  65
  66     /**
  67      * Return the number of pixels you shall use between a
  68      * dialog edge and the outermost widget(s) according to the KDE standard.
  69      **/
  70     static int marginHint();
  71
  72     /**
  73      * Return the number of pixels you shall use between
  74      * widgets inside a dialog according to the KDE standard.
  75      */
  76     static int spacingHint();
  77
  78     /**
  79      * Resize every layout manager used in @p widget and its nested children.
  80      *
  81      * @param widget The widget used.
  82      * @param margin The new layout margin.
  83      * @param spacing The new layout spacing.
  84      */
  85     static void resizeLayout( QWidget *widget, int margin, int spacing );
  86
  87     /**
  88      * Resize every layout associated with @p lay and its children.
  89      *
  90      * @param lay layout to be resized
  91      * @param margin The new layout margin
  92      * @param spacing The new layout spacing
  93      */
  94     static void resizeLayout( QLayoutItem *lay, int margin, int spacing );
  95
  96     /**
  97      * Centers @p widget on the desktop, taking multi-head setups into
  98      * account. If @p screen is -1, @p widget will be centered on its
  99      * current screen (if it was shown already) or on the primary screen.
 100      * If @p screen is -3, @p widget will be centered on the screen that
 101      * currently contains the mouse pointer.
 102      * @p screen will be ignored if a merged display (like Xinerama) is not
 103      * in use, or merged display placement is not enabled in kdeglobals.
 104      * @since 3.1
 105      */
 106     static void centerOnScreen( QWidget *widget, int screen = -1 );
 107
 108     /**
 109      * Places @p widget so that it doesn't cover a certain @p area of the screen.
 110      * This is typically used by the "find dialog" so that the match it finds can
 111      * be read.
 112      * For @p screen, see centerOnScreen
 113      * @return true on success (widget doesn't cover area anymore, or never did),
 114      * false on failure (not enough space found)
 115      * @since 3.2
 116      */
 117     static bool avoidArea( QWidget *widget, const QRect& area, int screen = -1 );
 118
 119   public slots:
 120     /**
 121      * If the dialog starts with focus in a QLineEdit child,
 122      * then call selectAll() on the child.
 123      */
 124     virtual void polish();
 125
 126     /**
 127      * Make a KDE compliant caption.
 128      *
 129      * @param caption Your caption. Do @p not include the application name
 130      * in this string. It will be added automatically according to the KDE
 131      * standard.
 132      */
 133     virtual void setCaption( const QString &caption );
 134
 135     /**
 136      * Make a plain caption without any modifications.
 137      *
 138      * @param caption Your caption. This is the string that will be
 139      * displayed in the window title.
 140      */
 141     virtual void setPlainCaption( const QString &caption );
 142
 143
 144   protected:
 145     /**
 146      * @internal
 147      */
 148     virtual void keyPressEvent(QKeyEvent*);
 149
 150
 151    signals:
 152     /**
 153      * Emitted when the margin size and/or spacing size
 154      * have changed.
 155      *
 156      * Use marginHint() and spacingHint() in your slot
 157      * to get the new values.
 158      */
 159     void layoutHintChanged();
 160
 161   private:
 162     static const int mMarginSize;
 163     static const int mSpacingSize;
 164
 165   protected:
 166     virtual void virtual_hook( int id, void* data );
 167   private:
 168     class KDialogPrivate;
 169     KDialogPrivate* const d;
 170
 171 };
 172
 173
 174  /**
 175   * \brief Queue for showing modal dialogs one after the other.
 176   *
 177   * This is useful if you want to show a modal dialog but are not in the
 178   * position to start a new event loop at that point in your code.
 179   *
 180   * The disadvantage is that you will not be able to get any information from
 181   * the dialog, so it can currently only be used for simple dialogs.
 182   *
 183   * You probably want to use KMessageBox::queueMessageBox() instead
 184   * of this class directly.
 185   *
 186   * @author Waldo Bastian <bastian@kde.org>
 187   */
 188 class KDialogQueuePrivate;
 189 class KDEUI_EXPORT KDialogQueue : public QObject
 190 {
 191       Q_OBJECT
 192
 193 public:
 194
 195       static void queueDialog(QDialog *);
 196
 197       ~KDialogQueue();
 198
 199 protected:
 200       KDialogQueue();
 201       static KDialogQueue *self();
 202
 203 private slots:
 204       void slotShowQueuedDialog();
 205
 206 protected:
 207       KDialogQueuePrivate* const d;
 208       static KDialogQueue *_self;
 209 };
 210
 211 #endif // __KDIALOG_H