001    /*
002     * Copyright (c) 2005, romain guy (romain.guy@jext.org) and craig wickesser (craig@codecraig.com)
003     * All rights reserved.
004     * 
005     * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
006     * 
007     *     * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
008     *     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
009     *     * Neither the name of the <ORGANIZATION> nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
010     * 
011     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
012     * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
013     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
014     * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
015     * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
016     * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
017     * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
018     * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
019     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
020     * POSSIBILITY OF SUCH DAMAGE.
021     */
022    
023    package net.java.swingfx.jdraggable;
024    
025    import java.awt.Component;
026    import java.awt.Container;
027    import java.awt.event.ContainerListener;
028    
029    
030    /**
031     * An interface which defines a manager whose responsibility is to enable
032     * dragging for {@link java.awt.Component}'s of a {@link java.awt.Container}
033     * which registers itself as the "draggable container"
034     * 
035     * @author craig
036     * @since v0.1
037     * <br>
038     * $Header: /cvs/swingfx/docs/api/src-html/net/java/swingfx/jdraggable/DraggableManager.html,v 1.1 2005/06/23 00:24:44 codecraig Exp $
039     */
040    public interface DraggableManager extends ContainerListener {
041            /**
042             * the state of the component is unknown
043             */
044            byte STATE_UNKNOWN      = 1 << 0;
045            /**
046             * the component is not being dragged
047             */
048            byte STATE_STILL        = 1 << 1;
049            /**
050             * the component is being dragged
051             */
052            byte STATE_DRAGGING = 1 << 2;
053    
054            /**
055             * Returns the {@link Container} which has been registered as the "draggable container"
056             * 
057             * @return      the <code>Container</code> which was registered as the "draggable container"
058             *                      or <code>null</code> if no <code>Container</code> is registered
059             */
060            Container getDraggableContainer();
061            
062            /**
063             * Called before a {@link Component} is actually dragged
064             * 
065             * @param componentToDrag       the component which was chosen to be dragged
066             * 
067             * @return      <code>true</code> if the "drag" can continue, <code>false</code> otherwise
068             */
069            boolean startDrag(Component componentToDrag);
070            
071            /**
072             * Called while the {@link Component} is being dragged
073             * 
074             * @return      <code>true</code> if the dragging can continue,
075             *                      <code>false</code> otherwise
076             */
077            boolean dragging();
078            
079            /**
080             * Called when a {@link Component} has stopped being dragged
081             * 
082             * @return      <code>true</code> if no errors occurred when the drag completed,
083             *                      <code>false</code> otherwise
084             */
085            boolean stopDrag();
086            
087            /**
088             * Registers the given {@link Container} with this manager to enable the
089             * container's {@link Draggable} components to be draggable
090             * 
091             * @param draggableContainer    the <code>Container</code> whose <code>Draggable</code>
092             *                                                              components should be able to be dragged
093             */
094            void registerDraggableContainer(Container draggableContainer);
095            
096            /**
097             * Un-Registers the given {@link Container} from this manager which stops
098             * this manager from managing the container
099             * 
100             * @param draggableContainer    the <code>Container</code> to unregister
101             */
102            void unregisterDraggableContainer(Container draggableContainer);
103            
104            /**
105             * Returns the state of the given {@link Draggable} component
106             * 
107             * @param draggableComponent    the <code>Draggable</code> whose state
108             *                                                              is of interest
109             * 
110             * @return      the state of <code>draggableComponent</code> as defined in this
111             *                      interface
112             * 
113             * @see #STATE_DRAGGING
114             * @see #STATE_STILL
115             * @see #STATE_UNKNOWN
116             */
117            byte getState(Draggable draggableComponent);
118            
119            /**
120             * Set the policy for which components are eligible for dragging
121             *      
122             * @param dragPolicy    the policy to set
123             * 
124             * @see #getDragPolicy()
125             * @see DragPolicy
126             */
127            void setDragPolicy(DragPolicy dragPolicy);
128            
129            /**
130             * Returns the {@link DragPolicy} for which this manager obides by
131             * 
132             * @return      the <code>DragPolicy</code> for this manager
133             * 
134             * @see #setDragPolicy(DragPolicy)
135             * @see DragPolicy
136             */
137            DragPolicy getDragPolicy();
138            
139            /**
140             * Returns the "nullify layout" value
141             * 
142             * @return      <code>true</code> to nullify the layout manager of the "draggable
143             *                      container", <code>false</code> otherwise
144             */
145            boolean shouldNullifyLayout();
146            
147            /**
148             * Sets whether the "draggable container" layout manager should be set to
149             * <code>null</code> once a component is dragged, or not.
150             * <br>
151             * By not setting the layout manager to <code>null</code>, the components
152             * may lose their "dragged" position if the container is resized.
153             * <br>
154             * By default this value is <code>true</code>
155             * 
156             * @param nullifyLayout <code>true</code> to nullify the layout manager,
157             *                                              <code>false</code> otherwise
158             */
159            void setNullifyLayout(boolean nullifyLayout);
160    }