KDELibs4Support

kdialog.h
1 /* This file is part of the KDE Libraries
2  * Copyright (C) 1998 Thomas Tanghus ([email protected])
3  * Additions 1999-2000 by Espen Sand ([email protected])
4  * and Holger Freyther <[email protected]>
5  * 2005-2009 Olivier Goffart <ogoffart @ kde.org>
6  * 2006 Tobias Koenig <[email protected]>
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Library General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Library General Public License for more details.
17  *
18  * You should have received a copy of the GNU Library General Public License
19  * along with this library; see the file COPYING.LIB. If not, write to
20  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21  * Boston, MA 02110-1301, USA.
22  */
23 
24 #ifndef KDIALOG_H
25 #define KDIALOG_H
26 
27 class QPushButton;
28 class QMenu;
29 class KDialogPrivate;
30 
31 #include <kdelibs4support_export.h>
32 #include <kconfiggroup.h>
33 #include <kguiitem.h>
34 
35 #include <QDialog>
36 
37 /**
38  * @short A dialog base class with standard buttons and predefined layouts.
39  *
40  * Provides basic functionality needed by nearly all dialogs.
41  *
42  * It offers the standard action buttons you'd expect to find in a
43  * dialog as well as the capability to define at most three configurable
44  * buttons. You can define a main widget that contains your specific
45  * dialog layout
46  *
47  * The class takes care of the geometry management. You only need to define
48  * a minimum size for the widget you want to use as the main widget.
49  *
50  * By default, the dialog is non-modal.
51  *
52  * <b>Standard buttons (action buttons):</b>\n
53  *
54  * You select which buttons should be displayed, but you do not choose the
55  * order in which they are displayed. This ensures a standard interface in
56  * KDE. The button order can be changed, but this ability is only available
57  * for a central KDE control tool. The following buttons are available:
58  * OK, Cancel/Close, Apply/Try, Default, Help and three user definable
59  * buttons: User1, User2 and User3. You must specify the text of the UserN
60  * buttons. Each button emit a signal, so you can choose to connect that signal.
61  *
62  * The default action of the Help button will open the help system if you have
63  * provided a path to the help text.
64  * The default action of Ok and Cancel will run QDialog::accept() and QDialog::reject(),
65  * which you can override by reimplementing slotButtonClicked(). The default
66  * action of the Close button will close the dialog.
67  *
68  * Note that the KDialog will animate a button press
69  * when the user presses Escape. The button that is enabled is either Cancel,
70  * Close or the button that is defined by setEscapeButton().
71  * Your custom dialog code should reimplement the keyPressEvent and
72  * animate the cancel button so that the dialog behaves like regular
73  * dialogs.
74  *
75  * <b>Layout:</b>\n
76  *
77  * The dialog consists of a help area on top (becomes visible if you define
78  * a help path and use enableLinkedHelp()), the main area which is
79  * the built-in dialog face or your own widget in the middle and by default
80  * a button box at the bottom. The button box can also be placed at the
81  * right edge (to the right of the main widget). Use
82  * setButtonsOrientation() to control this behavior. A separator
83  * can be placed above the button box (or to the left when the button box
84  * is at the right edge).
85  *
86  * <b>Standard compliance:</b>\n
87  *
88  * The marginHint() and spacingHint() sizes shall be used
89  * whenever you lay out the interior of a dialog. One special note. If
90  * you make your own action buttons (OK, Cancel etc), the space
91  * between the buttons shall be spacingHint(), whereas the space
92  * above, below, to the right and to the left shall be marginHint().
93  * If you add a separator line above the buttons, there shall be a
94  * marginHint() between the buttons and the separator and a
95  * marginHint() above the separator as well.
96  *
97  * <b>Example:</b>\n
98  *
99  * \code
100  * KDialog *dialog = new KDialog( this );
101  * dialog->setCaption( "My title" );
102  * dialog->setButtons( KDialog::Ok | KDialog::Cancel | KDialog::Apply );
103  *
104  * FooWidget *widget = new FooWidget( dialog );
105  * dialog->setMainWidget( widget );
106  * connect( dialog, SIGNAL( applyClicked() ), widget, SLOT( save() ) );
107  * connect( dialog, SIGNAL( okClicked() ), widget, SLOT( save() ) );
108  * connect( widget, SIGNAL( changed( bool ) ), dialog, SLOT( enableButtonApply( bool ) ) );
109  *
110  * dialog->enableButtonApply( false );
111  * dialog->show();
112  * \endcode
113  *
114  * \image html kdialog.png "KDE Dialog example"
115  *
116  * This class can be used in many ways. Note that most KDE ui widgets
117  * and many of KDE core applications use the KDialog so for more
118  * inspiration you should study the code for these.
119  *
120  *
121  * @see KPageDialog
122  * @author Thomas Tanghus <[email protected]>
123  * @author Espen Sand <[email protected]>
124  * @author Mirko Boehm <[email protected]>
125  * @author Olivier Goffart <ogoffart at kde.org>
126  * @author Tobias Koenig <[email protected]>
127  */
128 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KDialog : public QDialog //krazy:exclude=qclasses
129 {
130  Q_OBJECT
132  Q_DECLARE_PRIVATE(KDialog)
133 
134 public:
135 
136  enum ButtonCode {
137  None = 0x00000000,
138  Help = 0x00000001, ///< Show Help button. (this button will run the help set with setHelp)
139  Default = 0x00000002, ///< Show Default button.
140  Ok = 0x00000004, ///< Show Ok button. (this button accept()s the dialog; result set to QDialog::Accepted)
141  Apply = 0x00000008, ///< Show Apply button.
142  Try = 0x00000010, ///< Show Try button.
143  Cancel = 0x00000020, ///< Show Cancel-button. (this button reject()s the dialog; result set to QDialog::Rejected)
144  Close = 0x00000040, ///< Show Close-button. (this button closes the dialog)
145  No = 0x00000080, ///< Show No button. (this button closes the dialog and sets the result to KDialog::No)
146  Yes = 0x00000100, ///< Show Yes button. (this button closes the dialog and sets the result to KDialog::Yes)
147  Reset = 0x00000200, ///< Show Reset button
148  Details = 0x00000400, ///< Show Details button. (this button will show the detail widget set with setDetailsWidget)
149  User1 = 0x00001000, ///< Show User defined button 1.
150  User2 = 0x00002000, ///< Show User defined button 2.
151  User3 = 0x00004000, ///< Show User defined button 3.
152  NoDefault = 0x00008000 ///< Used when specifying a default button; indicates that no button should be marked by default.
153  };
154  // TODO KDE5: remove NoDefault and use the value None instead
155  Q_DECLARE_FLAGS(ButtonCodes, ButtonCode)
156 
157  enum ButtonPopupMode {
158  InstantPopup = 0,
159  DelayedPopup = 1
160  };
161  Q_DECLARE_FLAGS(ButtonPopupModes, ButtonPopupMode)
162 
163 public:
164  /**
165  * Creates a dialog.
166  *
167  * @param parent The parent of the dialog.
168  * @param flags The widget flags passed to the QDialog constructor
169  */
170  KDELIBS4SUPPORT_DEPRECATED explicit KDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = {});
171 
172  /**
173  * Destroys the dialog.
174  */
175  ~KDialog() override;
176 
177  /**
178  * Creates (or recreates) the button box and all the buttons in it.
179  *
180  * Note that some combinations are not possible. That means, you can't
181  * have the following pairs of buttons in a dialog:
182  * - Default and Details
183  * - Cancel and Close
184  * - Ok and Try
185  *
186  * This will reset all default KGuiItem of all button.
187  *
188  * @param buttonMask Specifies what buttons will be made.
189  *
190  * @deprecated Since 5.0 use QDialogButtonBox
191  */
192  void setButtons(ButtonCodes buttonMask);
193 
194  /**
195  * Sets the orientation of the button box.
196  *
197  * It can be @p Vertical or @p Horizontal. If @p Horizontal
198  * (default), the button box is positioned at the bottom of the
199  * dialog. If @p Vertical it will be placed at the right edge of the
200  * dialog.
201  *
202  * @param orientation The button box orientation.
203  */
204  void setButtonsOrientation(Qt::Orientation orientation);
205 
206  /**
207  * Sets the button that will be activated when the Escape key
208  * is pressed.
209  *
210  * By default, the Escape key is mapped to either the Cancel or the Close button
211  * if one of these buttons are defined. The user expects that Escape will
212  * cancel an operation so use this function with caution.
213  *
214  * @param id The button code.
215  */
216  void setEscapeButton(ButtonCode id);
217 
218  /**
219  * Sets the button that will be activated when the Enter key
220  * is pressed.
221  *
222  * By default, this is the Ok button if it is present
223  *
224  * @param id The button code.
225  */
226  void setDefaultButton(ButtonCode id);
227 
228  /**
229  * Returns the button code of the default button,
230  * or NoDefault if there is no default button.
231  */
232  ButtonCode defaultButton() const;
233 
234  /**
235  * Hide or display the a separator line drawn between the action
236  * buttons an the main widget.
237  */
238  void showButtonSeparator(bool state);
239 
240  /**
241  * Hide or display a general action button.
242  *
243  * Only buttons that have
244  * been created in the constructor can be displayed. This method will
245  * not create a new button.
246  *
247  * @param id Button identifier.
248  * @param state true display the button(s).
249  */
250  void showButton(ButtonCode id, bool state);
251 
252  /**
253  * Sets the text of any button.
254  *
255  * @param id The button identifier.
256  * @param text Button text.
257  */
258  void setButtonText(ButtonCode id, const QString &text);
259 
260  /**
261  * Returns the text of any button.
262  */
263  QString buttonText(ButtonCode id) const;
264 
265  /**
266  * Sets the icon of any button.
267  *
268  * @param id The button identifier.
269  * @param icon Button icon.
270  */
271  void setButtonIcon(ButtonCode id, const QIcon &icon);
272 
273  /**
274  * Returns the icon of any button.
275  */
276  QIcon buttonIcon(ButtonCode id) const;
277 
278  /**
279  * Sets the tooltip text of any button.
280  *
281  * @param id The button identifier.
282  * @param text Button text.
283  */
284  void setButtonToolTip(ButtonCode id, const QString &text);
285 
286  /**
287  * Returns the tooltip of any button.
288  */
289  QString buttonToolTip(ButtonCode id) const;
290 
291  /**
292  * Sets the "What's this?" text of any button.
293  *
294  * @param id The button identifier.
295  * @param text Button text.
296  */
297  void setButtonWhatsThis(ButtonCode id, const QString &text);
298 
299  /**
300  * Returns the "What's this?" text of any button.
301  */
302  QString buttonWhatsThis(ButtonCode id) const;
303 
304  /**
305  * Sets the KGuiItem directly for the button instead of using 3 methods to
306  * set the text, tooltip and whatsthis strings. This also allows to set an
307  * icon for the button which is otherwise not possible for the extra
308  * buttons beside Ok, Cancel and Apply.
309  *
310  * @param id The button identifier.
311  * @param item The KGuiItem for the button.
312  */
313  void setButtonGuiItem(ButtonCode id, const KGuiItem &item);
314 
315  /**
316  * Sets the menu of any button.
317  *
318  * @param id The button identifier.
319  * @param menu The menu.
320  * @param popupmode Choose if QPushButton setMenu or setDelayedMenu is used
321  */
322  void setButtonMenu(ButtonCode id, QMenu *menu, ButtonPopupMode popupmode = InstantPopup);
323 
324  /**
325  * Sets the focus to the button of the passed @p id.
326  */
327  void setButtonFocus(ButtonCode id);
328 
329  /**
330  * Convenience method. Sets the initial dialog size.
331  *
332  * This method should only be called right before show() or exec().
333  * The initial size will be ignored if smaller than
334  * the dialog's minimum size.
335  *
336  * @param size Startup size.
337  */
338  void setInitialSize(const QSize &size);
339 
340  /**
341  * Convenience method. Add a size to the default minimum size of a
342  * dialog.
343  *
344  * This method should only be called right before show() or exec().
345  *
346  * @param size Size added to minimum size.
347  */
348  void incrementInitialSize(const QSize &size);
349 
350  /**
351  * Restores the dialog's size from the configuration according to
352  * the screen size.
353  *
354  * @note the group must be set before calling
355  *
356  * @param config The config group to read from.
357  * @deprecated use KWindowConfig::restoreWindowSize() instead
358  */
359 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
360  KDELIBS4SUPPORT_DEPRECATED void restoreDialogSize(const KConfigGroup &config);
361 #endif
362 
363  /**
364  * Saves the dialog's size dependent on the screen dimension either to the
365  * global or application config file.
366  *
367  * @note the group must be set before calling
368  *
369  * @param config The config group to read from.
370  * @param options passed to KConfigGroup::writeEntry()
371  * @deprecated use KWindowConfig::saveWindowSize() instead
372  */
373 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
374  KDELIBS4SUPPORT_DEPRECATED void saveDialogSize(KConfigGroup &config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal) const;
375 #endif
376 
377  /**
378  * Returns the help link text.
379  *
380  * If no text has been defined,
381  * "Get help..." (internationalized) is returned.
382  *
383  * @return The help link text.
384  *
385  * @see enableLinkedHelp()
386  * @see setHelpLinkText()
387  * @see setHelp()
388  */
389  QString helpLinkText() const;
390 
391  /**
392  * Returns whether any button is enabled.
393  */
394  bool isButtonEnabled(ButtonCode id) const;
395 
396  /**
397  * Returns the button that corresponds to the @p id.
398  *
399  * Normally you should not use this function.
400  * @em Never delete the object returned by this function.
401  * See also enableButton(), showButton(), setButtonGuiItem().
402  *
403  * @param id Identifier of the button.
404  * @return The button or 0 if the button does not exist.
405  */
406  QPushButton *button(ButtonCode id) const;
407 
408  /**
409  * Returns the number of pixels that should be used between a
410  * dialog edge and the outermost widget(s) according to the KDE standard.
411  *
412  * @deprecated Use the style's pixelMetric() function to query individual margins.
413  * Different platforms may use different values for the four margins.
414  */
415  static int marginHint();
416 
417  /**
418  * Returns the number of pixels that should be used between
419  * widgets inside a dialog according to the KDE standard.
420  *
421  * @deprecated Use the style's layoutSpacing() function to query individual spacings.
422  * Different platforms may use different values depending on widget types and pairs.
423  */
424  static int spacingHint();
425 
426  /**
427  * Returns the number of pixels that should be used to visually
428  * separate groups of related options in a dialog according to
429  * the KDE standard.
430  * @since 4.2
431  */
432  static int groupSpacingHint();
433 
434  /**
435  * @enum StandardCaptionFlag
436  * Used to specify how to construct a window caption
437  *
438  * @value AppName Indicates that the method shall include
439  * the application name when making the caption string.
440  * @value Modified Causes a 'modified' sign will be included in the
441  * returned string. This is useful when indicating that a file is
442  * modified, i.e., it contains data that has not been saved.
443  * @value HIGCompliant The base minimum flags required to align a
444  * caption with the KDE Human Interface Guidelines
445  */
446  enum CaptionFlag {
447  NoCaptionFlags = 0,
448  AppNameCaption = 1,
449  ModifiedCaption = 2,
450  HIGCompliantCaption = AppNameCaption
451  };
452  Q_DECLARE_FLAGS(CaptionFlags, CaptionFlag)
453 
454  /**
455  * Builds a caption that contains the application name along with the
456  * userCaption using a standard layout.
457  *
458  * To make a compliant caption for your window, simply do:
459  * @p setWindowTitle(KDialog::makeStandardCaption(yourCaption));
460  *
461  * To ensure that the caption is appropriate to the desktop in which the
462  * application is running, pass in a pointer to the window the caption will
463  * be applied to.
464  *
465  * If using a KDialog or KMainWindow subclass, call setCaption instead and
466  * an appropraite standard caption will be created for you
467  *
468  * @param userCaption The caption string you want to display in the
469  * window caption area. Do not include the application name!
470  * @param window a pointer to the window this application will apply to
471  * @param flags
472  * @return the created caption
473  */
474  static QString makeStandardCaption(const QString &userCaption,
475  QWidget *window = nullptr,
476  CaptionFlags flags = HIGCompliantCaption);
477 
478  /**
479  * Resize every layout manager used in @p widget and its nested children.
480  *
481  * @param widget The widget used.
482  * @param margin The new layout margin.
483  * @param spacing The new layout spacing.
484  *
485  * @deprecated Use QLayout functions where necessary. Setting margin and spacing
486  * values recursively for all children prevents QLayout from creating platform native
487  * layouts.
488  */
489  static void resizeLayout(QWidget *widget, int margin, int spacing);
490 
491  /**
492  * Resize every layout associated with @p lay and its children.
493  *
494  * @param lay layout to be resized
495  * @param margin The new layout margin
496  * @param spacing The new layout spacing
497  *
498  * @deprecated Use QLayout functions where necessary. Setting margin and spacing
499  * values recursively for all children prevents QLayout from creating platform native
500  * layouts.
501  */
502  static void resizeLayout(QLayout *lay, int margin, int spacing);
503 
504  /**
505  * Centers @p widget on the desktop, taking multi-head setups into
506  * account. If @p screen is -1, @p widget will be centered on its
507  * current screen (if it was shown already) or on the primary screen.
508  * If @p screen is -3, @p widget will be centered on the screen that
509  * currently contains the mouse pointer.
510  * @p screen will be ignored if a merged display (like Xinerama) is not
511  * in use, or merged display placement is not enabled in kdeglobals.
512  */
513  static void centerOnScreen(QWidget *widget, int screen = -1);
514 
515  /**
516  * Places @p widget so that it doesn't cover a certain @p area of the screen.
517  * This is typically used by the "find dialog" so that the match it finds can
518  * be read.
519  * For @p screen, see centerOnScreen
520  * @return true on success (widget doesn't cover area anymore, or never did),
521  * false on failure (not enough space found)
522  */
523  static bool avoidArea(QWidget *widget, const QRect &area, int screen = -1);
524 
525  /**
526  * Sets the main widget of the dialog.
527  */
528  void setMainWidget(QWidget *widget);
529 
530  /**
531  * @return The current main widget. Will create a QWidget as the mainWidget
532  * if none was set before. This way you can write
533  * \code
534  * ui.setupUi(mainWidget());
535  * \endcode
536  * when using designer.
537  */
538  QWidget *mainWidget();
539 
540  /**
541  * Reimplemented from QDialog.
542  */
543  QSize sizeHint() const override;
544 
545  /**
546  * Reimplemented from QDialog.
547  */
548  QSize minimumSizeHint() const override;
549 
550  /**
551  * Allow embedding the dialogs based on KDialog into a graphics view. By default embedding is not allowed, dialogs
552  * will appear as separate windows.
553  * @since 4.6
554  */
555  static void setAllowEmbeddingInGraphicsView(bool allowEmbedding);
556 
557 public Q_SLOTS:
558  /**
559  * Make a KDE compliant caption.
560  *
561  * @param caption Your caption. Do @p not include the application name
562  * in this string. It will be added automatically according to the KDE
563  * standard.
564  *
565  * @deprecated Since 5.0 use QWidget::setWindowTitle
566  */
567  virtual void setCaption(const QString &caption);
568 
569  /**
570  * Makes a KDE compliant caption.
571  *
572  * @param caption Your caption. @em Do @em not include the application name
573  * in this string. It will be added automatically according to the KDE
574  * standard.
575  * @param modified Specify whether the document is modified. This displays
576  * an additional sign in the title bar, usually "**".
577  *
578  * @deprecated Since 5.0 use QWidget::setWindowTitle and QWidget::setWindowModified.
579  */
580  virtual void setCaption(const QString &caption, bool modified);
581 
582  /**
583  * Make a plain caption without any modifications.
584  *
585  * @param caption Your caption. This is the string that will be
586  * displayed in the window title.
587  */
588  virtual void setPlainCaption(const QString &caption);
589 
590  /**
591  * Enable or disable (gray out) a general action button.
592  *
593  * @param id Button identifier.
594  * @param state @p true enables the button(s).
595  */
596  void enableButton(ButtonCode id, bool state);
597 
598  /**
599  * Enable or disable (gray out) the OK button.
600  *
601  * @param state @p true enables the button.
602  */
603  void enableButtonOk(bool state);
604 
605  /**
606  * Enable or disable (gray out) the Apply button.
607  *
608  * @param state true enables the button.
609  */
610  void enableButtonApply(bool state);
611 
612  /**
613  * Enable or disable (gray out) the Cancel button.
614  *
615  * @param state true enables the button.
616  */
617  void enableButtonCancel(bool state);
618 
619  /**
620  * Display or hide the help link area on the top of the dialog.
621  *
622  * @param state @p true will display the area.
623  *
624  * @see helpLinkText()
625  * @see setHelpLinkText()
626  * @see setHelp()
627  */
628  void enableLinkedHelp(bool state);
629 
630  /**
631  * Sets the text that is shown as the linked text.
632  *
633  * If text is empty,
634  * the text "Get help..." (internationalized) is used instead.
635  *
636  * @param text The link text.
637  *
638  * @see helpLinkText()
639  * @see enableLinkedHelp()
640  * @see setHelp()
641  */
642  void setHelpLinkText(const QString &text);
643 
644  /**
645  * Sets the help path and topic.
646  *
647  * @param anchor Defined anchor in your docbook sources
648  * @param appname Defines the appname the help belongs to
649  * If empty it's the current one
650  *
651  * @note The help button works differently for the class
652  * KCMultiDialog, so it does not make sense to call this
653  * function for Dialogs of that type. See
654  * KCMultiDialog::slotHelp() for more information.
655  */
656  void setHelp(const QString &anchor, const QString &appname = QString());
657 
658  /**
659  * Returns the status of the Details button.
660  */
661  bool isDetailsWidgetVisible() const;
662 
663  /**
664  * Sets the status of the Details button.
665  */
666  void setDetailsWidgetVisible(bool visible);
667 
668  /**
669  * Sets the widget that gets shown when "Details" is enabled.
670  *
671  * The dialog takes over ownership of the widget.
672  * Any previously set widget gets deleted.
673  */
674  void setDetailsWidget(QWidget *detailsWidget);
675 
676  /**
677  * Destruct the dialog delayed.
678  *
679  * You can call this function from slots like closeClicked() and hidden().
680  * You should not use the dialog any more after calling this function.
681  * @deprecated use hide()+deleteLater()
682  */
683  void delayedDestruct();
684 
685 Q_SIGNALS:
686  /**
687  * Emitted when the margin size and/or spacing size
688  * have changed.
689  *
690  * Use marginHint() and spacingHint() in your slot
691  * to get the new values.
692  *
693  * @deprecated This signal is not emitted. Listen to QEvent::StyleChange events instead.
694  */
695  void layoutHintChanged();
696 
697  /**
698  * The Help button was pressed. This signal is only emitted if
699  * slotButtonClicked() is not replaced
700  */
701  void helpClicked();
702 
703  /**
704  * The Default button was pressed. This signal is only emitted if
705  * slotButtonClicked() is not replaced
706  */
707  void defaultClicked();
708 
709  /**
710  * The Reset button was pressed. This signal is only emitted if
711  * slotButtonClicked() is not replaced
712  */
713  void resetClicked();
714 
715  /**
716  * The User3 button was pressed. This signal is only emitted if
717  * slotButtonClicked() is not replaced
718  */
719  void user3Clicked();
720 
721  /**
722  * The User2 button was pressed. This signal is only emitted if
723  * slotButtonClicked() is not replaced
724  */
725  void user2Clicked();
726 
727  /**
728  * The User1 button was pressed. This signal is only emitted if
729  * slotButtonClicked() is not replaced
730  */
731  void user1Clicked();
732 
733  /**
734  * The Apply button was pressed. This signal is only emitted if
735  * slotButtonClicked() is not replaced
736  */
737  void applyClicked();
738 
739  /**
740  * The Try button was pressed. This signal is only emitted if
741  * slotButtonClicked() is not replaced
742  */
743  void tryClicked();
744 
745  /**
746  * The OK button was pressed. This signal is only emitted if
747  * slotButtonClicked() is not replaced
748  */
749  void okClicked();
750 
751  /**
752  * The Yes button was pressed. This signal is only emitted if
753  * slotButtonClicked() is not replaced
754  */
755  void yesClicked();
756 
757  /**
758  * The No button was pressed. This signal is only emitted if
759  * slotButtonClicked() is not replaced
760  */
761  void noClicked();
762 
763  /**
764  * The Cancel button was pressed. This signal is only emitted if
765  * slotButtonClicked() is not replaced
766  */
767  void cancelClicked();
768 
769  /**
770  * The Close button was pressed. This signal is only emitted if
771  * slotButtonClicked() is not replaced
772  */
773  void closeClicked();
774 
775  /**
776  * A button has been pressed. This signal is only emitted if
777  * slotButtonClicked() is not replaced
778  * @param button is the code of the pressed button.
779  */
780  void buttonClicked(KDialog::ButtonCode button);
781 
782  /**
783  * The dialog is about to be hidden.
784  *
785  * A dialog is hidden after a user clicks a button that ends
786  * the dialog or when the user switches to another desktop or
787  * minimizes the dialog.
788  */
789  void hidden();
790 
791  /**
792  * The dialog has finished.
793  *
794  * A dialog emits finished after a user clicks a button that ends
795  * the dialog.
796  *
797  * This signal is also emitted when you call hide()
798  *
799  * If you have stored a pointer to the
800  * dialog do @em not try to delete the pointer in the slot that is
801  * connected to this signal.
802  *
803  * You should use deleteLater() instead.
804  */
805  void finished();
806 
807  /**
808  * The detailsWidget is about to get shown. This is your last chance
809  * to call setDetailsWidget if you haven't done so yet.
810  */
811  void aboutToShowDetails();
812 
813 protected:
814  /**
815  * Emits the #hidden signal. You can connect to that signal to
816  * detect when a dialog has been closed.
817  */
818  void hideEvent(QHideEvent *) override;
819 
820  /**
821  * Detects when a dialog is being closed from the window manager
822  * controls. If the Cancel or Close button is present then the button
823  * is activated. Otherwise standard QDialog behavior
824  * will take place.
825  */
826  void closeEvent(QCloseEvent *e) override;
827 
828  /**
829  * @internal
830  */
831  void keyPressEvent(QKeyEvent *) override;
832 
833 protected Q_SLOTS:
834  /**
835  * Activated when the button @p button is clicked
836  *
837  * Sample that shows how to catch and handle button clicks within
838  * an own dialog;
839  * @code
840  * class MyDialog : public KDialog {
841  * protected Q_SLOTS:
842  * virtual void slotButtonClicked(int button) {
843  * if (button == KDialog::Ok)
844  * accept();
845  * else
846  * KDialog::slotButtonClicked(button);
847  * }
848  * }
849  * @endcode
850  *
851  * @param button is the type @a KDialog::ButtonCode
852  *
853  * @deprecated since 5.0 use QDialogButtonBox and connect to the clicked signal
854  */
855  virtual void slotButtonClicked(int button);
856 
857  /**
858  * Updates the margins and spacings.
859  *
860  * @deprecated KDialog respects the style's margins and spacings automatically. Calling
861  * this function has no effect.
862  */
863  void updateGeometry();
864 
865 protected:
866  KDialog(KDialogPrivate &dd, QWidget *parent, Qt::WindowFlags flags = {});
867  KDialogPrivate *const d_ptr;
868 
869 private:
871  Q_PRIVATE_SLOT(d_ptr, void queuedLayoutUpdate())
872  Q_PRIVATE_SLOT(d_ptr, void helpLinkClicked())
873 };
874 
875 Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::ButtonCodes)
876 Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::CaptionFlags)
877 
878 #endif // KDIALOG_H
Q_SLOTSQ_SLOTS
ButtonCode
Definition: kdialog.h:136
Q_ENUMS(...)
virtual void closeEvent(QCloseEvent *e) override
typedef WindowFlags
virtual void hideEvent(QHideEvent *event)
virtual QSize minimumSizeHint() const const override
Orientation
A dialog base class with standard buttons and predefined layouts.
Definition: kdialog.h:128
Q_SIGNALSQ_SIGNALS
virtual void keyPressEvent(QKeyEvent *e) override
void updateGeometry()
Q_DISABLE_COPY(Class)
void finished(int result)
virtual QSize sizeHint() const const override
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Dec 4 2022 03:58:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.