From dab421143cf719370cb3739d07e3e411d555cf3c Mon Sep 17 00:00:00 2001 From: wout Date: Wed, 19 Dec 2012 13:22:07 +0100 Subject: [PATCH] Updated Readme --- README.md | 97 ++++++++++++++++++++++++++++++++++++++---------- Rakefile | 2 +- dist/svg.js | 41 ++++++++++++++------ dist/svg.min.js | 4 +- src/container.js | 2 +- src/sugar.js | 17 +++++++++ 6 files changed, 128 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 30a0d47..0558792 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Svg.js -Svg.js is a small JavaScript library for manipulating SVG. - -Have a look at [svgjs.com](http://svgjs.com) for a examples. +Svg.js is a lightweight (2k gzipped) library for manipulating SVG. Svg.js is licensed under the terms of the MIT License. @@ -54,6 +52,20 @@ rect.attr({ rect.attr('x', 50, 'http://www.w3.org/2000/svg'); ``` + +#### Transform +With the transform attribute elements can be scaled, rotated, translated, skewed... : +```javascript +rect.transform('rotate(45, 100, 100)'); +``` +Every transformation will remembered so multiple rotate operations will be stacked together making them relative to previous operations. To ensure absolute operations a boolean value can be passed as a second argument: +```javascript +rect.transform('rotate(45, 100, 100)', true); +``` +More details on available transformations can be found here: +http://www.w3.org/TR/SVG/coords.html#TransformAttribute + + #### Move Move the element to a given x and y position by its upper left corner: ```javascript @@ -61,9 +73,9 @@ rect.move(200, 350); ``` Note that you can also use the following code to move elements around: ```javascript -rect.attr({ x: 20, y: 60 }) +rect.attr({ x: 20, y: 60 }); ``` -Although 'move()' is much more convenient because it will always use the upper left corner as the position reference, whereas with using 'attr()' the x an y reference differ between element types. For example, rect uses the upper left corner and circle uses the center. +Although 'move()' is much more convenient because it will always use the upper left corner as the position reference, whereas with using 'attr()' the x an y reference differ between element types. For example, rect uses the upper left corner and circle uses the centre. #### Size @@ -74,27 +86,27 @@ rect.size(200, 300); Same as with 'move()' the size of an element could be set by using 'attr()'. But because every type of element is handles its size differently the 'size()' function is much more convenient. -#### Fill -The 'fill()' function is a pretty alternative to the 'attr()' method: +#### Removing elements +Pretty straightforward: ```javascript -rect.fill({ color: '#f06', opacity: 0.6 }); +rect.remove(); ``` -#### Stroke -The 'stroke()' function is similar to 'fill()': -```javascript -rect.stroke({ color: '#f06', opacity: 0.6, width: 5 }); -``` -#### Removing elements -Pretty straightforward: +### Image element +When creating images the width and height values should be defined: ```javascript -rect.remove(); +var image = draw.image({ + width: 200, + height: 200, + x: 100, + y: 100, + src: '/path/to/image.jpg' +}); ``` ### Path element - ```javascript var path = draw.path({ data: "M10,20L30,40" }).attr({ fill: '#9dffd3' }); ``` @@ -114,6 +126,39 @@ This will return a SVGRect element as a js object: { height: 20, width: 20, y: 20, x: 10 } ``` + +### Syntax sugar +Fill and stroke are used quite often. Therefore two convenience methods are provided: + +#### Fill +The 'fill()' function is a pretty alternative to the 'attr()' method: +```javascript +rect.fill({ color: '#f06', opacity: 0.6 }); +``` + +#### Stroke +The 'stroke()' function is similar to 'fill()': +```javascript +rect.stroke({ color: '#f06', opacity: 0.6, width: 5 }); +``` + +#### Rotate +The 'rotate()' method will automatically rotate elements according to the centre of the element: +```javascript +rect.rotate({ deg: 45 }); +``` +But you also define a rotation point: +```javascript +rect.rotate({ deg: 45, x: 100, y: 100 }); +``` +To make the operation absolute: +```javascript +rect.rotate({ deg: 45, x: 100, y: 100, absolute: true }); +``` + +_This functionality requires the sugar.js module which is included in the default distribution._ + + ### Clipping elements Clipping elements can be done with either 'clip()' or 'clipTo()'. @@ -132,7 +177,7 @@ clipRect = clipPath.rect({ x:10, y:10, width:80, height:80 }); rect.clipTo(clipPath); ``` -This functionality requires the clip.js module which is included in the default distribution. +_This functionality requires the clip.js module which is included in the default distribution._ ### Arranging elements @@ -152,7 +197,21 @@ rect.forward(); rect.backward(); ``` -This functionality requires the arrange.js module which is included in the default distribution. +_This functionality requires the arrange.js module which is included in the default distribution._ + + +### Grouping elements +Grouping elements is useful if you want to transform a set of elements as if it were one. All element within a group maintain their position relative to the group they belong to. A group has all the same element methods as the root svg document: +```javascript +var group = draw.group(); +group.path({ data: "M10,20L30,40" }); +``` +Existing elements from the svg document can also be added to a group: +```javascript +group.add(rect); +``` + +_This functionality requires the group.js module which is included in the default distribution._ ## Compatibility diff --git a/Rakefile b/Rakefile index 5d3dc72..493430c 100644 --- a/Rakefile +++ b/Rakefile @@ -1,7 +1,7 @@ SVGJS_VERSION = '0.1a' # all available modules in the correct loading order -ALL = %w[ svg container element arrange clip doc defs shape rect circle ellipse path image group sugar ] +ALL = %w[ svg container element group arrange clip doc defs shape rect circle ellipse path image sugar ] # required modules to make the library operational CORE = %w[ circle container defs doc element ellipse image path rect shape svg ] diff --git a/dist/svg.js b/dist/svg.js index 9358be1..62dc9d5 100644 --- a/dist/svg.js +++ b/dist/svg.js @@ -1,4 +1,4 @@ -/* svg.js 0.1a - svg container element arrange clip doc defs shape rect circle ellipse path image group sugar - svgjs.com/license */ +/* svg.js 0.1a - svg container element group arrange clip doc defs shape rect circle ellipse path image sugar - svgjs.com/license */ (function() { this.SVG = { @@ -33,7 +33,7 @@ }, has: function(e) { - return Array.prototype.indexOf.call(this.children(), e) >= 0; + return this.children().indexOf(e) >= 0; }, children: function() { @@ -253,6 +253,16 @@ }); + SVG.G = function G() { + this.constructor.call(this, SVG.create('g')); + }; + + // inherit from SVG.Element + SVG.G.prototype = new SVG.Element(); + + // include the container object + SVG.extend(SVG.G, SVG.Container); + SVG.extend(SVG.Element, { // get all siblings, including me @@ -509,16 +519,6 @@ }); - SVG.G = function G() { - this.constructor.call(this, SVG.create('g')); - }; - - // inherit from SVG.Element - SVG.G.prototype = new SVG.Element(); - - // include the container object - SVG.extend(SVG.G, SVG.Container); - SVG.extend(SVG.Shape, { // set fill color and opacity @@ -557,6 +557,7 @@ // rotation rotate: function(o) { var b = this.bbox(); + if (o.x == null) o.x = b.cx; if (o.y == null) o.y = b.cy; @@ -566,6 +567,22 @@ } }); + + // Add group-specific functions + SVG.extend(SVG.G, { + + // move using translate + move: function(x, y) { + this.transform('translate(' + x + ' ' + y + ')', true); + + return this; + } + + }); + + + + }).call(this); diff --git a/dist/svg.min.js b/dist/svg.min.js index 8e23f03..937bc37 100644 --- a/dist/svg.min.js +++ b/dist/svg.min.js @@ -1,2 +1,2 @@ -/* svg.js 0.1a - svg container element arrange clip doc defs shape rect circle ellipse path image group sugar - svgjs.com/license */ -(function(){this.SVG={ns:"http://www.w3.org/2000/svg",xlink:"http://www.w3.org/1999/xlink",create:function(e){return document.createElementNS(this.ns,e)},extend:function(e,t){for(var n in t)e.prototype[n]=t[n]}},this.svg=function(e){return new SVG.Doc(e)},SVG.Container={add:function(e,t){return this.has(e)||(t=t==null?this.children().length:t,this.children().splice(t,0,e),this.node.insertBefore(e.node,this.node.childNodes[t]),e.parent=this),this},has:function(e){return Array.prototype.indexOf.call(this.children(),e)>=0},children:function(){return this._children||(this._children=[])},remove:function(e){return this.removeAt(this.children().indexOf(e))},removeAt:function(e){if(0<=e&&e1&&t.remove(this).add(this,e-1),this},front:function(){return this.mother().remove(this).add(this),this},back:function(){var e,t=this.mother();return t.levelDefs(),e=this.siblings().indexOf(this),e>1&&t.remove(this).add(this,0),this}});var e=0;SVG.Clip=function(){this.constructor.call(this,SVG.create("clipPath")),this.id="_"+e++,this.attr("id",this.id)},SVG.Clip.prototype=new SVG.Element,SVG.extend(SVG.Clip,SVG.Container),SVG.extend(SVG.Element,{clip:function(e){var t=this.mother().defs().clipPath();return e(t),this.clipTo(t)},clipTo:function(e){return this.attr("clip-path","url(#"+e.id+")")}}),SVG.Doc=function(t){this.constructor.call(this,SVG.create("svg")),this.attr("xmlns",SVG.ns),this.attr("version","1.1"),this.attr("xlink",SVG.xlink,SVG.ns),this.defs(),typeof t=="string"&&(t=document.getElementById(t)),t.appendChild(this.node)},SVG.Doc.prototype=new SVG.Element,SVG.extend(SVG.Doc,SVG.Container),SVG.Defs=function(){this.constructor.call(this,SVG.create("defs"))},SVG.Defs.prototype=new SVG.Element,SVG.extend(SVG.Defs,SVG.Container),SVG.extend(SVG.Defs,{clipPath:function(){var e=new SVG.Clip;return this.add(e),e}}),SVG.Shape=function(t){this.constructor.call(this,t)},SVG.Shape.prototype=new SVG.Element,SVG.Rect=function(){this.constructor.call(this,SVG.create("rect"))},SVG.Rect.prototype=new SVG.Shape,SVG.Circle=function(){this.constructor.call(this,SVG.create("circle"))},SVG.Circle.prototype=new SVG.Shape,SVG.extend(SVG.Circle,{move:function(e,t){return this.attrs.x=e,this.attrs.y=t,this.center(),this},size:function(e){return this.attr("r",e/2),this.center(),this},center:function(e,t){var n=this.attrs.r||0;this.attr("cx",e||(this.attrs.x||0)+n),this.attr("cy",t||(this.attrs.y||0)+n)}}),SVG.Ellipse=function(){this.constructor.call(this,SVG.create("ellipse"))},SVG.Ellipse.prototype=new SVG.Shape,SVG.extend(SVG.Ellipse,{move:function(e,t){return this.attrs.x=e,this.attrs.y=t,this.center(),this},size:function(e,t){return this.attr("rx",e/2),this.attr("ry",t/2),this.center(),this},center:function(e,t){this.attr("cx",e||(this.attrs.x||0)+(this.attrs.rx||0)),this.attr("cy",t||(this.attrs.y||0)+(this.attrs.ry||0))}}),SVG.Path=function(){this.constructor.call(this,SVG.create("path"))},SVG.Path.prototype=new SVG.Shape,SVG.extend(SVG.Path,{data:function(e){return this.attr("d",e),this}}),SVG.Image=function(){this.constructor.call(this,SVG.create("image"))},SVG.Image.prototype=new SVG.Element,SVG.extend(SVG.Image,SVG.Container),SVG.extend(SVG.Image,{load:function(e){return this.attr("href",e,SVG.xlink),this}}),SVG.G=function(){this.constructor.call(this,SVG.create("g"))},SVG.G.prototype=new SVG.Element,SVG.extend(SVG.G,SVG.Container),SVG.extend(SVG.Shape,{fill:function(e){return e.color!=null&&this.attr("fill",e.color),e.opacity!=null&&this.attr("fill-opacity",e.opacity),this},stroke:function(e){e.color&&this.attr("stroke",e.color);var t="width opacity linecap linejoin miterlimit dasharray dashoffset".split(" ");for(var n=t.length-1;n>=0;n--)e[t[n]]!=null&&this.attr("stroke-"+t[n],e[t[n]]);return this}}),SVG.extend(SVG.Element,{rotate:function(e){var t=this.bbox();return e.x==null&&(e.x=t.cx),e.y==null&&(e.y=t.cy),this.transform("rotate("+(e.deg||0)+" "+e.x+" "+e.y+")",e.absolute),this}})}).call(this); \ No newline at end of file +/* svg.js 0.1a - svg container element group arrange clip doc defs shape rect circle ellipse path image sugar - svgjs.com/license */ +(function(){this.SVG={ns:"http://www.w3.org/2000/svg",xlink:"http://www.w3.org/1999/xlink",create:function(e){return document.createElementNS(this.ns,e)},extend:function(e,t){for(var n in t)e.prototype[n]=t[n]}},this.svg=function(e){return new SVG.Doc(e)},SVG.Container={add:function(e,t){return this.has(e)||(t=t==null?this.children().length:t,this.children().splice(t,0,e),this.node.insertBefore(e.node,this.node.childNodes[t]),e.parent=this),this},has:function(e){return this.children().indexOf(e)>=0},children:function(){return this._children||(this._children=[])},remove:function(e){return this.removeAt(this.children().indexOf(e))},removeAt:function(e){if(0<=e&&e1&&t.remove(this).add(this,e-1),this},front:function(){return this.mother().remove(this).add(this),this},back:function(){var e,t=this.mother();return t.levelDefs(),e=this.siblings().indexOf(this),e>1&&t.remove(this).add(this,0),this}});var e=0;SVG.Clip=function(){this.constructor.call(this,SVG.create("clipPath")),this.id="_"+e++,this.attr("id",this.id)},SVG.Clip.prototype=new SVG.Element,SVG.extend(SVG.Clip,SVG.Container),SVG.extend(SVG.Element,{clip:function(e){var t=this.mother().defs().clipPath();return e(t),this.clipTo(t)},clipTo:function(e){return this.attr("clip-path","url(#"+e.id+")")}}),SVG.Doc=function(t){this.constructor.call(this,SVG.create("svg")),this.attr("xmlns",SVG.ns),this.attr("version","1.1"),this.attr("xlink",SVG.xlink,SVG.ns),this.defs(),typeof t=="string"&&(t=document.getElementById(t)),t.appendChild(this.node)},SVG.Doc.prototype=new SVG.Element,SVG.extend(SVG.Doc,SVG.Container),SVG.Defs=function(){this.constructor.call(this,SVG.create("defs"))},SVG.Defs.prototype=new SVG.Element,SVG.extend(SVG.Defs,SVG.Container),SVG.extend(SVG.Defs,{clipPath:function(){var e=new SVG.Clip;return this.add(e),e}}),SVG.Shape=function(t){this.constructor.call(this,t)},SVG.Shape.prototype=new SVG.Element,SVG.Rect=function(){this.constructor.call(this,SVG.create("rect"))},SVG.Rect.prototype=new SVG.Shape,SVG.Circle=function(){this.constructor.call(this,SVG.create("circle"))},SVG.Circle.prototype=new SVG.Shape,SVG.extend(SVG.Circle,{move:function(e,t){return this.attrs.x=e,this.attrs.y=t,this.center(),this},size:function(e){return this.attr("r",e/2),this.center(),this},center:function(e,t){var n=this.attrs.r||0;this.attr("cx",e||(this.attrs.x||0)+n),this.attr("cy",t||(this.attrs.y||0)+n)}}),SVG.Ellipse=function(){this.constructor.call(this,SVG.create("ellipse"))},SVG.Ellipse.prototype=new SVG.Shape,SVG.extend(SVG.Ellipse,{move:function(e,t){return this.attrs.x=e,this.attrs.y=t,this.center(),this},size:function(e,t){return this.attr("rx",e/2),this.attr("ry",t/2),this.center(),this},center:function(e,t){this.attr("cx",e||(this.attrs.x||0)+(this.attrs.rx||0)),this.attr("cy",t||(this.attrs.y||0)+(this.attrs.ry||0))}}),SVG.Path=function(){this.constructor.call(this,SVG.create("path"))},SVG.Path.prototype=new SVG.Shape,SVG.extend(SVG.Path,{data:function(e){return this.attr("d",e),this}}),SVG.Image=function(){this.constructor.call(this,SVG.create("image"))},SVG.Image.prototype=new SVG.Element,SVG.extend(SVG.Image,SVG.Container),SVG.extend(SVG.Image,{load:function(e){return this.attr("href",e,SVG.xlink),this}}),SVG.extend(SVG.Shape,{fill:function(e){return e.color!=null&&this.attr("fill",e.color),e.opacity!=null&&this.attr("fill-opacity",e.opacity),this},stroke:function(e){e.color&&this.attr("stroke",e.color);var t="width opacity linecap linejoin miterlimit dasharray dashoffset".split(" ");for(var n=t.length-1;n>=0;n--)e[t[n]]!=null&&this.attr("stroke-"+t[n],e[t[n]]);return this}}),SVG.extend(SVG.Element,{rotate:function(e){var t=this.bbox();return e.x==null&&(e.x=t.cx),e.y==null&&(e.y=t.cy),this.transform("rotate("+(e.deg||0)+" "+e.x+" "+e.y+")",e.absolute),this}}),SVG.extend(SVG.G,{move:function(e,t){return this.transform("translate("+e+" "+t+")",!0),this}})}).call(this); \ No newline at end of file diff --git a/src/container.js b/src/container.js index 46e8200..d24fe17 100644 --- a/src/container.js +++ b/src/container.js @@ -13,7 +13,7 @@ SVG.Container = { }, has: function(e) { - return Array.prototype.indexOf.call(this.children(), e) >= 0; + return this.children().indexOf(e) >= 0; }, children: function() { diff --git a/src/sugar.js b/src/sugar.js index 9b5b482..a9e1458 100644 --- a/src/sugar.js +++ b/src/sugar.js @@ -38,6 +38,7 @@ SVG.extend(SVG.Element, { // rotation rotate: function(o) { var b = this.bbox(); + if (o.x == null) o.x = b.cx; if (o.y == null) o.y = b.cy; @@ -47,3 +48,19 @@ SVG.extend(SVG.Element, { } }); + +// Add group-specific functions +SVG.extend(SVG.G, { + + // move using translate + move: function(x, y) { + this.transform('translate(' + x + ' ' + y + ')', true); + + return this; + } + +}); + + + + -- 2.39.5