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 }