GWT - BASIC WIDGETS

Every user interface considers the following three main aspects:

• UI elements : These are the core visual elements the user eventually sees and interacts with. GWT provides a huge list of widely used and common elements varying from basic to complex, which we will cover in this tutorial.
• Layouts: They define how UI elements should be organized on the screen and provide a final look and feel of the GUI (Graphical User Interface). This part will be covered in Layout chapter.
• Behavior: These are events which occur when the user interacts with UI elements. This part will be covered in Event Handling chapter.

GWT UI Elements

The GWT library provides classes in a well-defined class hierarchy to create complex web-based user interfaces. All classes in this component hierarchy has been derived from the UIObject base class as shown below:

Every Basic UI widget inherits properties from a Widget class which in turn inherits properties from UIObject. Tree and Menu will be covered in “Complex widgets” tutorial later.

S.N.	Widget & Description
1	GWT UIObject Class This widget contains text, not interpreted as HTML using a<div>element, causing it to be displayed with block layout.
2	GWT Widget Class This widget can contain HTML text and displays the html content using a <div> element, causing it to be displayed with block layout.

GWT – UIObject Class

Introduction

The class UIObject is the superclass for all user-interface objects. It simply wraps a DOM element, and cannot receive events. It provides direct child classes like Widget, MenuItem, MenuItemSeparator, TreeItem.

• All UIObject objects can be styled using CSS.
• Every UIObject has a primary style name that identifies the key CSS style rule that should always be applied to it.
• More complex styling behaviour can be achieved by manipulating an object's secondary style names.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.UIObject class:


Field

Following are the fields for com.google.gwt.user.client.ui.UIObject class:

• public static final java.lang.String DEBUG_ID_PREFIX -- The element ID that you specify will be prefixed by the static string DEBUG_ID_PREFIX.

Class Constructors

S.N.	Constructor & Description
1	UIObject() This creates a UIObject for the child classes.

Class Methods

S.N.	Method & Description
1	void addStyleDependentName(java.lang.String styleSuffix) Adds a dependent style name by specifying the style name's suffix.
2	void addStyleName(java.lang.String style) Adds a secondary or dependent style name to this object.
3	static void ensureDebugId(Element elem, java.lang.String id) Ensure that elem has an ID property set, which allows it to integrate with third-party libraries and test tools.
4	protected static void ensureDebugId(Element elem, java.lang.String baseID, java.lang.String id) Set the debug id of a specific element.
5	ensureDebugId(java.lang.String id) Ensure that the main Element for this UIObject has an ID property set, which allows it to integrate with third-party libraries and test tools.
6	int getAbsoluteLeft() Gets the object's absolute left position in pixels, as measured from the browser window's client area.
7	int getAbsoluteTop() Gets the object's absolute top position in pixels, as measured from the browser window's client area.
8	Element getElement() Gets a handle to the object's underlying DOM element.
9	int getOffsetHeight() Gets the object's offset height in pixels.
10	int getOffsetWidth() Gets the object's offset width in pixels.
11	protected Element getStyleElement() Template method that returns the element to which style names will be applied.
12	java.lang.String getStyleName() Gets all of the object's style names, as a space-separated list.
13	protected static java.lang.String getStyleName(Element elem) Gets all of the element's style names, as a space-separated list.
14	java.lang.String getStylePrimaryName() Gets the primary style name associated with the object.
15	protected static java.lang.String getStylePrimaryName(Element elem) Gets the element's primary style name.
16	java.lang.String getTitle() Gets the title associated with this object.
17	boolean isVisible() Determines whether or not this object is visible.
18	static boolean isVisible(Element elem) Determines whether element is visible or not.
19	protected void onEnsureDebugId(java.lang.String baseID) Called when the user sets the id using the ensureDebugId(String) method.
20	void removeStyleDependentName(java.lang.String styleSuffix) Removes a dependent style name by specifying the style name's suffix.
21	void removeStyleName(java.lang.String style) Removes a style name.
22	protected void setElement(Element elem) Sets this object's browser element.
23	protected void setElement(Element elem) Sets this object's browser element.
24	void setHeight(java.lang.String height) Sets the object's height.
25	void setPixelSize(int width, int height) Sets the object's size, in pixels, not including decorations such as border, margin, and padding.
26	void setSize(java.lang.String width, java.lang.String height) Sets the object's size.
27	protected static void setStyleName(Element elem, java.lang.String styleName) Clears all of the element's style names and sets it to the given style.
28	protected static void setStyleName(Element elem, java.lang.String style, boolean add) This convenience method adds or removes a style name for a given element.
29	void setStyleName(java.lang.String style) Clears all of the object's style names and sets it to the given style.
30	protected static void setStylePrimaryName(Element elem, java.lang.String style) Sets the element's primary style name and updates all dependent style names.
31	void setStylePrimaryName(java.lang.String style) Sets the object's primary style name and updates all dependent style names.
32	void setTitle(java.lang.String title) Sets the title associated with this object.
33	void setVisible(boolean visible) Sets whether this object is visible.
34	static void setVisible(Element elem, boolean visible) Sets whether this element is visible
35	void setWidth(java.lang.String width) Sets the object's width.
36	java.lang.String toString() This method is overridden so that any object can be viewed in the debugger as an HTML snippet.
37	void unsinkEvents(int eventBitsToRemove) Removes a set of events from this object's event list.

