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    }