The FileUpload widget acts as a GWT wrapper to the standard browser file-upload text box—the one you use to let the user upload a file from their machine to your server. (See figure 4.5.)

Figure 4.5. The FileUpload widget

Remember that this is only the client-side component—clicking the Browse button allows the user to select a file on their computer through the standard File Search dialog box, but it doesn’t let you save a file to your server. That takes a little more work. This widget should be embedded in a form that has its encoding set to multipart. When ready, you submit the form to your server to process the uploading of the file selected (an example of this functionality is provided in the FileUploadServlet class in the server package of the Dashboard). This widget doesn’t provide any server-side code to handle file upload; you have to provide that, but you’re free to do so in your favorite server-side language. We’ll look at such a FileUpload widget in more detail when we discuss server-side components in chapter 12; we’ll also consider it briefly later in this chapter when we discuss how to build widgets.

The FileUpload widget is one of the most inconsistently implemented widgets across browsers; different browsers allow differing security restrictions and abilities to style it. Most browsers, for example, won’t let you set the default value of the text box because that would allow a web application to go fishing for files. As with all widgets, remember that if you can’t do something with the widget in HTML and JavaScript, then you can’t do it in GWT. GWT only provides a getFilename() method that retrieves the filename selected by a user. Don’t confuse this method with the getName() and setName() methods, which are used to set the DOM name of the FileUpload widget.

But enough of file uploading until chapter 12. We’ll now continue looking at some of the other basic widgets that GWT provides.

The Hyperlink widget acts as an internal hyperlink in your GWT application. To the user, it looks exactly like a normal hyperlink on the web page; when they click it, they expect navigation to occur in the application. This action is usually coded as manipulating the GWT History object to change the application state—you can see how this works in the Dashboard’s Slideshow application (org.gwtbook.client.ui.slideshow.Slideshow). The application has two hyperlinks at the bottom, as shown in figure 4.6, which enable the user to move the slideshow to the start or the end.

Figure 4.6. Two Hyperlink widgets (Start and End) in action at the bottom of the Slideshow Dashboard application

Any component that uses a Hyperlink widget should also extend the HistoryListener interface and implement the onHistoryChange() method to catch and manage clicks the hyperlinks. As you can see, the Dashboard’s Slideshow component implements two hyperlinks, which can be found in the code as follows:

Hyperlink startLink = new Hyperlink("Start","0");   
Hyperlink endLink = new Hyperlink("End",""+(maxNumberImages-1));  

Each Hyperlink widget constructor comprises two elements: the text to be displayed on the screen and a history token (which can be any arbitrary string). In the Slideshow’s case, all the history tokens represent numbers of a picture, starting at 0 for the first and ending at the maximum number of images in the slideshow minus one. It’s easy to have a hyperlink that points to the start and end of the slideshow by using the appropriate values in the Hyperlink constructor—“0” for the start (as shown in ) and the string representation of the largest image number (as shown in ).

When you’re using GWT History, remember to include the following line in the body of your HTML page:

<iframe id="__gwt_historyFrame"
        style="width:0;height:0;border:0">
</iframe>

Failure to include the history frame will result in errors, because it’s used in GWT’s approach to storing and retrieving history tokens. This error in hosted web mode is visible by errors in the hosted web mode console, as shown in figure 4.7 (however, you’ll get no similar warning in web mode).

Figure 4.7. Error raised when you try to use the GWT History subsystem in hosted mode without its being properly initialized

(The rebinding message in figure 4.7 is a result of GWT manipulation you’ll perform later in the book using GWT generators to take the basic component application and automatically generate new code to show an About menu item.)

Using methods in the Hyperlink class, it’s easy to get the history token associated with a particular link (getTargetHistoryToken()) or update the token if you wish (setTargetHistoryToken()). Similarly, you can set the hyperlink’s text or get it through the setText() and getText() methods respectively (or the HTML using setHTML() and getHTML() if you’ve created the hyperlink so the text is treated as HTML, using the Hyperlink(String, boolean, String) constructor instead of the more simple Hyperlink(String, String) version), which treats the hyperlink as simple text.

Treating hyperlink text as HTML means that any mark-up code—such as text in bold, underlines, and images—is displayed. If you want a normal hyperlink to, say, another HTML page, then use the HTML widget, which we’ll look at later, rather than a Hyperlink widget that has its text set to some HTML.

Hyperlinks are one way to navigate through an application; another is to use a menu system.

The menu system provided by GWT is based on the MenuBar and MenuItem widgets. MenuItems are added to MenuBars, and MenuBars are added to other MenuBars, to create your application’s menu system. Figure 4.8 shows the Dashboard menu system, where Clock, Calculator, and Slideshow MenuItems are added to a Create MenuBar; this Create MenuBar and a Help MenuBar are then added to another MenuBar, which is displayed on the browser page.

