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 com.google.gwt.user.client.ui.Widget;
019    
020    /**
021     * A pluggable event handler which processes delegated events from
022     * {@link com.google.gwt.user.client.ui.Widget#onBrowserEvent(com.google.gwt.user.client.Event)
023     * Widget.onBrowserEvent(Event)}. Controllers are typically created via a
024     * factory method in the widget. Controllers can be added to and removed from
025     * the widget at any time by calling {@link #plugIn(Widget)} and
026     * {@link #unplug(Widget)}.
027     * <p>
028     * Controllers can be used to:
029     * <ul>
030     * <li>encapsulate browser behavioral differences (controller implementation
031     * class can be instantiated via GWT.create())</li>
032     * <li>install hooks for unsupported events (e.g. onselectstart)</li>
033     * <li>handle dependencies</li>
034     * <li>cancel events</li>
035     * <li>track state of input operations (e.g. mouse state for drag operation)</li>
036     * </ul>
037     * <p>
038     * Usage notes:
039     * <ul>
040     * <li>controllers should only be notified of events which are declared by 
041     * {@link asquare.gwt.tk.client.ui.behavior.EventDelegate#getEventBits() getEventBits()}</li>
042     * <li>controller notification order indeterminate</li>
043     * <li>controllers instantiated via deferred binding must have a default
044     * constructor</li>
045     * <li>stateless controllers can be shared</li>
046     * </ul>
047     */
048    public interface Controller extends EventDelegate
049    {
050            /**
051             * Get the id of this controller. Used for looking up a controller in a
052             * collection. Controllers with a single implementation will return the
053             * class of the controller. Controllers with multiple implementations will
054             * return the class of the interface or base class.
055             */
056            public Class getId();
057    
058            /**
059             * Called when the widget is attached to the DOM. Use to initialize widget,
060             * install special hooks and attach listeners. 
061             * 
062             * @param widget the view to control
063             */
064            void plugIn(Widget widget);
065            
066            /**
067             * Called when the widget is detached from the DOM. Use to remove listeners
068             * and null out any references set on the DOM.
069             * 
070             * @param widget
071             */
072            void unplug(Widget widget);
073    }