lib/amd/src/chart_axis.js

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