Panels & Layout

The interfaces split what a panel can do.

Source: Javadoc — HasWidgets, Javadoc — IndexedPanel, Javadoc — InsertPanel

The two everyday panels show the shape of the API.

Source: GWT — Panels: Basic Panels

RootPanel.get("sidebar") returns null when the host page has no element with that id (the probe printed null, there is no exception), so a missing id turns into a NullPointerException at the first use unless you test for it. The base Panel.add(Widget) throws UnsupportedOperationException with the message This panel does not support no-arg add(), and the panels whose children need extra information have their own overloads instead: StackLayoutPanel.add(Widget) fails an assertion (Single-argument add() is not supported for this widget), TabLayoutPanel.add(Widget) adds a tab with an empty title, and DockLayoutPanel.add(Widget) adds the center.

Because ComplexPanel and the interfaces above are common to most panels, code that only needs to walk the children can take an IndexedPanel or a HasWidgets.

Source: Javadoc — ComplexPanel

A widget is attached when it is a descendant of RootPanel (or of a panel that was attached through RootPanel), and onLoad() runs when it becomes attached, onUnload() when it stops being. Adding a child to a panel does not attach it if the panel itself is still detached: the child gets a parent but no onLoad() yet. The probe printed this order for a custom panel (the text in square brackets marks the steps of the test): [added to detached panel] onLoad [panel attached], and on removal onUnload, after which getParent() was null. Every panel therefore does two things beyond moving elements: it makes itself the parent of the child (adopt) and it forwards attach and detach to its children (doAttachChildren, doDetachChildren). That is why the writing of a new panel (a later section) is a short list of steps, and why a child can have at most one parent: adding a widget to a second panel first removes it from the first.

RootPanel is the only panel you never create: RootPanel.get() is the body, RootPanel.get(id) an element of the host page that you chose to hand to GWT, which is how a GWT widget is embedded in a server-rendered page (the page can contain several such islands, each with its own id). A FlowPanel is the simplest container, a <div> whose children keep their natural flow; FlowPanel(String tag) builds another element type such as ul, in which case the children should be elements valid inside it. An HTMLPanel starts from HTML and lets widgets take places in it, which is the panel UiBinder uses whenever a template mixes markup and widgets.

Source: Javadoc — HTMLPanel, GWT — SafeHtml

The title and the generated id go through a SafeHtmlTemplates method, which escapes each argument for its position, so a title such as Dune <b> is shown as text and does not become markup. The constructor with a String argument is annotated @IsSafeHtml, which tells static analysis that the value must be a constant, and the rule of this page is the same: build the HTML from constants and escape every value that comes from a user, a server or a database. add(widget, id) puts a widget inside the element with that id, addAndReplaceElement(widget, id) replaces the element with the widget; a missing id throws java.util.NoSuchElementException whose message is the id itself (the probe printed java.util.NoSuchElementException: nope). Put the placeholder in a div or span and not inside an element that cannot contain a block widget, because the browser, not GWT, decides what a p may hold.

SimplePanel holds exactly one widget, and a second add is an error: java.lang.IllegalStateException: SimplePanel can only contain one child widget. Use setWidget to replace the child, which detaches the old one. ScrollPanel, FocusPanel, FormPanel, PopupPanel, SimpleLayoutPanel and ResizeLayoutPanel are all `SimplePanel`s that add one behaviour.

ScrollPanel shows scroll bars when its child is larger than the panel, so it needs a size that does not come from its content: give it one with setSize, with CSS, or by placing it in a layout panel, which is exactly what the Developer Guide recommends. It implements RequiresResize and ProvidesResize, so it also tells a layout-aware child (for example a cell widget) when it was resized. FocusPanel makes any widget focusable and clickable by wrapping it in a focusable <div>; it is the panel that offers all the mouse, key, touch, drag and focus handlers (addClickHandler, addKeyDownHandler, addMouseOverHandler and the rest) that a plain panel does not have.

Source: Javadoc — ScrollPanel, Javadoc — FocusPanel

The key handler is not decoration: a <div> that reacts to clicks must also react to the keyboard, or users who do not use a mouse cannot operate it. For real buttons and links use the widgets of the Widgets page (Button, Anchor), which are focusable and operable by default.

FormPanel wraps its one child in an HTML <form>, which is the way to send multipart/form-data (file uploads), to get the browser’s default form keyboard behaviour, or to post to a server that expects a form. Because it is a SimplePanel, put a FlowPanel or another container inside it for the fields. submit() sends the form to the hidden frame the panel creates, addSubmitHandler runs before the submission and can cancel() it, and addSubmitCompleteHandler receives the response text (getResults()) when the frame has loaded.

Source: Javadoc — FormPanel