Figure 4.8. MenuBar and MenuItem widgets used in the Dashboard application. In this example, three MenuItems are placed in one MenuBar, which is then added to an overall MenuBar.

In the Dashboard class (org.gwtbook.client.Dashboard), you define one global MenuBar using the following code:

MenuBar menu = new MenuBar();

This simple line creates a horizontal menu bar. (It could just as easily be created using the alternative constructor, which takes a boolean parameter whose value is set to false: for example, new MenuBar(false). If the parameter is set to true, a vertical MenuBar is created.) At present, the Dashboard will have two standard menu bars; you’ll create two additional ones later in this book, and further down the Dashboard code you can find two methods used to build the create and help menu bars. The method buildHelpMenu(), shown in listing 4.1, builds the initial Create menu bar using vertical menu bars.

Example 4.1. Building the Dashboard’s Create menu bar and menu items, and the nested Locale menu bar

You create vertical menu bars by passing the Boolean value true as a parameter in the constructor (see ). In a MenuBar, one or more MenuItems or other MenuBars go together to give the visual structure shown in figure 4.8. It’s possible to create MenuItems inline in the code, which is what you do at where the first parameter to the addItem() method is a new MenuItem. Each MenuItem is bound to a segment of code, the second parameter to the addItem() method, which is executed when that menu item is clicked.

You use the command pattern to describe the command that will be executed when a menu item is clicked. In practice, this means you create a new instance of either the GWT Command class or a subclass, which contains an execute() method where the code is stored. For the Dashboard, we decided to define a number of Command subclasses as inner classes to the Dashboard, because this best met our needs. An example of one of these classes is shown in listing 4.2 (this command is attached to the MenuItems defined in of listing 4.1).

class ChangeLocaleToEnglishCommand implements Command{
  public void execute(){
    Window.removeWindowCloseListener(dashboardWindowCloseListener);
    changeLocale("");
  }
}

Using the command pattern allows the GWT application to turn a request for future functionality into an object that can be passed around the code; the defined functionality can then be invoked later. In the case of the menu items, GWT provides the plumbing so that when a menu item is clicked, the associated command’s execute() method is invoked. In this example, when the user clicks a menu item whose command is set to an instance of the ChangeLocaleToEnglishCommand class, then this execute() method is invoked, and a WindowCloseListener is removed from the application before the changeLocale() method is called. (Otherwise, you invoke both of the window-closing events you’ll set up in chapter 6—in the case of the Dashboard, these event handlers display two alert boxes, which you don’t want to happen if you’re just changing the locale.)

You can interrogate a MenuItem to find out what its parent menu is through its getParentMenu() method, as well as find out whether it opens a submenu through its getSubMenu() method. Similarly, you can set the submenu of a MenuItem through the setSubMenu() method, but not its parent menu. In some applications, you may need to change the command associated with a particular MenuItem (setCommand()) or find out what that command is (getCommand()).

The final implementation aspect of a MenuItem we want to discuss relates to the text shown as the item itself. This text can be treated either as pure text or as HTML, depending on whether a Boolean parameter is provided in the constructor of the MenuItem. As with any widget that can allow HTML to be set, you should always take care that you don’t expose the application to script-based security issues. Creating a menu item using new MenuItem(String, true, Command) treats the String as HTML; using the MenuItem(String, false, Command) or MenuItem(String, Command) constructor treats it as pure text.

A MenuBar widget lets you define whether its child menus open automatically or wait for the user to click them to open. The setAutoOpen() method achieves this. In the Dashboard, you do this in the onModuleLoad() method, where you create the whole menu system using the code shown in listing 4.3.

Example 4.3. Creating the Dashboard’s menu system

At the top of the screen is the Dashboard’s menu system, shown in figure 4.9, which is involved in the code a number of times. The Help and Create menu bars are created as simple implementations for an Internet view (in the Dashboard class) and then overridden to provide a more functional intranet version (in the Dashboard_intranet class). The version used, intranet or Internet, is chosen by using GWT user-defined properties and setting the user-defined externalvisibility property in the Dashboard.html file (we describe all this in chapter 15).

Figure 4.9. The Dashboard menu system, showing the four possible menu bars. The Help and Create menu bars are always present, the Bookmarks menu is loaded as XML from the server, and the option menu bar is shown when a component application gains focus.

The text for these two menu bars is created using GWT internationalization constants set up for a default (English) locale and an alternative Swedish locale. This internationalization approach, which we looked at briefly in chapter 3, is expanded on in chapter 15.

You also use the two new MenuItem widgets you’ll create later in this chapter in the Dashboard’s menu system. When running in intranet mode, the Help menu bar lets the user turn on/off the confirmation requested when they delete a component application; they do this through a TwoComponentMenuItem. In both modes, the user can change the locale through two TwoComponentMenuItems: one for each locale supported by the application. You can see the intranet view of the Help menu in figure 4.10, where both new widgets are in use.

