src/InterviewCursor.h

   1 /*
   2  * This file is part of the vng project
   3  * Copyright (C) 2008 Thomas Zander <tzander@trolltech.com>
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef INTERVIEWCURSOR_H
  20 #define INTERVIEWCURSOR_H
  21
  22 #include <QString>
  23
  24 class Configuration;
  25
  26 class InterviewCursor
  27 {
  28 public:
  29     enum Scope {
  30         ItemScope,
  31         BlockScope,
  32         FullRange
  33     };
  34
  35     InterviewCursor();
  36     virtual ~InterviewCursor();
  37
  38     void setConfiguration(Configuration &config) {
  39         m_config = &config;
  40     }
  41
  42     /**
  43      * Moves the cursor forward in the list.
  44      * returns the new index.
  45      * Moving the cursor past the last item will make isValid() return false.
  46      */
  47     virtual int forward(Scope scope = ItemScope, bool skipAnswered = true) = 0;
  48
  49     /**
  50      * Moves the cursor backwards in the list.
  51      * returns the new index.
  52      * This method can not move the cursor to be before the first item.
  53      */
  54     virtual int back(Scope scope = ItemScope) = 0;
  55     virtual void setResponse(bool response, Scope scope = ItemScope) = 0;
  56     virtual QString currentText() const = 0;
  57
  58     /**
  59      * Returns true if the item the cursor is on is a valid one.  The cursor can point to an invalid item when there
  60      * are no items in the document, or when the cursor moved past the end of the list.
  61      */
  62     virtual bool isValid() const = 0;
  63
  64     /**
  65      * Returns the amount of items in the list, or -1 if the amount is not fully determined yet.
  66      * @see forceCount()
  67      */
  68     virtual int count() = 0;
  69
  70     /**
  71      * Will force a count of all items, potentially blocking for extended times while counting.
  72      * Afterwards the count() method will return a valid count.
  73      */
  74     virtual void forceCount() = 0;
  75
  76     virtual QString helpMessage() const = 0;
  77
  78     /**
  79      * Returns all the interview options that the user can use on this cursor as a concatanated string.
  80      * Each option is encoded using one character, as follows;
  81      *  y  allow the user to accept the current item.
  82      *  n  allow the user to decline the current item.
  83      *  s  allow the user to skip over a whole block.
  84      *  f  allow the user to accept all items in the block and skip over it.
  85      *  q  allow the user to cancel the interaction.
  86      *  a  allow the user to accept all remainting items.
  87      *  d  allow the user to indicate the interaction is succesfully completed.
  88      *  j  allow the user to forward to the next item without indicating either yes or no.
  89      *  k  allow the user to go back to the previos item without indicating either yes or no.
  90      *  c  allow the user to calculate the total number of items.
  91      */
  92     virtual QString allowedOptions() const = 0;
  93
  94 protected:
  95     Configuration *m_config;
  96 };
  97
  98 #endif