package org.litesoft.GWT.client.pavsupport;

import org.litesoft.GWT.client.util.*;

import com.google.gwt.place.shared.*;
import com.google.gwt.user.client.*;

public interface PlaceChanger {
    enum GoToPlace {
        AlreadyThere,
        NoActivity,
        CurrentActivityRejectedLeaving
    }

    /**
     * Returns the current place.
     *
     * @return a {@link Place} instance
     */
    Place getWhere();

    /**
     * Request a change to the previous place on the browser's history stack.
     * If there is a previous place on the browser's history stack, the location
     * changes and a {@link PlaceChangeEvent} is posted announcing the previous place.
     */
    void goBack();

    /**
     * Request a change to a new place (and if we get there, the resulting URL will
     * become the new top of the History Stack).
     * <p/>
     * It is not a given that we'll actually get there. First a
     * {@link PlaceChangeRequestEvent} will be posted to the event bus. If any
     * receivers post a warning message to that event, it will be presented to
     * the user via {@link WindowClose#confirm(String)} (which is typically a
     * call to {@link Window#confirm(String)}). If she cancels, the current
     * location will not change. Otherwise, the location changes and a
     * {@link PlaceChangeEvent} is posted announcing the new place.
     *
     * @param pNewPlace a {@link Place} instance
     *
     * @return null if going to pNewPlace, !null means NOT going and why
     */
    GoToPlace goForwardTo( Place pNewPlace );
}