ScrollBar

Kind of class:	class
Inherits from:	EventMovieClip < MovieClip
Author:	Martijn de Visser
Classpath:	org.asapframework.ui.scrollbar.ScrollBar
File last modified:	Sunday, 08 October 2006, 10:08:09

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// Adobe classes
//import flash.geom.*;
// Still support Flash 7:
import org.asapframework.util.types.*;

// framework classses
import org.asapframework.ui.buttons.*;
import org.asapframework.ui.scrollbar.*;


/**
ScrollBar class to create scrollbars with. Assumes the presence of 4 other clips:
<ul>
    <li>'scroller_mc'     DragButton, scrollable handle</li>
    <li>'scrollerBg_mc' MovieClip, background of scrollbar</li>
    <li>'arrowUp_mc'    RepeaterButton, scroll up arrow</li>
    <li>'arrowDown_mc'    RepeaterButton, scroll down arrow</li>
</ul>
@author Martijn de Visser
@todo Support for orientation so horizontal scrollbars are possible as well.
*/

class org.asapframework.ui.scrollbar.ScrollBar extends org.asapframework.ui.EventMovieClip {

    private var mEnabled:Boolean;
    private var mScroller:DragButton;
    private var mScrollerBg:MovieClip;
    private var mArrowUp:RepeaterButton;
    private var mArrowDown:RepeaterButton;
    private var mScrollTarget:IScrollable;

    private var mSnap:Number;
    private var mScrollerHeight:Number;
    private var mOldScrollerHeight:Number;
    private var mVisibleHeight:Number;
    private var mOldVisibleHeight:Number;
    private var mTotalHeight:Number;
    private var mOldTotalHeight:Number;
    
    private static var DEFAULT_MIN_HEIGHT:Number = 10;
    private static var mMinHeight:Number = DEFAULT_MIN_HEIGHT;

    public function ScrollBar () {

        super();
    }

    public function onLoad () : Void {

        // get references
        mScroller = DragButton(mMc.scroller_mc);
        mScrollerBg = MovieClip(mMc.scrollerBg_mc);
        mArrowUp = RepeaterButton(mMc.arrowUp_mc);
        mArrowDown = RepeaterButton(mMc.arrowDown_mc);

        // set default values
        setHeight(mMc._height);

        // set listeners
        mArrowUp.addEventListener(EventButtonEvent.ON_RELEASE, this);
        mArrowDown.addEventListener(EventButtonEvent.ON_RELEASE, this);
        mScroller.addEventListener(DragButtonEvent.ON_MOVE, this);
        mScroller.sendMoveEvent = true;
    }

    /**
    Updates the scroller.
    */
    public function update () : Void {

        // store previous values
        mOldTotalHeight = mTotalHeight;

        // get latest target sizes
        mVisibleHeight = mScrollTarget.getVisibleHeight();
        mTotalHeight = mScrollTarget.getTotalHeight();

        // has the scroller height been changed?
        // if so, we need a new lay-out
        if (mScrollerHeight != mOldScrollerHeight) {

            if (mScrollerHeight == undefined) { 
                mScrollerHeight = mMc._height;
            }
            mArrowDown._y = Math.floor(mScrollerHeight - mArrowDown._height);
            mScrollerBg._y = Math.floor(mArrowUp._height);
            mScrollerBg._height = Math.floor(mScrollerHeight - (mArrowUp._height + mArrowDown._height));
            mOldScrollerHeight = mScrollerHeight;
        }

        // has the target height been changed?
        // if so, we need to adjust the size of the scroller
        if ((mVisibleHeight != mOldVisibleHeight) || (mOldTotalHeight != mTotalHeight)) {

            // is all content already visible? then hide scroller
            if (mTotalHeight <= mVisibleHeight) {

                mScroller._visible = false;
                mArrowUp.enabled = false;
                mArrowDown.enabled = false;

            } else {

                var scrollerLength:Number = Math.floor((mVisibleHeight / mTotalHeight) * mScrollerBg._height);
                
                mScroller._height = (scrollerLength < mMinHeight) ? mMinHeight : scrollerLength;
                var bounds:Rectangle = new Rectangle(
                    mScrollerBg._x,
                    mScrollerBg._y,
                    0,
                    mScrollerBg._height - mScroller._height);
                mScroller.setBounds(bounds);
                
                mScroller._y = bounds.top;
                
                mOldVisibleHeight = mVisibleHeight;

                mScroller._visible = true;
                mArrowUp.enabled = true;
                mArrowDown.enabled = true;
            }
        }
    }
    
