001 // Copyright May 14, 2006 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.annotations; 015 016 import org.apache.tapestry.IComponent; 017 018 import java.lang.annotation.*; 019 020 /** 021 * Annotation used to connect an event on a component / page with a particular listener method. This 022 * is currently intended to be used to connect client side events to listener methods but may have 023 * uses elsewhere. 024 * 025 */ 026 @Target( { ElementType.METHOD }) 027 @Retention(RetentionPolicy.RUNTIME) 028 @Documented 029 public @interface EventListener 030 { 031 032 /** 033 * The unique {@link IComponent} ids of the targeted sources that this listener will be 034 * listening to events on. 035 */ 036 String[] targets() default {}; 037 038 /** 039 * The unique html element ids to listen to the events on. 040 */ 041 String[] elements() default {}; 042 043 /** 044 * The list of events that should cause this listener to invoke. Ie 045 * <code>events = {"onClick", "onOptionSelect"}</code> etc.. 046 */ 047 String[] events(); 048 049 /** 050 * The form id of the form that should have its data submitted when one of the specified events 051 * is triggered. 052 * 053 * @return The form name (or id of component) to submit when event is triggered. 054 */ 055 String submitForm() default ""; 056 057 /** 058 * When any of the components targeted for an event is an instance of {@link org.apache.tapestry.form.IFormComponent} this 059 * setting can allow the form to be automatically discovered when wiring this listener up to the event such that it is 060 * submitted for you automatically without having to specify a {@link #submitForm()} parameter. The default is true. 061 * 062 * @return True if {@link org.apache.tapestry.form.IFormComponent}s should submit their containing forms by default, false otherwise. 063 */ 064 boolean autoSubmit() default true; 065 066 /** 067 * Whether or not to perform form validation if the {@link #submitForm()} parameter has been set. 068 * Default is false. 069 * 070 * @return Whether or not to validate the form. 071 */ 072 boolean validateForm() default false; 073 074 /** 075 * Controls whether or not any forms being submitted as part of this event will request focus 076 * as per normal form semantics. The default is false. 077 * 078 * @return True if the form should get focus, false otherwise. The default is false. 079 */ 080 boolean focus() default false; 081 082 /** 083 * If used in conjunction with {@link #submitForm()} <i>(or just targeting a {@link org.apache.tapestry.form.IFormComponent})</i>, 084 * will either submit the form normally or asynchronously. Default is asyncrhonous. 085 * 086 * @return True if form should be submitted asynchronously, false otherwise. 087 */ 088 boolean async() default true; 089 }