Context Navigation

source: Dev/branches/rest-dojo-ui/client/dojox/charting/Theme.js @ 256

Last change on this file since 256 was 256, checked in by hendrikvanantwerpen, 13 years ago
Reworked project structure based on REST interaction and Dojo library. As soon as this is stable, the old jQueryUI branch can be removed (it's kept for reference).
File size: 20.9 KB

Line
1	define(["dojo/_base/lang", "dojo/_base/array","dojo/_base/declare","dojo/_base/Color",
2	"dojox/color/_base", "dojox/color/Palette", "dojox/lang/utils", "dojox/gfx/gradutils"],
3	function(lang, arr, declare, Color, colorX, Palette, dlu, dgg){
4
5	var Theme = declare("dojox.charting.Theme", null, {
6	// summary:
7	// A Theme is a pre-defined object, primarily JSON-based, that makes up the definitions to
8	// style a chart.
9	//
10	// description:
11	// While you can set up style definitions on a chart directly (usually through the various add methods
12	// on a dojox.charting.Chart object), a Theme simplifies this manual setup by allowing you to
13	// pre-define all of the various visual parameters of each element in a chart.
14	//
15	// Most of the properties of a Theme are straight-forward; if something is line-based (such as
16	// an axis or the ticks on an axis), they will be defined using basic stroke parameters. Likewise,
17	// if an element is primarily block-based (such as the background of a chart), it will be primarily
18	// fill-based.
19	//
20	// In addition (for convenience), a Theme definition does not have to contain the entire JSON-based
21	// structure. Each theme is built on top of a default theme (which serves as the basis for the theme
22	// "GreySkies"), and is mixed into the default theme object. This allows you to create a theme based,
23	// say, solely on colors for data series.
24	//
25	// Defining a new theme is relatively easy; see any of the themes in dojox.charting.themes for examples
26	// on how to define your own.
27	//
28	// When you set a theme on a chart, the theme itself is deep-cloned. This means that you cannot alter
29	// the theme itself after setting the theme value on a chart, and expect it to change your chart. If you
30	// are looking to make alterations to a theme for a chart, the suggestion would be to create your own
31	// theme, based on the one you want to use, that makes those alterations before it is applied to a chart.
32	//
33	// Finally, a Theme contains a number of functions to facilitate rendering operations on a chart--the main
34	// helper of which is the ~next~ method, in which a chart asks for the information for the next data series
35	// to be rendered.
36	//
37	// A note on colors:
38	// The Theme constructor was on the use of dojox.color.Palette (in general) for creating a visually distinct
39	// set of colors for usage in a chart. A palette is usually comprised of 5 different color definitions, and
40	// no more. If you have a need to render a chart with more than 5 data elements, you can simply "push"
41	// new color definitions into the theme's .color array. Make sure that you do that with the actual
42	// theme object from a Chart, and not in the theme itself (i.e. either do that before using .setTheme
43	// on a chart).
44	//
45	// example:
46	// The default theme (and structure) looks like so:
47	// \| // all objects are structs used directly in dojox.gfx
48	// \| chart:{
49	// \| stroke: null,
50	// \| fill: "white",
51	// \| pageStyle: null // suggested page style as an object suitable for dojo.style()
52	// \| },
53	// \| plotarea:{
54	// \| stroke: null,
55	// \| fill: "white"
56	// \| },
57	// \| axis:{
58	// \| stroke: { // the axis itself
59	// \| color: "#333",
60	// \| width: 1
61	// \| },
62	// \| tick: { // used as a foundation for all ticks
63	// \| color: "#666",
64	// \| position: "center",
65	// \| font: "normal normal normal 7pt Tahoma", // labels on axis
66	// \| fontColor: "#333" // color of labels
67	// \| },
68	// \| majorTick: { // major ticks on axis, and used for major gridlines
69	// \| width: 1,
70	// \| length: 6
71	// \| },
72	// \| minorTick: { // minor ticks on axis, and used for minor gridlines
73	// \| width: 0.8,
74	// \| length: 3
75	// \| },
76	// \| microTick: { // minor ticks on axis, and used for minor gridlines
77	// \| width: 0.5,
78	// \| length: 1
79	// \| }
80	// \| },
81	// \| series: {
82	// \| stroke: {width: 1.5, color: "#333"}, // line
83	// \| outline: {width: 0.1, color: "#ccc"}, // outline
84	// \| //shadow: {dx: 1, dy: 1, width: 2, color: [0, 0, 0, 0.3]},
85	// \| shadow: null, // no shadow
86	// \| fill: "#ccc", // fill, if appropriate
87	// \| font: "normal normal normal 8pt Tahoma", // if there's a label
88	// \| fontColor: "#000" // color of labels
89	// \| labelWiring: {width: 1, color: "#ccc"}, // connect marker and target data item(slice, column, bar...)
90	// \| },
91	// \| marker: { // any markers on a series
92	// \| symbol: "m-3,3 l3,-6 3,6 z", // symbol
93	// \| stroke: {width: 1.5, color: "#333"}, // stroke
94	// \| outline: {width: 0.1, color: "#ccc"}, // outline
95	// \| shadow: null, // no shadow
96	// \| fill: "#ccc", // fill if needed
97	// \| font: "normal normal normal 8pt Tahoma", // label
98	// \| fontColor: "#000"
99	// \| },
100	// \| indicator: {
101	// \| lineStroke: {width: 1.5, color: "#333"}, // line
102	// \| lineOutline: {width: 0.1, color: "#ccc"}, // line outline
103	// \| lineShadow: null, // no line shadow
104	// \| stroke: {width: 1.5, color: "#333"}, // label background stroke
105	// \| outline: {width: 0.1, color: "#ccc"}, // label background outline
106	// \| shadow: null, // no label background shadow
107	// \| fill: "#ccc", // label background fill
108	// \| radius: 3, // radius of the label background
109	// \| font: "normal normal normal 10pt Tahoma", // label font
110	// \| fontColor: "#000" // label color
111	// \| markerFill: "#ccc", // marker fill
112	// \| markerSymbol: "m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0", // marker symbol
113	// \| markerStroke: {width: 1.5, color: "#333"}, // marker stroke
114	// \| markerOutline: {width: 0.1, color: "#ccc"}, // marker outline
115	// \| markerShadow: null, // no marker shadow
116	// \| }
117	//
118	// example:
119	// Defining a new theme is pretty simple:
120	// \| dojox.charting.themes.Grasslands = new dojox.charting.Theme({
121	// \| colors: [ "#70803a", "#dde574", "#788062", "#b1cc5d", "#eff2c2" ]
122	// \| });
123	// \|
124	// \| myChart.setTheme(dojox.charting.themes.Grasslands);
125
126	shapeSpaces: {shape: 1, shapeX: 1, shapeY: 1},
127
128	constructor: function(kwArgs){
129	// summary:
130	// Initialize a theme using the keyword arguments. Note that the arguments
131	// look like the example (above), and may include a few more parameters.
132	kwArgs = kwArgs \|\| {};
133
134	// populate theme with defaults updating them if needed
135	var def = Theme.defaultTheme;
136	arr.forEach(["chart", "plotarea", "axis", "series", "marker", "indicator"], function(name){
137	this[name] = lang.delegate(def[name], kwArgs[name]);
138	}, this);
139
140	// personalize theme
141	if(kwArgs.seriesThemes && kwArgs.seriesThemes.length){
142	this.colors = null;
143	this.seriesThemes = kwArgs.seriesThemes.slice(0);
144	}else{
145	this.seriesThemes = null;
146	this.colors = (kwArgs.colors \|\| Theme.defaultColors).slice(0);
147	}
148	this.markerThemes = null;
149	if(kwArgs.markerThemes && kwArgs.markerThemes.length){
150	this.markerThemes = kwArgs.markerThemes.slice(0);
151	}
152	this.markers = kwArgs.markers ? lang.clone(kwArgs.markers) : lang.delegate(Theme.defaultMarkers);
153
154	// set flags
155	this.noGradConv = kwArgs.noGradConv;
156	this.noRadialConv = kwArgs.noRadialConv;
157	if(kwArgs.reverseFills){
158	this.reverseFills();
159	}
160
161	// private housekeeping
162	this._current = 0;
163	this._buildMarkerArray();
164	},
165
166	clone: function(){
167	// summary:
168	// Clone the current theme.
169	// returns: dojox.charting.Theme
170	// The cloned theme; any alterations made will not affect the original.
171	var theme = new Theme({
172	// theme components
173	chart: this.chart,
174	plotarea: this.plotarea,
175	axis: this.axis,
176	series: this.series,
177	marker: this.marker,
178	// individual arrays
179	colors: this.colors,
180	markers: this.markers,
181	indicator: this.indicator,
182	seriesThemes: this.seriesThemes,
183	markerThemes: this.markerThemes,
184	// flags
185	noGradConv: this.noGradConv,
186	noRadialConv: this.noRadialConv
187	});
188	// copy custom methods
189	arr.forEach(
190	["clone", "clear", "next", "skip", "addMixin", "post", "getTick"],
191	function(name){
192	if(this.hasOwnProperty(name)){
193	theme[name] = this[name];
194	}
195	},
196	this
197	);
198	return theme; // dojox.charting.Theme
199	},
200
201	clear: function(){
202	// summary:
203	// Clear and reset the internal pointer to start fresh.
204	this._current = 0;
205	},
206
207	next: function(elementType, mixin, doPost){
208	// summary:
209	// Get the next color or series theme.
210	// elementType: String?
211	// An optional element type (for use with series themes)
212	// mixin: Object?
213	// An optional object to mix into the theme.
214	// doPost: Boolean?
215	// A flag to post-process the results.
216	// returns: Object
217	// An object of the structure { series, marker, symbol }
218	var merge = dlu.merge, series, marker;
219	if(this.colors){
220	series = lang.delegate(this.series);
221	marker = lang.delegate(this.marker);
222	var color = new Color(this.colors[this._current % this.colors.length]), old;
223	// modify the stroke
224	if(series.stroke && series.stroke.color){
225	series.stroke = lang.delegate(series.stroke);
226	old = new Color(series.stroke.color);
227	series.stroke.color = new Color(color);
228	series.stroke.color.a = old.a;
229	}else{
230	series.stroke = {color: color};
231	}
232	if(marker.stroke && marker.stroke.color){
233	marker.stroke = lang.delegate(marker.stroke);
234	old = new Color(marker.stroke.color);
235	marker.stroke.color = new Color(color);
236	marker.stroke.color.a = old.a;
237	}else{
238	marker.stroke = {color: color};
239	}
240	// modify the fill
241	if(!series.fill \|\| series.fill.type){
242	series.fill = color;
243	}else{
244	old = new Color(series.fill);
245	series.fill = new Color(color);
246	series.fill.a = old.a;
247	}
248	if(!marker.fill \|\| marker.fill.type){
249	marker.fill = color;
250	}else{
251	old = new Color(marker.fill);
252	marker.fill = new Color(color);
253	marker.fill.a = old.a;
254	}
255	}else{
256	series = this.seriesThemes ?
257	merge(this.series, this.seriesThemes[this._current % this.seriesThemes.length]) :
258	this.series;
259	marker = this.markerThemes ?
260	merge(this.marker, this.markerThemes[this._current % this.markerThemes.length]) :
261	series;
262	}
263
264	var symbol = marker && marker.symbol \|\| this._markers[this._current % this._markers.length];
265
266	var theme = {series: series, marker: marker, symbol: symbol};
267
268	// advance the counter
269	++this._current;
270
271	if(mixin){
272	theme = this.addMixin(theme, elementType, mixin);
273	}
274	if(doPost){
275	theme = this.post(theme, elementType);
276	}
277
278	return theme; // Object
279	},
280
281	skip: function(){
282	// summary:
283	// Skip the next internal color.
284	++this._current;
285	},
286
287	addMixin: function(theme, elementType, mixin, doPost){
288	// summary:
289	// Add a mixin object to the passed theme and process.
290	// theme: dojox.charting.Theme
291	// The theme to mixin to.
292	// elementType: String
293	// The type of element in question. Can be "line", "bar" or "circle"
294	// mixin: Object\|Array
295	// The object or objects to mix into the theme.
296	// doPost: Boolean
297	// If true, run the new theme through the post-processor.
298	// returns: dojox.charting.Theme
299	// The new theme.
300	if(lang.isArray(mixin)){
301	arr.forEach(mixin, function(m){
302	theme = this.addMixin(theme, elementType, m);
303	}, this);
304	}else{
305	var t = {};
306	if("color" in mixin){
307	if(elementType == "line" \|\| elementType == "area"){
308	lang.setObject("series.stroke.color", mixin.color, t);
309	lang.setObject("marker.stroke.color", mixin.color, t);
310	}else{
311	lang.setObject("series.fill", mixin.color, t);
312	}
313	}
314	arr.forEach(["stroke", "outline", "shadow", "fill", "font", "fontColor", "labelWiring"], function(name){
315	var markerName = "marker" + name.charAt(0).toUpperCase() + name.substr(1),
316	b = markerName in mixin;
317	if(name in mixin){
318	lang.setObject("series." + name, mixin[name], t);
319	if(!b){
320	lang.setObject("marker." + name, mixin[name], t);
321	}
322	}
323	if(b){
324	lang.setObject("marker." + name, mixin[markerName], t);
325	}
326	});
327	if("marker" in mixin){
328	t.symbol = mixin.marker;
329	}
330	theme = dlu.merge(theme, t);
331	}
332	if(doPost){
333	theme = this.post(theme, elementType);
334	}
335	return theme; // dojox.charting.Theme
336	},
337
338	post: function(theme, elementType){
339	// summary:
340	// Process any post-shape fills.
341	// theme: dojox.charting.Theme
342	// The theme to post process with.
343	// elementType: String
344	// The type of element being filled. Can be "bar" or "circle".
345	// returns: dojox.charting.Theme
346	// The post-processed theme.
347	var fill = theme.series.fill, t;
348	if(!this.noGradConv && this.shapeSpaces[fill.space] && fill.type == "linear"){
349	if(elementType == "bar"){
350	// transpose start and end points
351	t = {
352	x1: fill.y1,
353	y1: fill.x1,
354	x2: fill.y2,
355	y2: fill.x2
356	};
357	}else if(!this.noRadialConv && fill.space == "shape" && (elementType == "slice" \|\| elementType == "circle")){
358	// switch to radial
359	t = {
360	type: "radial",
361	cx: 0,
362	cy: 0,
363	r: 100
364	};
365	}
366	if(t){
367	return dlu.merge(theme, {series: {fill: t}});
368	}
369	}
370	return theme; // dojox.charting.Theme
371	},
372
373	getTick: function(name, mixin){
374	// summary:
375	// Calculates and merges tick parameters.
376	// name: String
377	// Tick name, can be "major", "minor", or "micro".
378	// mixin: Object?
379	// Optional object to mix in to the tick.
380	var tick = this.axis.tick, tickName = name + "Tick",
381	merge = dlu.merge;
382	if(tick){
383	if(this.axis[tickName]){
384	tick = merge(tick, this.axis[tickName]);
385	}
386	}else{
387	tick = this.axis[tickName];
388	}
389	if(mixin){
390	if(tick){
391	if(mixin[tickName]){
392	tick = merge(tick, mixin[tickName]);
393	}
394	}else{
395	tick = mixin[tickName];
396	}
397	}
398	return tick; // Object
399	},
400
401	inspectObjects: function(f){
402	arr.forEach(["chart", "plotarea", "axis", "series", "marker", "indicator"], function(name){
403	f(this[name]);
404	}, this);
405	if(this.seriesThemes){
406	arr.forEach(this.seriesThemes, f);
407	}
408	if(this.markerThemes){
409	arr.forEach(this.markerThemes, f);
410	}
411	},
412
413	reverseFills: function(){
414	this.inspectObjects(function(o){
415	if(o && o.fill){
416	o.fill = dgg.reverse(o.fill);
417	}
418	});
419	},
420
421	addMarker:function(/String/ name, /String/ segment){
422	// summary:
423	// Add a custom marker to this theme.
424	// example:
425	// \| myTheme.addMarker("Ellipse", foo);
426	this.markers[name] = segment;
427	this._buildMarkerArray();
428	},
429
430	setMarkers:function(/Object/ obj){
431	// summary:
432	// Set all the markers of this theme at once. obj should be a
433	// dictionary of keys and path segments.
434	//
435	// example:
436	// \| myTheme.setMarkers({ "CIRCLE": foo });
437	this.markers = obj;
438	this._buildMarkerArray();
439	},
440
441	_buildMarkerArray: function(){
442	this._markers = [];
443	for(var p in this.markers){
444	this._markers.push(this.markers[p]);
445	}
446	}
447	});
448
449	/*=====
450	dojox.charting.Theme.__DefineColorArgs = function(num, colors, hue, saturation, low, high, base, generator){
451	// summary:
452	// The arguments object that can be passed to define colors for a theme.
453	// num: Number?
454	// The number of colors to generate. Defaults to 5.
455	// colors: String[]\|dojo.Color[]?
456	// A pre-defined set of colors; this is passed through to the Theme directly.
457	// hue: Number?
458	// A hue to base the generated colors from (a number from 0 - 359).
459	// saturation: Number?
460	// If a hue is passed, this is used for the saturation value (0 - 100).
461	// low: Number?
462	// An optional value to determine the lowest value used to generate a color (HSV model)
463	// high: Number?
464	// An optional value to determine the highest value used to generate a color (HSV model)
465	// base: String\|dojo.Color?
466	// A base color to use if we are defining colors using dojox.color.Palette
467	// generator: String?
468	// The generator function name from dojox.color.Palette.
469	this.num = num;
470	this.colors = colors;
471	this.hue = hue;
472	this.saturation = saturation;
473	this.low = low;
474	this.high = high;
475	this.base = base;
476	this.generator = generator;
477	}
478	=====*/
479	lang.mixin(Theme, {
480	defaultMarkers: {
481	CIRCLE: "m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0",
482	SQUARE: "m-3,-3 l0,6 6,0 0,-6 z",
483	DIAMOND: "m0,-3 l3,3 -3,3 -3,-3 z",
484	CROSS: "m0,-3 l0,6 m-3,-3 l6,0",
485	X: "m-3,-3 l6,6 m0,-6 l-6,6",
486	TRIANGLE: "m-3,3 l3,-6 3,6 z",
487	TRIANGLE_INVERTED: "m-3,-3 l3,6 3,-6 z"
488	},
489
490	defaultColors:[
491	// gray skies
492	"#54544c", "#858e94", "#6e767a", "#948585", "#474747"
493	],
494
495	defaultTheme: {
496	// all objects are structs used directly in dojox.gfx
497	chart:{
498	stroke: null,
499	fill: "white",
500	pageStyle: null,
501	titleGap: 20,
502	titlePos: "top",
503	titleFont: "normal normal bold 14pt Tahoma", // labels on axis
504	titleFontColor: "#333"
505	},
506	plotarea:{
507	stroke: null,
508	fill: "white"
509	},
510	// TODO: label rotation on axis
511	axis:{
512	stroke: { // the axis itself
513	color: "#333",
514	width: 1
515	},
516	tick: { // used as a foundation for all ticks
517	color: "#666",
518	position: "center",
519	font: "normal normal normal 7pt Tahoma", // labels on axis
520	fontColor: "#333", // color of labels
521	titleGap: 15,
522	titleFont: "normal normal normal 11pt Tahoma", // labels on axis
523	titleFontColor: "#333", // color of labels
524	titleOrientation: "axis" // "axis": facing the axis, "away": facing away
525	},
526	majorTick: { // major ticks on axis, and used for major gridlines
527	width: 1,
528	length: 6
529	},
530	minorTick: { // minor ticks on axis, and used for minor gridlines
531	width: 0.8,
532	length: 3
533	},
534	microTick: { // minor ticks on axis, and used for minor gridlines
535	width: 0.5,
536	length: 1
537	}
538	},
539	series: {
540	// used as a "main" theme for series, sThemes augment it
541	stroke: {width: 1.5, color: "#333"}, // line
542	outline: {width: 0.1, color: "#ccc"}, // outline
543	//shadow: {dx: 1, dy: 1, width: 2, color: [0, 0, 0, 0.3]},
544	shadow: null, // no shadow
545	fill: "#ccc", // fill, if appropriate
546	font: "normal normal normal 8pt Tahoma", // if there's a label
547	fontColor: "#000", // color of labels
548	labelWiring: {width: 1, color: "#ccc"} // connect marker and target data item(slice, column, bar...)
549	},
550	marker: { // any markers on a series
551	stroke: {width: 1.5, color: "#333"}, // stroke
552	outline: {width: 0.1, color: "#ccc"}, // outline
553	//shadow: {dx: 1, dy: 1, width: 2, color: [0, 0, 0, 0.3]},
554	shadow: null, // no shadow
555	fill: "#ccc", // fill if needed
556	font: "normal normal normal 8pt Tahoma", // label
557	fontColor: "#000"
558	},
559	indicator: {
560	lineStroke: {width: 1.5, color: "#333"},
561	lineOutline: {width: 0.1, color: "#ccc"},
562	lineShadow: null,
563	stroke: {width: 1.5, color: "#333"},
564	outline: {width: 0.1, color: "#ccc"},
565	shadow: null,
566	fill : "#ccc",
567	radius: 3,
568	font: "normal normal normal 10pt Tahoma",
569	fontColor: "#000",
570	markerFill: "#ccc",
571	markerSymbol: "m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0",
572	markerStroke: {width: 1.5, color: "#333"},
573	markerOutline: {width: 0.1, color: "#ccc"},
574	markerShadow: null
575	}
576	},
577
578	defineColors: function(kwArgs){
579	// summary:
580	// Generate a set of colors for the theme based on keyword
581	// arguments.
582	// kwArgs: dojox.charting.Theme.__DefineColorArgs
583	// The arguments object used to define colors.
584	// returns: dojo.Color[]
585	// An array of colors for use in a theme.
586	//
587	// example:
588	// \| var colors = dojox.charting.Theme.defineColors({
589	// \| base: "#369",
590	// \| generator: "compound"
591	// \| });
592	//
593	// example:
594	// \| var colors = dojox.charting.Theme.defineColors({
595	// \| hue: 60,
596	// \| saturation: 90,
597	// \| low: 30,
598	// \| high: 80
599	// \| });
600	kwArgs = kwArgs \|\| {};
601	var l, c = [], n = kwArgs.num \|\| 5; // the number of colors to generate
602	if(kwArgs.colors){
603	// we have an array of colors predefined, so fix for the number of series.
604	l = kwArgs.colors.length;
605	for(var i = 0; i < n; i++){
606	c.push(kwArgs.colors[i % l]);
607	}
608	return c; // dojo.Color[]
609	}
610	if(kwArgs.hue){
611	// single hue, generate a set based on brightness
612	var s = kwArgs.saturation \|\| 100, // saturation
613	st = kwArgs.low \|\| 30,
614	end = kwArgs.high \|\| 90;
615	// we'd like it to be a little on the darker side.
616	l = (end + st) / 2;
617	// alternately, use "shades"
618	return colorX.Palette.generate(
619	colorX.fromHsv(kwArgs.hue, s, l), "monochromatic"
620	).colors;
621	}
622	if(kwArgs.generator){
623	// pass a base color and the name of a generator
624	return colorX.Palette.generate(kwArgs.base, kwArgs.generator).colors;
625	}
626	return c; // dojo.Color[]
627	},
628
629	generateGradient: function(fillPattern, colorFrom, colorTo){
630	var fill = lang.delegate(fillPattern);
631	fill.colors = [
632	{offset: 0, color: colorFrom},
633	{offset: 1, color: colorTo}
634	];
635	return fill;
636	},
637
638	generateHslColor: function(color, luminance){
639	color = new Color(color);
640	var hsl = color.toHsl(),
641	result = colorX.fromHsl(hsl.h, hsl.s, luminance);
642	result.a = color.a; // add missing opacity
643	return result;
644	},
645
646	generateHslGradient: function(color, fillPattern, lumFrom, lumTo){
647	color = new Color(color);
648	var hsl = color.toHsl(),
649	colorFrom = colorX.fromHsl(hsl.h, hsl.s, lumFrom),
650	colorTo = colorX.fromHsl(hsl.h, hsl.s, lumTo);
651	colorFrom.a = colorTo.a = color.a; // add missing opacity
652	return Theme.generateGradient(fillPattern, colorFrom, colorTo); // Object
653	}
654	});
655
656	return Theme;
657	});

Note: See TracBrowser for help on using the repository browser.

Download in other formats: