Java tutorial
/* * 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.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; /** * A widget that represents a simple <a> element. * * <p> * If you want use this anchor only for changing history states, use * {@link Hyperlink} instead. * </p> * * <p> * <h3>Built-in Bidi Text Support</h3> * 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. * </p> * * <h3>CSS Style Rules</h3> * <ul class='css'> * <li>.gwt-Anchor { }</li> * </ul> * * @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. * * <p> * The anchor's href is <em>not</em> 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. * </p> * * @see #Anchor(boolean) */ public Anchor() { this(false); } /** * Creates an anchor. * * The anchor's href is optionally set to <code>javascript:;</code>, based on * the expectation that listeners will be added to the anchor. * * @param useDefaultHref true to set the default href to * <code>javascript:;</code>, 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); } } /** * 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 <code>javascript : ;</code>, 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 <code>javascript : ;</code>, 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 <code>javascript:;</code>, 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 <code>javascript : ;</code>, 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 <code>javascript : ;</code>, 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 <code>javascript:;</code>, based on the * expectation that listeners will be added to the anchor. * * @param text the anchor's text * @param asHtml <code>true</code> to treat the specified text as html */ public Anchor(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, 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 dir the html's direction * @param href the url to which it will link */ public Anchor(SafeHtml html, Direction dir, 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 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, String href) { this(html.asString(), true, directionEstimator, href); } /** * 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 */ public Anchor(String text, 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 */ public Anchor(String text, Direction dir, 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 */ public Anchor(String text, DirectionEstimator directionEstimator, 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 <code>true</code> to treat the specified text as html * @param href the url to which it will link */ public Anchor(String text, boolean asHTML, 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, String href, String target) { this(html.asString(), true, href, 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) */ public Anchor(String text, 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 <code>true</code> 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(String text, boolean asHtml, 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 <code>true</code> to treat the specified text as html * @param dir the text's direction * @param href the url to which it will link */ private Anchor(String text, boolean asHTML, Direction dir, 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 <code>true</code> 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(String text, boolean asHTML, DirectionEstimator directionEstimator, String href) { this(); directionalTextHelper.setDirectionEstimator(directionEstimator); directionalTextHelper.setTextOrHtml(text, asHTML); setHref(href); } public Direction getDirection() { return BidiUtils.getDirectionOnElement(getElement()); } public DirectionEstimator getDirectionEstimator() { return directionalTextHelper.getDirectionEstimator(); } 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(); } public String getHTML() { return getElement().getInnerHTML(); } 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(); } public String getText() { return directionalTextHelper.getTextOrHtml(false); } public Direction getTextDirection() { return directionalTextHelper.getTextDirection(); } public boolean getWordWrap() { return !getElement().getStyle().getProperty("whiteSpace").equals("nowrap"); } @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 */ @Deprecated public void setDirection(Direction direction) { directionalTextHelper.setDirection(direction); } /** * {@inheritDoc} * <p> * See note at {@link #setDirectionEstimator(DirectionEstimator)}. */ public void setDirectionEstimator(boolean enabled) { directionalTextHelper.setDirectionEstimator(enabled); } /** * {@inheritDoc} * <p> * 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. */ public void setDirectionEstimator(DirectionEstimator directionEstimator) { directionalTextHelper.setDirectionEstimator(directionEstimator); } @Override public void setFocus(boolean focused) { if (focused) { getAnchorElement().focus(); } else { getAnchorElement().blur(); } } 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(String href) { getAnchorElement().setHref(href); } public void setHTML(SafeHtml html) { setHTML(html.asString()); } public void setHTML(String html) { directionalTextHelper.setTextOrHtml(html, true); } public void setHTML(SafeHtml html, Direction dir) { directionalTextHelper.setTextOrHtml(html.asString(), dir, true); } 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); } public void setText(String text) { directionalTextHelper.setTextOrHtml(text, false); } public void setText(String text, Direction dir) { directionalTextHelper.setTextOrHtml(text, dir, false); } public void setWordWrap(boolean wrap) { getElement().getStyle().setProperty("whiteSpace", wrap ? "normal" : "nowrap"); } private AnchorElement getAnchorElement() { return AnchorElement.as(getElement()); } }