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