2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
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() method 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.
99 result RegisterFormFactory(const IFormFactory& formFactory);
102 * Registers a panel factory. @n
103 * The IPanelFactory::CreatePanelN() method is called when a new panel is required.
107 * @return An error code
108 * @param[in] panelFactory The user-defined panel factory instance
109 * @exception E_SUCCESS The method is successful.
111 result RegisterPanelFactory(const IPanelFactory& panelFactory);
115 * A scene is combination of a form and a panel.
119 * @return An error code
120 * @param[in] sceneId The scene ID
121 * @param[in] formId The form ID string
122 * @param[in] panelId The panel ID string
123 * @exception E_SUCCESS The method is successful.
124 * @exception E_INVALID_ARG A specified input parameter is invalid.
125 * @exception E_OBJ_ALREADY_EXIST The specified @c sceneId already exists.
126 * @exception E_OUT_OF_MEMORY The memory is insufficient.
129 result RegisterScene(const SceneId& sceneId, const Tizen::Base::String& formId, const Tizen::Base::String& panelId);
132 * Registers scene(s) with the specified resource ID.
133 * The %RegisterScene() method does not remove a scene that is already registered.
137 * @return An error code
138 * @param[in] resourceId The resource ID of the scene(s) @n
139 * A duplicated scene (scene ID) will not be registered.
140 * @exception E_SUCCESS The method is successful.
141 * @exception E_OUT_OF_MEMORY The memory is insufficient.
142 * @exception E_FILE_NOT_FOUND The corresponding resource file is not found.
143 * @exception E_OBJ_ALREADY_EXIST A scene ID already exists.
144 * @exception E_SYSTEM A system error has occurred.
145 * @see UnregisterScene()
148 result RegisterScene(const Tizen::Base::String& resourceId);
151 * Unregisters the specified scene.
155 * @return An error code
156 * @param[in] sceneId The scene ID
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_INVALID_ARG The specified input parameter is invalid.
159 * @exception E_OBJ_NOT_FOUND The specified @c sceneId does not exist.
160 * @see RegisterScene()
162 result UnregisterScene(const SceneId& sceneId);
165 * Adds a %SceneManager event listener.
169 * @return An error code
170 * @param[in] sceneManagerEventListener An instance of ISceneManagerEventListener to add
171 * @exception E_SUCCESS The method is successful.
172 * @exception E_OUT_OF_MEMORY The memory is insufficient.
173 * @exception E_OBJ_ALREADY_EXIST The listener with the specified type is already added.
174 * @see RemoveSceneManagerEventListener()
175 * @see ISceneManagerEventListener::OnSceneTransitionCompleted()
176 * @see ISceneManagerEventListener::OnSceneTransitionStarted()
178 result AddSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
181 * Removes a %SceneManager event listener.
185 * @return An error code
186 * @param[in] sceneManagerEventListener An instance of ISceneManagerEventListener to remove
187 * @exception E_SUCCESS The method is successful.
188 * @exception E_OBJ_NOT_FOUND The specified listener is not found.
189 * @see AddSceneManagerEventListener()
191 result RemoveSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
194 * Adds a Scene event listener.
198 * @return An error code
199 * @param[in] sceneId The target scene ID
200 * @param[in] sceneEventListener An instance of ISceneEventListener to add
201 * @exception E_SUCCESS The method is successful.
202 * @exception E_OUT_OF_MEMORY The memory is insufficient.
203 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
204 * @exception E_OBJ_ALREADY_EXIST The listener with the specified type is already added.
205 * @see RemoveSceneEventListener()
206 * @see ISceneEventListener::OnSceneActivatedN()
207 * @see ISceneEventListener::OnSceneDeactivated()
209 result AddSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
212 * Removes a Scene event listener.
216 * @return An error code
217 * @param[in] sceneId The target scene ID
218 * @param[in] sceneEventListener An instance of ISceneEventListener to remove
219 * @exception E_SUCCESS The method is successful.
220 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
221 * @exception E_OBJ_NOT_FOUND The specified @c sceneId is not found.
222 * @see AddSceneEventListener()
224 result RemoveSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
227 * Sets a Scene animation provider.
231 * @return An error code
232 * @param[in] sceneId The target scene ID
233 * @param[in] pSceneAnimationProvider An instance of ISceneAnimationProvider to set, @n else @c null to clear previous one
234 * @exception E_SUCCESS The method is successful.
235 * @exception E_INVALID_ARG The specified @c sceneId is invalid.
236 * @exception E_OBJ_NOT_FOUND The specified scene is not found.
238 result SetSceneAnimationProvider(const SceneId& sceneId, ISceneAnimationProvider* pSceneAnimationProvider);
241 * Sets a Scene transition policy provider.
245 * @return An error code
246 * @param[in] pSceneTransitionPolicyProvider An instance of ISceneTransitionPolicyProvider to set, @n
247 * else @c null to clear previous one
248 * @exception E_SUCCESS The method is successful.
249 * @see ISceneTransitionPolicyProvider::GetNextScene()
252 result SetSceneTransitionPolicyProvider(ISceneTransitionPolicyProvider* pSceneTransitionPolicyProvider);
255 * Sets the default values for the individual animation types.
259 * @return An error code
260 * @param[in] animationType The target animation type
261 * @param[in] duration The duration of the animation in milliseconds @n The maximum duration is one second.
262 * @param[in] interpolatorType The type of interpolator used for the intermediate value calculation of the animation
263 * @exception E_SUCCESS The method is successful.
264 * @exception E_INVALID_ARG The specified @c animationType is either @c SCENE_TRANSITION_ANIMATION_TYPE_NONE or
265 * @c SCENE_TRANSITION_ANIMATION_TYPE_CUSTOM.
269 result SetFormTransitionAnimationDefaultValues(SceneTransitionAnimationType animationType, long duration,
270 Tizen::Ui::Animations::AnimationInterpolatorType interpolatorType);
273 * Requests forward scene transition with the specified scene transition.
277 * @return An error code
278 * @param[in] sceneTransition The scene transition that describes the destination and options
279 * @param[in] pArgs A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
280 * @exception E_SUCCESS The method is successful.
281 * @exception E_INVALID_ARG A specified input parameter is invalid.
282 * @exception E_IN_PROGRESS A previous transition is in progress.
283 * @exception E_OUT_OF_MEMORY The memory is insufficient.
284 * @exception E_OBJ_NOT_FOUND The destination scene ID is not found in the registered scenes.
285 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
286 * ISceneTransitionPolicyProvider is not set.
287 * @exception E_SYSTEM A system error has occurred. @n
288 * (Internal logic or failed to create control from a factory).
289 * @remarks To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
290 * also you must register the user-defined ISceneTransitionPolicyProvider and implement the
291 * ISceneTransitionPolicyProvider::GetNextScene() callback method.
293 result GoForward(const ForwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
296 * Requests forward scene transition with the specified transition ID.
300 * @return An error code
301 * @param[in] transitionId The transition ID that describes the destination and options
302 * @param[in] pArgs A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
303 * @exception E_SUCCESS The method is successful.
304 * @exception E_INVALID_ARG A specified input parameter is invalid.
305 * @exception E_IN_PROGRESS A previous transition is in progress.
306 * @exception E_OUT_OF_MEMORY The memory is insufficient.
307 * @exception E_OBJ_NOT_FOUND The destination scene ID is not found in the registered scenes.
308 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
309 * ISceneTransitionPolicyProvider is not set.
310 * @exception E_SYSTEM A system error has occurred. @n
311 * (Internal logic or failed to create control from a factory).
312 * @remarks To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
313 * also you must register the user-defined ISceneTransitionPolicyProvider and implement the
314 * ISceneTransitionPolicyProvider::GetNextScene() callback method.
316 result GoForward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
319 * Requests backward scene transition with the specified scene transition.
323 * @return An error code
324 * @param[in] sceneTransition The scene transition that describes the destination and options
325 * @param[in] pArgs A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG A specified input parameter is invalid.
328 * @exception E_IN_PROGRESS A previous transition is in progress.
329 * @exception E_OUT_OF_MEMORY The memory is insufficient.
330 * @exception E_OBJ_NOT_FOUND The scene ID of the previous scene in the internal history is not found in
331 * the current registered scenes.
332 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
333 * ISceneTransitionPolicyProvider is not set.
334 * @exception E_UNDERFLOW The scene history is empty.
335 * @exception E_SYSTEM A system error has occurred. @n
336 * (Internal logic or failed to create control from a factory).
337 * @remarks An item removed from the internal history except the E_SYSTEM exception case. @n
338 * For non-adjacent backward transition, the current scene and the scenes between the current scene and
339 * the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
340 * If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
342 result GoBackward(const BackwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
345 * Requests backward scene transition with the specified transition ID.
349 * @return An error code
350 * @param[in] transitionId The transition ID that describes the destination and options
351 * @param[in] pArgs A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
352 * @exception E_SUCCESS The method is successful.
353 * @exception E_INVALID_ARG A specified input parameter is invalid.
354 * @exception E_IN_PROGRESS A previous transition is in progress.
355 * @exception E_OUT_OF_MEMORY The memory is insufficient.
356 * @exception E_OBJ_NOT_FOUND The scene ID of the previous scene in the internal history is not found in
357 * the current registered scenes.
358 * @exception E_INVALID_STATE The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
359 * ISceneTransitionPolicyProvider is not set.
360 * @exception E_UNDERFLOW The scene history is empty.
361 * @exception E_SYSTEM A system error has occurred. @n
362 * (Internal logic or failed to create control from a factory).
363 * @remarks An item removed from the internal history except the E_SYSTEM exception case. @n
364 * For non-adjacent backward transition, the current scene and the scenes between the current scene and
365 * the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
366 * If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
368 result GoBackward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
371 * Gets a pointer to the current Scene instance.
375 * @return A pointer to the current Scene instance
376 * @see GetCurrentSceneId()
378 Scene* GetCurrentScene(void) const;
381 * Gets the current scene ID string.
385 * @return The scene ID
386 * @see GetCurrentScene()
388 SceneId GetCurrentSceneId(void) const;
391 * Checks whether the Scene instance with the specified sceneId has been destroyed or not.
395 * @return @c true if the scene instance has not been destroyed, @n
397 * @param[in] sceneId The scene ID
398 * @remarks This method is useful to check state of the scene, because the scene lifetime is determined
399 * by scene transition option and user can destroy the scene in real time.
401 bool IsSceneAlive(const SceneId& sceneId) const;
404 * Destroys the specified scene.
408 * @return An error code
409 * @param[in] sceneId The scene ID
410 * @exception E_SUCCESS The method is successful.
411 * @exception E_INVALID_ARG The current scene cannot be destroyed.
412 * @exception E_OBJ_NOT_FOUND The specified @c sceneId does not exist.
413 * @exception E_SYSTEM A system error has occurred.
415 result DestroyScene(const SceneId& sceneId);
418 * Brings the current scene to the topmost to get back the control of scene management.
422 * @return An error code
423 * @exception E_SUCCESS The method is successful.
424 * @exception E_OPERATION_FAILED The current scene is invalid.
425 * @exception E_SYSTEM A system error has occurred.
426 * @remarks If a user sets a form as a current form on a frame by calling Tizen::Ui::Controls::Frame::SetCurrentForm(),
427 * they will no longer be under the control of %SceneManager. In this case,
428 * they can get back the control of scene management easily by calling this method.
430 result BringCurrentSceneToTop(void);
433 * Clears the scene history.
437 * @return An error code
438 * @exception E_SUCCESS The method is successful.
439 * @see AddToSceneHistory()
441 result ClearSceneHistory(void);
444 * Adds the scene to the scene history.
448 * @return An error code
449 * @param[in] sceneId The scene ID
450 * @exception E_SUCCESS The method is successful.
451 * @exception E_INVALID_ARG The specified input parameter is invalid.
452 * @exception E_OBJ_NOT_FOUND The specified @c sceneId is not found in the registered scenes.
453 * @exception E_OUT_OF_MEMORY The memory is insufficient.
454 * @see ClearSceneHistory()
456 result AddToSceneHistory(const SceneId& sceneId);
459 * Gets the scene history list.
463 * @return A pointer to the list that contains the scene history
464 * @exception E_SUCCESS The method is successful.
465 * @exception E_OUT_OF_MEMORY The memory is insufficient.
466 * @remarks The specific error code can be accessed using the GetLastResult() method.
468 Tizen::Base::Collection::IListT<SceneId>* GetSceneHistoryN(void) const;
472 * This default constructor is intentionally declared as private to implement the Singleton semantic.
479 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
483 SceneManager(const SceneManager& rhs);
486 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
490 SceneManager& operator =(const SceneManager& rhs);
493 * This destructor is intentionally declared as private to implement the Singleton semantic.
497 virtual ~SceneManager(void);
500 * Initializes the instance of the this class.
504 * @return An error code.
505 * @exception E_SUCCESS The method is successful.
506 * @exception E_SYSTEM A system error has occurred.
507 * @exception E_OUT_OF_MEMORY The memory is insufficient.
510 result Construct(void);
512 static void InitSingleton(void);
513 static void DestroySingleton(void);
516 friend class _SceneManagerImpl;
517 class _SceneManagerImpl* __pSceneManagerImpl;
518 static SceneManager* __pSceneManagerInstance;
521 } } } // Tizen::Ui::Scenes
523 #endif //_FUI_SCENES_SCENE_MANAGER_H_