com.google.gwt.user.client.ui.FormPanel Maven / Gradle / Ivy
/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.user.client.ui;
import com.google.gwt.core.client.GWT;
import com.google.gwt.core.client.Scheduler;
import com.google.gwt.core.client.Scheduler.ScheduledCommand;
import com.google.gwt.dom.client.Document;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.FormElement;
import com.google.gwt.event.shared.EventHandler;
import com.google.gwt.event.shared.GwtEvent;
import com.google.gwt.event.shared.HandlerRegistration;
import com.google.gwt.safehtml.client.SafeHtmlTemplates;
import com.google.gwt.safehtml.shared.SafeHtml;
import com.google.gwt.safehtml.shared.SafeUri;
import com.google.gwt.safehtml.shared.annotations.IsSafeUri;
import com.google.gwt.user.client.Event;
import com.google.gwt.user.client.ui.impl.FormPanelImpl;
import com.google.gwt.user.client.ui.impl.FormPanelImplHost;
/**
* A panel that wraps its contents in an HTML <FORM> element.
*
*
* This panel can be used to achieve interoperability with servers that accept
* traditional HTML form encoding. The following widgets (those that implement
* {@link com.google.gwt.user.client.ui.HasName}) will be submitted to the
* server if they are contained within this panel:
*
* - {@link com.google.gwt.user.client.ui.TextBox}
* - {@link com.google.gwt.user.client.ui.PasswordTextBox}
* - {@link com.google.gwt.user.client.ui.RadioButton}
* - {@link com.google.gwt.user.client.ui.SimpleRadioButton}
* - {@link com.google.gwt.user.client.ui.CheckBox}
* - {@link com.google.gwt.user.client.ui.SimpleCheckBox}
* - {@link com.google.gwt.user.client.ui.TextArea}
* - {@link com.google.gwt.user.client.ui.ListBox}
* - {@link com.google.gwt.user.client.ui.FileUpload}
* - {@link com.google.gwt.user.client.ui.Hidden}
*
* In particular, {@link com.google.gwt.user.client.ui.FileUpload} is
* only useful when used within a FormPanel, because the browser will
* only upload files using form submission.
*
*
*
*
Example
* {@example com.google.gwt.examples.FormPanelExample}
*
*/
@SuppressWarnings("deprecation")
public class FormPanel extends SimplePanel implements FiresFormEvents, FormPanelImplHost {
/**
* Fired when a form has been submitted successfully.
*/
public static class SubmitCompleteEvent extends GwtEvent {
/**
* The event type.
*/
private static Type TYPE;
/**
* Handler hook.
*
* @return the handler hook
*/
public static Type getType() {
if (TYPE == null) {
TYPE = new Type();
}
return TYPE;
}
private String resultHtml;
/**
* Create a submit complete event.
*
* @param resultsHtml the results from submitting the form
*/
protected SubmitCompleteEvent(String resultsHtml) {
this.resultHtml = resultsHtml;
}
@Override
public final Type getAssociatedType() {
return getType();
}
/**
* Gets the result text of the form submission.
*
* @return the result html, or null
if there was an error
* reading it
* @tip The result html can be null
as a result of submitting a
* form to a different domain.
*/
public String getResults() {
return resultHtml;
}
@Override
protected void dispatch(SubmitCompleteHandler handler) {
handler.onSubmitComplete(this);
}
}
/**
* Handler for {@link FormPanel.SubmitCompleteEvent} events.
*/
public interface SubmitCompleteHandler extends EventHandler {
/**
* Fired when a form has been submitted successfully.
*
* @param event the event
*/
void onSubmitComplete(FormPanel.SubmitCompleteEvent event);
}
/**
* Fired when the form is submitted.
*/
public static class SubmitEvent extends GwtEvent {
/**
* The event type.
*/
private static Type TYPE;
/**
* Handler hook.
*
* @return the handler hook
*/
public static Type getType() {
if (TYPE == null) {
TYPE = new Type();
}
return TYPE;
}
private boolean canceled = false;
/**
* Cancel the form submit. Firing this will prevent a subsequent
* {@link FormPanel.SubmitCompleteEvent} from being fired.
*/
public void cancel() {
this.canceled = true;
}
@Override
public final Type getAssociatedType() {
return getType();
}
/**
* Gets whether this form submit will be canceled.
*
* @return true
if the form submit will be canceled
*/
public boolean isCanceled() {
return canceled;
}
@Override
protected void dispatch(FormPanel.SubmitHandler handler) {
handler.onSubmit(this);
}
/**
* This method is used for legacy support and should be removed when
* {@link FormHandler} is removed.
*
* @deprecated Use {@link FormPanel.SubmitEvent#cancel()} instead
*/
@Deprecated
void setCanceled(boolean canceled) {
this.canceled = canceled;
}
}
/**
* Handler for {@link FormPanel.SubmitEvent} events.
*/
public interface SubmitHandler extends EventHandler {
/**
* Fired when the form is submitted.
*
*
* The FormPanel must not be detached (i.e. removed from its parent
* or otherwise disconnected from a {@link RootPanel}) until the submission
* is complete. Otherwise, notification of submission will fail.
*
*
* @param event the event
*/
void onSubmit(FormPanel.SubmitEvent event);
}
interface IFrameTemplate extends SafeHtmlTemplates {
static final IFrameTemplate INSTANCE = GWT.create(IFrameTemplate.class);
@Template("