5 * Copyright (c) 2020 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 <cstdint> // uint32_t
25 #include <dali/public-api/object/base-handle.h>
26 #include <dali/public-api/signals/dali-signal.h>
31 * @addtogroup dali_core_common
35 namespace Internal DALI_INTERNAL
52 * @brief The Stage is a top-level object used for displaying a tree of Actors.
54 * Stage is a top-level object that represents the entire screen.
55 * It is used for displaying a hierarchy of actors managed by the scene graph structure,
56 * which means an actor inherits a position relative to its parent,
57 * and can be moved in relation to this point.
59 * The stage instance is a singleton object (the only instance of its class during the
60 * lifetime of the program). You can get it using a static function.
62 * To display the contents of an actor, it must be added to a stage.
63 * The following example shows how to connect a new actor to the stage:
65 * Actor actor = Actor::New();
66 * Stage::GetCurrent().Add( actor );
69 * The stage has a 2D size that matches the size of the application window.
70 * The default unit 1 is 1 pixel with the default camera.
72 * Multiple stage/window support is not currently provided.
75 * | %Signal Name | Method |
76 * |-------------------------|--------------------------------------|
77 * | keyEvent | @ref KeyEventSignal() |
78 * | eventProcessingFinished | @ref EventProcessingFinishedSignal() |
79 * | touched | @ref TouchedSignal() |
80 * | wheelEvent | @ref WheelEventSignal() |
81 * | contextLost | @ref ContextLostSignal() |
82 * | contextRegained | @ref ContextRegainedSignal() |
83 * | sceneCreated | @ref SceneCreatedSignal() |
85 class DALI_CORE_API Stage : public BaseHandle
88 using KeyEventSignalType = Signal<void( const KeyEvent& )>; ///< Key event signal type
89 using EventProcessingFinishedSignalType = Signal<void()>; ///< Event Processing finished signal type
90 using TouchEventSignalType = Signal<void( const TouchEvent& )>; ///< Touch signal type
91 using WheelEventSignalType = Signal<void( const WheelEvent& )>; ///< Wheel signal type
92 using ContextStatusSignal = Signal<void()>; ///< Context status signal type
93 using SceneCreatedSignalType = Signal<void()>; ///< Scene created signal type
96 * @brief Allows the creation of an empty stage handle.
98 * To retrieve the current stage, this handle can be set using Stage::GetCurrent().
103 * @brief Gets the current Stage.
105 * @return The current stage or an empty handle if the internal core has not been created or has been already destroyed
107 static Stage GetCurrent();
110 * @brief Queries whether the Stage exists; this should only return false during or after destruction of Dali core.
112 * @return True when it's safe to call Stage::GetCurrent()
114 static bool IsInstalled();
119 * This is non-virtual since derived Handle types must not contain data or virtual methods.
124 * @brief This copy constructor is required for (smart) pointer semantics.
126 * @param[in] handle A reference to the copied handle
128 Stage(const Stage& handle);
131 * @brief This assignment operator is required for (smart) pointer semantics.
133 * @param[in] rhs A reference to the copied handle
134 * @return A reference to this
136 Stage& operator=(const Stage& rhs);
141 * @brief Adds a child Actor to the Stage.
143 * The child will be referenced.
144 * @param[in] actor The child
145 * @pre The actor has been initialized.
146 * @pre The actor does not have a parent.
148 void Add(Actor& actor);
151 * @brief Removes a child Actor from the Stage.
153 * The child will be unreferenced.
154 * @param[in] actor The child
155 * @pre The actor has been added to the stage.
157 void Remove(Actor& actor);
160 * @brief Returns the size of the Stage in pixels as a Vector.
162 * The x component will be the width of the Stage in pixels.
163 * The y component will be the height of the Stage in pixels.
164 * The z component will be the distance between far and near planes.
165 * @return The size of the Stage as a Vector
167 Vector2 GetSize() const;
172 * @brief Retrieves the list of render-tasks.
174 * @return A valid handle to a RenderTaskList
176 RenderTaskList GetRenderTaskList() const;
181 * @brief Queries the number of on-stage layers.
183 * Note that a default layer is always provided (count >= 1).
184 * @return The number of layers
186 uint32_t GetLayerCount() const;
189 * @brief Retrieves the layer at a specified depth.
191 * @param[in] depth The depth
192 * @return The layer found at the given depth
193 * @pre Depth is less than layer count; see GetLayerCount().
195 Layer GetLayer(uint32_t depth) const;
198 * @brief Returns the Stage's Root Layer.
200 * @return The root layer
202 Layer GetRootLayer() const;
207 * @brief Sets the background color of the stage.
209 * @param[in] color The new background color
211 void SetBackgroundColor(Vector4 color);
214 * @brief Retrieves the background color of the stage.
216 * @return The background color
218 Vector4 GetBackgroundColor() const;
221 * @brief Retrieves the DPI of the display device to which the stage is connected.
223 * @return The horizontal and vertical DPI
225 Vector2 GetDpi() const;
228 * @brief Gets the Object registry.
230 * @return The object registry
232 ObjectRegistry GetObjectRegistry() const;
237 * @brief Keep rendering for at least the given amount of time.
239 * By default, Dali will stop rendering when no Actor positions are being set, and when no animations are running etc.
240 * This method is useful to force screen refreshes e.g. when updating a NativeImage.
241 * @param[in] durationSeconds Time to keep rendering, 0 means render at least one more frame
243 void KeepRendering( float durationSeconds );
248 * @brief This signal is emitted when key event is received.
250 * A callback of the following type may be connected:
252 * void YourCallbackName(const KeyEvent& event);
254 * @return The signal to connect to
256 KeyEventSignalType& KeyEventSignal();
259 * @brief This signal is emitted just after the event processing is finished.
261 * @return The signal to connect to
263 EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
266 * @brief This signal is emitted when the screen is touched and when the touch ends
267 * (i.e. the down & up touch events only).
269 * If there are multiple touch points, then this will be emitted when the first touch occurs and
270 * then when the last finger is lifted.
271 * An interrupted event will also be emitted (if it occurs).
272 * A callback of the following type may be connected:
274 * void YourCallbackName( TouchEvent event );
277 * @return The touch signal to connect to
278 * @note Motion events are not emitted.
280 TouchEventSignalType& TouchedSignal();
283 * @brief This signal is emitted when wheel event is received.
285 * A callback of the following type may be connected:
287 * void YourCallbackName(const WheelEvent& event);
289 * @return The signal to connect to
291 WheelEventSignalType& WheelEventSignal();
294 * @brief This signal is emitted when the GL context is lost (Platform specific behaviour).
296 * If the application is responsible for handling context loss, it should listen to
297 * this signal and tear down UI components when received.
298 * @return The context lost signal to connect to
300 ContextStatusSignal& ContextLostSignal();
303 * @brief This signal is emitted when the GL context is regained (Platform specific
306 * If the application is responsible for handling context loss, it should listen to
307 * this signal and rebuild UI components on receipt.
308 * @return The context regained signal to connect to
310 ContextStatusSignal& ContextRegainedSignal();
313 * @brief This signal is emitted after the initial scene is created.
315 * It will be triggered after the
316 * application init signal.
318 * A callback of the following type may be connected:
320 * void YourCallbackName();
322 * @return The signal to connect to
324 SceneCreatedSignalType& SceneCreatedSignal();
326 public: // Not intended for application developers
330 * @brief This constructor is used by Stage::GetCurrent() methods.
332 * @param[in] stage A pointer to a Dali resource
334 explicit DALI_INTERNAL Stage(Internal::Stage* stage);
344 #endif // DALI_STAGE_H