Figure 4.10. Examining the Dashboard’s menu system and showing off the two new MenuItem widgets built in this chapter. The English and Swedish locale MenuItems are instances of the TwoComponentMenuItem, and the Confirm Delete MenuItem is an instance of the ToggleMenuItem (it’s shown in the ON state).

You also manipulate the menu bar in two further ways. First, you create a bookmark menu bar whose contents are loaded from an external XML file using the GWT implementation of the XMLHttpRequest object; this is covered in chapter 12. Second, each component application can register an option menu, which is shown in the main menu when the application gains focus (you use a GWT generator, discussed in chapter 14, to automatically generate an About item in the option menu for each application; it lists all the methods and fields included in the application). Figure 4.10 shows the option menu for the Google Search component application. These component applications also have some generic functional requirements placed on them.

The final point to note about the MenuBar is that it implements the PopupListener interface, which allows functionality to be fired when the MenuBar is closed. If you wish to use different functionality than the standard when the MenuBar closes, then you can override the existing class and implement your own onPopupClosed() method. (You don’t use this functionality in the Dashboard.)

We’ve nearly completed our look at most of the basic widgets in GWT. Two are left, the first of which is the Tree widget. This widget provides applications with a standard hierarchical tree comprising TreeItem widgets. (See figure 4.11.)

Figure 4.11. The Dashboard’s Book application, showing the Tree widget on the left. In chapter 6, you’ll see how events are used when TreeItems are selected or expanded.

A Tree is built similarly to the way you built a menu earlier. In that case, you added a number of MenuItems to a MenuBar; here, you’ll add TreeItems to a Tree. The constructors for a TreeItem are flexible and allow you to create an empty TreeItem or TreeItems from Strings or other widgets (which could mean a standard widget or a composite widget). In listing 4.4, which comes from the Dashboard’s Book application (org.gwtbook.client.ui.book.Book), you build a simple tree to represent the top-level structure of the book.

Example 4.4. Creating the Dashboard’s Book tree system

Unlike in the menu system, you don’t add commands to MenuItems to implement functionality when they’re clicked or expanded; instead, you implement a TreeListener. Doing so requires you to implement two methods: an onTreeItemSelected() method, which is fired when a MenuItem is selected; and the onTreeItemStateChanged() method, which is invoked if the state (opened or closed) of a TreeItem changes.

For the Dashboard Book application, you implement the TreeListener as shown in listing 4.5.

Example 4.5. Adding event handling to the Dashboard’s Book tree to change the display text

This listener calls the Dashboard application’s changeText() method to fill in the text box at right in the Book application with text when a TreeItem is selected . When the state of a TreeItem changes, then the onTreeItemStateChanged() method is called. This method retrieves the state of the MenuItem that was changed and, if this item is now open, places the text of the time at the bottom of the widget by retrieving it using the getText() method . Otherwise, it places dashes as the text.

A TreeItem comes with a host of helper methods that you can invoke to learn more about or change existing properties of the item. You can find out the child at a particular index (getChild(int index)), count the number of children (getChildCount()), or get the index of a particular child (getChildIndex(TreeItem)). Additionally, you can get the Tree a particular TreeItem is in (getTree()), find out if an item’s children are currently displayed (getState()), determine its parent item (getParentItem()), and find out whether it’s currently selected (isSelected()).

A TreeItem may have a widget associated with it, though if it does, it can’t directly have text associated (unless it’s set up as a composite widget). Often, you may associate a CheckBox, for example, with TreeItems. You associate a widget with a TreeItem either through the setWidget() method or by using the TreeItem(Widget) constructor.

Finally, the various states of the TreeItem, whether an item is closed or open, are shown as images. By default, these images are in the public folder of your application and are called tree_closed.gif, tree_open.gif, and tree_white.gif. You can replace these images with your own versions if you wish—just keep the names the same. If you’d like to store the images in a different directory, indicate the location using the setImageBase() method.

If you wish to display an image in a GWT application, you can use the Image basic widget. This widget allows images to be loaded and displayed, as you can see in figure 4.12.

Figure 4.12. The Image widget in the Dashboard’s Slideshow application

An interesting aspect of the Image widget is the ability to add a LoadListener to it so that a particular action can be performed when the image has completed loading (onLoad()), or another action can be performed if there is an error loading the image (onError()).

Listing 4.6 shows the code from the Dashboard’s Slideshow component (org.gwt.client.ui.slideshow.Slideshow), which can be used to preload images into an application.

Example 4.6. Preloading Slideshow images with a LoadListener

