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 namespace KNSCore 16 { 17 /** 18 * @short A way to ask a user a question from inside a GUI-less library (like KNewStuffCore) 19 * 20 * Rather than using a message box (which is a UI thing), when you want to ask your user 21 * a question, create an instance of this class and use that instead. The consuming library 22 * (in most cases KNewStuff or KNewStuffQuick) will listen to any question being asked, 23 * and act appropriately (that is, KNewStuff will show a dialog with an appropriate dialog 24 * box, and KNewStuffQuick will either request a question be asked if the developer is using 25 * the plugin directly, or ask the question using an appropriate method for Qt Quick based 26 * applications) 27 * 28 * The following is an example of a question asking the user to select an item from a list. 29 * 30 * @code 31 QStringList choices() << "foo" << "bar"; 32 Question question(Question::SelectFromListQuestion); 33 question.setTitle("Pick your option"); 34 question.setQuestion("Please select which option you would like"); 35 question.setList(choices); 36 if(question.ask() == Question::OKResponse) { 37 QString theChoice = question.response(); 38 } 39 @endcode 40 */ 41 class KNEWSTUFFCORE_EXPORT Question : public QObject 42 { 43 Q_OBJECT 44 public: 45 enum Response { 46 InvalidResponse = 0, 47 YesResponse = 1, 48 NoResponse = 2, 49 ContinueResponse = 3, 50 CancelResponse = 4, 51 OKResponse = YesResponse, 52 }; 53 Q_ENUM(Response) 54 55 enum QuestionType { 56 YesNoQuestion = 0, 57 ContinueCancelQuestion = 1, 58 InputTextQuestion = 2, 59 SelectFromListQuestion = 3, 60 PasswordQuestion = 4, 61 }; 62 Q_ENUM(QuestionType) 63 64 explicit Question(QuestionType = YesNoQuestion, QObject *parent = nullptr); 65 ~Question() override; 66 67 Response ask(); 68 69 void setQuestionType(QuestionType newType = YesNoQuestion); 70 QuestionType questionType() const; 71 72 void setQuestion(const QString &newQuestion); 73 QString question() const; 74 void setTitle(const QString &newTitle); 75 QString title() const; 76 void setList(const QStringList &newList); 77 QStringList list() const; 78 79 /** 80 * When the user makes a choice on a question, that is a response. This is the return value in ask(). 81 * @param response This will set the response, and mark the question as answered 82 */ 83 void setResponse(Response response); 84 /** 85 * If the user has any way of inputting data to go along with the response above, consider this a part 86 * of the response. As such, you can set, and later get, that response as well. This does NOT mark the 87 * question as answered ( @see setResponse(Response) ). 88 * @param response This sets the string response for the question 89 */ 90 void setResponse(const QString &response); 91 QString response() const; 92 93 private: 94 class Private; 95 Private *d; 96 }; 97 } 98 99 #endif // KNS3_QUESTION_H 100