inc/FUiScenesSceneManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FUiScenesSceneManager.h
  20  * @brief       This is the header file for the %SceneManager class.
  21  *
  22  * This header file contains the declarations of the %SceneManager class.
  23  */
  24
  25 #ifndef _FUI_SCENES_SCENE_MANAGER_H_
  26 #define _FUI_SCENES_SCENE_MANAGER_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FUiAnimAnimationBase.h>
  31 #include <FUiScenesTypes.h>
  32
  33
  34 namespace Tizen { namespace Ui { namespace Controls
  35 {
  36 class Form;
  37 class Panel;
  38 }}}
  39 namespace Tizen { namespace Base { namespace Collection
  40 {
  41 class IList;
  42 template<class Type> class IListT;
  43 }}}
  44
  45
  46 namespace Tizen { namespace Ui { namespace Scenes
  47 {
  48
  49 class Scene;
  50 class ForwardSceneTransition;
  51 class BackwardSceneTransition;
  52 class IFormFactory;
  53 class IPanelFactory;
  54 class ISceneEventListener;
  55 class ISceneManagerEventListener;
  56 class ISceneAnimationProvider;
  57 class ISceneTransitionPolicyProvider;
  58
  59 /**
  60  * @class       SceneManager
  61  * @brief       This class provides methods to manage scenes and scene states.
  62  *
  63  * @since       2.0
  64  *
  65  * @final       This class is not intended for extension.
  66  *
  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
  69  *
  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>.
  71  */
  72 class _OSP_EXPORT_ SceneManager
  73         : public Tizen::Base::Object
  74 {
  75 public:
  76         /**
  77          * Gets the %SceneManager instance.
  78          *
  79          * @since       2.0
  80          *
  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.
  86          */
  87         static SceneManager* GetInstance(void);
  88
  89         /**
  90          * Registers a form factory. @n
  91          * The IFormFactory::CreateFormN() method is called when a new form is required.
  92          *
  93          * @since       2.0
  94          *
  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
  99          * @see                 IFormFactory::CreateFormN()
 100          */
 101         result RegisterFormFactory(const IFormFactory& formFactory);
 102
 103         /**
 104          * Registers a panel factory. @n
 105          * The IPanelFactory::CreatePanelN() method is called when a new panel is required.
 106          *
 107          * @since       2.0
 108          *
 109          * @return              An error code
 110          * @param[in]   panelFactory            The user-defined panel factory instance
 111          * @exception   E_SUCCESS                       The method is successful.
 112          * @see                 IPanelFactory
 113          * @see                 IPanelFactory::CreatePanelN()
 114          */
 115         result RegisterPanelFactory(const IPanelFactory& panelFactory);
 116
 117         /**
 118          * Registers a scene.
 119          * A scene is combination of a form and a panel.
 120          *
 121          * @since       2.0
 122          *
 123          * @return              An error code
 124          * @param[in]   sceneId                         The scene ID
 125          * @param[in]   formId                          The form ID string
 126          * @param[in]   panelId                         The panel ID string
 127          * @exception   E_SUCCESS                       The method is successful.
 128          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 129          * @exception   E_OBJ_ALREADY_EXIST     The specified @c sceneId already exists.
 130          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 131          *
 132          */
 133         result RegisterScene(const SceneId& sceneId, const Tizen::Base::String& formId, const Tizen::Base::String& panelId);
 134
 135         /**
 136          * Registers scene(s) with the specified resource ID.
 137          * The %RegisterScene() method does not remove a scene that is already registered.
 138          *
 139          * @since       2.0
 140          *
 141          * @return              An error code
 142          * @param[in]   resourceId                      The resource ID of the scene(s)
 143          * @exception   E_SUCCESS                       The method is successful.
 144          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 145          * @exception   E_FILE_NOT_FOUND        The corresponding resource file is not found.
 146          * @exception   E_OBJ_ALREADY_EXIST     A scene ID already exists.
 147          * @exception   E_SYSTEM                        A system error has occurred.
 148          * @remarks             A duplicated scene (scene ID) will not be registered. Also it throws the E_OBJ_ALREADY_EXIST exception.
 149          * @see                 UnregisterScene()
 150          *
 151          */
 152         result RegisterScene(const Tizen::Base::String& resourceId);
 153
 154         /**
 155          * Unregisters the specified scene.
 156          *
 157          * @since       2.0
 158          *
 159          * @return              An error code
 160          * @param[in]   sceneId                         The scene ID
 161          * @exception   E_SUCCESS                       The method is successful.
 162          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 163          * @exception   E_OBJ_NOT_FOUND         The specified @c sceneId does not exist.
 164          * @see                 RegisterScene()
 165          */
 166         result UnregisterScene(const SceneId& sceneId);
 167
 168         /**
 169          * Adds a %SceneManager event listener.
 170          *
 171          * @since       2.0
 172          *
 173          * @return              An error code
 174          * @param[in]   sceneManagerEventListener       An instance of ISceneManagerEventListener to add
 175          * @exception   E_SUCCESS                                       The method is successful.
 176          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 177          * @exception   E_OBJ_ALREADY_EXIST                     The listener with the specified type is already added.
 178          * @see                 RemoveSceneManagerEventListener()
 179          * @see                 ISceneManagerEventListener
 180          * @see                 ISceneManagerEventListener::OnSceneTransitionCompleted()
 181          * @see                 ISceneManagerEventListener::OnSceneTransitionStarted()
 182          */
 183         result AddSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
 184
 185         /**
 186          * Removes a %SceneManager event listener.
 187          *
 188          * @since       2.0
 189          *
 190          * @return              An error code
 191          * @param[in]   sceneManagerEventListener       An instance of ISceneManagerEventListener to remove
 192          * @exception   E_SUCCESS                                       The method is successful.
 193          * @exception   E_OBJ_NOT_FOUND                         The specified listener is not found.
 194          * @see                 AddSceneManagerEventListener()
 195          * @see                 ISceneManagerEventListener
 196          */
 197         result RemoveSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
 198
 199         /**
 200          * Adds a Scene event listener.
 201          *
 202          * @since       2.0
 203          *
 204          * @return              An error code
 205          * @param[in]   sceneId                                 The target scene ID
 206          * @param[in]   sceneEventListener              An instance of ISceneEventListener to add
 207          * @exception   E_SUCCESS                               The method is successful.
 208          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 209          * @exception   E_INVALID_ARG                   The specified @c sceneId is invalid.
 210          * @exception   E_OBJ_ALREADY_EXIST             The listener with the specified type is already added.
 211          * @see                 RemoveSceneEventListener()
 212          * @see                 ISceneEventListener
 213          * @see                                                 ISceneEventListener::OnSceneActivatedN()
 214          * @see                 ISceneEventListener::OnSceneDeactivated()
 215          */
 216         result AddSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
 217
 218         /**
 219          * Removes a Scene event listener.
 220          *
 221          * @since       2.0
 222          *
 223          * @return              An error code
 224          * @param[in]   sceneId                         The target scene ID
 225          * @param[in]   sceneEventListener      An instance of ISceneEventListener to remove
 226          * @exception   E_SUCCESS                       The method is successful.
 227          * @exception   E_INVALID_ARG           The specified @c sceneId is invalid.
 228          * @exception   E_OBJ_NOT_FOUND         The specified @c sceneId is not found.
 229          * @see                 AddSceneEventListener()
 230          * @see                 ISceneEventListener
 231          */
 232         result RemoveSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
 233
 234         /**
 235          * Sets a Scene animation provider.
 236          *
 237          * @since       2.0
 238          *
 239          * @return              An error code
 240          * @param[in]   sceneId                                 The target scene ID
 241          * @param[in]   pSceneAnimationProvider An instance of ISceneAnimationProvider to set, @n else @c null to clear previous one
 242          * @exception   E_SUCCESS                               The method is successful.
 243          * @exception   E_INVALID_ARG                   The specified @c sceneId is invalid.
 244          * @exception   E_OBJ_NOT_FOUND                 The specified scene is not found.
 245          * @see                 ISceneAnimationProvider
 246          */
 247         result SetSceneAnimationProvider(const SceneId& sceneId, ISceneAnimationProvider* pSceneAnimationProvider);
 248
 249         /**
 250          * Sets a Scene transition policy provider.
 251          *
 252          * @since       2.0
 253          *
 254          * @return              An error code
 255          * @param[in]   pSceneTransitionPolicyProvider  An instance of ISceneTransitionPolicyProvider to set, @n
 256          *                                                                                              else @c null to clear previous one
 257          * @exception   E_SUCCESS                       The method is successful.
 258          * @see                 ISceneTransitionPolicyProvider
 259          * @see                 ISceneTransitionPolicyProvider::GetNextScene()
 260          * @see                 GoForward()
 261          */
 262         result SetSceneTransitionPolicyProvider(ISceneTransitionPolicyProvider* pSceneTransitionPolicyProvider);
 263
 264         /**
 265          * Sets the default values for the individual animation types.
 266          *
 267          * @since       2.0
 268          *
 269          * @return              An error code
 270          * @param[in]   animationType           The target animation type
 271          * @param[in]   duration                        The duration of the animation in milliseconds @n The maximum duration is one second.
 272          * @param[in]   interpolatorType        The type of interpolator used for the intermediate value calculation of the animation
 273          * @exception   E_SUCCESS                       The method is successful.
 274          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 275          * @remarks             It throws an E_INVALID_ARG exception if the animationType is SCENE_TRANSITION_ANIMATION_TYPE_NONE
 276          *                              or SCENE_TRANSITION_ANIMATION_TYPE_CUSTOM.
 277          * @see                 GoForward()
 278          * @see                 GoBackward()
 279          */
 280         result SetFormTransitionAnimationDefaultValues(SceneTransitionAnimationType animationType, long duration,
 281                                                                                                    Tizen::Ui::Animations::AnimationInterpolatorType interpolatorType);
 282
 283         /**
 284          * Requests forward scene transition with the specified scene transition.
 285          *
 286          * @since       2.0
 287          *
 288          * @return              An error code
 289          * @param[in]   sceneTransition         The scene transition that describes the destination and options
 290          * @param[in]   pArgs                           A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
 291          * @exception   E_SUCCESS                       The method is successful.
 292          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 293          * @exception   E_IN_PROGRESS           A previous transition is in progress.
 294          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 295          * @exception   E_OBJ_NOT_FOUND         The destination scene ID is not found in the registered scenes.
 296          * @exception   E_INVALID_STATE         The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
 297          *                                                                      ISceneTransitionPolicyProvider is not set.
 298          * @exception   E_SYSTEM                        A system error has occurred. @n
 299          *                                                                      (Internal logic or failed to create control from a factory).
 300          * @remarks             To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
 301          *                              also you must register the user-defined ISceneTransitionPolicyProvider and implement the
 302          *                              ISceneTransitionPolicyProvider::GetNextScene() callback method.
 303          **/
 304         result GoForward(const ForwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
 305
 306         /**
 307          * Requests forward scene transition with the specified transition ID.
 308          *
 309          * @since       2.0
 310          *
 311          * @return              An error code
 312          * @param[in]   transitionId            The transition ID that describes the destination and options
 313          * @param[in]   pArgs                           A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
 314          * @exception   E_SUCCESS                       The method is successful.
 315          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 316          * @exception   E_IN_PROGRESS           A previous transition is in progress.
 317          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 318          * @exception   E_OBJ_NOT_FOUND         The destination scene ID is not found in the registered scenes.
 319          * @exception   E_INVALID_STATE         The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
 320          *                                                                      ISceneTransitionPolicyProvider is not set.
 321          * @exception   E_SYSTEM                        A system error has occurred. @n
 322          *                                                                      (Internal logic or failed to create control from a factory).
 323          * @remarks             To use the policy provider operation, SceneTransition's destinationSceneId must be of length 0,
 324          *                              also you must register the user-defined ISceneTransitionPolicyProvider and implement the
 325          *                              ISceneTransitionPolicyProvider::GetNextScene() callback method.
 326          **/
 327         result GoForward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
 328
 329         /**
 330          * Requests backward scene transition with the specified scene transition.
 331          *
 332          * @since       2.0
 333          *
 334          * @return              An error code
 335          * @param[in]   sceneTransition         The scene transition that describes the destination and options
 336          * @param[in]   pArgs                           A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
 337          * @exception   E_SUCCESS                       The method is successful.
 338          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 339          * @exception   E_IN_PROGRESS           A previous transition is in progress.
 340          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 341          * @exception   E_OBJ_NOT_FOUND         The scene ID of the previous scene in the internal history is not found in
 342          *                                                                      the current registered scenes.
 343          * @exception   E_INVALID_STATE         The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
 344          *                                                                      ISceneTransitionPolicyProvider is not set.
 345          * @exception   E_UNDERFLOW                     The scene history is empty.
 346          * @exception   E_SYSTEM                        A system error has occurred. @n
 347          *                                  (Internal logic or failed to create control from a factory).
 348          * @remarks             An item removed from the internal history except the E_SYSTEM exception case. @n
 349          *                              For non-adjacent backward transition, the current scene and the scenes between the current scene and
 350          *                              the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
 351          *                              If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
 352          */
 353         result GoBackward(const BackwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
 354
 355         /**
 356          * Requests backward scene transition with the specified transition ID.
 357          *
 358          * @since       2.0
 359          *
 360          * @return              An error code
 361          * @param[in]   transitionId            The transition ID that describes the destination and options
 362          * @param[in]   pArgs                           A pointer to Tizen::Base::Collection::IList that contains the scene transition parameters
 363          * @exception   E_SUCCESS                       The method is successful.
 364          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 365          * @exception   E_IN_PROGRESS           A previous transition is in progress.
 366          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 367          * @exception   E_OBJ_NOT_FOUND         The scene ID of the previous scene in the internal history is not found in
 368          *                                                                      the current registered scenes.
 369          * @exception   E_INVALID_STATE         The factory instance ( @ref IFormFactory, @ref IPanelFactory ) or
 370          *                                                                      ISceneTransitionPolicyProvider is not set.
 371          * @exception   E_UNDERFLOW                     The scene history is empty.
 372          * @exception   E_SYSTEM                        A system error has occurred. @n
 373          *                                  (Internal logic or failed to create control from a factory).
 374          * @remarks             An item removed from the internal history except the E_SYSTEM exception case. @n
 375          *                              For non-adjacent backward transition, the current scene and the scenes between the current scene and
 376          *                              the requested scene would be destroyed if SCENE_DESTROY_OPTION_KEEP is not specified as destroyOption. @n
 377          *                              If the destroy option is selected then the sibling panel scenes (sharing same base form) are also destroyed.
 378          */
 379         result GoBackward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
 380
 381         /**
 382          * Gets a pointer to the current Scene instance.
 383          *
 384          * @since       2.0
 385          *
 386          * @return              A pointer to the current Scene instance
 387          * @see                 GetCurrentSceneId()
 388          */
 389         Scene* GetCurrentScene(void) const;
 390
 391         /**
 392          * Gets the current scene ID string.
 393          *
 394          * @since       2.0
 395          *
 396          * @return              The scene ID
 397          * @see                 GetCurrentScene()
 398          */
 399         SceneId GetCurrentSceneId(void) const;
 400
 401         /**
 402          * Checks whether the Scene instance with the specified sceneId has been destroyed or not.
 403          *
 404          * @since       2.0
 405          *
 406          * @return              @c true if the scene instance has not been destroyed, @n
 407          *              else @c false
 408          * @param[in]   sceneId                         The scene ID
 409          * @remarks             This method is useful to check state of the scene, because the scene lifetime is determined
 410          *                              by scene transition option and user can destroy the scene in real time.
 411          */
 412         bool IsSceneAlive(const SceneId& sceneId) const;
 413
 414         /**
 415          * Destroys the specified scene.
 416          *
 417          * @since       2.0
 418          *
 419          * @return              An error code
 420          * @param[in]   sceneId                         The scene ID
 421          * @exception   E_SUCCESS                       The method is successful.
 422          * @exception   E_INVALID_ARG           The current scene cannot be destroyed.
 423          * @exception   E_OBJ_NOT_FOUND         The specified @c sceneId does not exist.
 424          * @exception   E_SYSTEM                        A system error has occurred.
 425          */
 426         result DestroyScene(const SceneId& sceneId);
 427
 428         /**
 429          * Brings the current scene to the topmost to get back the control of scene management.
 430          *
 431          * @since       2.0
 432          *
 433          * @return              An error code
 434          * @exception   E_SUCCESS                       The method is successful.
 435          * @exception   E_OPERATION_FAILED      The current scene is invalid.
 436          * @exception   E_SYSTEM                        A system error has occurred.
 437          * @remarks             If a user sets a form as a current form on a frame by calling Tizen::Ui::Controls::Frame::SetCurrentForm(),
 438          *                              they will no longer be under the control of %SceneManager. In this case,
 439          *                              they can get back the control of scene management easily by calling this method.
 440          * @see                 Tizen::Ui::Controls::Frame::SetCurrentForm()
 441          */
 442         result BringCurrentSceneToTop(void);
 443
 444         /**
 445          * Clears the scene history.
 446          *
 447          * @since       2.0
 448          *
 449          * @return              An error code
 450          * @exception   E_SUCCESS                       The method is successful.
 451          * @see                 AddToSceneHistory()
 452          */
 453         result ClearSceneHistory(void);
 454
 455         /**
 456          * Adds the scene to the scene history.
 457          *
 458          * @since       2.0
 459          *
 460          * @return              An error code
 461          * @param[in]   sceneId                         The scene ID
 462          * @exception   E_SUCCESS                       The method is successful.
 463          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 464          * @exception   E_OBJ_NOT_FOUND         The specified @c sceneId is not found in the registered scenes.
 465          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 466          * @see                 ClearSceneHistory()
 467          */
 468         result AddToSceneHistory(const SceneId& sceneId);
 469
 470         /**
 471          * Gets the scene history list.
 472          *
 473          * @since       2.0
 474          *
 475          * @return              A pointer to the list that contains the scene history
 476          * @exception   E_SUCCESS                       The method is successful.
 477          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 478          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 479          */
 480         Tizen::Base::Collection::IListT<SceneId>* GetSceneHistoryN(void) const;
 481
 482 private:
 483         /**
 484          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 485          *
 486          * @since       2.0
 487          */
 488         SceneManager(void);
 489
 490         /**
 491          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 492          *
 493          * @since       2.0
 494          */
 495         SceneManager(const SceneManager& rhs);
 496
 497         /**
 498          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 499          *
 500          * @since       2.0
 501          */
 502         SceneManager& operator =(const SceneManager& rhs);
 503
 504         /**
 505          * This destructor is intentionally declared as private to implement the Singleton semantic.
 506          *
 507          * @since       2.0
 508          */
 509         virtual ~SceneManager(void);
 510
 511         /**
 512          * Initializes the instance of the this class.
 513          *
 514          * @since       2.0
 515          *
 516          * @return              An error code.
 517          * @exception   E_SUCCESS               The method is successful.
 518          * @exception   E_SYSTEM                A system error has occurred.
 519          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 520          *
 521          */
 522         result Construct(void);
 523
 524         static void InitSingleton(void);
 525         static void DestroySingleton(void);
 526
 527 private:
 528         friend class _SceneManagerImpl;
 529         class _SceneManagerImpl* __pSceneManagerImpl;
 530         static SceneManager* __pSceneManagerInstance;
 531
 532 }; // SceneManager
 533 } } } // Tizen::Ui::Scenes
 534
 535 #endif  //_FUI_SCENES_SCENE_MANAGER_H_