The preloadImages object is a HorizontalPanel, which you add to the application specifically for the future use of preloading images. Due to the way the GWT event mechanism works, you need to have the images loading into a component that is added to the browser page (if they aren’t, then there is no hook into the event mechanism, and the LoadListener is ignored). However, there is no requirement for the component to be visible, so in you set it to be invisible to avoid an unsightly mess!

You add a new LoadListener at and define the onError() method to just put a JavaScript alert on the screen if there is an error ; or, if the image loads, you change the title bar of the browser window to show the image name using the Window.setTitle() method .

Once you have an Image object, it’s possible to use the prefetch() or setUrl() method to load a new image rather than creating new objects as you did in the example. Either way is valid, and you’ll choose which way to set it up in your own applications.

You should also be aware that when you use a transparent PNG image over another image in Internet Explorer 5.5 and 6, ugly backgrounds start to get applied. You’ll build a new widget later in this chapter that overcomes these problems.

An exciting addition that came with GWT 1.4 is the ability to bundle together and clip images. The original Image class gained a new method that allows you to display only a portion of the image. For example, to display only the top left 50x50 pixel square of an image, you can use the constructor new Image("image.png", 0, 0, 50, 50).

The ultimate purpose of clipping an image is optimizing the load time of your GWT application. Loading one image containing a number of images you’ll use is more efficient than loading each of the images individually. Let’s look at an HTML page that loads the five images displayed in the Events Widget Browser Dashboard application. When you have a simple page that loads all five images separately, the Firebug extension to Firefox reports the timelines shown in figure 4.13.

Figure 4.13. The Dashboard’s Server Status application showing GWT Label widgets in action

The five images take around 130ms to download. The images are coming from a web server local to the machine; but look at the results shown in figure 4.14, where we manually created an image that contains all the five images in one. You’re down to 50ms to load the images. Extend this to a larger application that is loading images across a real network, and you can begin to see that there are distinct advantages to bundling images together. There’s a disadvantage as well, though: Do you want to manually manipulate all the images you have into one? Luckily, GWT provides the ImageBundle class that gets around this problem. You provide your images as you want and create an interface that extends ImageBundle that references your images, and GWT does the work of putting them together for you. Let’s look at that in more detail.

Figure 4.14. All five images displayed in one

In the Public folder of the Dashboard application, create a ToolbarImages folder into which you place all the individual images for the toolbar. Then, in the org.gwtbook.client.ui.EventsWidgetBrowser package, create a new interface class that extends ImageBundle; a sample of that interface is shown in listing 4.7.

Example 4.7. Creating an ImageBundle

The interface defines a method for each image that will be bundled together, and the GWT-generated implementations of these methods are used to extract the clipped images. By default, GWT takes the images from within the package in which the bundle interface is defined (this is different from other images/resources) and looks for an image named after the method name. To play nicer with the application structure, you can direct GWT to take the resource from a location of your choosing. This is achieved by using annotations in the comments; for example, tells the compiler to get the image returned by the ChangeEvents() method from the ToolbarImages directory.

Using the bundled image is simple. Listing 4.8 shows the case of creating an instance of your image bundle, via the deferred binding approach. With access to the image bundle, you call the appropriate methods for the image we wish to use, and that method returns an AbstractImagePrototype. To get the Image you’re after, you call the createImage() method on the AbstractImagePrototype. Now, you have a standard Image that can be added to your application.

Example 4.8. Creating an ImageBundle

But images aren’t the only thing you can display on the application. You also have a range of ways to display text.

A Label widget contains arbitrary text, which is displayed exactly as written. This means the Label created by the code new Label("Hi <B>there</B>") appears on the browser page exactly as “Hi <b>there</b>”—the word there isn’t interpreted as HTML and isn’t shown in bold text.

It’s possible to control the horizontal alignment of labels, although by default the size of a Label widget is the size of the text it encloses. Right-aligning, using the following command

theLabel.setHorizontalAlignment(HorizontalAlignmentConstant.ALIGN_RIGHT)

has little visible affect unless you use a style sheet (or, less preferably, the theLabel.setWidth() method) to set the width of the label to be longer than the text. The alignment you see in the Dashboard’s Server Status application (org.gwtbook.client.ui.serverstatus.ServerStatus), shown in figure 4.15, is achieved by aligning Labels in a Grid panel (see chapter 5). A Label may also word-wrap if the setWordWrap() method is called; this method takes a Boolean variable that is set to true if the Label should word-wrap and false otherwise.

Figure 4.15. The Dashboard’s Server Status application showing GWT Label widgets in action

GWT allows you to add ClickListener and MouseListener to a standard Label widget, offering the possibility of capturing the user trying to interact with the Label. By default, no action occurs; you have to add click or mouse listeners. In the EditableLabel widget you’ll build in chapter 7 (org.gwtbook.client.ui.EditableLabel), when a user clicks the label, you present a text box instead of the label; they can use it to change the text of the label. You add the click listener as shown in listing 4.9.

