1/* This file is part of the KDE libraries
2 Copyright (C) 2006 Olivier Goffart <ogoffart at kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19
20#ifndef KASSISTANTDIALOG_H
21#define KASSISTANTDIALOG_H
22
23#include <kpagedialog.h>
24
25/**
26 * This class provides a framework for assistant dialogs.
27 *
28 * The use of this class is the same as KWizard in KDE3.
29 * You should use the word "assistant" instead of "wizard" both in the source
30 * and translatable strings.
31 *
32 * An assistant dialog consists of a sequence of pages.
33 * Its purpose is to guide the user (assist) through a process step by step.
34 * Assistant dialogs are useful for complex or infrequently occurring tasks
35 * that people may find difficult to learn or do.
36 * Sometimes a task requires too many input fields to fit them on a single dialog.
37 *
38 * KAssistantDialog provides page titles and displays Next, Back, Finish, Cancel,
39 * and Help push buttons, as appropriate to the current position in the page sequence.
40 * The Finish Button has the code KDialog::User1, The Next button is KDialog::User2
41 * and the Back button is KDialog::User3.
42 * The help button may be hidden using showButton(KDialog::Help, false)
43 *
44 * Create and populate dialog pages that inherit from QWidget and add them
45 * to the assistant dialog using addPage().
46 *
47 * The functions next() and back() are virtual and may be reimplemented to
48 * override the default actions of the next and back buttons.
49 *
50 * \image html kassistantdialog.png "KDE Assistant Dialog"
51 *
52 * @author Olivier Goffart <ogoffart at kde.org>
53 */
54class KDEUI_EXPORT KAssistantDialog : public KPageDialog
55{
56 Q_OBJECT
57 public:
58 /**
59 * Construct a new assistant dialog with @p parent as parent.
60 * @param parent is the parent of the widget.
61 * @flags the window flags to give to the assistant dialog. The
62 * default of zero is usually what you want.
63 */
64 explicit KAssistantDialog(QWidget *parent=0, Qt::WindowFlags flags=0);
65 virtual ~KAssistantDialog();
66
67 /**
68 * Specify if the content of the page is valid, and if the next button may be enabled on this page.
69 * By default all pages are valid.
70 *
71 * This will disable or enable the next button on the specified page
72 *
73 * @param page the page on which the next button will be enabled/disable
74 * @param enable if true the next button will be enabled, if false it will be disabled
75 */
76 void setValid(KPageWidgetItem* page, bool enable);
77
78 /**
79 * return if a page is valid
80 * @see setValid
81 * @param page the page to check the validity of
82 */
83 bool isValid(KPageWidgetItem *page) const;
84
85 /**
86 * Specify whether a page is appropriate.
87 *
88 * A page is considered inappropriate if it should not be shown due to
89 * the contents of other pages making it inappropriate.
90 *
91 * A page which is inappropriate will not be shown.
92 *
93 * The last page in an assistant dialog should always be appropriate
94 * @param page the page to set as appropriate
95 * @param appropriate flag indicating the appropriateness of the page.
96 * If @p appropriate is true, then @p page is appropriate and will be
97 * shown in the assistant dialog. If false, @p page will not be shown.
98 */
99 void setAppropriate(KPageWidgetItem *page, bool appropriate);
100
101 /**
102 * Check if a page is appropriate for use in the assistant dialog.
103 * @param page is the page to check the appropriateness of.
104 * @return true if @p page is appropriate, false if it is not
105 */
106 bool isAppropriate(KPageWidgetItem *page) const;
107
108
109 public Q_SLOTS:
110 /**
111 * Called when the user clicks the Back button.
112 *
113 * This function will show the preceding relevant page in the sequence.
114 * Do nothing if the current page is the first page in the sequence.
115 */
116 virtual void back();
117
118 /**
119 * Called when the user clicks the Next/Finish button.
120 *
121 * This function will show the next relevant page in the sequence.
122 * If the current page is the last page, it will call accept()
123 */
124 virtual void next();
125
126 protected:
127 /**
128 * Construct an assistant dialog from a single widget.
129 * @param widget the widget to construct the dialog with
130 * @param parent the parent of the assistant dialog
131 * @flags the window flags to use when creating the widget. The default
132 * of zero is usually fine.
133 *
134 * Calls the KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags) constructor
135 */
136 explicit KAssistantDialog(KPageWidget *widget, QWidget *parent=0, Qt::WindowFlags flags=0);
137
138 virtual void showEvent(QShowEvent * event);
139
140 private:
141 class Private;
142 Private * const d;
143
144 Q_PRIVATE_SLOT( d, void _k_slotUpdateButtons() )
145
146 Q_DISABLE_COPY( KAssistantDialog )
147};
148
149
150#endif
151