kdelibs/kdeui/dialogs/kdialog.h

/*  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 KDialogPrivate;

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

#include <QtGui/QMenu>
#include <QtGui/QDialog>

/**
 * @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
 *
 * 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.
 *
 * By default, the dialog is non-modal.
 *
 * <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 emit a signal, so you can choose to connect that signal.
 *
 * The default action of the Help button will open the help system if you have
 * provided a path to the help text.
 * The default action of Ok and Cancel will run QDialog::accept() and QDialog::reject(),
 * which you can override by reimplementing slotButtonClicked(). The default
 * action of the Close button will close the dialog.
 *
 * Note that the KDialog will animate a button press
 * when the user presses Escape. The button that is enabled is either Cancel,
 * Close or the button that is defined by setEscapeButton().
 * Your custom dialog code should reimplement the keyPressEvent and
 * animate the cancel button so that the dialog behaves like regular
 * dialogs.
 *
 * <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
 * setButtonsOrientation() 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).
 *
 * <b>Standard compliance:</b>\n
 *
 * The marginHint() and spacingHint() sizes shall be used
 * whenever you lay out the interior of a dialog. One special note. If
 * you make your own action buttons (OK, Cancel etc), the space
 * between the buttons shall be spacingHint(), whereas the space
 * above, below, to the right and to the left shall be marginHint().
 * If you add a separator line above the buttons, there shall be a
 * marginHint() between the buttons and the separator and a
 * marginHint() above the separator as well.
 *
 * <b>Example:</b>\n
 *
 * \code
 *   KDialog *dialog = new KDialog(this);
 *   dialog->setCaption("My title");
 *   dialog->setButtons(KDialog::Ok | KDialog::Cancel | KDialog::Apply);
 *
 *   FooWidget *widget = new FooWidget(dialog);
 *   dialog->setMainWidget(widget);
 *   connect(dialog, SIGNAL(applyClicked()), widget, SLOT(save()));
 *   connect(dialog, SIGNAL(okClicked()), widget, SLOT(save()));
 *   connect(widget, SIGNAL(changed(bool)), dialog, SLOT(enableButtonApply(bool)));
 *
 *   dialog->enableButtonApply( false );
 *   dialog->show();
 * \endcode
 *
 * \image html kdialog.png "KDE Dialog example"
 *
 * This class can be used in many ways. Note that most KDE ui widgets
 * and many of KDE core applications use the KDialog so for more
 * inspiration you should study the code for these.
 *
 *
 * @see KPageDialog
 * @author Thomas Tanghus <tanghus@earthling.net>
 * @author Espen Sand <espensa@online.no>
 * @author Mirko Boehm <mirko@kde.org>
 * @author Olivier Goffart <ogoffart at kde.org>
 * @author Tobias Koenig <tokoe@kde.org>
 */
