1////////////////////////////////////////////////////////////////////////////////
2//
3//  ADOBE SYSTEMS INCORPORATED
4//  Copyright 2003-2007 Adobe Systems Incorporated
5//  All Rights Reserved.
6//
7//  NOTICE: Adobe permits you to use, modify, and distribute this file
8//  in accordance with the terms of the license agreement accompanying it.
9//
10////////////////////////////////////////////////////////////////////////////////
11
12package mx.managers
13{
14
15import mx.core.Singleton;
16import mx.core.mx_internal;
17import mx.managers.IHistoryManagerClient;
18
19use namespace mx_internal;
20
21/**
22 *  History management lets users navigate through a Flex application
23 *  using the web browser's Back and Forward navigation commands.
24 *
25 *  <p>In general, you should use the BrowserManager class and deep linking for maintaining state
26 *  in an application and manipulating URLs and browser history, but the HistoryManager class can
27 *  be useful under some circumstances, such as if you are maintaining a legacy Flex application.
28 *  You cannot use the HistoryManager and the BrowserManager classes in the same Flex application,
29 *  even though they use the same set of supporting files.</p>
30 *
31 *  <p>History management is enabled by default for the Accordion and TabNavigator containers.
32 *  This means that if the user selects one of the panes in an Accordion control,
33 *  that user can return to the previous pane by using the browser's Back button or back
34 *  navigation command. History management is disabled by default for the ViewStack
35 *  navigator container.</p>
36 *
37 *  <p>You can disable history management by setting the navigator container's
38 *  <code>historyManagementEnabled</code> property to <code>false</code>.</p>
39 *
40 *  <p>You can also enable history management for other objects
41 *  in an application by registering the objects with the HistoryManager. To register a component
42 *  with the HistoryManager class, you call the HistoryManager class's <code>register()</code>
43 *  method with a reference to a component instance that implements the IHistoryManagerClient interface.
44 *  In the following example, the Application component (<code>this</code>) is registered with
45 *  the HistoryManager class when the Application is initialized:
46 *  <pre>
47 *  &lt;mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
48 *    implements="mx.managers.IHistoryManagerClient"
49 *    initialize="mx.managers.HistoryManager.register(this);"&gt;
50 *  </pre>
51 *  You must also implement the <code>saveState()</code> and <code>loadState()</code> methods of the
52 *  IHistoryManagerClient interface to complete the registration of the component. Components that extend
53 *  UIComponent automatically inherit the <code>loadState()</code> method.</p>
54 *
55 *  <p>All methods and properties of the HistoryManager are static,
56 *  so you do not need to create an instance of it.</p>
57 *
58 *  @see mx.managers.BrowserManager
59 *  @see mx.managers.IHistoryManagerClient
60 */
61public class HistoryManager
62{
63    include "../core/Version.as";
64
65    //--------------------------------------------------------------------------
66    //
67    //  Class variables
68    //
69    //--------------------------------------------------------------------------
70
71    /**
72     *  @private
73     *  Linker dependency on implementation class.
74     */
75    private static var implClassDependency:HistoryManagerImpl;
76
77    /**
78     *  @private
79     *  Storage for the impl getter.
80     *  This gets initialized on first access,
81     *  not at static initialization time, in order to ensure
82     *  that the Singleton registry has already been initialized.
83     */
84    private static var _impl:IHistoryManager;
85
86    /**
87     *  @private
88     *  The singleton instance of HistoryManagerImpl which was
89     *  registered as implementing the IHistoryManager interface.
90     */
91    private static function get impl():IHistoryManager
92    {
93        if (!_impl)
94        {
95            _impl = IHistoryManager(
96                Singleton.getInstance("mx.managers::IHistoryManager"));
97        }
98
99        return _impl;
100    }
101
102    //--------------------------------------------------------------------------
103    //
104    //  Class methods
105    //
106    //--------------------------------------------------------------------------
107
108    /**
109     *  DEPRECATED - Initializes the HistoryManager. In general, this does not need to be called
110     *  because any time you add a component with <code>historyManagementEnabled</code>, Flex
111     *  calls this method. However, the HistoryManager will not work correctly if it is
112     *  not initialized from the top-level application. So, if your application does
113     *  not have any HistoryManager enabled components in it and loads other sub-applications
114     *  That do, you must call the <code>HistoryManager.initialize()</code> method in the
115     *  main application, usually from an <code>initialize</code> event handler on the application.
116     *
117     *  @param sm SystemManager for this application.
118     */
119    public static function initialize(sm:ISystemManager):void
120    {
121        // this code is handled in HistoryManagerImpl.getInstance() now
122    }
123
124    /**
125     *  Registers an object with the HistoryManager.
126     *  The object must implement the IHistoryManagerClient interface.
127     *
128     *  @param obj Object to register.
129     *
130     *  @see mx.managers.IHistoryManagerClient
131     */
132    public static function register(obj:IHistoryManagerClient):void
133    {
134        impl.register(obj);
135    }
136
137    /**
138     *  Unregisters an object with the HistoryManager.
139     *
140     *  @param obj Object to unregister.
141     */
142    public static function unregister(obj:IHistoryManagerClient):void
143    {
144        impl.unregister(obj);
145    }
146
147    /**
148     *  Saves the application's current state so it can be restored later.
149     *  This method is automatically called by navigator containers
150     *  whenever their navigation state changes.
151     *  If you registered an interface with the HistoryManager,
152     *  you are responsible for calling the <code>save()</code> method
153     *  when the application state changes.
154     */
155    public static function save():void
156    {
157        impl.save();
158    }
159
160}
161
162}
163
164