com.google.gwt.place.shared

## Class PlaceChangeRequestEvent

- java.lang.Object
- - com.google.web.bindery.event.shared.Event<H>
  - - com.google.gwt.event.shared.GwtEvent<PlaceChangeRequestEvent.Handler>
    - - com.google.gwt.place.shared.PlaceChangeRequestEvent

-     public class PlaceChangeRequestEvent
      extends GwtEvent<PlaceChangeRequestEvent.Handler>

  Event thrown when the user may go to a new place in the app, or tries to leave it. Receivers can call `setWarning(String)` request that the user be prompted to confirm the change.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `PlaceChangeRequestEvent.Handler` Implemented by handlers of PlaceChangeRequestEvent.

    - ### Nested classes/interfaces inherited from class com.google.gwt.event.shared.GwtEvent

      `GwtEvent.Type<H>`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static GwtEvent.Type<PlaceChangeRequestEvent.Handler>` | `TYPE` A singleton instance of Type<Handler>.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PlaceChangeRequestEvent(Place newPlace)` Constructs a PlaceChangeRequestEvent for the given `Place`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `dispatch(PlaceChangeRequestEvent.Handler handler)` Should only be called by `HandlerManager`.
    `GwtEvent.Type<PlaceChangeRequestEvent.Handler>` | `getAssociatedType()` Returns the `Event.Type` used to register this event, allowing an `EventBus` to find handlers of the appropriate class.
    `Place` | `getNewPlace()` Returns the place we may navigate to, or null on window close.
    `java.lang.String` | `getWarning()` Returns the warning message to show the user before allowing the place change, or null if none has been set.
    `void` | `setWarning(java.lang.String warning)` Set a message to warn the user that it might be unwise to navigate away from the current place, e.g.

    - ### Methods inherited from class com.google.gwt.event.shared.GwtEvent

      `assertLive, getSource, isLive, kill, revive`

    - ### Methods inherited from class com.google.web.bindery.event.shared.Event

      `setSource, toDebugString, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### TYPE

          public static final GwtEvent.Type<PlaceChangeRequestEvent.Handler> TYPE

      A singleton instance of Type<Handler>.

  - ### Constructor Detail

    - #### PlaceChangeRequestEvent

          public PlaceChangeRequestEvent(Place newPlace)

      Constructs a PlaceChangeRequestEvent for the given `Place`.
      Parameters:
        `newPlace` - a `Place` instance

  - ### Method Detail

    - #### getAssociatedType

          public GwtEvent.Type<PlaceChangeRequestEvent.Handler> getAssociatedType()

      Description copied from class: `Event`
      Returns the `Event.Type` used to register this event, allowing an `EventBus` to find handlers of the appropriate class.
      Specified by:
        `getAssociatedType` in class `GwtEvent<PlaceChangeRequestEvent.Handler>`
      Returns:
        the type

    - #### getNewPlace

          public Place getNewPlace()

      Returns the place we may navigate to, or null on window close.
      Returns:
        a `Place` instance

    - #### getWarning

          public java.lang.String getWarning()

      Returns the warning message to show the user before allowing the place change, or null if none has been set.
      Returns:
        the warning message as a String
      See Also:
        `setWarning(String)`

    - #### setWarning

          public void setWarning(java.lang.String warning)

      Set a message to warn the user that it might be unwise to navigate away from the current place, e.g. due to unsaved changes. If the user clicks okay to that message, navigation will be canceled.

      Calling with a null warning is the same as not calling the method at all -- the user will not be prompted.

      Only the first non-null call to setWarning has any effect. That is, once the warning message has been set it cannot be cleared.

      Parameters:
        `warning` - the warning message as a String
      See Also:
        `getWarning()`

    - #### dispatch

          protected void dispatch(PlaceChangeRequestEvent.Handler handler)

      Description copied from class: `GwtEvent`
      Should only be called by `HandlerManager`. In other words, do not use or call.
      Specified by:
        `dispatch` in class `GwtEvent<PlaceChangeRequestEvent.Handler>`
      Parameters:
        `handler` - handler
      See Also:
        `EventBus.dispatchEvent(Event, Object)`