Google Web Toolkit (Beta)
Search this site:

# Class History

public class History
extends 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.

### 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);
      }
    }

## Methods

addHistoryListener(HistoryListener) | Adds a listener to be informed of changes to the browser's history stack.
back() | Programmatic equivalent to the user pressing the browser's 'back' button.
forward() | Programmatic equivalent to the user pressing the browser's 'forward' button.
getToken() | Gets the current history token.
newItem(String) | Adds a new browser history entry.
onHistoryChanged(String) |
removeHistoryListener(HistoryListener) | Removes a history listener.

## 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 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.

#### Return Value

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

### newItem

public static void newItem(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 to be called as well.

#### Parameters

historyToken
  the token to associate with the new history item

### onHistoryChanged

public static void onHistoryChanged(String historyToken)

#### Parameters

historyToken

### removeHistoryListener

public static void removeHistoryListener(HistoryListener listener)
Removes a history listener.

#### Parameters

listener
  the listener to be removed