001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    package org.apache.tapestry.spec;
015    
016    import org.apache.tapestry.IComponent;
017    import org.apache.tapestry.IForm;
018    import org.apache.tapestry.event.BrowserEvent;
019    import org.apache.tapestry.internal.event.ComponentEventProperty;
020    import org.apache.tapestry.internal.event.EventBoundListener;
021    
022    import java.util.Map;
023    
024    
025    /**
026     * Specification for something that can listen to and act on client side generated
027     * browser events.
028     *
029     */
030    public interface IEventListener
031    {
032        /**
033         * Adds a deferred event listener binding for the specified component.
034         * 
035         * @param componentId 
036         *          The component this is for.
037         * @param events
038         *          The events that should cause the listener to be executed.
039         * @param methodName
040         *          The page/component listener name that should be executed when
041         *          one of the supplied events occurs.
042         * @param formId
043         *          The optional id of the form that should be submitted as part of this event invocation.
044         * @param validateForm
045         *          If a formId was specified, whether or not that form should have client side valiation
046         *          invoked during the process.
047         * @param async 
048         *          If submitting a form, whether or not to do it asynchronously.
049         * @param focus
050         *          If submitting a form, controls whether or not to focus it after an update.
051         * @param autoSubmit
052         *          If true - auto form wiring is performed on any component targets implementing {@link org.apache.tapestry.form.IFormComponent} so
053         *          that the enclosing form is submitted as part of the event in order to maintain consistent form state as in normal listener method
054         *          invocations.
055         */
056        void addEventListener(String componentId, String[] events, String methodName,
057                              String formId, boolean validateForm, boolean async, boolean focus, boolean autoSubmit);
058        
059        /**
060         * Adds a deferred event listener binding for the specified html element.
061         * 
062         * @param elementId
063         *          The client side html element id to match against.
064         * @param events
065         *          The client side events to bind to.
066         * @param methodName
067         *          The listener that should be invoked when the event happens.
068         * @param formId
069         *          The optional id of the form that should be submitted as part of this event invocation.
070         * @param validateForm
071         *          If a formId was specified, whether or not that form should have client side valiation
072         *          invoked during the process.
073         * @param async 
074         *          If submitting a form, whether or not to do it asynchronously.
075         * @param focus
076         *          If submitting a form, controls whether or not to focus it after an update.
077         */
078        void addElementEventListener(String elementId, String[] events, 
079                String methodName, String formId, boolean validateForm, boolean async, boolean focus);
080    
081        /**
082         * Invoked during rendering when a component has been detected as a {@link org.apache.tapestry.form.IFormComponent} and may
083         * possibly need its events to be wired up as form events.
084         *
085         * @param component The component to rewire form events for.
086         * @param form The form containing the component.
087         */
088        void connectAutoSubmitEvents(IComponent component, IForm form);
089    
090        /**
091         * Checks if any element events are bound to this component.
092         * 
093         * @return True if any element events are mapped from this component.
094         */
095        boolean hasElementEvents();
096        
097        /**
098         * Gets component bound event properties.
099         * 
100         * @param componentId The component to get event listeners for.
101         * @return The bound component event property container, or null if none exist.
102         */
103        ComponentEventProperty getComponentEvents(String componentId);
104        
105        /**
106         * Gets element bound event properties.
107         * 
108         * @param elementId The element to get listeners for.
109         * @return The bound element event property container, or null if none exist.
110         */
111        ComponentEventProperty getElementEvents(String elementId);
112        
113        /**
114         * Returns a list of element / component bound event listeners that were specified
115         * as invoking the form component with a matching id to <code>formId</code> of type
116         * {@link EventBoundListener} .
117         * 
118         * @param formId
119         *          The form that the event listeners were bound to submit when the event occurs.
120         * @param event
121         *           The event that caused the current invocation.
122         * 
123         * @return A list of events bound to the specified form, empty if none exist.
124         */
125        EventBoundListener[] getFormEvents(String formId, BrowserEvent event);
126        
127        /**
128         * Gets all mapped element events for this component.
129         * 
130         * @return Mapped elements events, if any.
131         */
132        Map getElementEvents();
133    
134        /**
135         * Gets all component event mappings.
136         *
137         * @return Map of component {@link ComponentEventProperty} values this component is listening to.
138         */
139        Map getComponentEvents();
140    
141        /**
142         * Invoked during page load to map event connections previously made via the {@link org.apache.tapestry.IComponent#getId()} identifier
143         * to use the more unique {@link org.apache.tapestry.IComponent#getIdPath()}.
144         *
145         * @param componentId
146         *          The base component id.
147         * @param extendedId
148         *          The id of the component as returned by {@link org.apache.tapestry.IComponent#getExtendedId()}
149         * @param idPath
150         *          The id of the component as returned by {@link org.apache.tapestry.IComponent#getIdPath()} 
151         */
152        void rewireComponentId(String componentId, String extendedId, String idPath);
153    }