Reviewers: jgw, Description: This patch 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 (pending no complaints from the GWTC thread about it).
This addresses issue 1960 http://code.google.com/p/google-web-toolkit/issues/detail?id=1960 Please review this at http://gwt-code-reviews.appspot.com/33809 Affected files: user/src/com/google/gwt/user/client/ui/Anchor.java user/src/com/google/gwt/user/client/ui/Hyperlink.java Index: user/src/com/google/gwt/user/client/ui/Anchor.java =================================================================== --- user/src/com/google/gwt/user/client/ui/Anchor.java (revision 5352) +++ user/src/com/google/gwt/user/client/ui/Anchor.java (working copy) @@ -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 { Index: user/src/com/google/gwt/user/client/ui/Hyperlink.java =================================================================== --- user/src/com/google/gwt/user/client/ui/Hyperlink.java (revision 5352) +++ user/src/com/google/gwt/user/client/ui/Hyperlink.java (working copy) @@ -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 -~----------~----~----~----~------~----~------~--~---
