A Loom Class that handles calculations for UI scaling

UIScaler.ls

/**
 * Made By JOSHUA EVANS
 */
package utils 
{
	import loom2d.display.DisplayObject;
	import loom2d.display.Stage;
	
	/**
	 * This class handles calculations for UI scaling.
	 * 
	 * This class will take decimal values representing a fraction of the total screen height or width and
	 * then return a pixel value calculatee from that fraction. All calulations are rounded down.
	 * 
	 * This class MUST be initiated with the main stage object before it can be used!
	 */
	public class UIScaler 
	{
		/**
		 * The Stage used for scale calculations.
		 */
		private static var _stage:Stage;
		
		/**
		 * Retrieves the stage that was provided to the scaler on initialization.
		 */
		public static function get stage():Stage { return _stage; }
		
		/**
		 * Initializes the UIScaler with the main stage. This function MUST be called before
		 * any calculations can be made.
		 * 
		 * @param	s The stage to initialize the scaler with
		 */
		public static function initialize(s:Stage):void
		{
			_stage = s;
		}
		
		/**
		 * Takes a decimal representing a fraction of the application's stage's native height, and return a pixel value representing that fraction.
		 * 
		 * @param	h A fraction of the stage's height
		 * @return 	  A pixel value
		 */
		public static function calculateHeight(h:Number):Number
		{
			checkForStage();
			
			return Math.floor(_stage.nativeStageHeight * h);
		}
		
		/**
		 * Takes a decimal representing a fraction of the application's stage's native width, and return a pixel value representing that fraction.
		 * 
		 * @param	w A fraction of the stage's height
		 * @return 	  A pixel value
		 */
		public static function calculateWidth(w:Number):Number
		{
			checkForStage();
			
			return Math.floor(_stage.nativeStageWidth * w);
		}
		
		/**
		 * Helper function takes a display object and automatically adjusts its x and y positional values to match fractions provided
		 * 
		 * NaN can be provided for the xPos or yPos if they should remain unchanged
		 * 
		 * @param	displayObject The display object to be placed
		 * @param	xPos		  The desired x position of the object, as a fraction of the total stage width or NaN
		 * @param	yPos		  The desired y position of the object, as a fraction of the total stage height or NaN
		 */
		public static function placeObject(displayObject:DisplayObject, xPos:Number, yPos:Number):void
		{
			checkForStage();
			
			if (!Object.isNaN(xPos)) displayObject.x = calculateWidth(xPos);
			if (!Object.isNaN(yPos)) displayObject.y = calculateHeight(yPos);
		}
		
		/**
		 * Helper function takes a display object and automatically adjusts its width and height values to match fractions provided.
		 * 
		 * Note that within this function, the width scaleX and scaleY properities are actually used to adjust the size of UI elements.
		 * 
		 * NaN can be provided for the width or height if htey should remain unchanged
		 * 
		 * @param	displayObject The display object to be scaled
		 * @param	width		  The desired width of the object, as a fraction of the total stage width or NaN
		 * @param	height		  The desired height of the object, as a fraction of the total stage height or NaN
		 */
		public static function scaleObject(displayObject:DisplayObject, width:Number, height:Number):void
		{
			checkForStage();
			
			// There are two steps to this
			// First, determine the width and height as if we are using the non-native width and height
			// Second, use the width and height ratios to appropriately scale the object
			if (!Object.isNaN(width)) 
			{
				displayObject.width = Math.floor(_stage.stageWidth * width);
				displayObject.scaleX = widthRatio;
			}
			
			if (!Object.isNaN(height))
			{
				displayObject.height = Math.floor(_stage.stageHeight * height);
				displayObject.scaleY = heightRatio;
			}
			
		}
		
		/**
		 * Helper function takes a display object and automatically adjusts its x position, y position, width, and height values to match fractions provided
		 * 
		 * NaN can be provided for any numeric value, and it that value will remain unchainged
		 * 
		 * @param	displayObject The display object to be placed and scaled
		 * @param	xPos		  The desired x position of the object, as a fraction of the total stage width or NaN
		 * @param	yPos		  The desired y position of the object, as a fraction of the total stage height or NaN
		 * @param	width		  The desired width of the object, as a fraction of the total stage width or NaN
		 * @param	height		  The desired height of the object, as a fraction of the total stage height NaN
		 */
		public static function placeAndScaleObject(displayObject:DisplayObject, xPos:Number, yPos:Number, width:Number, height:Number):void
		{
			checkForStage();
			
			placeObject(displayObject, xPos, yPos);
			scaleObject(displayObject, width, height);
		}
		
		/**
		 * Will place a display object beneath another display object with an optional vertical fractional offset. Only the object's Y value
		 * will be altered using this function.
		 * 
		 * WARNING: This function will not work if the height value of the "otherObject" has not been explicitly assigned
		 * 
		 * @param	objectToBePlaced The object that will have its Y value altered
		 * @param	otherObject		 The object that the "objectToBePlaced" will be placed underneath
		 * @param	offset		     OPTIONAL: Additional space that should be between the two objects, as a fraction of the stage's native height
		 */
		public static function placeObjectBeneath(objectToBePlaced:DisplayObject, otherObject:DisplayObject, offset:Number = 0):void
		{
			checkForStage();
			
			objectToBePlaced.y = otherObject.y + getTrueObjectHeight(otherObject) + calculateHeight(offset);
		}
		
		/**
		 * Will place a display object to the right of another display object with an optional horizontal fractional offset. Only the object's X value
		 * will be altered using this function.
		 * 
		 * WARNING: This function will not work if the width value of the "otherObject" has not been explicitly assigned
		 * 
		 * @param	objectToBePlaced The object that will have its X value altered
		 * @param	otherObject		 The object that the "objectToBePlaced" will be placed to the right of
		 * @param	offset		     OPTIONAL: Additional space that should be between the two objects, as a fraction of the stage's native width
		 */
		public static function placeObjectRight(objectToBePlaced:DisplayObject, otherObject:DisplayObject, offset:Number = 0):void
		{
			checkForStage();
			
			objectToBePlaced.x = otherObject.x + getTrueObjectWidth(otherObject) + calculateWidth(offset);
		}
		
		/**
		 * Will get the width of an object, with the scaleX taken into account
		 * 
		 * WARNING: This function will not work if the width value of the display object has not been explicityly assigned
		 * 
		 * @param	displayObject The display object to be measured
		 * @return				  The true width of the display object
		 */
		public static function getTrueObjectWidth(displayObject:DisplayObject):Number
		{
			return displayObject.width * displayObject.scaleX;
		}
		
		/**
		 * Will get the height of an object, with the scaleY taken into account
		 * 
		 * WARNING: This function will not work if the width value of the display object has not been explicityly assigned
		 * 
		 * @param	displayObject The display object to be measured
		 * @return				  The true width of the display object
		 */
		public static function getTrueObjectHeight(displayObject:DisplayObject):Number
		{
			return displayObject.height * displayObject.scaleY;
		}
		
		/**
		 * Takes a number of pixels and returns the fraction of the native stage width that that number of pixels represents
		 * 
		 * @param	pixels The number of pixels to use in calculation
		 * @return		   The fraction of the native stage width the provided pixels represents
		 */
		public static function getWidthFractionFromPixels(pixels:Number):Number
		{
			checkForStage();
			
			return (pixels / _stage.nativeStageWidth);
		}
		
		/**
		 * Takes a number of pixels and returns the fraction of the native stage height that that number of pixels represents
		 * 
		 * @param	pixels The number of pixels to use in calculation
		 * @return		   The fraction of the native stage height the provided pixels represents
		 */
		public static function getHeightFractionFromPixels(pixels:Number):Number
		{
			checkForStage();
			
			return (pixels / _stage.nativeStageHeight);
		}
		
		/**
		 * The native stage width divided by the non-native stage width
		 */
		public static function get widthRatio():Number
		{
			return _stage.nativeStageWidth / _stage.stageWidth;
		}
		
		/**
		 * The ratio of the stage height to the native stage height
		 */
		public static function get heightRatio():Number
		{
			return _stage.nativeStageHeight / _stage.stageHeight;
		}
		
		/**
		 * @private
		 * 
		 * Called at the start of all stage-dependent functions. If the stage has not been instatiated will cause an assert error
		 */
		private static function checkForStage():void
		{
			Debug.assert(_stage != null, "Attempting to call stage-dependent function before instantiating!");
		}
	}
}