Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / Color2.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-draw.Color'>/**
2 </span> * @class Ext.draw.Color
3  * @extends Object
4  *
5  * Represents an RGB color and provides helper functions get
6  * color components in HSL color space.
7  */
8 Ext.define('Ext.draw.Color', {
9
10     /* Begin Definitions */
11
12     /* End Definitions */
13
14     colorToHexRe: /(.*?)rgb\((\d+),\s*(\d+),\s*(\d+)\)/,
15     rgbRe: /\s*rgb\s*\(\s*([0-9]+)\s*,\s*([0-9]+)\s*,\s*([0-9]+)\s*\)\s*/,
16     hexRe: /\s*#([0-9a-fA-F][0-9a-fA-F]?)([0-9a-fA-F][0-9a-fA-F]?)([0-9a-fA-F][0-9a-fA-F]?)\s*/,
17
18 <span id='Ext-draw.Color-cfg-lightnessFactor'>    /**
19 </span>     * @cfg {Number} lightnessFactor
20      *
21      * The default factor to compute the lighter or darker color. Defaults to 0.2.
22      */
23     lightnessFactor: 0.2,
24
25 <span id='Ext-draw.Color-method-constructor'>    /**
26 </span>     * @constructor
27      * @param {Number} red Red component (0..255)
28      * @param {Number} green Green component (0..255)
29      * @param {Number} blue Blue component (0..255)
30      */
31     constructor : function(red, green, blue) {
32         var me = this,
33             clamp = Ext.Number.constrain;
34         me.r = clamp(red, 0, 255);
35         me.g = clamp(green, 0, 255);
36         me.b = clamp(blue, 0, 255);
37     },
38
39 <span id='Ext-draw.Color-method-getRed'>    /**
40 </span>     * Get the red component of the color, in the range 0..255.
41      * @return {Number}
42      */
43     getRed: function() {
44         return this.r;
45     },
46
47 <span id='Ext-draw.Color-method-getGreen'>    /**
48 </span>     * Get the green component of the color, in the range 0..255.
49      * @return {Number}
50      */
51     getGreen: function() {
52         return this.g;
53     },
54
55 <span id='Ext-draw.Color-method-getBlue'>    /**
56 </span>     * Get the blue component of the color, in the range 0..255.
57      * @return {Number}
58      */
59     getBlue: function() {
60         return this.b;
61     },
62
63 <span id='Ext-draw.Color-method-getRGB'>    /**
64 </span>     * Get the RGB values.
65      * @return {Array}
66      */
67     getRGB: function() {
68         var me = this;
69         return [me.r, me.g, me.b];
70     },
71
72 <span id='Ext-draw.Color-method-getHSL'>    /**
73 </span>     * Get the equivalent HSL components of the color.
74      * @return {Array}
75      */
76     getHSL: function() {
77         var me = this,
78             r = me.r / 255,
79             g = me.g / 255,
80             b = me.b / 255,
81             max = Math.max(r, g, b),
82             min = Math.min(r, g, b),
83             delta = max - min,
84             h,
85             s = 0,
86             l = 0.5 * (max + min);
87
88         // min==max means achromatic (hue is undefined)
89         if (min != max) {
90             s = (l &lt; 0.5) ? delta / (max + min) : delta / (2 - max - min);
91             if (r == max) {
92                 h = 60 * (g - b) / delta;
93             } else if (g == max) {
94                 h = 120 + 60 * (b - r) / delta;
95             } else {
96                 h = 240 + 60 * (r - g) / delta;
97             }
98             if (h &lt; 0) {
99                 h += 360;
100             }
101             if (h &gt;= 360) {
102                 h -= 360;
103             }
104         }
105         return [h, s, l];
106     },
107
108 <span id='Ext-draw.Color-method-getLighter'>    /**
109 </span>     * Return a new color that is lighter than this color.
110      * @param {Number} factor Lighter factor (0..1), default to 0.2
111      * @return Ext.draw.Color
112      */
113     getLighter: function(factor) {
114         var hsl = this.getHSL();
115         factor = factor || this.lightnessFactor;
116         hsl[2] = Ext.Number.constrain(hsl[2] + factor, 0, 1);
117         return this.fromHSL(hsl[0], hsl[1], hsl[2]);
118     },
119
120 <span id='Ext-draw.Color-method-getDarker'>    /**
121 </span>     * Return a new color that is darker than this color.
122      * @param {Number} factor Darker factor (0..1), default to 0.2
123      * @return Ext.draw.Color
124      */
125     getDarker: function(factor) {
126         factor = factor || this.lightnessFactor;
127         return this.getLighter(-factor);
128     },
129
130 <span id='Ext-draw.Color-method-toString'>    /**
131 </span>     * Return the color in the hex format, i.e. '#rrggbb'.
132      * @return {String}
133      */
134     toString: function() {
135         var me = this,
136             round = Math.round,
137             r = round(me.r).toString(16),
138             g = round(me.g).toString(16),
139             b = round(me.b).toString(16);
140         r = (r.length == 1) ? '0' + r : r;
141         g = (g.length == 1) ? '0' + g : g;
142         b = (b.length == 1) ? '0' + b : b;
143         return ['#', r, g, b].join('');
144     },
145
146 <span id='Ext-draw.Color-method-toHex'>    /**
147 </span>     * Convert a color to hexadecimal format.
148      *
149      * @param {String|Array} color The color value (i.e 'rgb(255, 255, 255)', 'color: #ffffff').
150      * Can also be an Array, in this case the function handles the first member.
151      * @returns {String} The color in hexadecimal format.
152      */
153     toHex: function(color) {
154         if (Ext.isArray(color)) {
155             color = color[0];
156         }
157         if (!Ext.isString(color)) {
158             return '';
159         }
160         if (color.substr(0, 1) === '#') {
161             return color;
162         }
163         var digits = this.colorToHexRe.exec(color);
164
165         if (Ext.isArray(digits)) {
166             var red = parseInt(digits[2], 10),
167                 green = parseInt(digits[3], 10),
168                 blue = parseInt(digits[4], 10),
169                 rgb = blue | (green &lt;&lt; 8) | (red &lt;&lt; 16);
170             return digits[1] + '#' + (&quot;000000&quot; + rgb.toString(16)).slice(-6);
171         }
172         else {
173             return '';
174         }
175     },
176
177 <span id='Ext-draw.Color-method-fromString'>    /**
178 </span>     * Parse the string and create a new color.
179      *
180      * Supported formats: '#rrggbb', '#rgb', and 'rgb(r,g,b)'.
181      *
182      * If the string is not recognized, an undefined will be returned instead.
183      *
184      * @param {String} str Color in string.
185      * @returns Ext.draw.Color
186      */
187     fromString: function(str) {
188         var values, r, g, b,
189             parse = parseInt;
190
191         if ((str.length == 4 || str.length == 7) &amp;&amp; str.substr(0, 1) === '#') {
192             values = str.match(this.hexRe);
193             if (values) {
194                 r = parse(values[1], 16) &gt;&gt; 0;
195                 g = parse(values[2], 16) &gt;&gt; 0;
196                 b = parse(values[3], 16) &gt;&gt; 0;
197                 if (str.length == 4) {
198                     r += (r * 16);
199                     g += (g * 16);
200                     b += (b * 16);
201                 }
202             }
203         }
204         else {
205             values = str.match(this.rgbRe);
206             if (values) {
207                 r = values[1];
208                 g = values[2];
209                 b = values[3];
210             }
211         }
212
213         return (typeof r == 'undefined') ? undefined : Ext.create('Ext.draw.Color', r, g, b);
214     },
215
216 <span id='Ext-draw.Color-method-getGrayscale'>    /**
217 </span>     * Returns the gray value (0 to 255) of the color.
218      *
219      * The gray value is calculated using the formula r*0.3 + g*0.59 + b*0.11.
220      *
221      * @returns {Number}
222      */
223     getGrayscale: function() {
224         // http://en.wikipedia.org/wiki/Grayscale#Converting_color_to_grayscale
225         return this.r * 0.3 + this.g * 0.59 + this.b * 0.11;
226     },
227
228 <span id='Ext-draw.Color-method-fromHSL'>    /**
229 </span>     * Create a new color based on the specified HSL values.
230      *
231      * @param {Number} h Hue component (0..359)
232      * @param {Number} s Saturation component (0..1)
233      * @param {Number} l Lightness component (0..1)
234      * @returns Ext.draw.Color
235      */
236     fromHSL: function(h, s, l) {
237         var C, X, m, i, rgb = [],
238             abs = Math.abs,
239             floor = Math.floor;
240
241         if (s == 0 || h == null) {
242             // achromatic
243             rgb = [l, l, l];
244         }
245         else {
246             // http://en.wikipedia.org/wiki/HSL_and_HSV#From_HSL
247             // C is the chroma
248             // X is the second largest component
249             // m is the lightness adjustment
250             h /= 60;
251             C = s * (1 - abs(2 * l - 1));
252             X = C * (1 - abs(h - 2 * floor(h / 2) - 1));
253             m = l - C / 2;
254             switch (floor(h)) {
255                 case 0:
256                     rgb = [C, X, 0];
257                     break;
258                 case 1:
259                     rgb = [X, C, 0];
260                     break;
261                 case 2:
262                     rgb = [0, C, X];
263                     break;
264                 case 3:
265                     rgb = [0, X, C];
266                     break;
267                 case 4:
268                     rgb = [X, 0, C];
269                     break;
270                 case 5:
271                     rgb = [C, 0, X];
272                     break;
273             }
274             rgb = [rgb[0] + m, rgb[1] + m, rgb[2] + m];
275         }
276         return Ext.create('Ext.draw.Color', rgb[0] * 255, rgb[1] * 255, rgb[2] * 255);
277     }
278 }, function() {
279     var prototype = this.prototype;
280
281     //These functions are both static and instance. TODO: find a more elegant way of copying them
282     this.addStatics({
283         fromHSL: function() {
284             return prototype.fromHSL.apply(prototype, arguments);
285         },
286         fromString: function() {
287             return prototype.fromString.apply(prototype, arguments);
288         },
289         toHex: function() {
290             return prototype.toHex.apply(prototype, arguments);
291         }
292     });
293 });
294 </pre></pre></body></html>