com.google.gwt.user.client
Class History

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

public class History
extends java.lang.Object

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 HistoryListener interface and attach it via addHistoryListener(com.google.gwt.user.client.HistoryListener).

Example

public class HistoryExample implements EntryPoint, HistoryListener {

  private Label lbl = new Label();

  public void onModuleLoad() {
    // Create three hyperlinks that change the application's history.
    Hyperlink link0 = new Hyperlink("link to foo", "foo");
    Hyperlink link1 = new Hyperlink("link to bar", "bar");
    Hyperlink link2 = new Hyperlink("link to baz", "baz");

    // If the application starts with no history token, start it off in the
    // 'baz' state.
    String initToken = History.getToken();
    if (initToken.length() == 0)
      initToken = "baz";

    // onHistoryChanged() is not called when the application first runs. Call
    // it now in order to reflect the initial state.
    onHistoryChanged(initToken);

    // Add widgets to the root panel.
    VerticalPanel panel = new VerticalPanel();
    panel.add(lbl);
    panel.add(link0);
    panel.add(link1);
    panel.add(link2);
    RootPanel.get().add(panel);

    // Add history listener
    History.addHistoryListener(this);
  }

  public void onHistoryChanged(String historyToken) {
    // This method is called whenever the application's history changes. Set
    // the label to reflect the current history token.
    lbl.setText("The current history token is: " + historyToken);
  }
}

Constructor Summary

History()

Method Summary

static void	addHistoryListener(HistoryListener listener) Adds a listener 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	forward() Programmatic equivalent to the user pressing the browser's 'forward' button.
static java.lang.String	getToken() Gets the current history token.
static void	newItem(java.lang.String historyToken) Adds a new browser history entry.
static void	onHistoryChanged(java.lang.String historyToken)
static void	removeHistoryListener(HistoryListener listener) Removes a history listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

History

public History()

Method Detail

addHistoryListener

public static void addHistoryListener(HistoryListener listener)

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

Parameters:

listener - the listener to be added

back

public static void back()

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

forward

public static void forward()

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

getToken

public static java.lang.String getToken()

Gets the current history token. The listener will not receive an onHistoryChanged() 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.

newItem

public static void newItem(java.lang.String historyToken)

Adds a new browser history entry. In hosted mode, the 'back' and 'forward' actions are accessible via the standard Alt-Left and Alt-Right keystrokes. Calling this method will cause onHistoryChanged(java.lang.String) to be called as well.

Parameters:

historyToken - the token to associate with the new history item

onHistoryChanged

public static void onHistoryChanged(java.lang.String historyToken)

removeHistoryListener

public static void removeHistoryListener(HistoryListener listener)

Removes a history listener.

Parameters:

listener - the listener to be removed