Revision: 7223
Author: [email protected]
Date: Tue Dec 1 15:21:10 2009
Log: Adding UiBinder doc for widgets that require it.
Review: http://gwt-code-reviews.appspot.com/116803
http://code.google.com/p/google-web-toolkit/source/detail?r=7223
Modified:
/trunk/user/src/com/google/gwt/user/client/ui/CustomButton.java
/trunk/user/src/com/google/gwt/user/client/ui/DialogBox.java
/trunk/user/src/com/google/gwt/user/client/ui/DisclosurePanel.java
/trunk/user/src/com/google/gwt/user/client/ui/DockLayoutPanel.java
/trunk/user/src/com/google/gwt/user/client/ui/HasHTML.java
/trunk/user/src/com/google/gwt/user/client/ui/HasText.java
/trunk/user/src/com/google/gwt/user/client/ui/LayoutPanel.java
/trunk/user/src/com/google/gwt/user/client/ui/MenuBar.java
/trunk/user/src/com/google/gwt/user/client/ui/StackLayoutPanel.java
/trunk/user/src/com/google/gwt/user/client/ui/TabLayoutPanel.java
/trunk/user/test/com/google/gwt/uibinder/test/client/WidgetBasedUi.ui.xml
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/CustomButton.java Wed
Nov 4 10:50:50 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/CustomButton.java Tue
Dec 1 15:21:10 2009
@@ -20,6 +20,7 @@
import com.google.gwt.dom.client.NativeEvent;
import com.google.gwt.event.dom.client.ClickEvent;
import com.google.gwt.event.dom.client.ClickHandler;
+import com.google.gwt.resources.client.ImageResource;
import com.google.gwt.user.client.DOM;
import com.google.gwt.user.client.Element;
import com.google.gwt.user.client.Event;
@@ -99,6 +100,38 @@
* </table>
* </p>
*
+ * <h3>Use in UiBinder Templates</h3>
+ *
+ * When working with CustomButton subclasses in
+ * {...@link com.google.gwt.uibinder.client.UiBinder UiBinder} templates, you
+ * can set text and assign ImageResources for their various faces via
+ * child elements:
+ * <p>
+ * <dl>
+ * <dt><g:upFace>
+ * <dt><g:downFace>
+ * <dt><g:upHoveringFace>
+ * <dt><g:downHoveringFace>
+ * <dt><g:upDisabledFace>
+ * <dt><g:downDisabledFace>
+ * </dl>
+ *
+ * Each face element can take an optional <code>image</code> attribute
+ * and an html body. For example:<pre>
+ * <ui:image field='downButton'/> <!-- define an {...@link
ImageResource} -->
+ *
+ * <g:PushButton ui:field='pushButton' enabled='true'>
+ * <g:upFace>
+ * <b>click me</b>
+ * </gwt:upFace>
+ * <g:upHoveringFace>
+ * <b>Click ME!</b>
+ * </gwt:upHoveringFace>
+ *
+ * <g:downFace image='{downButton}'/>
+ * <g:downHoveringFace image='{downButton}'/>
+ * </g:PushButton>
+ * </pre>
*/
public abstract class CustomButton extends ButtonBase {
/**
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/DialogBox.java Wed Nov
4
09:18:51 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/DialogBox.java Tue Dec
1
15:21:10 2009
@@ -79,6 +79,26 @@
* <h3>Example</h3>
* {...@example com.google.gwt.examples.DialogBoxExample}
* </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * DialogBox elements in
+ * {...@link com.google.gwt.uibinder.client.UiBinder UiBinder} templates can
+ * have one widget child and one <g:caption> child. (Note the lower case
+ * "c", meant to signal that the caption is not a runtime object, and so
cannot
+ * have a <code>ui:field</code> attribute.) The body of the
+ * caption can be html.
+ * <p>
+ * For example: <pre>
+ * <g:DialogBox autoHide="true" modal="true">
+ * <g:caption><b>Caption text</b></g:caption>
+ * <g:HTMLPanel>
+ * Body text
+ * <g:Button ui:field='cancelButton'>Cancel</g:Button>
+ * <g:Button ui:field='okButton'>Okay</g:Button>
+ * </g:HTMLPanel>
+ * </g:DialogBox>
+ * </pre>
*/
@SuppressWarnings("deprecation")
public class DialogBox extends DecoratedPopupPanel implements HasHTML,
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/DisclosurePanel.java Wed
Oct 28 15:52:50 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/DisclosurePanel.java Tue
Dec 1 15:21:10 2009
@@ -37,11 +37,15 @@
* A widget that consists of a header and a content panel that discloses
the
* content when a user clicks on the header.
*
- * <h3>CSS Style Rules</h3> <ul class="css"> <li>.gwt-DisclosurePanel { the
- * panel's primary style }</li> <li>.gwt-DisclosurePanel-open { dependent
style
- * set when panel is open }</li> <li>.gwt-DisclosurePanel-closed {
dependent
- * style set when panel is closed }</li>
- *
+ * <h3>CSS Style Rules</h3>
+ * <dl class="css">
+ * <dt>.gwt-DisclosurePanel
+ * <dd>the panel's primary style
+ * <dt>.gwt-DisclosurePanel-open
+ * <dd> dependent style set when panel is open
+ * <dt>.gwt-DisclosurePanel-closed
+ * <dd> dependent style set when panel is closed
+ * </dl>
* <p>
* <img class='gallery' src='DisclosurePanel.png'/>
* </p>
@@ -51,6 +55,29 @@
* selector:<br/>
* .gwt-DisclosurePanel-open .header { ... }
* </p>
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * DisclosurePanel elements in
+ * {...@link com.google.gwt.uibinder.client.UiBinder UiBinder} templates can
+ * have one widget child and one of two types of header elements. A
+ * <g:header> element can hold html, or a <g:customHeader> element
+ * can hold a widget. (Note that the tags of the header elements are not
+ * capitalized. This is meant to signal that the head is not a runtime
object,
+ * and so cannot have a <code>ui:field</code> attribute.)
+ * <p>
+ * For example:<pre>
+ * <g:DisclosurePanel>
+ * <g:header><b>Text header</b></gwt:caption>
+ * <g:Label>Widget body</g:Label>
+ * </g:DisclosurePanel>
+ *
+ * <g:DisclosurePanel>
+ * <g:customeHeader>
+ * <g:Label>Widget header</g:Label>
+ * </g:customeHeader>
+ * <g:Label>Widget body</g:Label>
+ * </g:DisclosurePanel>
+ * </pre>
*/
@SuppressWarnings("deprecation")
public final class DisclosurePanel extends Composite implements
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/DockLayoutPanel.java Tue
Nov 24 14:38:02 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/DockLayoutPanel.java Tue
Dec 1 15:21:10 2009
@@ -35,6 +35,50 @@
* <h3>Example</h3>
* {...@example com.google.gwt.examples.DockLayoutPanelExample}
* </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * DockLayoutPanel elements in
+ * {...@link com.google.gwt.uibinder.client.UiBinder UiBinder} templates
+ * lay out their children in elements tagged with the cardinal directions,
+ * and center:
+ *
+ * <p>
+ * <dl>
+ * <dt><g:center>
+ * <dt><g:north>
+ * <dt><g:south>
+ * <dt><g:west>
+ * <dt><g:east>
+ * </dl>
+ *
+ * <p>
+ * Each child can hold only widget, and there can be only one
<g:center>.
+ * However, there can be any number of the directional children.
+ *<p>
+ * (Note that the tags of the child elements are not
+ * capitalized. This is meant to signal that they are not runtime objects,
+ * and so cannot have a <code>ui:field</code> attribute.)
+ * <p>
+ * For example:<pre>
+ * <g:DockLayoutPanel unit='EM'>
+ * <g:north size='5'>
+ * <g:Label>Top</g:Label>
+ * </g:north>
+ * <g:center>
+ * <g:Label>Body</g:Label>
+ * </g:center>
+ * <g:west size='192'>
+ * <g:HTML>
+ * <ul>
+ * <li>Sidebar</li>
+ * <li>Sidebar</li>
+ * <li>Sidebar</li>
+ * </ul>
+ * </g:HTML>
+ * </g:west>
+ * </g:DockLayoutPanel>
+ * </pre>
*/
public class DockLayoutPanel extends ComplexPanel implements
AnimatedLayout,
RequiresResize, ProvidesResize {
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/HasHTML.java Wed Dec 27
15:03:26 2006
+++ /trunk/user/src/com/google/gwt/user/client/ui/HasHTML.java Tue Dec 1
15:21:10 2009
@@ -19,6 +19,16 @@
* An object that implements this interface contains text, which can be
set and
* retrieved using these methods. The object's text can be set either as
HTML or
* as text.
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * The body of an XML element representing a widget that implements
+ * HasHTML will be parsed as HTML and be used in a call to its
+ * {...@link #setHTML(String)} method.
+ *
+ * <p>For example:<pre>
+ * <g:PushButton><b>Click me!</b></g:PushButton>
+ * </pre>
*/
public interface HasHTML extends HasText {
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/HasText.java Wed Dec 27
15:03:26 2006
+++ /trunk/user/src/com/google/gwt/user/client/ui/HasText.java Tue Dec 1
15:21:10 2009
@@ -18,6 +18,18 @@
/**
* An object that implements this interface contains text, which can be
set and
* retrieved using these methods.
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * The body of an XML element representing a widget that implements
+ * HasText will be parsed as text and be used in a call to its
+ * {...@link #setText(String)} method. HasText elements must only
+ * contain text. (This behavior is overridden for {...@link HasHTML}
+ * widgets.)
+ *
+ * <p>For example:<pre>
+ * <g:Label>Hello.</g:Label>
+ * </pre>
*/
public interface HasText {
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/LayoutPanel.java Tue Nov
24 14:38:02 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/LayoutPanel.java Tue Dec
1 15:21:10 2009
@@ -38,6 +38,69 @@
* <h3>Example</h3>
* {...@example com.google.gwt.examples.LayoutPanelExample}
* </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * LayoutPanel elements in {...@link com.google.gwt.uibinder.client.UiBinder
+ * UiBinder} templates lay out their children with arbitrary constraints,
using
+ * <g:layer> elements. Each layer may have any of the following
constraint
+ * attributes specified as CSS length attributes: <code>left</code>,
+ * <code>top</code>, <code>right</code>, <code>bottom</code>,
<code>width</code>
+ * , and <code>height</code>.
+ *
+ * <p>
+ * Precisely zero or two constraints are required for each axis
(horizontal and
+ * vertial). Specifying no constraints implies that the child should fill
that
+ * axis completely.
+ *
+ * <p>
+ * The valid sets of horizontal constraints are:
+ * <dl>
+ * <dt>(none)
+ * <dd>Fill the parent's horizontal axis
+ * <dt>left, width
+ * <dd>Fixed width, positioned from parent's left edge
+ * <dt>right, width
+ * <dd>Fixed width, positioned from parent's right edge
+ * <dt>left, right
+ * <dd>Width implied by fixed distance from parent's left and right edges
+ * </dl>
+ *
+ * <p>
+ * The valid sets of vertical constraints are:
+ * <dl>
+ * <dt>(none)
+ * <dd>Fill the parent's vertical axis
+ * <dt>top, height
+ * <dd>Fixed height, positioned from parent's top edge
+ * <dt>bottom, height
+ * <dd>Fixed height, positioned from parent's bottom edge
+ * <dt>top, bottom
+ * <dd>Height implied by fixed distance from parent's top and bottom edges
+ * </dl>
+ *
+ * <p>
+ * The values of constraint attributes can be any valid <a
+ * href='http://www.w3.org/TR/CSS21/syndata.html#length-units'>CSS
length</a>,
+ * such as <code>1px</code>, <code>3em</code>, or <code>0</code> (zero
lengths require no
+ * units).
+ *
+ * <p>
+ * For example:
+ *
+ * <pre>
+ * <g:LayoutPanel>
+ * <!-- No constraints causes the layer to fill the parent -->
+ * <g:layer>
+ * <g:Label>Lorem ipsum...</g:Label>
+ * </g:layer>
+ * <!-- Position horizontally 25% from each edge;
+ * Vertically 4px from the top and 10em tall. -->
+ * <g:layer left='25%' right='25%' top='4px' height='10em'>
+ * <g:Label>Header</g:Label>
+ * </g:layer>
+ * </g:LayoutPanel>
+ * </pre>
*/
public class LayoutPanel extends ComplexPanel implements AnimatedLayout,
RequiresResize, ProvidesResize {
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/MenuBar.java Mon Nov 2
07:51:58 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/MenuBar.java Tue Dec 1
15:21:10 2009
@@ -104,6 +104,40 @@
* <h3>Example</h3>
* {...@example com.google.gwt.examples.MenuBarExample}
* </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * MenuBar elements in UiBinder template files can have a
<code>vertical</code>
+ * boolean attribute (which defaults to false), and may have only MenuItem
+ * elements as children. MenuItems may contain HTML and MenuBars.
+ * <p>
+ * For example:
+ *
+ * <pre>
+ * <g:MenuBar>
+ * <g:MenuItem>Higgledy
+ * <g:MenuBar vertical="true">
+ * <g:MenuItem>able</g:MenuItem>
+ * <g:MenuItem>baker</g:MenuItem>
+ * <g:MenuItem>charlie</g:MenuItem>
+ * </g:MenuBar>
+ * </g:MenuItem>
+ * <g:MenuItem>Piggledy
+ * <g:MenuBar vertical="true">
+ * <g:MenuItem>foo</g:MenuItem>
+ * <g:MenuItem>bar</g:MenuItem>
+ * <g:MenuItem>baz</g:MenuItem>
+ * </g:MenuBar>
+ * </g:MenuItem>
+ * <g:MenuItem><b>Pop!</b>
+ * <g:MenuBar vertical="true">
+ * <g:MenuItem>uno</g:MenuItem>
+ * <g:MenuItem>dos</g:MenuItem>
+ * <g:MenuItem>tres</g:MenuItem>
+ * </g:MenuBar>
+ * </g:MenuItem>
+ * </g:MenuBar>
+ * </pre>
*/
// Nothing we can do about MenuBar implementing PopupListener until next
// release.
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/StackLayoutPanel.java Tue
Nov 24 14:38:02 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/StackLayoutPanel.java Tue
Dec 1 15:21:10 2009
@@ -29,8 +29,8 @@
* with a header for each child which the user can click to display.
*
* <p>
- * This widget will <em>only</em> work in standards mode, which requires
- * that the HTML page in which it is run have an explicit <!DOCTYPE>
+ * This widget will <em>only</em> work in standards mode, which requires
that
+ * the HTML page in which it is run have an explicit <!DOCTYPE>
* declaration.
* </p>
*
@@ -38,6 +38,38 @@
* <h3>Example</h3>
* {...@example com.google.gwt.examples.StackLayoutPanelExample}
* </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * A StackLayoutPanel element in a
+ * {...@link com.google.gwt.uibinder.client.UiBinder UiBinder} template may
have a
+ * <code>unit</code> attribute with a
+ * {...@link com.google.gwt.dom.client.Style.Unit Style.Unit} value (it
defaults to
+ * PX).
+ * <p>
+ * The children of a StackLayoutPanel element are laid out in <g:stack>
+ * elements. Each stack can have one widget child and one of two types of
header
+ * elements. A <g:header> element can hold html, or a
<g:customHeader>
+ * element can hold a widget. (Note that the tags of the header elements
are not
+ * capitalized. This is meant to signal that the head is not a runtime
object,
+ * and so cannot have a <code>ui:field</code> attribute.)
+ * <p>
+ * For example:
+ *
+ * <pre>
+ * <g:StackLayoutPanel unit='PX'>
+ * <g:stack>
+ * <g:header size='3'><b>HTML</b> header</g:header>
+ * <g:Label>able</g:Label>
+ * </g:stack>
+ * <g:stack>
+ * <g:customHeader size='3'>
+ * <g:Label>Custom header</g:Label>
+ * </g:customHeader>
+ * <g:Label>baker</g:Label>
+ * </g:stack>
+ * </g:StackLayoutPanel>
+ * </pre>
*/
public class StackLayoutPanel extends Composite implements HasWidgets,
RequiresResize, ProvidesResize {
=======================================
--- /trunk/user/src/com/google/gwt/user/client/ui/TabLayoutPanel.java Wed
Nov 25 08:06:44 2009
+++ /trunk/user/src/com/google/gwt/user/client/ui/TabLayoutPanel.java Tue
Dec 1 15:21:10 2009
@@ -45,18 +45,47 @@
* </p>
*
* <h3>CSS Style Rules</h3>
- * <ul class='css'>
- * <li>.gwt-TabLayoutPanel { the panel itself }</li>
- * <li>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTabs { the tab bar element
}</li>
- * <li>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTab { an individual tab
}</li>
- * <li>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTabInner { an element nested
in
- * each tab (useful for styling) }</li>
- * </ul>
+ * <dl>
+ * <dt>.gwt-TabLayoutPanel <dd> the panel itself
+ * <dt>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTabs <dd> the tab bar element
+ * <dt>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTab <dd> an individual tab
+ * <dt>.gwt-TabLayoutPanel .gwt-TabLayoutPanelTabInner <dd> an element
nested in
+ * each tab (useful for styling)
+ * </dl>
*
* <p>
* <h3>Example</h3>
* {...@example com.google.gwt.examples.TabLayoutPanelExample}
- * </p>
+ *
+ * <h3>Use in UiBinder Templates</h3>
+ * <p>
+ * A TabLayoutPanel element in a {...@link
com.google.gwt.uibinder.client.UiBinder
+ * UiBinder} template must have a <code>barHeight</code> attribute with a
double
+ * value, and may have a <code>barUnit</code> attribute with a
+ * {...@link com.google.gwt.dom.client.Style.Unit Style.Unit} value.
+ * <code>barUnit</code> defaults to PX.
+ * <p>
+ * The children of a TabLayoutPanel element are laid out in <g:tab>
+ * elements. Each tab can have one widget child and one of two types of
header
+ * elements. A <g:header> element can hold html, or a
<g:customHeader>
+ * element can hold a widget. (Note that the tags of the header elements
are
+ * not capitalized. This is meant to signal that the head is not a runtime
+ * object, and so cannot have a <code>ui:field</code> attribute.)
+ * <p>
+ * For example:<pre>
+ * <g:TabLayoutPanel barUnit='PX' barHeight='3'>
+ * <g:tab>
+ * <g:header size='7'><b>HTML</b> header</g:header>
+ * <g:Label>able</g:Label>
+ * </g:tab>
+ * <g:tab>
+ * <g:customHeader size='7'>
+ * <g:Label>Custom header</g:Label>
+ * </g:customHeader>
+ * <g:Label>baker</g:Label>
+ * </g:tab>
+ * </g:TabLayoutPanel>
+ * </pre>
*/
public class TabLayoutPanel extends ResizeComposite implements HasWidgets,
ProvidesResize, IndexedPanel, HasBeforeSelectionHandlers<Integer>,
@@ -113,7 +142,7 @@
private int selectedIndex = -1;
/**
- * Creates an empty tab panel.
+ * Creates an empty tab panel.
*
* @param barHeight the size of the tab bar
* @param barUnit the unit in which the tab bar size is specified
@@ -250,8 +279,8 @@
}
/**
- * Inserts a widget into the panel. If the Widget is already attached,
it will be
- * moved to the requested index.
+ * Inserts a widget into the panel. If the Widget is already attached,
it will
+ * be moved to the requested index.
*
* @param child the widget to be added
* @param text the text to be shown on its tab
@@ -269,8 +298,8 @@
}
/**
- * Inserts a widget into the panel. If the Widget is already attached,
it will be
- * moved to the requested index.
+ * Inserts a widget into the panel. If the Widget is already attached,
it will
+ * be moved to the requested index.
*
* @param child the widget to be added
* @param text the text to be shown on its tab
@@ -281,8 +310,8 @@
}
/**
- * Inserts a widget into the panel. If the Widget is already attached,
it will be
- * moved to the requested index.
+ * Inserts a widget into the panel. If the Widget is already attached,
it will
+ * be moved to the requested index.
*
* @param child the widget to be added
* @param tab the widget to be placed in the associated tab
@@ -344,8 +373,7 @@
// Fire the before selection event, giving the recipients a chance to
// cancel the selection.
- BeforeSelectionEvent<Integer> event =
- BeforeSelectionEvent.fire(this, index);
+ BeforeSelectionEvent<Integer> event = BeforeSelectionEvent.fire(this,
index);
if ((event != null) && event.isCanceled()) {
return;
}
=======================================
---
/trunk/user/test/com/google/gwt/uibinder/test/client/WidgetBasedUi.ui.xml
Wed Nov 25 09:15:38 2009
+++
/trunk/user/test/com/google/gwt/uibinder/test/client/WidgetBasedUi.ui.xml
Tue Dec 1 15:21:10 2009
@@ -32,7 +32,6 @@
which are not part of XML. (The file is also available as
https://dl-ssl.google.com/gwt/DTD/xhtml.ent.)
-
Next, the bit in square brackets is even more optional. It shows how
to add your own entities, in this case pulling in additional
definitions for &point-left; and &point-right; from local file
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
