package org.litesoft.sandbox.infrastructure.client;

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
     */
    public Place getWhere();

    /**
     * Request a change to a new place. 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
     */
    public GoToPlace goTo( Place pNewPlace );
}