KDirStat – a graphical disk usage utility
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

kfeedback.h 11KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463
  1. /*
  2. * File name: kfeedback.h
  3. * Summary: User feedback form and mailing utilities
  4. * License: LGPL - See file COPYING.LIB for details.
  5. * Author: Stefan Hundhammer <sh@suse.de>
  6. *
  7. * Updated: 2003-01-07
  8. */
  9. #ifndef KFeedback_h
  10. #define KFeedback_h
  11. #ifdef HAVE_CONFIG_H
  12. #include <config.h>
  13. #endif
  14. #include <tqlistview.h>
  15. #include <tqvbox.h>
  16. #include <kdialogbase.h>
  17. #ifndef NOT_USED
  18. # define NOT_USED(PARAM) ( (void) (PARAM) )
  19. #endif
  20. class KFeedbackForm;
  21. class KFeedbackQuestionList;
  22. class KFeedbackQuestion;
  23. class KFeedbackAnswer;
  24. class TQMultiLineEdit;
  25. /**
  26. * Dialog containing a @ref KFeedbackForm and all the infrastructure for
  27. * sending a mail etc.
  28. **/
  29. class KFeedbackDialog: public KDialogBase
  30. {
  31. Q_OBJECT
  32. public:
  33. /**
  34. * Constructor.
  35. **/
  36. KFeedbackDialog( const TQString & feedbackMailAddress,
  37. const TQString & helpTopic = TQString() );
  38. /**
  39. * Destructor.
  40. **/
  41. virtual ~KFeedbackDialog();
  42. /**
  43. * Returns the internal @KFeedbackForm
  44. **/
  45. KFeedbackForm *form() { return _form; }
  46. public slots:
  47. /**
  48. * Check if sufficient information is available to send a mail now and
  49. * enable / disable the "send mail" button accordingly.
  50. **/
  51. void checkSendButton();
  52. signals:
  53. /**
  54. * Emitted when the user has sent the feedback mail - i.e. when he clicked
  55. * on the "Send mail" button and the mail has successfully been forwarded
  56. * to the mailer. He can still choose not to send the mail from within the
  57. * mailer, though.
  58. **/
  59. void mailSent();
  60. protected:
  61. KFeedbackForm * _form;
  62. };
  63. /**
  64. * User feedback form:
  65. *
  66. * User is asked a list of questions, the answers of which will be sent via
  67. * mail back to a feedback mail address.
  68. **/
  69. class KFeedbackForm: public TQVBox
  70. {
  71. Q_OBJECT
  72. public:
  73. /**
  74. * Constructor.
  75. **/
  76. KFeedbackForm( const TQString & feedbackMailAddress,
  77. TQWidget * parent );
  78. /**
  79. * Destructor.
  80. **/
  81. virtual ~KFeedbackForm();
  82. public slots:
  83. /**
  84. * Compose a mail from the user's answers and send it to the feedback mail
  85. * address passed to the constructor.
  86. *
  87. * This method will check with @ref readyToSend() if the mail can be sent
  88. * with the questions answered until now and prompt the user to answer more
  89. * questions if not.
  90. *
  91. * Connect the @ref mailSent() signal if you are interested when exactly
  92. * all this was successful.
  93. **/
  94. virtual void sendMail();
  95. public:
  96. /**
  97. * Checks if the mail is ready to send, i.e. if all required fields are
  98. * filled.
  99. **/
  100. virtual bool readyToSend();
  101. /**
  102. * Returns the @ref KFeedbackQuestionList .
  103. **/
  104. KFeedbackQuestionList * questionList() { return _questionList; }
  105. signals:
  106. /**
  107. * Emitted when the user has sent the feedback mail - i.e. when he clicked
  108. * on the "Send mail" button and the mail has successfully been forwarded
  109. * to the mailer. He can still choose not to send the mail from within the
  110. * mailer, though.
  111. **/
  112. void mailSent();
  113. /**
  114. * Emitted when it is time to check for completeness of all information in
  115. * this form: Either when a new question is added or when a question is
  116. * answered.
  117. **/
  118. void checkComplete();
  119. protected slots:
  120. /**
  121. * Check for completeness of this form.
  122. **/
  123. void slotCheckComplete();
  124. protected:
  125. /**
  126. * Format the "personal comments" field for sending mail.
  127. **/
  128. TQString formatComment();
  129. TQString _feedbackMailAddress;
  130. KFeedbackQuestionList * _questionList;
  131. TQMultiLineEdit * _comment;
  132. };
  133. /**
  134. * List of feedback questions presented in a @ref TQListView widget.
  135. **/
  136. class KFeedbackQuestionList: public TQListView
  137. {
  138. Q_OBJECT
  139. public:
  140. /**
  141. * Constructor.
  142. **/
  143. KFeedbackQuestionList( TQWidget *parent );
  144. /**
  145. * Destructor.
  146. **/
  147. virtual ~KFeedbackQuestionList();
  148. /**
  149. * Returns whether or not this question list is answered satisfactorily,
  150. * i.e. if all questions marked as "required" are answered.
  151. **/
  152. virtual bool isComplete();
  153. /**
  154. * The result of all answered questions in ASCII.
  155. **/
  156. TQString result();
  157. /**
  158. * Add a yes/no question to the list.
  159. *
  160. * 'text' is the text the user will see (in his native language).
  161. *
  162. * 'id' is what will be sent with the feedback mail, thus it should be
  163. * unique within the application, yet human readable (preferably English)
  164. * and not contain any weird characters that might confuse scripts that are
  165. * later used to automatically parse those mails.
  166. * Examples: "would_recommend_to_a_friend"
  167. *
  168. * Set 'required' to 'true' if answering this question is required to
  169. * successfully complete this form.
  170. *
  171. * Returns a pointer to this question so you can add answers.
  172. **/
  173. KFeedbackQuestion * addQuestion( const TQString & text,
  174. const TQString & id,
  175. bool exclusiveAnswer = true,
  176. bool required = false );
  177. /**
  178. * Add a yes/no question to the list.
  179. **/
  180. void addYesNoQuestion( const TQString & text,
  181. const TQString & id,
  182. bool required = false );
  183. /**
  184. * Returns the first question of that list.
  185. * Use @ref KFeedbackQuestion::next() to get the next one.
  186. **/
  187. KFeedbackQuestion * firstQuestion() const
  188. { return (KFeedbackQuestion *) TQListView::firstChild(); }
  189. /**
  190. * Notify the list that another question has been answered.
  191. * Emits the @ref checkComplete() signal when all required questions are
  192. * answered.
  193. **/
  194. void questionAnswered();
  195. /**
  196. * Notify the list that another question has been added.
  197. * Emits the @ref checkComplete() signal when a required question is
  198. * added.
  199. **/
  200. void questionAdded( KFeedbackQuestion * question );
  201. signals:
  202. /**
  203. * Emitted when all required questions are answered.
  204. **/
  205. void checkComplete();
  206. };
  207. /**
  208. * A user feedback question to be inserted into a @ref KFeedbackQuestionList.
  209. **/
  210. class KFeedbackQuestion: public TQCheckListItem
  211. {
  212. public:
  213. /**
  214. * Constructor.
  215. *
  216. * The parent @ref KFeedbackQuestionList assumes ownership of this object,
  217. * so don't delete it unless you want to delete it from the question list
  218. * as well.
  219. *
  220. * 'text' is the text the user will see (in his native language).
  221. *
  222. * 'id' is what will be sent with the feedback mail, thus it should be
  223. * unique within the application, yet human readable (preferably English)
  224. * and not contain any weird characters that might confuse scripts that are
  225. * later used to automatically parse those mails.
  226. * Examples: "features_not_liked", "stability"
  227. *
  228. * Set 'required' to 'true' if answering this question is required to
  229. * successfully complete this form.
  230. *
  231. * Set 'exclusiveAnswer' to 'true' if only one of all answers may be
  232. * checked at any one time, to 'false' if multiple answers are allowed.
  233. **/
  234. KFeedbackQuestion( KFeedbackQuestionList * parent,
  235. const TQString & text,
  236. const TQString & id,
  237. bool exclusiveAnswer = true,
  238. bool required = false,
  239. bool open = true );
  240. /**
  241. * Add an answer to this question. Again, 'text' is what the user will see
  242. * (translated to his native language), 'id' is what you will get back with
  243. * the mail. The answer IDs need only be unique for that question; answers
  244. * to other questions may have the same ID.
  245. **/
  246. void addAnswer( const TQString & text,
  247. const TQString & id );
  248. /**
  249. * Returns if answering this question is required.
  250. **/
  251. bool isRequired() { return _required; }
  252. /**
  253. * Returns if this question is answered satisfactorily.
  254. **/
  255. bool isAnswered();
  256. /**
  257. * The result of this question in ASCII, e.g.
  258. * recommend="yes"
  259. * or
  260. * features_i_like="builtin_tetris"
  261. * features_i_like="pink_elephant"
  262. * features_i_like="studlycapslyfier"
  263. **/
  264. TQString result();
  265. /**
  266. * Return this question's ID.
  267. **/
  268. TQString id() { return _id; }
  269. /**
  270. * Return this question's text.
  271. **/
  272. TQString text();
  273. /**
  274. * Returns whether or not this question requires an exclusive answer.
  275. **/
  276. bool exclusiveAnswer() { return _exclusiveAnswer; }
  277. /**
  278. * Returns the sort key.
  279. *
  280. * Reimplemented from @ref TQListViewItem to maintain insertion order.
  281. **/
  282. virtual TQString key( int column, bool ascending ) const;
  283. /**
  284. * Returns the next question or 0 if there is no more.
  285. **/
  286. KFeedbackQuestion * nextQuestion() const
  287. { return (KFeedbackQuestion *) TQListViewItem::nextSibling(); }
  288. /**
  289. * Returns the first possible answer to this question.
  290. * Use @ref KFeedbackAnswer::nextAnswer() to get the next one.
  291. **/
  292. KFeedbackAnswer * firstAnswer() const
  293. { return (KFeedbackAnswer *) TQListViewItem::firstChild(); }
  294. /**
  295. * Returns the @ref KFeedbackQuestionList this question belongs to or 0 if
  296. * the parent is no @ref KFeedbackQuestionList.
  297. **/
  298. KFeedbackQuestionList * questionList() const;
  299. protected:
  300. TQString _id;
  301. bool _exclusiveAnswer;
  302. bool _required;
  303. int _no;
  304. };
  305. class KFeedbackAnswer: public TQCheckListItem
  306. {
  307. public:
  308. /**
  309. * Constructor.
  310. *
  311. * 'exclusive' tells the type of answer: One of many allowed or any number
  312. * of many.
  313. **/
  314. KFeedbackAnswer( KFeedbackQuestion * parent,
  315. const TQString & text,
  316. const TQString & id,
  317. bool exclusive = true );
  318. /**
  319. * Return this answer's ID.
  320. **/
  321. TQString id() { return _id; }
  322. /**
  323. * Return this answer's text.
  324. **/
  325. TQString text();
  326. /**
  327. * Returns whether or not this is an exclusive answer.
  328. **/
  329. bool isExclusive() { return _exclusive; }
  330. /**
  331. * Returns whether or not this answer is checked.
  332. **/
  333. bool isChecked() { return TQCheckListItem::isOn(); }
  334. /**
  335. * Returns the next possible answer or 0 if there is no more.
  336. **/
  337. KFeedbackAnswer * nextAnswer() const
  338. { return (KFeedbackAnswer *) TQListViewItem::nextSibling(); }
  339. /**
  340. * Returns the question to this answer.
  341. **/
  342. KFeedbackQuestion * question() const
  343. { return (KFeedbackQuestion *) TQListViewItem::parent(); }
  344. /**
  345. * Returns the sort key.
  346. *
  347. * Reimplemented from @ref TQListViewItem to maintain insertion order.
  348. **/
  349. virtual TQString key( int column, bool ascending ) const;
  350. /**
  351. * On/off change.
  352. *
  353. * Reimplemented from @ref TQCheckListItem to monitor answering required
  354. * questions. This method notifies the @ref KFeedbackQuestionList whenever
  355. * a required question is being answered.
  356. **/
  357. virtual void stateChange( bool newState );
  358. protected:
  359. TQString _id;
  360. bool _exclusive;
  361. int _no;
  362. };
  363. #endif // KFeedback_h
  364. // EOF