optional/dali-toolkit/public-api/controls/view/view.h

   1 #ifndef __DALI_TOOLKIT_VIEW_H__
   2 #define __DALI_TOOLKIT_VIEW_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 // INTERNAL INCLUDES
  21 #include <dali-toolkit/public-api/controls/control.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Internal DALI_INTERNAL
  27 {
  28 // Forward declarations
  29 class CustomActor;
  30 }
  31
  32 namespace Toolkit
  33 {
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37 // Forward declarations
  38 class View;
  39 }
  40
  41 /**
  42  * View provides a container where different Dali::Layer instances and a background could be added. It
  43  * also provides a View::OrientationChanged() method which could be connected to the Dali::Orientation::SignalChange() signal.
  44  * This method rotates all layers accordingly with the given orientation, it emits an OrientationAnimationStartsSignal signal just before the rotation animation starts.
  45  *
  46  * By default view anchor point and parent origin are centered, the size is full screen and is got directly from the Dali::Stage. However, by passing \e false to the
  47  * Toolkit::View::New() method a custom size could be specified, and after initialization, anchor point and parent origin could be updated.
  48  *
  49  * If a background is set, a background layer will be created and dropped to the bottom.
  50  *
  51  * Use example (application is a Dali::Application object):
  52  * \code{.cpp}
  53  * Stage stage = Stage::GetCurrent();
  54  *
  55  * // Create default View. By default it gets the stage size.
  56  * Toolkit::View view = Toolkit::View::New();
  57  *
  58  * // Add the view to the stage before setting the background.
  59  * stage.Add( view );
  60  *
  61  * // Set background image. BACKGROUND_IMAGE is a string with the background image file path.
  62  * Image backgroundImage = Image::New( BACKGROUND_IMAGE );
  63  * ImageActor backgroundImageActor = ImageActor::New( backgroundImage );
  64  * mView.SetBackground( backgroundImageActor );
  65  *
  66  * // Connects the orientation signal with the View::OrientationChanged method.
  67  * application.GetOrientation().ChangedSignal().Connect( &view, &Toolkit::View::OrientationChanged );
  68  *
  69  * // Create a content layer.
  70  * Layer contentLayer = Layer::New();
  71  * contentLayer.SetAnchorPoint( AnchorPoint::CENTER );
  72  * contentLayer.SetParentOrigin( ParentOrigin::CENTER );
  73  * contentLayer.ApplyConstraint( ParentConstraint::Size::New( ParentSize() ) );
  74  * view.AddContentLayer( contentLayer );
  75  * \endcode
  76  */
  77 class View : public Control
  78 {
  79 public:
  80   //Signal Names
  81   static const char* const SIGNAL_ORIENTATION_ANIMATION_START;
  82
  83 public:
  84
  85   /**
  86    * Create a View handle; this can be initialised with View::New()
  87    * Calling member functions with an uninitialised handle is not allowed.
  88    */
  89   View();
  90
  91   /**
  92    * Copy constructor. Creates another handle that points to the same real object
  93    * @param handle to copy from
  94    */
  95   View( const View& handle );
  96
  97   /**
  98    * Assignment operator. Changes this handle to point to another real object
  99    */
 100   View& operator=( const View& handle );
 101
 102   /**
 103    * virtual Destructor.
 104    */
 105   virtual ~View();
 106
 107   /**
 108    * Create an initialized View.
 109    * @param fullscreen If true, the view's size is going to be set with the Dali::Stage size. Otherwise a size must be provided. By default fullscreen is set to true.
 110    * @return A handle to a newly allocated Dali resource.
 111    */
 112   static View New( bool fullscreen = true );
 113
 114   /**
 115    * Downcast an Object handle to View. If handle points to a View the
 116    * downcast produces valid handle. If not the returned handle is left uninitialized.
 117    * @param[in] handle Handle to an object
 118    * @return handle to a View or an uninitialized handle
 119    */
 120   static View DownCast( BaseHandle handle );
 121
 122   /**
 123    * Returns a content layer.
 124    * @param index to the layer container.
 125    * @return A Layer handle if it exists, otherwise it returns an uninitialized handle.
 126    */
 127   Layer GetContentLayer( unsigned int index ) const;
 128
 129   /**
 130    * Adds a new layer in the view.
 131    * @pre layer must be initialized.
 132    * @param layer A Layer handle.
 133    * @return the an index that can be used to access the layer stores in the view.
 134    */
 135   unsigned int AddContentLayer( Layer layer );
 136
 137   /**
 138    * Removes a layer from the view.
 139    * @param layer The layer to be removed.
 140    */
 141   void RemoveContentLayer( Layer layer );
 142
 143   /**
 144    * Returns the background layer.
 145    * @return the background layer or an empty handle if any background has been set before.
 146    */
 147   Layer GetBackgroundLayer() const;
 148
 149   /**
 150    * Sets a background image.
 151    *
 152    * It creates a background layer the first time this method is called and it is dropped to the bottom.
 153    * Any previous set background will be replaced by the new one.
 154    *
 155    * @pre View must be on stage before calling SetBackground.
 156    * @param image An image actor.
 157    */
 158   void SetBackground( ImageActor image );
 159
 160   /**
 161    * Sets the angle values for portrait, landscape, portrait inverse and landscape inverse.
 162    *
 163    * These angles are used to rotate the views.
 164    * By default, orientation angles are initialized as follows: portrait 0, landscape 90, portrait inverse 180, landscape inverse 270.
 165    *
 166    * @param portrait angle in degrees.
 167    * @param landscale angle in degrees.
 168    * @param portraitInverse angle in degrees.
 169    * @param landscapeInverse angle in degrees.
 170    */
 171   void SetOrientationFunction( Degree portrait, Degree landscale, Degree portraitInverse, Degree landscapeInverse );
 172
 173   /**
 174    * It rotates all layers to the new given orientation.
 175    *
 176    * @param orientation The new orientation.
 177    */
 178   void OrientationChanged( Orientation orientation );
 179
 180   /**
 181    * Enables or disables the view's rotation when device orientation changes.
 182    * @param enabled Whether auto-rotate should be enabled or disabled. By default is enabled.
 183    */
 184   void SetAutoRotate( bool enabled );
 185
 186 public: //Signals
 187
 188   // Orientation change animation starts.
 189   typedef SignalV2< void ( View, Animation&, const Orientation& ) > OrientationAnimationStartedSignalV2;
 190
 191   /**
 192    * Signal emitted just before the rotate animation starts when the device orientation changes.
 193    */
 194   OrientationAnimationStartedSignalV2& OrientationAnimationStartedSignal();
 195
 196 public: // Not intended for application developers
 197
 198   /**
 199    * Creates a handle using the Toolkit::Internal implementation.
 200    * @param[in]  implementation  The Control implementation.
 201    */
 202   View( Internal::View& implementation );
 203
 204   /**
 205    * Allows the creation of this Control from an Internal::CustomActor pointer.
 206    * @param[in]  internal  A pointer to the internal CustomActor.
 207    */
 208   View( Dali::Internal::CustomActor* internal );
 209 };
 210
 211
 212 } // namespace Toolkit
 213
 214 } // namespace Dali
 215
 216 #endif // __DALI_TOOLKIT_VIEW_H__