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.
76 * @return question_state[] of question_state objects.
78 public static function get_all() {
80 $us = new ReflectionClass('question_state');
81 foreach ($us->getStaticProperties() as $name => $notused) {
82 $states[] = self
::$
$name;
88 * Get all the states in an array.
89 * @param string $summarystate one of the four summary states
90 * inprogress, needsgrading, manuallygraded or autograded.
91 * @return array of the corresponding states.
93 public static function get_all_for_summary_state($summarystate) {
95 foreach (self
::get_all() as $state) {
96 if ($state->get_summary_state() == $summarystate) {
100 if (empty($states)) {
101 throw new coding_exception('unknown summary state ' . $summarystate);
107 * @return string convert this state to a string.
109 public function __toString() {
110 return substr(get_class($this), 15);
114 * Get the instance of this class for a given state name.
116 * @param string $name a state name.
117 * @return question_state|null the state with that name. (Null only in an exceptional case.)
119 public static function get(string $name): ?question_state
{
120 // In the past, there was a bug where null states got stored
121 // in the database as an empty string, which was wrong because
122 // the state column should be NOT NULL.
123 // That is no longer possible, but we need to avoid exceptions
124 // for people with old bad data in their database.
126 debugging('Attempt to create a state from an empty string. ' .
127 'This is probably a sign of bad data in your database. See MDL-80127.');
135 * Is this state one of the ones that mean the question attempt is in progress?
136 * That is, started, but no finished.
139 public function is_active() {
144 * Is this state one of the ones that mean the question attempt is finished?
145 * That is, no further interaction possible, apart from manual grading.
148 public function is_finished() {
153 * Is this state one of the ones that mean the question attempt has been graded?
156 public function is_graded() {
161 * Is this state one of the ones that mean the question attempt has been graded?
164 public function is_correct() {
169 * Is this state one of the ones that mean the question attempt has been graded?
172 public function is_partially_correct() {
177 * Is this state one of the ones that mean the question attempt has been graded?
180 public function is_incorrect() {
185 * Is this state one of the ones that mean the question attempt has been graded?
188 public function is_gave_up() {
193 * Is this state one of the ones that mean the question attempt has had a manual comment added?
196 public function is_commented() {
201 * Each state can be categorised into one of four categories:
202 * inprogress, needsgrading, manuallygraded or autograded.
203 * @return string which category this state falls into.
205 public function get_summary_state() {
206 if (!$this->is_finished()) {
208 } else if ($this == self
::$needsgrading) {
209 return 'needsgrading';
210 } else if ($this->is_commented()) {
211 return 'manuallygraded';
218 * Return the appropriate graded state based on a fraction. That is 0 or less
219 * is $graded_incorrect, 1 is $graded_correct, otherwise it is $graded_partcorrect.
220 * Appropriate allowance is made for rounding float values.
222 * @param number $fraction the grade, on the fraction scale.
223 * @return question_state one of the state constants.
225 public static function graded_state_for_fraction($fraction) {
226 if ($fraction < 0.000001) {
227 return self
::$gradedwrong;
228 } else if ($fraction > 0.999999) {
229 return self
::$gradedright;
231 return self
::$gradedpartial;
236 * Return the appropriate manually graded state based on a fraction. That is 0 or less
237 * is $manually_graded_incorrect, 1 is $manually_graded_correct, otherwise it is
238 * $manually_graded_partcorrect. Appropriate allowance is made for rounding float values.
240 * @param number $fraction the grade, on the fraction scale.
241 * @return int one of the state constants.
243 public static function manually_graded_state_for_fraction($fraction) {
244 if (is_null($fraction)) {
245 return self
::$needsgrading;
246 } else if ($fraction < 0.000001) {
247 return self
::$mangrwrong;
248 } else if ($fraction > 0.999999) {
249 return self
::$mangrright;
251 return self
::$mangrpartial;
256 * Compute an appropriate state to move to after a manual comment has been
257 * added to this state.
258 * @param number $fraction the manual grade (if any) on the fraction scale.
259 * @return int the new state.
261 public function corresponding_commented_state($fraction) {
262 throw new coding_exception('Unexpected question state.');
266 * Return an appropriate CSS class name ''/'correct'/'partiallycorrect'/'incorrect',
270 public function get_feedback_class() {
275 * Return the name of an appropriate string to look up in the question
276 * language pack for a state. This is used, for example, by
277 * {@link question_behaviour::get_state_string()}. However, behaviours
278 * sometimes change this default string for soemthing more specific.
280 * @param bool $showcorrectness Whether right/partial/wrong states should
281 * be distinguised, or just treated as 'complete'.
282 * @return string the name of a string that can be looked up in the 'question'
283 * lang pack, or used as a CSS class name, etc.
285 abstract public function get_state_class($showcorrectness);
288 * The result of doing get_string on the result of {@link get_state_class()}.
290 * @param bool $showcorrectness Whether right/partial/wrong states should
292 * @return string a string from the lang pack that can be used in the UI.
294 public function default_string($showcorrectness) {
295 return get_string($this->get_state_class($showcorrectness), 'question');
301 * Specific question_state subclasses.
303 * @copyright 2009 The Open University
304 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
306 class question_state_notstarted
extends question_state
{
307 public function is_finished() {
310 public function get_state_class($showcorrectness) {
311 throw new coding_exception('Unexpected question state.');
314 class question_state_unprocessed
extends question_state
{
315 public function is_finished() {
318 public function get_state_class($showcorrectness) {
319 throw new coding_exception('Unexpected question state.');
322 class question_state_todo
extends question_state
{
323 public function is_active() {
326 public function is_finished() {
329 public function get_state_class($showcorrectness) {
330 return 'notyetanswered';
333 class question_state_invalid
extends question_state
{
334 public function is_active() {
337 public function is_finished() {
340 public function get_state_class($showcorrectness) {
341 return 'invalidanswer';
344 class question_state_complete
extends question_state
{
345 public function is_active() {
348 public function is_finished() {
351 public function get_state_class($showcorrectness) {
352 return 'answersaved';
355 class question_state_needsgrading
extends question_state
{
356 public function get_state_class($showcorrectness) {
357 if ($showcorrectness) {
358 return 'requiresgrading';
363 public function corresponding_commented_state($fraction) {
364 return self
::manually_graded_state_for_fraction($fraction);
367 class question_state_finished
extends question_state
{
368 public function get_state_class($showcorrectness) {
371 public function corresponding_commented_state($fraction) {
372 return self
::$manfinished;
375 class question_state_gaveup
extends question_state
{
376 public function is_gave_up() {
379 public function get_feedback_class() {
382 public function get_state_class($showcorrectness) {
383 return 'notanswered';
385 public function corresponding_commented_state($fraction) {
386 if (is_null($fraction)) {
387 return self
::$mangaveup;
389 return self
::manually_graded_state_for_fraction($fraction);
393 abstract class question_state_graded
extends question_state
{
394 public function is_graded() {
397 public function get_state_class($showcorrectness) {
398 if ($showcorrectness) {
399 return $this->get_feedback_class();
404 public function corresponding_commented_state($fraction) {
405 return self
::manually_graded_state_for_fraction($fraction);
408 class question_state_gradedwrong
extends question_state_graded
{
409 public function is_incorrect() {
412 public function get_feedback_class() {
416 class question_state_gradedpartial
extends question_state_graded
{
417 public function is_graded() {
420 public function is_partially_correct() {
423 public function get_feedback_class() {
424 return 'partiallycorrect';
427 class question_state_gradedright
extends question_state_graded
{
428 public function is_graded() {
431 public function is_correct() {
434 public function get_feedback_class() {
438 class question_state_manfinished
extends question_state_finished
{
439 public function is_commented() {
443 class question_state_mangaveup
extends question_state_gaveup
{
444 public function is_commented() {
448 abstract class question_state_manuallygraded
extends question_state_graded
{
449 public function is_commented() {
453 class question_state_mangrwrong
extends question_state_manuallygraded
{
454 public function is_incorrect() {
457 public function get_feedback_class() {
461 class question_state_mangrpartial
extends question_state_manuallygraded
{
462 public function is_partially_correct() {
465 public function get_feedback_class() {
466 return 'partiallycorrect';
469 class question_state_mangrright
extends question_state_manuallygraded
{
470 public function is_correct() {
473 public function get_feedback_class() {
478 question_state
::init();