1 /*
  2     Copyright 2008-2011
  3         Matthias Ehmann,
  4         Michael Gerhaeuser,
  5         Carsten Miller,
  6         Bianca Valentin,
  7         Alfred Wassermann,
  8         Peter Wilfahrt
  9 
 10     This file is part of JSXGraph.
 11 
 12     JSXGraph is free software: you can redistribute it and/or modify
 13     it under the terms of the GNU Lesser General Public License as published by
 14     the Free Software Foundation, either version 3 of the License, or
 15     (at your option) any later version.
 16 
 17     JSXGraph is distributed in the hope that it will be useful,
 18     but WITHOUT ANY WARRANTY; without even the implied warranty of
 19     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 20     GNU Lesser General Public License for more details.
 21 
 22     You should have received a copy of the GNU Lesser General Public License
 23     along with JSXGraph.  If not, see <http://www.gnu.org/licenses/>.
 24 
 25 */
 26 
 27 /*jshint bitwise: false, curly: true, debug: false, eqeqeq: true, devel: false, evil: false,
 28   forin: false, immed: true, laxbreak: false, newcap: false, noarg: true, nonew: true, onevar: true,
 29    undef: true, white: true, sub: false*/
 30 /*global JXG: true, AMprocessNode: true, MathJax: true, document: true */
 31 
 32 /**
 33  * @fileoverview JSXGraph can use various technologies to render the contents of a construction, e.g.
 34  * SVG, VML, and HTML5 Canvas. To accomplish this, The rendering and the logic and control mechanisms
 35  * are completely separated from each other. Every rendering technology has it's own class, called
 36  * Renderer, e.g. SVGRenderer for SVG, the same for VML and Canvas. The common base for all available
 37  * renderers is the class AbstractRenderer.
 38  */
 39 
 40 /**
 41  * @class JXG.AbstractRenderer
 42  */
 43 JXG.NoRenderer = function () {
 44     /**
 45      * If this property is set to <tt>true</tt> the visual properties of the elements are updated
 46      * on every update. Visual properties means: All the stuff stored in the
 47      * {@link JXG.GeometryElement#visProp} property won't be set if enhancedRendering is <tt>false</tt>
 48      * @type Boolean
 49      * @default true
 50      */
 51     this.enhancedRendering = false;
 52 
 53     /**
 54      * This is used to easily determine which renderer we are using
 55      * @example if (board.renderer.type === 'vml') {
 56      *     // do something
 57      * }
 58      * @type String
 59      */
 60     this.type = 'no';
 61 };
 62 
 63 JXG.extend(JXG.NoRenderer.prototype, /** @lends JXG.AbstractRenderer.prototype */ {
 64     /* ******************************** *
 65      *    Point drawing and updating    *
 66      * ******************************** */
 67 
 68     /**
 69      * Draws a point on the {@link JXG.Board}.
 70      * @param {JXG.Point} element Reference to a {@link JXG.Point} object that has to be drawn.
 71      * @see Point
 72      * @see JXG.Point
 73      * @see JXG.AbstractRenderer#updatePoint
 74      * @see JXG.AbstractRenderer#changePointStyle
 75      */
 76     drawPoint: function (element) {},
 77 
 78     /**
 79      * Updates visual appearance of the renderer element assigned to the given {@link JXG.Point}.
 80      * @param {JXG.Point} element Reference to a {@link JXG.Point} object, that has to be updated.
 81      * @see Point
 82      * @see JXG.Point
 83      * @see JXG.AbstractRenderer#drawPoint
 84      * @see JXG.AbstractRenderer#changePointStyle
 85      */
 86     updatePoint: function (element) { },
 87 
 88     /**
 89      * Changes the style of a {@link JXG.Point}. This is required because the point styles differ in what
 90      * elements have to be drawn, e.g. if the point is marked by a "x" or a "+" two lines are drawn, if
 91      * it's marked by spot a circle is drawn. This method removes the old renderer element(s) and creates
 92      * the new one(s).
 93      * @param {JXG.Point} element Reference to a {@link JXG.Point} object, that's style is changed.
 94      * @see Point
 95      * @see JXG.Point
 96      * @see JXG.AbstractRenderer#updatePoint
 97      * @see JXG.AbstractRenderer#drawPoint
 98      */
 99     changePointStyle: function (element) { },
100 
101     /* ******************************** *
102      *           Lines                  *
103      * ******************************** */
104 
105     /**
106      * Draws a line on the {@link JXG.Board}.
107      * @param {JXG.Line} element Reference to a line object, that has to be drawn.
108      * @see Line
109      * @see JXG.Line
110      * @see JXG.AbstractRenderer#updateLine
111      */
112     drawLine: function (element) { },
113 
114     /**
115      * Updates visual appearance of the renderer element assigned to the given {@link JXG.Line}.
116      * @param {JXG.Line} element Reference to the {@link JXG.Line} object that has to be updated.
117      * @see Line
118      * @see JXG.Line
119      * @see JXG.AbstractRenderer#drawLine
120      */
121     updateLine: function (element) { },
122 
123     /**
124      * Creates a rendering node for ticks added to a line.
125      * @param {JXG.Line} element A arbitrary line.
126      * @see Line
127      * @see Ticks
128      * @see JXG.Line
129      * @see JXG.Ticks
130      * @see JXG.AbstractRenderer#updateTicks
131      */
132     drawTicks: function (element) { },
133 
134     /**
135      * Update {@link Ticks} on a {@link JXG.Line}. This method is only a stub and has to be implemented
136      * in any descendant renderer class.
137      * @param {JXG.Line} element Reference of an line object, thats ticks have to be updated.
138      * @param {Number} dxMaj Number of pixels a major tick counts in x direction.
139      * @param {Number} dyMaj Number of pixels a major tick counts in y direction.
140      * @param {Number} dxMin Number of pixels a minor tick counts in x direction.
141      * @param {Number} dyMin Number of pixels a minor tick counts in y direction.
142      * @see Line
143      * @see Ticks
144      * @see JXG.Line
145      * @see JXG.Ticks
146      * @see JXG.AbstractRenderer#drawTicks
147      */
148     updateTicks: function (element, dxMaj, dyMaj, dxMin, dyMin) { /* stub */ },
149 
150     /* **************************
151      *    Curves
152      * **************************/
153 
154     /**
155      * Draws a {@link JXG.Curve} on the {@link JXG.Board}.
156      * @param {JXG.Curve} element Reference to a graph object, that has to be plotted.
157      * @see Curve
158      * @see JXG.Curve
159      * @see JXG.AbstractRenderer#updateCurve
160      */
161     drawCurve: function (element) { },
162 
163     /**
164      * Updates visual appearance of the renderer element assigned to the given {@link JXG.Curve}.
165      * @param {JXG.Curve} element Reference to a {@link JXG.Curve} object, that has to be updated.
166      * @see Curve
167      * @see JXG.Curve
168      * @see JXG.AbstractRenderer#drawCurve
169      */
170     updateCurve: function (element) { },
171 
172     /* **************************
173      *    Circle related stuff
174      * **************************/
175 
176     /**
177      * Draws a {@link JXG.Circle}
178      * @param {JXG.Circle} element Reference to a {@link JXG.Circle} object that has to be drawn.
179      * @see Circle
180      * @see JXG.Circle
181      * @see JXG.AbstractRenderer#updateEllipse
182      */
183     drawEllipse: function (element) { },
184 
185     /**
186      * Updates visual appearance of a given {@link JXG.Circle} on the {@link JXG.Board}.
187      * @param {JXG.Circle} element Reference to a {@link JXG.Circle} object, that has to be updated.
188      * @see Circle
189      * @see JXG.Circle
190      * @see JXG.AbstractRenderer#drawEllipse
191      */
192     updateEllipse: function (element) { },
193 
194 
195     /* **************************
196      *   Polygon related stuff
197      * **************************/
198 
199     /**
200      * Draws a {@link JXG.Polygon} on the {@link JXG.Board}.
201      * @param {JXG.Polygon} element Reference to a Polygon object, that is to be drawn.
202      * @see Polygon
203      * @see JXG.Polygon
204      * @see JXG.AbstractRenderer#updatePolygon
205      */
206     drawPolygon: function (element) { },
207 
208     /**
209      * Updates properties of a {@link JXG.Polygon}'s rendering node.
210      * @param {JXG.Polygon} element Reference to a {@link JXG.Polygon} object, that has to be updated.
211      * @see Polygon
212      * @see JXG.Polygon
213      * @see JXG.AbstractRenderer#drawPolygon
214      */
215     updatePolygon: function (element) { },
216 
217     /* **************************
218      *    Text related stuff
219      * **************************/
220 
221     /**
222      * Shows a small copyright notice in the top left corner of the board.
223      * @param {String} str The copyright notice itself
224      * @param {Number} fontsize Size of the font the copyright notice is written in
225      */
226     displayCopyright: function (str, fontsize) { /* stub */ },
227 
228     /**
229      * An internal text is a {@link JXG.Text} element which is drawn using only
230      * the given renderer but no HTML. This method is only a stub, the drawing
231      * is done in the special renderers.
232      * @param {JXG.Text} element Reference to a {@link JXG.Text} object
233      * @see Text
234      * @see JXG.Text
235      * @see JXG.AbstractRenderer#updateInternalText
236      * @see JXG.AbstractRenderer#drawText
237      * @see JXG.AbstractRenderer#updateText
238      * @see JXG.AbstractRenderer#updateTextStyle
239      */
240     drawInternalText: function (element) { /* stub */ },
241 
242     /**
243      * Updates visual properties of an already existing {@link JXG.Text} element.
244      * @param {JXG.Text} element Reference to an {@link JXG.Text} object, that has to be updated.
245      * @see Text
246      * @see JXG.Text
247      * @see JXG.AbstractRenderer#drawInternalText
248      * @see JXG.AbstractRenderer#drawText
249      * @see JXG.AbstractRenderer#updateText
250      * @see JXG.AbstractRenderer#updateTextStyle
251      */
252     updateInternalText: function (element) { /* stub */ },
253 
254     /**
255      * Displays a {@link JXG.Text} on the {@link JXG.Board} by putting a HTML div over it.
256      * @param {JXG.Text} element Reference to an {@link JXG.Text} object, that has to be displayed
257      * @see Text
258      * @see JXG.Text
259      * @see JXG.AbstractRenderer#drawInternalText
260      * @see JXG.AbstractRenderer#updateText
261      * @see JXG.AbstractRenderer#updateInternalText
262      * @see JXG.AbstractRenderer#updateTextStyle
263      */
264     drawText: function (element) { },
265 
266     /**
267      * Updates visual properties of an already existing {@link JXG.Text} element.
268      * @param {JXG.Text} element Reference to an {@link JXG.Text} object, that has to be updated.
269      * @see Text
270      * @see JXG.Text
271      * @see JXG.AbstractRenderer#drawText
272      * @see JXG.AbstractRenderer#drawInternalText
273      * @see JXG.AbstractRenderer#updateInternalText
274      * @see JXG.AbstractRenderer#updateTextStyle
275      */
276     updateText: function (element) { },
277 
278     /**
279      * Updates CSS style properties of a {@link JXG.Text} node.
280      * @param {JXG.Text} element Reference to the {@link JXG.Text} object, that has to be updated.
281      * @see Text
282      * @see JXG.Text
283      * @see JXG.AbstractRenderer#drawText
284      * @see JXG.AbstractRenderer#drawInternalText
285      * @see JXG.AbstractRenderer#updateText
286      * @see JXG.AbstractRenderer#updateInternalText
287      */
288     updateTextStyle: function (element, doHighlight) { },
289 
290      /**
291      * Set color and opacity of internal texts. 
292      * SVG needs its own version.
293      * @private
294      * @see JXG.AbstractRenderer#updateTextStyle
295      * @see JXG.AbstractRenderer#updateInternalTextStyle
296      */
297     updateInternalTextStyle: function(element, strokeColor, strokeOpacity) { /* stub */ },
298 
299     /* **************************
300      *    Image related stuff
301      * **************************/
302 
303     /**
304      * Draws an {@link JXG.Image} on a board; This is just a template that has to be implemented by special renderers.
305      * @param {JXG.Image} element Reference to the image object that is to be drawn
306      * @see Image
307      * @see JXG.Image
308      * @see JXG.AbstractRenderer#updateImage
309      */
310     drawImage: function (element) { /* stub */ },
311 
312     /**
313      * Updates the properties of an {@link JXG.Image} element.
314      * @param {JXG.Image} element Reference to an {@link JXG.Image} object, that has to be updated.
315      * @see Image
316      * @see JXG.Image
317      * @see JXG.AbstractRenderer#drawImage
318      */
319     updateImage: function (element) { },
320 
321     /**
322      * Applies transformations on images and text elements. This method is just a stub and has to be implemented in all
323      * descendant classes where text and image transformations are to be supported.
324      * @param {JXG.Image|JXG.Text} element A {@link JXG.Image} or {@link JXG.Text} object.
325      * @param {Array} transformations An array of {@link JXG.Transformation} objects. This is usually the transformations property
326      * of the given element <tt>el</tt>.
327      */
328     transformImage: function (element, transformations) { /* stub */ },
329 
330     /**
331      * If the URL of the image is provided by a function the URL has to be updated during updateImage()
332      * @param {JXG.Image} element Reference to an image object.
333      * @see JXG.AbstractRenderer#updateImage
334      */
335     updateImageURL: function (element) { /* stub */ },
336 
337     /* **************************
338      * Render primitive objects
339      * **************************/
340 
341     /**
342      * Appends a node to a specific layer level. This is just an abstract method and has to be implemented
343      * in all renderers that want to use the <tt>createPrim</tt> model to draw.
344      * @param {Node} node A DOM tree node.
345      * @param {Number} level The layer the node is attached to. This is the index of the layer in
346      * {@link JXG.SVGRenderer#layer} or the <tt>z-index</tt> style property of the node in VMLRenderer.
347      */
348     appendChildPrim: function (node, level) { /* stub */ },
349 
350     /**
351      * Stores the rendering nodes. This is an abstract method which has to be implemented in all renderers that use
352      * the <tt>createPrim</tt> method.
353      * @param {JXG.GeometryElement} element A JSXGraph element.
354      * @param {String} type The XML node name. Only used in VMLRenderer.
355      */
356     appendNodesToElement: function (element, type) { /* stub */ },
357 
358     /**
359      * Creates a node of a given type with a given id.
360      * @param {String} type The type of the node to create.
361      * @param {String} id Set the id attribute to this.
362      * @returns {Node} Reference to the created node.
363      */
364     createPrim: function (type, id) {
365         /* stub */
366         return null;
367     },
368 
369     /**
370      * Removes an element node. Just a stub.
371      * @param {Node} node The node to remove.
372      */
373     remove: function (node) { /* stub */ },    
374 
375     /**
376      * Can be used to create the nodes to display arrows. This is an abstract method which has to be implemented
377      * in any descendant renderer.
378      * @param {JXG.GeometryElement} element The element the arrows are to be attached to.
379      */
380     makeArrows: function(element) { /* stub */ },
381 
382     /**
383      * Updates an ellipse node primitive. This is an abstract method which has to be implemented in all renderers
384      * that use the <tt>createPrim</tt> method.
385      * @param {Node} node Reference to the node.
386      * @param {Number} x Centre X coordinate
387      * @param {Number} y Centre Y coordinate
388      * @param {Number} rx The x-axis radius.
389      * @param {Number} ry The y-axis radius.
390      */
391     updateEllipsePrim: function(node, x, y, rx, ry) { /* stub */ },
392 
393     /**
394      * Refreshes a line node. This is an abstract method which has to be implemented in all renderers that use
395      * the <tt>createPrim</tt> method.
396      * @param {Node} node The node to be refreshed.
397      * @param {Number} p1x The first point's x coordinate.
398      * @param {Number} p1y The first point's y coordinate.
399      * @param {Number} p2x The second point's x coordinate.
400      * @param {Number} p2y The second point's y coordinate.
401      * @param {JXG.Board} board
402      */
403     updateLinePrim: function(node, p1x, p1y, p2x, p2y, board) { /* stub */ },
404 
405     /**
406      * Updates a path element. This is an abstract method which has to be implemented in all renderers that use
407      * the <tt>createPrim</tt> method.
408      * @param {Node} node The path node.
409      * @param {String} pathString A string formatted like e.g. <em>'M 1,2 L 3,1 L5,5'</em>. The format of the string
410      * depends on the rendering engine.
411      * @param {JXG.Board} board Reference to the element's board.
412      */
413     updatePathPrim: function (node, pathString, board) { /* stub */ },
414 
415     /**
416      * Builds a path data string to draw a point with a face other than <em>rect</em> and <em>circle</em>. Since
417      * the format of such a string usually depends on the renderer this method
418      * is only an abstract method. Therefore, it has to be implemented in the descendant renderer itself unless
419      * the renderer does not use the createPrim interface but the draw* interfaces to paint.
420      * @param {JXG.Point} element The point element
421      * @param {Number} size A positive number describing the size. Usually the half of the width and height of
422      * the drawn point.
423      * @param {String} type A string describing the point's face. This method only accepts the shortcut version of
424      * each possible face: <tt>x, +, <>, ^, v, >, <
425      */
426     updatePathStringPoint: function (element, size, type) { /* stub */ },
427 
428     /**
429      * Builds a path data string from a {@link JXG.Curve} element. Since the path data strings heavily depend on the
430      * underlying rendering technique this method is just a stub. Although such a path string is of no use for the
431      * CanvasRenderer, this method is used there to draw a path directly.
432      * @param element
433      */
434     updatePathStringPrim: function (element) { /* stub */ },
435 
436     /**
437      * Builds a path data string from a {@link JXG.Curve} element such that the curve looks like
438      * hand drawn.
439      * Since the path data strings heavily depend on the
440      * underlying rendering technique this method is just a stub. Although such a path string is of no use for the
441      * CanvasRenderer, this method is used there to draw a path directly.
442      * @param element
443      */
444     updatePathStringBezierPrim: function (element) { /* stub */ },
445 
446     
447     /**
448      * Update a polygon primitive.
449      * @param {Node} node
450      * @param {JXG.Polygon} element A JSXGraph element of type {@link JXG.Polygon}
451      */
452     updatePolygonPrim: function (node, element) { /* stub */ },
453 
454     /**
455      * Update a rectangle primitive. This is used only for points with face of type 'rect'.
456      * @param {Node} node The node yearning to be updated.
457      * @param {Number} x x coordinate of the top left vertex.
458      * @param {Number} y y coordinate of the top left vertex.
459      * @param {Number} w Width of the rectangle.
460      * @param {Number} h The rectangle's height.
461      */
462     updateRectPrim: function(node, x, y, w, h) { /* stub */ },
463 
464     /* **************************
465      *  Set Attributes
466      * **************************/
467 
468     /**
469      * Sets a node's attribute.
470      * @param {Node} node The node that is to be updated.
471      * @param {String} key Name of the attribute.
472      * @param {String} val New value for the attribute.
473      */
474     setPropertyPrim: function (node, key, val) { /* stub */ },
475 
476     /**
477      * Shows a hidden element on the canvas; Only a stub, requires implementation in the derived renderer.
478      * @param {JXG.GeometryElement} element Reference to the object that has to appear.
479      * @see JXG.AbstractRenderer#hide
480      */
481     show: function (element) { /* stub */ },
482 
483     /**
484      * Hides an element on the canvas; Only a stub, requires implementation in the derived renderer.
485      * @param {JXG.GeometryElement} element Reference to the geometry element that has to disappear.
486      * @see JXG.AbstractRenderer#show
487      */
488     hide: function (element) { /* stub */ },
489 
490     /**
491      * Sets the buffering as recommended by SVGWG. Until now only Opera supports this and will be ignored by
492      * other browsers. Although this feature is only supported by SVG we have this method in {@link JXG.AbstractRenderer}
493      * because it is called from outside the renderer.
494      * @param {Node} node The SVG DOM Node which buffering type to update.
495      * @param {String} type Either 'auto', 'dynamic', or 'static'. For an explanation see
496      *   {@link http://www.w3.org/TR/SVGTiny12/painting.html#BufferedRenderingProperty}.
497      */
498     setBuffering: function (node, type) { /* stub */ },
499 
500     /**
501      * Sets an element's dash style.
502      * @param {JXG.GeometryElement} element An JSXGraph element.
503      */
504     setDashStyle: function (element) { /* stub */ },
505 
506     /**
507      * Puts an object into draft mode, i.e. it's visual appearance will be changed. For GEONE<sub>x</sub>T backwards compatibility.
508      * @param {JXG.GeometryElement} element Reference of the object that is in draft mode.
509      */
510     setDraft: function (element) { },
511 
512     /**
513      * Puts an object from draft mode back into normal mode.
514      * @param {JXG.GeometryElement} element Reference of the object that no longer is in draft mode.
515      */
516     removeDraft: function (element) { },
517 
518     /**
519      * Sets up nodes for rendering a gradient fill.
520      * @param element
521      */
522     setGradient: function (element) { /* stub */ },
523 
524     /**
525      * Updates the gradient fill.
526      * @param {JXG.GeometryElement} element An JSXGraph element with an area that can be filled.
527      */
528     updateGradient: function (element) { /* stub */ },
529 
530     /**
531      * Sets an objects fill color.
532      * @param {JXG.GeometryElement} element Reference of the object that wants a new fill color.
533      * @param {String} color Color in a HTML/CSS compatible format. If you don't want any fill color at all, choose 'none'.
534      * @param {Number} opacity Opacity of the fill color. Must be between 0 and 1.
535      */
536     setObjectFillColor: function (element, color, opacity) { /* stub */ },
537 
538     /**
539      * Changes an objects stroke color to the given color.
540      * @param {JXG.GeometryElement} element Reference of the {@link JXG.GeometryElement} that gets a new stroke color.
541      * @param {String} color Color value in a HTML compatible format, e.g. <strong>#00ff00</strong> or <strong>green</strong> for green.
542      * @param {Number} opacity Opacity of the fill color. Must be between 0 and 1.
543      */
544     setObjectStrokeColor: function (element, color, opacity) { /* stub */ },
545 
546     /**
547      * Sets an element's stroke width.
548      * @param {JXG.GeometryElement} element Reference to the geometry element.
549      * @param {Number} width The new stroke width to be assigned to the element.
550      */
551     setObjectStrokeWidth: function (element, width) { /* stub */ },
552     
553     /**
554      * Sets the shadow properties to a geometry element. This method is only a stub, it is implemented in the actual renderers.
555      * @param {JXG.GeometryElement} element Reference to a geometry object, that should get a shadow
556      */
557     setShadow: function (element) { /* stub */ },
558 
559     /**
560      * Highlights an object, i.e. changes the current colors of the object to its highlighting colors
561      * @param {JXG.GeometryElement} element Reference of the object that will be highlighted.
562      * @returns {JXG.AbstractRenderer} Reference to the renderer
563      */
564     highlight: function (element) { },
565 
566     /**
567      * Uses the normal colors of an object, i.e. the opposite of {@link JXG.AbstractRenderer#highlight}.
568      * @param {JXG.GeometryElement} element Reference of the object that will get its normal colors.
569      * @returns {JXG.AbstractRenderer} Reference to the renderer
570      */
571     noHighlight: function (element) { },
572 
573 
574     /* **************************
575      * renderer control
576      * **************************/
577 
578     /**
579      * Stop redraw. This method is called before every update, so a non-vector-graphics based renderer
580      * can use this method to delete the contents of the drawing panel. This is an abstract method every
581      * descendant renderer should implement, if appropriate.
582      * @see JXG.AbstractRenderer#unsuspendRedraw
583      */
584     suspendRedraw: function () { /* stub */ },
585 
586     /**
587      * Restart redraw. This method is called after updating all the rendering node attributes.
588      * @see JXG.AbstractRenderer#suspendRedraw
589      */
590     unsuspendRedraw: function () { /* stub */ },
591 
592     /**
593      * The tiny zoom bar shown on the bottom of a board (if showNavigation on board creation is true).
594      * @param {JXG.Board} board Reference to a JSXGraph board.
595      */
596     drawZoomBar: function (board) { },
597 
598     /**
599      * Wrapper for getElementById for maybe other renderers which elements are not directly accessible by DOM methods like document.getElementById().
600      * @param {String} id Unique identifier for element.
601      * @returns {Object} Reference to a JavaScript object. In case of SVG/VMLRenderer it's a reference to a SVG/VML node.
602      */
603     getElementById: function (id) {
604         return null;
605     },
606 
607     /**
608      * Resizes the rendering element
609      * @param {Number} w New width
610      * @param {Number} h New height
611      */
612     resize: function (w, h) { /* stub */}
613 
614 });
615 
616 //JXG.NoRenderer.prototype = new JXG.AbstractRenderer();
617