/*
 * $Id: ColumnControlPopup.java 4065 2011-08-19 13:28:26Z kleopatra $
 *
 * Copyright 2008 Sun Microsystems, Inc., 4150 Network Circle,
 * Santa Clara, California 95054, U.S.A. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package org.jdesktop.swingx.table;

import java.awt.ComponentOrientation;
import java.util.List;

import javax.swing.Action;
import javax.swing.JComponent;

import org.jdesktop.swingx.action.AbstractActionExt;
import org.jdesktop.swingx.plaf.UIDependent;

/**
 * Encapsulates the popup component which is the delegate for
 * all popup visuals, used by a ColumnControlButton.
 * <p>
 * For now, this class a simple extraction of what a ColumnControl needs. 
 * Usage will drive further evolution.
 * 
 */
public interface ColumnControlPopup extends UIDependent {
    /**
     * Toggles the popup's visibility. This method is responsible for
     * placing itself relative to the given owner if toggled to visible.
     * 
     * @param owner the JComponent which triggered the visibility change, typically
     *   a ColumnControlButton.
     */
    void toggleVisibility(JComponent owner);

    /**
     * Applies the specified component orientation to all internal widgets.
     * This method must be called by the owner if its component orientation 
     * changes. 
     * 
     * @param o the componentOrientation to apply to all internal widgets.
     * @see javax.swing.JComponent#applyComponentOrientation(ComponentOrientation).
     */
    void applyComponentOrientation(ComponentOrientation o);

    /**
     * Removes all items from the popup. 
     */
    void removeAll();

    /**
     * Adds items corresponding to the column's visibility actions.
     * <p>
     * Each <code>Action</code> in the list is a <code>stateAction</code>,
     * its <code>selected</code> property bound to a column's
     * <code>visible</code> property, that is toggling the selected will
     * toggle the column's visibility (if the action is enabled).
     * 
     * The  <code>Action</code>s <code>name</code> property is bound to 
     * the column's <code>title</code>.
     * 
     * @param actions List of AbstractActionExt to add.
     */
    void addVisibilityActionItems(List<? extends AbstractActionExt> actions);
    // JW: dooohhh ... what a winding description ...
    // sure need to have a better abstraction! 
    // 
    
    /**
     * Adds additional actions to the popup. 
     * 
     * @param actions List of <code>Action</code>s to add to the popup.
     */
    void addAdditionalActionItems(List<? extends Action> actions);
    
    /**
     * Splits and returns a List of actions into sub-lists. 
     */
    public interface ActionGrouper {
        <A extends Action> List<List<A>> group(List<A> actions);
    }
    
    /**
     * Interface indicating support for grouping of menu actions.
     * Implementations of ColumnControlPopup may implement this 
     * if they support grouping of additional action.
     */
    public interface ActionGroupable {
        public void setActionGrouper(ActionGrouper grouper);
    }
    

}