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