/*
Copyright (c) 2007 Matt Williams matt@milliams.com

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License or (at
your option) version 3 or, at the discretion of KDE e.V. (which shall
act as a proxy as in section 14 of the GPLv3), any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef KQTIRESPONSEDECLARATION_H
#define KQTIRESPONSEDECLARATION_H

#include <kqti_export.h>

#include <QDomElement>
#include <QList>

class KQTI_EXPORT KQtiMapping;

/**
 * \class KQtiResponseDeclaration
 * Response variables are declared by response declarations and bound to
 * interactions in the itemBody.
 * 
 * At runtime, response variables are instantiated as part of an item session.
 * Their values are always initialized to NULL (no value) regardless of whether
 * or not a default value is given in the declaration. A response variable with
 * a NULL value indicates that the candidate has not offered a response, either
 * because they have not attempted the item at all or because they have
 * attempted it and chosen not to provide a response.
 * 
 * If a default value has been provided for a response variable then the
 * variable is set to this value at the start of the first attempt. If the
 * candidate never attempts the item, in other words, the item session passes
 * straight from the initial state to the closed state without going through
 * the interacting state, then the response variable remains NULL and the
 * default value is never used.
 * 
 * Implementors of Delivery Engines should take care when implementing user
 * interfaces for items with default response variable values. If the
 * associated interaction is left in the default state (i.e., representing the
 * default value) then it is important that the system is confident that the
 * candidate intended to submit this value and has not simply failed to notice
 * that a default has been provided. This is especially true if the candidate's
 * attempt ended due to some external event, such as running out of time. The
 * techniques required to distinguish between these cases are an issue for user
 * interface design and are therefore out of scope for this specification.
 * 
 * http://www.imsglobal.org/question/qtiv2p1pd2/imsqti_infov2p1pd2.html#element10073
 */

class KQtiResponseDeclaration /*: public KQtiVariableDeclaration*/ //TODO Create KQtiVariableDeclaration
{
    public:
        explicit KQtiResponseDeclaration(const QString& identifier=QString("RESPONSE"), const QString& cardinality=QString("single"), const QString& baseType=QString("identifier"));
        explicit KQtiResponseDeclaration(const QDomElement& element);
        ~KQtiResponseDeclaration();
        
        void setIdentifier(const QString& identifier) {mIdentifier = identifier;}
        QString identifier() const {return mIdentifier;}
        void setCardinality(const QString& cardinality) {mCardinality = cardinality;}
        QString cardinality() const {return mCardinality;}
        void setBaseType(const QString& baseType) {mBaseType = baseType;}
        QString baseType() const {return mBaseType;}
        
        /**
         * addCorrectResponse
         * @param value the identifier given to KQtiChoiceInteraction::appendChoice() of the correct answer
         */
        void addCorrectResponse(const QString& value);
        QList<QString> correctResponse() const {return mCorrectResponse;}
        
        void setMapping(KQtiMapping* mapping);
        KQtiMapping* mapping() const {return mMapping;}
        
        /**
         * element
         * @return create and return the DOM element
         */
        QDomElement element() const;
        
    protected:
        QString mIdentifier;
        QString mCardinality;
        QString mBaseType;
        
        QList<QString> mCorrectResponse;
        
        bool usingMapping;
        KQtiMapping* mMapping;
};

#endif