A form post that changes state needs the same protection as an RPC call: include the XSRF token as a field (as above) and check it on the server (the XSRF, RPC & Server Security page explains the token flow), and validate the uploaded file’s type and size on the server, never in the browser alone.

HTMLTable is the common base: setText, setHTML, setWidget, getText, getWidget, clearCell, the formatters and the cell-click support (getCellForEvent(ClickEvent)). Grid has a fixed number of rows and columns (change it with resize, resizeRows, resizeColumns, insertRow, removeRow), while FlexTable creates rows and cells when you touch them and lets cells span. The three formatters hold the presentation: getCellFormatter() (alignment, style names, width, height, setWordWrap), getRowFormatter() (style names and visibility per row) and getColumnFormatter() (width and style per column); getFlexCellFormatter() adds setColSpan and setRowSpan.

Source: Javadoc — HTMLTable, Javadoc — FlexTable

The probe printed the result of the formatters as plain markup, which is why the table-based panels are easy to style with CSS selectors on the head class and on the col elements:

On a FlexTable with one cell in row 0 and a cell at (2, 3), the cell counts of the three rows were 1, 0 and 4: GWT creates the missing cells of the touched row but leaves row 1 empty, which is the reason to prefer Grid when every row has the same shape. Grid throws IndexOutOfBoundsException for an index outside its size and FlexTable for a negative one, with the messages in the pitfalls table. Two sizing facts follow from tables being tables: a Grid placed in the center of a DockLayoutPanel kept its natural 34 by 24 pixels in the probe, and it fills the 300 by 200 pixel area only after setSize("100%", "100%"), because the layout panels size their child’s container, and a table does not stretch to fill its container by itself.

AbsolutePanel positions each child at a left and top in pixels (add(widget, left, top), setWidgetPosition, getWidgetLeft, getWidgetTop) and is the panel for drag and drop surfaces and overlays; give it an explicit size. The CellPanel family (HorizontalPanel, VerticalPanel, DockPanel) puts every child in a table cell, so the cell, not the child, carries the alignment and size: setHorizontalAlignment, setVerticalAlignment, setSpacing, setCellWidth(widget, "100%") and setCellHeight apply to the <td>. DeckPanel shows one child (showWidget(index), getVisibleWidget(), and -1 until something is shown), and StackPanel and TabPanel are the table-based stack and tab panels with a header string per child (TabPanel is a tab bar above a DeckPanel and reports selections through addSelectionHandler). They still work, and these are the classes most older code and the book use, so you will meet them, but new application frames should use the layout panels below.

Source: Javadoc — CellPanel, Javadoc — AbsolutePanel, Javadoc — TabPanel

A few more panels in the same package are worth knowing by name.

Source: Javadoc — com.google.gwt.user.client.ui

A DisclosurePanel has a header that the user clicks to show or hide one content widget: new DisclosurePanel("Reviews") builds a text header with the default arrow image, new DisclosurePanel(Widget header) a custom header, and setContent sets the body. It fires OpenEvent and CloseEvent (the classic DisclosureHandler and addEventHandler are deprecated), which makes it the right place to load the content lazily. A third add throws IllegalStateException: A DisclosurePanel can only contain two Widgets.: the message counts the header and the content.

Source: Javadoc — DisclosurePanel

The style names are gwt-DisclosurePanel plus gwt-DisclosurePanel-open or gwt-DisclosurePanel-closed, and the header and content carry header and content class names.

A PopupPanel floats over the page; it is the one panel that you do not add to another panel, you show() it and hide() it, and GWT attaches it to RootPanel itself. Its size comes from its content (setting the width or height forwards to the child), setPopupPosition(left, top) places it, setPopupPositionAndShow(PositionCallback) is called with the popup’s measured size so that you can place it before it appears, center() shows it in the middle of the window, and showRelativeTo(UIObject) puts it below another element, with its left edges aligned, and moves it above or aligns the right edges when it would not fit. Three flags decide how it closes: auto-hide (a click outside closes it; a PopupPanel(boolean autoHide) also closes on a history change), modal (events outside the popup and its children are ignored, new PopupPanel(autoHide, modal)), and setGlassEnabled(true), which adds a "glass" element (default style gwt-PopupPanelGlass) that greys out the page. Animation is off by default (setAnimationEnabled(true) turns it on, with AnimationType.CENTER, ONE_WAY_CORNER or ROLL_DOWN). A DialogBox is a decorated popup with a caption (setText escapes the text, setHTML takes SafeHtml) and a draggable caption bar; new DialogBox(false, true) is the usual modal dialog.

Source: Javadoc — PopupPanel, Javadoc — DialogBox

The DOM of the popup printed by the probe is small, and the dialog is a nine-cell table of styled `<div>`s:

