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