2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * This defines the states a question can be in.
21 * @subpackage questionengine
22 * @copyright 2010 The Open University
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') ||
die();
31 * An enumeration representing the states a question can be in after a
32 * {@link question_attempt_step}.
34 * There are also some useful methods for testing and manipulating states.
36 * @copyright 2009 The Open University
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 abstract class question_state
{
41 * Specific question_state instances.
43 public static $notstarted;
44 public static $unprocessed;
46 public static $invalid;
47 public static $complete;
48 public static $needsgrading;
49 public static $finished;
50 public static $gaveup;
51 public static $gradedwrong;
52 public static $gradedpartial;
53 public static $gradedright;
54 public static $manfinished;
55 public static $mangaveup;
56 public static $mangrwrong;
57 public static $mangrpartial;
58 public static $mangrright;
61 protected function __construct() {
64 public static function init() {
65 $us = new ReflectionClass('question_state');
66 foreach ($us->getStaticProperties() as $name => $notused) {
67 $class = 'question_state_' . $name;
68 $states[$name] = new $class();
69 self
::$
$name = $states[$name];
74 * Get all the states in an array.
75 * @return of question_state objects.
77 public static function get_all() {
79 $us = new ReflectionClass('question_state');
80 foreach ($us->getStaticProperties() as $name => $notused) {
81 $states[] = self
::$
$name;
87 * Get all the states in an array.
88 * @param string $summarystate one of the four summary states
89 * inprogress, needsgrading, manuallygraded or autograded.
90 * @return arrau of the corresponding states.
92 public static function get_all_for_summary_state($summarystate) {
94 foreach (self
::get_all() as $state) {
95 if ($state->get_summary_state() == $summarystate) {
100 throw new coding_exception('unknown summary state ' . $summarystate);
106 * @return string convert this state to a string.
108 public function __toString() {
109 return substr(get_class($this), 15);
113 * @param string $name a state name.
114 * @return question_state the state with that name.
116 public static function get($name) {
121 * Is this state one of the ones that mean the question attempt is in progress?
122 * That is, started, but no finished.
125 public function is_active() {
130 * Is this state one of the ones that mean the question attempt is finished?
131 * That is, no further interaction possible, apart from manual grading.
134 public function is_finished() {
139 * Is this state one of the ones that mean the question attempt has been graded?
142 public function is_graded() {
147 * Is this state one of the ones that mean the question attempt has been graded?
150 public function is_correct() {
155 * Is this state one of the ones that mean the question attempt has been graded?
158 public function is_partially_correct() {
163 * Is this state one of the ones that mean the question attempt has been graded?
166 public function is_incorrect() {
171 * Is this state one of the ones that mean the question attempt has been graded?
174 public function is_gave_up() {
179 * Is this state one of the ones that mean the question attempt has had a manual comment added?
182 public function is_commented() {
187 * Each state can be categorised into one of four categories:
188 * inprogress, needsgrading, manuallygraded or autograded.
189 * @return string which category this state falls into.
191 public function get_summary_state() {
192 if (!$this->is_finished()) {
194 } else if ($this == self
::$needsgrading) {
195 return 'needsgrading';
196 } else if ($this->is_commented()) {
197 return 'manuallygraded';
204 * Return the appropriate graded state based on a fraction. That is 0 or less
205 * is $graded_incorrect, 1 is $graded_correct, otherwise it is $graded_partcorrect.
206 * Appropriate allowance is made for rounding float values.
208 * @param number $fraction the grade, on the fraction scale.
209 * @return question_state one of the state constants.
211 public static function graded_state_for_fraction($fraction) {
212 if ($fraction < 0.000001) {
213 return self
::$gradedwrong;
214 } else if ($fraction > 0.999999) {
215 return self
::$gradedright;
217 return self
::$gradedpartial;
222 * Return the appropriate manually graded state based on a fraction. That is 0 or less
223 * is $manually_graded_incorrect, 1 is $manually_graded_correct, otherwise it is
224 * $manually_graded_partcorrect. Appropriate allowance is made for rounding float values.
226 * @param number $fraction the grade, on the fraction scale.
227 * @return int one of the state constants.
229 public static function manually_graded_state_for_fraction($fraction) {
230 if (is_null($fraction)) {
231 return self
::$needsgrading;
232 } else if ($fraction < 0.000001) {
233 return self
::$mangrwrong;
234 } else if ($fraction > 0.999999) {
235 return self
::$mangrright;
237 return self
::$mangrpartial;
242 * Compute an appropriate state to move to after a manual comment has been
243 * added to this state.
244 * @param number $fraction the manual grade (if any) on the fraction scale.
245 * @return int the new state.
247 public function corresponding_commented_state($fraction) {
248 throw new coding_exception('Unexpected question state.');
252 * Return an appropriate CSS class name ''/'correct'/'partiallycorrect'/'incorrect',
256 public function get_feedback_class() {
261 * Return the name of an appropriate string to look up in the question
262 * language pack for a state. This is used, for example, by
263 * {@link question_behaviour::get_state_string()}. However, behaviours
264 * sometimes change this default string for soemthing more specific.
266 * @param bool $showcorrectness Whether right/partial/wrong states should
267 * be distinguised, or just treated as 'complete'.
268 * @return string the name of a string that can be looked up in the 'question'
269 * lang pack, or used as a CSS class name, etc.
271 public abstract function get_state_class($showcorrectness);
274 * The result of doing get_string on the result of {@link get_state_class()}.
276 * @param bool $showcorrectness Whether right/partial/wrong states should
278 * @return string a string from the lang pack that can be used in the UI.
280 public function default_string($showcorrectness) {
281 return get_string($this->get_state_class($showcorrectness), 'question');
287 * Specific question_state subclasses.
289 * @copyright 2009 The Open University
290 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
292 class question_state_notstarted
extends question_state
{
293 public function is_finished() {
296 public function get_state_class($showcorrectness) {
297 throw new coding_exception('Unexpected question state.');
300 class question_state_unprocessed
extends question_state
{
301 public function is_finished() {
304 public function get_state_class($showcorrectness) {
305 throw new coding_exception('Unexpected question state.');
308 class question_state_todo
extends question_state
{
309 public function is_active() {
312 public function is_finished() {
315 public function get_state_class($showcorrectness) {
316 return 'notyetanswered';
319 class question_state_invalid
extends question_state
{
320 public function is_active() {
323 public function is_finished() {
326 public function get_state_class($showcorrectness) {
327 return 'invalidanswer';
330 class question_state_complete
extends question_state
{
331 public function is_active() {
334 public function is_finished() {
337 public function get_state_class($showcorrectness) {
338 return 'answersaved';
341 class question_state_needsgrading
extends question_state
{
342 public function get_state_class($showcorrectness) {
343 if ($showcorrectness) {
344 return 'requiresgrading';
349 public function corresponding_commented_state($fraction) {
350 return self
::manually_graded_state_for_fraction($fraction);
353 class question_state_finished
extends question_state
{
354 public function get_state_class($showcorrectness) {
357 public function corresponding_commented_state($fraction) {
358 return self
::$manfinished;
361 class question_state_gaveup
extends question_state
{
362 public function is_gave_up() {
365 public function get_feedback_class() {
368 public function get_state_class($showcorrectness) {
369 return 'notanswered';
371 public function corresponding_commented_state($fraction) {
372 if (is_null($fraction)) {
373 return self
::$mangaveup;
375 return self
::manually_graded_state_for_fraction($fraction);
379 abstract class question_state_graded
extends question_state
{
380 public function is_graded() {
383 public function get_state_class($showcorrectness) {
384 if ($showcorrectness) {
385 return $this->get_feedback_class();
390 public function corresponding_commented_state($fraction) {
391 return self
::manually_graded_state_for_fraction($fraction);
394 class question_state_gradedwrong
extends question_state_graded
{
395 public function is_incorrect() {
398 public function get_feedback_class() {
402 class question_state_gradedpartial
extends question_state_graded
{
403 public function is_graded() {
406 public function is_partially_correct() {
409 public function get_feedback_class() {
410 return 'partiallycorrect';
413 class question_state_gradedright
extends question_state_graded
{
414 public function is_graded() {
417 public function is_correct() {
420 public function get_feedback_class() {
424 class question_state_manfinished
extends question_state_finished
{
425 public function is_commented() {
429 class question_state_mangaveup
extends question_state_gaveup
{
430 public function is_commented() {
434 abstract class question_state_manuallygraded
extends question_state_graded
{
435 public function is_commented() {
439 class question_state_mangrwrong
extends question_state_manuallygraded
{
440 public function is_incorrect() {
443 public function get_feedback_class() {
447 class question_state_mangrpartial
extends question_state_manuallygraded
{
448 public function is_partially_correct() {
451 public function get_feedback_class() {
452 return 'partiallycorrect';
455 class question_state_mangrright
extends question_state_manuallygraded
{
456 public function is_correct() {
459 public function get_feedback_class() {
464 question_state
::init();