This class allows you to interact with the browser's history stack. Each "item" on the stack is represented by a single string, referred to as a "token". You can create new history items (which have a token associated with them when they are created), and you can programmatically force the current history to move back or forward.

In order to receive notification of user-directed changes to the current history item, implement the {@link ValueChangeHandler} interface and attach it via {@link #addValueChangeHandler(ValueChangeHandler)}.

Example

{@example com.google.gwt.examples.HistoryExample}

URL Encoding

Any valid characters may be used in the history token and will survive round-trips through {@link #newItem(String)} to {@link #getToken()}/ {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)} , but most will be encoded in the user-visible URL. The following US-ASCII characters are not encoded on any currently supported browser (but may be in the future due to future browser changes):

• a-z
• A-Z
• 0-9
• ;,/?:@&=+$-_.!~*()

class History {
 static HistoryImpl _impl;

 static bool _initialized = false;
 
 static void init() {
   if (!_initialized) {
     _initialized = true;
     //
     _impl = new HistoryImpl();
     if (!_impl.init()) {
       // Set impl to null as a flag to no-op future calls
       _impl = null;
       
       // Tell the user
       print('''Unable to initialise the history subsystem; did you
include the history frame in you host page? Try  
<iframe src=\"javascript:''\" id='__dwt_historyFrame' 
style='position:absolute;width:0'height:0;border:0'>
</iframe>
''');
     }
   }
 }
 
 /**
  * Adds a {@link com.google.gwt.event.logical.shared.ValueChangeEvent} handler
  * to be informed of changes to the browser's history stack.
  *
  * @param handler the handler
  * @return the registration used to remove this value change handler
  */
 static HandlerRegistration addValueChangeHandler(ValueChangeHandler<String> handler) {
   init();
   return _impl != null ? _impl.addValueChangeHandler(handler) : null;
 }

 /**
  * Programmatic equivalent to the user pressing the browser's 'back' button.
  *
  * Note that this does not work correctly on Safari 2.
  */
 static void back() {
   init();
   dart_html.window.history.back();
 }

 /**
  * Programmatic equivalent to the user pressing the browser's 'forward'
  * button.
  */
 static void forward() {
   init();
   dart_html.window.history.forward();
 }

 /**
  * Encode a history token for use as part of a URI.
  *
  * @param historyToken the token to encode
  * @return the encoded token, suitable for use as part of a URI
  */
 static String encodeHistoryToken(String historyToken) {
   init();
   return _impl != null ? _impl.encodeFragment(historyToken) : historyToken;
 }

 /**
  * Fire
  * {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)}
  * events with the current history state. This is most often called at the end 
  * of an application's
  * {@link com.google.gwt.core.client.EntryPoint#onModuleLoad()} to inform
  * history handlers of the initial application state.
  */
 static void fireCurrentHistoryState() {
   init();
   if (_impl != null) {
     String token = getToken();
     _impl.fireHistoryChangedImpl(token);
   }
 }

 /**
  * Gets the current history token. The handler will not receive a
  * {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)}
  * event for the initial token; requiring that an application request the
  * token explicitly on startup gives it an opportunity to run different
  * initialization code in the presence or absence of an initial token.
  *
  * @return the initial token, or the empty string if none is present.
  */
 static String getToken() {
   init();
   return _impl != null ? HistoryImpl.getToken() : "";
 }

 /**
  * Adds a new browser history entry. Calling this method will cause
  * {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)}
  * to be called as well if and only if issueEvent is true.
  *
  * @param historyToken the token to associate with the new history item
  * @param issueEvent true if a
  *          {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)}
  *          event should be issued
  */
 static void newItem(String historyToken, [bool issueEvent = true]) {
   init();
   if (_impl != null) {
     _impl.newItem(historyToken, issueEvent);
   }
 }
}

static void init() {
 if (!_initialized) {
   _initialized = true;
   //
   _impl = new HistoryImpl();
   if (!_impl.init()) {
     // Set impl to null as a flag to no-op future calls
     _impl = null;
     
     // Tell the user
     print('''Unable to initialise the history subsystem; did you
include the history frame in you host page? Try  
<iframe src=\"javascript:''\" id='__dwt_historyFrame' 
style='position:absolute;width:0'height:0;border:0'>
</iframe>
''');
   }
 }
}

static HandlerRegistration addValueChangeHandler(ValueChangeHandler<String> handler) {
 init();
 return _impl != null ? _impl.addValueChangeHandler(handler) : null;
}

static void back() {
 init();
 dart_html.window.history.back();
}

static void forward() {
 init();
 dart_html.window.history.forward();
}

static String encodeHistoryToken(String historyToken) {
 init();
 return _impl != null ? _impl.encodeFragment(historyToken) : historyToken;
}

static void fireCurrentHistoryState() {
 init();
 if (_impl != null) {
   String token = getToken();
   _impl.fireHistoryChangedImpl(token);
 }
}

static String getToken() {
 init();
 return _impl != null ? HistoryImpl.getToken() : "";
}

     {@link ValueChangeHandler#onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)}
     event should be issued

static void newItem(String historyToken, [bool issueEvent = true]) {
 init();
 if (_impl != null) {
   _impl.newItem(historyToken, issueEvent);
 }
}