AS2: AxisScroller v2.0

October 31, 2007 in AS2, My Classes | Show Some Love |

View Example
View Documentation
Download Class & Example Files

This is the latest update to the AxisScroller. This update adds a new optionalParameter, continuousScroll, which allows you to scroll (if the arrows are active) continuously by just pressing down one of the arrows. There is also a new method, reset(), that resets the scroller and content movie clips to its original positions. Lastly, some of the code was condensed to promote reuse. If you're using the AxisScroller, definitely upgrade to this version. The syntax for usage was all kept in tact so you should have no problems just replacing this in a project (nothing should be broken because of it).

PLAIN TEXT
Actionscript:
  1. import mx.utils.Delegate;
  2. import mx.transitions.easing.*;
  3. import mx.transitions.Tween;
  4.  
  5. /**
  6. * Creates a scroller that allows for scrolling in the x or y axis, using the mouse wheel/arrow keys, different easing functions and types, and some other miscellaneous cool things.
  7. *
  8. * @usage
  9. * <code>
  10. * <pre>
  11. import com.reintroducing.ui.AxisScroller;
  13. stop();
  15. var optionalObj:Object = new Object(
  16. {
  17.     scrollType: "easing",
  18.     isTrackClickable: true,
  19.     useArrows: true,
  20.     upArrow: content_mc.up_btn,
  21.     downArrow: content_mc.down_btn,
  22.     continuousScroll: true,
  23.     easeFunc: Regular.easeOut,
  24.     duration: .25,
  25.     arrowMove: 50,
  26.     scaleScroller: true,
  27.     autoHideControls: true
  28. });
  30. var scroller:AxisScroller = new AxisScroller(content_mc, content_mc.scroller_mc, content_mc.movie_mc, content_mc.track_mc, content_mc.mask_mc, "y", optionalObj);
  31. * </pre>
  32. * </code>
  33. *
  34. * @author Matt Przybylski [http://www.reintroducing.com]
  35. * @version 2.0
  36. */
  37.  
  38. class com.reintroducing.ui.AxisScroller
  39. {
  40. //- PRIVATE VARIABLES -------------------------------------------------------------------------------------
  41.    
  42.     private var _changeProp:String;
  43.     private var _mouseAxis:String;
  44.     private var _changeScale:String;
  45.     private var _nextPosition:Number;
  46.     private var _arrowMove:Number;
  47.     private var _scaleScroller:Boolean;
  48.     private var _autoHideControls:Boolean;
  49.     private var _mouseIsPressedDown:Boolean;
  50.     private var _trackOffset:Number;
  51.     private var _trackStart:Number;
  52.     private var _trackEnd:Number;
  53.     private var _tween:Tween;
  54.     private var _arrow1Tween:Tween;
  55.     private var _arrow2Tween:Tween;
  56.     private var _scrollerTween:Tween;
  57.     private var _trackTween:Tween;
  58.     private var _easeFunc:Function;
  59.     private var _duration:Number;
  60.     private var _holder:MovieClip;
  61.     private var _scroller:MovieClip;
  62.     private var _toBeScrolled:MovieClip;
  63.     private var _track:MovieClip;
  64.     private var _mask:MovieClip;
  65.     private var _axis:String;
  66.     private var _scrollType:String;
  67.     private var _isTrackClickable:Boolean;
  68.     private var _arrows:Boolean;
  69.     private var _upArrow:MovieClip;
  70.     private var _downArrow:MovieClip;
  71.     private var _continuousScroll:Boolean;
  72.     private var _arrowTimer:Number;
  73.     private var _arrowPressed:String;
  74.    
  75. //- PUBLIC VARIABLES --------------------------------------------------------------------------------------
  76.    
  77.     public static var DEFAULT_NAME:String = "com.reintroducing.ui.AxisScroller";
  78.  
  79. //- CONSTRUCTOR -------------------------------------------------------------------------------------------
  80.    
  81.     /**
  82.      * Creates a new instance of the AxisScroller class.
  83.      *
  84.      * <p>
  85.      * The $optionalParams parameter takes in a couple of values.
  86.      * <ul>
  87.      * <li>scrollType: A string representing the scroll type, "instant" or "easing" (default: "easing")</li>
  88.      * <li>isTrackClickable: A boolean value that makes the track clickable so that you can scroll directly to a certain spot (default: true)</li>
  89.      * <li>useArrows: A boolean value that allows the use of arrow buttons (default: false)</li>
  90.      * <li>upArrow: If useArrows, a movie clip that represents the up arrow button (default: null)</li>
  91.      * <li>downArrow: If useArrows, a movie clip that represents the down arrow button (default: null)</li>
  92.      * <li>continuousScroll: If useArrows, a boolean that specifies if when pressing the arrows the scrolling should happen continuously or not (default: false)</li>
  93.      * <li>easeFunc: A function representing the ease type you'd like to use, as per the Tween class easing functions (default: Regular.easeOut)</li>
  94.      * <li>duration: An integer (in seconds) representing the time that the scrollable content will take to move when easing is used (default: .25)</li>
  95.      * <li>arrowMove: An integer (in pixels) that the scrollable content will move onMouseWheel/Key/Arrow movement (default: 100)</li>
  96.      * <li>autoHideControls: A boolean value that hides the scroller/track/arrows (if applicable) if the scroll content is too small to scroll (default: false)</li>
  97.      * <li>scaleScroller *: A boolean value that allows automatic scaling of the scroll bar (default: false)</li>
  98.      * </ul>
  99.      * * If you use the scaleScroller optional parameter, please make the size of the scroll bar the same size as the track and this will take care of
  100.      * scaling it automatically for you.  If you AREN'T using this parameter, please size your scroll bar accordingly manually.
  101.      * </p>
  102.      *
  103.      * @usage <pre><code>var scroller:AxisScroller = new AxisScroller($holder, $scroller, $toBeScrolled, $track, $mask, $axis, $optionalParams);</code></pre>
  104.      *
  105.      * @param $holder The movie clip (or timeline) that holds all of the other clips corresponding to the scroller
  106.      * @param $scroller The movie clip to be used as the scroller
  107.      * @param $toBeScrolled The movie clip where the scrollable content resides
  108.      * @param $track The movie clip that is used as the track (measures extremes)
  109.      * @param $mask The movie clip that is used as the mask for the scrollable content area
  110.      * @param $axis A string value of either "x" or "y" that determines what axis the content is scrolled along
  111.      * @param $optionalParams Optional parameters to further control the scroller
  112.      */
  113.    
  114.     public function AxisScroller($holder:MovieClip, $scroller:MovieClip, $toBeScrolled:MovieClip, $track:MovieClip, $mask:MovieClip, $axis:String, $optionalParams:Object)
  115.     {
  116.         this._holder                = $holder;
  117.         this._scroller      = $scroller;
  118.         this._toBeScrolled     = $toBeScrolled;
  119.         this._track                     = $track;
  120.         this._mask       = $mask;
  121.         this._axis       = "_" + $axis;
  122.        
  123.         this._scrollType             = ($optionalParams.scrollType == undefined) ? "easing" : $optionalParams.scrollType;
  124.         this._isTrackClickable    = ($optionalParams.isTrackClickable == undefined) ? true : $optionalParams.isTrackClickable;
  125.         this._arrows                = ($optionalParams.useArrows == undefined) ? false : $optionalParams.useArrows;
  126.         this._upArrow           = ($optionalParams.upArrow == undefined) ? null : $optionalParams.upArrow;
  127.         this._downArrow                 = ($optionalParams.downArrow == undefined) ? null : $optionalParams.downArrow;
  128.         this._continuousScroll      = ($optionalParams.continuousScroll == undefined) ? false : $optionalParams.continuousScroll;
  129.         this._easeFunc      = ($optionalParams.easeFunc == undefined) ? Regular.easeOut : $optionalParams.easeFunc;
  130.         this._duration      = ($optionalParams.duration == undefined) ? .25 : $optionalParams.duration;
  131.         this._arrowMove                 = ($optionalParams.arrowMove == undefined) ? 100 : $optionalParams.arrowMove;
  132.         this._autoHideControls      = ($optionalParams.autoHideControls == undefined) ? false : $optionalParams.autoHideControls;
  133.         this._scaleScroller    = ($optionalParams.scaleScroller == undefined) ? false : $optionalParams.scaleScroller;
  134.        
  135.         this.manageAxis(this._axis);
  136.         this.init();
  137.     }
  138.    
  139. //- PRIVATE METHODS ---------------------------------------------------------------------------------------
  140.    
  141.     // initiates listeners and other events
  142.     private function init():Void
  143.     {
  144.         Mouse.addListener(this);
  145.         Key.addListener(this);
  146.        
  147.         this._holder.onEnterFrame       = Delegate.create(this, manageScrolling);
  148.        
  149.         this.activateButtonEvents();
  150.     }
  151.    
  152.     // re-activates the button events
  153.     private function activateButtonEvents():Void
  154.     {
  155.         this._scroller.onPress     = Delegate.create(this, manageMouseDown);
  156.        
  157.         this._scroller.onRelease = this._scroller.onReleaseOutside = Delegate.create(this, manageMouseUp);
  158.         this._scroller.useHandCursor = true;
  159.        
  160.         if (this._isTrackClickable)
  161.         {
  162.             this._track.onRelease       = Delegate.create(this, manageTrack);
  163.             this._track.useHandCursor      = true;
  164.         }
  165.        
  166.         if (this._arrows)
  167.         {
  168.             this._upArrow.onPress        = Delegate.create(this, manageUpArrow);
  169.             this._upArrow.onRelease         = Delegate.create(this, resetArrowTimer);
  170.            
  171.             this._downArrow.onPress         = Delegate.create(this, manageDownArrow);
  172.             this._downArrow.onRelease     = Delegate.create(this, resetArrowTimer);
  173.            
  174.             this._downArrow.useHandCursor = this._upArrow.useHandCursor = true;
  175.         }
  176.     }
  177.    
  178.     // destroys the events on the buttons
  179.     private function killButtonEvents():Void
  180.     {
  181.         this._scroller.onPress = this._scroller.onRelease = this._scroller.onReleaseOutside = null;
  182.         this._scroller.useHandCursor = false;
  183.        
  184.         if (this._isTrackClickable)
  185.         {
  186.             this._track.onRelease = null;
  187.             this._track.useHandCursor = false;
  188.         }
  189.        
  190.         if (this._arrows)
  191.         {
  192.             this._upArrow.onPress = this._downArrow.onPress = null;
  193.             this._upArrow.onRelease = this._downArrow.onRelease = null;
  194.             this._upArrow.useHandCursor = this._downArrow.useHandCursor = false;
  195.         }
  196.     }
  197.    
  198.     // sets the axis at which the scroller will function against
  199.     private function manageAxis($axis:String):Void
  200.     {
  201.         if ($axis == "_x")
  202.         {
  203.             this._changeProp          = "_width";
  204.             this._mouseAxis             = "_xmouse";
  205.             this._changeScale         = "_xscale";
  206.         }
  207.         else if ($axis == "_y")
  208.         {
  209.             this._changeProp          = "_height";
  210.             this._mouseAxis             = "_ymouse";
  211.             this._changeScale         = "_yscale";
  212.         }
  213.        
  214.         this._trackOffset         = - (this._scroller[this._changeProp] / 2);
  215.     }
  216.    
  217.     // calculates values and responds to changes by the scroller
  218.     private function manageScrolling():Void
  219.     {
  220.         var trackSize:Number          = this._track[this._changeProp];
  221.         var trackStart:Number       = this._track[this._axis];
  222.         var trackEnd:Number             = this._track[this._axis] + trackSize - (this._scroller[this._changeProp]);
  223.         var trackRange:Number       = trackEnd - trackStart;
  224.         var maskSize:Number             = this._mask[this._changeProp];
  225.         var movieSize:Number          = this._toBeScrolled[this._changeProp];
  226.         var minPosition:Number    = this._mask[this._axis] + 2;
  227.         var maxPosition:Number    = minPosition + movieSize - maskSize + 4;
  228.         var onePercentChange:Number     = (maxPosition - minPosition) / 100;
  229.         var percent:Number     = Math.round(((this._scroller[this._axis] - trackStart) / trackRange) * 100);
  230.         var targetPosition:Number     = Math.round(minPosition - (onePercentChange * percent));
  231.        
  232.         this._trackStart             = trackStart;
  233.         this._trackEnd      = trackEnd;
  234.        
  235.         if (this._scrollType == "instant")
  236.         {
  237.             this._toBeScrolled[this._axis] = targetPosition;
  238.         }
  239.         else if (this._scrollType == "easing")
  240.         {
  241.             this._toBeScrolled[this._axis] += Math.round((targetPosition - this._toBeScrolled[this._axis]) / 5);
  242.         }
  243.  
  244.         if (movieSize <maskSize)
  245.         {
  246.             onePercentChange = 0;
  247.         }
  248.        
  249.         if (this._mouseIsPressedDown)
  250.         {
  251.             this._scroller[this._axis] = Math.round(this._holder[this._mouseAxis] - (this._scroller[this._changeProp] / 2));
  252.         }
  253.        
  254.         if (this._scroller[this._axis] <trackStart)
  255.         {
  256.             this._scroller[this._axis] = Math.round(trackStart);
  257.         }
  258.         else if (this._scroller[this._axis]> trackEnd)
  259.         {
  260.             this._scroller[this._axis] = Math.round(trackEnd);
  261.         }
  262.        
  263.         if (this._scaleScroller) this.manageScrollScaling(movieSize, maskSize);
  264.        
  265.         this.manageControls(this._autoHideControls, movieSize, maskSize);
  266.     }
  267.    
  268.     // regulates mouse pressed down
  269.     private function manageMouseDown():Void
  270.     {
  271.         this._mouseIsPressedDown = true;
  272.     }
  273.    
  274.     // regulates mouse released
  275.     private function manageMouseUp():Void
  276.     {
  277.         this._mouseIsPressedDown = false;
  278.     }
  279.    
  280.     // moves the scroller up when the up arrow is clicked
  281.     private function moveUp():Void
  282.     {
  283.         if (this._scrollType == "instant")
  284.         {
  285.             this._nextPosition = Math.round(this._scroller[this._axis] - this._arrowMove);
  286.            
  287.             if (this._nextPosition <this._trackStart)
  288.             {
  289.                 this._scroller[this._axis] = this._trackStart;
  290.             }
  291.             else
  292.             {
  293.                 this._scroller[this._axis] = this._nextPosition;
  294.             }
  295.         }
  296.         else if (this._scrollType == "easing")
  297.         {
  298.             this._nextPosition = Math.round(this._scroller[this._axis] - this._arrowMove);
  299.            
  300.             if (this._nextPosition <this._trackStart)
  301.             {
  302.                 this._tween = new Tween(this._scroller, this._axis, this._easeFunc, this._scroller[this._axis], this._trackStart, this._duration, true);
  303.             }
  304.             else
  305.             {
  306.                 this._tween = new Tween(this._scroller, this._axis, this._easeFunc, this._scroller[this._axis], this._nextPosition, this._duration, true);
  307.             }
  308.         }
  309.     }
  310.    
  311.     // moves the scroller down when the down arrow is clicked
  312.     private function moveDown():Void
  313.     {
  314.         if (this._scrollType == "instant")
  315.         {
  316.             this._nextPosition = Math.round(this._scroller[this._axis] + this._arrowMove);
  317.            
  318.             if (this._nextPosition> this._trackEnd)
  319.             {
  320.                 this._scroller[this._axis] = this._trackEnd;
  321.             }
  322.             else
  323.             {
  324.                 this._scroller[this._axis] = this._nextPosition;
  325.             }
  326.         }
  327.         else if (this._scrollType == "easing")
  328.         {
  329.             this._nextPosition = Math.round(this._scroller[this._axis] + this._arrowMove);
  330.            
  331.             if (this._nextPosition> this._trackEnd)
  332.             {
  333.                 this._tween = new Tween(this._scroller, this._axis, this._easeFunc, this._scroller[this._axis], this._trackEnd, this._duration, true);
  334.             }
  335.             else
  336.             {
  337.                 this._tween = new Tween(this._scroller, this._axis, this._easeFunc, this._scroller[this._axis], this._nextPosition, this._duration, true);
  338.             }
  339.         }
  340.     }
  341.    
  342.     // regulates the movement of the up arrow, if applicable
  343.     private function manageUpArrow():Void
  344.     {
  345.         if (this._continuousScroll)
  346.         {
  347.             this._arrowPressed = "up";
  348.             this._arrowTimer = setInterval(this, "manage