1 #ifndef __DALI_STAGE_H__
2 #define __DALI_STAGE_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/object/base-handle.h>
23 #include <dali/public-api/signals/dali-signal.h>
28 * @addtogroup dali-core-common
32 namespace Internal DALI_INTERNAL
49 * @brief The Stage is a top-level object used for displaying a tree of Actors.
51 * Multiple stage/window support is not currently provided.
54 * | %Signal Name | Method |
55 * |---------------------------|--------------------------------------|
56 * | key-event | @ref KeyEventSignal() |
57 * | event-processing-finished | @ref EventProcessingFinishedSignal() |
58 * | touched | @ref TouchedSignal() |
59 * | wheel-event | @ref WheelEventSignal() |
60 * | context-lost | @ref ContextLostSignal() |
61 * | context-regained | @ref ContextRegainedSignal() |
62 * | scene-created | @ref SceneCreatedSignal() |
64 class DALI_IMPORT_API Stage : public BaseHandle
68 typedef Signal< void (const KeyEvent&)> KeyEventSignalType; ///< Key event signal type
69 typedef Signal< void () > EventProcessingFinishedSignalType; ///< Event Processing finished signal type
70 typedef Signal< void (const TouchEvent&)> TouchedSignalType; ///< Touched signal type
71 typedef Signal< void (const WheelEvent&)> WheelEventSignalType; ///< Touched signal type
72 typedef Signal< void () > ContextStatusSignal; ///< Context status signal type
73 typedef Signal< void () > SceneCreatedSignalType; ///< Scene created signal type
75 static const Vector4 DEFAULT_BACKGROUND_COLOR; ///< Default black background.
76 static const Vector4 DEBUG_BACKGROUND_COLOR; ///< Green background, useful when debugging.
79 * @brief Allows the creation of an empty stage handle.
81 * To retrieve the current stage, this handle can be set using Stage::GetCurrent().
86 * @brief Get the current Stage.
88 * @return The current stage or an empty handle if Core has not been created or has been already destroyed.
90 static Stage GetCurrent();
93 * @brief Query whether the Stage exists; this should only return false during or after destruction of Dali core.
95 * @return True when it's safe to call Stage::GetCurrent().
97 static bool IsInstalled();
102 * This is non-virtual since derived Handle types must not contain data or virtual methods.
107 * @brief This copy constructor is required for (smart) pointer semantics.
109 * @param [in] handle A reference to the copied handle
111 Stage(const Stage& handle);
114 * @brief This assignment operator is required for (smart) pointer semantics.
116 * @param [in] rhs A reference to the copied handle
117 * @return A reference to this
119 Stage& operator=(const Stage& rhs);
124 * @brief Adds a child Actor to the Stage.
126 * The child will be referenced.
127 * @pre The actor has been initialized.
128 * @pre The actor does not have a parent.
129 * @param [in] actor The child.
131 void Add(Actor& actor);
134 * @brief Removes a child Actor from the Stage.
136 * The child will be unreferenced.
137 * @pre The actor has been added to the stage.
138 * @param [in] actor The child.
140 void Remove(Actor& actor);
143 * @brief Returns the size of the Stage in pixels as a Vector.
145 * The x component will be the width of the Stage in pixels
146 * The y component will be the height of the Stage in pixels
147 * The z component will be the distance between far and near planes
148 * @return The size of the Stage as a Vector.
150 Vector2 GetSize() const;
155 * @brief Retrieve the list of render-tasks.
157 * @return A valid handle to a RenderTaskList.
159 RenderTaskList GetRenderTaskList() const;
164 * @brief Query the number of on-stage layers.
166 * Note that a default layer is always provided (count >= 1).
167 * @return The number of layers.
169 unsigned int GetLayerCount() const;
172 * @brief Retrieve the layer at a specified depth.
174 * @pre depth is less than layer count; see GetLayerCount().
175 * @param[in] depth The depth.
176 * @return The layer found at the given depth.
178 Layer GetLayer(unsigned int depth) const;
181 * @brief Returns the Stage's Root Layer.
183 * @return The root layer.
185 Layer GetRootLayer() const;
190 * @brief Set the background color of the stage.
192 * @param[in] color The new background color.
194 void SetBackgroundColor(Vector4 color);
197 * @brief Retrieve the background color of the stage.
199 * @return The background color.
201 Vector4 GetBackgroundColor() const;
204 * @brief Retrieve the DPI of the display device to which the stage is connected.
206 * @return the horizontal and vertical DPI
208 Vector2 GetDpi() const;
211 * @brief Get the Object registry.
213 * @return The object registry.
215 ObjectRegistry GetObjectRegistry() const;
220 * @brief Keep rendering for at least the given amount of time.
222 * By default Dali will stop rendering when no Actor positions are being set, and when no animations are running etc.
223 * This method is useful to force screen refreshes e.g. when updating a NativeImage.
224 * @param durationSeconds to keep rendering, 0 means render at least one more frame
226 void KeepRendering( float durationSeconds );
231 * @brief This signal is emitted when key event is received.
233 * A callback of the following type may be connected:
235 * void YourCallbackName(const KeyEvent& event);
237 * @return The signal to connect to.
239 KeyEventSignalType& KeyEventSignal();
242 * @brief This signal is emitted just after the event processing is finished.
244 * @return The signal to connect to.
246 EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
249 * @brief This signal is emitted when the screen is touched and when the touch ends
250 * (i.e. the down & up touch events only).
252 * If there are multiple touch points, then this will be emitted when the first touch occurs and
253 * then when the last finger is lifted.
254 * An interrupted event will also be emitted.
255 * A callback of the following type may be connected:
257 * void YourCallbackName(const TouchEvent& event);
260 * @note Motion events are not emitted.
261 * @return The touch signal to connect to.
263 TouchedSignalType& TouchedSignal();
266 * @brief This signal is emitted when wheel event is received.
268 * A callback of the following type may be connected:
270 * void YourCallbackName(const WheelEvent& event);
272 * @return The signal to connect to.
274 WheelEventSignalType& WheelEventSignal();
277 * @brief This signal is emitted when the GL context is lost (Platform specific behaviour).
279 * If the application is responsible for handling context loss, it should listen to
280 * this signal and tear down UI components when recieved.
281 * @return The ContextLost signal to connect to.
283 ContextStatusSignal& ContextLostSignal();
286 * @brief This signal is emitted when the GL context is regained (Platform specific
289 * If the application is responsible for handling context loss, it should listen to
290 * this signal and rebuild UI components on receipt.
291 * @return The ContextRegained signal to connect to.
293 ContextStatusSignal& ContextRegainedSignal();
296 * @brief This signal is emitted after the initial scene is created. It will be triggered after the
297 * application init signal.
299 * A callback of the following type may be connected:
301 * void YourCallbackName();
303 * @return The signal to connect to.
305 SceneCreatedSignalType& SceneCreatedSignal();
307 public: // Not intended for application developers
310 * @brief This constructor is used by Dali GetCurrent() methods.
312 * @param [in] stage A pointer to a Dali resource
314 explicit DALI_INTERNAL Stage(Internal::Stage* stage);
323 #endif // __DALI_STAGE_H__