/*
 * Copyright 2007-2010 Enrico Boldrini, Lorenzo Bigagli This file is part of
 * CheckboxTree. CheckboxTree is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version. CheckboxTree is distributed in the hope that it
 * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License for more details. You should have received a copy of the GNU
 * General Public License along with CheckboxTree; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA
 */
package it.cnr.imaa.essi.lablib.gui.checkboxtree;

import javax.swing.tree.TreePath;

/**
 * The interface of a model for checking/unchecking the nodes of a CheckboxTree.
 * Alterations of a node state may propagate to descendants/ancestors, according
 * to the behaviour of the checking model. See CheckingMode for the available
 * behaviours.
 * 
 * @author bigagli
 * @author boldrini
 */
public interface TreeCheckingModel {

    /**
     * The checking behaviours provided by this class.
     * 
     * @author boldrini
     */
    public enum CheckingMode {
	/*
	 * TODO: this should be moved to DefaultTreeCheckingModel, together with TreeCheckingMode
	 */

	/**
	 * Toggles the clicked checkbox and propagates the change down. In other
	 * words, if the clicked checkbox becomes checked, all the descendants
	 * will be checked; otherwise, all the descendants will be unchecked.
	 */
	PROPAGATE,

	/**
	 * Propagates the change not only to descendants but also to ancestors.
	 * With regard to descendants this mode behaves exactly like the
	 * Propagate mode. With regard to ancestors it checks/unchecks them as
	 * needed so that a node is checked if and only if all of its children
	 * are checked.
	 */
	PROPAGATE_PRESERVING_CHECK,

	/**
	 * Propagates the change not only to descendants but also to ancestors.
	 * With regard to descendants this mode behaves exactly like the
	 * Propagate mode. With regard to ancestors it checks/unchecks them as
	 * needed so that a node is unchecked if and only if all of its children
	 * are unchecked.
	 */
	PROPAGATE_PRESERVING_UNCHECK,

	/**
	 * The change is propagated to descendants like in the PROPAGATE mode.
	 * Moreover, if the checkbox becomes unchecked, all the ancestors will
	 * be unchecked.
	 */
	PROPAGATE_UP_UNCHECK,

	/**
	 * The check is not propagated at all, toggles the clicked checkbox
	 * only.
	 */
	SIMPLE,

	/**
	 * The check is not propagated at all, toggles the clicked checkbox
	 * only. Only one checkbox is allowed to be checked at any given time.
	 */
	SINGLE
    }

    /**
     * add a path to the checked paths set
     * 
     * @param path the path to be added.
     */
    public void addCheckingPath(TreePath path);

    /**
     * add paths to the checked paths set
     * 
     * @param paths the paths to be added.
     */
    public void addCheckingPaths(TreePath[] paths);

    /**
     * Adds the specified listener to the list of listeners that are notified
     * each time the set of checking TreePaths changes.
     * 
     * @param x the new listener to be added
     */
    public void addTreeCheckingListener(TreeCheckingListener x);

    /**
     * Clears the checking.
     */
    public void clearChecking();

    /**
     * @return Returns the CheckingMode.
     */
    public CheckingMode getCheckingMode();

    /**
     * @return Returns the paths that are in the checking set.
     */
    public TreePath[] getCheckingPaths();

    /**
     * @return Returns the paths that are in the checking set and are the
     *         (upper) roots of checked trees.
     */
    public TreePath[] getCheckingRoots();

    /**
     * @return Returns the paths that are in the greying set.
     */
    public TreePath[] getGreyingPaths();

    /**
     * Returns true if the item identified by the path is currently checked.
     * 
     * @param path a <code>TreePath</code> identifying a node
     * @return true if the node is checked
     */
    public boolean isPathChecked(TreePath path);

    /**
     * Returns whether the specified path checking state can be toggled.
     */
    public boolean isPathEnabled(TreePath path);

    /**
     * Returns whether the specified path is greyed.
     */
    public boolean isPathGreyed(TreePath path);

    /**
     * remove a path from the checked paths set
     * 
     * @param path the path to be added.
     */
    public void removeCheckingPath(TreePath path);

    /**
     * remove paths from the checked paths set
     * 
     * @param paths the paths to be added.
     */
    public void removeCheckingPaths(TreePath[] paths);

    /**
     * Removes x from the list of listeners that are notified each time the set
     * of checking TreePaths changes.
     * 
     * @param x the listener to remove
     */
    public void removeTreeCheckingListener(TreeCheckingListener x);

    /**
     * Set the checking mode.
     * 
     * @param mode The checkingMode to set.
     */
    public void setCheckingMode(CheckingMode mode);

    /**
     * Set the checking to path.
     */
    public void setCheckingPath(TreePath path);

    /**
     * Set the checking to paths.
     */
    public void setCheckingPaths(TreePath[] paths);

    /**
     * Sets whether or not the path is enabled.
     * 
     * @param path the path to enable/disable
     */
    public void setPathEnabled(TreePath path, boolean enable);

    /**
     * Sets whether or not the paths are enabled.
     * 
     * @param paths the paths to enable/disable
     */
    public void setPathsEnabled(TreePath[] paths, boolean enable);

    /**
     * Alter (check/uncheck) the checking state of the specified path if
     * possible and also propagate the new state if needed by the mode.
     */
    public void toggleCheckingPath(TreePath pathForRow);

}