Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle 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 3 of the License, or

// (at your option) any later version.

//

// Moodle 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 Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * This defines the states a question can be in.

 *

 * @package    moodlecore

 * @subpackage questionengine

 * @copyright  2010 The Open University

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

defined('MOODLE_INTERNAL') || die();

/**

 * An enumeration representing the states a question can be in after a

 * {@link question_attempt_step}.

 *

 * There are also some useful methods for testing and manipulating states.

 *

 * @copyright  2009 The Open University

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

abstract class question_state {

    /**#@+

     * Specific question_state instances.

     */

    public static $notstarted;

    public static $unprocessed;

    public static $todo;

    public static $invalid;

    public static $complete;

    public static $needsgrading;

    public static $finished;

    public static $gaveup;

    public static $gradedwrong;

    public static $gradedpartial;

    public static $gradedright;

    public static $manfinished;

    public static $mangaveup;

    public static $mangrwrong;

    public static $mangrpartial;

    public static $mangrright;

    /**#@+-*/

    protected function __construct() {

    }

    public static function init() {

        $us = new ReflectionClass('question_state');

        foreach ($us->getStaticProperties() as $name => $notused) {

            $class = 'question_state_' . $name;

            $states[$name] = new $class();

            self::$$name = $states[$name];

        }

    }

    /**

     * Get all the states in an array.

     *

     * @return question_state[] of question_state objects.

     */

    public static function get_all() {

        $states = array();

        $us = new ReflectionClass('question_state');

        foreach ($us->getStaticProperties() as $name => $notused) {

            $states[] = self::$$name;

        }

        return $states;

    }

    /**

     * Get all the states in an array.

     * @param string $summarystate one of the four summary states

     * inprogress, needsgrading, manuallygraded or autograded.

     * @return array of the corresponding states.

     */

    public static function get_all_for_summary_state($summarystate) {

        $states = array();

        foreach (self::get_all() as $state) {

            if ($state->get_summary_state() == $summarystate) {

                $states[] = $state;

            }

        }

        if (empty($states)) {

            throw new coding_exception('unknown summary state ' . $summarystate);

        }

        return $states;

    }

    /**

     * @return string convert this state to a string.

     */

    public function __toString() {

        return substr(get_class($this), 15);

    }

    /**

     * Get the instance of this class for a given state name.

     *

     * @param string $name a state name.

     * @return question_state|null the state with that name. (Null only in an exceptional case.)

     */

    public static function get(string $name): ?question_state {

        // In the past, there was a bug where null states got stored

        // in the database as an empty string, which was wrong because

        // the state column should be NOT NULL.

        // That is no longer possible, but we need to avoid exceptions

        // for people with old bad data in their database.

        if ($name === '') {

            debugging('Attempt to create a state from an empty string. ' .

                'This is probably a sign of bad data in your database. See MDL-80127.');

            return null;

        }

        return self::$$name;

    }

    /**

     * Is this state one of the ones that mean the question attempt is in progress?

     * That is, started, but no finished.

     * @return bool

     */

    public function is_active() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt is finished?

     * That is, no further interaction possible, apart from manual grading.

     * @return bool

     */

    public function is_finished() {

        return true;

    }

    /**

     * Is this state one of the ones that mean the question attempt has been graded?

     * @return bool

     */

    public function is_graded() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt has been graded?

     * @return bool

     */

    public function is_correct() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt has been graded?

     * @return bool

     */

    public function is_partially_correct() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt has been graded?

     * @return bool

     */

    public function is_incorrect() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt has been graded?

     * @return bool

     */

    public function is_gave_up() {

        return false;

    }

    /**

     * Is this state one of the ones that mean the question attempt has had a manual comment added?

     * @return bool

     */

    public function is_commented() {

        return false;

    }

    /**

     * Each state can be categorised into one of four categories:

     * inprogress, needsgrading, manuallygraded or autograded.

     * @return string which category this state falls into.

     */

    public function get_summary_state() {

        if (!$this->is_finished()) {

            return 'inprogress';

        } else if ($this == self::$needsgrading) {

            return 'needsgrading';

        } else if ($this->is_commented()) {

            return 'manuallygraded';

        } else {

            return 'autograded';

        }

    }

    /**

     * Return the appropriate graded state based on a fraction. That is 0 or less

     * is $graded_incorrect, 1 is $graded_correct, otherwise it is $graded_partcorrect.

     * Appropriate allowance is made for rounding float values.

     *

     * @param number $fraction the grade, on the fraction scale.

     * @return question_state one of the state constants.

     */

    public static function graded_state_for_fraction($fraction) {

        if ($fraction < 0.000001) {

            return self::$gradedwrong;

        } else if ($fraction > 0.999999) {

            return self::$gradedright;

        } else {

            return self::$gradedpartial;

        }

    }

    /**

     * Return the appropriate manually graded state based on a fraction. That is 0 or less

     * is $manually_graded_incorrect, 1 is $manually_graded_correct, otherwise it is

     * $manually_graded_partcorrect. Appropriate allowance is made for rounding float values.

     *

     * @param number $fraction the grade, on the fraction scale.

     * @return int one of the state constants.

     */

    public static function manually_graded_state_for_fraction($fraction) {

        if (is_null($fraction)) {

            return self::$needsgrading;

        } else if ($fraction < 0.000001) {

            return self::$mangrwrong;

        } else if ($fraction > 0.999999) {

            return self::$mangrright;

        } else {

            return self::$mangrpartial;

        }

    }

    /**

     * Compute an appropriate state to move to after a manual comment has been

     * added to this state.

     * @param number $fraction the manual grade (if any) on the fraction scale.

     * @return int the new state.

     */

    public function corresponding_commented_state($fraction) {

        throw new coding_exception('Unexpected question state.');

    }

    /**

     * Return an appropriate CSS class name ''/'correct'/'partiallycorrect'/'incorrect',

     * for a state.

     * @return string

     */

    public function get_feedback_class() {

        return '';

    }

    /**

     * Return the name of an appropriate string to look up in the question

     * language pack for a state. This is used, for example, by

     * {@link question_behaviour::get_state_string()}. However, behaviours

     * sometimes change this default string for soemthing more specific.

     *

     * @param bool $showcorrectness Whether right/partial/wrong states should

     * be distinguised, or just treated as 'complete'.

     * @return string the name of a string that can be looked up in the 'question'

     *      lang pack, or used as a CSS class name, etc.

     */

    abstract public function get_state_class($showcorrectness);

    /**

     * The result of doing get_string on the result of {@link get_state_class()}.

     *

     * @param bool $showcorrectness Whether right/partial/wrong states should

     * be distinguised.

     * @return string a string from the lang pack that can be used in the UI.

     */

    public function default_string($showcorrectness) {

        return get_string($this->get_state_class($showcorrectness), 'question');

    }

}

