inc/FUiScenesSceneManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  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          */
  99         result RegisterFormFactory(const IFormFactory& formFactory);
 100
 101         /**
 102          * Registers a panel factory. @n
 103          * The IPanelFactory::CreatePanelN() method is called when a new panel is required.
 104          *
 105          * @since       2.0
 106          *
 107          * @return              An error code
 108          * @param[in]   panelFactory            The user-defined panel factory instance
 109          * @exception   E_SUCCESS                       The method is successful.
 110          */
 111         result RegisterPanelFactory(const IPanelFactory& panelFactory);
 112
 113         /**
 114          * Registers a scene.
 115          * A scene is combination of a form and a panel.
 116          *
 117          * @since       2.0
 118          *
 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.
 127          *
 128          */
 129         result RegisterScene(const SceneId& sceneId, const Tizen::Base::String& formId, const Tizen::Base::String& panelId);
 130
 131         /**
 132          * Registers scene(s) with the specified resource ID.
 133          * The %RegisterScene() method does not remove a scene that is already registered.
 134          *
 135          * @since       2.0
 136          *
 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()
 146          *
 147          */
 148         result RegisterScene(const Tizen::Base::String& resourceId);
 149
 150         /**
 151          * Unregisters the specified scene.
 152          *
 153          * @since       2.0
 154          *
 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()
 161          */
 162         result UnregisterScene(const SceneId& sceneId);
 163
 164         /**
 165          * Adds a %SceneManager event listener.
 166          *
 167          * @since       2.0
 168          *
 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()
 177          */
 178         result AddSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
 179
 180         /**
 181          * Removes a %SceneManager event listener.
 182          *
 183          * @since       2.0
 184          *
 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()
 190          */
 191         result RemoveSceneManagerEventListener(ISceneManagerEventListener& sceneManagerEventListener);
 192
 193         /**
 194          * Adds a Scene event listener.
 195          *
 196          * @since       2.0
 197          *
 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()
 208          */
 209         result AddSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
 210
 211         /**
 212          * Removes a Scene event listener.
 213          *
 214          * @since       2.0
 215          *
 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()
 223          */
 224         result RemoveSceneEventListener(const SceneId& sceneId, ISceneEventListener& sceneEventListener);
 225
 226         /**
 227          * Sets a Scene animation provider.
 228          *
 229          * @since       2.0
 230          *
 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.
 237          */
 238         result SetSceneAnimationProvider(const SceneId& sceneId, ISceneAnimationProvider* pSceneAnimationProvider);
 239
 240         /**
 241          * Sets a Scene transition policy provider.
 242          *
 243          * @since       2.0
 244          *
 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()
 250          * @see                 GoForward()
 251          */
 252         result SetSceneTransitionPolicyProvider(ISceneTransitionPolicyProvider* pSceneTransitionPolicyProvider);
 253
 254         /**
 255          * Sets the default values for the individual animation types.
 256          *
 257          * @since       2.0
 258          *
 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.
 266          * @see                 GoForward()
 267          * @see                 GoBackward()
 268          */
 269         result SetFormTransitionAnimationDefaultValues(SceneTransitionAnimationType animationType, long duration,
 270                                                                                                    Tizen::Ui::Animations::AnimationInterpolatorType interpolatorType);
 271
 272         /**
 273          * Requests forward scene transition with the specified scene transition.
 274          *
 275          * @since       2.0
 276          *
 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.
 292          **/
 293         result GoForward(const ForwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
 294
 295         /**
 296          * Requests forward scene transition with the specified transition ID.
 297          *
 298          * @since       2.0
 299          *
 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.
 315          **/
 316         result GoForward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
 317
 318         /**
 319          * Requests backward scene transition with the specified scene transition.
 320          *
 321          * @since       2.0
 322          *
 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.
 341          */
 342         result GoBackward(const BackwardSceneTransition& sceneTransition, const Tizen::Base::Collection::IList* pArgs = null);
 343
 344         /**
 345          * Requests backward scene transition with the specified transition ID.
 346          *
 347          * @since       2.0
 348          *
 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.
 367          */
 368         result GoBackward(const SceneTransitionId& transitionId, const Tizen::Base::Collection::IList* pArgs = null);
 369
 370         /**
 371          * Gets a pointer to the current Scene instance.
 372          *
 373          * @since       2.0
 374          *
 375          * @return              A pointer to the current Scene instance
 376          * @see                 GetCurrentSceneId()
 377          */
 378         Scene* GetCurrentScene(void) const;
 379
 380         /**
 381          * Gets the current scene ID string.
 382          *
 383          * @since       2.0
 384          *
 385          * @return              The scene ID
 386          * @see                 GetCurrentScene()
 387          */
 388         SceneId GetCurrentSceneId(void) const;
 389
 390         /**
 391          * Checks whether the Scene instance with the specified sceneId has been destroyed or not.
 392          *
 393          * @since       2.0
 394          *
 395          * @return              @c true if the scene instance has not been destroyed, @n
 396          *              else @c false
 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.
 400          */
 401         bool IsSceneAlive(const SceneId& sceneId) const;
 402
 403         /**
 404          * Destroys the specified scene.
 405          *
 406          * @since       2.0
 407          *
 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.
 414          */
 415         result DestroyScene(const SceneId& sceneId);
 416
 417         /**
 418          * Brings the current scene to the topmost to get back the control of scene management.
 419          *
 420          * @since       2.0
 421          *
 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.
 429          */
 430         result BringCurrentSceneToTop(void);
 431
 432         /**
 433          * Clears the scene history.
 434          *
 435          * @since       2.0
 436          *
 437          * @return              An error code
 438          * @exception   E_SUCCESS                       The method is successful.
 439          * @see                 AddToSceneHistory()
 440          */
 441         result ClearSceneHistory(void);
 442
 443         /**
 444          * Adds the scene to the scene history.
 445          *
 446          * @since       2.0
 447          *
 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()
 455          */
 456         result AddToSceneHistory(const SceneId& sceneId);
 457
 458         /**
 459          * Gets the scene history list.
 460          *
 461          * @since       2.0
 462          *
 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.
 467          */
 468         Tizen::Base::Collection::IListT<SceneId>* GetSceneHistoryN(void) const;
 469
 470 private:
 471         /**
 472          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 473          *
 474          * @since       2.0
 475          */
 476         SceneManager(void);
 477
 478         /**
 479          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 480          *
 481          * @since       2.0
 482          */
 483         SceneManager(const SceneManager& rhs);
 484
 485         /**
 486          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 487          *
 488          * @since       2.0
 489          */
 490         SceneManager& operator =(const SceneManager& rhs);
 491
 492         /**
 493          * This destructor is intentionally declared as private to implement the Singleton semantic.
 494          *
 495          * @since       2.0
 496          */
 497         virtual ~SceneManager(void);
 498
 499         /**
 500          * Initializes the instance of the this class.
 501          *
 502          * @since       2.0
 503          *
 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.
 508          *
 509          */
 510         result Construct(void);
 511
 512         static void InitSingleton(void);
 513         static void DestroySingleton(void);
 514
 515 private:
 516         friend class _SceneManagerImpl;
 517         class _SceneManagerImpl* __pSceneManagerImpl;
 518         static SceneManager* __pSceneManagerInstance;
 519
 520 }; // SceneManager
 521 } } } // Tizen::Ui::Scenes
 522
 523 #endif  //_FUI_SCENES_SCENE_MANAGER_H_