package org.litesoft.sandbox.infrastructure.client;

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

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

    /**
     * Optional delegate in charge of Window-related events. Provides nice
     * isolation for unit testing, and allows customization of confirmation
     * handling.
     */
    public interface Delegate
    {
        /**
         * Adds a {@link Window.ClosingHandler} to the Delegate.
         *
         * @param pHandler a {@link Window.ClosingHandler} instance
         *
         * @return a {@link HandlerRegistration} instance
         */
        HandlerRegistration addWindowClosingHandler( Window.ClosingHandler pHandler );

        /**
         * Called to confirm a window closing event.
         *
         * @param pMessage a warning message
         *
         * @return true to allow the window closing
         */
        boolean confirm( String pMessage );
    }

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