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