The dialog carries no role or aria-label attribute in 2.13.1 (the probe read an empty role), so a screen reader does not know it is a dialog. com.google.gwt.aria.client.Roles adds them: after Roles.getDialogRole().set(box.getElement()) and Roles.getDialogRole().setAriaLabelProperty(box.getElement(), "Edit book") the element had role="dialog" and aria-label="Edit book". The modal flag stops mouse and keyboard events from reaching the page behind the dialog, but neither PopupPanel nor DialogBox moves keyboard focus into the popup (there is no focus call in either class), so call setFocus(true) on the first field yourself after center().

Each layout panel owns a container <div> and attaches every child in a layer, a position: absolute element, which a helper class, com.google.gwt.layout.client.Layout, positions with CSS constraints. CSS lets you combine left, right, width, top, bottom and height: any two per axis form a valid constraint pair (three would be degenerate), so a child can be pinned 1 em from each edge, or be 50 percent wide and stuck to the left, or have a fixed height at the bottom. The browser’s own layout engine does the work, GWT only writes the constraints, and the panels still behave when the parent resizes, when the child has a border, margin or padding, and when lengths are mixed (em, px, %). The Developer Guide lists the goals: predictable layout in standards mode, correct behaviour with decorations in arbitrary units, as much as possible done by the browser, and smooth automatic animation; the non-goals are quirks mode, Swing-style preferred-size layout (which the guide considers intractable in the browser) and taking over all layout.

The DOM of the Bookshelf shell shows the result: an invisible ruler <div> that the Layout class uses to measure em and ex, and one absolutely positioned layer per child with the constraints from the Java call.

Source: GWT — Panels: Design of the GWT 2.0 layout system, Javadoc — Layout

The first layer is north (left, top, right, height: 3em), the second is south (bottom, height: 2em), and the child inside each layer is stretched over the layer (Chrome prints the pair left: 0; top: 0; right: 0; bottom: 0 as inset: 0px). The em of a layer is the font size of the container, and that depends on your CSS: with the Clean theme inherited by the module, 3em measured 39 pixels (13 pixels per em), and the same call on a page with no theme measured 48.

Source: GWT — Panels: Layout Panels

RootLayoutPanel.get() is the root of a layout-panel application: it fills the body (it ignores body margins, the layer is positioned from the viewport edges), registers a window resize handler once, and calls onResize() on its children when the window changes. You normally add one child, the application panel, and let that child divide the space.

Source: Javadoc — RootLayoutPanel

LayoutPanel is the general mechanism, the one the other layout panels are built on; the closest classic panel is AbsolutePanel, with arbitrary constraints instead of fixed left and top. Each of the six setters (setWidgetLeftWidth and its siblings) takes the two constraints for one axis, and for every pair the values and units are independent.

Source: GWT — Panels: LayoutPanel

In a 400 by 300 pixel LayoutPanel (13-pixel em) the three children measured 200x300 at the left edge, 200x300 starting at x = 200, and 270x170 starting at (65, 65): the third pair is 5 em from every edge, 400 - 2 * 65 = 270 and 300 - 2 * 65 = 170. Layout work is batched: the setters only record the constraints, and the panel applies them in one deferred step (forceLayout() applies them immediately), which is why the animation recipe below calls forceLayout() to fix the starting state.

Hiding a child has a trap that the Developer Guide describes. The panel wraps each child in a container element, and UIObject.setVisible(false) hides the child but not that container, which then still consumes mouse events. The probe put a child under a point and hit-tested it: the visible child was the element found at the point, after child.setVisible(false) the element found was the child’s layer container (an empty-class div), and after panel.setWidgetVisible(child, false) (the call in the snippet above) the container was gone from under the point too. setWidgetVisible hides the child and its layer; DockLayoutPanel.setWidgetHidden hides an edge child by collapsing its size to zero and leaves isVisible() true (the probe measured the north child at 40 pixels, then 0, with isVisible() still true).

A layout panel used without RootLayoutPanel or another ProvidesResize ancestor has no size of its own, because its layer is absolutely positioned and contributes no height to its parent: an unsized LayoutPanel in a FlowPanel measured 1004 by 0 pixels (it took the width of the page and no height). Give it a size (panel.setSize("20em", "10em")) when the parent cannot, and resize it yourself when the parent changes, because no panel can observe an arbitrary element. The same applies inside a PopupPanel or a DialogBox:

Source: GWT — Panels: Recipes

DockLayoutPanel is the same idea as the classic DockPanel without tables: children are docked to the north, south, east or west edge in the order you add them, each with an explicit size along its primary axis, and the last child, the center, takes the rest. All sizes use the one Unit given to the constructor (Unit.EM, Unit.PX, Unit.PCT and so on), the center cannot have a size, and addLineStart and addLineEnd choose the west or east edge by the text direction of the current locale. The size of an edge child can be changed afterwards with setWidgetSize (not for the center), and getWidgetDirection and getWidgetSize read the layout data back.

