public class

History

extends Object
java.lang.Object
   ↳ com.google.gwt.user.client.History

Class Overview

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 ValueChangeHandler interface and attach it via 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 newItem(String) to getToken()/ 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
  • ;,/?:@&=+$-_.!~*()

Summary

Public Constructors
History()
Public Methods
static void addHistoryListener(HistoryListener listener)
This method is deprecated. use addValueChangeHandler(ValueChangeHandler) instead
static HandlerRegistration addValueChangeHandler(ValueChangeHandler<String> handler)
Adds a ValueChangeEvent handler to be informed of changes to the browser's history stack.
static void back()
Programmatic equivalent to the user pressing the browser's 'back' button.
static void fireCurrentHistoryState()
Fire onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent) events with the current history state.
static void forward()
Programmatic equivalent to the user pressing the browser's 'forward' button.
static String getToken()
Gets the current history token.
static void newItem(String historyToken, boolean issueEvent)
Adds a new browser history entry.
static void newItem(String historyToken)
Adds a new browser history entry.
static void onHistoryChanged(String historyToken)
This method is deprecated. Use fireCurrentHistoryState() instead.
static void removeHistoryListener(HistoryListener listener)
Removes a history listener.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public History ()

Public Methods

public static void addHistoryListener (HistoryListener listener)

This method is deprecated.
use addValueChangeHandler(ValueChangeHandler) instead

Adds a listener to be informed of changes to the browser's history stack.

Parameters
listener the listener to be added

public static HandlerRegistration addValueChangeHandler (ValueChangeHandler<String> handler)

Adds a ValueChangeEvent handler to be informed of changes to the browser's history stack.

Parameters
handler the handler
Returns
  • the registration used to remove this value change handler

public static void back ()

Programmatic equivalent to the user pressing the browser's 'back' button. Note that this does not work correctly on Safari 2.

public static void fireCurrentHistoryState ()

Fire 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 onModuleLoad() to inform history handlers of the initial application state.

public static void forward ()

Programmatic equivalent to the user pressing the browser's 'forward' button.

public static String getToken ()

Gets the current history token. The handler will not receive a 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.

Returns
  • the initial token, or the empty string if none is present.

public static void newItem (String historyToken, boolean issueEvent)

Adds a new browser history entry. Calling this method will cause onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent) to be called as well if and only if issueEvent is true.

Parameters
historyToken the token to associate with the new history item
issueEvent true if a onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent) event should be issued

public static void newItem (String historyToken)

Adds a new browser history entry. Calling this method will cause onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent) to be called as well.

Parameters
historyToken the token to associate with the new history item

public static void onHistoryChanged (String historyToken)

This method is deprecated.
Use fireCurrentHistoryState() instead.

Call all history handlers with the specified token. Note that this does not change the history system's idea of the current state and is only kept for backward compatibility. To fire history events for the initial state of the application, instead call fireCurrentHistoryState() from the application onModuleLoad() method.

Parameters
historyToken history token to fire events for

public static void removeHistoryListener (HistoryListener listener)

Removes a history listener.

Parameters
listener the listener to be removed