Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||||
IEventListener |
|
| 1.0;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 basic component id. |
|
147 | * @param idPath |
|
148 | * The id of the component pre-pended with the path of components containing it. |
|
149 | */ |
|
150 | void rewireComponentId(String componentId, String idPath); |
|
151 | } |