uiScrollPane

The uiScrollPane component is used to display content within a scrollable area. This component is a composite consisting of a uiPane, uiScrollBar and uiVScrollBar.

The uiScrollPane component can only contain a single uiPane child object, which can be accessed via the content property. This embedded uiPane instance can of course contain other child objects. This means that if you wish to add content to a uiScrollPane instance, you must do so by adding to the single child content¹⁾.

// ** add to content **
sp.content.addChild(txta);

You can also create a new uiPane container, add whatever content you want to this container, and set the uiScrollPane instance's content property to this uiPane instance.

 1: import com.ghostwire.ui.containers.uiPane;
 2: import com.ghostwire.ui.containers.uiScrollPane;
 3: import com.ghostwire.ui.controls.uiText;
 4:
 5: var txta:uiText = new uiText("some text");
 6: txta.move(10,10);
 7:
 8: var txtb:uiText = new uiText("more text");
 9: txtb.move(100,100);
10:
11: // ** create the content **
12: var pane:uiPane = new uiPane();
13: pane.addChild(txta);
14: pane.addChild(txtb);
15:
16: // ** the scrollpane **
17: var sp:uiScrollPane = new uiScrollPane();
18: sp.content = pane; // ** set the content **
19:
20: // ** add to display list **
21: addChild(sp);

NOTE: The uiPane container within the uiScrollPane is a non-constraining container - it does not do any space allocation. Child objects must be positioned absolutely using the move() method.

Where scroll positions are concerned, the origin is always at (0,0). It is not necessary to have something at the origin (0,0). The uiScrollPane will compute the scrollable region correctly even if there is nothing at the origin (0,0). In fact, the uiScrollPane component is flexible enough to handle objects placed at negative positions as well.

For example, append the following code, adding another child object at position (-50,-5):

23: var txtc:uiText = new uiText("even more text");
24: txtc.move(-50,-5);
25: pane.addChild(txtc);

The starting position remains at (0,0), with the scroll values (and scroll bars) are updated to allow scrolling into negative positions.

var sp:uiScrollPane = new uiScrollPane();
sp.hScrollPolicy = SCROLLBAR.ON;
sp.vScrollPolicy = SCROLLBAR.ON;

The hScrollPolicy property indicates whether a horizontal scroll bar should be shown (anchored at the bottom of the component instance). Qualified values are SCROLLBAR.ON (always shown), SCROLLBAR.OFF (never shown), or SCROLLBAR.AUTO (shown when it is needed/hidden when it is not needed)²⁾. Any other values will set the property to SCROLLBAR.AUTO. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

In order for the horizontal scroll bar to appear, the width of the uiScrollPane instance must be greater than the desired width of the scroll bar (enough space to show the left/right arrow buttons).

The vScrollPolicy property indicates whether a vertical scroll bar should be shown (anchored on the right-hand-side of the component instance). Qualified values are as for hScrollPolicy. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

In order for the vertical scroll bar to appear, the height of the uiScrollPane instance must be greater than the desired height of the scroll bar (enough space to show the up/down arrow buttons).

NOTE: When containing objects that are not uiComponent instances, you must invalidate the container after making changes to the positions and/or sizes of the objects during run-time³⁾ (Line 33):

 1: import com.ghostwire.ui.containers.uiBox;
 2: import com.ghostwire.ui.containers.uiScrollPane;
 3: import com.ghostwire.ui.controls.uiPushButton;
 4:
 5: import flash.display.Shape;
 6:
 7: // ** a Shape object **
 8: var circle:Shape = new Shape();
 9: circle.graphics.beginFill(0x777777, 1);
10: circle.graphics.drawCircle(100,100,100);
11: circle.graphics.endFill();
12:
13: // ** the scrollpane **
14: var sp:uiScrollPane = new uiScrollPane();
15: sp.content.addChild(circle);
16:
17: // ** resize button **
18: var btn:uiPushButton = new uiPushButton("resize");
19: btn.addEventListener(MouseEvent.CLICK,on_click);
20:
21: // ** box for layout **
22: var box:uiBox = new uiBox();
23: box.addChild(sp);
24: box.addChild(btn);
25:
26: // ** add to display list **
27: addChild(box);
28:
29: // ** resize button handler **
30: function on_click(evt:MouseEvent):void
31: {
32:     circle.width = 10;
33:     sp.content.invalidate();
34: }

The uiScrollPane has a fixed default size of 100px width and 100px height; the contents do not affect this default size. Use the setSize(width,height) method to set preferred dimensions.

var sp:uiScrollPane= new uiScrollPane();
sp.setSize(300,300);

The component will allocate enough space to the scroll bars first; the balance is then allocated to the content area.

A uiScrollPane instance with a scrollable area (ie its content is not being displayed fully) will itself be included in the tab focus chain⁴⁾. This is to allow scrolling using the keyboard.

While it has focus, the user can use the following keys:

The user can also use the mouse wheel to scroll the content.

As a visual cue, a focus rectangle will be drawn on the perimeter of the content area, but will disappear once scrolling occurs. The disappearance of the focus rectangle is intended behavior.

For more information on the members of the com.ghostwire.ui.containers.uiScrollPane class, please refer to the API Reference.