docs/content/programming-guide/scroll-view.h

   1 /*! \page scroll-view Example and Usage
   2
   3    We will start by showing the steps to creating a ScrollView, adding to the stage, and adding content to the ScrollView.
   4
   5    Then we look at some of the options to achieve commonly desired ScrollView effects, from ruler snap points to domains.
   6
   7    \section intro Simple ScrollView setup, and ruler configuration.
   8
   9    We declare a ScrollView component called myScrollView
  10
  11    @code
  12    Dali::Toolkit::ScrollView myScrollView;
  13    @endcode
  14
  15    A new ScrollView instance is then created by calling the following
  16    @code
  17    myScrollView = ScrollView::New();
  18    @endcode
  19
  20    We then add it to the stage.
  21    @code
  22    Stage::GetCurrent().Add(myScrollView);
  23    @endcode
  24
  25    Then we specify the size. We'll make it cover the entire stage
  26    @code
  27    Stage stage = Dali::Stage::GetCurrent();
  28    Size size = stage.GetSize();
  29    myScrollView.SetSize( size );
  30    @endcode
  31
  32    Add Actors to this ScrollView
  33    @code
  34    Image image = Image::New(DALI_IMAGE_DIR "button-background.png");
  35    ImageActor imageActor = ImageActor::New(image);
  36    myScrollView.Add( imageActor );
  37    @endcode
  38
  39    The ScrollView contents are now draggable by the user using touch (panning gestures).
  40
  41    To enforce horizontal-only scrolling, the Y-axis ruler can be disabled
  42    @code
  43    RulerPtr rulerY = new DefaultRuler();
  44    rulerY->Disable();
  45    myScrollView.SetRulerY(rulerY);
  46    @endcode
  47
  48    To enable snapping, a FixedRuler can be applied to the X-axis, with snap points spaced to the width of the stage.
  49    @code
  50    Stage stage = Dali::Stage::GetCurrent();
  51    Size size = stage.GetSize();
  52    RulerPtr rulerX = new FixedRuler(size.width);
  53    myScrollView.SetRulerX(rulerX);
  54    @endcode
  55
  56    A 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.
  57    @code
  58    Stage stage = Dali::Stage::GetCurrent();
  59    Size size = stage.GetSize();
  60    RulerPtr rulerX = new FixedRuler(size.width);
  61    rulerX->SetDomain(RulerDomain(0.0f, size.width*4.0f));
  62    myScrollView.SetRulerX(rulerX);
  63    @endcode
  64
  65    Ruler      Domain      Wrap      Behaviour
  66    =====      ======      ====      =========
  67
  68    Disabled   Disabled    No-Wrap   "No Movement in axis"
  69    Disabled   Disabled    Wrap      "No Movement in axis"
  70    Disabled   Enabled     No-Wrap   "No Movement in axis"
  71    Disabled   Enable      Wrap      "No Movement in axis"
  72    Enabled    Disabled    No-Wrap   "Free Movement in axis"
  73    Enabled    Disabled    Wrap      "Free Movement in axis, but will wrap based on domain min-max"
  74    Enabled    Enabled     No-Wrap   "Movement limited to domain min-max"
  75    Enabled    Enabled     Wrap      "Movement limited to domain min-max"
  76
  77    @note It is important to note that Actors within ScrollView are controlled by constraints,
  78    and thus undefined behaviour will occur when applying constraints to these Actors externally.
  79    If you wish to apply additional constraints that may conflict with the ScrollView's constraints,
  80    then it is recommended that you place the Actors within container Actors. So that the container
  81    Actors are affected by the constraints.
  82
  83  */
  84