text = new Label(labelText);
text.setStyleName("editableLabel-label");
text.addClickListener(new ClickListener()
{
   public void onClick (Widget sender){
      changeTextLabel();
   }
});

The ClickListener acts similarly to the Command you used in the MenuItem widget. It registers an onClick() method that GWT executes when the user of the application clicks the label.

Once you have a label, you can change the text programmatically using the setText() method (as well as get the current text using the getText() method). See listing 4.10.

Example 4.10. Changing the label text in the Clock application through the setText() method

You can also use a slightly more active text-presenting widget if you wish: the HTML widget.

If you want to provide more funkiness with the presentation of text, then the HTML widget may be the component you’re looking for. It acts the same as a Label widget, but—this is important—it interprets any text as arbitrary HTML. Whereas in the label the text “Hi <B>there</B>” is written as is, if you write the code new HTML("Hi <B>there</B>"), the text is displayed as “Hi there”.

The HTML widget is also useful if you wish to provide a true hyperlink. When we looked at the Hyperlink widget, you learned that you can present what looks like a hyperlink to the user, but when clicked, it only changes the historical aspect of the application. If you use an HTML widget instead, then you can provide proper links, as you’ll do later in the About application to link to the book’s web pages:

new HTML("<a href='http://www.manning.com/hanson'>Manning</a>");

You must be careful with this widget because allowing arbitrary HTML can expose security issues to your application if maliciously constructed HTML is used. Also consider whether the HTML Panel we’ll discuss in chapter 5 is more appropriate for your needs.

Labels and HTML are a useful way of presenting information to a user, but there is another half of interacting with the user: capturing their input.

In the Dashboard, we wanted to introduce flexibility into the About component application (org.gwtbook.client.ui.about.About). Rather than hard-code the about message, we decided that it should be loaded from a separate HTML file. To support that functionality, you use the Frame widget, into which you can easily load a new HTML page. You do this either through the constructor, such as new Frame("resource-to-load"), or through the widget’s frame.setURL("resource-to-load") method.

Figure 4.16 shows the basic About component application in the Dashboard, where the contents are loaded from another HTML file (About.html, if you’ve downloaded the example code). Because the widget represents an IFRAME DOM element, this content can easily be created from a static HTML file, JSP, servlet, PHP script, .NET application, and so on.

Figure 4.16. Using the Frame widget in the Dashboard About dialog. The contents of this display are loaded from another HTML file into a frame.

A subclass of the Frame widget is the NamedFrame widget, which lets you associate a name. These NamedFrames are typically used as targets for the FormPanel—and you’ll see this in action in chapter 12, when we deal with forms.

The ListBox widget is used extensively in the Dashboard’s Address Book application (org.gwtbook.client.ui.addressbook.AddressBook), as shown in figure 4.17. It presents a list of choices to the user, either as a drop-down or as a standard list box. In the Address Book application, you use the listbox form for selecting names and in drop-down form for selecting countries.

Figure 4.17. The Dashboard Address Book application uses both forms of the ListBox widget. Names are stored in a normal format list box, and countries are selected from a list box in its drop-down style.

To create a normal format list box, you use the standard constructor new ListBox(), as shown in listing 4.12.

Example 4.12. Creating a standard ListBox and adding a ChangeListener to the Address Book application

After creating the ListBox object , you set the maximum number of visible items that will be shown through the setVisibleItemCount(number) method; this is effectively the height of the list box. For the Address Book, you display 10 items as standard; if there are more, then the widget acquires a scroll bar.

Having a list box provides a way of presenting choices to the user. To understand which item the user selects, you add a ChangeListener to the ListBox . When the selected value in the list box is changed, the onChange() method is called. You use this change listener to show the address of the new person by first finding out the index of the option the user selected (using the getSelectedIndex() method, ) and then passing that index value as the parameter to the getItemText() method to get the text representation of the selected option . This returned text is then used as a parameter in the Address Book’s showAddress() method.

The alternative view of ListBox as a drop-down box of options is created by setting the visible item count to 1. For variety in the Address Book, you subclass the ListBox widget to provide a country choice drop-down widget, as shown in listing 4.13.

Example 4.13. Creating a drop-down list box for the Dashboard’s Address Book application

You select an option programmatically using the setSelectedIndex(value) method. This method works best, and makes more sense, when the list box is in its drop-down view; you use it in the Dashboard to ensure that the correct country option is shown for each address.

One thing you don’t do in any of the Dashboard component applications is allow the list box to have multiple selections. To do so is just a case of using the setMultipleSelect() method. If you do that, then you need to be a little more intelligent when getting the selected item, because the getSelectedItem() method returns only the first selected item. To get all the selected items, you need to iterate over all the items, calling the isItemSelected() method for each item to determine whether it’s selected.

