ScrollView
PUBLISHED
The Dali::Toolkit::ScrollView
class provides a scrollable view, which contains actors and can be scrolled automatically or manually by panning.
The following figure shows example layouts using the ScrollView
.
Figure: ScrollView
In this tutorial, the following subjects are covered:
ScrollView events
The following table lists the basic signals provided by the Dali::Toolkit::ScrollView
class.
Table: Dali::Toolkit::ScrollView input signals
Input signal | Description |
---|---|
SnapStartedSignal() |
Emitted when the ScrollView has started to snap or flick. |
A scroll view emits a ScrollView::SnapStartedSignal()
signal when the scroll view has started to snap or flick. The signal informs the target of the scroll position, scale, and rotation.
Creating a ScrollView
The following example shows how to create a Dali::Toolkit::ScrollView
object:
void HelloWorldExample::Create( Application& application ) { // Create a ScrollView instance ScrollView scrollView = ScrollView::New(); scrollView.SetParentOrigin( ParentOrigin::CENTER ); Stage::GetCurrent().Add( scrollView ); // Set the size of scrollView; // it covers the entire stage Size size = Stage::GetCurrent().GetSize(); scrollView.SetSize( size ); // Add actors to the ScrollView for( int i; i < MY_ITEM_COUNT; ++i ) { ImageView imageView = ImageView::New( MY_IMAGE_PATHS[i] ); imageView.SetAnchorPoint( AnchorPoint::TOP_LEFT ); imageView.SetPosition( i * size.x, 0.0f ); scrollView.Add( imageView ); } // ScrollView contents are now draggable // To enforce horizontal-only scrolling, // the Y axis ruler can be disabled RulerPtr rulerY = new DefaultRuler(); rulerY->Disable(); scrollView.SetRulerY( rulerY ); // To enable snapping, a FixedRuler can be // applied to the X axis, with snap // points spaced to the width of the stage RulerPtr rulerX1 = new FixedRuler( size.width ); scrollView.SetRulerX( rulerX1 ); // Domain can be applied to rulers to prevent // scrolling beyond this boundary // In this case, to 4 times the width of the // stage, allowing for 4 pages to be scrolled RulerPtr rulerX2 = new FixedRuler( size.width ); rulerX2->SetDomain( RulerDomain( 0.0f, size.width*4.0f ) ); scrollView.SetRulerX( rulerX2 ); }
Using Ruler, RulerDomain, and Wrap
The Dali::Toolkit::Ruler
abstract class defines the scroll axes. The Dali::Toolkit::RulerDomain
class specifies the minimum and maximum values of a ruler.
The Dali::Toolkit::ScrollView
class provides a wrap mode for ScrollView
contents. When enabled, the ScrollView
contents are wrapped over the x/y domain.
The ScrollView
behavior depends on a combination of the ruler, ruler domain, and wrap modes. The following table shows ScrollView
behavior according to the combination.
Figure: Ruler, ruler domain, and wrap modes
Table: Scrollview behavior in the ruler, ruler domain, and wrap mode
Ruler | Domain | Wrap | Behavior |
---|---|---|---|
Disabled | Disabled | Wrap | No movement in axis |
Disabled | Enabled | No wrap | No movement in axis |
Disabled | Enabled | Wrap | No movement in axis |
Enabled | Disabled | No wrap | Free movement in axis |
Enabled | Disabled | Wrap | Free movement in axis, wrapped according to domain minimum and maximum |
Enabled | Enabled | No wrap | Movement limited to domain minimum and maximum |
Enabled | Enabled | Wrap | Movement limited to domain minimum and maximum |
ScrollView
are controlled by constraints. If you apply constraints to these actors externally, undefined behavior can occur. Since applying additional constraints can conflict with the ScrollView
constraints, place the actors within container actors. The container actors are affected by the constraints.ScrollView Properties
The following table lists the available ScrollView properties.
Table: ScrollView properties
Property | Type | Description |
---|---|---|
WRAP_ENABLED |
BOOLEAN | Whether wrapping is enabled |
PANNING_ENABLED |
BOOLEAN | Whether panning is enabled |
AXIS_AUTO_LOCK_ENABLED |
BOOLEAN | Whether the Axis Auto Lock mode for panning within the ScrollView is enabled |
WHEEL_SCROLL_DISTANCE_STEP |
VECTOR2 | The step of scroll distance in actor coordinates for each wheel event received in free panning mode |
SCROLL_MODE |
MAP | The scroll mode |
SCROLL_POSITION |
VECTOR2 | The current scroll position |
SCROLL_PRE_POSITION |
VECTOR2 | The position before we set the clamp at scroll boundaries |
SCROLL_PRE_POSITION_X |
FLOAT | The X component of SCROLL_PRE_POSITION |
SCROLL_PRE_POSITION_Y |
FLOAT | The Y component of SCROLL_PRE_POSITION |
SCROLL_PRE_POSITION_MAX |
VECTOR2 | The maximum value that SCROLL_PRE_POSITION can be |
SCROLL_PRE_POSITION_MAX_X |
FLOAT | The X component of SCROLL_PRE_POSITION_MAX |
SCROLL_PRE_POSITION_MAX_Y |
FLOAT | The Y component of SCROLL_PRE_POSITION_MAX |
OVERSHOOT_X |
FLOAT | The amount that we can scroll beyond the boundary along the X axis |
OVERSHOOT_Y |
FLOAT | The amount that we can scroll beyond the boundary along the Y axis |
SCROLL_FINAL |
VECTOR2 | The position after the overshoot value has been considered in the calculation |
SCROLL_FINAL_X |
FLOAT | The X component of SCROLL_FINAL |
SCROLL_FINAL_Y |
FLOAT | The Y component of SCROLL_FINAL |
WRAP |
BOOLEAN | Whether scrolling wraps |
PANNING |
BOOLEAN | Whether we are currently panning |
SCROLLING |
BOOLEAN | Whether we are currently scrolling |
SCROLL_DOMAIN_SIZE |
VECTOR2 | The size of the scrolling domain |
SCROLL_DOMAIN_SIZE_X |
FLOAT | The X component of SCROLL_DOMAIN_SIZE |
SCROLL_DOMAIN_SIZE_Y |
FLOAT | The Y component of SCROLL_DOMAIN_SIZE |
SCROLL_DOMAIN_OFFSET |
VECTOR2 | The offset of the scroll domain |
SCROLL_POSITION_DELTA |
VECTOR2 | The delta in the position when scrolling |
START_PAGE_POSITION |
VECTOR3 | The starting page position |