File indexing completed on 2024-04-28 15:28:58
0001 /* 0002 This file is part of KNewStuffCore. 0003 SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <admin@leinir.dk> 0004 0005 SPDX-License-Identifier: LGPL-2.1-or-later 0006 */ 0007 0008 #ifndef KNS3_QUESTION_H 0009 #define KNS3_QUESTION_H 0010 0011 #include <QObject> 0012 0013 #include "knewstuffcore_export.h" 0014 0015 #include <memory> 0016 0017 namespace KNSCore 0018 { 0019 class EntryInternal; 0020 class QuestionPrivate; 0021 /** 0022 * @short A way to ask a user a question from inside a GUI-less library (like KNewStuffCore) 0023 * 0024 * Rather than using a message box (which is a UI thing), when you want to ask your user 0025 * a question, create an instance of this class and use that instead. The consuming library 0026 * (in most cases KNewStuff or KNewStuffQuick) will listen to any question being asked, 0027 * and act appropriately (that is, KNewStuff will show a dialog with an appropriate dialog 0028 * box, and KNewStuffQuick will either request a question be asked if the developer is using 0029 * the plugin directly, or ask the question using an appropriate method for Qt Quick based 0030 * applications) 0031 * 0032 * The following is an example of a question asking the user to select an item from a list. 0033 * 0034 * @code 0035 QStringList choices() << "foo" << "bar"; 0036 Question question(Question::SelectFromListQuestion); 0037 question.setTitle("Pick your option"); 0038 question.setQuestion("Please select which option you would like"); 0039 question.setList(choices); 0040 question.setEntry(entry); 0041 if(question.ask() == Question::OKResponse) { 0042 QString theChoice = question.response(); 0043 } 0044 @endcode 0045 */ 0046 class KNEWSTUFFCORE_EXPORT Question : public QObject 0047 { 0048 Q_OBJECT 0049 public: 0050 enum Response { 0051 InvalidResponse = 0, 0052 YesResponse = 1, 0053 NoResponse = 2, 0054 ContinueResponse = 3, 0055 CancelResponse = 4, 0056 OKResponse = YesResponse, 0057 }; 0058 Q_ENUM(Response) 0059 0060 enum QuestionType { 0061 YesNoQuestion = 0, 0062 ContinueCancelQuestion = 1, 0063 InputTextQuestion = 2, 0064 SelectFromListQuestion = 3, 0065 PasswordQuestion = 4, 0066 }; 0067 Q_ENUM(QuestionType) 0068 0069 explicit Question(QuestionType = YesNoQuestion, QObject *parent = nullptr); 0070 ~Question() override; 0071 0072 Response ask(); 0073 0074 void setQuestionType(QuestionType newType = YesNoQuestion); 0075 QuestionType questionType() const; 0076 0077 void setQuestion(const QString &newQuestion); 0078 QString question() const; 0079 void setTitle(const QString &newTitle); 0080 QString title() const; 0081 void setList(const QStringList &newList); 0082 QStringList list() const; 0083 void setEntry(const EntryInternal &entry); 0084 EntryInternal entry() const; 0085 0086 /** 0087 * When the user makes a choice on a question, that is a response. This is the return value in ask(). 0088 * @param response This will set the response, and mark the question as answered 0089 */ 0090 void setResponse(Response response); 0091 /** 0092 * If the user has any way of inputting data to go along with the response above, consider this a part 0093 * of the response. As such, you can set, and later get, that response as well. This does NOT mark the 0094 * question as answered ( @see setResponse(Response) ). 0095 * @param response This sets the string response for the question 0096 */ 0097 void setResponse(const QString &response); 0098 QString response() const; 0099 0100 private: 0101 const std::unique_ptr<QuestionPrivate> d; 0102 }; 0103 } 0104 0105 #endif // KNS3_QUESTION_H