Using a list box gives the user a wide range of choices. If you wish to be more careful about the range of choices offered to the user, then you should consider using one of the widgets that extends the ButtonBase widgets.

These widgets include Button along with RadioButton and CheckBox. ButtonBase provides the standard methods common to its three children—for example, setting and getting the text associated with them through the setText() and getText() methods or the similar methods for the HTML (setHTML() and getHTML()).

Let’s look at these three children and how you use them in the Dashboard.

The Button widget is one you’ve already seen in this chapter. It’s a push button in the style normally found on web pages. It’s created by calling the constructor as follows:

new Button("7");

You can see the Dashboard’s calculator buttons all lined up in figure 4.18. You add them to a Grid panel and also apply some CSS styling to change the normal gray button/black text to a light blue button/green text—although that may not be visible in the book!

Figure 4.18. A range of Button widgets set out to form the keypad of the Calculator Dashboard application

Normally, you register a ClickListener with the Button in order to perform some functionality when the button is clicked. For the keys that represent the operation buttons (plus and so on) in the Dashboard’s Calculator application (org.gwtbook.client.ui.calculator.Calculator), you add click listeners to the button:

Button w = new Button("+");
w.addClickListener(new ClickListener(){
   public void onClick(Widget sender) {
      performCalculation(op);
   }
});

When you press keyboard buttons while focused in the Dashboard Calculator application, you wish to perform the same functionality as if you clicked the buttons. You achieve this by programmatically executing the clicking of a button by calling the button.click() method.

Buttons are one subclass of the ButtonBase widget, but there are two more. Next, we’ll look at the CheckBox.

The CheckBox widget implements the standard browser check box functionality (see figure 4.19). In normal pre-Ajax applications, this widget was usually found in a Form, and the values were submitted to the server when the form is submitted. In the Ajax world, this isn’t a constraint anymore; yes, it’s still found in forms, but it can also function as a standalone component. If you’re using it standalone, you can add a ClickListener to it, so that some segment of code can be executed when the element is checked or unchecked. You’ll do this in chapter 5 for the Dashboard application.

Figure 4.19. CheckBox components in action

The final widget we’ll look at that’s included with the GWT distribution as a subclass of ButtonBase is the RadioButton widget, which provides the implementation of a set of mutually exclusive selections. As with the CheckBox, it’s common to see this either in a form or standing alone. Unlike CheckBox, you need a way to indicate which RadioButtons are included in a particular group. You do this in the constructor, which has three forms, all of which require the definition of a group name. Listing 4.14 shows the construction of two groups of radio buttons.

Example 4.14. Creating two groups of a radio buttons

If management of choices isn’t the purpose of your application and you need a freer way to let users express themselves, then the next set of widgets in the TextBoxBase family are probably the ones you’re after.

The PasswordTextBox widget represents the standard browser text box that masks its input when the user types in values. It’s commonly used to allow application users to enter passwords. The Dashboard includes a simple security application called the Login component (org.gwtbook.client.ui.login.Login), which uses the PasswordTextBox as shown in figure 4.20.

Figure 4.20. PasswordTextBox in the Dashboard Login application hides the characters being typed for the password.

This widget is easily created using the PasswordTextBox() constructor, but it includes no other methods except those inherited from the TextBoxBase widget.

The TextArea widget allows application users to enter text that has multiple lines. In the Dashboard, you use this widget in the EditableLabel composite widget (see chapter 7) as shown in action in figure 4.21.

Figure 4.21. Using the TextArea in the EditableLabel composite widget built for the Dashboard (we’ll look at this in more detail in chapter 7)

Creating a TextArea is a simple case of using the TextArea() constructor. From there, you can set the width and height of the TextArea either through CSS or by using the provided setCharacterWidth() and setVisibleLines() methods.

Sometimes you don’t need multiple lines of text, and in that case the TextBox widget is more appropriate.

If you don’t need multiple lines of text that can be edited, then TextBox is probably a more appropriate widget. In the Dashboard, you use text boxes in a number of places, including in the Calculator Dashboard application; a user can enter numbers directly in the screen area as well as by clicking buttons (see figure 4.22).

Figure 4.22. The TextBox widget in the Dashboard Calculator application

One aspect of TextBoxBase widgets we haven’t discussed is the ability to trap keypresses and either change or cancel them through using a KeyboardListener. In the Calculator, you don’t want users to have the ability to enter anything except numerical characters in the text box. You achieve this using the code given in listing 4.15.

Example 4.15. Cancelling keypresses in the Calculator display through a KeyboardListener

