@@ -28,20 +28,35 @@ var Symbol = this.Symbol = Base.extend({
2828 * @name Symbol
2929 * @constructor
3030 *
31- * @example
32- * var circlePath = new Path.Circle(new Point(100, 100), 50);
33- * circlePath.fillColor = 'red';
31+ * @example {@paperscript split=true height=240 }
32+ * // Placing 100 instances of a symbol:
33+ * var path = new Path.Star(new Point(0, 0), 6, 5, 13);
34+ * path.style = {
35+ * fillColor: 'white',
36+ * strokeColor: 'black'
37+ * };
38+ *
39+ * // Create a symbol from the path:
40+ * var symbol = new Symbol(path);
3441 *
35- * var circleSymbol = new Symbol(circlePath);
36- *
37- * // The original item is still contained in the document:
38- * circlePath.remove();
39- *
40- * // Place an instance of the symbol in the document:
41- * var placedCircle = new PlacedSymbol(circleSymbol);
42- *
43- * // Move the placed symbol to {x: 150, y: 150}:
44- * placedCircle.position = new Point(150, 150);
42+ * // Remove the path:
43+ * path.remove();
44+ *
45+ * // Place 100 instances of the symbol:
46+ * for (var i = 0; i < 100; i++) {
47+ * // Place an instance of the symbol in the project:
48+ * var instance = symbol.place();
49+ *
50+ * // Move the instance to a random position within the view:
51+ * instance.position = Point.random() * view.size;
52+ *
53+ * // Rotate the instance by a random amount between
54+ * // 0 and 360 degrees:
55+ * instance.rotate(Math.random() * 360);
56+ *
57+ * // Scale the instance between 0.25 and 1:
58+ * instance.scale(0.25 + Math.random() * 0.75);
59+ * }
4560 *
4661 * @class Symbols allow you to place multiple instances of an item in your
4762 * project. This can save memory, since all instances of a symbol
@@ -86,6 +101,16 @@ var Symbol = this.Symbol = Base.extend({
86101 item . setPosition ( new Point ( ) ) ;
87102 } ,
88103
104+ /**
105+ * Places in instance of the symbol in the project.
106+ *
107+ * @param [position] The position of the placed symbol.
108+ * @return {PlacedSymbol }
109+ */
110+ place : function ( position ) {
111+ return new PlacedSymbol ( this , position ) ;
112+ } ,
113+
89114 /**
90115 * Returns a copy of the symbol.
91116 *
0 commit comments