Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / ColorPalette.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.3.1
11  * Copyright(c) 2006-2010 Sencha Inc.
12  * licensing@sencha.com
13  * http://www.sencha.com/license
14  */
15 <div id="cls-Ext.ColorPalette"></div>/**
16  * @class Ext.ColorPalette
17  * @extends Ext.Component
18  * Simple color palette class for choosing colors.  The palette can be rendered to any container.<br />
19  * Here's an example of typical usage:
20  * <pre><code>
21 var cp = new Ext.ColorPalette({value:'993300'});  // initial selected color
22 cp.render('my-div');
23
24 cp.on('select', function(palette, selColor){
25     // do something with selColor
26 });
27 </code></pre>
28  * @constructor
29  * Create a new ColorPalette
30  * @param {Object} config The config object
31  * @xtype colorpalette
32  */
33 Ext.ColorPalette = Ext.extend(Ext.Component, {
34         <div id="cfg-Ext.ColorPalette-tpl"></div>/**
35          * @cfg {String} tpl An existing XTemplate instance to be used in place of the default template for rendering the component.
36          */
37     <div id="cfg-Ext.ColorPalette-itemCls"></div>/**
38      * @cfg {String} itemCls
39      * The CSS class to apply to the containing element (defaults to 'x-color-palette')
40      */
41     itemCls : 'x-color-palette',
42     <div id="cfg-Ext.ColorPalette-value"></div>/**
43      * @cfg {String} value
44      * The initial color to highlight (should be a valid 6-digit color hex code without the # symbol).  Note that
45      * the hex codes are case-sensitive.
46      */
47     value : null,
48     <div id="cfg-Ext.ColorPalette-clickEvent"></div>/**
49      * @cfg {String} clickEvent
50      * The DOM event that will cause a color to be selected. This can be any valid event name (dblclick, contextmenu). 
51      * Defaults to <tt>'click'</tt>.
52      */
53     clickEvent :'click',
54     // private
55     ctype : 'Ext.ColorPalette',
56
57     <div id="cfg-Ext.ColorPalette-allowReselect"></div>/**
58      * @cfg {Boolean} allowReselect If set to true then reselecting a color that is already selected fires the {@link #select} event
59      */
60     allowReselect : false,
61
62     <div id="prop-Ext.ColorPalette-colors"></div>/**
63      * <p>An array of 6-digit color hex code strings (without the # symbol).  This array can contain any number
64      * of colors, and each hex code should be unique.  The width of the palette is controlled via CSS by adjusting
65      * the width property of the 'x-color-palette' class (or assigning a custom class), so you can balance the number
66      * of colors with the width setting until the box is symmetrical.</p>
67      * <p>You can override individual colors if needed:</p>
68      * <pre><code>
69 var cp = new Ext.ColorPalette();
70 cp.colors[0] = 'FF0000';  // change the first box to red
71 </code></pre>
72
73 Or you can provide a custom array of your own for complete control:
74 <pre><code>
75 var cp = new Ext.ColorPalette();
76 cp.colors = ['000000', '993300', '333300'];
77 </code></pre>
78      * @type Array
79      */
80     colors : [
81         '000000', '993300', '333300', '003300', '003366', '000080', '333399', '333333',
82         '800000', 'FF6600', '808000', '008000', '008080', '0000FF', '666699', '808080',
83         'FF0000', 'FF9900', '99CC00', '339966', '33CCCC', '3366FF', '800080', '969696',
84         'FF00FF', 'FFCC00', 'FFFF00', '00FF00', '00FFFF', '00CCFF', '993366', 'C0C0C0',
85         'FF99CC', 'FFCC99', 'FFFF99', 'CCFFCC', 'CCFFFF', '99CCFF', 'CC99FF', 'FFFFFF'
86     ],
87
88     <div id="cfg-Ext.ColorPalette-handler"></div>/**
89      * @cfg {Function} handler
90      * Optional. A function that will handle the select event of this palette.
91      * The handler is passed the following parameters:<div class="mdetail-params"><ul>
92      * <li><code>palette</code> : ColorPalette<div class="sub-desc">The {@link #palette Ext.ColorPalette}.</div></li>
93      * <li><code>color</code> : String<div class="sub-desc">The 6-digit color hex code (without the # symbol).</div></li>
94      * </ul></div>
95      */
96     <div id="cfg-Ext.ColorPalette-scope"></div>/**
97      * @cfg {Object} scope
98      * The scope (<tt><b>this</b></tt> reference) in which the <code>{@link #handler}</code>
99      * function will be called.  Defaults to this ColorPalette instance.
100      */
101     
102     // private
103     initComponent : function(){
104         Ext.ColorPalette.superclass.initComponent.call(this);
105         this.addEvents(
106             <div id="event-Ext.ColorPalette-select"></div>/**
107              * @event select
108              * Fires when a color is selected
109              * @param {ColorPalette} this
110              * @param {String} color The 6-digit color hex code (without the # symbol)
111              */
112             'select'
113         );
114
115         if(this.handler){
116             this.on('select', this.handler, this.scope, true);
117         }    
118     },
119
120     // private
121     onRender : function(container, position){
122         this.autoEl = {
123             tag: 'div',
124             cls: this.itemCls
125         };
126         Ext.ColorPalette.superclass.onRender.call(this, container, position);
127         var t = this.tpl || new Ext.XTemplate(
128             '<tpl for="."><a href="#" class="color-{.}" hidefocus="on"><em><span style="background:#{.}" unselectable="on">&#160;</span></em></a></tpl>'
129         );
130         t.overwrite(this.el, this.colors);
131         this.mon(this.el, this.clickEvent, this.handleClick, this, {delegate: 'a'});
132         if(this.clickEvent != 'click'){
133                 this.mon(this.el, 'click', Ext.emptyFn, this, {delegate: 'a', preventDefault: true});
134         }
135     },
136
137     // private
138     afterRender : function(){
139         Ext.ColorPalette.superclass.afterRender.call(this);
140         if(this.value){
141             var s = this.value;
142             this.value = null;
143             this.select(s, true);
144         }
145     },
146
147     // private
148     handleClick : function(e, t){
149         e.preventDefault();
150         if(!this.disabled){
151             var c = t.className.match(/(?:^|\s)color-(.{6})(?:\s|$)/)[1];
152             this.select(c.toUpperCase());
153         }
154     },
155
156     <div id="method-Ext.ColorPalette-select"></div>/**
157      * Selects the specified color in the palette (fires the {@link #select} event)
158      * @param {String} color A valid 6-digit color hex code (# will be stripped if included)
159      * @param {Boolean} suppressEvent (optional) True to stop the select event from firing. Defaults to <tt>false</tt>.
160      */
161     select : function(color, suppressEvent){
162         color = color.replace('#', '');
163         if(color != this.value || this.allowReselect){
164             var el = this.el;
165             if(this.value){
166                 el.child('a.color-'+this.value).removeClass('x-color-palette-sel');
167             }
168             el.child('a.color-'+color).addClass('x-color-palette-sel');
169             this.value = color;
170             if(suppressEvent !== true){
171                 this.fireEvent('select', this, color);
172             }
173         }
174     }
175
176     <div id="cfg-Ext.ColorPalette-autoEl"></div>/**
177      * @cfg {String} autoEl @hide
178      */
179 });
180 Ext.reg('colorpalette', Ext.ColorPalette);</pre>    
181 </body>
182 </html>