com.google.gwt.user.client.ui

## Class Hyperlink

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.Hyperlink

All Implemented Interfaces:
  HasClickHandlers, HasAttachHandlers, HasHandlers, HasDirectionEstimator, HasSafeHtml, EventListener, HasDirectionalSafeHtml, HasDirectionalText, HasHTML, HasText, HasVisibility, IsWidget, SourcesClickEvents

Direct Known Subclasses:
  InlineHyperlink

    public class Hyperlink
    extends Widget
    implements HasHTML, SourcesClickEvents, HasClickHandlers, HasDirectionEstimator, HasDirectionalSafeHtml

A widget that serves as an "internal" hyperlink. That is, it is a link to another state of the running application. When clicked, it will create a new history frame using `History.newItem(java.lang.String)`, but without reloading the page.

If you want an HTML hyperlink (<a> tag) without interacting with the history system, use `Anchor` instead.

Being a true hyperlink, it is also possible for the user to "right-click, open link in new window", which will cause the application to be loaded in a new window at the state specified by the hyperlink.

### Built-in Bidi Text Support

This widget is capable of automatically adjusting its direction according to its content. This feature is controlled by `setDirectionEstimator(boolean)` or passing a DirectionEstimator parameter to the constructor, and is off by default.

### CSS Style Rules

- .gwt-Hyperlink { }

### Example

>     public class HistoryExample implements EntryPoint, ValueChangeHandler<String> {

>       private Label lbl = new Label();

>       public void onModuleLoad() {
>         // Create three hyperlinks that change the application's history.
>         Hyperlink link0 = new Hyperlink("link to foo", "foo");
>         Hyperlink link1 = new Hyperlink("link to bar", "bar");
>         Hyperlink link2 = new Hyperlink("link to baz", "baz");

>         // If the application starts with no history token, redirect to a new
>         // 'baz' state.
>         String initToken = History.getToken();
>         if (initToken.length() == 0) {
>           History.newItem("baz");
>         }

>         // Add widgets to the root panel.
>         VerticalPanel panel = new VerticalPanel();
>         panel.add(lbl);
>         panel.add(link0);
>         panel.add(link1);
>         panel.add(link2);
>         RootPanel.get().add(panel);

>         // Add history listener
>         History.addValueChangeHandler(this);

>         // Now that we've setup our listener, fire the initial history state.
>         History.fireCurrentHistoryState();
>       }

>       public void onValueChange(ValueChangeEvent<String> event) {
>         // This method is called whenever the application's history changes. Set
>         // the label to reflect the current history token.
>         lbl.setText("The current history token is: " + event.getValue());
>       }
>     }

See Also:
  `Anchor`

### Nested Class Summary

### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

`UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

### Field Summary

Fields
`static DirectionEstimator` `DEFAULT_DIRECTION_ESTIMATOR`
`protected DirectionalTextHelper` `directionalTextHelper`

### Fields inherited from class com.google.gwt.user.client.ui.Widget

`eventsToSink`

### Fields inherited from class com.google.gwt.user.client.ui.UIObject

`DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

### Constructor Summary

