JSignage:Path

.path()

$.path( attributes );

Returns: jSignage Object

Description

Draws the outline of a shape which can be filled or stroked. A path is described using the concept of a current point (i.e. the location of the pen). The outline of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves. See paths in the SVG specification for reference.

Parameters

• attributes

  Type: Plain Object.

  Contains the shape attributes.

Attributes

The following attributes can be specified:

• fill, stroke etc.

  Fill and stroke attributes (common to all shapes).

• d

  Type: String or Object.

  The definition of the outline of the shape, i.e. the path data, containing the moveto, line, curve (both cubic and quadratic Béziers) and closepath instructions (expressed as one character) and their coordinates. To improve the code readability, instead of the "raw" string, you can use the pathData class.

• pathLength

  Type: Number.

  The authoring length of the path for calibration. This is rarely needed.

pathData class

new $.pathData();

The pathData class helps building the path definition string necessary for the d attribute of the path function, using the class' human-friendly inner methods:

• .moveTo( x, y )

  Establish a new current point.

• .close()

  A straight line shall be drawn from the current point to the initial point of the current subpath, and shall end the current subpath.

• .lineTo( x, y )

  Draw straight lines from the current point to a new point.

• .curveTo( x1, y1, x2, y2, x, y )

  A cubic Bézier curve shall be drawn from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve.

• .smoothCurveTo( x2, y2, x, y )

  A cubic Bézier curve shall be drawn from the current point to (x,y). The first control point shall be the reflection of the second control point on the previous command relative to the current point.

• .quadTo( x1, y1, x, y )

  A quadratic Bézier curve is drawn from the current point to (x,y) using (x1,y1) as the control point.

• .smoothQuadTo( x, y )

  A quadratic Bézier curve is drawn from the current point to (x,y). The control point shall be the reflection of the control point on the previous command relative to the current point.

• .arcTo( rx, ry, rotation, largeArc, sweep, x, y )

  Draws an elliptical arc from the current point to (x,y). The size and orientation of the ellipse are defined by two radii (rx,ry) and an x-axis rotation, which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. The largeArc flag and sweep flag contribute to the automatic calculations and help determine how the arc is drawn.

Examples

See also these advanced examples using paths.

Triangle example

// draw a red triangle with blue outline and add it to the document
$.path( {
    fill:'red', stroke: 'blue', strokeWidth: 3,
    d: new $.pathData().moveTo( 100, 100 ).lineTo( 300, 100).lineTo( 200, 300).close()
}).addTo('svg');

Simple graph

/**
 * Draws a graph-path for the given set of values.
 * @param {Array.<number>} data The set of values.
 */
function doGraph( data ) {
    var min = 1.1,                              // minimum value
        max = 1.3,                              // maximum value
        width = 1280,                           // graph width
        height = 720,                           // graph height
        delta = width / ( data.length - 1 ),    // the size of each step
        path = new $.pathData();                // create a pathData object

    for ( i in data ) {
        // calculate the value on the y axis
        val = height - (data[i] - min) * height / (max - min); 
        if ( i == 0 ) {
            path.moveTo( 0, val );
        } else {
            path.lineTo( i * delta, val );
        }
    }
    
    // draw a blue path outline and add it to the document
    $.path( { fill:'none', stroke: 'blue', strokeWidth: 3, d: path }).addTo('svg');
}

// call the doGraph function using an array of numerical values
doGraph( [ 1.27907, 1.29758, 1.28666, 1.29704, 1.25372, 1.20917, 1.17659, 1.12028, 1.18173 ] );

Pie chart

/**
 * Draws a pie chart for the given set of values.
 * @param {Array.<number>} data The set of values.
 */
function doPie ( data ) {
    var width = 1280,                       // pie width
        height = 720,                       // pie height
        r = 300,                            // pie radius
        start = 0,                          // starting angle
        colors = ['red', 'green', 'blue', 'indigo', 'yellow', 'magenta', 'brown', 'gray', 'pink'];

    var xc = width / 2,                     // x coordinate of the center
        yc = height / 2,                    // y coordinate of the center
        xs = Math.sin( start ) * r + xc,    // x coordinate of starting point of the slice
        ys = Math.cos( start ) * r + yc,    // y coordinate of starting point of the slice
        sum = 0, angle, end, x, y, flag, path;
    
    for ( i in data ) {
        sum += data[i];     // calculate the sum of values
    }
   
    for ( i in data ) {
        angle = 2 * Math.PI / sum * data[i];    // convert the current value into an angle
        end = start + angle;                    // calculate the ending angle
        x = Math.sin( end ) * r + xc;           // x coordinate of ending point of the slice
        y = Math.cos( end ) * r + yc;           // y coordinate of ending point of the slice
        flag = ( angle > Math.PI ? 1 : 0 );
        
        path = new $.pathData();
        // build the path data
        path.moveTo( xc, yc ).lineTo( xs, ys ).arcTo( r, r, 0, flag, 0, x, y ).close();
        
        // draw a slice of the pie and add it to the document
        $.path( { fill: colors[i], stroke: 'black', strokeWidth: 1, d: path }).addTo('svg');
        
        // prepare for the next iteration
        xs = x; ys = y; start = end;
    }
}

// call the doPie function using an array of numerical values
doPie( [ 40, 30, 15, 10, 5 ] );