X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fcommon%2Fstage.h;h=06d44166b554c0947e06a10b41ea72d48dd91148;hb=1e196c6efe3a7a10c7198bb729027658fbdd5b16;hp=0a11b8e00bdb84e929e8d98b3bb4e6115311a549;hpb=125ec6872f317edb3a6e2fd4707896877e74c42c;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/common/stage.h b/dali/public-api/common/stage.h index 0a11b8e..06d4416 100644 --- a/dali/public-api/common/stage.h +++ b/dali/public-api/common/stage.h @@ -37,6 +37,7 @@ class Stage; class Actor; class Layer; class ObjectRegistry; +class TouchData; class RenderTaskList; struct Vector2; struct Vector3; @@ -51,26 +52,28 @@ struct WheelEvent; * Multiple stage/window support is not currently provided. * * Signals - * | %Signal Name | Method | - * |---------------------------|--------------------------------------| - * | key-event | @ref KeyEventSignal() | - * | event-processing-finished | @ref EventProcessingFinishedSignal() | - * | touched | @ref TouchedSignal() | - * | wheel-event | @ref WheelEventSignal() | - * | context-lost | @ref ContextLostSignal() | - * | context-regained | @ref ContextRegainedSignal() | - * | scene-created | @ref SceneCreatedSignal() | + * | %Signal Name | Method | + * |-------------------------|--------------------------------------| + * | keyEvent | @ref KeyEventSignal() | + * | eventProcessingFinished | @ref EventProcessingFinishedSignal() | + * | touched | @ref TouchedSignal() | + * | wheelEvent | @ref WheelEventSignal() | + * | contextLost | @ref ContextLostSignal() | + * | contextRegained | @ref ContextRegainedSignal() | + * | sceneCreated | @ref SceneCreatedSignal() | + * @SINCE_1_0.0 */ class DALI_IMPORT_API Stage : public BaseHandle { public: - typedef Signal< void (const KeyEvent&)> KeyEventSignalType; ///< Key event signal type - typedef Signal< void () > EventProcessingFinishedSignalType; ///< Event Processing finished signal type - typedef Signal< void (const TouchEvent&)> TouchedSignalType; ///< Touched signal type - typedef Signal< void (const WheelEvent&)> WheelEventSignalType; ///< Touched signal type - typedef Signal< void () > ContextStatusSignal; ///< Context status signal type - typedef Signal< void () > SceneCreatedSignalType; ///< Scene created signal type + typedef Signal< void (const KeyEvent&) > KeyEventSignalType; ///< Key event signal type @SINCE_1_0.0 + typedef Signal< void () > EventProcessingFinishedSignalType; ///< Event Processing finished signal type @SINCE_1_0.0 + typedef Signal< void (const TouchEvent&) > TouchedSignalType; ///< @DEPRECATED_1_1.37 @brief Touched signal type @SINCE_1_0.0 + typedef Signal< void (const TouchData&) > TouchSignalType; ///< Touch signal type @SINCE_1_1.37 + typedef Signal< void (const WheelEvent&) > WheelEventSignalType; ///< Touched signal type @SINCE_1_0.0 + typedef Signal< void () > ContextStatusSignal; ///< Context status signal type @SINCE_1_0.0 + typedef Signal< void () > SceneCreatedSignalType; ///< Scene created signal type @SINCE_1_0.0 static const Vector4 DEFAULT_BACKGROUND_COLOR; ///< Default black background. static const Vector4 DEBUG_BACKGROUND_COLOR; ///< Green background, useful when debugging. @@ -79,19 +82,22 @@ public: * @brief Allows the creation of an empty stage handle. * * To retrieve the current stage, this handle can be set using Stage::GetCurrent(). + * @SINCE_1_0.0 */ Stage(); /** * @brief Get the current Stage. * - * @return The current stage or an empty handle if Core has not been created or has been already destroyed. + * @SINCE_1_0.0 + * @return The current stage or an empty handle if the internal core has not been created or has been already destroyed. */ static Stage GetCurrent(); /** * @brief Query whether the Stage exists; this should only return false during or after destruction of Dali core. * + * @SINCE_1_0.0 * @return True when it's safe to call Stage::GetCurrent(). */ static bool IsInstalled(); @@ -100,12 +106,14 @@ public: * @brief Destructor * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Stage(); /** * @brief This copy constructor is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] handle A reference to the copied handle */ Stage(const Stage& handle); @@ -113,6 +121,7 @@ public: /** * @brief This assignment operator is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] rhs A reference to the copied handle * @return A reference to this */ @@ -124,9 +133,10 @@ public: * @brief Adds a child Actor to the Stage. * * The child will be referenced. + * @SINCE_1_0.0 + * @param [in] actor The child. * @pre The actor has been initialized. * @pre The actor does not have a parent. - * @param [in] actor The child. */ void Add(Actor& actor); @@ -134,8 +144,9 @@ public: * @brief Removes a child Actor from the Stage. * * The child will be unreferenced. - * @pre The actor has been added to the stage. + * @SINCE_1_0.0 * @param [in] actor The child. + * @pre The actor has been added to the stage. */ void Remove(Actor& actor); @@ -145,6 +156,7 @@ public: * The x component will be the width of the Stage in pixels * The y component will be the height of the Stage in pixels * The z component will be the distance between far and near planes + * @SINCE_1_0.0 * @return The size of the Stage as a Vector. */ Vector2 GetSize() const; @@ -154,6 +166,7 @@ public: /** * @brief Retrieve the list of render-tasks. * + * @SINCE_1_0.0 * @return A valid handle to a RenderTaskList. */ RenderTaskList GetRenderTaskList() const; @@ -164,6 +177,7 @@ public: * @brief Query the number of on-stage layers. * * Note that a default layer is always provided (count >= 1). + * @SINCE_1_0.0 * @return The number of layers. */ unsigned int GetLayerCount() const; @@ -171,15 +185,17 @@ public: /** * @brief Retrieve the layer at a specified depth. * - * @pre depth is less than layer count; see GetLayerCount(). + * @SINCE_1_0.0 * @param[in] depth The depth. * @return The layer found at the given depth. + * @pre Depth is less than layer count; see GetLayerCount(). */ Layer GetLayer(unsigned int depth) const; /** * @brief Returns the Stage's Root Layer. * + * @SINCE_1_0.0 * @return The root layer. */ Layer GetRootLayer() const; @@ -189,6 +205,7 @@ public: /** * @brief Set the background color of the stage. * + * @SINCE_1_0.0 * @param[in] color The new background color. */ void SetBackgroundColor(Vector4 color); @@ -196,6 +213,7 @@ public: /** * @brief Retrieve the background color of the stage. * + * @SINCE_1_0.0 * @return The background color. */ Vector4 GetBackgroundColor() const; @@ -203,13 +221,15 @@ public: /** * @brief Retrieve the DPI of the display device to which the stage is connected. * - * @return the horizontal and vertical DPI + * @SINCE_1_0.0 + * @return The horizontal and vertical DPI */ Vector2 GetDpi() const; /** * @brief Get the Object registry. * + * @SINCE_1_0.0 * @return The object registry. */ ObjectRegistry GetObjectRegistry() const; @@ -221,7 +241,8 @@ public: * * By default Dali will stop rendering when no Actor positions are being set, and when no animations are running etc. * This method is useful to force screen refreshes e.g. when updating a NativeImage. - * @param durationSeconds to keep rendering, 0 means render at least one more frame + * @SINCE_1_0.0 + * @param[in] durationSeconds Time to keep rendering, 0 means render at least one more frame */ void KeepRendering( float durationSeconds ); @@ -234,6 +255,7 @@ public: * @code * void YourCallbackName(const KeyEvent& event); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ KeyEventSignalType& KeyEventSignal(); @@ -241,34 +263,56 @@ public: /** * @brief This signal is emitted just after the event processing is finished. * + * @SINCE_1_0.0 * @return The signal to connect to. */ EventProcessingFinishedSignalType& EventProcessingFinishedSignal(); /** + * @DEPRECATED_1_1.37 Use TouchSignal() instead. * @brief This signal is emitted when the screen is touched and when the touch ends * (i.e. the down & up touch events only). * * If there are multiple touch points, then this will be emitted when the first touch occurs and * then when the last finger is lifted. - * An interrupted event will also be emitted. + * An interrupted event will also be emitted (if it occurs). * A callback of the following type may be connected: * @code * void YourCallbackName(const TouchEvent& event); * @endcode * - * @note Motion events are not emitted. + * @SINCE_1_0.0 * @return The touch signal to connect to. + * @note Motion events are not emitted. */ TouchedSignalType& TouchedSignal(); /** + * @brief This signal is emitted when the screen is touched and when the touch ends + * (i.e. the down & up touch events only). + * + * If there are multiple touch points, then this will be emitted when the first touch occurs and + * then when the last finger is lifted. + * An interrupted event will also be emitted (if it occurs). + * A callback of the following type may be connected: + * @code + * void YourCallbackName( TouchData event ); + * @endcode + * + * @SINCE_1_1.37 + * @return The touch signal to connect to. + * @note Motion events are not emitted. + */ + TouchSignalType& TouchSignal(); + + /** * @brief This signal is emitted when wheel event is received. * * A callback of the following type may be connected: * @code * void YourCallbackName(const WheelEvent& event); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ WheelEventSignalType& WheelEventSignal(); @@ -278,7 +322,8 @@ public: * * If the application is responsible for handling context loss, it should listen to * this signal and tear down UI components when recieved. - * @return The ContextLost signal to connect to. + * @SINCE_1_0.0 + * @return The context lost signal to connect to. */ ContextStatusSignal& ContextLostSignal(); @@ -288,18 +333,22 @@ public: * * If the application is responsible for handling context loss, it should listen to * this signal and rebuild UI components on receipt. - * @return The ContextRegained signal to connect to. + * @SINCE_1_0.0 + * @return The context regained signal to connect to. */ ContextStatusSignal& ContextRegainedSignal(); /** - * @brief This signal is emitted after the initial scene is created. It will be triggered after the + * @brief This signal is emitted after the initial scene is created. + * + * It will be triggered after the * application init signal. * * A callback of the following type may be connected: * @code * void YourCallbackName(); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ SceneCreatedSignalType& SceneCreatedSignal(); @@ -307,8 +356,10 @@ public: public: // Not intended for application developers /** - * @brief This constructor is used by Dali GetCurrent() methods. + * @internal + * @brief This constructor is used by Stage::GetCurrent() methods. * + * @SINCE_1_0.0 * @param [in] stage A pointer to a Dali resource */ explicit DALI_INTERNAL Stage(Internal::Stage* stage);