Methods Inherited

This class inherits methods from the following classes:

• java.lang.Object

GWT – Widget Class

Introduction

The class Widget is the base class for the majority of user-interface objects. Widget adds support for receiving events from the browser and being added directly to panels.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.Widget class:


Field

Following are the fields for com.google.gwt.user.client.ui.Widget class:

• public static final java.lang.String DEBUG_ID_PREFIX -- The element ID that you specify will be prefixed by the static string DEBUG_ID_PREFIX.

Class Constructors

S.N.	Constructor & Description
1	Widget() This creates a Widget for the child classes.

Class Methods

S.N.	Method & Description
1	protected <H extends EventHandler> HandlerRegistration addDomHandler(H handler, DomEvent.Type<H> type) Adds a native event handler to the widget and sinks the corresponding native event.
2	protected <H extends EventHandler> HandlerRegistration addHandler(H handler, GwtEvent.Type<H> type) Adds this handler to the widget.
3	protected void delegateEvent(Widget target, GwtEvent<?> event) Fires an event on a child widget.
4	protected void doAttachChildren() If a widget implements HasWidgets, it must override this method and call onAttach() for each of its child widgets.
5	protected void doDetachChildren() If a widget implements HasWidgets, it must override this method and call onDetach() for each of its child widgets.
6	void fireEvent(GwtEvent<?> event) Fires the given event to all the appropriate handlers.
7	protected int getHandlerCount(GwtEvent.Type<?> type) Gets the number of handlers listening to the event type.
8	Widget getParent() Gets this widget's parent panel.
9	boolean isAttached() Determines whether this widget is currently attached to the browser's document (i.e., there is an unbroken chain of widgets between this widget and the underlying browser document).
10	protected boolean isOrWasAttached() Has this widget ever been attached?
11	void onBrowserEvent(Event event) Fired whenever a browser event is received.
12	void onBrowserEvent(Event event) Fired whenever a browser event is received.
13	protected void onLoad() Gets a handle to the object's underlying DOM element.
14	protected void onLoad() Gets a handle to the object's underlying DOM element.
15	protected void onUnload() This method is called immediately before a widget will be detached from the browser's document.
16	void removeFromParent() Removes this widget from its parent widget.
17	void sinkEvents(int eventBitsToAdd) Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement.

Methods Inherited

This class inherits methods from the following classes:

• com.google.gwt.user.client.ui.UIObject

Basic Widgets

Following are few important Basic Widgets:

S.N.	Widget & Description
1	Label This widget contains text, not interpreted as HTML using a <div>element, causing it to be displayed with block layout.
2	HTML This widget can contain HTML text and displays the html content using a <div> element, causing it to be displayed with block layout.
3	Image This widget displays an image at a given URL.
4	Anchor This widget represents a simple <a> element.

GWT – Label Widget

Introduction

The Label can contains only arbitrary text and it can not be interpreted as HTML. This widget uses a <div> element, causing it to be displayed with block layout.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.Label class:


Css Style Rulesles

Following default CSS Style rule will be applied to all the labels. You can override it as per your requirements.


