KNewStuff

question.h
1 /*
2  This file is part of KNewStuffCore.
3  SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <[email protected]>
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  virtual ~Question();
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
A way to ask a user a question from inside a GUI-less library (like KNewStuffCore) ...
Definition: question.h:41
Contains the core functionality for handling interaction with NewStuff providers. ...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 26 2021 22:43:05 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.