1 | /* |
2 | This file is part of KNewStuffCore. |
3 | SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <admin@leinir.dk> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.1-or-later |
6 | */ |
7 | |
8 | #ifndef KNS3_QUESTION_H |
9 | #define KNS3_QUESTION_H |
10 | |
11 | #include <QObject> |
12 | |
13 | #include "knewstuffcore_export.h" |
14 | |
15 | #include <memory> |
16 | |
17 | namespace KNSCore |
18 | { |
19 | class Entry; |
20 | class QuestionPrivate; |
21 | /*! |
22 | \class KNSCore::Question |
23 | \inmodule KNewStuffCore |
24 | |
25 | \brief A way to ask a user a question from inside a GUI-less library (like KNewStuffCore). |
26 | |
27 | Rather than using a message box (which is a UI thing), when you want to ask your user |
28 | a question, create an instance of this class and use that instead. The consuming library |
29 | (in most cases KNewStuff or KNewStuffQuick) will listen to any question being asked, |
30 | and act appropriately (that is, KNewStuff will show a dialog with an appropriate dialog |
31 | box, and KNewStuffQuick will either request a question be asked if the developer is using |
32 | the plugin directly, or ask the question using an appropriate method for Qt Quick based |
33 | applications) |
34 | |
35 | The following is an example of a question asking the user to select an item from a list. |
36 | |
37 | \code |
38 | QStringList choices() << "foo" << "bar"; |
39 | Question question(Question::SelectFromListQuestion); |
40 | question.setTitle("Pick your option"); |
41 | question.setQuestion("Please select which option you would like"); |
42 | question.setList(choices); |
43 | question.setEntry(entry); |
44 | if (question.ask() == Question::OKResponse) { |
45 | QString theChoice = question.response(); |
46 | } |
47 | \endcode |
48 | */ |
49 | class KNEWSTUFFCORE_EXPORT Question : public QObject |
50 | { |
51 | Q_OBJECT |
52 | public: |
53 | /*! |
54 | * \enum KNSCore::Question::Response |
55 | * |
56 | * \brief Defines how the user responded to the question. |
57 | * |
58 | * \sa QuestionType |
59 | * |
60 | * \value InvalidResponse |
61 | * The user did not provide a valid response. |
62 | * |
63 | * \value YesResponse |
64 | * The user selected yes. |
65 | * |
66 | * \value NoResponse |
67 | * The user selected no. |
68 | * |
69 | * \value ContinueResponse |
70 | * The user selected continue. |
71 | * |
72 | * \value CancelResponse |
73 | * The user selected cancel. |
74 | * |
75 | * \value OKResponse |
76 | * The user selected OK. |
77 | */ |
78 | enum Response { |
79 | InvalidResponse = 0, |
80 | YesResponse = 1, |
81 | NoResponse = 2, |
82 | ContinueResponse = 3, |
83 | CancelResponse = 4, |
84 | OKResponse = YesResponse, |
85 | }; |
86 | Q_ENUM(Response) |
87 | |
88 | /*! |
89 | * \enum KNSCore::Question::QuestionType |
90 | * |
91 | * \brief Defines the type of question to be presented to the user. |
92 | * |
93 | * \sa Response |
94 | * |
95 | * \value YesNoQuestion |
96 | * The question can be answered with either yes or no. |
97 | * |
98 | * \value ContinueCancelQuestion |
99 | * The question can be answered with either continue or cancel. |
100 | * |
101 | * \value InputTextQuestion |
102 | * Answering the question requires text input from the user. |
103 | * |
104 | * \value SelectFromListQuestion |
105 | * Answering the question requires selecting from a list of choices. |
106 | * |
107 | * \value PasswordQuestion |
108 | * Answering the question requires the user to input a password. |
109 | */ |
110 | enum QuestionType { |
111 | YesNoQuestion = 0, |
112 | ContinueCancelQuestion = 1, |
113 | InputTextQuestion = 2, |
114 | SelectFromListQuestion = 3, |
115 | PasswordQuestion = 4, |
116 | }; |
117 | Q_ENUM(QuestionType) |
118 | |
119 | explicit Question(QuestionType = YesNoQuestion, QObject *parent = nullptr); |
120 | ~Question() override; |
121 | |
122 | /*! |
123 | * Returns the user's reponse to the question. |
124 | * |
125 | * \sa setResponse |
126 | */ |
127 | Response ask(); |
128 | |
129 | /*! |
130 | * Sets the type of question presented to the user. |
131 | * |
132 | * \a newType is the question type |
133 | */ |
134 | void setQuestionType(QuestionType newType = YesNoQuestion); |
135 | |
136 | /*! |
137 | * Returns the configured question type. |
138 | */ |
139 | QuestionType questionType() const; |
140 | |
141 | /*! |
142 | * Sets the question to be presented to the user. |
143 | * |
144 | * \a newQuestion is the question message |
145 | * |
146 | */ |
147 | void setQuestion(const QString &newQuestion); |
148 | |
149 | /*! |
150 | * Returns the question message to be presented to the user. |
151 | */ |
152 | QString question() const; |
153 | |
154 | /*! |
155 | * Sets the title of the UX element presented to the user. |
156 | * |
157 | * \a newTitle is the title text |
158 | */ |
159 | void setTitle(const QString &newTitle); |
160 | |
161 | /*! |
162 | * Returns the title of the UX element. |
163 | */ |
164 | QString title() const; |
165 | |
166 | /*! |
167 | * Sets the list of optional choices to present to the user to \a newList |
168 | * for a SelectFromListQuestion. |
169 | */ |
170 | void setList(const QStringList &newList); |
171 | |
172 | /*! |
173 | * Returns the list of choices to present to the user, if any. |
174 | */ |
175 | QStringList list() const; |
176 | |
177 | /*! |
178 | * Sets the data \a entry container this question refers to. |
179 | */ |
180 | void setEntry(const Entry &entry); |
181 | |
182 | /*! |
183 | * Returns the configured entry. |
184 | */ |
185 | Entry entry() const; |
186 | |
187 | /*! |
188 | * When the user makes a choice on a question, that is a response. This is the return value in ask(). |
189 | * |
190 | * \a response This will set the response, and mark the question as answered |
191 | * |
192 | */ |
193 | void setResponse(Response response); |
194 | |
195 | /*! |
196 | * If the user has any way of inputting data to go along with the response above, consider this a part |
197 | * of the response. As such, you can set, and later get, that response as well. This does NOT mark the |
198 | * question as answered. |
199 | * |
200 | * \a response This sets the string response for the question |
201 | * |
202 | * \sa setResponse |
203 | */ |
204 | void setResponse(const QString &response); |
205 | |
206 | /*! |
207 | * Returns the response data provided by the user, if any. |
208 | */ |
209 | QString response() const; |
210 | |
211 | private: |
212 | const std::unique_ptr<QuestionPrivate> d; |
213 | }; |
214 | } |
215 | |
216 | #endif // KNS3_QUESTION_H |
217 | |