Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Component5.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-draw-Component'>/**
19 </span> * @class Ext.draw.Component
20  * @extends Ext.Component
21  *
22  * The Draw Component is a surface in which sprites can be rendered. The Draw Component
23  * manages and holds a `Surface` instance: an interface that has
24  * an SVG or VML implementation depending on the browser capabilities and where
25  * Sprites can be appended.
26  * {@img Ext.draw.Component/Ext.draw.Component.png Ext.draw.Component component}
27  * One way to create a draw component is:
28  * 
29  *     var drawComponent = Ext.create('Ext.draw.Component', {
30  *         viewBox: false,
31  *         items: [{
32  *             type: 'circle',
33  *             fill: '#79BB3F',
34  *             radius: 100,
35  *             x: 100,
36  *             y: 100
37  *         }]
38  *     });
39  *   
40  *     Ext.create('Ext.Window', {
41  *         width: 215,
42  *         height: 235,
43  *         layout: 'fit',
44  *         items: [drawComponent]
45  *     }).show();
46  * 
47  * In this case we created a draw component and added a sprite to it.
48  * The *type* of the sprite is *circle* so if you run this code you'll see a yellow-ish
49  * circle in a Window. When setting `viewBox` to `false` we are responsible for setting the object's position and
50  * dimensions accordingly. 
51  * 
52  * You can also add sprites by using the surface's add method:
53  *    
54  *     drawComponent.surface.add({
55  *         type: 'circle',
56  *         fill: '#79BB3F',
57  *         radius: 100,
58  *         x: 100,
59  *         y: 100
60  *     });
61  *  
62  * For more information on Sprites, the core elements added to a draw component's surface,
63  * refer to the Ext.draw.Sprite documentation.
64  */
65 Ext.define('Ext.draw.Component', {
66
67     /* Begin Definitions */
68
69     alias: 'widget.draw',
70
71     extend: 'Ext.Component',
72
73     requires: [
74         'Ext.draw.Surface',
75         'Ext.layout.component.Draw'
76     ],
77
78     /* End Definitions */
79
80 <span id='Ext-draw-Component-cfg-enginePriority'>    /**
81 </span>     * @cfg {Array} enginePriority
82      * Defines the priority order for which Surface implementation to use. The first
83      * one supported by the current environment will be used.
84      */
85     enginePriority: ['Svg', 'Vml'],
86
87     baseCls: Ext.baseCSSPrefix + 'surface',
88
89     componentLayout: 'draw',
90
91 <span id='Ext-draw-Component-cfg-viewBox'>    /**
92 </span>     * @cfg {Boolean} viewBox
93      * Turn on view box support which will scale and position items in the draw component to fit to the component while
94      * maintaining aspect ratio. Note that this scaling can override other sizing settings on yor items. Defaults to true.
95      */
96     viewBox: true,
97
98 <span id='Ext-draw-Component-cfg-autoSize'>    /**
99 </span>     * @cfg {Boolean} autoSize
100      * Turn on autoSize support which will set the bounding div's size to the natural size of the contents. Defaults to false.
101      */
102     autoSize: false,
103     
104 <span id='Ext-draw-Component-cfg-gradients'>    /**
105 </span>     * @cfg {Array} gradients (optional) Define a set of gradients that can be used as `fill` property in sprites.
106      * The gradients array is an array of objects with the following properties:
107      *
108      * &lt;ul&gt;
109      * &lt;li&gt;&lt;strong&gt;id&lt;/strong&gt; - string - The unique name of the gradient.&lt;/li&gt;
110      * &lt;li&gt;&lt;strong&gt;angle&lt;/strong&gt; - number, optional - The angle of the gradient in degrees.&lt;/li&gt;
111      * &lt;li&gt;&lt;strong&gt;stops&lt;/strong&gt; - object - An object with numbers as keys (from 0 to 100) and style objects
112      * as values&lt;/li&gt;
113      * &lt;/ul&gt;
114      * 
115      
116      For example:
117      
118      &lt;pre&gt;&lt;code&gt;
119         gradients: [{
120             id: 'gradientId',
121             angle: 45,
122             stops: {
123                 0: {
124                     color: '#555'
125                 },
126                 100: {
127                     color: '#ddd'
128                 }
129             }
130         },  {
131             id: 'gradientId2',
132             angle: 0,
133             stops: {
134                 0: {
135                     color: '#590'
136                 },
137                 20: {
138                     color: '#599'
139                 },
140                 100: {
141                     color: '#ddd'
142                 }
143             }
144         }]
145      &lt;/code&gt;&lt;/pre&gt;
146      
147      Then the sprites can use `gradientId` and `gradientId2` by setting the fill attributes to those ids, for example:
148      
149      &lt;pre&gt;&lt;code&gt;
150         sprite.setAttributes({
151             fill: 'url(#gradientId)'
152         }, true);
153      &lt;/code&gt;&lt;/pre&gt;
154      
155      */
156
157     initComponent: function() {
158         this.callParent(arguments);
159
160         this.addEvents(
161             'mousedown',
162             'mouseup',
163             'mousemove',
164             'mouseenter',
165             'mouseleave',
166             'click'
167         );
168     },
169
170 <span id='Ext-draw-Component-method-onRender'>    /**
171 </span>     * @private
172      *
173      * Create the Surface on initial render
174      */
175     onRender: function() {
176         var me = this,
177             viewBox = me.viewBox,
178             autoSize = me.autoSize,
179             bbox, items, width, height, x, y;
180         me.callParent(arguments);
181
182         me.createSurface();
183
184         items = me.surface.items;
185
186         if (viewBox || autoSize) {
187             bbox = items.getBBox();
188             width = bbox.width;
189             height = bbox.height;
190             x = bbox.x;
191             y = bbox.y;
192             if (me.viewBox) {
193                 me.surface.setViewBox(x, y, width, height);
194             }
195             else {
196                 // AutoSized
197                 me.autoSizeSurface();
198             }
199         }
200     },
201
202     //@private
203     autoSizeSurface: function() {
204         var me = this,
205             items = me.surface.items,
206             bbox = items.getBBox(),
207             width = bbox.width,
208             height = bbox.height;
209         items.setAttributes({
210             translate: {
211                 x: -bbox.x,
212                 //Opera has a slight offset in the y axis.
213                 y: -bbox.y + (+Ext.isOpera)
214             }
215         }, true);
216         if (me.rendered) {
217             me.setSize(width, height);
218             me.surface.setSize(width, height);
219         }
220         else {
221             me.surface.setSize(width, height);
222         }
223         me.el.setSize(width, height);
224     },
225
226 <span id='Ext-draw-Component-method-createSurface'>    /**
227 </span>     * Create the Surface instance. Resolves the correct Surface implementation to
228      * instantiate based on the 'enginePriority' config. Once the Surface instance is
229      * created you can use the handle to that instance to add sprites. For example:
230      *
231      &lt;pre&gt;&lt;code&gt;
232         drawComponent.surface.add(sprite);
233      &lt;/code&gt;&lt;/pre&gt;
234      */
235     createSurface: function() {
236         var surface = Ext.draw.Surface.create(Ext.apply({}, {
237                 width: this.width,
238                 height: this.height,
239                 renderTo: this.el
240             }, this.initialConfig));
241         this.surface = surface;
242
243         function refire(eventName) {
244             return function(e) {
245                 this.fireEvent(eventName, e);
246             };
247         }
248
249         surface.on({
250             scope: this,
251             mouseup: refire('mouseup'),
252             mousedown: refire('mousedown'),
253             mousemove: refire('mousemove'),
254             mouseenter: refire('mouseenter'),
255             mouseleave: refire('mouseleave'),
256             click: refire('click')
257         });
258     },
259
260
261 <span id='Ext-draw-Component-method-onDestroy'>    /**
262 </span>     * @private
263      * 
264      * Clean up the Surface instance on component destruction
265      */
266     onDestroy: function() {
267         var surface = this.surface;
268         if (surface) {
269             surface.destroy();
270         }
271         this.callParent(arguments);
272     }
273
274 });
275 </pre>
276 </body>
277 </html>