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 "Configuration.h"
  23
  24 #include <QString>
  25
  26 class InterviewCursor {
  27 public:
  28     enum Scope {
  29         ItemScope,
  30         BlockScope,
  31         FullRange
  32     };
  33
  34     InterviewCursor();
  35     virtual ~InterviewCursor();
  36
  37     void setConfiguration(Configuration &config) {
  38         m_config = &config;
  39     }
  40
  41     /**
  42      * Moves the cursor forward in the list.
  43      * returns the new index.
  44      * Moving the cursor past the last item will make isValid() return false.
  45      */
  46     virtual int forward(Scope scope = ItemScope, bool skipAnswered = true) = 0;
  47
  48     /**
  49      * Moves the cursor backwards in the list.
  50      * returns the new index.
  51      * This method can not move the cursor to be before the first item.
  52      */
  53     virtual int back(Scope scope = ItemScope) = 0;
  54     virtual void setResponse(bool response, Scope scope = ItemScope) = 0;
  55     virtual QString currentText() const = 0;
  56
  57     /**
  58      * Returns true if the item the cursor is on is a valid one.  The cursor can point to an invalid item when there
  59      * are no items in the document, or when the cursor moved past the end of the list.
  60      */
  61     virtual bool isValid() const = 0;
  62
  63     /**
  64      * Returns the amount of items in the list, or -1 if the amount is not fully determined yet.
  65      * @see forceCount()
  66      */
  67     virtual int count() = 0;
  68
  69     /**
  70      * Will force a count of all items, potentially blocking for extended times while counting.
  71      * Afterwards the count() method will return a valid count.
  72      */
  73     virtual void forceCount() = 0;
  74
  75     virtual QString helpMessage() const = 0;
  76
  77     /**
  78      * Returns all the interview options that the user can use on this cursor as a concatanated string.
  79      * Each option is encoded using one character, as follows;
  80      *  y  allow the user to accept the current item.
  81      *  n  allow the user to decline the current item.
  82      *  s  allow the user to skip over a whole block.
  83      *  f  allow the user to accept all items in the block and skip over it.
  84      *  q  allow the user to cancel the interaction.
  85      *  a  allow the user to accept all remainting items.
  86      *  d  allow the user to indicate the interaction is succesfully completed.
  87      *  j  allow the user to forward to the next item without indicating either yes or no.
  88      *  k  allow the user to go back to the previos item without indicating either yes or no.
  89      *  c  allow the user to calculate the total number of items.
  90      */
  91     virtual QString allowedOptions() const = 0;
  92
  93 protected:
  94     Configuration *m_config;
  95 };
  96
  97 #endif