001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.extensions.wizard;
018
019import org.apache.wicket.Component;
020import org.apache.wicket.util.io.IClusterable;
021
022/**
023 * Models one step in a wizard, and is the equivalent of one panel in a wizard from an end-user's
024 * perspective.
025 * <p>
026 * Typically, you would extend {@link WizardStep panel based wizard steps} and provide a custom
027 * panel for the step instead of directly implementing this interface.
028 * </p>
029 * 
030 * <p>
031 * <a href="https://wizard-framework.dev.java.net/">Swing Wizard Framework</a> served as a valuable
032 * source of inspiration.
033 * </p>
034 * 
035 * @author Eelco Hillenius
036 */
037public interface IWizardStep extends IClusterable
038{
039        /**
040         * Initializes this step with the model it will belong to.
041         * <p>
042         * This method is called at least once before this step becomes the actual step.
043         * 
044         * @param wizardModel
045         *            the owning wizard model
046         */
047        void init(IWizardModel wizardModel);
048        
049        /**
050         * Gets the header component for this step. This component is displayed in a special section of
051         * the wizard.
052         * <p>
053         * This method is called every time this step becomes the active step of the wizard.
054         * 
055         * @param id
056         *            The id that the component should be created with
057         * @param parent
058         *            The parent component (for post 1.2)
059         * @param wizard
060         *            The wizard component the header will be placed on
061         * @return The header component
062         */
063        Component getHeader(String id, Component parent, IWizard wizard);
064
065        /**
066         * Returns the current view this step is displaying. This component will be displayed in the
067         * main section of the wizard.
068         * <p>
069         * This method is called every time this step becomes the active step of the wizard.
070         * 
071         * @param id
072         *            The id that the component should be created with
073         * @param parent
074         *            The parent component (for post 1.2)
075         * @param wizard
076         *            The wizard component the header will be placed on
077         * @return The current view of the step.
078         */
079        Component getView(String id, Component parent, IWizard wizard);
080
081        /**
082         * This method is called whenever the wizard proceeds from this step to another step. It is not
083         * called when returning to a previous step.
084         * 
085         * @see IWizardModel#next() 
086         * @see IWizardModel#last() 
087         * @see IWizardModel#finish() 
088         */
089        void applyState();
090
091        /**
092         * Checks if this step is complete. This method should return {@code true} if the wizard can
093         * proceed to the next step.
094         * 
095         * @return {@code true} if the wizard can proceed from this step, {@code false} otherwise.
096         * 
097         * @see IWizardModel#next() 
098         * @see IWizardModel#last() 
099         * @see IWizardModel#finish() 
100         */
101        boolean isComplete();
102}