jul
29
The PanScrollingCanvas is a Flex container that scrolls its children on mouse move. Fully skinnable buttons appear when hovering over the container. The behavior of those buttons can be customized on the client side, by listening to events that this container will fire on button rollover, rollout, and click.
This component is inspired from Doug McCune’s ButtonScrollingCanvas, which is part of flexlib. Using Doug’s component, users interact with one of the four buttons laid out over the container, in order to initiate a scrolling effect–in the direction indicated by the button. I wanted to do something similar, but without relying on the buttons for scrolling the content. Here, the interaction consists of panning the mouse over the container, with a goal-based ease out to give an organic feel to it. Also, 8 directional buttons (instead of 4) are introduced for control affordance and client custom behavior.
Let’s jump to a demo, before getting to the nitty gritty…
Example: exploring Yahoo! maps
To see a full page demo (with source view), click here.
In the above example, the zoom buttons (in the center) have been added by the client application, and their visibility is synchronized through the PanScrollingEvent.CONTROLS_VISIBLE_CHANGE event.
Brief Notes
Syntax
The <containers:PanScrollingPan> tag inherits all the tag attributes of its superclass mx.containers.Canvas and adds the following tag attributes:
<containers:PanScrollingCanvas
Properties
buttonsAlpha="1.0"
buttonsEnabled="true"
buttonsVisible="false"
explicitButtonLength="NaN"
panningEaseFactor="0.08"
panningRefreshRate="10"
panningThreshold="1.5"
Styles
buttonThickness="20"
eastButtonStyleName="eastButton"
mouseScrollPadding="20"
northButtonStyleName="northButton"
northEastButtonStyleName="northEastButton"
northWestButtonStyleName="northWestButton"
southButtonStyleName="southButton"
southEastButtonStyleName="southEastButton"
southWestButtonStyleName="southWestButton"
westButtonStyleName="westButton"
Events
panScrollingButtonClick="No default"
panScrollingButtonRollOut="No default"
panScrollingButtonRollOver="No default"
panScrollingClick="No default"
/>
Properties
- buttonsAlpha : Number
Indicates the alpha transparency value of the eight control buttons located around the canvas. - buttonsEnabled : Boolean
Whether the eight control buttons can accept user interaction. - buttonsVisible : Boolean
Controls the visibility of the eight control buttons.This property is controlled by the component. But in some cases, the client may need to manually set the visibility. (See example’s source code.)
- explicitButtonLength : Number
If set, determines the length of the North, East, South, and West control buttons, that is North/South button’s width, and East/West button’s height, not to exceed the length they would have when the property is not set. If not set, or set back toNaN, the button length will be determined by the size of the canvas and thebuttonThicknessproperty. - panningEaseFactor : Number
Regulates the ease out during the panning. As mouse locations determine scrolling goals, this parameter tells the component what portion of the goal to scroll to, each time the pan clock refreshes. This is a ratio between 0 and 1, not inclusive.Adjust this property to get the desired pan scrolling feel, based on the relative sizes of the canvas and its scrollable content.
- panningRefreshRate : Number
Pan clock tick, in milliseconds. - panningThreshold : Number
Amount of pixels by which a scrolling goal is deemed reached. Should be a non-zero positive number.
Methods
- startPanScrolling():void
Starts the pan clock, which in turn activates the goal-based automatic scrolling. - stopPanScrolling():void
Stops the pan clock, which stops the automatic scrolling.
Events
- controlsVisibleChange
dda.events.PanScrollingEvent.CONTROLS_VISIBLE_CHANGE
Dispatched when the control buttons changed their visibility state. - panScrollingButtonClick
dda.events.PanScrollingEvent.PAN_SCROLLING_BUTTON_CLICK
Dispatched when a control button has been clicked. Seedataproperty for information about the button index. - panScrollingButtonRollOut
dda.events.PanScrollingEvent.PAN_SCROLLING_BUTTON_ROLL_OUT
Dispatched when the user rolls over a control button. Seedataproperty for information about the button index. - panScrollingButtonRollOver
dda.events.PanScrollingEvent.PAN_SCROLLING_BUTTON_ROLL_OVER
Dispatched when the user rolls out of a control button. Seedataproperty for information about the button index. - panScrollingClick
dda.events.PanScrollingEvent.PAN_SCROLLING_CLICK
Dispatched when the user clicks on the canvas. SeelocalXandlocalYproperties for the mouse location, relative to the top left corner of the canvas.
Styles
- buttonThickness Type: Number
Specifies the thickness of the 8 control buttons. - mouseScrollPadding Type:Number
Specifies the amount of padding from the canvas edges to be excluded from the area that is used for determining scrolling goals with respect to mouse locations. By default it is set tobuttonThickness.A positive value allows the user to see the edges of the content without having to pan the mouse to the edges of the canvas.
- <ID>ButtonStyleName Type: String
Specifies the stylename for the corresponging button, where <ID> is one of {north, northEast, east, southEast, south, southWest, west, northWest}.
Public Constants
- BUTTON_NONE
:int = -1;
[static] - BUTTON_NORTH
:int = 0;
[static] The index value for the North control button. - BUTTON_NORTH_EAST
:int = 1;
[static] The index value for the North East control button. - BUTTON_EAST
:int = 2;
[static] The index value for the East control button. - BUTTON_SOUTH_EAST
:int = 3;
[static] The index value for the South East control button. - BUTTON_SOUTH
:int = 4;
[static] The index value for the South control button. - BUTTON_SOUTH_WEST
:int = 5;
[static] The index value for the South West control button. - BUTTON_WEST
:int = 6;
[static] The index value for the West control button. - BUTTON_NORTH_WEST
:int = 7;
[static] The index value for the North West control button.

Valerie
August 22nd, 2008 at 4:58 amHi Didier,
Is it possible to drag the map instead of roll over it ?
Thanks,
Valerie
didier
August 22nd, 2008 at 8:23 amDragging the map is a built-in feature in the Yahoo! Maps API. You can enable it by doing:
yahooMap.addPanControl();You can also check the source code of the examples at http://developer.yahoo.com/flash/maps/examples.html if you need more insight about the Yahoo! Maps API.
Just note that exploring maps was just an application of this Flex component, which should be considered an alternative to clicking and dragging. Mixing both might be very confusing. I’ll post more uses of mouse panning using this component.
Valerie
August 22nd, 2008 at 2:10 pmThanks for your answer.
Actually, I don’t use yahoo maps but svg maps that I load dynamically with Degrafa … And dragging the map is a feature I would like to implement in my project …
Best regards,
Valérie
newbie_ekol
September 18th, 2008 at 11:41 amhi I need some help with using your container in a project that I am doing right now…how do I use the container if I am not using your container for yahoo! maps? is there a tutorial that I can take which could help me out? I am a total newbie to flex and I know a lil bit of AS3
didier
September 18th, 2008 at 7:19 pmJust use the container as a
Canvas, and make sure its content is allowed to be bigger than the container itself, i.e. don’t constraint the content width and height to 100%. Otherwise, you will not get any scrolling. Refer to the Flex doc if you need more info about how to use containers.