Class Constructors

S.N.	Constructor & Description
1	Label() Creates an empty label.
2	protected Label(Element element) This constructor may be used by subclasses to explicitly use an existing element.
3	Label(java.lang.String text) Creates a label with the specified text.
4	Label(java.lang.String text, boolean wordWrap) Creates a label with the specified text.

Class Methods

S.N.	Method & Description
1	void addClickListener(ClickListener listener) Adds a listener interface to receive click events.
2	void addMouseListener(MouseListener listener) Adds a listener interface to receive mouse events.
3	void addMouseWheelListener(MouseWheelListener listener) Gets this widget's parent panel.
4	HasDirection.Direction getDirection() Gets the directionality of the widget.
5	HasHorizontalAlignment.HorizontalAlignmentConstant getHorizontalAlignment() Gets the horizontal alignment.
6	java.lang.String getText() Gets this object's text.
7	boolean getWordWrap() Gets whether word-wrapping is enabled.
8	void onBrowserEvent(Event event) Removes a previously added listener interface.
9	void removeClickListener(ClickListener listener) This method is called immediately before a widget will be detached from the browser's document.
10	void removeMouseListener(MouseListener listener) Removes a previously added listener interface.
11	void removeMouseWheelListener(MouseWheelListener listener) Removes a previously added listener interface.
12	void setDirection(HasDirection.Direction direction) Sets the directionality for a widget.
13	void setHorizontalAlignment(HasHorizontalAlignment.HorizontalAlignmentConstant align) Sets the horizontal alignment.
14	void setText(java.lang.String text) Sets this object's text.
15	void setWordWrap(boolean wrap) Sets whether word-wrapping is enabled.
16	static Label wrap(Element element) Creates a Label widget that wraps an existing or element.

Methods Inherited

This class inherits methods from the following classes:

• com.google.gwt.user.client.ui.UIObject
• com.google.gwt.user.client.ui.Widget

Label Widget Example

This example shows the usage of Label Widget in GWT. You can use the following steps to update the GWT application we created in GWT - Create Application chapter:

Step	Description
1	Create a project with a name HelloWorld under a package com.jtc as explained in the GWT - Create Application chapter.
2	Modify HelloWorld.gwt.xml, HelloWorld.css, HelloWorld.html and HelloWorld.javaas explained below. Keep rest of the files unchanged.
3	Compile and run the application to verify the result of the implemented logic.

Following is the content of the modified module descriptorsrc/com.jtc/HelloWorld.gwt.xml.


Following is the content of the modified Style Sheet file war/HelloWorld.css.


Following is the content of the modified HTML host file war/HelloWorld.html to accommodate two buttons.


Let us have following content of Java file src/com.jtc/HelloWorld.java which will demonstrate use of Label widget.


Once you are ready with all the changes done, let us compile and run the application in development mode as we did in GWT - Create Application chapter. If everything is fine with your application, this will produce the following result:

GWT - HTML Widget

Introduction

The HTML widget can contain arbitrary HTML which can be interpreted as HTML. This widget uses a <div> element, causing it to be displayed with block layout.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.Label class:


Css Style Rules

Following default CSS Style rule will be applied to all the HTML widget. You can override it as per your requirements.


Class Constructors

S.N.	Constructor & Description
1	HTML() Creates an empty HTML.
2	protected HTML(Element element) This constructor may be used by subclasses to explicitly use an existing element.
3	HTML(java.lang.String html) Creates a HTML with the specified html contents.
4	HTML(java.lang.String html, boolean wordWrap) Creates an HTML widget with the specified contents, optionally treating it as HTML, and optionally disabling word wrapping.

Class Methods

1	java.lang.String getHTML() Gets this object's contents as HTML.
2	void setHTML(java.lang.String html) Sets this object's contents via HTML.
3	static HTML wrap(Element element) Creates an HTML widget that wraps an existing or element.

Methods Inherited

This class inherits methods from the following classes:

• com.google.gwt.user.client.ui.Label
• com.google.gwt.user.client.ui.UIObject
• com.google.gwt.user.client.ui.Widget
• com.google.gwt.user.client.ui.HasText
• java.lang.Object

Html Widget Example

