kdialog.h

Go to the documentation of this file.

/*  This file is part of the KDE Libraries
 *  Copyright (C) 1998 Thomas Tanghus (tanghus@earthling.net)
 *  Additions 1999-2000 by Espen Sand (espen@kde.org)
 *                      and Holger Freyther <freyther@kde.org>
 *            2005-2009 Olivier Goffart <ogoffart @ kde.org>
 *            2006      Tobias Koenig <tokoe@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_H
#define KDIALOG_H

class KPushButton;
class QMenu;
class KDialogPrivate;

#include <kdeui_export.h>
#include <kconfiggroup.h>
#include <kguiitem.h>

#include <QtGui/QDialog>

class KDEUI_EXPORT KDialog : public QDialog //krazy:exclude=qclasses
{
  Q_OBJECT
  Q_ENUMS(ButtonCode)
    Q_DECLARE_PRIVATE(KDialog)

  public:

    enum ButtonCode
    {
      None    = 0x00000000,
      Help    = 0x00000001, 
      Default = 0x00000002, 
      Ok      = 0x00000004, 
      Apply   = 0x00000008, 
      Try     = 0x00000010, 
      Cancel  = 0x00000020, 
      Close   = 0x00000040, 
      No      = 0x00000080, 
      Yes     = 0x00000100, 
      Reset   = 0x00000200, 
      Details = 0x00000400, 
      User1   = 0x00001000, 
      User2   = 0x00002000, 
      User3   = 0x00004000, 
      NoDefault = 0x00008000 
    };
    // TODO KDE5: remove NoDefault and use the value None instead
    Q_DECLARE_FLAGS(ButtonCodes, ButtonCode)

    enum ButtonPopupMode
    {
      InstantPopup = 0,
      DelayedPopup = 1
    };
    Q_DECLARE_FLAGS(ButtonPopupModes, ButtonPopupMode)

  public:
    explicit KDialog( QWidget *parent = 0, Qt::WindowFlags flags = 0 );

    ~KDialog();

    void setButtons( ButtonCodes buttonMask );

    void setButtonsOrientation( Qt::Orientation orientation );

    void setEscapeButton( ButtonCode id );

    void setDefaultButton( ButtonCode id );

    ButtonCode defaultButton() const;

    void showButtonSeparator( bool state );

    void showButton( ButtonCode id, bool state );

    void setButtonText( ButtonCode id, const QString &text );

    QString buttonText( ButtonCode id ) const;

    void setButtonIcon( ButtonCode id, const KIcon &icon );

    KIcon buttonIcon( ButtonCode id ) const;

    void setButtonToolTip( ButtonCode id, const QString &text );

    QString buttonToolTip( ButtonCode id ) const;

    void setButtonWhatsThis( ButtonCode id, const QString &text );

    QString buttonWhatsThis( ButtonCode id ) const;

    void setButtonGuiItem( ButtonCode id, const KGuiItem &item );

    void setButtonMenu( ButtonCode id, QMenu *menu, ButtonPopupMode popupmode=InstantPopup);

    void setButtonFocus( ButtonCode id );

    void setInitialSize( const QSize &size );

    void incrementInitialSize( const QSize &size );

    void restoreDialogSize( const KConfigGroup& config ) ;

    void saveDialogSize( KConfigGroup& config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal ) const;

    QString helpLinkText() const;

    bool isButtonEnabled( ButtonCode id ) const;

    KPushButton* button( ButtonCode id ) const;

    static int marginHint();

    static int spacingHint();

    static int groupSpacingHint();

    enum CaptionFlag
    {
        NoCaptionFlags = 0,
        AppNameCaption = 1,
        ModifiedCaption = 2,
        HIGCompliantCaption = AppNameCaption
    };
    Q_DECLARE_FLAGS(CaptionFlags, CaptionFlag)

    
    static QString makeStandardCaption( const QString &userCaption,
                                        QWidget* window = 0,
                                        CaptionFlags flags = HIGCompliantCaption );

    static void resizeLayout( QWidget *widget, int margin, int spacing );

    static void resizeLayout( QLayout *lay, int margin, int spacing );

    static void centerOnScreen( QWidget *widget, int screen = -1 );

    static bool avoidArea( QWidget *widget, const QRect& area, int screen = -1 );

    void setMainWidget( QWidget *widget );

    QWidget *mainWidget();

    virtual QSize sizeHint() const;

    virtual QSize minimumSizeHint() const;
    
    static void setAllowEmbeddingInGraphicsView( bool allowEmbedding );

  public Q_SLOTS:
    virtual void setCaption( const QString &caption );

    virtual void setCaption( const QString &caption, bool modified );

    virtual void setPlainCaption( const QString &caption );

    void enableButton( ButtonCode id, bool state );

    void enableButtonOk( bool state );

    void enableButtonApply( bool state );

    void enableButtonCancel( bool state );

    void enableLinkedHelp( bool state );

    void setHelpLinkText( const QString &text );

    void setHelp( const QString &anchor, const QString &appname = QString() );

    bool isDetailsWidgetVisible() const;

    void setDetailsWidgetVisible( bool visible );

    void setDetailsWidget( QWidget *detailsWidget );

    void delayedDestruct();

  Q_SIGNALS:
    void layoutHintChanged();

    void helpClicked();

    void defaultClicked();

    void resetClicked();

    void user3Clicked();

    void user2Clicked();

    void user1Clicked();

    void applyClicked();

    void tryClicked();

    void okClicked();

    void yesClicked();

    void noClicked();

    void cancelClicked();

    void closeClicked();

    void buttonClicked( KDialog::ButtonCode button);

    void hidden();

    void finished();

    void aboutToShowDetails();

  protected:
    virtual void hideEvent( QHideEvent * );

    virtual void closeEvent( QCloseEvent *e );

    virtual void keyPressEvent( QKeyEvent* );

  protected Q_SLOTS:
    virtual void slotButtonClicked(int button);

    void updateGeometry();

    protected:
        KDialog(KDialogPrivate &dd, QWidget *parent, Qt::WindowFlags flags = 0);
        KDialogPrivate *const d_ptr;

    private:
        Q_DISABLE_COPY(KDialog)
        Q_PRIVATE_SLOT(d_ptr, void queuedLayoutUpdate())
        Q_PRIVATE_SLOT(d_ptr, void helpLinkClicked())
};

Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::ButtonCodes)
Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::CaptionFlags)

#endif // KDIALOG_H