First, you associate a KeyboardListenerAdapter with the text box (theDisplay) and then override its onKeyPress() method. In that method, you check to see if the keyCode is a digit by using the Java Character.isDigit() method. If it isn’t a digit, then you cancel the keypress—which means it doesn’t reach the widget and therefore is never displayed on the browser. The syntax to do this may be a little strange; you have to cast the sender object into a TextBox object before you can call the cancelKey() method, because the listener method only deals with pure Widget class objects.

Just as you can alter some of the stylistic aspects of the TextArea via either the preferred approach of CSS or programmatically, you can do the same with TextBox. Programmatically, you use the setMaxLength() and setVisibleLength() methods. The first method defined the maximum number of characters that can be typed into the text box; the second the maximum number of characters that are visible at any one time.

We hope this discussion has shown that many widgets are available for you to use in your applications and indicated where you’ll use them in future development in this book. However, sometimes this set of simple widgets isn’t enough or doesn’t fulfill the needs of your application. In these cases, you can either create your own widget or extend an existing one.

You want the version of the FileUpload widget to look like exactly like the standard browser file-upload box shown in figure 4.24.

Figure 4.24. Standard browser file-upload GWT widget (this is how you want the widget to appear)

The first step when creating a new widget is to decide which DOM element the widget will implement. In this case, it’s a simple choice: Because you want a FileUpload widget, you need to use a DOM <input> element whose type attribute is set to file (this is the only way in a browser to create the widget shown in figure 4.24).

Next, you decide where the new widget will sit in the hierarchy that already exists. The approach sometimes involves a little trial and error because the hierarchy is large. Taking a common-sense approach, you want the widget to be notified of focus events and clicks, so you choose for it to sit under the FocusWidget class.

The widget is rather like a text box, and a user may expect it to behave in such a way, so TextBoxBase is also a good candidate; but there are a number of issues with this. It isn’t possible to set the text of the underlying input DOM element due to valid security restrictions implemented by most browsers. Plus, the notion of text alignment isn’t valid for this type of widget. Choose for this widget to extend FocusWidget as well as implement the HasText interface (which indicates that there is text you can set and get in this widget).

The widget consists of the code shown in listing 4.16.

Example 4.16. The FileUpload widget

At , you state the name of the new widget and say that it will extend the FocusWidget class as just discussed. You’ll inherit a number of methods from there. You also say that this widget will implement the HasText interface, which means you have to provide setText() and getText() methods.

Next , you define the constructor of this widget. Here you introduce the direct DOM manipulation we’ve discussed in this section so far. Initially, you need to create the DOM input element, using the following code:

DOM.createElement("input")

This creates the <input> element, which you then use in the FocusWidget’s constructor, which is accessed through the call to super() to establish the widget. This also sets the element field of the widget to be this new <input> element.

To complete the widget, you use more DOM manipulation approaches to set the type of the element (file) and its name:

DOM.setAttribute(getElement(), "type", "file");
DOM.setAttribute(getElement(), "name", name);

The getElement() method retrieves the widget’s underlying element that was set in the call to the FocusWidget’s constructor. You use this returned element in the two setAttribute() calls to set both the type and name attributes.

After the constructor has completed the element, you have the following DOM element held as the Java object:

<INPUT type="file" name="name" __eventBits="7040"/>

The eventBits has been set, although you haven’t asked for it. These values appeared because you’re extending the FocusWidget that has these values set.

Because you’ve implemented the HasText interface, you need to provide the two methods that this interface requires. First is the getText() method. For the FileUpload widget, it makes sense that the value returned is the value of the filename selected by the user. To get this value, you must perform some more DOM manipulation; this time, you use the getAttribute() method, as follows, to retrieve the value of the file input box :

return DOM.getAttribute(getElement(), "value");

Another consequence of implementing the HasText interface is that you must provide the setText() method . The majority of browsers place security restrictions on setting the text of a browser file-upload input, so you raise an exception if this method is called:

throw new RuntimeException("Not possible to set Text");

You can now use the new widget like any other widget by creating a new instance of it in the Java code, such as this:

FileUpload myUpload = new FileUpload();

As it turns out, this version isn’t too far off the version that now ships with GWT, although that one is a little fancier and more flexible. The steps required to create a new widget by manipulating the DOM are summarized in table 4.3.

That is all there is to it to building a simple new widget from scratch. As we’ve said, though, it isn’t easy to see where this situation will arise, given the increasing completeness of the provided GWT widgets. Most of the time, new widgets come from extending existing ones or creating composite widgets (as you’ll see in chapter 7). The next section looks at how you extend existing widgets; you’ll build three concrete examples for use in the Dashboard later on.

The Dashboard application displays a trash-can image that sits at upper right on screen. In chapter 3, you implemented this as a simple Image widget. However, the Image widget that comes with GWT isn’t that successful in displaying a transparent PNG image over another when you’re using IE 5.5 or 6. This is what you could end up doing in the Dashboard, where the trash icon sits on top of a background image. Also, when you build the slider widget in chapter 7, you’ll be sliding a thumbnail image over a background scale image; if you use the standard Image widget, and the programmer provides two PNG images, then it will look messy.

