Author: [email protected]
Date: Fri May 15 13:39:00 2009
New Revision: 5399
Modified:
trunk/user/src/com/google/gwt/user/client/ui/Anchor.java
trunk/user/src/com/google/gwt/user/client/ui/Hyperlink.java
Log:
Adds Javadoc to Hyperlink/Anchor clarifying the uses for each, an
assertion on the target history token with an explanatory error message, and
deprecates listeners on Hyperlink.
Issue: 1960
Patch by: jat
Review by: jgw
Modified: trunk/user/src/com/google/gwt/user/client/ui/Anchor.java
==============================================================================
--- trunk/user/src/com/google/gwt/user/client/ui/Anchor.java (original)
+++ trunk/user/src/com/google/gwt/user/client/ui/Anchor.java Fri May 15
13:39:00 2009
@@ -24,10 +24,17 @@
/**
* 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>
+ *
* <h3>CSS Style Rules</h3>
* <ul class='css'>
* <li>.gwt-Anchor { }</li>
* </ul>
+ *
+ * @see Hyperlink
*/
public class Anchor extends FocusWidget implements HasHorizontalAlignment,
HasName, HasText, HasHTML, HasWordWrap, HasDirection {
Modified: trunk/user/src/com/google/gwt/user/client/ui/Hyperlink.java
==============================================================================
--- trunk/user/src/com/google/gwt/user/client/ui/Hyperlink.java (original)
+++ trunk/user/src/com/google/gwt/user/client/ui/Hyperlink.java Fri May 15
13:39:00 2009
@@ -33,6 +33,11 @@
* without reloading the page.
*
* <p>
+ * If you want an HTML hyperlink (<a> tag) without interacting with
the
+ * history system, use {...@link Anchor} instead.
+ * </p>
+ *
+ * <p>
* 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.
@@ -50,6 +55,8 @@
* <p>
* <h3>Example</h3> {...@example com.google.gwt.examples.HistoryExample}
* </p>
+ *
+ * @see Anchor
*/
@SuppressWarnings("deprecation")
public class Hyperlink extends Widget implements HasHTML,
SourcesClickEvents,
@@ -89,7 +96,9 @@
* Creates a hyperlink with its text and target history token specified.
*
* @param text the hyperlink's text
- * @param targetHistoryToken the history token to which it will link
+ * @param targetHistoryToken the history token to which it will link,
which
+ * may not be null (use {...@link Anchor} instead if you don't need
history
+ * processing)
*/
public Hyperlink(String text, String targetHistoryToken) {
this();
@@ -109,12 +118,20 @@
setStyleName("gwt-Hyperlink");
}
+ /**
+ * @deprecated Use {...@link Anchor#addClickHandler} instead and call
+ * History.newItem from the handler if you need to process the
+ * click before the history token is set.
+ */
+ @Deprecated
public HandlerRegistration addClickHandler(ClickHandler handler) {
return addHandler(handler, ClickEvent.getType());
}
/**
- * @deprecated Use {...@link #addClickHandler} instead
+ * @deprecated Use {...@link Anchor#addClickHandler} instead and call
+ * History.newItem from the handler if you need to process the
+ * click before the history token is set.
*/
@Deprecated
public void addClickListener(ClickListener listener) {
@@ -166,9 +183,12 @@
* token that will be passed to {...@link History#newItem} when this link is
* clicked.
*
- * @param targetHistoryToken the new target history token
+ * @param targetHistoryToken the new history token, which may not be
null (use
+ * {...@link Anchor} instead if you don't need history processing)
*/
public void setTargetHistoryToken(String targetHistoryToken) {
+ assert targetHistoryToken != null
+ : "targetHistoryToken must not be null, consider using Anchor
instead";
this.targetHistoryToken = targetHistoryToken;
DOM.setElementProperty(anchorElem, "href", "#" + targetHistoryToken);
}
--~--~---------~--~----~------------~-------~--~----~
http://groups.google.com/group/Google-Web-Toolkit-Contributors
-~----------~----~----~----~------~----~------~--~---
