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 * <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 48 * implements="mx.managers.IHistoryManagerClient" 49 * initialize="mx.managers.HistoryManager.register(this);"> 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