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