com.google.gwt.user.client.ui.Anchor Maven / Gradle / Ivy
/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.user.client.ui;
import com.google.gwt.dom.client.AnchorElement;
import com.google.gwt.dom.client.Document;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.Style.WhiteSpace;
import com.google.gwt.event.dom.client.ClickEvent;
import com.google.gwt.event.dom.client.ClickHandler;
import com.google.gwt.i18n.client.BidiUtils;
import com.google.gwt.i18n.client.HasDirection;
import com.google.gwt.i18n.shared.DirectionEstimator;
import com.google.gwt.i18n.shared.HasDirectionEstimator;
import com.google.gwt.safehtml.shared.SafeHtml;
import com.google.gwt.safehtml.shared.SafeUri;
import com.google.gwt.safehtml.shared.annotations.IsSafeHtml;
import com.google.gwt.safehtml.shared.annotations.IsSafeUri;
import com.google.gwt.safehtml.shared.annotations.SuppressIsSafeHtmlCastCheck;
/**
* A widget that represents a simple <a> element.
*
*
* If you want use this anchor only for changing history states, use
* {@link Hyperlink} instead.
*
*
*
*
Built-in Bidi Text Support
* This widget is capable of automatically adjusting its direction according to
* its content. This feature is controlled by {@link #setDirectionEstimator} or
* passing a DirectionEstimator parameter to the constructor, and is off by
* default.
*
*
* CSS Style Rules
*
* - .gwt-Anchor { }
*
*
* @see Hyperlink
*/
public class Anchor extends FocusWidget implements HasHorizontalAlignment,
HasName, HasHTML, HasWordWrap, HasDirection,
HasDirectionEstimator, HasDirectionalSafeHtml {
public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR =
DirectionalTextHelper.DEFAULT_DIRECTION_ESTIMATOR;
/**
* The default HREF is a no-op javascript statement. We need an href to ensure
* that the browser renders the anchor with native styles, such as underline
* and font color.
*/
private static final String DEFAULT_HREF = "javascript:;";
/**
* Creates an Anchor widget that wraps an existing <a> element.
*
* This element must already be attached to the document. If the element is
* removed from the document, you must call
* {@link RootPanel#detachNow(Widget)}.
*
* @param element the element to be wrapped
*/
public static Anchor wrap(Element element) {
// Assert that the element is attached.
assert Document.get().getBody().isOrHasChild(element);
Anchor anchor = new Anchor(element);
// Mark it attached and remember it for cleanup.
anchor.onAttach();
RootPanel.detachOnWindowClose(anchor);
return anchor;
}
private final DirectionalTextHelper directionalTextHelper;
private HorizontalAlignmentConstant horzAlign;
/**
* Creates an empty anchor.
*
*
* The anchor's href is not set, which means that the widget will not
* not be styled with the browser's native link styles (such as underline and
* font color). Use {@link #Anchor(boolean)} to add a default no-op href that
* does not open a link but ensures the native link styles are applied.
*
*
* @see #Anchor(boolean)
*/
public Anchor() {
this(false);
}
/**
* Creates an anchor.
*
* The anchor's href is optionally set to javascript:;, based on
* the expectation that listeners will be added to the anchor.
*
* @param useDefaultHref true to set the default href to
* javascript:;, false to leave it blank
*/
public Anchor(boolean useDefaultHref) {
setElement(Document.get().createAnchorElement());
setStyleName("gwt-Anchor");
directionalTextHelper = new DirectionalTextHelper(getAnchorElement(),
/* is inline */true);
if (useDefaultHref) {
setHref(DEFAULT_HREF);
}
// The following click handler is used to support users of CSP (Content
// Security Policy). When a CSP policy is in place, clicking on a link with
// the DEFAULT_HREF as the href can trigger a CSP violation. As a
// work-around, we prevent execution using preventDefault() when the href is
// set to DEFAULT_HREF.
if ("true".equals(System.getProperty("gwt.cspCompatModeEnabled"))) {
addClickHandler(new ClickHandler() {
@Override
public void onClick(ClickEvent event) {
if (DEFAULT_HREF.equals(getAnchorElement().getHref())) {
event.preventDefault();
}
}
});
}
}
/**
* Creates an anchor for scripting.
*
* @param html the anchor's html
*/
public Anchor(SafeHtml html) {
this(html.asString(), true);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript : ;, based on the
* expectation that listeners will be added to the anchor.
*
* @param html the anchor's html
* @param dir the html's direction
*/
public Anchor(SafeHtml html, Direction dir) {
this(html.asString(), true, dir, DEFAULT_HREF);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript : ;, based on the
* expectation that listeners will be added to the anchor.
*
* @param html the anchor's html
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
*/
public Anchor(SafeHtml html, DirectionEstimator directionEstimator) {
this(html.asString(), true, directionEstimator, DEFAULT_HREF);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript:;, based on the
* expectation that listeners will be added to the anchor.
*
* @param text the anchor's text
*/
public Anchor(String text) {
this(text, DEFAULT_HREF);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript : ;, based on the
* expectation that listeners will be added to the anchor.
*
* @param text the anchor's text
* @param dir the text's direction
*/
public Anchor(String text, Direction dir) {
this(text, dir, DEFAULT_HREF);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript : ;, based on the
* expectation that listeners will be added to the anchor.
*
* @param text the anchor's text
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
*/
public Anchor(String text, DirectionEstimator directionEstimator) {
this(text, directionEstimator, DEFAULT_HREF);
}
/**
* Creates an anchor for scripting.
*
* The anchor's href is set to javascript:;, based on the
* expectation that listeners will be added to the anchor.
*
* @param text the anchor's text
* @param asHtml true to treat the specified text as html
*/
public Anchor(@IsSafeHtml String text, boolean asHtml) {
this(text, asHtml, DEFAULT_HREF);
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, @IsSafeUri String href) {
this(html.asString(), true, href);
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, SafeUri href) {
this(html.asString(), true, href.asString());
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param dir the html's direction
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, Direction dir, @IsSafeUri String href) {
this(html.asString(), true, dir, href);
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param dir the html's direction
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, Direction dir, SafeUri href) {
this(html.asString(), true, dir, href.asString());
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, DirectionEstimator directionEstimator, @IsSafeUri String href) {
this(html.asString(), true, directionEstimator, href);
}
/**
* Creates an anchor with its html and href (target URL) specified.
*
* @param html the anchor's html
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
* @param href the url to which it will link
*/
public Anchor(SafeHtml html, DirectionEstimator directionEstimator,
SafeUri href) {
this(html.asString(), true, directionEstimator, href.asString());
}
/**
* Creates an anchor with its text and href (target URL) specified.
*
* @param text the anchor's text
* @param href the url to which it will link
*/
@SuppressIsSafeHtmlCastCheck
public Anchor(String text, @IsSafeUri String href) {
this(text, false, href);
}
/**
* Creates an anchor with its text and href (target URL) specified.
*
* @param text the anchor's text
* @param dir the text's direction
* @param href the url to which it will link
*/
@SuppressIsSafeHtmlCastCheck
public Anchor(String text, Direction dir, @IsSafeUri String href) {
this(text, false, dir, href);
}
/**
* Creates an anchor with its text and href (target URL) specified.
*
* @param text the anchor's text
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
* @param href the url to which it will link
*/
@SuppressIsSafeHtmlCastCheck
public Anchor(String text, DirectionEstimator directionEstimator, @IsSafeUri String href) {
this(text, false, directionEstimator, href);
}
/**
* Creates an anchor with its text and href (target URL) specified.
*
* @param text the anchor's text
* @param asHTML true to treat the specified text as html
* @param href the url to which it will link
*/
public Anchor(@IsSafeHtml String text, boolean asHTML, @IsSafeUri String href) {
this();
directionalTextHelper.setTextOrHtml(text, asHTML);
setHref(href);
}
/**
* Creates a source anchor (link to URI).
*
* That is, an anchor with an href attribute specifying the destination URI.
*
* @param html the anchor's html
* @param href the url to which it will link
* @param target the target frame (e.g. "_blank" to open the link in a new
* window)
*/
public Anchor(SafeHtml html, @IsSafeUri String href, String target) {
this(html.asString(), true, href, target);
}
/**
* Creates a source anchor (link to URI).
*
* That is, an anchor with an href attribute specifying the destination URI.
*
* @param html the anchor's html
* @param href the url to which it will link
* @param target the target frame (e.g. "_blank" to open the link in a new
* window)
*/
public Anchor(SafeHtml html, SafeUri href, String target) {
this(html.asString(), true, href.asString(), target);
}
/**
* Creates a source anchor with a frame target.
*
* @param text the anchor's text
* @param href the url to which it will link
* @param target the target frame (e.g. "_blank" to open the link in a new
* window)
*/
@SuppressIsSafeHtmlCastCheck
public Anchor(String text, @IsSafeUri String href, String target) {
this(text, false, href, target);
}
/**
* Creates a source anchor (link to URI).
*
* That is, an anchor with an href attribute specifying the destination URI.
*
* @param text the anchor's text
* @param asHtml asHTML true to treat the specified text as html
* @param href the url to which it will link
* @param target the target frame (e.g. "_blank" to open the link in a new
* window)
*/
public Anchor(@IsSafeHtml String text, boolean asHtml, @IsSafeUri String href, String target) {
this(text, asHtml, href);
setTarget(target);
}
/**
* This constructor may be used by subclasses to explicitly use an existing
* element. This element must be an <a> element.
*
* @param element the element to be used
*/
protected Anchor(Element element) {
AnchorElement.as(element);
setElement(element);
directionalTextHelper = new DirectionalTextHelper(getAnchorElement(),
/* is inline */ true);
}
/**
* Creates an anchor with its text, direction and href (target URL) specified.
*
* @param text the anchor's text
* @param asHTML true to treat the specified text as html
* @param dir the text's direction
* @param href the url to which it will link
*/
private Anchor(@IsSafeHtml String text, boolean asHTML, Direction dir, @IsSafeUri String href) {
this();
directionalTextHelper.setTextOrHtml(text, dir, asHTML);
setHref(href);
}
/**
* Creates an anchor with its text, direction and href (target URL) specified.
*
* @param text the anchor's text
* @param asHTML true to treat the specified text as html
* @param directionEstimator A DirectionEstimator object used for automatic
* direction adjustment. For convenience,
* {@link #DEFAULT_DIRECTION_ESTIMATOR} can be used.
* @param href the url to which it will link
*/
private Anchor(
@IsSafeHtml String text,
boolean asHTML,
DirectionEstimator directionEstimator,
@IsSafeUri String href) {
this();
directionalTextHelper.setDirectionEstimator(directionEstimator);
directionalTextHelper.setTextOrHtml(text, asHTML);
setHref(href);
}
@Override
public Direction getDirection() {
return BidiUtils.getDirectionOnElement(getElement());
}
@Override
public DirectionEstimator getDirectionEstimator() {
return directionalTextHelper.getDirectionEstimator();
}
@Override
public HorizontalAlignmentConstant getHorizontalAlignment() {
return horzAlign;
}
/**
* Gets the anchor's href (the url to which it links).
*
* @return the anchor's href
*/
public String getHref() {
return getAnchorElement().getHref();
}
@Override
public String getHTML() {
return getElement().getInnerHTML();
}
@Override
public String getName() {
return getAnchorElement().getName();
}
@Override
public int getTabIndex() {
return getAnchorElement().getTabIndex();
}
/**
* Gets the anchor's target frame (the frame in which navigation will occur
* when the link is selected).
*
* @return the target frame
*/
public String getTarget() {
return getAnchorElement().getTarget();
}
@Override
public String getText() {
return directionalTextHelper.getText();
}
@Override
public Direction getTextDirection() {
return directionalTextHelper.getTextDirection();
}
@Override
public boolean getWordWrap() {
return !WhiteSpace.NOWRAP.getCssName().equals(getElement().getStyle().getWhiteSpace());
}
@Override
public void setAccessKey(char key) {
getAnchorElement().setAccessKey(Character.toString(key));
}
/**
* @deprecated Use {@link #setDirectionEstimator} and / or pass explicit
* direction to {@link #setText}, {@link #setHTML} instead
*/
@Override
@Deprecated
public void setDirection(Direction direction) {
directionalTextHelper.setDirection(direction);
}
/**
* {@inheritDoc}
*
* See note at {@link #setDirectionEstimator(DirectionEstimator)}.
*/
@Override
public void setDirectionEstimator(boolean enabled) {
directionalTextHelper.setDirectionEstimator(enabled);
}
/**
* {@inheritDoc}
*
* Note: DirectionEstimator should be set before the widget has any content;
* it's highly recommended to set it using a constructor. Reason: if the
* widget already has non-empty content, this will update its direction
* according to the new estimator's result. This may cause flicker, and thus
* should be avoided.
*/
@Override
public void setDirectionEstimator(DirectionEstimator directionEstimator) {
directionalTextHelper.setDirectionEstimator(directionEstimator);
}
@Override
public void setFocus(boolean focused) {
if (focused) {
getAnchorElement().focus();
} else {
getAnchorElement().blur();
}
}
@Override
public void setHorizontalAlignment(HorizontalAlignmentConstant align) {
horzAlign = align;
getElement().getStyle().setProperty("textAlign", align.getTextAlignString());
}
/**
* Sets the anchor's href (the url to which it links).
*
* @param href the anchor's href
*/
public void setHref(SafeUri href) {
getAnchorElement().setHref(href);
}
/**
* Sets the anchor's href (the url to which it links).
*
* @param href the anchor's href
*/
public void setHref(@IsSafeUri String href) {
getAnchorElement().setHref(href);
}
@Override
public void setHTML(SafeHtml html) {
directionalTextHelper.setHtml(html);
}
@Override
public void setHTML(@IsSafeHtml String html) {
directionalTextHelper.setHtml(html);
}
@Override
public void setHTML(SafeHtml html, Direction dir) {
directionalTextHelper.setHtml(html, dir);
}
@Override
public void setName(String name) {
getAnchorElement().setName(name);
}
@Override
public void setTabIndex(int index) {
getAnchorElement().setTabIndex(index);
}
/**
* Sets the anchor's target frame (the frame in which navigation will occur
* when the link is selected).
*
* @param target the target frame
*/
public void setTarget(String target) {
getAnchorElement().setTarget(target);
}
@Override
public void setText(String text) {
directionalTextHelper.setText(text);
}
@Override
public void setText(String text, Direction dir) {
directionalTextHelper.setText(text, dir);
}
@Override
public void setWordWrap(boolean wrap) {
getElement().getStyle().setWhiteSpace(wrap ? WhiteSpace.NORMAL : WhiteSpace.NOWRAP);
}
private AnchorElement getAnchorElement() {
return AnchorElement.as(getElement());
}
}