Source: GWT — Panels: DockLayoutPanel

The order matters: the first edge child is docked first and gets the full edge, the next one gets what remains. In the Bookshelf shell the north and south bars span the whole width because they were added first, and the west navigation fills only the height between them. Add the west child first and it would span the full height with the bars squeezed to its right. The measured sizes in the shell (13-pixel em, 1024 by 768 window) were 1024x39 (north), 1024x26 (south), 156x703 (west) and 868x703 (center).

SplitLayoutPanel is a DockLayoutPanel with a draggable splitter between every pair of children. It supports only pixels (its constructor passes Unit.PX to the superclass), and the splitter is 8 pixels thick unless you pass another size. Use it instead of HorizontalSplitPanel and VerticalSplitPanel.

Source: Javadoc — SplitLayoutPanel

The minimum size, the snap-closed size (a speed bump: below that size the child closes completely) and the double-click toggle are per child, and they have no effect on the center. A dock and a split can be nested, which is how an outer header can be sized in em while the inner split uses pixels (the Developer Guide recipe): in the Bookshelf shell the center of the dock is a SplitLayoutPanel, and in the probe a 200-pixel west child measured 200x703, the splitter 8 pixels, and the tabs 660x703 (868 minus 200 minus 8). setWidgetHidden hides a child and its splitter together.

TabLayoutPanel shows a row of tabs and one child below it; the constructor takes the height of the tab bar and its unit, which you must give. It fires BeforeSelectionEvent (which can be cancelled) and SelectionEvent; selectTab(index) fires them and selectTab(index, false) does not. The first tab added is selected (getSelectedIndex() was 0 right after adding the tabs, with no event), getTabWidget(i) returns the tab’s widget (use add(child, Widget tab) for a custom tab), and setTabText/setTabHTML(int, SafeHtml) change a title (prefer setTabText and SafeHtml for anything that comes from data). StackLayoutPanel shows one section at a time; each add(child, header, headerSize) gives the header text (or a SafeHtml, or a widget) and its size, showWidget opens a section and fires the selection events (stack selected 1 in the probe), and getVisibleIndex() reads the open one (0 at first). DeckLayoutPanel is the building block under TabLayoutPanel: all children are stacked, showWidget shows one with an optional slide (setAnimationDuration, setAnimationVertical), and getVisibleWidgetIndex() is -1 until you show something.

Source: Javadoc — TabLayoutPanel, Javadoc — StackLayoutPanel, Javadoc — DeckLayoutPanel

The probe, in order: before selection 1, selected 1, then a veto on the third tab (before selection 2 and no selected 2), and a silent selectTab(0, false) left the index at 0. The default animation duration is 0 for TabLayoutPanel and DeckLayoutPanel and 250 milliseconds for StackLayoutPanel.

Every layout panel has a UiBinder form, and the parser enforces the rules of the Java API with compile-time errors. The elements in lower case (north, layer, tab, stack, header) are not widgets and cannot carry ui:field.

Source: GWT 2.13.1 source — UiBinder element parsers

The compiler reports template mistakes by name, and these are the messages the probe collected from broken templates (the part after [ERROR], followed by the element and the line as (:3)):

each followed by Failed to resolve '...Binder' via deferred binding, which is the generic line of every UiBinder failure. The UiBinder page covers templates in general; the complete shell template of this page is in the worked example below.

The layout system animates between two sets of constraints: set up the state you want to end in, then call animate(duration) (milliseconds). LayoutPanel, DockLayoutPanel, SplitLayoutPanel (every class implementing AnimatedLayout) have animate(int) and animate(int, Layout.AnimationCallback), plus forceLayout(). To animate a LayoutPanel you must first give the child initial constraints and apply them, otherwise there is nothing to animate from: the snippet slideIn above gives the banner a zero height, calls forceLayout(), sets a height of 2 em and animates over 500 milliseconds. The callback has two methods: onLayout(Layer, double progress) for every step and layer, and onAnimationComplete() after the last step. In the probe the banner measured 0 pixels before and 26 (2 em at 13 pixels) after the animation, and onLayout had been called. Tabs, stacks, decks and popups have their own duration setters (setAnimationDuration, setAnimationEnabled); the Developer Guide notes that animation is built into the layout system, because several use cases need panels that can animate between sets of constraints.

There are three kinds of layout in a GWT application, and the choice is by the part of the page you are laying out.

Two rules of thumb come out of the probes. Widgets that are themselves tables or frames (Grid, FlexTable, RichTextArea) do not fill the space a layout panel gives them: set 100% width and height explicitly (the Developer Guide uses a RichTextArea in the center of a dock as its example). And elements that must scroll go into a ScrollPanel placed in a layout region, since the region itself is overflow: hidden.