/src/name/carter/mark/flex/util/icon/IconUtils.as

  1package name.carter.mark.flex.util.icon
  2{
  3	import flash.display.DisplayObjectContainer;
  4	
  5	import mx.core.IDataRenderer;
  6	
  7	/**
  8	 * Provides functionality to display icons loaded at runtime in components designed to display
  9	 * embedded (compile-time) icons.
 10	 * 
 11	 */
 12	public class IconUtils
 13	{		
 14		public static function getIconClass(ancestorComponent:DisplayObjectContainer, iconPath:String, iconWidth:int = -1, iconHeight:int = -1, defaultIconClass:Class = null):Class {
 15			if (ancestorComponent == null) {
 16				// this can often happen while components are being initialised
 17				return null;
 18			}
 19			if (iconPath == null) {
 20				throw new Error("Passed a null iconPath");
 21			}
 22			var iconDescriptor:IconDescriptor = new IconDescriptor(iconPath, iconWidth, iconHeight, defaultIconClass); 
 23			var iconDescriptorFunction:Function = function(parent:DisplayObjectContainer):IconDescriptor {
 24				return iconDescriptor;
 25			};
 26			IconClass.registerIconDescriptorFunction(ancestorComponent, iconDescriptorFunction);
 27			return IconClass;
 28		}
 29
 30		public static function getIconClassUsingEmbeddedClass(ancestorComponent:DisplayObjectContainer, embeddedIconClass:Class, iconWidth:int = -1, iconHeight:int = -1):Class {
 31			if (ancestorComponent == null) {
 32				// this can often happen while components are being initialised
 33				return null;
 34			}
 35			if (embeddedIconClass == null) {
 36				throw new Error("Passed a null embeddedIconClass");
 37			}
 38			var iconDescriptor:IconDescriptor = new IconDescriptor(null, iconWidth, iconHeight, embeddedIconClass); 
 39			var iconDescriptorFunction:Function = function(parent:DisplayObjectContainer):IconDescriptor {
 40				return iconDescriptor;
 41			};
 42			IconClass.registerIconDescriptorFunction(ancestorComponent, iconDescriptorFunction);
 43			return IconClass;
 44		}
 45
 46		public static function getIconFunctionForDataRenderer(ancestorComponent:DisplayObjectContainer, iconPathFunction:Function, iconWidth:int = -1, iconHeight:int = -1, defaultIconClass:Class = null):Function {
 47			if (ancestorComponent == null) {
 48				// this can often happen while components are being initialised
 49				return null;
 50			}
 51			if (iconPathFunction == null) {
 52				throw new Error("Passed a null iconPathFunction");
 53			}
 54			var iconDescriptorFunction:Function = function(parent:DisplayObjectContainer):IconDescriptor {
 55				if (!(parent is IDataRenderer)) {
 56					return null;
 57				}
 58				var dr:IDataRenderer = parent as IDataRenderer;
 59				var iconPath:String = iconPathFunction(dr.data);
 60				var result:IconDescriptor;
 61				if (iconPath == null) {
 62					result = null;
 63				}
 64				else {
 65					result = new IconDescriptor(iconPath, iconWidth, iconHeight, defaultIconClass);
 66				}
 67				return result;
 68			};
 69			IconClass.registerIconDescriptorFunction(ancestorComponent, iconDescriptorFunction);
 70			return function(item:Object):Class {
 71				return IconClass;
 72			};
 73		}
 74		
 75		public static function getIconFunctionForDataRendererUsingSimpleIconFunction(ancestorComponent:DisplayObjectContainer, iconFunction:Function, iconWidth:int = -1, iconHeight:int = -1):Function {
 76			if (ancestorComponent == null) {
 77				// this can often happen while components are being initialised
 78				return null;
 79			}
 80			if (iconFunction == null) {
 81				throw new Error("Passed a null iconPathFunction");
 82			}
 83			var iconDescriptorFunction:Function = function(parent:DisplayObjectContainer):IconDescriptor {
 84				if (!(parent is IDataRenderer)) {
 85					return null;
 86				}
 87				var dr:IDataRenderer = parent as IDataRenderer;
 88				var embeddedIconClass:Class = iconFunction(dr.data);
 89				var result:IconDescriptor;
 90				if (embeddedIconClass == null) {
 91					result = null;
 92				}
 93				else {
 94					result = new IconDescriptor(null, iconWidth, iconHeight, embeddedIconClass);
 95				}
 96				return result;
 97			};
 98			IconClass.registerIconDescriptorFunction(ancestorComponent, iconDescriptorFunction);
 99			return function(item:Object):Class {
100				return IconClass;
101			};
102		}
103		
104		/**
105		 * Preload the icon so it is more readily displayable.
106		 * 
107		 * Both specified functions take a single String parameter - which is the icon path.
108		 * 
109		 * Note - one of the specified functions may be called (in the same thread) before this function returns
110		 * 
111		 * @param iconPath The URL for the icon
112		 * @param successFunction The function to be called when the icon is successfully loaded. If it is already loaded, then it is called immediately (before this function returns). 
113		 * @param failureFunction The function to be called when the icon has failed to load. If it is already loaded, then it is called immediately (before this function returns) 
114		 */
115		public static function preloadIcon(iconPath:String, successFunction:Function = null, failureFunction:Function = null):void {
116			var iconSource:IconSource = IconSource.getInstance(iconPath);
117			if (successFunction != null || failureFunction != null) {
118				iconSource.callRelevantFunctionOnCompletion(successFunction, failureFunction);
119			}
120		}
121		
122		/**
123		 * Specify the embedded icon to override runtime icon loading for this iconPath
124		 * 
125		 * Note - an attempt will still be made to load so that we can accurately report the availability of the icon.
126		 *        This is useful for icon paths used in TextArea html. 
127		 */		
128		public static function overrideIcon(iconPath:String, embeddedIconClass:Class):void {
129			var iconSource:IconSource = IconSource.getInstance(iconPath);
130			if (embeddedIconClass != null) {
131				iconSource.embeddedIcon = new embeddedIconClass();
132			}
133		}
134		
135		public static function isKnownToBeUnavailable(iconPath:String):Boolean {
136			return IconSource.getInstance(iconPath).unavailable;
137		}
138
139		private static function isKnownToBeAvailable(iconPath:String):Boolean {
140			return IconSource.getInstance(iconPath).available;
141		}
142
143		/**
144		 * Returns the corresponding html <img/> element.
145		 * 
146		 * If the specified iconPath is known to be available then its path is used.
147		 * Otherwise, if the defaultIconPath is known to be available, then its path is used
148		 * Otherwise, null is returned.
149		 */
150		public static function createImgElement(iconPath:String, iconWidth:int = -1, iconHeight:int = -1, defaultIconPath:String = null):XML {
151			if (!isKnownToBeAvailable(iconPath)) {
152				if (defaultIconPath == null || !isKnownToBeAvailable(defaultIconPath)) {
153					// couldnt even load the default - probably security problems
154					// so don't show icon at all
155					return null;
156				}
157				else {
158					iconPath = defaultIconPath;
159				}
160			}
161			var result:XML = <img src={iconPath}/>;
162			if (iconWidth >= 0) {
163				result.@width = iconWidth;
164			}
165			if (iconHeight >= 0) {
166				result.@height = iconHeight;
167			}
168			return result;
169		}
170	}
171}