This example will take you through simple steps to show usage of a HTML Widget in GWT. Follow the following steps to update the GWT application we created in GWT - Create Application chapter:

Step	Description
1	Create a project with a name HelloWorld under a package com.jtc as explained in the GWT - Create Application chapter.
2	Modify HelloWorld.gwt.xml, HelloWorld.css, HelloWorld.html and HelloWorld.javaas explained below. Keep rest of the files unchanged.
3	Compile and run the application to verify the result of the implemented logic.

Following is the content of the modified module descriptor src/com.jtc/HelloWorld.gwt.xml.


Following is the content of the modified Style Sheet file war/HelloWorld.css.


Following is the content of the modified HTML host file war/HelloWorld.html.


Let us have following content of Java file src/com.jtc/HelloWorld.java which will demonstrate use of HTML widget.


Once you are ready with all the changes done, let us compile and run the application in development mode as we did in GWT - Create Application chapter. If everything is fine with your application, this will produce following result:

GWT – Image Widget

Introduction

The Image widget displays an image at a given URL. The image widget can be in 'unclipped' mode (the default mode) or 'clipped' mode. In clipped mode, a viewport is overlaid on top of the image so that a subset of the image will be displayed. In unclipped mode, there is no viewport - the entire image will be visible. Methods will operate differently depending on the mode that the image is in. These differences are detailed in the documentation for each method.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.Image class:


CSS Style Rules

Following default CSS Style rule will be applied to all the Image widget. You can override it as per your requirements.


Class Constructors

S.N.	Constructor & Description
1	Image() Creates an empty image.
2	protected Image(Element element) This constructor may be used by subclasses to explicitly use an existing element.
3	Image(java.lang.String url) Creates an image with the specified url.
4	Image(java.lang.String html, int left, int top, int width, int height) Creates a clipped image with a specified URL and visibility rectangle.

Class Methods

S.N.	Function name & Description
1	void addClickListener(ClickListener listener) Adds a listener interface to receive click events.
2	void addLoadListener(LoadListener listener) Adds a listener interface to receive load events.
3	void addMouseListener(MouseListener listener) Adds a listener interface to receive mouse events.
4	void addMouseWheelListener(MouseWheelListener listener) Gets this widget's parent panel.
5	int getHeight() Gets the height of the image.
6	int getOriginLeft() Gets the horizontal co-ordinate of the upper-left vertex of the image's visibility rectangle.
7	int getOriginTop() Gets the vertical co-ordinate of the upper-left vertex of the image's visibility rectangle.
8	java.lang.String getUrl() Gets the URL of the image.
9	int getWidth() Gets the width of the image.
10	void onBrowserEvent(Event event) Removes a previously added listener interface.
11	static void prefetch(java.lang.String url) Causes the browser to pre-fetch the image at a given URL.
12	void removeClickListener(ClickListener listener) This method is called immediately before a widget will be detached from the browser's document.
13	void removeLoadListener(LoadListener listener) Removes a previously added listener interface.
14	void removeMouseListener(MouseListener listener) Removes a previously added listener interface.
15	void removeMouseWheelListener(MouseWheelListener listener) Removes a previously added listener interface.
16	void setUrl(java.lang.String url) Sets the URL of the image to be displayed.
17	void setUrlAndVisibleRect(java.lang.String url, int left, int top, int width, int height) Sets the url and the visibility rectangle for the image at the same time.
18	void setVisibleRect(int left, int top, int width, int height) Sets the visibility rectangle of an image.
19	static Image wrap(Element element) Creates a Image widget that wraps an existing <img> element.

Methods Inherited

This class inherits methods from the following classes:

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

Image Widget Example

This example will take you through simple steps to show usage of an Image Widget in GWT.

Following are the steps to update a GWT application which we created in GWT - Create Application chapter:

Step	Description
1	Create a project with a name HelloWorld under a package com.jtc as explained in the GWT - Create Application chapter.
2	Modify HelloWorld.gwt.xml, HelloWorld.css, HelloWorld.html and HelloWorld.javaas explained below. Keep rest of the files unchanged.
3	Compile and run the application to verify the result of the implemented logic.

Following is the content of the modified module descriptorsrc/com.jtc/HelloWorld.gwt.xml.


Following is the content of the modified Style Sheet file war/HelloWorld.css.


