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 java.lang.annotation.Documented;
017    import java.lang.annotation.ElementType;
018    import java.lang.annotation.Retention;
019    import java.lang.annotation.RetentionPolicy;
020    import java.lang.annotation.Target;
021    
022    /**
023     * Annotation used to connect an event on a component / page 
024     * with a particular listener method. This is currently intended
025     * to be used to connect client side events to listener methods but
026     * may have uses elsewhere.
027     * 
028     * @author jkuhnert
029     */
030    @Target({ ElementType.METHOD })
031    @Retention(RetentionPolicy.RUNTIME)
032    @Documented
033    public @interface EventListener
034    {
035        /**
036         * The unique {@link IComponent} ids of the targeted 
037         * sources that this listener will be listening to events on. 
038         */
039        String[] targets() default {};
040        
041        /**
042         * The unique html element ids to listen to the events on.
043         */
044        String[] elements() default {};
045        
046        /**
047         * The list of events that should cause this listener to invoke. 
048         * Ie <code>events = {"onClick", "onOptionSelect"}</code> etc..
049         */
050        String[] events();
051        
052        /**
053         * The form id of the form that should have its data submitted when one 
054         * of the specified events is triggered.
055         * @return
056         */
057        String submitForm() default "";
058        
059        /**
060         * Whether or not to perform form validation if the {@link #form()} parameter has 
061         * been set. Default is false.
062         * @return
063         */
064        boolean validateForm() default false;
065        
066        /**
067         * If used in conjunction with {@link #submitForm()}, will either submit the form
068         * normally or asynchronously. Default is asyncrhonous. 
069         * 
070         * @return True if form should be submitted asynchronously, false otherwise.
071         */
072        boolean async() default true;
073    }