    /**
    Programmatically scrolls the scrollbar.
    @sends ScrollEvent#ON_SCROLL_CONTENT
    */
    public function scroll ( inDirection:Number ) : Void {        

        // calculate if new position is within bounds
        
        var newContentPos:Number = mScrollTarget.getScrollPosition() - mScrollTarget.getStepSize() * inDirection;
                
        var curScroll:Number = newContentPos / (mVisibleHeight - mTotalHeight);
        // calculate new position of content clip
        var maxScroll:Number = mVisibleHeight - mTotalHeight;

        var newPos:Number = Math.round(curScroll * maxScroll);
        if (newPos < maxScroll) {
            newPos = maxScroll;
        }
        if (newPos > 0) {
            newPos = 0;
        }
        mScrollTarget.scrollTo(newPos);
        alignScroller();
        
        dispatchEvent( new ScrollEvent(ScrollEvent.ON_SCROLL_CONTENT, this, inDirection));
    }

    /**
    Aligns the scroller to the position of the content
    */
    public function alignScroller () : Void {
        // calculate new position of scroller clip
        var maxScroll:Number = mScrollerBg._height - mScroller._height;
        var curScroll:Number = mScrollTarget.getScrollPosition() / (mVisibleHeight - mTotalHeight);
        var newPos:Number = -Math.round(curScroll * maxScroll);
        mScroller._y = mScrollerBg._y - newPos;
    }

    /**
    The target clip to scroll. This target should implement the IScrollable interface. The target will automatically be added to the listener queue and receive the 'onScroll' event.
    @param inScrollTarget
    */
    public function setTarget ( inScrollTarget:IScrollable ) : Void {

        // remove current listener if present
        if (mScrollTarget != undefined) {
            removeEventListener(ScrollEvent.ON_SCROLL_CONTENT, mScrollTarget);
        }

        // set new target
        mScrollTarget = inScrollTarget;
        mOldVisibleHeight = mVisibleHeight;

        // set new listener
        addEventListener(ScrollEvent.ON_SCROLL_CONTENT, mScrollTarget);

        // update scrollbar
        update();
    }
    
    /**
    @deprecated: Use {@link #setTarget}.
    */
    public function set target ( inScrollTarget:IScrollable ) : Void {
        setTarget(inScrollTarget);
    }
    
    /**
    The total height of the scrollbar in pixels.
    */
    public function setHeight ( inHeight:Number ) : Void {
        mOldScrollerHeight = mScrollerHeight;
        mScrollerHeight = inHeight;
        update();
    }

    /**
    @deprecated: Use {@link #setHeight}.
    */
    public function set height ( inHeight:Number ) : Void {
        setHeight(inHeight);
    }

    /**
    The number of pixels to snap to.
    */
    public function set snapping ( inValue:Number ) {

        mSnap = inValue;
    }

    /**
    The enabled state of ScrollBar.
    */
    public function get enabled () : Boolean {

        return mEnabled;
    }
    public function set enabled ( inValue:Boolean ) {

        mEnabled = inValue;
        mScroller.enabled = inValue;
        mArrowUp.enabled = inValue;
        mArrowDown.enabled = inValue;
    }
    
    // EVENTS
    
    /**
    Triggered by scroller.
    */
    public function onDragMove ( e:DragButtonEvent ) : Void {

        alignContent();
    }

    /**
    Triggered by arrows.
    */
    public function onEventButtonRelease ( e:EventButtonEvent ) : Void {

        var dir:Number = (e.buttonName == "arrowDown_mc")? 1 : -1;
        scroll(dir);
    }
    
    // PRIVATE METHODS
    
    /**
    Aligns the content to the position of the scroller.
    */
    private function alignContent () : Void {

        // calculate new position of content clip
        var maxScroll:Number = mVisibleHeight - mTotalHeight;
        var curScroll:Number = mScroller.distance.y / (mScrollerBg._height - mScroller._height);
        var newPos:Number = Math.round(curScroll * maxScroll);

        if (newPos < maxScroll) { newPos = maxScroll; };
        if (newPos > 0) {
            newPos = 0;
        }

        // do we need to snap?
        if (mSnap != undefined) {
            // yes, scroll modulo snapfactor
            mScrollTarget.scrollTo(-((newPos - (newPos % mSnap)) / mSnap));
        } else {
            // no, just scroll...
            mScrollTarget.scrollTo(newPos);
        }
    }
    
    /**
    Is this method used?
    */
    private function getPos ( inDirection:Number ) : Number {
        
        var dir:Number = (inDirection == undefined)? 1 : inDirection;
        var maxScroll:Number = -(mVisibleHeight - mTotalHeight);
        var newPos:Number;

        // update position of scrolltarget and scroller
        if (mSnap != undefined) {

            // yes, scroll times snapfactor
            newPos = -(dir * mSnap);

        } else {

            // no, just scroll...
            newPos = -newPos;
        }

        if (newPos < maxScroll) {
            newPos = maxScroll;
        }
        if (newPos > 0)  {
            newPos = 0;
        }
        
        return newPos;
    }
}