class KDEUI_EXPORT KDialog : public QDialog
{
    Q_OBJECT
    Q_ENUMS(ButtonCode)
    Q_DECLARE_PRIVATE(KDialog)
public:
    enum ButtonCode
    {
        None    = 0x00000000,
        Help    = 0x00000001, ///< Show Help button. (this button will run the help set with setHelp)
        Default = 0x00000002, ///< Show Default button.
        Ok      = 0x00000004, ///< Show Ok button. (this button accept()s the dialog; result set to QDialog::Accepted)
        Apply   = 0x00000008, ///< Show Apply button.
        Try     = 0x00000010, ///< Show Try button.
        Cancel  = 0x00000020, ///< Show Cancel-button. (this button reject()s the dialog; result set to QDialog::Rejected)
        Close   = 0x00000040, ///< Show Close-button. (this button closes the dialog)
        No      = 0x00000080, ///< Show No button. (this button closes the dialog and sets the result to KDialog::No)
        Yes     = 0x00000100, ///< Show Yes button. (this button closes the dialog and sets the result to KDialog::Yes)
        Reset   = 0x00000200, ///< Show Reset button
        Details = 0x00000400, ///< Show Details button. (this button will show the detail widget set with setDetailsWidget)
        User1   = 0x00001000, ///< Show User defined button 1.
        User2   = 0x00002000, ///< Show User defined button 2.
        User3   = 0x00004000, ///< Show User defined button 3.
        NoDefault = 0x00008000 ///< Used when specifying a default button; indicates that no button should be marked by default.
    };
    // 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:
    /**
     * Creates a dialog.
     *
     * @param parent The parent of the dialog.
     * @param flags  The widget flags passed to the QDialog constructor
     */
    explicit KDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = 0);

    /**
     * Destroys the dialog.
     */
    ~KDialog();

    /**
     * Creates (or recreates) the button box and all the buttons in it.
     *
     * Note that some combinations are not possible. That means, you can't
     * have the following pairs of buttons in a dialog:
     * - Default and Details
     * - Cancel and Close
     * - Ok and Try
     *
     * This will reset all default KGuiItem of all button.
     *
     * @param buttonMask Specifies what buttons will be made.
     */
    void setButtons(ButtonCodes buttonMask);

    /**
     * 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 setButtonsOrientation(Qt::Orientation orientation);

    /**
     * Sets the button that will be activated when the Escape key
     * is pressed.
     *
     * 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);

    /**
     * Sets the button that will be activated when the Enter key
     * is pressed.
     *
     * By default, this is the Ok button if it is present
     *
     * @param id The button code.
     */
    void setDefaultButton(ButtonCode id);

    /**
     * Returns the button code of the default button,
     * or NoDefault if there is no default button.
     */
    ButtonCode defaultButton() const;

    /**
     * Hide or display the separator line drawn between the action
     * buttons an the main widget.
     */
    void showButtonSeparator(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);

    /**
     * Sets the text of any button.
     *
     * @param id The button identifier.
     * @param text Button text.
     */
    void setButtonText(ButtonCode id, const QString &text);

    /**
     * Returns the text of any button.
     */
    QString buttonText(ButtonCode id) const;

    /**
     * Sets the icon of any button.
     *
     * @param id The button identifier.
     * @param icon Button icon.
     */
    void setButtonIcon(ButtonCode id, const KIcon &icon);

    /**
     * Returns the icon of any button.
     */
    KIcon buttonIcon(ButtonCode id) const;

    /**
     * Sets the tooltip text of any button.
     *
     * @param id The button identifier.
     * @param text Button text.
     */
    void setButtonToolTip(ButtonCode id, const QString &text);

    /**
     * Returns the tooltip of any button.
     */
    QString buttonToolTip(ButtonCode id) const;

    /**
     * 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);

    /**
     * Returns the "What's this?" text of any button.
     */
    QString buttonWhatsThis(ButtonCode id) const;

    /**
     * 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.
     */
    void setButtonGuiItem(ButtonCode id, const KGuiItem &item);

    /**
     * Sets the menu of any button.
     *
     * @param id The button identifier.
     * @param menu The menu.
     * @param popupmode Choose if KPushButton setMenu or setDelayedMenu is used
     */
    void setButtonMenu(ButtonCode id, QMenu *menu, ButtonPopupMode popupmode = InstantPopup);

    /**
     * Sets the focus to the button of the passed @p id.
     */
    void setButtonFocus(ButtonCode id);

    /**
     * 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 size Startup size.
     */
    void setInitialSize(const QSize &size);

    /**
     * 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 size  Size added to minimum size.
     */
    void incrementInitialSize(const QSize &size);

    /**
     * Restores the dialog's size from the configuration according to
     * the screen size.
     *
     * @note the group must be set before calling
     *
     * @param config The config group to read from.
     */
    void restoreDialogSize(const KConfigGroup &config);

    /**
     * Saves the dialog's size dependent on the screen dimension either to the
     * global or application config file.
     *
     * @note the group must be set before calling
     *
     * @param config The config group to read from.
     * @param options passed to KConfigGroup::writeEntry()
     */
    void saveDialogSize(KConfigGroup &config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal) const;

    /**
     * Returns the help link text.
     *
     *  If no text has been defined,
     * "Get help..." (internationalized) is returned.
     *
     * @return The help link text.
     *
     * @see enableLinkedHelp()
     * @see setHelpLinkText()
     * @see setHelp()
     */
    QString helpLinkText() const;

    /**
     * Returns whether any button is enabled.
     */
    bool isButtonEnabled(ButtonCode id) const;

    /**
     * Returns the 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(), setButtonGuiItem().
     *
     * @param id Identifier of the button.
     * @return The button or 0 if the button does not exist.
     */
    KPushButton* button(ButtonCode id) const;

    /**
     * Returns the number of pixels that should be used between a
     * dialog edge and the outermost widget(s) according to the KDE standard.
     *
     * @deprecated Use the style's pixelMetric() function to query individual margins.
     * Different platforms may use different values for the four margins.
     */
    static int marginHint();

    /**
     * Returns the number of pixels that should be used between
     * widgets inside a dialog according to the KDE standard.
     *
     * @deprecated Use the style's layoutSpacing() function to query individual spacings.
     * Different platforms may use different values depending on widget types and pairs.
     */
    static int spacingHint();

    /**
     * Returns the number of pixels that should be used to visually
     * separate groups of related options in a dialog according to
     * the KDE standard.
     * @since 4.2
     */
    static int groupSpacingHint();

    /**
     * @enum StandardCaptionFlag
     * Used to specify how to construct a window caption
     *
     * @value AppName Indicates that the method shall include
     * the application name when making the caption string.
     * @value Modified Causes a 'modified' sign will be included in the
     * returned string. This is useful when indicating that a file is
     * modified, i.e., it contains data that has not been saved.
     * @value HIGCompliant The base minimum flags required to align a
     * caption with the KDE Human Interface Guidelines
     */
    enum CaptionFlag
    {
        NoCaptionFlags = 0,
        AppNameCaption = 1,
        ModifiedCaption = 2,
        HIGCompliantCaption = AppNameCaption
    };
    Q_DECLARE_FLAGS(CaptionFlags, CaptionFlag)

    /**
     * Builds a caption that contains the application name along with the
     * userCaption using a standard layout.
     *
     * To make a compliant caption for your window, simply do:
     * @p setWindowTitle(KDialog::makeStandardCaption(yourCaption));
     *
     * To ensure that the caption is appropriate to the desktop in which the
     * application is running, pass in a pointer to the window the caption will
     * be applied to.
     *
     * If using a KDialog or KMainWindow subclass, call setCaption instead and
     * an appropraite standard caption will be created for you
     *
     * @param userCaption The caption string you want to display in the
     * window caption area. Do not include the application name!
     * @param window a pointer to the window this application will apply to
     * @param flags
     * @return the created caption
     */
    static QString makeStandardCaption(const QString &userCaption,
                                       QWidget* window = nullptr,
                                       CaptionFlags flags = HIGCompliantCaption);

    /**
     * Centers @p widget on the desktop, taking multi-head setups into
     * account. If @p screen is -1, @p widget will be centered on its
     * current screen (if it was shown already) or on the primary screen.
     * If @p screen is -3, @p widget will be centered on the screen that
     * currently contains the mouse pointer.
     * @p screen will be ignored if a merged display (like Xinerama) is not
     * in use, or merged display placement is not enabled in kdeglobals.
     */
    static void centerOnScreen(QWidget *widget, int screen = -1);

    /**
     * Places @p widget so that it doesn't cover a certain @p area of the screen.
     * This is typically used by the "find dialog" so that the match it finds can
     * be read.
     * For @p screen, see centerOnScreen
     * @return true on success (widget doesn't cover area anymore, or never did),
     * false on failure (not enough space found)
     */
    static bool avoidArea(QWidget *widget, const QRect& area, int screen = -1);

    /**
     * Sets the main widget of the dialog.
     */
    void setMainWidget(QWidget *widget);

    /**
     * @return The current main widget. Will create a QWidget as the mainWidget
     * if none was set before. This way you can write
     * \code
     *   ui.setupUi(mainWidget());
     * \endcode
     * when using designer.
     */
    QWidget *mainWidget();

    /**
     * Reimplemented from QDialog.
     */
    virtual QSize sizeHint() const;

    /**
     * Reimplemented from QDialog.
     */
    virtual QSize minimumSizeHint() const;

    /**
     * Allow embedding the dialogs based on KDialog into a graphics view. By default embedding is not allowed, dialogs
     * will appear as separate windows.
     * @since 4.6
     */
    static void setAllowEmbeddingInGraphicsView(bool allowEmbedding);

