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 `ValueChangeHandler` interface and attach it via `addValueChangeHandler(ValueChangeHandler)`.

  ### Example

  >     public class HistoryExample implements EntryPoint, ValueChangeHandler<String> {

  >       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, redirect to a new
  >         // 'baz' state.
  >         String initToken = History.getToken();
  >         if (initToken.length() == 0) {
  >           History.newItem("baz");
  >         }

  >         // 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.addValueChangeHandler(this);

  >         // Now that we've setup our listener, fire the initial history state.
  >         History.fireCurrentHistoryState();
  >       }

  >       public void onValueChange(ValueChangeEvent<String> event) {
  >         // 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: " + event.getValue());
  >       }
  >     }

  ### URL Encoding

  Any valid characters may be used in the history token and will survive round-trips through `newItem(String)` to `getToken()`/ `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
  - ;,/?:@&=+$-_.!~*()

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `History()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addHistoryListener(HistoryListener listener)` Deprecated. use `addValueChangeHandler(ValueChangeHandler)` instead
    `static HandlerRegistration` | `addValueChangeHandler(ValueChangeHandler<java.lang.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 java.lang.String` | `encodeHistoryToken(java.lang.String historyToken)` Encode a history token for use as part of a URI.
    `static void` | `fireCurrentHistoryState()` Fire `ValueChangeHandler.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 java.lang.String` | `getToken()` Gets the current history token.
    `static void` | `newItem(java.lang.String historyToken)` Adds a new browser history entry.
    `static void` | `newItem(java.lang.String historyToken, boolean issueEvent)` Adds a new browser history entry.
    `static void` | `onHistoryChanged(java.lang.String historyToken)` Deprecated. Use `fireCurrentHistoryState()` instead.
    `static void` | `removeHistoryListener(HistoryListener listener)` Deprecated.
    `static void` | `replaceItem(java.lang.String historyToken)` Replace the current history token on top of the browsers history stack.
    `static void` | `replaceItem(java.lang.String historyToken, boolean issueEvent)` Replace the current history token on top of the browsers history stack.

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

          @Deprecated
          public static void addHistoryListener(HistoryListener listener)

      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

    - #### addValueChangeHandler

          public static HandlerRegistration addValueChangeHandler(ValueChangeHandler<java.lang.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

    - #### back

          public static void back()

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

    - #### encodeHistoryToken

          public static java.lang.String encodeHistoryToken(java.lang.String historyToken)

      Encode a history token for use as part of a URI.
      Parameters:
        `historyToken` - the token to encode
      Returns:
        the encoded token, suitable for use as part of a URI

    - #### fireCurrentHistoryState

          public static void fireCurrentHistoryState()

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

    - #### 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 handler will not receive a `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.
      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. Calling this method will cause `ValueChangeHandler.onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)` to be called as well.
      Parameters:
        `historyToken` - the token to associate with the new history item

    - #### newItem

          public static void newItem(java.lang.String historyToken,
                                     boolean issueEvent)

      Adds a new browser history entry. Calling this method will cause `ValueChangeHandler.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 `ValueChangeHandler.onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)` event should be issued

    - #### onHistoryChanged

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

      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 `EntryPoint.onModuleLoad()` method.
      Parameters:
        `historyToken` - history token to fire events for

    - #### removeHistoryListener

          @Deprecated
          public static void removeHistoryListener(HistoryListener listener)

      Deprecated.
      Removes a history listener.
      Parameters:
        `listener` - the listener to be removed

    - #### replaceItem

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

      Replace the current history token on top of the browsers history stack.

      Note: This method has problems. The URL is updated with window.location.replace, this unfortunately has side effects when using the deprecated iframe linker (ie. "std" linker). Make sure you are using the cross site iframe linker when using this method in your code.

      Calling this method will cause `ValueChangeHandler.onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)` to be called as well.

      Parameters:
        `historyToken` - history token to replace current top entry

    - #### replaceItem

          public static void replaceItem(java.lang.String historyToken,
                                         boolean issueEvent)

      Replace the current history token on top of the browsers history stack.

      Note: This method has problems. The URL is updated with window.location.replace, this unfortunately has side effects when using the deprecated iframe linker (ie. "std" linker). Make sure you are using the cross site iframe linker when using this method in your code.

      Calling this method will cause `ValueChangeHandler.onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)` to be called as well if and only if issueEvent is true.

      Parameters:
        `historyToken` - history token to replace current top entry
        `issueEvent` - issueEvent true if a `ValueChangeHandler.onValueChange(com.google.gwt.event.logical.shared.ValueChangeEvent)` event should be issued