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