public Q_SLOTS:
    /**
     * Make a KDE compliant caption.
     *
     * @param caption Your caption. Do @p not include the application name
     * in this string. It will be added automatically according to the KDE
     * standard.
     */
    virtual void setCaption(const QString &caption);

    /**
     * Makes a KDE compliant caption.
     *
     * @param caption Your caption. @em Do @em not include the application name
     * in this string. It will be added automatically according to the KDE
     * standard.
     * @param modified Specify whether the document is modified. This displays
     * an additional sign in the title bar, usually "**".
     */
    virtual void setCaption(const QString &caption, bool modified);

    /**
     * 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.
     *
     * @see helpLinkText()
     * @see setHelpLinkText()
     * @see setHelp()
     */
    void enableLinkedHelp(bool state);

    /**
     * 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.
     *
     * @see helpLinkText()
     * @see enableLinkedHelp()
     * @see setHelp()
     */
    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());

    /**
     * Returns the status of the Details button.
     */
    bool isDetailsWidgetVisible() const;

    /**
     * Sets the status of the Details button.
     */
    void setDetailsWidgetVisible(bool visible);

    /**
     * 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);

    /**
     * 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.
     */
    void delayedDestruct();

Q_SIGNALS:
    /**
     * The Help button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void helpClicked();

    /**
     * The Default button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void defaultClicked();

    /**
     * The Reset button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void resetClicked();

    /**
     * The User3 button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void user3Clicked();

    /**
     * The User2 button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void user2Clicked();

    /**
     * The User1 button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void user1Clicked();

    /**
     * The Apply button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void applyClicked();

    /**
     * The Try button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void tryClicked();

    /**
     * The OK button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void okClicked();

    /**
     * The Yes button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void yesClicked();

    /**
     * The No button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void noClicked();

    /**
     * The Cancel button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void cancelClicked();

    /**
     * The Close button was pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     */
    void closeClicked();

    /**
     * A button has been pressed. This signal is only emitted if
     * slotButtonClicked() is not replaced
     * @param button is the code of the pressed button.
     */
    void buttonClicked(KDialog::ButtonCode button);

    /**
     * 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 deleteLater() 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();

protected:
    /**
     * Emits the #hidden signal. You can connect to that signal to
     * detect when a dialog has been closed.
     */
    virtual void hideEvent(QHideEvent *event);

    /**
     * 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 *event);

    /**
     * @internal
     */
    virtual void keyPressEvent(QKeyEvent *event);

protected Q_SLOTS:
    /**
     * Activated when the button @p button is clicked
     *
     * Sample that shows how to catch and handle button clicks within
     * an own dialog;
     * @code
     * class MyDialog : public KDialog {
     *     protected Q_SLOTS:
     *         virtual void slotButtonClicked(int button) {
     *             if (button == KDialog::Ok)
     *                 accept();
     *             else
     *                 KDialog::slotButtonClicked(button);
     *         }
     * }
     * @endcode
     *
     * @param button is the type @a KDialog::ButtonCode
     */
    virtual void slotButtonClicked(int button);

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