Constructors
`` `Hyperlink()` Creates an empty hyperlink.
`protected` `Hyperlink(Element elem)`
`` `Hyperlink(SafeHtml html, DirectionEstimator directionEstimator, java.lang.String targetHistoryToken)` Creates a hyperlink with its html and target history token specified.
`` `Hyperlink(SafeHtml html, HasDirection.Direction dir, java.lang.String targetHistoryToken)` Creates a hyperlink with its html and target history token specified.
`` `Hyperlink(SafeHtml html, java.lang.String targetHistoryToken)` Creates a hyperlink with its html and target history token specified.
`` `Hyperlink(java.lang.String text, boolean asHTML, java.lang.String targetHistoryToken)` Creates a hyperlink with its text and target history token specified.
`` `Hyperlink(java.lang.String text, DirectionEstimator directionEstimator, java.lang.String targetHistoryToken)` Creates a hyperlink with its text and target history token specified.
`` `Hyperlink(java.lang.String text, HasDirection.Direction dir, java.lang.String targetHistoryToken)` Creates a hyperlink with its text and target history token specified.
`` `Hyperlink(java.lang.String text, java.lang.String targetHistoryToken)` Creates a hyperlink with its text and target history token specified.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`HandlerRegistration` `addClickHandler(ClickHandler handler)` Deprecated. Use `FocusWidget.addClickHandler(com.google.gwt.event.dom.client.ClickHandler)` instead and call History.newItem from the handler if you need to process the click before the history token is set.
`void` `addClickListener(ClickListener listener)` Deprecated. Use `FocusWidget.addClickHandler(com.google.gwt.event.dom.client.ClickHandler)` instead and call History.newItem from the handler if you need to process the click before the history token is set.
`DirectionEstimator` `getDirectionEstimator()` Returns the `DirectionEstimator` object.
`java.lang.String` `getHTML()` Gets this object's contents as HTML.
`java.lang.String` `getTargetHistoryToken()` Gets the history token referenced by this hyperlink.
`java.lang.String` `getText()` Gets this object's text.
`HasDirection.Direction` `getTextDirection()` Gets the direction of this object's text.
`void` `onBrowserEvent(Event event)` Fired whenever a browser event is received.
`protected void` `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -wrapper = the div around the link.
`void` `removeClickListener(ClickListener listener)` Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by an add*Handler method instead
`void` `setDirectionEstimator(boolean enabled)` Toggles on / off direction estimation.
`void` `setDirectionEstimator(DirectionEstimator directionEstimator)` Sets the `DirectionEstimator` object.
`void` `setHTML(SafeHtml html)` Sets this object's contents via known-safe HTML.
`void` `setHTML(SafeHtml html, HasDirection.Direction dir)` Sets this object's html, also declaring its direction.
`void` `setHTML(java.lang.String html)` Sets this object's contents via HTML.
`void` `setTargetHistoryToken(java.lang.String targetHistoryToken)` Sets the history token referenced by this hyperlink.
`void` `setText(java.lang.String text)` Sets this object's text.
`void` `setText(java.lang.String text, HasDirection.Direction dir)` Sets this object's text, also declaring its direction.

### Methods inherited from class com.google.gwt.user.client.ui.Widget

`addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onDetach, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEvents`

### Methods inherited from class com.google.gwt.user.client.ui.UIObject

`addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

`fireEvent`

### Field Detail

#### DEFAULT_DIRECTION_ESTIMATOR

    public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR

#### directionalTextHelper

    protected final DirectionalTextHelper directionalTextHelper

### Constructor Detail

#### Hyperlink

    public Hyperlink()

Creates an empty hyperlink.

