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 * and Holger Freyther <freyther@kde.org>
5 * 2005-2009 Olivier Goffart <ogoffart @ kde.org>
6 * 2006 Tobias Koenig <tokoe@kde.org>
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
27class KPushButton;
28class QMenu;
29class KDialogPrivate;
30
31#include <kdeui_export.h>
32#include <kconfiggroup.h>
33#include <kguiitem.h>
34
35#include <QtGui/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 <tanghus@earthling.net>
123 * @author Espen Sand <espensa@online.no>
124 * @author Mirko Boehm <mirko@kde.org>
125 * @author Olivier Goffart <ogoffart at kde.org>
126 * @author Tobias Koenig <tokoe@kde.org>
127 */
128class KDEUI_EXPORT KDialog : public QDialog //krazy:exclude=qclasses
129{
130 Q_OBJECT
131 Q_ENUMS(ButtonCode)
132 Q_DECLARE_PRIVATE(KDialog)
133
134 public:
135
136 enum ButtonCode
137 {
138 None = 0x00000000,
139 Help = 0x00000001, ///< Show Help button. (this button will run the help set with setHelp)
140 Default = 0x00000002, ///< Show Default button.
141 Ok = 0x00000004, ///< Show Ok button. (this button accept()s the dialog; result set to QDialog::Accepted)
142 Apply = 0x00000008, ///< Show Apply button.
143 Try = 0x00000010, ///< Show Try button.
144 Cancel = 0x00000020, ///< Show Cancel-button. (this button reject()s the dialog; result set to QDialog::Rejected)
145 Close = 0x00000040, ///< Show Close-button. (this button closes the dialog)
146 No = 0x00000080, ///< Show No button. (this button closes the dialog and sets the result to KDialog::No)
147 Yes = 0x00000100, ///< Show Yes button. (this button closes the dialog and sets the result to KDialog::Yes)
148 Reset = 0x00000200, ///< Show Reset button
149 Details = 0x00000400, ///< Show Details button. (this button will show the detail widget set with setDetailsWidget)
150 User1 = 0x00001000, ///< Show User defined button 1.
151 User2 = 0x00002000, ///< Show User defined button 2.
152 User3 = 0x00004000, ///< Show User defined button 3.
153 NoDefault = 0x00008000 ///< Used when specifying a default button; indicates that no button should be marked by default.
154 };
155 // TODO KDE5: remove NoDefault and use the value None instead
156 Q_DECLARE_FLAGS(ButtonCodes, ButtonCode)
157
158 enum ButtonPopupMode
159 {
160 InstantPopup = 0,
161 DelayedPopup = 1
162 };
163 Q_DECLARE_FLAGS(ButtonPopupModes, ButtonPopupMode)
164
165 public:
166 /**
167 * Creates a dialog.
168 *
169 * @param parent The parent of the dialog.
170 * @param flags The widget flags passed to the QDialog constructor
171 */
172 explicit KDialog( QWidget *parent = 0, Qt::WindowFlags flags = 0 );
173
174 /**
175 * Destroys the dialog.
176 */
177 ~KDialog();
178
179 /**
180 * Creates (or recreates) the button box and all the buttons in it.
181 *
182 * Note that some combinations are not possible. That means, you can't
183 * have the following pairs of buttons in a dialog:
184 * - Default and Details
185 * - Cancel and Close
186 * - Ok and Try
187 *
188 * This will reset all default KGuiItem of all button.
189 *
190 * @param buttonMask Specifies what buttons will be made.
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 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 KIcon &icon );
272
273 /**
274 * Returns the icon of any button.
275 */
276 KIcon 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 KPushButton 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 */
358 void restoreDialogSize( const KConfigGroup& config ) ;
359
360 /**
361 * Saves the dialog's size dependent on the screen dimension either to the
362 * global or application config file.
363 *
364 * @note the group must be set before calling
365 *
366 * @param config The config group to read from.
367 * @param options passed to KConfigGroup::writeEntry()
368 */
369 void saveDialogSize( KConfigGroup& config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal ) const;
370
371 /**
372 * Returns the help link text.
373 *
374 * If no text has been defined,
375 * "Get help..." (internationalized) is returned.
376 *
377 * @return The help link text.
378 *
379 * @see enableLinkedHelp()
380 * @see setHelpLinkText()
381 * @see setHelp()
382 */
383 QString helpLinkText() const;
384
385 /**
386 * Returns whether any button is enabled.
387 */
388 bool isButtonEnabled( ButtonCode id ) const;
389
390 /**
391 * Returns the button that corresponds to the @p id.
392 *
393 * Normally you should not use this function.
394 * @em Never delete the object returned by this function.
395 * See also enableButton(), showButton(), setButtonGuiItem().
396 *
397 * @param id Identifier of the button.
398 * @return The button or 0 if the button does not exist.
399 */
400 KPushButton* button( ButtonCode id ) const;
401
402 /**
403 * Returns the number of pixels that should be used between a
404 * dialog edge and the outermost widget(s) according to the KDE standard.
405 *
406 * @deprecated Use the style's pixelMetric() function to query individual margins.
407 * Different platforms may use different values for the four margins.
408 */
409 static int marginHint();
410
411 /**
412 * Returns the number of pixels that should be used between
413 * widgets inside a dialog according to the KDE standard.
414 *
415 * @deprecated Use the style's layoutSpacing() function to query individual spacings.
416 * Different platforms may use different values depending on widget types and pairs.
417 */
418 static int spacingHint();
419
420 /**
421 * Returns the number of pixels that should be used to visually
422 * separate groups of related options in a dialog according to
423 * the KDE standard.
424 * @since 4.2
425 */
426 static int groupSpacingHint();
427
428 /**
429 * @enum StandardCaptionFlag
430 * Used to specify how to construct a window caption
431 *
432 * @value AppName Indicates that the method shall include
433 * the application name when making the caption string.
434 * @value Modified Causes a 'modified' sign will be included in the
435 * returned string. This is useful when indicating that a file is
436 * modified, i.e., it contains data that has not been saved.
437 * @value HIGCompliant The base minimum flags required to align a
438 * caption with the KDE Human Interface Guidelines
439 */
440 enum CaptionFlag
441 {
442 NoCaptionFlags = 0,
443 AppNameCaption = 1,
444 ModifiedCaption = 2,
445 HIGCompliantCaption = AppNameCaption
446 };
447 Q_DECLARE_FLAGS(CaptionFlags, CaptionFlag)
448
449 /**
450 * Builds a caption that contains the application name along with the
451 * userCaption using a standard layout.
452 *
453 * To make a compliant caption for your window, simply do:
454 * @p setWindowTitle(KDialog::makeStandardCaption(yourCaption));
455 *
456 * To ensure that the caption is appropriate to the desktop in which the
457 * application is running, pass in a pointer to the window the caption will
458 * be applied to.
459 *
460 * If using a KDialog or KMainWindow subclass, call setCaption instead and
461 * an appropraite standard caption will be created for you
462 *
463 * @param userCaption The caption string you want to display in the
464 * window caption area. Do not include the application name!
465 * @param window a pointer to the window this application will apply to
466 * @param flags
467 * @return the created caption
468 */
469 static QString makeStandardCaption( const QString &userCaption,
470 QWidget* window = 0,
471 CaptionFlags flags = HIGCompliantCaption );
472
473 /**
474 * Resize every layout manager used in @p widget and its nested children.
475 *
476 * @param widget The widget used.
477 * @param margin The new layout margin.
478 * @param spacing The new layout spacing.
479 *
480 * @deprecated Use QLayout functions where necessary. Setting margin and spacing
481 * values recursively for all children prevents QLayout from creating platform native
482 * layouts.
483 */
484 static void resizeLayout( QWidget *widget, int margin, int spacing );
485
486 /**
487 * Resize every layout associated with @p lay and its children.
488 *
489 * @param lay layout to be resized
490 * @param margin The new layout margin
491 * @param spacing The new layout spacing
492 *
493 * @deprecated Use QLayout functions where necessary. Setting margin and spacing
494 * values recursively for all children prevents QLayout from creating platform native
495 * layouts.
496 */
497 static void resizeLayout( QLayout *lay, int margin, int spacing );
498
499 /**
500 * Centers @p widget on the desktop, taking multi-head setups into
501 * account. If @p screen is -1, @p widget will be centered on its
502 * current screen (if it was shown already) or on the primary screen.
503 * If @p screen is -3, @p widget will be centered on the screen that
504 * currently contains the mouse pointer.
505 * @p screen will be ignored if a merged display (like Xinerama) is not
506 * in use, or merged display placement is not enabled in kdeglobals.
507 */
508 static void centerOnScreen( QWidget *widget, int screen = -1 );
509
510 /**
511 * Places @p widget so that it doesn't cover a certain @p area of the screen.
512 * This is typically used by the "find dialog" so that the match it finds can
513 * be read.
514 * For @p screen, see centerOnScreen
515 * @return true on success (widget doesn't cover area anymore, or never did),
516 * false on failure (not enough space found)
517 */
518 static bool avoidArea( QWidget *widget, const QRect& area, int screen = -1 );
519
520 /**
521 * Sets the main widget of the dialog.
522 */
523 void setMainWidget( QWidget *widget );
524
525 /**
526 * @return The current main widget. Will create a QWidget as the mainWidget
527 * if none was set before. This way you can write
528 * \code
529 * ui.setupUi(mainWidget());
530 * \endcode
531 * when using designer.
532 */
533 QWidget *mainWidget();
534
535 /**
536 * Reimplemented from QDialog.
537 */
538 virtual QSize sizeHint() const;
539
540 /**
541 * Reimplemented from QDialog.
542 */
543 virtual QSize minimumSizeHint() const;
544
545 /**
546 * Allow embedding the dialogs based on KDialog into a graphics view. By default embedding is not allowed, dialogs
547 * will appear as separate windows.
548 * @since 4.6
549 */
550 static void setAllowEmbeddingInGraphicsView( bool allowEmbedding );
551
552 public Q_SLOTS:
553 /**
554 * Make a KDE compliant caption.
555 *
556 * @param caption Your caption. Do @p not include the application name
557 * in this string. It will be added automatically according to the KDE
558 * standard.
559 */
560 virtual void setCaption( const QString &caption );
561
562 /**
563 * Makes a KDE compliant caption.
564 *
565 * @param caption Your caption. @em Do @em not include the application name
566 * in this string. It will be added automatically according to the KDE
567 * standard.
568 * @param modified Specify whether the document is modified. This displays
569 * an additional sign in the title bar, usually "**".
570 */
571 virtual void setCaption( const QString &caption, bool modified );
572
573 /**
574 * Make a plain caption without any modifications.
575 *
576 * @param caption Your caption. This is the string that will be
577 * displayed in the window title.
578 */
579 virtual void setPlainCaption( const QString &caption );
580
581 /**
582 * Enable or disable (gray out) a general action button.
583 *
584 * @param id Button identifier.
585 * @param state @p true enables the button(s).
586 */
587 void enableButton( ButtonCode id, bool state );
588
589 /**
590 * Enable or disable (gray out) the OK button.
591 *
592 * @param state @p true enables the button.
593 */
594 void enableButtonOk( bool state );
595
596 /**
597 * Enable or disable (gray out) the Apply button.
598 *
599 * @param state true enables the button.
600 */
601 void enableButtonApply( bool state );
602
603 /**
604 * Enable or disable (gray out) the Cancel button.
605 *
606 * @param state true enables the button.
607 */
608 void enableButtonCancel( bool state );
609
610 /**
611 * Display or hide the help link area on the top of the dialog.
612 *
613 * @param state @p true will display the area.
614 *
615 * @see helpLinkText()
616 * @see setHelpLinkText()
617 * @see setHelp()
618 */
619 void enableLinkedHelp( bool state );
620
621 /**
622 * Sets the text that is shown as the linked text.
623 *
624 * If text is empty,
625 * the text "Get help..." (internationalized) is used instead.
626 *
627 * @param text The link text.
628 *
629 * @see helpLinkText()
630 * @see enableLinkedHelp()
631 * @see setHelp()
632 */
633 void setHelpLinkText( const QString &text );
634
635 /**
636 * Sets the help path and topic.
637 *
638 * @param anchor Defined anchor in your docbook sources
639 * @param appname Defines the appname the help belongs to
640 * If empty it's the current one
641 *
642 * @note The help button works differently for the class
643 * KCMultiDialog, so it does not make sense to call this
644 * function for Dialogs of that type. See
645 * KCMultiDialog::slotHelp() for more information.
646 */
647 void setHelp( const QString &anchor, const QString &appname = QString() );
648
649 /**
650 * Returns the status of the Details button.
651 */
652 bool isDetailsWidgetVisible() const;
653
654 /**
655 * Sets the status of the Details button.
656 */
657 void setDetailsWidgetVisible( bool visible );
658
659 /**
660 * Sets the widget that gets shown when "Details" is enabled.
661 *
662 * The dialog takes over ownership of the widget.
663 * Any previously set widget gets deleted.
664 */
665 void setDetailsWidget( QWidget *detailsWidget );
666
667 /**
668 * Destruct the dialog delayed.
669 *
670 * You can call this function from slots like closeClicked() and hidden().
671 * You should not use the dialog any more after calling this function.
672 */
673 void delayedDestruct();
674
675 Q_SIGNALS:
676 /**
677 * Emitted when the margin size and/or spacing size
678 * have changed.
679 *
680 * Use marginHint() and spacingHint() in your slot
681 * to get the new values.
682 *
683 * @deprecated This signal is not emitted. Listen to QEvent::StyleChange events instead.
684 */
685 void layoutHintChanged();
686
687 /**
688 * The Help button was pressed. This signal is only emitted if
689 * slotButtonClicked() is not replaced
690 */
691 void helpClicked();
692
693 /**
694 * The Default button was pressed. This signal is only emitted if
695 * slotButtonClicked() is not replaced
696 */
697 void defaultClicked();
698
699 /**
700 * The Reset button was pressed. This signal is only emitted if
701 * slotButtonClicked() is not replaced
702 */
703 void resetClicked();
704
705 /**
706 * The User3 button was pressed. This signal is only emitted if
707 * slotButtonClicked() is not replaced
708 */
709 void user3Clicked();
710
711 /**
712 * The User2 button was pressed. This signal is only emitted if
713 * slotButtonClicked() is not replaced
714 */
715 void user2Clicked();
716
717 /**
718 * The User1 button was pressed. This signal is only emitted if
719 * slotButtonClicked() is not replaced
720 */
721 void user1Clicked();
722
723 /**
724 * The Apply button was pressed. This signal is only emitted if
725 * slotButtonClicked() is not replaced
726 */
727 void applyClicked();
728
729 /**
730 * The Try button was pressed. This signal is only emitted if
731 * slotButtonClicked() is not replaced
732 */
733 void tryClicked();
734
735 /**
736 * The OK button was pressed. This signal is only emitted if
737 * slotButtonClicked() is not replaced
738 */
739 void okClicked();
740
741 /**
742 * The Yes button was pressed. This signal is only emitted if
743 * slotButtonClicked() is not replaced
744 */
745 void yesClicked();
746
747 /**
748 * The No button was pressed. This signal is only emitted if
749 * slotButtonClicked() is not replaced
750 */
751 void noClicked();
752
753 /**
754 * The Cancel button was pressed. This signal is only emitted if
755 * slotButtonClicked() is not replaced
756 */
757 void cancelClicked();
758
759 /**
760 * The Close button was pressed. This signal is only emitted if
761 * slotButtonClicked() is not replaced
762 */
763 void closeClicked();
764
765 /**
766 * A button has been pressed. This signal is only emitted if
767 * slotButtonClicked() is not replaced
768 * @param button is the code of the pressed button.
769 */
770 void buttonClicked( KDialog::ButtonCode button);
771
772 /**
773 * The dialog is about to be hidden.
774 *
775 * A dialog is hidden after a user clicks a button that ends
776 * the dialog or when the user switches to another desktop or
777 * minimizes the dialog.
778 */
779 void hidden();
780
781 /**
782 * The dialog has finished.
783 *
784 * A dialog emits finished after a user clicks a button that ends
785 * the dialog.
786 *
787 * This signal is also emitted when you call hide()
788 *
789 * If you have stored a pointer to the
790 * dialog do @em not try to delete the pointer in the slot that is
791 * connected to this signal.
792 *
793 * You should use deleteLater() instead.
794 */
795 void finished();
796
797 /**
798 * The detailsWidget is about to get shown. This is your last chance
799 * to call setDetailsWidget if you haven't done so yet.
800 */
801 void aboutToShowDetails();
802
803 protected:
804 /**
805 * Emits the #hidden signal. You can connect to that signal to
806 * detect when a dialog has been closed.
807 */
808 virtual void hideEvent( QHideEvent * );
809
810 /**
811 * Detects when a dialog is being closed from the window manager
812 * controls. If the Cancel or Close button is present then the button
813 * is activated. Otherwise standard QDialog behavior
814 * will take place.
815 */
816 virtual void closeEvent( QCloseEvent *e );
817
818 /**
819 * @internal
820 */
821 virtual void keyPressEvent( QKeyEvent* );
822
823 protected Q_SLOTS:
824 /**
825 * Activated when the button @p button is clicked
826 *
827 * Sample that shows how to catch and handle button clicks within
828 * an own dialog;
829 * @code
830 * class MyDialog : public KDialog {
831 * protected Q_SLOTS:
832 * virtual void slotButtonClicked(int button) {
833 * if (button == KDialog::Ok)
834 * accept();
835 * else
836 * KDialog::slotButtonClicked(button);
837 * }
838 * }
839 * @endcode
840 *
841 * @param button is the type @a KDialog::ButtonCode
842 */
843 virtual void slotButtonClicked(int button);
844
845 /**
846 * Updates the margins and spacings.
847 *
848 * @deprecated KDialog respects the style's margins and spacings automatically. Calling
849 * this function has no effect.
850 */
851 void updateGeometry();
852
853 protected:
854 KDialog(KDialogPrivate &dd, QWidget *parent, Qt::WindowFlags flags = 0);
855 KDialogPrivate *const d_ptr;
856
857 private:
858 Q_DISABLE_COPY(KDialog)
859 Q_PRIVATE_SLOT(d_ptr, void queuedLayoutUpdate())
860 Q_PRIVATE_SLOT(d_ptr, void helpLinkClicked())
861};
862
863Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::ButtonCodes)
864Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::CaptionFlags)
865
866#endif // KDIALOG_H
867