noponies

/* AS3
*Copyright 2008 noponies.
*/

package noponies.display {

  import flash.display.Sprite;
  import flash.display.Stage;
  import flash.display.StageAlign;
  import flash.display.StageScaleMode;
  import flash.display.DisplayObject;
  import flash.events.Event;
  /**
  *  The NpFSObjectResize class is a Utility class for resizing a given object to fullscreen dimensions. Note, that the object must be part of the displaylist. The class checks for this and will throw an error if the passed in object
  * is not part of the display list. Using this class you are able to resize an object proportionally to fullscreen dimensions, or you can set it to scale either just its width or height to the corresponding
  *   stage width and height.</p>
  *   <p>You are also able position (align) scaled objects within the stages dimensions, a typical use would be to center a width scaled image within the stages height. This allows you to position
  *  your scaled objects so that they appear to scale from a particular point on the stage. This feature is based off a numerical alignment setting, which represents the percentage of the stage you
  *   would like to position your object on. This approach gives you absolute flexibility for aligning your objects!<p>
  * <p>The class does not enforce smoothing of Bitmap or Video objects. Rather, you should set those object properties on each of your respective objects before
  *   passing them to this class.</p>
  * @langversion ActionScript 3.0
  * @Flash Player 9.0.28.0
  * @author noponies - 2008
  *   @version 1.0
  */

  public class NpFSObjectResize extends Sprite {
    private var resizeTarget:DisplayObject;
    private var stageRef:Stage;
    private var useMinStageSize:Boolean = false;
    private var XminSize:int = 400;
    private var YminSize:int = 400;
    private var stageWidth:int;
    private var stageHeight: int;
    private var resizeMode:String =  "full"
    private var xPos:Number = 0
    private var yPos:Number = 0
    private var img_prop:Number = 0
   
    //--------------------------------------
    // GETTERS/SETTERS
    //--------------------------------------
    /**
    * @langversion ActionScript 3.0
    * @playerversion Flash 9
     *  Get / Set the minStageScaleX, which is an int. Used to control at what X point the scaling of the object should stop and it should be clipped.
     *  @default 400
     *  @return int representing the <code>x</code> value at which point clipping rather than scaling should occur.
     */
    public function get minStageScaleX():int{
      return XminSize
    }
    /**
    * @private
    */
    public function set minStageScaleX(newMinScaleX:int):void{
      XminSize = newMinScaleX
    }
    /**
    * @langversion ActionScript 3.0
    * @playerversion Flash 9
     *  Get / Set the minStageScaleY, which is an int. Used to control at what Y point the scaling of the object should stop and it should be clipped.
     *  @default 400
     *  @return int representing the <code>y</code> value at which point clipping rather than scaling should occur.
     */
    public function get minStageScaleY():int{
      return YminSize;
    }
    /**
    * @private
    */

    public function set minStageScaleY(newMinScaleY:int):void{
      YminSize = newMinScaleY;
    }
   
    /**
     *  Get / Set the position relative to the browsers size <em>(as a percentage of the browsers width)</em> where you would like your object to scale from on the <code>x</code> axis.
     *  This parameter is designed to allow for you to align your objects within the stage.
     *  For instance, a value of <code>0.5</code> will cause your object to be centered on the x axis. A value of <code>0</code> will place your object hard left.
     *  @see #alignY
     *  @see #scaleMode  
     *  @default 0
     *  @return Number
     */
    public function get alignX():Number{
      return xPos;
    }
    /**
    * @private
    */
    public function set alignX(newxPos:Number):void{
      xPos = newxPos
    }
    /**
     *  Get / Set the position relative to the browsers size <em>(as a percentage of the browsers height)</em> where you would like your object to scale from on the <code>y</code> axis.
     *  This parameter is designed to allow for you to align your objects within the stage.
     *  For instance, a value of <code>0.5</code> will cause your object to be centered on the y axis. A value of <code>0</code> will place your object hard top.
     *  @see #alignX   
     *  @see #scaleMode 
     *  @default 0
     *  @return Number
     */
    public function get alignY():Number{
      return yPos;
    }
    /**
    * @private
    */
    public function set alignY(newyPos:Number):void{
      yPos = newyPos
    }
    /**
     *  Get / Set a string representing the scale mode for your target object. Possible values are <code>full</code> which will scale your object to match the screen dimensions, at all screen sizes.
     *  A value of <code>height</code> will scale the object to the stages height, and scale its width by the same scale factor. This can result in your object not always fully filling the browser window. A value of
     * <code>width</code> will scale your object to the stages width, scaling its height by the same scale factor. This can result in your object not always fully filling the browser window.
     *  @see #alignX
     *  @see #alignY      
     *  @return String
     *  @default "full"
     */
    public function get scaleMode():String{
      return resizeMode;
    }
    /**
    * @private
    */
    public function set scaleMode(newScaleMode:String):void{
      validateScaleMode(newScaleMode)
    }
   
    /**
    *   @langversion ActionScript 3.0
    * @playerversion Flash 9
     *  Get / Set whether or not to use clipping of the display object at a certain stage size. This property overrides the minStageScale setters, which have no
     *  effect if  this Boolean is false. Default
     *  @default false
     *  @return Boolean representing whether or not to enable clipping. A value of <code>true</code> enables clipping. A value of <code>false</code> disables clipping.
     */
     public function get useStageScaleMin():Boolean{
      return useMinStageSize
    }

    /**
    * @private
    */
    public function set useStageScaleMin(scaleOrClip:Boolean):void{
      useMinStageSize = scaleOrClip
    }

    //--------------------------------------
    // CONSTRUCTOR
    //--------------------------------------
    /**
     *  The NpFSObjectResize class is a Utility class for resizing a given object to fullscreen dimensions.
     *  <p>Please review classes public methods for adding content to the class!</p>
     *  @see #addResizeTarget()
     *  @example Demo Constructor and setter arguments.
     * <listing version="3.0">
     *  //Instantiate class first
     *  var fs:NpFSObjectResize = new NpFSObjectResize()
     *  fs.addResizeTarget(someDisplayObject)
     *  //Set properties via setters
     *  fs.minStageScaleX = 500
     *  fs.minStageScaleY = 500
     *  fs.useStageScaleMin = true
     * </listing>
     *  @example Demo Constructor setting an object to scale its width, and center it within the stages height
     * <listing version="3.0">
     *  //Instantiate class first
     *  var fs:NpFSObjectResize = new NpFSObjectResize()
     *  fs.addResizeTarget(monkey, 0,.5,"width")
     * </listing>
     */
    public function NpFSObjectResize() {
    }
    //-----------------------------------------------------------------------------
    // PROTECTED INSTANCE METHODS
    //-----------------------------------------------------------------------------
    //internal method
     /**
     *  @langversion ActionScript 3.0
     *  @playerversion  Flash 9
     *  @param String containing the scale mode you are attempting to use.
     *  Validate the passed in scale modes.
     *  <p>Allowable scale modes are <code>"full"</code>, <code>"height"</code>, <code>"width"</code>.
     *  @ throws Error if incorrect scaleMode is passed in.
     *  @return
     *  @private
     */
    protected function validateScaleMode(smode:String):void{
      switch (smode) {
        case "full" :
        this.resizeMode = smode;
        break;
        case  "width" :
        this.resizeMode = smode
        break
        case  "height" :
        this.resizeMode = smode
        break
        default:
        throw new Error("Problem: The scaleMode parameter you have attempted to pass with the value of \""+smode+ "\" does not match the allowed scaleModes, which are: \"full\", \"height\", \"width\"");
      }
    }
    //-----------------------------------------------------------------------------
    // PRIVATE INSTANCE METHODS
    //-----------------------------------------------------------------------------
    private function initResizeTarget():void{
      if (resizeTarget.stage != null) {
        setUpListeners();
      } else {
        resizeTarget.addEventListener(Event.ADDED_TO_STAGE, setUpListeners)
      } 
    }
    //set up listeners and stage props
    private function setUpListeners(event:Event = null):void {
      stageRef = resizeTarget.stage;
      stageRef.scaleMode = StageScaleMode.NO_SCALE;
      stageRef.align = StageAlign.TOP_LEFT;
      stageRef.addEventListener(Event.RESIZE, resizeListener);
      resizeTarget.addEventListener(Event.REMOVED_FROM_STAGE,cleanUpClass);
      resizeObject(resizeTarget);
    } 
    //resize listener
    private function resizeListener(event:Event):void {
      resizeObject(resizeTarget);
    }
    //here we actually resize our object
    //not sure if this is the best peforming approach here. Any opinions are welcome.
    private function resizeObject(targetObject:DisplayObject):void {
      //access stage width here. We want to respond to stage dimension changes immediately
      stageWidth = stageRef.stageWidth;
      stageHeight = stageRef.stageHeight;
     
      if (useMinStageSize) {
        if (stageWidth <= XminSize && stageHeight <= YminSize) {
          return;
        }
      }

      //determine what resize mode we are in, and respond accordingly
      switch (resizeMode) {
      case "height" :
        img_prop = targetObject.width/targetObject.height;
        targetObject.height = stageHeight;
        targetObject.width = stageHeight*img_prop;
        targetObject.x = stageWidth*xPos - targetObject.width*xPos;
        targetObject.y = stageHeight*yPos - targetObject.height*yPos;
        break;
      case "width" :
        img_prop = targetObject.height/targetObject.width;
        targetObject.width = stageWidth;
        targetObject.height = stageWidth*img_prop;
        targetObject.x = stageWidth*xPos - targetObject.width*xPos;
        targetObject.y = stageHeight*yPos - targetObject.height*yPos;
        break;
      default:

      if (stageHeight / stageWidth > targetObject.height / targetObject.width) {
          img_prop = targetObject.width/targetObject.height;
          targetObject.height = stageHeight;
          targetObject.width = stageHeight*img_prop;
        } else {
          img_prop = targetObject.height/targetObject.width;
          targetObject.width = stageWidth;
          targetObject.height = stageWidth*img_prop;
        }
       
        targetObject.x = stageWidth * xPos - targetObject.width * xPos;
        targetObject.y = stageHeight * yPos - targetObject.height * yPos;
      }

    }
   
    //clean up any listeners if the target object is removed from the display list.
    private function cleanUpClass(event:Event = null):void {
      stageRef.removeEventListener(Event.RESIZE, resizeListener);
      resizeTarget.removeEventListener(Event.REMOVED_FROM_STAGE,cleanUpClass);
      resizeTarget = null;
    }
    //-----------------------------------------------------------------------------
    // PUBLIC METHODS
    //-----------------------------------------------------------------------------
    /**
     *  The addResizeTarget function will load in a resize target object. Simply pass in a valid DisplayObject.
     *  <p>You have the option here for specifying how you want to position your clips when they scale. What this means is that you can set a proportionally scaling image
     *  to scale from the bottom Right of the stage, or top left, or bottom left etc.<br>
     *  To achieve this, use the <code>xPos</code> and the <code>yPos</code> parameters in combination.
     *  <em>Each parameter represents a proportion of the stage as a percentage.</em> So, an xPos value of 1 will position your clip hard right.<p>
     *
     *  @param resizeTarget Object which represents the DisplayObject you would like to scale to the full size of your stages dimensions.
     *
     *  @param xPos Number (Default = 0) <strong>Optional param</strong> representing the <code>x</code> position on the stage you would like
     *  your resize object to be placed. This parameter is designed to allow for you to center your objects within the stage.
     *  For instance, a value of <code>0.5</code> will cause your object to be centered on the x axis. A value of <code>0</code> will
     *  place your object hard left.
     *
     *  @param yPos Number (Default = 0) <strong>Optional param</strong> representing the <code>y</code> position on the stage you would like your
     *  resize object to be placed. This parameter is designed to allow for you to center your objects within the stage.
     *  For instance, a value of <code>0.5</code> will cause your object to be centered on the y axis. A value of <code>0</code> will place your
     *  object hard top.
     *
     *  @param resizeMode String (Default = full) <strong>Optional param</strong> representing the scale mode for your target object.
     *  Possible values are <code>full</code> which will scale your object to match the screen dimensions, at all screen sizes.
     *  A value of <code>height</code> will scale the object to the stages height, and scale its width by the same scale factor.
     *  This can result in your object not always fully filling the browser window. A value of
     *  <code>width</code> will scale your object to the stages width, scaling its height by the same scale factor.
     *  This can result in your object not always fully filling the browser window.
     *
     *  @see #minStageScaleX
     *  @see #minStageScaleY
     *  @see #useStageScaleMin
     *  @throws  Will throw an error if unable to add the desired DisplayObject as a resizeTarget of this class.
     *  @return
     * 
     *  @example Demo Flash CS3 Timeline Based Constructor arguments and using public <code>addResizeTarget()</code> method.
     * <listing version="3.0">
     *
     *    import noponies.display.NpFSObjectResize;
     *
     *    //black, green and pink are the instance names of movieClips sitting on the stage!
     *    //this demo will set an object to scale to fit the stages width, and will center it within the stages height
     *   
     *    var resizeTargetObj:NpFSObjectResize = new NpFSObjectResize()
     *    resizeTargetObj.addResizeTarget(black, 0,.5, "width")
     *    stage.addEventListener(MouseEvent.CLICK, handleClick)
     *   
     *    //this function will set an object to scale to fit the stages height, and will center it within the stages width
     *    function handleClick(event:MouseEvent):void{
     *      resizeTargetObj.addResizeTarget(green, .5, 0, "height", )
     *    }
     *
     *    //this function will set an object to scale to fit the stages width & height, and will position the object so that it scales from the bottom right of the stage
     *    function handleClick1(event:MouseEvent):void{
     *      resizeTargetObj.addResizeTarget(pink, 1, 1 )
     *    }
     *
     * </listing>
     */
    public function addResizeTarget(resizeTarget:DisplayObject, xPos:Number = 0, yPos:Number = 0, resizeMode:String = "full"):void {
      if (stageRef == null) {
        this.resizeTarget = resizeTarget;
        this.xPos = xPos
        this.yPos = yPos
        validateScaleMode(resizeMode)
        initResizeTarget();
      } else {
        try {
          //kill any existing targets within this class instance
          removeResizeTarget()
          this.resizeTarget = resizeTarget;
          this.xPos = xPos
          this.yPos = yPos
          validateScaleMode(resizeMode)
          initResizeTarget();
        } catch (error:Error) {
          throw new Error("Problem adding new resize target");
        }
      }
    }
    /**
    *   This public method will remove a resizeTarget from this class. Call this if you would like to disable resizing of a DisplayObject.
    * @example Demo Flash Timeline Based Constructor arguments and using public <code>removeResizeTarget()</code> method.
    * <listing version="3.0">
    * var resizeTargetObj:NpFSObjectResize = new NpFSObjectResize(black)
     *
    * stage.addEventListener(MouseEvent.CLICK, handleClick)
    *
    * function handleClick(event:MouseEvent):void{
    *  resizeTargetObj.removeResizeTarget()
    * }
    * </listing>
    * @return
    */
    public function removeResizeTarget():void {
      if(this.resizeTarget != null){
        stageRef.removeEventListener(Event.RESIZE, resizeListener);
        resizeTarget.removeEventListener(Event.REMOVED_FROM_STAGE,cleanUpClass);
        resizeTarget.removeEventListener(Event.ADDED_TO_STAGE, setUpListeners)
        this.resizeTarget = null
        this.resizeMode = ""
      }
    }
  }
}