Adobe Open Source
   Home     Projects     Source     Documentation     Forums    About
Welcome Guest | Sign In
 

Gumbo FxScroller - Functional and Design Specification


Summary and Background


The skinnable FxScroller component displays a pair of scrollbars and a viewport. A viewport is a UIComponent that implements IViewport, like Group or TextView.

The scrollbars control the viewport's vertical and horizontalScrollPosition and they reflect the viewport's actual size and content size. Scrollbars are displayed according to the Scroller's vertical and horizontalScrollPolicy. By default the policy is "auto", which means that scrollbars are displayed when the viewport's content size is larger than its actual size.

This feature adds classes mx.components.FxScroller and mx.skins.FxScrollerSkin, and the FxScrollBar viewport property.

Detailed Description


In Halo, scrollbar support was intrinsic to all container classes. The 14 properties devoted to scrolling, along with the related internal state and logic, added significantly to the size and complexity of Halo containers. Most of the containers in typical applications don't require scrollbars, so the burden was largely unnecessary. For Gumbo we've factored the support for displaying a viewport and scrollbars into a separate skinnable component called FxScroller. FxScroller's skin provides scrollbars and manages layout according to the vertical,horizontalScrollPolicy Scroller properties. These properties have the same meaning as in Halo (and see the API Description section below).

The connections between the FxScroller's viewport and its scrollbars are created by setting the scrollbar's viewport property. The FxVScrollBar and FxHScrollBar classes bind to the viewport's scroll position and actual and content sizes. They also use the viewport's vertical,horizotnalScrollPositionDelta methods to compute the offsets for page and step scrolling.

API Description


Class mx.components.FxScroller


The FxScroller component displays a single scrollable component, called a viewport, and a horizontal and vertical scrollbars. The viewport must implement the IViewport interface. The scrollbars control the viewport's horizontalScrollPosition and verticalScrollPosition properties. Scrollbars make it possible to view the area defined by the viewport's contentWidth and contentHeight properties.

The scrollbars are displayed according to the vertical and horizontal scrollbar policy, which can be auto, on, or off. The auto policy means that the scrollbar will be visible and included in the layout when the viewport's content is larger than the viewport itself.

public class FxScroller extends FxComponent implements IFocusManagerComponent
{
    [SkinPart] public var horizontalScrollBar:FxHScrollBar;
    [SkinPart] public var verticalScrollBar:FxVScrollBar;
    
    [Bindable]
    /**
     *  The viewport component to be scrolled.
     * 
     *  The viewport is added to the FXScroller component's skin 
     *  which lays out both the viewport and scrollbars.
     * xs
     *  When the viewport property is set, the viewport's clipContent property is 
     *  set to true to enable scrolling.
     * 
     *  Scroller does not support rotating the viewport directly.  The viewport's
     *  contents can be transformed arbitrarily but the viewport itself can not.
     */
    public function get viewport():IViewport
    public function set viewport(value:IViewport):void

    [Bindable]
    [Inspectable(enumeration="off,on,auto", defaultValue="auto")]
    /**
     *  Indicates under what conditions the vertical scrollbar is displayed.
     * 
     *  ScrollPolicy.ON ("on") - the scrollbar is always displayed.
     * 
     *  ScrollPolicy.OFF ("off") - the scrollbar is never displayed.
     *  The viewport can still be scrolled programmatically, by setting its
     *  verticalScrollPosition property.
     * 
     *  ScrollPolicy.AUTO ("auto") - the scrollbar is displayed when 
     *  the viewport's contentHeight is larger than its height.
     * 
     *  The scroll policy affects the measured size of the FxScroller component.
     * 
     *  @default ScrollPolicy.AUTO
     */ 
    public function get verticalScrollPolicy():String
    public function set verticalScrollPolicy(value:String):void
    
