001    /*
002     * Copyright 2006 Mat Gessel <mat.gessel@gmail.com>
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005     * use this file except in compliance with the License. You may obtain a copy of
006     * the License at
007     * 
008     * http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013     * License for the specific language governing permissions and limitations under
014     * the License.
015     */
016    package asquare.gwt.tk.client.ui.behavior;
017    
018    import java.util.List;
019    
020    import com.google.gwt.user.client.EventListener;
021    import com.google.gwt.user.client.ui.Widget;
022    
023    /**
024     * An interface implemented by widgets which support event handling via
025     * controllers.
026     */
027    public interface ControllerSupport extends EventListener
028    {
029            /**
030             * Sets the controllers which will process events on this widget. Clears out
031             * the current controllers, if any. When the widget is added to the DOM,
032             * received events will be delegated to each controller which declares the
033             * event's type via 
034             * {@link asquare.gwt.tk.client.ui.behavior.EventDelegate#getEventBits() getEventBits()}.
035             * 
036             * @param controllers a list of 0 or more controllers, or <code>null</code>
037             */
038            void setControllers(List controllers);
039            
040            /**
041             * Gets a controller with the specified id. The id is often an interface or
042             * base class, as controllers can have multiple implementations. Used to
043             * modify the behavior of existing widgets. 
044             * 
045             * @param id a Class identifying the type of controller to get
046             * @return the first controller matching the id, or <code>null</code>
047             */
048            Controller getController(Class id);
049            
050            /**
051             * Adds a controller to process events on this widget. Multiple controllers
052             * may be added.
053             * 
054             * @param controller a controller to add
055             * @return the widget this call was made on (for convenience)
056             */
057            Widget addController(Controller controller);
058            
059            /**
060             * Removes a controller
061             * 
062             * @param controller a controller to remove
063             * @return the widget this call was made on (for convenience)
064             * @throws IllegalArgumentException if <code>controller</code> is not present
065             */
066            Widget removeController(Controller controller);
067    }