#### Hyperlink

    public Hyperlink(SafeHtml html,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its html and target history token specified.

Parameters:
  `html` - the hyperlink's safe html
  `targetHistoryToken` - the history token to which it will link
See Also:
  `setTargetHistoryToken(java.lang.String)`

#### Hyperlink

    public Hyperlink(SafeHtml html,
                     HasDirection.Direction dir,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its html and target history token specified.

Parameters:
  `html` - the hyperlink's safe html
  `dir` - the html's direction
  `targetHistoryToken` - the history token to which it will link
See Also:
  `setTargetHistoryToken(java.lang.String)`

#### Hyperlink

    public Hyperlink(SafeHtml html,
                     DirectionEstimator directionEstimator,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its html and target history token specified.

Parameters:
  `html` - the hyperlink's safe html
  `directionEstimator` - A DirectionEstimator object used for automatic direction adjustment. For convenience, `DEFAULT_DIRECTION_ESTIMATOR` can be used.
  `targetHistoryToken` - the history token to which it will link
See Also:
  `setTargetHistoryToken(java.lang.String)`

#### Hyperlink

    public Hyperlink(java.lang.String text,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its text and target history token specified.

Parameters:
  `text` - the hyperlink's text
  `targetHistoryToken` - the history token to which it will link, which may not be null (use `Anchor` instead if you don't need history processing)

#### Hyperlink

    public Hyperlink(java.lang.String text,
                     HasDirection.Direction dir,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its text and target history token specified.

Parameters:
  `text` - the hyperlink's text
  `dir` - the text's direction
  `targetHistoryToken` - the history token to which it will link, which may not be null (use `Anchor` instead if you don't need history processing)

#### Hyperlink

    public Hyperlink(java.lang.String text,
                     DirectionEstimator directionEstimator,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its text and target history token specified.

Parameters:
  `text` - the hyperlink's text
  `directionEstimator` - A DirectionEstimator object used for automatic direction adjustment. For convenience, `DEFAULT_DIRECTION_ESTIMATOR` can be used.
  `targetHistoryToken` - the history token to which it will link, which may not be null (use `Anchor` instead if you don't need history processing)

#### Hyperlink

    public Hyperlink(java.lang.String text,
                     boolean asHTML,
                     java.lang.String targetHistoryToken)

Creates a hyperlink with its text and target history token specified.

Parameters:
  `text` - the hyperlink's text
  `asHTML` - `true` to treat the specified text as html
  `targetHistoryToken` - the history token to which it will link
See Also:
  `setTargetHistoryToken(java.lang.String)`

#### Hyperlink

    protected Hyperlink(Element elem)

### Method Detail

#### addClickHandler

    @Deprecated
    public HandlerRegistration addClickHandler(ClickHandler handler)

Deprecated. Use `FocusWidget.addClickHandler(com.google.gwt.event.dom.client.ClickHandler)` instead and call History.newItem from the handler if you need to process the click before the history token is set.
Description copied from interface: `HasClickHandlers`
Adds a `ClickEvent` handler.

Specified by:
  `addClickHandler` in interface `HasClickHandlers`
Parameters:
  `handler` - the click handler
Returns:
  `HandlerRegistration` used to remove this handler

#### addClickListener

    @Deprecated
    public void addClickListener(ClickListener listener)

Deprecated. Use `FocusWidget.addClickHandler(com.google.gwt.event.dom.client.ClickHandler)` instead and call History.newItem from the handler if you need to process the click before the history token is set.
Description copied from interface: `SourcesClickEvents`
Adds a listener interface to receive click events.

Specified by:
  `addClickListener` in interface `SourcesClickEvents`
Parameters:
  `listener` - the listener interface to add

#### getDirectionEstimator

    public DirectionEstimator getDirectionEstimator()

Description copied from interface: `HasDirectionEstimator`
Returns the `DirectionEstimator` object.

Specified by:
  `getDirectionEstimator` in interface `HasDirectionEstimator`

#### getHTML

    public java.lang.String getHTML()

Description copied from interface: `HasHTML`
Gets this object's contents as HTML.

Specified by:
  `getHTML` in interface `HasHTML`
Returns:
  the object's HTML

#### getTargetHistoryToken

    public java.lang.String getTargetHistoryToken()

Gets the history token referenced by this hyperlink.

Returns:
  the target history token
See Also:
  `setTargetHistoryToken(java.lang.String)`

#### getText

    public java.lang.String getText()

Description copied from interface: `HasText`
Gets this object's text.

Specified by:
  `getText` in interface `HasText`
Returns:
  the object's text

#### getTextDirection

    public HasDirection.Direction getTextDirection()

Description copied from interface: `HasDirectionalText`
Gets the direction of this object's text.

Specified by:
  `getTextDirection` in interface `HasDirectionalText`
Returns:
  the direction of this object's text

#### onBrowserEvent

    public void onBrowserEvent(Event event)

Description copied from interface: `EventListener`
Fired whenever a browser event is received.

Specified by:
  `onBrowserEvent` in interface `EventListener`
Overrides:
  `onBrowserEvent` in class `Widget`
Parameters:
  `event` - the event received

#### removeClickListener

    @Deprecated
    public void removeClickListener(ClickListener listener)

Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by an add*Handler method instead
Description copied from interface: `SourcesClickEvents`
Removes a previously added listener interface.

Specified by:
  `removeClickListener` in interface `SourcesClickEvents`
Parameters:
  `listener` - the listener interface to remove

#### setDirectionEstimator

    public void setDirectionEstimator(boolean enabled)

Toggles on / off direction estimation.

See note at `setDirectionEstimator(DirectionEstimator)`.

Specified by:
  `setDirectionEstimator` in interface `HasDirectionEstimator`
Parameters:
  `enabled` - Whether to enable direction estimation. If `true`, sets the `DirectionEstimator` object to a default `DirectionEstimator`.

#### setDirectionEstimator

    public void setDirectionEstimator(DirectionEstimator directionEstimator)

Sets the `DirectionEstimator` object.

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.

Specified by:
  `setDirectionEstimator` in interface `HasDirectionEstimator`
Parameters:
  `directionEstimator` - The `DirectionEstimator` to be set. `null` means turning off direction estimation.

#### setHTML

    public void setHTML(SafeHtml html)

Description copied from interface: `HasSafeHtml`
Sets this object's contents via known-safe HTML.

The object will behave exactly the same as when a widget's `HasHTML.setHTML(String)` method is invoked; however the `SafeHtml` passed to this method observes the contract that it can be used in an HTML context without causing unsafe script execution. Thus, unlike `HasHTML.setHTML(String)`, using this method cannot result in Cross-Site Scripting security vulnerabilities.

Specified by:
  `setHTML` in interface `HasSafeHtml`
Parameters:
  `html` - the object's new HTML, represented as a `SafeHtml` object

#### setHTML

    public void setHTML(java.lang.String html)

Description copied from interface: `HasHTML`
Sets this object's contents via HTML. Use care when setting an object's HTML; it is an easy way to expose script-based security problems. Consider using `HasText.setText(String)` whenever possible.

Specified by:
  `setHTML` in interface `HasHTML`
Parameters:
  `html` - the object's new HTML

#### setHTML

    public void setHTML(SafeHtml html,
                        HasDirection.Direction dir)

Description copied from interface: `HasDirectionalSafeHtml`
Sets this object's html, also declaring its direction.

Specified by:
  `setHTML` in interface `HasDirectionalSafeHtml`
Parameters:
  `html` - the object's new html
  `dir` - the html's direction

#### setTargetHistoryToken

    public void setTargetHistoryToken(java.lang.String targetHistoryToken)

Sets the history token referenced by this hyperlink. This is the history token that will be passed to `History.newItem(java.lang.String)` when this link is clicked.

Parameters:
  `targetHistoryToken` - the new history token, which may not be null (use `Anchor` instead if you don't need history processing)

#### setText

    public void setText(java.lang.String text)

Description copied from interface: `HasText`
Sets this object's text.

Specified by:
  `setText` in interface `HasText`
Parameters:
  `text` - the object's new text

#### setText

    public void setText(java.lang.String text,
                        HasDirection.Direction dir)

Description copied from interface: `HasDirectionalText`
Sets this object's text, also declaring its direction.

Specified by:
  `setText` in interface `HasDirectionalText`
Parameters:
  `text` - the object's new text
  `dir` - the text's direction

#### onEnsureDebugId

    protected void onEnsureDebugId(java.lang.String baseID)

Affected Elements:

- -wrapper = the div around the link.

Overrides:
  `onEnsureDebugId` in class `UIObject`
Parameters:
  `baseID` - the base ID used by the main element
See Also:
  `UIObject.onEnsureDebugId(String)`