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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier | Constructor and Description
    --- | ---
    `` | `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
    Modifier and Type | Method and Description
    --- | ---
    `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)`