Following is the content of the modified HTML host file war/HelloWorld.html.


Let us have the content of Java file src/com.jtc/HelloWorld.java which will demonstrate the use of Image widget.


Once you are ready with all the changes done, let us compile and run the application in development mode as we did in GWT - Create Application chapter. If everything is fine with your application, this will produce following result:

GWT - Anchor Widget

Introduction

The Anchor widget that represents a simple <a> element.

Class Declaration

Following is the declaration for com.google.gwt.user.client.ui.Anchor class:


CSS Style Rules

Following default CSS Style rule will be applied to all the Image widget. You can override it as per your requirements.


Class Constructors

S.N.	Constructor & Description
1	Anchor() Creates an empty anchor.
2	protected Anchor(Element element) This constructor may be used by subclasses to explicitly use an existing element.
3	Anchor(java.lang.String text) Creates an anchor for scripting.
4	Anchor(java.lang.String text, boolean asHtml) Creates an anchor for scripting.
5	Anchor(java.lang.String text, boolean asHTML, java.lang.String href) Creates an anchor with its text and href (target URL) specified.
6	Anchor(java.lang.String text, boolean asHtml, java.lang.String href, java.lang.String target) Creates a source anchor (link to URI).
7	Anchor(java.lang.String text, java.lang.String href) Creates an anchor with its text and href (target URL) specified.
8	Anchor(java.lang.String text, java.lang.String href, java.lang.String target) Creates a source anchor with a frame target.

Class Methods

S.N.	Function name & Description
1	HasDirection.Direction getDirection() Gets the directionality of the widget.
2	HasHorizontalAlignment.HorizontalAlignmentConstant getHorizontalAlignment() Gets the horizontal alignment.
3	java.lang.String getHref() Gets the anchor's href (the url to which it links).
4	java.lang.String getHTML() Gets this object's contents as HTML.
5	java.lang.String getName() Gets the widget's name.
6	int getTabIndex() Gets the widget's position in the tab index.
7	java.lang.String getTarget() Gets the anchor's target frame (the frame in which navigation will occur when the link is selected).
8	java.lang.String getText() Gets this object's text.
9	boolean getWordWrap() Gets whether word-wrapping is enabled.
10	void setAccessKey(char key) Sets the widget's 'access key'.
11	void setFocus(boolean focused) Explicitly focus/unfocus this widget.
12	void setHorizontalAlignment(HasHorizontalAlignment.HorizontalAlignmentConstant align) Sets the horizontal alignment.
13	void setHref(java.lang.String href) Sets the anchor's href (the url to which it links).
14	void setHTML(java.lang.String html) Sets this object's contents via HTML.
15	void setName(java.lang.String name) Sets the widget's name.
16	void setTabIndex(int index) Sets the widget's position in the tab index.
17	void setText(java.lang.String text) Sets this object's text.
18	void setWordWrap(boolean wrap) Sets whether word-wrapping is enabled.
19	static Anchor wrap(Element element) Creates an Anchor widget that wraps an existing <a> element.

Methods Inherited

This class inherits methods from the following classes:

• com.google.gwt.user.client.ui.UIObject
• com.google.gwt.user.client.ui.Widget
• com.google.gwt.user.client.ui.FocusWidget

Anchor Widget Example

This example will take you through simple steps to show usage of an Anchor Widget in GWT. Following are the steps to update the GWT application which we created in GWT - Create Application chapter:

Step	Description
1	Create a project with a name HelloWorld under a package com.jtc as explained in the GWT - Create Application chapter.
2	Modify HelloWorld.gwt.xml, HelloWorld.css, HelloWorld.html and HelloWorld.javaas explained below. Keep rest of the files unchanged.
3	Compile and run the application to verify the result of the implemented logic.

Following is the content of the modified module descriptorsrc/com.jtc/HelloWorld.gwt.xml.


Following is the content of the modified Style Sheet file war/HelloWorld.css.


Following is the content of the modified HTML host file war/HelloWorld.html.


Let us have following content of Java file src/com.jtc/HelloWorld.java which will demonstrate use of Anchor widget.


Once you are ready with all the changes done, let us compile and run the application in development mode as we did in GWT - Create Application chapter. If everything is fine with your application, this will produce following result:

---