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    
015    package org.apache.tapestry.components;
016    
017    import org.apache.tapestry.IComponent;
018    import org.apache.tapestry.IMarkupWriter;
019    import org.apache.tapestry.IRequestCycle;
020    import org.apache.tapestry.engine.ILink;
021    
022    /**
023     * A component that renders an HTML <a> element. It exposes some
024     * properties to the components it wraps. This is basically to facilitate the
025     * {@link org.apache.tapestry.html.Rollover} component.
026     * 
027     * @author Howard Lewis Ship
028     */
029    
030    public interface ILinkComponent extends IComponent
031    {
032    
033        /**
034         * Returns the desired scheme (i.e., "http" or "https") for the link, or
035         * null to not output a specific scheme (in which case the URL will fall
036         * under the incoming request's scheme).
037         * 
038         * @since 4.0
039         */
040    
041        String getScheme();
042    
043        /**
044         * Returns the desired port (i.e., "80" or "443") for the link, or null to
045         * not output a specific port (in which case the URL will fall under the
046         * incoming request's port).
047         * 
048         * @since 4.1
049         */
050    
051        Integer getPort();
052    
053        /**
054         * Returns whether this service link component is enabled or disabled.
055         * 
056         * @since 0.2.9
057         */
058    
059        boolean isDisabled();
060    
061        /**
062         * Returns the anchor defined for this link, or null for no anchor.
063         * 
064         * @since 3.0
065         */
066    
067        String getAnchor();
068    
069        /**
070         * Returns the name of the target window or frame for this link, or null if
071         * current window or frame is to be used.
072         * 
073         * @since 4.0
074         */
075        String getTarget();
076    
077        /**
078         * Adds a new event handler. When the event occurs, the JavaScript function
079         * specified is executed. Multiple functions can be specified, in which case
080         * all of them are executed.
081         * <p>
082         * This was created for use by {@link org.apache.tapestry.html.Rollover} to
083         * set mouse over and mouse out handlers on the {@link ILinkComponent} that
084         * wraps it, but can be used for many other things as well.
085         * 
086         * @since 0.2.9
087         */
088    
089        void addEventHandler(LinkEventType type, String functionName);
090    
091        /**
092         * Invoked by the {@link org.apache.tapestry.link.ILinkRenderer} (if the
093         * link is not disabled) to provide a
094         * {@link org.apache.tapestry.engine.EngineServiceLink} that the renderer
095         * can convert into a URL.
096         */
097    
098        ILink getLink(IRequestCycle cycle);
099    
100        /**
101         * Invoked (by the {@link org.apache.tapestry.link.ILinkRenderer}) to make
102         * the link render any additional attributes. These are informal parameters,
103         * plus any attributes related to events. This is only invoked for
104         * non-disabled links.
105         * 
106         * @since 3.0
107         */
108    
109        void renderAdditionalAttributes(IMarkupWriter writer,
110                IRequestCycle cycle);
111    }