com.shipdream.lib.android.mvc.controller.NavigationController Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of android-mvc-controller Show documentation
Controller module for AndroidMvc Framework. It doesn't depend on Android SDK thus app controller module depending on this module would do jUnit test easily on pure JVM.
There is a newer version: 2.2.0
Show newest version
/*
 * Copyright 2015 Kejun Xia
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.shipdream.lib.android.mvc.controller;

import com.shipdream.lib.android.mvc.NavLocation;
import com.shipdream.lib.android.mvc.event.ValueChangeEventC2V;

/**
 * Controller to navigate among different fragments in the SAME activity.
 */
public interface NavigationController extends BaseController {
    /**
     * Navigate to a new location. Current location will be saved/stacked into history which can be
     * popped out by {@link #navigateBack(Object, String)} or {@link #navigateTo(Object, String, String)}.
     * Navigation only takes effect when the given locationId is different from the current location
     * and raises {@link EventC2V.OnLocationForward}
     *
     * @param sender     Who wants to navigate
     * @param locationId The id of the location navigate to
     */
    void navigateTo(Object sender, String locationId);

    /**
     * Navigates to a new location and exclusively clears history prior to the given
     * clearTopToLocationId (clearTopToLocationId will be second last location below given location).
     * When clearTopToLocationId is null, it clears all history. In other words, the current given
     * location will be the only location in the history stack and all other previous locations
     * will be cleared. Navigation only takes effect when the given locationId is different from the
     * current location and raises {@link EventC2V.OnLocationForward}
     *
     * @param sender               Who wants to navigate
     * @param locationId           The id of the location navigate to
     * @param clearTopToLocationId Null if all history locations want to be cleared otherwise, the
     *                             id of the location the history will be exclusively cleared up to
     *                             which will be the second last location after navigation.
     */
    void navigateTo(Object sender, String locationId, String clearTopToLocationId);

    /**
     * Navigates back. If current location is null it doesn't take any effect otherwise
     * raises a {@link EventC2V.OnLocationBack} event when there is a previous location.
     *
     * @param sender Who wants to navigate back
     */
    void navigateBack(Object sender);

    /**
     * Navigates back. If current location is null it doesn't take any effect. When toLocationId
     * is null, navigate to the very first location and clear all history prior to it, otherwise
     * navigate to location with given locationId and clear history prior to it. Then a
     * {@link EventC2V.OnLocationBack} event will be raised.
     *
     * @param sender       Who wants to navigate
     * @param toLocationId Null when needs to navigate to the very first location and all history
     *                     locations will be above it will be cleared. Otherwise, the id of the
     *                     location where the history will be exclusively cleared up to. Then this
     *                     location will be the second last one.
     */
    void navigateBack(Object sender, String toLocationId);

    interface EventC2V {
        /**
         * Event to notify views navigation will move forward.
         */
        class OnLocationForward extends ValueChangeEventC2V {
            private boolean clearHistory;
            private NavLocation locationWhereHistoryClearedUpTo;

            /**
             * Construct event to notify views navigation will move forward.
             * @param sender Who wanted to navigate
             * @param lastValue The previous location before the navigation
             * @param currentValue The location navigating to
             * @param clearHistory Whether or not need to clear history locations
             * @param locationWhereHistoryClearedUpTo If need to clear location, up to where
             */
            public OnLocationForward(Object sender, NavLocation lastValue, NavLocation currentValue,
                                     boolean clearHistory, NavLocation locationWhereHistoryClearedUpTo) {
                super(sender, lastValue, currentValue);
                this.clearHistory = clearHistory;
                this.locationWhereHistoryClearedUpTo = locationWhereHistoryClearedUpTo;
            }

            /**
             * Indicates whether to clear some history locations
             */
            public boolean isClearHistory() {
                return clearHistory;
            }

            /**
             * The location where the history will be cleared up to. In other words, this location
             * will be the second last location underneath the top most one.
             *
             * @return The location where the history will be exclusively cleared up to
             */
            public NavLocation getLocationWhereHistoryClearedUpTo() {
                return locationWhereHistoryClearedUpTo;
            }
        }

        /**
         * Event to notify views navigation will move backward.
         */
        class OnLocationBack extends ValueChangeEventC2V {
            private boolean fastRewind;

            public OnLocationBack(Object sender, NavLocation lastValue, NavLocation currentValue,
                                  boolean fastRewind) {
                super(sender, lastValue, currentValue);
                this.fastRewind = fastRewind;
            }

            /**
             * Indicates will this navigation jump more then 1 step
             */
            public boolean isFastRewind() {
                return fastRewind;
            }
        }
    }

    class Model {
        private NavLocation currentLocation;

        public NavLocation getCurrentLocation() {
            return currentLocation;
        }

        public void setCurrentLocation(NavLocation currentLocation) {
            this.currentLocation = currentLocation;
        }
    }

}