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