com.threerings.gwt.ui.Widgets Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of gwt-utils Show documentation
Show all versions of gwt-utils Show documentation
Utilities for use in developing GWT applications.
The newest version!
//
// $Id$
//
// OOO GWT Utils - utilities for creating GWT applications
// Copyright (C) 2009-2010 Three Rings Design, Inc., All Rights Reserved
// http://code.google.com/p/ooo-gwt-utils/
//
// This library is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License as published
// by the Free Software Foundation; either version 2.1 of the License, or
// (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
package com.threerings.gwt.ui;
import com.google.gwt.core.client.GWT;
import com.google.gwt.event.dom.client.ClickHandler;
import com.google.gwt.event.dom.client.HasClickHandlers;
import com.google.gwt.event.shared.HandlerRegistration;
import com.google.gwt.resources.client.ImageResource;
import com.google.gwt.user.client.DOM;
import com.google.gwt.user.client.Window;
import com.google.gwt.user.client.ui.AbsolutePanel;
import com.google.gwt.user.client.ui.AbstractImagePrototype;
import com.google.gwt.user.client.ui.FlowPanel;
import com.google.gwt.user.client.ui.HTML;
import com.google.gwt.user.client.ui.HasAlignment;
import com.google.gwt.user.client.ui.HorizontalPanel;
import com.google.gwt.user.client.ui.Image;
import com.google.gwt.user.client.ui.InlineLabel;
import com.google.gwt.user.client.ui.Label;
import com.google.gwt.user.client.ui.PushButton;
import com.google.gwt.user.client.ui.ScrollPanel;
import com.google.gwt.user.client.ui.SimplePanel;
import com.google.gwt.user.client.ui.TextArea;
import com.google.gwt.user.client.ui.TextBox;
import com.google.gwt.user.client.ui.TextBoxBase;
import com.google.gwt.user.client.ui.Widget;
import com.threerings.gwt.util.Value;
/**
* Convenience methods for creating and configuring widgets.
*/
public class Widgets
{
/**
* Creates a SimplePanel with the supplied style and widget
*/
public static SimplePanel newSimplePanel (String styleName, Widget widget)
{
SimplePanel panel = new SimplePanel();
if (widget != null) {
panel.setWidget(widget);
}
return setStyleNames(panel, styleName);
}
/**
* Creates a FlowPanel with the supplied widgets.
*/
public static FlowPanel newFlowPanel (Widget... contents)
{
return newFlowPanel(null, contents);
}
/**
* Creates a FlowPanel with the provided style and widgets.
*/
public static FlowPanel newFlowPanel (String styleName, Widget... contents)
{
FlowPanel panel = new FlowPanel();
for (Widget child : contents) {
if (child != null) {
panel.add(child);
}
}
return setStyleNames(panel, styleName);
}
/**
* Creates a AbsolutePanel with the supplied style
*/
public static AbsolutePanel newAbsolutePanel (String styleName)
{
return setStyleNames(new AbsolutePanel(), styleName);
}
/**
* Wraps the supplied contents in a scroll panel that will set the max-width to
* Window.getClientWidth()-xpad and the max-height to Window.getClientHeight()-ypad. If either
* xpad or ypad are less than zero, the max-size attribute on that axis will not be set.
*/
public static ScrollPanel newScrollPanel (Widget contents, int xpad, int ypad)
{
ScrollPanel panel = new ScrollPanel(contents);
if (xpad >= 0) {
String maxWidth = (Window.getClientWidth() - xpad) + "px";
DOM.setStyleAttribute(panel.getElement(), "maxWidth", maxWidth);
}
if (ypad >= 0) {
String maxHeight = (Window.getClientHeight() - ypad) + "px";
DOM.setStyleAttribute(panel.getElement(), "maxHeight", maxHeight);
}
return panel;
}
/**
* Wraps the supplied contents in a scroll panel with the specified maximum width.
*/
public static ScrollPanel newScrollPanelX (Widget contents, int maxWidth)
{
ScrollPanel panel = new ScrollPanel(contents);
DOM.setStyleAttribute(panel.getElement(), "maxWidth", maxWidth + "px");
return panel;
}
/**
* Wraps the supplied contents in a scroll panel with the specified maximum height.
*/
public static ScrollPanel newScrollPanelY (Widget contents, int maxHeight)
{
ScrollPanel panel = new ScrollPanel(contents);
DOM.setStyleAttribute(panel.getElement(), "maxHeight", maxHeight + "px");
return panel;
}
/**
* Creates a row of widgets in a horizontal panel with a 5 pixel gap between them.
*/
public static HorizontalPanel newRow (Widget... contents)
{
return newRow(null, contents);
}
/**
* Creates a row of widgets in a horizontal panel with a 5 pixel gap between them.
*/
public static HorizontalPanel newRow (String styleName, Widget... contents)
{
return newRow(HasAlignment.ALIGN_MIDDLE, styleName, contents);
}
/**
* Creates a row of widgets in a horizontal panel with a 5 pixel gap between them. The supplied
* style name is added to the container panel.
*/
public static HorizontalPanel newRow (HasAlignment.VerticalAlignmentConstant valign,
String styleName, Widget... contents)
{
HorizontalPanel row = new HorizontalPanel();
row.setVerticalAlignment(valign);
if (styleName != null) {
row.setStyleName(styleName);
}
for (Widget widget : contents) {
if (widget != null) {
if (row.getWidgetCount() > 0) {
row.add(newShim(5, 5));
}
row.add(widget);
}
}
return row;
}
/**
* Creates a label with the supplied text and style and optional additional styles.
*/
public static Label newLabel (String text, String... styles)
{
return setStyleNames(new Label(text), styles);
}
/**
* Creates an inline label with optional styles.
*/
public static InlineLabel newInlineLabel (String text, String... styles)
{
return setStyleNames(new InlineLabel(text), styles);
}
/**
* Creates a label that triggers an action using the supplied text and handler.
*/
public static Label newActionLabel (String text, ClickHandler onClick)
{
return newActionLabel(text, null, onClick);
}
/**
* Creates a label that triggers an action using the supplied text and handler. The label will
* be styled as specified with an additional style that configures the mouse pointer and adds
* underline to the text.
*/
public static Label newActionLabel (String text, String style, ClickHandler onClick)
{
return makeActionLabel(newLabel(text, style), onClick);
}
/**
* Makes the supplied label into an action label. The label will be styled such that it
* configures the mouse pointer and adds underline to the text.
*/
public static Label makeActionLabel (Label label, ClickHandler onClick)
{
return makeActionable(label, onClick, null);
}
/**
* Makes the supplied widget "actionable" which means adding the "actionLabel" style to it and
* binding the supplied click handler.
*
* @param enabled an optional value that governs the enabled state of the target. When the
* value becomes false, the target's click handler and "actionLabel" style will be removed,
* when it becomes true they will be reinstated.
*/
public static T makeActionable (
final T target, final ClickHandler onClick, Value enabled)
{
if (onClick != null) {
if (enabled != null) {
enabled.addListenerAndTrigger(new Value.Listener() {
public void valueChanged (Boolean enabled) {
if (!enabled && _regi != null) {
_regi.removeHandler();
_regi = null;
target.removeStyleName("actionLabel");
} else if (enabled && _regi == null) {
_regi = target.addClickHandler(onClick);
target.addStyleName("actionLabel");
}
}
protected HandlerRegistration _regi;
});
} else {
target.addClickHandler(onClick);
target.addStyleName("actionLabel");
}
}
return target;
}
/**
* Creates a new HTML element with the specified contents and style.
*/
public static HTML newHTML (String text, String... styles)
{
return setStyleNames(new HTML(text), styles);
}
/**
* Creates an image with the supplied resource and style.
*/
public static Image newImage (ImageResource image, String... styles)
{
return setStyleNames(new Image(image), styles);
}
/**
* Creates an image with the supplied resource and style.
*/
public static Image newImage (AbstractImagePrototype image, String... styles)
{
return setStyleNames(image.createImage(), styles);
}
/**
* Creates an image with the supplied path and style.
*/
public static Image newImage (String path, String... styles)
{
return setStyleNames(new Image(path), styles);
}
/**
* Creates an image that responds to clicking.
*/
public static Image newActionImage (String path, ClickHandler onClick)
{
return newActionImage(path, null, onClick);
}
/**
* Creates an image that responds to clicking.
*/
public static Image newActionImage (String path, String tip, ClickHandler onClick)
{
return makeActionImage(new Image(path), tip, onClick);
}
/**
* Makes an image into one that responds to clicking.
*/
public static Image makeActionImage (Image image, String tip, ClickHandler onClick)
{
if (tip != null) {
image.setTitle(tip);
}
return makeActionable(image, onClick, null);
}
/**
* Creates an image that will render inline with text (rather than forcing a break).
*/
public static Image newInlineImage (String path)
{
Image image = new Image(path);
image.setStyleName("inline");
return image;
}
/**
* Creates a text box with all of the configuration that you're bound to want to do.
*/
public static TextBox newTextBox (String text, int maxLength, int visibleLength)
{
return initTextBox(new TextBox(), text, maxLength, visibleLength);
}
/**
* Set the placeholder text to use on the specified form field.
* This text will be shown when the field is blank and unfocused.
*
* Note: To safely read the text from this TextBox on all browsers, use
* getText(TextBoxBase, placeholder). This is because on legacy browsers that don't support
* HTML5 form awesomeness, the text will actually be set in the field when it is unfocused.
*/
public static B setPlaceholderText (B box, String placeholder)
{
return _formSupport.setPlaceholderText(box, placeholder);
}
/**
* Retrieve the text from the TextBox, unless it is the specified default, in which case
* we return "".
*/
public static String getText (TextBoxBase box, String defaultAsBlank)
{
String s = box.getText().trim();
return s.equals(defaultAsBlank) ? "" : s;
}
/**
* Configures a text box with all of the configuration that you're bound to want to do. This is
* useful for configuring a PasswordTextBox.
*/
public static TextBox initTextBox (TextBox box, String text, int maxLength, int visibleLength)
{
if (text != null) {
box.setText(text);
}
box.setMaxLength(maxLength > 0 ? maxLength : 255);
if (visibleLength > 0) {
box.setVisibleLength(visibleLength);
}
return box;
}
/**
* Creates a text area with all of the configuration that you're bound to want to do.
*
* @param width the width of the text area or -1 to use the default (or CSS styled) width.
*/
public static TextArea newTextArea (String text, int width, int height)
{
TextArea area = new TextArea();
if (text != null) {
area.setText(text);
}
if (width > 0) {
area.setCharacterWidth(width);
}
if (height > 0) {
area.setVisibleLines(height);
}
return area;
}
/**
* Creates a limited text area with all of the configuration that you're bound to want to do.
*
* @param width the width of the text area or -1 to use the default (or CSS styled) width.
*/
public static LimitedTextArea newTextArea (String text, int width, int height, int maxLength)
{
LimitedTextArea area = new LimitedTextArea(maxLength, width, height);
if (text != null) {
area.setText(text);
}
return area;
}
/**
* Creates a PushButton with default(up), mouseover and mousedown states.
*/
public static PushButton newPushButton (Image defaultImage, Image overImage,
Image downImage, ClickHandler onClick)
{
PushButton button = new PushButton(defaultImage, downImage);
maybeAddClickHandler(button, onClick);
button.getUpHoveringFace().setImage(overImage);
return button;
}
/**
* Creates an image button that changes appearance when you click and hover over it.
*/
public static PushButton newImageButton (String style, ClickHandler onClick)
{
PushButton button = new PushButton();
maybeAddClickHandler(button, onClick);
return setStyleNames(button, style, "actionLabel");
}
/**
* Makes a widget that takes up horizontal and or vertical space. Shim shimminy shim shim
* shiree.
*/
public static Widget newShim (int width, int height)
{
Image shim = new Image(_rsrc.blank());
shim.setWidth(width + "px");
shim.setHeight(height + "px");
return shim;
}
/**
* Configures the supplied styles on the supplied widget. Existing styles will not be preserved
* unless you call this with no-non-null styles. Returns the widget for easy chaining.
*/
public static T setStyleNames (T widget, String... styles)
{
int idx = 0;
for (String style : styles) {
if (style == null) {
continue;
}
if (idx++ == 0) {
widget.setStyleName(style);
} else {
widget.addStyleName(style);
}
}
return widget;
}
protected static void maybeAddClickHandler (HasClickHandlers target, ClickHandler onClick)
{
if (onClick != null) {
target.addClickHandler(onClick);
}
}
protected static FormSupport _formSupport = GWT.create(FormSupport.class);
protected static UIResources _rsrc = GWT.create(UIResources.class);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy