Debian Codegraph @

src/libs/widgets/KoDialog.h

raw
1 /* This file is part of the KDE Libraries
2 * SPDX-FileCopyrightText: 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 * SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10
11 #ifndef KODIALOG_H
12 #define KODIALOG_H
13
14 class QPushButton;
15 class QMenu;
16 class KoDialogPrivate;
17
18 #include <kowidgets_export.h>
19 #include <KConfigGroup>
20 #include <KGuiItem>
21
22 #include <QDialog>
23
24 /**
25 * @short A dialog base class with standard buttons and predefined layouts.
26 *
27 * Provides basic functionality needed by nearly all dialogs.
28 *
29 * It offers the standard action buttons you'd expect to find in a
30 * dialog as well as the capability to define at most three configurable
31 * buttons. You can define a main widget that contains your specific
32 * dialog layout
33 *
34 * The class takes care of the geometry management. You only need to define
35 * a minimum size for the widget you want to use as the main widget.
36 *
37 * By default, the dialog is non-modal.
38 *
39 * <b>Standard buttons (action buttons):</b>\n
40 *
41 * You select which buttons should be displayed, but you do not choose the
42 * order in which they are displayed. This ensures a standard interface in
43 * KDE. The button order can be changed, but this ability is only available
44 * for a central KDE control tool. The following buttons are available:
45 * OK, Cancel/Close, Apply/Try, Default, Help and three user definable
46 * buttons: User1, User2 and User3. You must specify the text of the UserN
47 * buttons. Each button Q_EMIT a signal, so you can choose to connect that signal.
48 *
49 * The default action of the Help button will open the help system if you have
50 * provided a path to the help text.
51 * The default action of Ok and Cancel will run QDialog::accept() and QDialog::reject(),
52 * which you can override by reimplementing slotButtonClicked(). The default
53 * action of the Close button will close the dialog.
54 *
55 * Note that the KoDialog will animate a button press
56 * when the user presses Escape. The button that is enabled is either Cancel,
57 * Close or the button that is defined by setEscapeButton().
58 * Your custom dialog code should reimplement the keyPressEvent and
59 * animate the cancel button so that the dialog behaves like regular
60 * dialogs.
61 *
62 * <b>Layout:</b>\n
63 *
64 * The dialog consists of a help area on top (becomes visible if you define
65 * a help path and use enableLinkedHelp()), the main area which is
66 * the built-in dialog face or your own widget in the middle and by default
67 * a button box at the bottom. The button box can also be placed at the
68 * right edge (to the right of the main widget). Use
69 * setButtonsOrientation() to control this behavior. A separator
70 * can be placed above the button box (or to the left when the button box
71 * is at the right edge).
72 *
73 * <b>Standard compliance:</b>\n
74 *
75 * The marginHint() and spacingHint() sizes shall be used
76 * whenever you lay out the interior of a dialog. One special note. If
77 * you make your own action buttons (OK, Cancel etc), the space
78 * between the buttons shall be spacingHint(), whereas the space
79 * above, below, to the right and to the left shall be marginHint().
80 * If you add a separator line above the buttons, there shall be a
81 * marginHint() between the buttons and the separator and a
82 * marginHint() above the separator as well.
83 *
84 * <b>Example:</b>\n
85 *
86 * \code
87 * KoDialog *dialog = new KoDialog(this);
88 * dialog->setCaption("My title");
89 * dialog->setButtons(KoDialog::Ok | KoDialog::Cancel | KoDialog::Apply);
90 *
91 * FooWidget *widget = new FooWidget(dialog);
92 * dialog->setMainWidget(widget);
93 * connect(dialog, SIGNAL(applyClicked()), widget, SLOT(save()));
94 * connect(dialog, SIGNAL(okClicked()), widget, SLOT(save()));
95 * connect(widget, SIGNAL(changed(bool)), dialog, SLOT(enableButtonApply(bool)));
96 *
97 * dialog->enableButtonApply(false);
98 * dialog->show();
99 * \endcode
100 *
101 * This class can be used in many ways. Note that most KDE ui widgets
102 * and many of KDE core applications use the KoDialog so for more
103 * inspiration you should study the code for these.
104 *
105 *
106 * @see KPageDialog
107 * @author Thomas Tanghus <[email protected]>
108 * @author Espen Sand <[email protected]>
109 * @author Mirko Boehm <[email protected]>
110 * @author Olivier Goffart <ogoffart at kde.org>
111 * @author Tobias Koenig <[email protected]>
112 */
113 class KOWIDGETS_EXPORT KoDialog : public QDialog //krazy:exclude=qclasses
114 {
115 Q_OBJECT
116 Q_DECLARE_PRIVATE(KoDialog)
117
118 public:
119
120 enum ButtonCode {
121 None = 0x00000000,
122 Help = 0x00000001, ///< Show Help button. (this button will run the help set with setHelp)
123 Default = 0x00000002, ///< Show Default button.
124 Ok = 0x00000004, ///< Show Ok button. (this button accept()s the dialog; result set to QDialog::Accepted)
125 Apply = 0x00000008, ///< Show Apply button.
126 Try = 0x00000010, ///< Show Try button.
127 Cancel = 0x00000020, ///< Show Cancel-button. (this button reject()s the dialog; result set to QDialog::Rejected)
128 Close = 0x00000040, ///< Show Close-button. (this button closes the dialog)
129 Reset = 0x00000200, ///< Show Reset button
130 Details = 0x00000400, ///< Show Details button. (this button will show the detail widget set with setDetailsWidget)
131 User1 = 0x00001000, ///< Show User defined button 1.
132 User2 = 0x00002000, ///< Show User defined button 2.
133 User3 = 0x00004000, ///< Show User defined button 3.
134 NoDefault = 0x00008000 ///< Used when specifying a default button; indicates that no button should be marked by default.
135 };
136 Q_ENUM(ButtonCode)
137 // TODO KDE5: remove NoDefault and use the value None instead
138 Q_DECLARE_FLAGS(ButtonCodes, ButtonCode)
139
140 enum ButtonPopupMode {
141 InstantPopup = 0,
142 DelayedPopup = 1
143 };
144 Q_DECLARE_FLAGS(ButtonPopupModes, ButtonPopupMode)
145
146 public:
147 /**
148 * Creates a dialog.
149 *
150 * @param parent The parent of the dialog.
151 * @param flags The widget flags passed to the QDialog constructor
152 */
153 explicit KoDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags());
154
155 /**
156 * Destroys the dialog.
157 */
158 ~KoDialog() override;
159
160 /**
161 * Creates (or recreates) the button box and all the buttons in it.
162 *
163 * Note that some combinations are not possible. That means, you can't
164 * have the following pairs of buttons in a dialog:
165 * - Default and Details
166 * - Cancel and Close
167 * - Ok and Try
168 *
169 * This will reset all default KGuiItem of all button.
170 *
171 * @param buttonMask Specifies what buttons will be made.
172 *
173 * @deprecated Since 5.0 use QDialogButtonBox
174 */
175 void setButtons(ButtonCodes buttonMask);
176
177 /**
178 * Sets the orientation of the button box.
179 *
180 * It can be @p Vertical or @p Horizontal. If @p Horizontal
181 * (default), the button box is positioned at the bottom of the
182 * dialog. If @p Vertical it will be placed at the right edge of the
183 * dialog.
184 *
185 * @param orientation The button box orientation.
186 */
187 void setButtonsOrientation(Qt::Orientation orientation);
188
189 /**
190 * Sets the button that will be activated when the Escape key
191 * is pressed.
192 *
193 * By default, the Escape key is mapped to either the Cancel or the Close button
194 * if one of these buttons are defined. The user expects that Escape will
195 * cancel an operation so use this function with caution.
196 *
197 * @param id The button code.
198 */
199 void setEscapeButton(ButtonCode id);
200
201 /**
202 * Sets the button that will be activated when the Enter key
203 * is pressed.
204 *
205 * By default, this is the Ok button if it is present
206 *
207 * @param id The button code.
208 */
209 void setDefaultButton(ButtonCode id);
210
211 /**
212 * Returns the button code of the default button,
213 * or NoDefault if there is no default button.
214 */
215 ButtonCode defaultButton() const;
216
217 /**
218 * Hide or display the a separator line drawn between the action
219 * buttons an the main widget.
220 */
221 void showButtonSeparator(bool state);
222
223 /**
224 * Hide or display a general action button.
225 *
226 * Only buttons that have
227 * been created in the constructor can be displayed. This method will
228 * not create a new button.
229 *
230 * @param id Button identifier.
231 * @param state true display the button(s).
232 */
233 void showButton(ButtonCode id, bool state);
234
235 /**
236 * Sets the text of any button.
237 *
238 * @param id The button identifier.
239 * @param text Button text.
240 */
241 void setButtonText(ButtonCode id, const QString &text);
242
243 /**
244 * Returns the text of any button.
245 */
246 QString buttonText(ButtonCode id) const;
247
248 /**
249 * Sets the icon of any button.
250 *
251 * @param id The button identifier.
252 * @param icon Button icon.
253 */
254 void setButtonIcon(ButtonCode id, const QIcon &icon);
255
256 /**
257 * Returns the icon of any button.
258 */
259 QIcon buttonIcon(ButtonCode id) const;
260
261 /**
262 * Sets the tooltip text of any button.
263 *
264 * @param id The button identifier.
265 * @param text Button text.
266 */
267 void setButtonToolTip(ButtonCode id, const QString &text);
268
269 /**
270 * Returns the tooltip of any button.
271 */
272 QString buttonToolTip(ButtonCode id) const;
273
274 /**
275 * Sets the "What's this?" text of any button.
276 *
277 * @param id The button identifier.
278 * @param text Button text.
279 */
280 void setButtonWhatsThis(ButtonCode id, const QString &text);
281
282 /**
283 * Returns the "What's this?" text of any button.
284 */
285 QString buttonWhatsThis(ButtonCode id) const;
286
287 /**
288 * Sets the KGuiItem directly for the button instead of using 3 methods to
289 * set the text, tooltip and whatsthis strings. This also allows to set an
290 * icon for the button which is otherwise not possible for the extra
291 * buttons beside Ok, Cancel and Apply.
292 *
293 * @param id The button identifier.
294 * @param item The KGuiItem for the button.
295 */
296 void setButtonGuiItem(ButtonCode id, const KGuiItem &item);
297
298 /**
299 * Sets the focus to the button of the passed @p id.
300 */
301 void setButtonFocus(ButtonCode id);
302
303 /**
304 * Convenience method. Sets the initial dialog size.
305 *
306 * This method should only be called right before show() or exec().
307 * The initial size will be ignored if smaller than
308 * the dialog's minimum size.
309 *
310 * @param size Startup size.
311 */
312 void setInitialSize(const QSize &size);
313
314 /**
315 * Convenience method. Add a size to the default minimum size of a
316 * dialog.
317 *
318 * This method should only be called right before show() or exec().
319 *
320 * @param size Size added to minimum size.
321 */
322 void incrementInitialSize(const QSize &size);
323
324 /**
325 * Returns the help link text.
326 *
327 * If no text has been defined,
328 * "Get help..." (internationalized) is returned.
329 *
330 * @return The help link text.
331 *
332 * @see enableLinkedHelp()
333 * @see setHelpLinkText()
334 * @see setHelp()
335 */
336 QString helpLinkText() const;
337
338 /**
339 * Returns whether any button is enabled.
340 */
341 bool isButtonEnabled(ButtonCode id) const;
342
343 /**
344 * Returns the button that corresponds to the @p id.
345 *
346 * Normally you should not use this function.
347 * @em Never delete the object returned by this function.
348 * See also enableButton(), showButton(), setButtonGuiItem().
349 *
350 * @param id Identifier of the button.
351 * @return The button or 0 if the button does not exist.
352 */
353 QPushButton *button(ButtonCode id) const;
354
355 /**
356 * @enum CaptionFlag
357 * Used to specify how to construct a window caption
358 *
359 * @var NoCaptionFlags Indicates that the method has no caption flags.
360 * @var AppNameCaption Indicates that the method shall include
361 * the application name when making the caption string.
362 * @var ModifiedCaption Causes a 'modified' sign will be included in the
363 * returned string. This is useful when indicating that a file is
364 * modified, i.e., it contains data that has not been saved.
365 * @var HIGCompliantCaption The base minimum flags required to align a
366 * caption with the KDE Human Interface Guidelines
367 */
368 enum CaptionFlag {
369 NoCaptionFlags = 0,
370 AppNameCaption = 1,
371 ModifiedCaption = 2,
372 HIGCompliantCaption = AppNameCaption
373 };
374 Q_DECLARE_FLAGS(CaptionFlags, CaptionFlag)
375
376 /**
377 * Builds a caption that contains the application name along with the
378 * userCaption using a standard layout.
379 *
380 * To make a compliant caption for your window, simply do:
381 * @p setWindowTitle(KoDialog::makeStandardCaption(yourCaption));
382 *
383 * To ensure that the caption is appropriate to the desktop in which the
384 * application is running, pass in a pointer to the window the caption will
385 * be applied to.
386 *
387 * If using a KoDialog or KMainWindow subclass, call setCaption instead and
388 * an appropriate standard caption will be created for you
389 *
390 * @param userCaption The caption string you want to display in the
391 * window caption area. Do not include the application name!
392 * @param window a pointer to the window this application will apply to
393 * @param flags
394 * @return the created caption
395 */
396 static QString makeStandardCaption(const QString &userCaption,
397 QWidget *window = nullptr,
398 CaptionFlags flags = HIGCompliantCaption);
399
400 /**
401 * Resize every layout manager used in @p widget and its nested children.
402 *
403 * @param widget The widget used.
404 * @param margin The new layout margin.
405 * @param spacing The new layout spacing.
406 *
407 * @deprecated Use QLayout functions where necessary. Setting margin and spacing
408 * values recursively for all children prevents QLayout from creating platform native
409 * layouts.
410 */
411 static void resizeLayout(QWidget *widget, int margin, int spacing);
412
413 /**
414 * Resize every layout associated with @p lay and its children.
415 *
416 * @param lay layout to be resized
417 * @param margin The new layout margin
418 * @param spacing The new layout spacing
419 *
420 * @deprecated Use QLayout functions where necessary. Setting margin and spacing
421 * values recursively for all children prevents QLayout from creating platform native
422 * layouts.
423 */
424 static void resizeLayout(QLayout *lay, int margin, int spacing);
425
426 /**
427 * Sets the main widget of the dialog.
428 */
429 void setMainWidget(QWidget *widget);
430
431 /**
432 * @return The current main widget. Will create a QWidget as the mainWidget
433 * if none was set before. This way you can write
434 * \code
435 * ui.setupUi(mainWidget());
436 * \endcode
437 * when using designer.
438 */
439 QWidget *mainWidget();
440
441 /**
442 * Reimplemented from QDialog.
443 */
444 QSize sizeHint() const override;
445
446 /**
447 * Reimplemented from QDialog.
448 */
449 QSize minimumSizeHint() const override;
450
451 /**
452 * Returns the status of the Details button.
453 */
454 bool isDetailsWidgetVisible() const;
455
456 public Q_SLOTS:
457 /**
458 * Make a KDE compliant caption.
459 *
460 * @param caption Your caption. Do @p not include the application name
461 * in this string. It will be added automatically according to the KDE
462 * standard.
463 *
464 * @deprecated Since 5.0 use QWidget::setWindowTitle
465 */
466 virtual void setCaption(const QString &caption);
467
468 /**
469 * Makes a KDE compliant caption.
470 *
471 * @param caption Your caption. @em Do @em not include the application name
472 * in this string. It will be added automatically according to the KDE
473 * standard.
474 * @param modified Specify whether the document is modified. This displays
475 * an additional sign in the title bar, usually "**".
476 *
477 * @deprecated Since 5.0 use QWidget::setWindowTitle and QWidget::setWindowModified.
478 */
479 virtual void setCaption(const QString &caption, bool modified);
480
481 /**
482 * Make a plain caption without any modifications.
483 *
484 * @param caption Your caption. This is the string that will be
485 * displayed in the window title.
486 */
487 virtual void setPlainCaption(const QString &caption);
488
489 /**
490 * Enable or disable (gray out) a general action button.
491 *
492 * @param id Button identifier.
493 * @param state @p true enables the button(s).
494 */
495 void enableButton(KoDialog::ButtonCode id, bool state);
496
497 /**
498 * Enable or disable (gray out) the OK button.
499 *
500 * @param state @p true enables the button.
501 */
502 void enableButtonOk(bool state);
503
504 /**
505 * Enable or disable (gray out) the Apply button.
506 *
507 * @param state true enables the button.
508 */
509 void enableButtonApply(bool state);
510
511 /**
512 * Enable or disable (gray out) the Cancel button.
513 *
514 * @param state true enables the button.
515 */
516 void enableButtonCancel(bool state);
517
518 /**
519 * Display or hide the help link area on the top of the dialog.
520 *
521 * @param state @p true will display the area.
522 *
523 * @see helpLinkText()
524 * @see setHelpLinkText()
525 * @see setHelp()
526 */
527 void enableLinkedHelp(bool state);
528
529 /**
530 * Sets the text that is shown as the linked text.
531 *
532 * If text is empty,
533 * the text "Get help..." (internationalized) is used instead.
534 *
535 * @param text The link text.
536 *
537 * @see helpLinkText()
538 * @see enableLinkedHelp()
539 * @see setHelp()
540 */
541 void setHelpLinkText(const QString &text);
542
543 /**
544 * Sets the help path and topic.
545 *
546 * @param anchor Defined anchor in your docbook sources
547 * @param appname Defines the appname the help belongs to
548 * If empty it's the current one
549 *
550 * @note The help button works differently for the class
551 * KCMultiDialog, so it does not make sense to call this
552 * function for Dialogs of that type. See
553 * KCMultiDialog::slotHelp() for more information.
554 */
555 void setHelp(const QString &anchor, const QString &appname = QString());
556
557 /**
558 * Sets the status of the Details button.
559 */
560 void setDetailsWidgetVisible(bool visible);
561
562 /**
563 * Sets the widget that gets shown when "Details" is enabled.
564 *
565 * The dialog takes over ownership of the widget.
566 * Any previously set widget gets deleted.
567 */
568 void setDetailsWidget(QWidget *detailsWidget);
569
570 /**
571 * Destruct the dialog delayed.
572 *
573 * You can call this function from slots like closeClicked() and hidden().
574 * You should not use the dialog any more after calling this function.
575 * @deprecated use hide()+deleteLater()
576 */
577 void delayedDestruct();
578
579 Q_SIGNALS:
580 /**
581 * Emitted when the margin size and/or spacing size
582 * have changed.
583 *
584 * Use marginHint() and spacingHint() in your slot
585 * to get the new values.
586 *
587 * @deprecated This signal is not emitted. Listen to QEvent::StyleChange events instead.
588 */
589 void layoutHintChanged();
590
591 /**
592 * The Help button was pressed. This signal is only emitted if
593 * slotButtonClicked() is not replaced
594 */
595 void helpClicked();
596
597 /**
598 * The Default button was pressed. This signal is only emitted if
599 * slotButtonClicked() is not replaced
600 */
601 void defaultClicked();
602
603 /**
604 * The Reset button was pressed. This signal is only emitted if
605 * slotButtonClicked() is not replaced
606 */
607 void resetClicked();
608
609 /**
610 * The User3 button was pressed. This signal is only emitted if
611 * slotButtonClicked() is not replaced
612 */
613 void user3Clicked();
614
615 /**
616 * The User2 button was pressed. This signal is only emitted if
617 * slotButtonClicked() is not replaced
618 */
619 void user2Clicked();
620
621 /**
622 * The User1 button was pressed. This signal is only emitted if
623 * slotButtonClicked() is not replaced
624 */
625 void user1Clicked();
626
627 /**
628 * The Apply button was pressed. This signal is only emitted if
629 * slotButtonClicked() is not replaced
630 */
631 void applyClicked();
632
633 /**
634 * The Try button was pressed. This signal is only emitted if
635 * slotButtonClicked() is not replaced
636 */
637 void tryClicked();
638
639 /**
640 * The OK button was pressed. This signal is only emitted if
641 * slotButtonClicked() is not replaced
642 */
643 void okClicked();
644
645 /**
646 * The Cancel button was pressed. This signal is only emitted if
647 * slotButtonClicked() is not replaced
648 */
649 void cancelClicked();
650
651 /**
652 * The Close button was pressed. This signal is only emitted if
653 * slotButtonClicked() is not replaced
654 */
655 void closeClicked();
656
657 /**
658 * A button has been pressed. This signal is only emitted if
659 * slotButtonClicked() is not replaced
660 * @param button is the code of the pressed button.
661 */
662 void buttonClicked(KoDialog::ButtonCode button);
663
664 /**
665 * The dialog is about to be hidden.
666 *
667 * A dialog is hidden after a user clicks a button that ends
668 * the dialog or when the user switches to another desktop or
669 * minimizes the dialog.
670 */
671 void hidden();
672
673 /**
674 * The detailsWidget is about to get shown. This is your last chance
675 * to call setDetailsWidget if you haven't done so yet.
676 */
677 void aboutToShowDetails();
678
679 protected:
680 /**
681 * Emits the #hidden signal. You can connect to that signal to
682 * detect when a dialog has been closed.
683 */
684 void hideEvent(QHideEvent *) override;
685
686 /**
687 * Detects when a dialog is being closed from the window manager
688 * controls. If the Cancel or Close button is present then the button
689 * is activated. Otherwise standard QDialog behavior
690 * will take place.
691 */
692 void closeEvent(QCloseEvent *e) override;
693
694 /**
695 * @internal
696 */
697 void keyPressEvent(QKeyEvent *) override;
698
699 protected Q_SLOTS:
700 /**
701 * Activated when the button @p button is clicked
702 *
703 * Sample that shows how to catch and handle button clicks within
704 * an own dialog;
705 * @code
706 * class MyDialog : public KoDialog {
707 * protected Q_SLOTS:
708 * virtual void slotButtonClicked(int button) {
709 * if (button == KoDialog::Ok)
710 * accept();
711 * else
712 * KoDialog::slotButtonClicked(button);
713 * }
714 * }
715 * @endcode
716 *
717 * @param button is the type @a KoDialog::ButtonCode
718 *
719 * @deprecated since 5.0 use QDialogButtonBox and connect to the clicked signal
720 */
721 virtual void slotButtonClicked(int button);
722
723 /**
724 * Updates the margins and spacings.
725 *
726 * @deprecated KoDialog respects the style's margins and spacings automatically. Calling
727 * this function has no effect.
728 */
729 void updateGeometry();
730
731 private:
732 KoDialog(KoDialogPrivate &dd, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags());
733 KoDialogPrivate *const d_ptr;
734
735 private:
736 Q_DISABLE_COPY(KoDialog)
737 Q_PRIVATE_SLOT(d_ptr, void queuedLayoutUpdate())
738 Q_PRIVATE_SLOT(d_ptr, void helpLinkClicked())
739 };
740
741 Q_DECLARE_OPERATORS_FOR_FLAGS(KoDialog::ButtonCodes)
742 Q_DECLARE_OPERATORS_FOR_FLAGS(KoDialog::CaptionFlags)
743
744 #endif // KODIALOG_H