[Summary view] [Print] [Text view]

   1  // This file is part of Moodle - http://moodle.org/
   2  //
   3  // Moodle is free software: you can redistribute it and/or modify
   4  // it under the terms of the GNU General Public License as published by
   5  // the Free Software Foundation, either version 3 of the License, or
   6  // (at your option) any later version.
   7  //
   8  // Moodle is distributed in the hope that it will be useful,
   9  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  // GNU General Public License for more details.
  12  //
  13  // You should have received a copy of the GNU General Public License
  14  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15  
  16  /**
  17   * Chart axis.
  18   *
  19   * @module core/chart_axis
  20   * @copyright  2016 Frédéric Massart - FMCorz.net
  21   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22   */
  23  define([], function() {
  24  
  25      /**
  26       * Chart axis class.
  27       *
  28       * This is used to represent an axis, whether X or Y.
  29       *
  30       * @class core/chart_axis
  31       */
  32      function Axis() {
  33          // Please eslint no-empty-function.
  34      }
  35  
  36      /**
  37       * Default axis position.
  38       * @const {Null}
  39       */
  40      Axis.prototype.POS_DEFAULT = null;
  41  
  42      /**
  43       * Bottom axis position.
  44       * @const {String}
  45       */
  46      Axis.prototype.POS_BOTTOM = 'bottom';
  47  
  48      /**
  49       * Left axis position.
  50       * @const {String}
  51       */
  52      Axis.prototype.POS_LEFT = 'left';
  53  
  54      /**
  55       * Right axis position.
  56       * @const {String}
  57       */
  58      Axis.prototype.POS_RIGHT = 'right';
  59  
  60      /**
  61       * Top axis position.
  62       * @const {String}
  63       */
  64      Axis.prototype.POS_TOP = 'top';
  65  
  66      /**
  67       * Label of the axis.
  68       * @type {String}
  69       * @protected
  70       */
  71      Axis.prototype._label = null;
  72  
  73      /**
  74       * Labels of the ticks.
  75       * @type {String[]}
  76       * @protected
  77       */
  78      Axis.prototype._labels = null;
  79  
  80      /**
  81       * Maximum value of the axis.
  82       * @type {Number}
  83       * @protected
  84       */
  85      Axis.prototype._max = null;
  86  
  87      /**
  88       * Minimum value of the axis.
  89       * @type {Number}
  90       * @protected
  91       */
  92      Axis.prototype._min = null;
  93  
  94      /**
  95       * Position of the axis.
  96       * @type {String}
  97       * @protected
  98       */
  99      Axis.prototype._position = null;
 100  
 101      /**
 102       * Steps on the axis.
 103       * @type {Number}
 104       * @protected
 105       */
 106      Axis.prototype._stepSize = null;
 107  
 108      /**
 109       * Create a new instance of an axis from serialised data.
 110       *
 111       * @static
 112       * @method create
 113       * @param {Object} obj The data of the axis.
 114       * @return {module:core/chart_axis}
 115       */
 116      Axis.prototype.create = function(obj) {
 117          var s = new Axis();
 118          s.setPosition(obj.position);
 119          s.setLabel(obj.label);
 120          s.setStepSize(obj.stepSize);
 121          s.setMax(obj.max);
 122          s.setMin(obj.min);
 123          s.setLabels(obj.labels);
 124          return s;
 125      };
 126  
 127      /**
 128       * Get the label of the axis.
 129       *
 130       * @method getLabel
 131       * @return {String}
 132       */
 133      Axis.prototype.getLabel = function() {
 134          return this._label;
 135      };
 136  
 137      /**
 138       * Get the labels of the ticks of the axis.
 139       *
 140       * @method getLabels
 141       * @return {String[]}
 142       */
 143      Axis.prototype.getLabels = function() {
 144          return this._labels;
 145      };
 146  
 147      /**
 148       * Get the maximum value of the axis.
 149       *
 150       * @method getMax
 151       * @return {Number}
 152       */
 153      Axis.prototype.getMax = function() {
 154          return this._max;
 155      };
 156  
 157      /**
 158       * Get the minimum value of the axis.
 159       *
 160       * @method getMin
 161       * @return {Number}
 162       */
 163      Axis.prototype.getMin = function() {
 164          return this._min;
 165      };
 166  
 167      /**
 168       * Get the position of the axis.
 169       *
 170       * @method getPosition
 171       * @return {String}
 172       */
 173      Axis.prototype.getPosition = function() {
 174          return this._position;
 175      };
 176  
 177      /**
 178       * Get the step size of the axis.
 179       *
 180       * @method getStepSize
 181       * @return {Number}
 182       */
 183      Axis.prototype.getStepSize = function() {
 184          return this._stepSize;
 185      };
 186  
 187      /**
 188       * Set the label of the axis.
 189       *
 190       * @method setLabel
 191       * @param {String} label The label.
 192       */
 193      Axis.prototype.setLabel = function(label) {
 194          this._label = label || null;
 195      };
 196  
 197      /**
 198       * Set the labels of the values on the axis.
 199       *
 200       * This automatically sets the [_stepSize]{@link module:core/chart_axis#_stepSize},
 201       * [_min]{@link module:core/chart_axis#_min} and [_max]{@link module:core/chart_axis#_max}
 202       * to define a scale from 0 to the number of labels when none of the previously
 203       * mentioned values have been modified.
 204       *
 205       * You can use other values so long that your values in a series are mapped
 206       * to the values represented by your _min, _max and _stepSize.
 207       *
 208       * @method setLabels
 209       * @param {String[]} labels The labels.
 210       */
 211      Axis.prototype.setLabels = function(labels) {
 212          this._labels = labels || null;
 213  
 214          // By default we set the grid according to the labels.
 215          if (this._labels !== null
 216                  && this._stepSize === null
 217                  && (this._min === null || this._min === 0)
 218                  && this._max === null) {
 219              this.setStepSize(1);
 220              this.setMin(0);
 221              this.setMax(labels.length - 1);
 222          }
 223      };
 224  
 225      /**
 226       * Set the maximum value on the axis.
 227       *
 228       * When this is not set (or set to null) it is left for the output
 229       * library to best guess what should be used.
 230       *
 231       * @method setMax
 232       * @param {Number} max The value.
 233       */
 234      Axis.prototype.setMax = function(max) {
 235          this._max = typeof max !== 'undefined' ? max : null;
 236      };
 237  
 238      /**
 239       * Set the minimum value on the axis.
 240       *
 241       * When this is not set (or set to null) it is left for the output
 242       * library to best guess what should be used.
 243       *
 244       * @method setMin
 245       * @param {Number} min The value.
 246       */
 247      Axis.prototype.setMin = function(min) {
 248          this._min = typeof min !== 'undefined' ? min : null;
 249      };
 250  
 251      /**
 252       * Set the position of the axis.
 253       *
 254       * This does not validate whether or not the constant used is valid
 255       * as the axis itself is not aware whether it represents the X or Y axis.
 256       *
 257       * The output library has to have a fallback in case the values are incorrect.
 258       * When this is not set to {@link module:core/chart_axis#POS_DEFAULT} it is up
 259       * to the output library to choose what position fits best.
 260       *
 261       * @method setPosition
 262       * @param {String} position The value.
 263       */
 264      Axis.prototype.setPosition = function(position) {
 265          if (position != this.POS_DEFAULT
 266                  && position != this.POS_BOTTOM
 267                  && position != this.POS_LEFT
 268                  && position != this.POS_RIGHT
 269                  && position != this.POS_TOP) {
 270              throw new Error('Invalid axis position.');
 271          }
 272          this._position = position;
 273      };
 274  
 275      /**
 276       * Set the stepSize on the axis.
 277       *
 278       * This is used to determine where ticks are displayed on the axis between min and max.
 279       *
 280       * @method setStepSize
 281       * @param {Number} stepSize The value.
 282       */
 283      Axis.prototype.setStepSize = function(stepSize) {
 284          if (typeof stepSize === 'undefined' || stepSize === null) {
 285              stepSize = null;
 286          } else if (isNaN(Number(stepSize))) {
 287              throw new Error('Value for stepSize is not a number.');
 288          } else {
 289              stepSize = Number(stepSize);
 290          }
 291  
 292          this._stepSize = stepSize;
 293      };
 294  
 295      return Axis;
 296  
 297  });