dali/public-api/common/stage.h

   1 #ifndef __DALI_STAGE_H__
   2 #define __DALI_STAGE_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/signals/dali-signal.h>
  24
  25 namespace Dali
  26 {
  27 /**
  28  * @addtogroup dali_core_common
  29  * @{
  30  */
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class Stage;
  35 }
  36
  37 class Actor;
  38 class Layer;
  39 class ObjectRegistry;
  40 class RenderTaskList;
  41 struct Vector2;
  42 struct Vector3;
  43 struct Vector4;
  44 struct KeyEvent;
  45 struct TouchEvent;
  46 struct WheelEvent;
  47
  48 /**
  49  * @brief The Stage is a top-level object used for displaying a tree of Actors.
  50  *
  51  * Multiple stage/window support is not currently provided.
  52  *
  53  * Signals
  54  * | %Signal Name            | Method                               |
  55  * |-------------------------|--------------------------------------|
  56  * | keyEvent                | @ref KeyEventSignal()                |
  57  * | eventProcessingFinished | @ref EventProcessingFinishedSignal() |
  58  * | touched                 | @ref TouchedSignal()                 |
  59  * | wheelEvent              | @ref WheelEventSignal()              |
  60  * | contextLost             | @ref ContextLostSignal()             |
  61  * | contextRegained         | @ref ContextRegainedSignal()         |
  62  * | sceneCreated            | @ref SceneCreatedSignal()            |
  63  * @SINCE_1_0.0
  64  */
  65 class DALI_IMPORT_API Stage : public BaseHandle
  66 {
  67 public:
  68
  69   typedef Signal< void (const KeyEvent&)> KeyEventSignalType;     ///< Key event signal type @SINCE_1_0.0
  70   typedef Signal< void () > EventProcessingFinishedSignalType;    ///< Event Processing finished signal type @SINCE_1_0.0
  71   typedef Signal< void (const TouchEvent&)> TouchedSignalType;    ///< Touched signal type @SINCE_1_0.0
  72   typedef Signal< void (const WheelEvent&)> WheelEventSignalType; ///< Touched signal type @SINCE_1_0.0
  73   typedef Signal< void () > ContextStatusSignal;                  ///< Context status signal type @SINCE_1_0.0
  74   typedef Signal< void () > SceneCreatedSignalType;               ///< Scene created signal type @SINCE_1_0.0
  75
  76   static const Vector4 DEFAULT_BACKGROUND_COLOR; ///< Default black background.
  77   static const Vector4 DEBUG_BACKGROUND_COLOR;   ///< Green background, useful when debugging.
  78
  79   /**
  80    * @brief Allows the creation of an empty stage handle.
  81    *
  82    * To retrieve the current stage, this handle can be set using Stage::GetCurrent().
  83    * @SINCE_1_0.0
  84    */
  85   Stage();
  86
  87   /**
  88    * @brief Get the current Stage.
  89    *
  90    * @SINCE_1_0.0
  91    * @return The current stage or an empty handle if the internal core has not been created or has been already destroyed.
  92    */
  93   static Stage GetCurrent();
  94
  95   /**
  96    * @brief Query whether the Stage exists; this should only return false during or after destruction of Dali core.
  97    *
  98    * @SINCE_1_0.0
  99    * @return True when it's safe to call Stage::GetCurrent().
 100    */
 101   static bool IsInstalled();
 102
 103   /**
 104    * @brief Destructor
 105    *
 106    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 107    * @SINCE_1_0.0
 108    */
 109   ~Stage();
 110
 111   /**
 112    * @brief This copy constructor is required for (smart) pointer semantics.
 113    *
 114    * @SINCE_1_0.0
 115    * @param [in] handle A reference to the copied handle
 116    */
 117   Stage(const Stage& handle);
 118
 119   /**
 120    * @brief This assignment operator is required for (smart) pointer semantics.
 121    *
 122    * @SINCE_1_0.0
 123    * @param [in] rhs  A reference to the copied handle
 124    * @return A reference to this
 125    */
 126   Stage& operator=(const Stage& rhs);
 127
 128   // Containment
 129
 130   /**
 131    * @brief Adds a child Actor to the Stage.
 132    *
 133    * The child will be referenced.
 134    * @SINCE_1_0.0
 135    * @param [in] actor The child.
 136    * @pre The actor has been initialized.
 137    * @pre The actor does not have a parent.
 138    */
 139   void Add(Actor& actor);
 140
 141   /**
 142    * @brief Removes a child Actor from the Stage.
 143    *
 144    * The child will be unreferenced.
 145    * @SINCE_1_0.0
 146    * @param [in] actor The child.
 147    * @pre The actor has been added to the stage.
 148    */
 149   void Remove(Actor& actor);
 150
 151   /**
 152    * @brief Returns the size of the Stage in pixels as a Vector.
 153    *
 154    * The x component will be the width of the Stage in pixels
 155    * The y component will be the height of the Stage in pixels
 156    * The z component will be the distance between far and near planes
 157    * @SINCE_1_0.0
 158    * @return The size of the Stage as a Vector.
 159    */
 160   Vector2 GetSize() const;
 161
 162   // Render Tasks
 163
 164   /**
 165    * @brief Retrieve the list of render-tasks.
 166    *
 167    * @SINCE_1_0.0
 168    * @return A valid handle to a RenderTaskList.
 169    */
 170   RenderTaskList GetRenderTaskList() const;
 171
 172   // Layers
 173
 174   /**
 175    * @brief Query the number of on-stage layers.
 176    *
 177    * Note that a default layer is always provided (count >= 1).
 178    * @SINCE_1_0.0
 179    * @return The number of layers.
 180    */
 181   unsigned int GetLayerCount() const;
 182
 183   /**
 184    * @brief Retrieve the layer at a specified depth.
 185    *
 186    * @SINCE_1_0.0
 187    * @param[in] depth The depth.
 188    * @return The layer found at the given depth.
 189    * @pre Depth is less than layer count; see GetLayerCount().
 190    */
 191   Layer GetLayer(unsigned int depth) const;
 192
 193   /**
 194    * @brief Returns the Stage's Root Layer.
 195    *
 196    * @SINCE_1_0.0
 197    * @return The root layer.
 198    */
 199   Layer GetRootLayer() const;
 200
 201   // Background color
 202
 203   /**
 204    * @brief Set the background color of the stage.
 205    *
 206    * @SINCE_1_0.0
 207    * @param[in] color The new background color.
 208    */
 209   void SetBackgroundColor(Vector4 color);
 210
 211   /**
 212    * @brief Retrieve the background color of the stage.
 213    *
 214    * @SINCE_1_0.0
 215    * @return The background color.
 216    */
 217   Vector4 GetBackgroundColor() const;
 218
 219   /**
 220    * @brief Retrieve the DPI of the display device to which the stage is connected.
 221    *
 222    * @SINCE_1_0.0
 223    * @return The horizontal and vertical DPI
 224    */
 225   Vector2 GetDpi() const;
 226
 227   /**
 228    * @brief Get the Object registry.
 229    *
 230    * @SINCE_1_0.0
 231    * @return The object registry.
 232    */
 233   ObjectRegistry GetObjectRegistry() const;
 234
 235   // Rendering
 236
 237   /**
 238    * @brief Keep rendering for at least the given amount of time.
 239    *
 240    * By default Dali will stop rendering when no Actor positions are being set, and when no animations are running etc.
 241    * This method is useful to force screen refreshes e.g. when updating a NativeImage.
 242    * @SINCE_1_0.0
 243    * @param[in] durationSeconds Time to keep rendering, 0 means render at least one more frame
 244    */
 245   void KeepRendering( float durationSeconds );
 246
 247   // Signals
 248
 249   /**
 250    * @brief This signal is emitted when key event is received.
 251    *
 252    * A callback of the following type may be connected:
 253    * @code
 254    *   void YourCallbackName(const KeyEvent& event);
 255    * @endcode
 256    * @SINCE_1_0.0
 257    * @return The signal to connect to.
 258    */
 259   KeyEventSignalType& KeyEventSignal();
 260
 261   /**
 262    * @brief This signal is emitted just after the event processing is finished.
 263    *
 264    * @SINCE_1_0.0
 265    * @return The signal to connect to.
 266    */
 267   EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
 268
 269   /**
 270    * @brief This signal is emitted when the screen is touched and when the touch ends
 271    * (i.e. the down & up touch events only).
 272    *
 273    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 274    * then when the last finger is lifted.
 275    * An interrupted event will also be emitted.
 276    * A callback of the following type may be connected:
 277    * @code
 278    *   void YourCallbackName(const TouchEvent& event);
 279    * @endcode
 280    *
 281    * @SINCE_1_0.0
 282    * @return The touch signal to connect to.
 283    * @note Motion events are not emitted.
 284    */
 285   TouchedSignalType& TouchedSignal();
 286
 287   /**
 288    * @brief This signal is emitted when wheel event is received.
 289    *
 290    * A callback of the following type may be connected:
 291    * @code
 292    *   void YourCallbackName(const WheelEvent& event);
 293    * @endcode
 294    * @SINCE_1_0.0
 295    * @return The signal to connect to.
 296    */
 297   WheelEventSignalType& WheelEventSignal();
 298
 299   /**
 300    * @brief This signal is emitted when the GL context is lost (Platform specific behaviour).
 301    *
 302    * If the application is responsible for handling context loss, it should listen to
 303    * this signal and tear down UI components when recieved.
 304    * @SINCE_1_0.0
 305    * @return The context lost signal to connect to.
 306    */
 307   ContextStatusSignal& ContextLostSignal();
 308
 309   /**
 310    * @brief This signal is emitted when the GL context is regained (Platform specific
 311    * behaviour).
 312    *
 313    * If the application is responsible for handling context loss, it should listen to
 314    * this signal and rebuild UI components on receipt.
 315    * @SINCE_1_0.0
 316    * @return The context regained signal to connect to.
 317    */
 318   ContextStatusSignal& ContextRegainedSignal();
 319
 320   /**
 321    * @brief This signal is emitted after the initial scene is created.
 322    *
 323    * It will be triggered after the
 324    * application init signal.
 325    *
 326    * A callback of the following type may be connected:
 327    * @code
 328    *   void YourCallbackName();
 329    * @endcode
 330    * @SINCE_1_0.0
 331    * @return The signal to connect to.
 332    */
 333   SceneCreatedSignalType& SceneCreatedSignal();
 334
 335 public: // Not intended for application developers
 336
 337   /**
 338    * @brief This constructor is used by Stage::GetCurrent() methods.
 339    *
 340    * @SINCE_1_0.0
 341    * @param [in] stage A pointer to a Dali resource
 342    */
 343   explicit DALI_INTERNAL Stage(Internal::Stage* stage);
 344 };
 345
 346 /**
 347  * @}
 348  */
 349
 350 } // namespace Dali
 351
 352 #endif // __DALI_STAGE_H__