    [Bindable]
    [Inspectable(enumeration="off,on,auto", defaultValue="auto")]
    /**
     *  Indicates under what conditions the horizontal scrollbar is displayed.
     * 
     *  ScrollPolicy.ON ("on") - the scrollbar is always displayed.
     *  
     *  ScrollPolicy.OFF ("off") - the scrollbar is never displayed.
     *  The viewport can still be scrolled programmatically, by setting its
     *  horizontalScrollPosition property.
     *  
     *  ScrollPolicy.AUTO ("auto") - the scrollbar is displayed when 
     *  the viewport's contentWidth is larger than its width.
     * 
     *  The scroll policy affects the measured size of the FxScroller component.
     * 
     *  @default ScrollPolicy.AUTO
     */ 
    public function get horizontalScrollPolicy():String
    public function set horizontalScrollPolicy(value:String):void
}

mx.components.FxScrollBar viewport Property


One property and five methods were added to the FxScrollBar to support linking a scrollbar and a viewport. Most of the linking "work" is done by the vertical and horizontal FxScrollBar subclasses FxVScrollBar and FxHScrollBar.

    /**
     *  The viewport controlled by this scrollbar.  If a viewport is
     *  specified, then changes to its actual size, content size, and
     *  scroll position, cause the corresponding ScrollBar methods to
     *  run:
     * 
     *  - viewportResizeHandler()
     *  - contentWidthChangeHandler()
     *  - contentHeightChangeHandler()
     *  - viewportVerticalScrollPositionChangeHandler()
     *  - viewportHorizontalScrollPositionChangeHandler()
     * 
     *  The FxVScrollBar and FxHScrollBar classes override these methods to 
     *  keep their pageSize, maximum, and value properties in sync with the
     *  viewport.   Similarly, they override their page and step methods to
     *  use the viewport's scrollPositionDelta methods to compute page and
     *  and step offsets.
     *    
     *  @default null
     */
    public function get viewport():IViewport
    public function set viewport(value:IViewport):void

   /**
    *  Called when the viewport's width or height changes, does nothing by default.
    */
    protected function viewportResizeHandler(event:ResizeEvent):void
    
   /**
    *  Called when the viewport's contentWidth changes, does nothing by default.
    */
    protected function viewportContentWidthChangeHandler(event:PropertyChangeEvent):void
    
    /**
     *  Called when the viewport's contentHeight changes, does nothing by default.
     */
    protected function viewportContentHeightChangeHandler(event:PropertyChangeEvent):void
    
    /**
     *  Called when the viewport's horizontalScrollPosition changes, does nothing by default.
     */
    protected function viewportHorizontalScrollPositionChangeHandler(event:PropertyChangeEvent):void
    
    /**
     *  Called when the viewport's verticalScrollPosition changes, does nothing by default. 
     */
    protected function viewportVerticalScrollPositionChangeHandler(event:PropertyChangeEvent):void

B Features


Content size changes should be reported with a ResizeEvent, for consistency with changes to a component's acutal size.

Examples and Usage


To make an viewport, like a VGroup, scrollable, add a Scroller parent:

<Scroller width="100%" height="100%">
    <VGroup>
    .... scrollable items here
    </VGroup>
</Scroller>

In this example the scroller's default "auto" scroll policies specify
that the scrollbars will appear as needed.

Additional Implementation Details


None at this time.

Flex SDK Project
Home
About
Versions
Downloads
Source
Bug Database
Submitting a Patch
Developer Documentation
Forums
License

Pages
Comments

Other Projects
BlazeDS
Cairngorm
Corelib
FlexUnit

More related projects ›
More Adobe projects ›
You must be logged in to comment.

 
Last Modified: 2008-11-03 13:14:45.0
Powered by Atlassian Confluence 2.7.1, the Enterprise Wiki.

Company | Online Privacy Policy | Terms of Use | Contact Us | Accessibility | Report Piracy | Permissions & Trademarks

Copyright @ 2008 Adobe Systems Incorporated.
Use of this website signifies your agreement to the Terms of Use and Online Privacy Policy.
Search powered by Google