The problem is that the transparent PNG images acquires a halo effect in IE 5.5 (see figure 4.25) and a horrible background in IE 6 (see figure 4.26).

Figure 4.25. PNG image transparency problem in IE 5.5: a white halo around the star using the GWT Image widget

Figure 4.26. PNG image transparency problem in IE 6: a gray background around the star using the GWT Image widget

The third-party GWT Widget Library includes a PNGImage widget that overcomes this problem. In this section, we’ll walk through the steps we took to develop this widget (to avoid importing the GWT Widget Library into the project yet, you’ll create the PNGImage widget under the org.gwtbook.client.ui package).

Rather than try to create a completely new widget, we decided that PNGImage should behave as much as possible like the standard GWT Image widget, and therefore inheritance from the standard Image widget was the way forward. The widget is made from three classes: a main widget class and two implementation classes (one for IE and one for other browsers). The full code for the implementation class of the PNGImage is shown in listing 4.17.

Example 4.17. The main GWT PNGImage class

Having identified the functionality required for the PNGImage to be exactly the same as the Image widget, except to be able to handle PNG transparency, you indicate that the definition of the PNGImage class extends the Image widget . There are no new interfaces that you wish PNGImage to implement, because you want PNGImage to behave the same as Image.

At you use code similar to that which we looked at when we discussed internationalization. Although in this case, instead of deferring picking the right Java class until you know the locale, you defer the binding until you know the browser in which the code is being executed (this is known technically as deferred binding, which we’ll cover in chapter 15—it’s used here because you need to implement different code depending on whether the browser is IE 5.5/6 or not). If the browser isn’t IE 5.5/6, then the deferred binding picks a class called PNGImageImpl; if not, then it picks a class called PNGImageImplIE6.

At , you create the DOM object that represents the PNG image. You do so by calling the create method on whichever version of the PNGImageImpl class has been selected by the compiler under the deferred binding rules. In the case where the browser isn’t IE 5.5/6, the create method contains the following code to create a standard <image> DOM element and set some attributes:

Element result = DOM.createImg();
DOM.setAttribute(result, "src", url);
DOM.setIntAttribute(result, "width", width);
DOM.setIntAttribute(result, "height", height);
return result;

If the browser is IE 5.5/6, then the create method in the PNGImageImplIE6 class is used. First, it determines whether the image is a PNG image (by crudely looking at the extension). If the file isn’t a PNG image, then the normal constructor is used to create an <img> element. Otherwise, you need to apply a specific IE AlphaImageLoader filter to the image. You do this by creating a <div> element and then setting the innerHTML of that DIV to include the PNGImage plus a specific IE AlphaImageLoader filter, as follows:

Element div = DOM.createDiv();
DOM.setInnerHTML(div, "<span style="display:inline-block;width:" +
                    width + "px;height:" + height + "px;"+
 filter:progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" +
                    url + "', sizingMethod='scale')"></span>");

In all cases, a DOM element is returned to the constructor in the PNGImage class. This element is then set as the element of the PNGImage widget. You can find the full code for the implementation classes in the electronic downloads for the book (http://www.manning.com/hanson).

The events that this widget must sink are the same as for the Image widget, so normally you wouldn’t need to include a new sinkEvents() call. However, in this case you don’t call the Image constructor using (super()), so you must explicitly identify the events you’ll sink . You don’t need to override the onBrowserEvent() method because that is directly inherited from the parent Image widget.

To finalize the widget, you ensure that the methods from the Image class you inherit are handled appropriately. The getURL() method of the Image class is no longer valid in this implementation, so you override it and make it call the browser-specific implementation you’re using to return the correct value.

Finally, for PNG images, it isn’t possible to set the URL, because it’s for an Image widget. This is a case where the parent widget provides more functionality than you can support in the extended widget. You solved this problem by raising a RuntimeException if someone wishes to try to call this method .

The corrected PNGImage now displays correctly in IE 5.5/6, as shown in figure 4.27. The halo effect from IE 5.5 and background from IE 6 are gone, and PNGImage displays a PNG image correctly in all browsers.

Figure 4.27. Corrected IE PNG handling with no halo or background using the new PNGImage widget, which extends the GWT Image widget

You create the new PNGImage object using the standard Java call to its constructor:

PNGImage myImage = new PNGImage("star.png",100,100);

Now that you have the PNGImage class, you can represent the trash icon in the Dashboard application and use safely when building the sliders—both of which we cover later in this book. Next we’ll look at developing another widget that you need for the Dashboard—the ToggleMenuItem widget.