Coverage Report - org.apache.tapestry.spec.IEventListener
 
Classes in this File Line Coverage Branch Coverage Complexity
IEventListener
N/A
N/A
1
 
 1  
 // Copyright 2004, 2005 The Apache Software Foundation
 2  
 //
 3  
 // Licensed under the Apache License, Version 2.0 (the "License");
 4  
 // you may not use this file except in compliance with the License.
 5  
 // You may obtain a copy of the License at
 6  
 //
 7  
 //     http://www.apache.org/licenses/LICENSE-2.0
 8  
 //
 9  
 // Unless required by applicable law or agreed to in writing, software
 10  
 // distributed under the License is distributed on an "AS IS" BASIS,
 11  
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12  
 // See the License for the specific language governing permissions and
 13  
 // limitations under the License.
 14  
 package org.apache.tapestry.spec;
 15  
 
 16  
 import org.apache.tapestry.IComponent;
 17  
 import org.apache.tapestry.IForm;
 18  
 import org.apache.tapestry.event.BrowserEvent;
 19  
 import org.apache.tapestry.internal.event.ComponentEventProperty;
 20  
 import org.apache.tapestry.internal.event.EventBoundListener;
 21  
 
 22  
 import java.util.Map;
 23  
 
 24  
 
 25  
 /**
 26  
  * Specification for something that can listen to and act on client side generated
 27  
  * browser events.
 28  
  *
 29  
  */
 30  
 public interface IEventListener
 31  
 {
 32  
     /**
 33  
      * Adds a deferred event listener binding for the specified component.
 34  
      * 
 35  
      * @param componentId 
 36  
      *          The component this is for.
 37  
      * @param events
 38  
      *          The events that should cause the listener to be executed.
 39  
      * @param methodName
 40  
      *          The page/component listener name that should be executed when
 41  
      *          one of the supplied events occurs.
 42  
      * @param formId
 43  
      *          The optional id of the form that should be submitted as part of this event invocation.
 44  
      * @param validateForm
 45  
      *          If a formId was specified, whether or not that form should have client side valiation
 46  
      *          invoked during the process.
 47  
      * @param async 
 48  
      *          If submitting a form, whether or not to do it asynchronously.
 49  
      * @param focus
 50  
      *          If submitting a form, controls whether or not to focus it after an update.
 51  
      * @param autoSubmit
 52  
      *          If true - auto form wiring is performed on any component targets implementing {@link org.apache.tapestry.form.IFormComponent} so
 53  
      *          that the enclosing form is submitted as part of the event in order to maintain consistent form state as in normal listener method
 54  
      *          invocations.
 55  
      */
 56  
     void addEventListener(String componentId, String[] events, String methodName,
 57  
                           String formId, boolean validateForm, boolean async, boolean focus, boolean autoSubmit);
 58  
     
 59  
     /**
 60  
      * Adds a deferred event listener binding for the specified html element.
 61  
      * 
 62  
      * @param elementId
 63  
      *          The client side html element id to match against.
 64  
      * @param events
 65  
      *          The client side events to bind to.
 66  
      * @param methodName
 67  
      *          The listener that should be invoked when the event happens.
 68  
      * @param formId
 69  
      *          The optional id of the form that should be submitted as part of this event invocation.
 70  
      * @param validateForm
 71  
      *          If a formId was specified, whether or not that form should have client side valiation
 72  
      *          invoked during the process.
 73  
      * @param async 
 74  
      *          If submitting a form, whether or not to do it asynchronously.
 75  
      * @param focus
 76  
      *          If submitting a form, controls whether or not to focus it after an update.
 77  
      */
 78  
     void addElementEventListener(String elementId, String[] events, 
 79  
             String methodName, String formId, boolean validateForm, boolean async, boolean focus);
 80  
 
 81  
     /**
 82  
      * Invoked during rendering when a component has been detected as a {@link org.apache.tapestry.form.IFormComponent} and may
 83  
      * possibly need its events to be wired up as form events.
 84  
      *
 85  
      * @param component The component to rewire form events for.
 86  
      * @param form The form containing the component.
 87  
      */
 88  
     void connectAutoSubmitEvents(IComponent component, IForm form);
 89  
 
 90  
     /**
 91  
      * Checks if any element events are bound to this component.
 92  
      * 
 93  
      * @return True if any element events are mapped from this component.
 94  
      */
 95  
     boolean hasElementEvents();
 96  
     
 97  
     /**
 98  
      * Gets component bound event properties.
 99  
      * 
 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  
 }