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 | |
27 | class KPushButton; |
28 | class ; |
29 | class 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 | */ |
128 | class 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 |
159 | { |
160 | = 0, |
161 | = 1 |
162 | }; |
163 | Q_DECLARE_FLAGS(, 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 ( ButtonCode id, QMenu *, ButtonPopupMode =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 | |
863 | Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::ButtonCodes) |
864 | Q_DECLARE_OPERATORS_FOR_FLAGS(KDialog::CaptionFlags) |
865 | |
866 | #endif // KDIALOG_H |
867 | |