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 to NaN, the button length will be determined by the size of the canvas and the buttonThickness property.
• 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. See data property for information about the button index.
• panScrollingButtonRollOut dda.events.PanScrollingEvent.PAN_SCROLLING_BUTTON_ROLL_OUT
  Dispatched when the user rolls over a control button. See data property 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. See data property for information about the button index.
• panScrollingClick dda.events.PanScrollingEvent.PAN_SCROLLING_CLICK
  Dispatched when the user clicks on the canvas. See localX and localY properties 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 to buttonThickness.

  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.