/*
 * Paper.js
 *
 * This file is part of Paper.js, a JavaScript Vector Graphics Library,
 * based on Scriptographer.org and designed to be largely API compatible.
 * http://paperjs.org/
 * http://scriptographer.org/
 *
 * Distributed under the MIT license. See LICENSE file for details.
 *
 * Copyright (c) 2011, Juerg Lehni & Jonathan Puckey
 * http://lehni.org/ & http://jonathanpuckey.com/
 *
 * All rights reserved.
 */

var Group = this.Group = Item.extend({
	/** @lends Group# */

	beans: true,

	/**
	 * Creates a new Group item and places it at the top of the active layer.
	 * 
	 * @param {Array} [children] An optional array of children that will be
	 * added to the newly created group.
	 * 
	 * @example
	 * // Create an empty group and append a path to the top of its children
	 * // array:
	 * 
	 * // Create an empty group:
	 * var group = new Group();
	 * 
	 * var path = new Path([new Point(10, 10), new Point(50, 50)]);
	 * path.strokeColor = 'black';
	 * 
	 * // Append the path to the group:
	 * group.appendTop(path);
	 * 
	 * // Set the stroke color of all items in the group:
	 * circleGroup.strokeColor = 'black';
	 * 
	 * @example
	 * // Create a group containing two paths:
	 * var circle = new Path.Circle(new Point(30, 50), 10);
	 * var circle2 = new Path.Circle(new Point(50, 50), 10);
	 * 
	 * var circleGroup = new Group([circle, circle2]);
	 * // Set the fill color of all items in the group:
	 * circleGroup.fillColor = 'black';
	 * 
	 * @class A Group is a collection of items. When you transform a Group, its
	 * children are treated as a single unit without changing their relative
	 * positions.
	 * @extends Item
	 * @constructs Group
	 */
	initialize: function(items) {
		this.base();
		this._children = [];
		this._namedChildren = {};
		this._clipped = false;
		this.setChildren(!items || !Array.isArray(items)
				|| typeof items[0] !== 'object' ? arguments : items);
	},

	clone: function() {
		var copy = this.base();
		copy._clipped = this._clipped;
		return copy;
	},

	/**
	 * Specifies whether the group item is to be clipped.
	 * When setting to {@code true}, the first child in the group is
	 * automatically defined as the clipping mask.
	 *
	 * @type Boolean
	 * @bean
	 */
	isClipped: function() {
		return this._clipped;
	},

	setClipped: function(clipped) {
		this._clipped = clipped;
		var child = this.getFirstChild();
		if (child)
			child.setClipMask(clipped);
	},

	draw: function(ctx, param) {
		for (var i = 0, l = this._children.length; i < l; i++) {
			Item.draw(this._children[i], ctx, param);
			if (this._clipped && i == 0)
				ctx.clip();
		}
	}
});

@@ -496,16 +496,61 @@
  true,%0A%0A
+%09// DOCS: document new Group(item, item...);%0A
 %09/**%0A%09 *
@@ -758,166 +758,157 @@
 mple
-%0A%09 * // Create an empty group and append a path to the top of its children%0A%09 * // array:%0A%09 * %0A%09 * // Create an empty group:%0A%09 * var group = new Group(
+ %7B@paperscript split=true height=200%7D%0A%09 * // Create a group containing two paths:%0A%09 * var path = new Path(new Point(100, 100), new Point(100, 200)
 );%0A
-%09 * %0A
 %09 * 
@@ -907,32 +907,33 @@
 ));%0A%09 * var path
+2
  = new Path(%5Bnew
@@ -928,17 +928,16 @@
 ew Path(
-%5B
 new Poin
@@ -942,13 +942,14 @@
 int(
-1
+5
 0, 1
+5
 0), 
@@ -962,117 +962,106 @@
 int(
+1
 50, 
+1
 50)
-%5D
 );%0A%09 * 
-path.strokeColor = 'black';%0A%09 * %0A%09 * // Append the path to the group
+%0A%09 * // Create a group from the two paths
 :%0A%09 *
+ var
  group
-.appendTo
+ = new Grou
 p(
+%5B
 path
+, path2%5D
 );%0A%09
@@ -1119,31 +1119,25 @@
  group:%0A%09 * 
-circleG
+g
 roup.strokeC
@@ -1165,133 +1165,388 @@
 %09 * 
-@example%0A%09 * // Create a group containing two paths:%0A%09 * var circle =
+// Move the group to the center of the view:%0A%09 * group.position = view.center;%0A%09 * %0A%09 * @example %7B@paperscript split=true%7D%0A%09 * // Click in the view to add a path to the group, which in turn is rotated%0A%09 * // every frame:%0A%09 * var group = new Group();%0A%09 * %0A%09 * function onMouseDown(event) %7B%0A%09 * %09// Create a
  new 
-Path.Circle(new Point(30, 50), 10);
+circle shaped path at the position%0A%09 * %09// of the mouse:
 %0A%09 * 
+%09
 var 
-circle2
+path
  = n
@@ -1564,178 +1564,312 @@
 cle(
-new Point(50, 50), 10);%0A%09 * %0A%09 * var circleGroup = new Group(%5Bcircle, circle2%5D);
+event.point, 5);%0A%09 * %09path.fillColor = 'black';%0A%09 * %0A%09 * %09// Move the path to the top of the group's children list:%0A%09 * %09group.appendTop(path);%0A%09 * %7D%0A%09 * %0A%09 * function onFrame(event) %7B
 %0A%09 * 
+%09
 // 
-Set the fill color of all items in the group:%0A%09 * circleGroup.fillColor = 'black';
+Rotate the group by 1 degree from%0A%09 * %09// the centerpoint of the view:%0A%09 * %09group.rotate(1, view.center);%0A%09 * %7D
 %0A%09 *

Improve Group example code.