Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / src / picker / Color.js
1 /**
2  * @class Ext.picker.Color
3  * @extends Ext.Component
4  * <p>ColorPicker provides a simple color palette for choosing colors. The picker can be rendered to any container.
5  * The available default to a standard 40-color palette; this can be customized with the {@link #colors} config.</p>
6  * <p>Typically you will need to implement a handler function to be notified when the user chooses a color from the
7  * picker; you can register the handler using the {@link #select} event, or by implementing the {@link #handler}
8  * method.</p>
9  * <p>Here's an example of typical usage:</p>
10  * <pre><code>var cp = new Ext.picker.Color({
11     value: '993300',  // initial selected color
12     renderTo: 'my-div'
13 });
14
15 cp.on('select', function(picker, selColor){
16     // do something with selColor
17 });
18 </code></pre>
19  * {@img Ext.picker.Color/Ext.picker.Color.png Ext.picker.Color component}
20  *
21  * @constructor
22  * Create a new ColorPicker
23  * @param {Object} config The config object
24  * 
25  * @xtype colorpicker
26  */
27 Ext.define('Ext.picker.Color', {
28     extend: 'Ext.Component',
29     requires: 'Ext.XTemplate',
30     alias: 'widget.colorpicker',
31     alternateClassName: 'Ext.ColorPalette',
32     
33     /**
34      * @cfg {String} componentCls
35      * The CSS class to apply to the containing element (defaults to 'x-color-picker')
36      */
37     componentCls : Ext.baseCSSPrefix + 'color-picker',
38     
39     /**
40      * @cfg {String} selectedCls
41      * The CSS class to apply to the selected element
42      */
43     selectedCls: Ext.baseCSSPrefix + 'color-picker-selected',
44     
45     /**
46      * @cfg {String} value
47      * The initial color to highlight (should be a valid 6-digit color hex code without the # symbol).  Note that
48      * the hex codes are case-sensitive.
49      */
50     value : null,
51     
52     /**
53      * @cfg {String} clickEvent
54      * The DOM event that will cause a color to be selected. This can be any valid event name (dblclick, contextmenu).
55      * Defaults to <tt>'click'</tt>.
56      */
57     clickEvent :'click',
58
59     /**
60      * @cfg {Boolean} allowReselect If set to true then reselecting a color that is already selected fires the {@link #select} event
61      */
62     allowReselect : false,
63
64     /**
65      * <p>An array of 6-digit color hex code strings (without the # symbol).  This array can contain any number
66      * of colors, and each hex code should be unique.  The width of the picker is controlled via CSS by adjusting
67      * the width property of the 'x-color-picker' class (or assigning a custom class), so you can balance the number
68      * of colors with the width setting until the box is symmetrical.</p>
69      * <p>You can override individual colors if needed:</p>
70      * <pre><code>
71 var cp = new Ext.picker.Color();
72 cp.colors[0] = 'FF0000';  // change the first box to red
73 </code></pre>
74
75 Or you can provide a custom array of your own for complete control:
76 <pre><code>
77 var cp = new Ext.picker.Color();
78 cp.colors = ['000000', '993300', '333300'];
79 </code></pre>
80      * @type Array
81      */
82     colors : [
83         '000000', '993300', '333300', '003300', '003366', '000080', '333399', '333333',
84         '800000', 'FF6600', '808000', '008000', '008080', '0000FF', '666699', '808080',
85         'FF0000', 'FF9900', '99CC00', '339966', '33CCCC', '3366FF', '800080', '969696',
86         'FF00FF', 'FFCC00', 'FFFF00', '00FF00', '00FFFF', '00CCFF', '993366', 'C0C0C0',
87         'FF99CC', 'FFCC99', 'FFFF99', 'CCFFCC', 'CCFFFF', '99CCFF', 'CC99FF', 'FFFFFF'
88     ],
89
90     /**
91      * @cfg {Function} handler
92      * Optional. A function that will handle the select event of this picker.
93      * The handler is passed the following parameters:<div class="mdetail-params"><ul>
94      * <li><code>picker</code> : ColorPicker<div class="sub-desc">The {@link #picker Ext.picker.Color}.</div></li>
95      * <li><code>color</code> : String<div class="sub-desc">The 6-digit color hex code (without the # symbol).</div></li>
96      * </ul></div>
97      */
98     /**
99      * @cfg {Object} scope
100      * The scope (<tt><b>this</b></tt> reference) in which the <code>{@link #handler}</code>
101      * function will be called.  Defaults to this ColorPicker instance.
102      */
103     
104     colorRe: /(?:^|\s)color-(.{6})(?:\s|$)/,
105     
106     constructor: function() {
107         this.renderTpl = Ext.create('Ext.XTemplate', '<tpl for="colors"><a href="#" class="color-{.}" hidefocus="on"><em><span style="background:#{.}" unselectable="on">&#160;</span></em></a></tpl>');
108         this.callParent(arguments);
109     },
110     
111     // private
112     initComponent : function(){
113         var me = this;
114         
115         this.callParent(arguments);
116         me.addEvents(
117             /**
118              * @event select
119              * Fires when a color is selected
120              * @param {Ext.picker.Color} this
121              * @param {String} color The 6-digit color hex code (without the # symbol)
122              */
123             'select'
124         );
125
126         if (me.handler) {
127             me.on('select', me.handler, me.scope, true);
128         }
129     },
130
131
132     // private
133     onRender : function(container, position){
134         var me = this,
135             clickEvent = me.clickEvent;
136             
137         Ext.apply(me.renderData, {
138             itemCls: me.itemCls,
139             colors: me.colors    
140         });
141         this.callParent(arguments);
142
143         me.mon(me.el, clickEvent, me.handleClick, me, {delegate: 'a'});
144         // always stop following the anchors
145         if(clickEvent != 'click'){
146             me.mon(me.el, 'click', Ext.emptyFn, me, {delegate: 'a', stopEvent: true});
147         }
148     },
149
150     // private
151     afterRender : function(){
152         var me = this,
153             value;
154             
155         this.callParent(arguments);
156         if (me.value) {
157             value = me.value;
158             me.value = null;
159             me.select(value, true);
160         }
161     },
162
163     // private
164     handleClick : function(event, target){
165         var me = this,
166             color;
167             
168         event.stopEvent();
169         if (!me.disabled) {
170             color = target.className.match(me.colorRe)[1];
171             me.select(color.toUpperCase());
172         }
173     },
174
175     /**
176      * Selects the specified color in the picker (fires the {@link #select} event)
177      * @param {String} color A valid 6-digit color hex code (# will be stripped if included)
178      * @param {Boolean} suppressEvent (optional) True to stop the select event from firing. Defaults to <tt>false</tt>.
179      */
180     select : function(color, suppressEvent){
181         
182         var me = this,
183             selectedCls = me.selectedCls,
184             value = me.value,
185             el;
186             
187         color = color.replace('#', '');
188         if (!me.rendered) {
189             me.value = color;
190             return;
191         }
192         
193         
194         if (color != value || me.allowReselect) {
195             el = me.el;
196
197             if (me.value) {
198                 el.down('a.color-' + value).removeCls(selectedCls);
199             }
200             el.down('a.color-' + color).addCls(selectedCls);
201             me.value = color;
202             if (suppressEvent !== true) {
203                 me.fireEvent('select', me, color);
204             }
205         }
206     },
207     
208     /**
209      * Get the currently selected color value.
210      * @return {String} value The selected value. Null if nothing is selected.
211      */
212     getValue: function(){
213         return this.value || null;
214     }
215 });