ScrollBar class to create scrollbars with. Assumes the presence of 4 other clips:

'scroller_mc' DragButton, scrollable handle
'scrollerBg_mc' MovieClip, background of scrollbar
'arrowUp_mc' RepeaterButton, scroll up arrow
'arrowDown_mc' RepeaterButton, scroll down arrow

To do:

Support for orientation so horizontal scrollbars are possible as well.

Events broadcasted to listeners:

ScrollEvent with type: ON_SCROLL_CONTENT
- (null)

Summary

Constructor

ScrollBar

Class properties

DEFAULT_MIN_HEIGHT : Number
mMinHeight : Number

Instance properties

mEnabled : Boolean
mScroller : DragButton
mScrollerBg : MovieClip
mArrowUp : RepeaterButton
mArrowDown : RepeaterButton
mScrollTarget : IScrollable
mSnap : Number
mScrollerHeight : Number
mOldScrollerHeight : Number
mVisibleHeight : Number
mOldVisibleHeight : Number
mTotalHeight : Number
mOldTotalHeight : Number
target (inScrollTarget:IScrollable
height (inHeight:Number) : Number
snapping (inValue:Number)
- The number of pixels to snap to.
enabled : Boolean
- The enabled state of ScrollBar.

Instance properties inherited from EventMovieClip

addEventListener dispatchEvent mMc removeEventListener

Instance methods

update : Void
- Updates the scroller.
scroll (inDirection:Number) : Void
- Programmatically scrolls the scrollbar.
alignScroller : Void
- Aligns the scroller to the position of the content
setTarget (inScrollTarget:IScrollable) : Void
- The target clip to scroll.
setHeight (inHeight:Number) : Void
- The total height of the scrollbar in pixels.
alignContent : Void
- Aligns the content to the position of the scroller.
getPos (inDirection:Number) : Number
- Is this method used?

Event handlers

onLoad : Void
onDragMove (e:DragButtonEvent) : Void
- Triggered by scroller.
onEventButtonRelease (e:EventButtonEvent) : Void
- Triggered by arrows.

Constructor

ScrollBar

function ScrollBar (

)

Class properties

DEFAULT_MIN_HEIGHT

static private DEFAULT_MIN_HEIGHT:Number = 10

(read)

mMinHeight

static private mMinHeight:Number = DEFAULT_MIN_HEIGHT

(read)

Instance properties

enabled

enabled:Boolean

(read,write)

The enabled state of ScrollBar.

height

height:Number

(write)

Deprecated Use setHeight.

mArrowDown

private mArrowDown:RepeaterButton

(read)

mArrowUp

private mArrowUp:RepeaterButton

(read)

mEnabled

private mEnabled:Boolean

(read)

mOldScrollerHeight

private mOldScrollerHeight:Number

(read)

mOldTotalHeight

private mOldTotalHeight:Number

(read)

mOldVisibleHeight

private mOldVisibleHeight:Number

(read)

mScroller

private mScroller:DragButton

(read)

mScrollerBg

private mScrollerBg:MovieClip

(read)

mScrollerHeight

private mScrollerHeight:Number

(read)

mScrollTarget

private mScrollTarget:IScrollable

(read)

mSnap

private mSnap:Number

(read)

mTotalHeight

private mTotalHeight:Number

(read)

mVisibleHeight

private mVisibleHeight:Number

(read)

snapping

snapping

(write)

The number of pixels to snap to.

target

target:IScrollable

(write)

Deprecated Use setTarget.

Instance methods

alignContent

private function alignContent (

) : Void

Aligns the content to the position of the scroller.

alignScroller

function alignScroller (

) : Void

Aligns the scroller to the position of the content

getPos

private function getPos (

inDirection:Number) : Number

Is this method used?

scroll

function scroll (

inDirection:Number) : Void

Programmatically scrolls the scrollbar.

Events broadcasted to listeners:

ScrollEvent with type: ON_SCROLL_CONTENT
- (null)

setHeight

function setHeight (

inHeight:Number) : Void

The total height of the scrollbar in pixels.

setTarget

function setTarget (

inScrollTarget:IScrollable) : Void

The target clip to scroll. This target should implement the IScrollable interface. The target will automatically be added to the listener queue and receive the 'onScroll' event.

Parameters:

inScrollTarget:

update

function update (

) : Void

Updates the scroller.

Event handlers

onDragMove

function onDragMove (

e:DragButtonEvent) : Void

Triggered by scroller.

onEventButtonRelease

function onEventButtonRelease (

e:EventButtonEvent) : Void

Triggered by arrows.

onLoad

function onLoad (

) : Void