/**#@+

 * Specific question_state subclasses.

 *

 * @copyright  2009 The Open University

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class question_state_notstarted extends question_state {

    public function is_finished() {

        return false;

    }

    public function get_state_class($showcorrectness) {

        throw new coding_exception('Unexpected question state.');

    }

}

class question_state_unprocessed extends question_state {

    public function is_finished() {

        return false;

    }

    public function get_state_class($showcorrectness) {

        throw new coding_exception('Unexpected question state.');

    }

}

class question_state_todo extends question_state {

    public function is_active() {

        return true;

    }

    public function is_finished() {

        return false;

    }

    public function get_state_class($showcorrectness) {

        return 'notyetanswered';

    }

}

class question_state_invalid extends question_state {

    public function is_active() {

        return true;

    }

    public function is_finished() {

        return false;

    }

    public function get_state_class($showcorrectness) {

        return 'invalidanswer';

    }

}

class question_state_complete extends question_state {

    public function is_active() {

        return true;

    }

    public function is_finished() {

        return false;

    }

    public function get_state_class($showcorrectness) {

        return 'answersaved';

    }

}

class question_state_needsgrading extends question_state {

    public function get_state_class($showcorrectness) {

        if ($showcorrectness) {

            return 'requiresgrading';

        } else {

            return 'complete';

        }

    }

    public function corresponding_commented_state($fraction) {

        return self::manually_graded_state_for_fraction($fraction);

    }

}

class question_state_finished extends question_state {

    public function get_state_class($showcorrectness) {

        return 'complete';

    }

    public function corresponding_commented_state($fraction) {

        return self::$manfinished;

    }

}

class question_state_gaveup extends question_state {

    public function is_gave_up() {

        return true;

    }

    public function get_feedback_class() {

        return 'incorrect';

    }

    public function get_state_class($showcorrectness) {

        return 'notanswered';

    }

    public function corresponding_commented_state($fraction) {

        if (is_null($fraction)) {

            return self::$mangaveup;

        } else {

            return self::manually_graded_state_for_fraction($fraction);

        }

    }

}

abstract class question_state_graded extends question_state {

    public function is_graded() {

        return true;

    }

    public function get_state_class($showcorrectness) {

        if ($showcorrectness) {

            return $this->get_feedback_class();

        } else {

            return 'complete';

        }

    }

    public function corresponding_commented_state($fraction) {

        return self::manually_graded_state_for_fraction($fraction);

    }

}

class question_state_gradedwrong extends question_state_graded {

    public function is_incorrect() {

        return true;

    }

    public function get_feedback_class() {

        return 'incorrect';

    }

}

class question_state_gradedpartial extends question_state_graded {

    public function is_graded() {

        return true;

    }

    public function is_partially_correct() {

        return true;

    }

    public function get_feedback_class() {

        return 'partiallycorrect';

    }

}

class question_state_gradedright extends question_state_graded {

    public function is_graded() {

        return true;

    }

    public function is_correct() {

        return true;

    }

    public function get_feedback_class() {

        return 'correct';

    }

}

class question_state_manfinished extends question_state_finished {

    public function is_commented() {

        return true;

    }

}

class question_state_mangaveup extends question_state_gaveup {

    public function is_commented() {

        return true;

    }

}

abstract class question_state_manuallygraded extends question_state_graded {

    public function is_commented() {

        return true;

    }

}

class question_state_mangrwrong extends question_state_manuallygraded {

    public function is_incorrect() {

        return false;

    }

    public function get_feedback_class() {

        return 'incorrect';

    }

}

class question_state_mangrpartial extends question_state_manuallygraded {

    public function is_partially_correct() {

        return true;

    }

    public function get_feedback_class() {

        return 'partiallycorrect';

    }

}

class question_state_mangrright extends question_state_manuallygraded {

    public function is_correct() {

        return true;

    }

    public function get_feedback_class() {

        return 'correct';

    }

}

/**#@-*/

question_state::init();