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
015package org.apache.tapestry.components;
016
017import org.apache.tapestry.IComponent;
018import org.apache.tapestry.IMarkupWriter;
019import org.apache.tapestry.IRequestCycle;
020import 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
030public 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}