2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Flora License, Version 1.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://floralicense.org/license/
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an AS IS BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FUiScenesSceneManager.h
20 * @brief This is the header file for the %SceneManager class.
22 * This header file contains the declarations of the %SceneManager class.
25 #ifndef _FUI_SCENES_SCENE_MANAGER_H_
26 #define _FUI_SCENES_SCENE_MANAGER_H_
28 #include <FBaseTypes.h>
29 #include <FBaseString.h>
30 #include <FUiAnimAnimationBase.h>
31 #include <FUiScenesTypes.h>
34 namespace Tizen { namespace Ui { namespace Controls
39 namespace Tizen { namespace Base { namespace Collection
42 template<class Type> class IListT;
46 namespace Tizen { namespace Ui { namespace Scenes
50 class ForwardSceneTransition;
51 class BackwardSceneTransition;
54 class ISceneEventListener;
55 class ISceneManagerEventListener;
56 class ISceneAnimationProvider;
57 class ISceneTransitionPolicyProvider;
61 * @brief This class provides methods to manage scenes and scene states.
65 * @final This class is not intended for extension.
67 * The %SceneManager class provides methods to manage scenes and scene states. This class is simplified to a single method call for UI Scene transition that changes the GUI, such as
68 * form to form transition or tab to tab transition. @n
70 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/scene_management.htm">Scene Management</a> and <a href="../org.tizen.native.appprogramming/html/guide/ui/transition_animation.htm">Transition Animations</a>.
72 class _OSP_EXPORT_ SceneManager
73 : public Tizen::Base::Object
77 * Gets the %SceneManager instance.
81 * @return A pointer to the %SceneManager instance if successful, @n
82 * else @c null if it fails
83 * @exception E_SUCCESS The method is successful.
84 * @exception E_OUT_OF_MEMORY The memory is insufficient.
85 * @remarks The specific error code can be accessed using the GetLastResult() method.
87 static SceneManager* GetInstance(void);
90 * Registers a form factory. @n
91 * The IFormFactory::CreateFormN() is called when a new form is required.
95 * @return An error code
96 * @param[in] formFactory The user-defined form factory instance
97 * @exception E_SUCCESS The method is successful.
98 * @see IFormFactory, IFormFactory::CreateFormN()
100 result RegisterFormFactory(const IFormFactory& formFactory);
103 * Registers a panel factory. @n
104 * The IPanelFactory::CreatePanelN() is called when a new panel is required.
108 * @return An error code
109 * @param[in] panelFactory The user-defined panel factory instance
110 * @exception E_SUCCESS The method is successful.
111 * @see IPanelFactory, IPanelFactory::CreatePanelN()
113 result RegisterPanelFactory(const IPanelFactory& panelFactory);
117 * A scene is combination of a form and a panel.
121 * @return An error code
122 * @param[in] sceneId The scene ID
123 * @param[in] formId The form ID string
124 * @param[in] panelId The panel ID string
125 * @exception E_SUCCESS The method is successful.
126 * @exception E_INVALID_ARG A specified input parameter is invalid.
127 * @exception E_OBJ_ALREADY_EXIST The specified @c sceneId already exists.
128 * @exception E_OUT_OF_MEMORY The memory is insufficient.
131 result RegisterScene(const SceneId& sceneId, const Tizen::Base::String& formId, const Tizen::Base::String& panelId);
134 * Registers scene(s) with the specified resource ID.
135 * This method does not remove a scene that is already registered.
139 * @return An error code
140 * @param[in] resourceId The resource ID of the scene(s)
141 * @exception E_SUCCESS The method is successful.
142 * @exception E_OUT_OF_MEMORY The memory is insufficient.
143 * @exception E_FILE_NOT_FOUND The corresponding resource file is not found.
144 * @exception E_OBJ_ALREADY_EXIST A scene ID already exists.
145 * @exception E_SYSTEM A system error has occurred.
146 * @remarks A duplicated scene (scene ID) will not be registered. Also it throws the E_OBJ_ALREADY_EXIST exception.
147 * @see UnregisterScene()
150 result RegisterScene(const Tizen::Base::String& resourceId);
153 * Unregisters the specified scene.
157 * @return An error code
158 * @param[in] sceneId The scene ID
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_INVALID_ARG The specified input parameter is invalid.
161 * @exception E_OBJ_NOT_FOUND The specified @c sceneId does not exist.
162 * @see RegisterScene()
164 result UnregisterScene(const SceneId& sceneId);
167 * Adds a %SceneManager event listener.
171 * @return An error code
172 * @param[in] sceneManagerEventListener An instance of ISceneManagerEventListener to add
173 * @exception E_SUCCESS The method is successful.
174 * @exception E_OUT_OF_MEMORY The memory is insufficient.
175 * @exception E_OBJ_ALREADY_EXIST The listener with the specified type is already added.
176 * @see RemoveSceneManagerEventListener(), ISceneManagerEventListener,
177 * ISceneManagerEventListener::OnSceneTransitionCompleted(),
178 * ISceneManagerEventListener::OnSceneTransitionStarted()
180 result AddSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
183 * Removes a %SceneManager event listener.
187 * @return An error code
188 * @param[in] sceneManagerEventListener An instance of ISceneManagerEventListener to remove
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_OBJ_NOT_FOUND The specified listener is not found.
191 * @see AddSceneManagerEventListener(), ISceneManagerEventListener
193 result RemoveSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
196 * Adds a Scene event listener.
200 * @return An error code
201 * @param[in] sceneId The target scene ID
202 * @param[in] sceneEventListener An instance of ISceneEventListener to add
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_OUT_OF_MEMORY The memory is insufficient.
205 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
206 * @exception E_OBJ_ALREADY_EXIST The listener with the specified type is already added.
207 * @see RemoveSceneEventListener, ISceneEventListener,
208 * ISceneEventListener::OnSceneActivatedN(), ISceneEventListener::OnSceneDeactivated()
210 result AddSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
213 * Removes a Scene event listener.
217 * @return An error code
218 * @param[in] sceneId The target scene ID
219 * @param[in] sceneEventListener An instance of ISceneEventListener to remove
220 * @exception E_SUCCESS The method is successful.
221 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
222 * @exception E_OBJ_NOT_FOUND The specified @c sceneId is not found.
223 * @see AddSceneEventListener, ISceneEventListener
225 result RemoveSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
228 * Sets a Scene animation provider.
232 * @return An error code
233 * @param[in] sceneId The target scene ID
234 * @param[in] pSceneAnimationProvider An instance of ISceneAnimationProvider to set, or null to clear previous one.
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
237 * @exception E_OBJ_NOT_FOUND The specified scene is not found.
238 * @see ISceneAnimationProvider
240 result SetSceneAnimationProvider(const SceneId& sceneId, ISceneAnimationProvider* pSceneAnimationProvider);
243 * Sets a Scene transition policy provider.
247 * @return An error code
248 * @param[in] pSceneTransitionPolicyProvider An instance of ISceneTransitionPolicyProvider to set,
249 * or null to clear previous one.
250 * @exception E_SUCCESS The method is successful.
251 * @see ISceneTransitionPolicyProvider, ISceneTransitionPolicyProvider::GetNextScene(), GoForward()
253 result SetSceneTransitionPolicyProvider(ISceneTransitionPolicyProvider* pSceneTransitionPolicyProvider);
256 * Sets the default values for the individual animation types.
260 * @return An error code
261 * @param[in] animationType The target animation type
262 * @param[in] duration The duration of the animation in milliseconds @n The maximum duration is one second.
263 * @param[in] interpolatorType The type of interpolator used for the intermediate value calculation of the animation
264 * @exception E_SUCCESS The method is successful.
265 * @exception E_INVALID_ARG A specified input parameter is invalid.
266 * @remarks It throws an E_INVALID_ARG exception if the animationType is SCENE_TRANSITION_ANIMATION_TYPE_NONE
267 * or SCENE_TRANSITION_ANIMATION_TYPE_CUSTOM.
268 * @see GoForward(), GoBackward()
270 result SetFormTransitionAnimationDefaultValues(SceneTransitionAnimationType animationType, long duration,
271 Tizen::Ui::Animations::AnimationInterpolatorType interpolatorType);
274 * Requests forward scene transition with the specified scene transition.
278 * @return An error code
279 * @param[in] sceneTransition The scene transition that describes the destination and options
280 * @param[in] pArgs A pointer to an IList that contains the scene transition parameters
281 * @exception E_SUCCESS The method is successful.
282 * @exception E_INVALID_ARG A specified input parameter is invalid.
283 * @exception E_IN_PROGRESS A previous transition is in progress.
284 * @exception E_OUT_OF_MEMORY The memory is insufficient.
285 * @exception E_OBJ_NOT_FOUND The destination scene ID is not found in the registered scenes.
286 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
287 * ISceneTransitionPolicyProvider is not set.
288 * @exception E_SYSTEM A system error has occurred. @n
289 * (Internal logic or failed to create control from a factory).
290 * @remarks To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
291 * also you must register the user-defined ISceneTransitionPolicyProvider and implement the
292 * ISceneTransitionPolicyProvider::GetNextScene() callback method.
294 result GoForward(const ForwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
297 * Requests forward scene transition with the specified transition ID.
301 * @return An error code
302 * @param[in] transitionId The transition ID that describes the destination and options
303 * @param[in] pArgs A pointer to an IList that contains the scene transition parameters
304 * @exception E_SUCCESS The method is successful.
305 * @exception E_INVALID_ARG A specified input parameter is invalid.
306 * @exception E_IN_PROGRESS A previous transition is in progress.
307 * @exception E_OUT_OF_MEMORY The memory is insufficient.
308 * @exception E_OBJ_NOT_FOUND The destination scene ID is not found in the registered scenes.
309 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
310 * ISceneTransitionPolicyProvider is not set.
311 * @exception E_SYSTEM A system error has occurred. @n
312 * (Internal logic or failed to create control from a factory).
313 * @remarks To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
314 * also you must register the user-defined ISceneTransitionPolicyProvider and implement the
315 * ISceneTransitionPolicyProvider::GetNextScene() callback method.
317 result GoForward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
320 * Requests backward scene transition with the specified scene transition.
324 * @return An error code
325 * @param[in] sceneTransition The scene transition that describes the destination and options
326 * @param[in] pArgs A pointer to an IList that contains the scene transition parameters
327 * @exception E_SUCCESS The method is successful.
328 * @exception E_INVALID_ARG A specified input parameter is invalid.
329 * @exception E_IN_PROGRESS A previous transition is in progress.
330 * @exception E_OUT_OF_MEMORY The memory is insufficient.
331 * @exception E_OBJ_NOT_FOUND The scene ID of the previous scene in the internal history is not found in
332 * the current registered scenes.
333 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
334 * ISceneTransitionPolicyProvider is not set.
335 * @exception E_UNDERFLOW The scene history is empty.
336 * @exception E_SYSTEM A system error has occurred. @n
337 * (Internal logic or failed to create control from a factory).
338 * @remarks An item removed from the internal history except the E_SYSTEM exception case. @n
339 * For non-adjacent backward transition, the current scene and the scenes between the current scene and
340 * the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
341 * If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
343 result GoBackward(const BackwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
346 * Requests backward scene transition with the specified transition ID.
350 * @return An error code
351 * @param[in] transitionId The transition ID that describes the destination and options
352 * @param[in] pArgs A pointer to an IList that contains the scene transition parameters
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_INVALID_ARG A specified input parameter is invalid.
355 * @exception E_IN_PROGRESS A previous transition is in progress.
356 * @exception E_OUT_OF_MEMORY The memory is insufficient.
357 * @exception E_OBJ_NOT_FOUND The scene ID of the previous scene in the internal history is not found in
358 * the current registered scenes.
359 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
360 * ISceneTransitionPolicyProvider is not set.
361 * @exception E_UNDERFLOW The scene history is empty.
362 * @exception E_SYSTEM A system error has occurred. @n
363 * (Internal logic or failed to create control from a factory).
364 * @remarks An item removed from the internal history except the E_SYSTEM exception case. @n
365 * For non-adjacent backward transition, the current scene and the scenes between the current scene and
366 * the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
367 * If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
369 result GoBackward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
372 * Gets a pointer to the current Scene instance.
376 * @return A pointer to the current Scene instance
377 * @see GetCurrentSceneId()
379 Scene* GetCurrentScene(void) const;
382 * Gets the current scene ID string.
386 * @return The scene ID
387 * @see GetCurrentScene()
389 SceneId GetCurrentSceneId(void) const;
392 * Checks whether the Scene instance with the specified sceneId has been destroyed or not.
396 * @return @c true if the scene instance has not been destroyed, @n
398 * @param[in] sceneId The scene ID
399 * @remarks This function is useful to check state of the scene, because the scene lifetime is determined
400 * by scene transition option and user can destroy the scene in real time.
402 bool IsSceneAlive(const SceneId& sceneId) const;
405 * Destroys the specified scene.
409 * @return An error code
410 * @param[in] sceneId The scene ID
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_INVALID_ARG The current scene cannot be destroyed.
413 * @exception E_OBJ_NOT_FOUND The specified @c sceneId does not exist.
414 * @exception E_SYSTEM A system error has occurred.
416 result DestroyScene(const SceneId& sceneId);
419 * Brings the current scene to the topmost to get back the control of scene management.
423 * @return An error code
424 * @exception E_SUCCESS The method is successful.
425 * @exception E_OPERATION_FAILED The current scene is invalid.
426 * @exception E_SYSTEM A system error has occurred.
427 * @remarks If a user sets a form as a current form on a frame by calling SetCurrentForm(),
428 * they will no longer be under the control of %SceneManager. In this case,
429 * they can get back the control of scene management easily by calling this method.
430 * @see Tizen::Ui::Controls::Frame::SetCurrentForm
432 result BringCurrentSceneToTop(void);
435 * Clears the scene history.
439 * @return An error code
440 * @exception E_SUCCESS The method is successful.
441 * @see AddSceneHistory()
443 result ClearSceneHistory(void);
446 * Adds the scene to the scene history.
450 * @return An error code
451 * @param[in] sceneId The scene ID
452 * @exception E_SUCCESS The method is successful.
453 * @exception E_INVALID_ARG The specified input parameter is invalid.
454 * @exception E_OBJ_NOT_FOUND The specified @c sceneId is not found in the registered scenes.
455 * @exception E_OUT_OF_MEMORY The memory is insufficient.
456 * @see ClearSceneHistory()
458 result AddToSceneHistory(const SceneId& sceneId);
461 * Gets the scene history list.
465 * @return A pointer to the list that contains the scene history
466 * @exception E_SUCCESS The method is successful.
467 * @exception E_OUT_OF_MEMORY The memory is insufficient.
468 * @remarks The specific error code can be accessed using the GetLastResult() method.
470 Tizen::Base::Collection::IListT<SceneId>* GetSceneHistoryN(void) const;
474 * This default constructor is intentionally declared as private to implement the Singleton semantic.
481 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
485 SceneManager(const SceneManager& rhs);
488 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
492 SceneManager& operator =(const SceneManager& rhs);
495 * This destructor is intentionally declared as private to implement the Singleton semantic.
499 virtual ~SceneManager(void);
502 * Initializes the instance of the this class.
506 * @return An error code.
507 * @exception E_SUCCESS The method is successful.
508 * @exception E_SYSTEM A system error has occurred.
509 * @exception E_OUT_OF_MEMORY The memory is insufficient.
512 result Construct(void);
514 static void InitSingleton(void);
515 static void DestroySingleton(void);
518 friend class _SceneManagerImpl;
519 class _SceneManagerImpl* __pSceneManagerImpl;
520 static SceneManager* __pSceneManagerInstance;
523 } } } // Tizen::Ui::Scenes
525 #endif //_FUI_SCENES_SCENE_MANAGER_H_