com.google.gwt.uibinder.rebind.FieldWriter Maven / Gradle / Ivy
/*
* Copyright 2009 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.uibinder.rebind;
import com.google.gwt.core.ext.UnableToCompleteException;
import com.google.gwt.core.ext.typeinfo.JClassType;
import com.google.gwt.core.ext.typeinfo.JType;
import com.google.gwt.core.ext.typeinfo.TypeOracle;
import com.google.gwt.uibinder.rebind.model.OwnerField;
/**
* Models a field to be written in the generated binder code. Note that this is
* not necessarily a field that the user has declared. It's basically any
* variable the generated UiBinder#createAndBindUi implementation will need.
*
* A field can have a custom initialization statement, set via
* {@link #setInitializer}. Without one it will be initialized via a
* {@link com.google.gwt.core.client.GWT#create} call. (In the rare case that
* you need a field not to be initialized, initialize it to "null".)
*
* Dependencies can be declared between fields via {@link #needs}, to ensure
* that one can be initialized via reference to another. Circular references are
* not supported, nor detected.
*/
public interface FieldWriter {
/**
* Add a statement to be executed right after the current field is attached.
*
*
* HTMLPanel panel = new HTMLPanel(
* "...");
*
* // statement section.
* widgetX.setStyleName("someCss");
* widgetX.setVisible(true);
*
* // attach section.
* UiBinderUtil.TempAttachment attachRecord =
* UiBinderUtil.attachToDom(panel.getElement());
* get_domId0Element().get();
* get_domId1Element().get();
*
* // detach section.
* attachRecord.detach();
* panel.addAndReplaceElement(get_someWidget(), get_domId0Element().get());
* panel.addAndReplaceElement(get_otherWidget(), get_domId1Element().get());
*
*/
void addAttachStatement(String format, Object... args);
/**
* Add a statement to be executed right after the current field is detached.
* {@see #addAttachStatement}.
*/
void addDetachStatement(String format, Object... args);
/**
* Add a statement for the given field, executed right after its creation. Example:
*
*
* WidgetX widgetX = GWT.create(WidgetX.class);
*
* // statement section.
* widgetX.setStyleName("someCss");
* widgetX.setVisible(true);
*
*/
void addStatement(String format, Object... args);
/**
* Returns the type of this field, or for generated types the type it extends.
*/
// TODO(rjrjr) When ui:style is able to implement multiple interfaces,
// this will need to become a set
JClassType getAssignableType();
/**
* Gets this field builder precedence.
*/
int getBuildPrecedence();
/**
* Gets the type of this field.
*/
FieldWriterType getFieldType();
/**
* Returns the string html representation of the field.
*/
String getHtml();
/**
* Returns the custom initializer for this field, or null if it is not set.
*/
String getInitializer();
/**
* Returns the type of this field, or null if this field is of a type that has
* not yet been generated.
*/
JClassType getInstantiableType();
/**
* Get the name of the field.
*/
String getName();
/**
* Returns the expression that to evaluate to get the contents of this field.
* Keeps a reference count, so if the field is to be used more than once it is
* important to call this method each time.
*/
String getNextReference();
/**
* Returns the qualified source name of this type.
*/
String getQualifiedSourceName();
/**
* Returns the return type found at the end of the given method call
* path, which must begin with the receiver's name, or null if the
* path is invalid.
*/
JType getReturnType(String[] path, MonitoredLogger logger);
/**
* Returns the string SafeHtml representation of the field.
*/
String getSafeHtml();
/**
* Declares that the receiver depends upon the given field.
*/
void needs(FieldWriter f);
/**
* Sets the precedence of this field builder. Field with higher values are
* written first. This is automatically set by FieldManager when the field is
* created. You should only change it somewhere else if you really know
* what you are doing.
*/
void setBuildPrecedence(int precedence);
/**
* Sets the html representation of the field for applicable field types.
*/
void setHtml(String html);
/**
* Used to provide an initializer string to use instead of a
* {@link com.google.gwt.core.client.GWT#create} call. Note that this is an
* RHS expression. Don't include the leading '=', and don't end it with ';'.
*
* @throws IllegalStateException on second attempt to set the initializer
*/
void setInitializer(String initializer);
/**
* Write the field declaration.
*/
void write(IndentedWriter w) throws UnableToCompleteException;
/**
* Write this field builder in the Widgets inner class. There are 3
* possible situations:
*
*
* - getter never called
* - write builder only if there's a ui:field associated
* - getter called only once
* - don't need to write the builder since the getter fallback to the
* builder when called
* - getter called more than once
* - in this case a field class is created, the builder is written
* and the getter returns the field class
*
*
* {@see com.google.gwt.uibinder.rebind.FieldWriter#writeFieldGetter}.
*/
void writeFieldBuilder(IndentedWriter w, int getterCount, OwnerField ownerField)
throws UnableToCompleteException;
/**
* Output the getter and builder definitions for the given field.
*
*
* Example for widgets called only once:
*
* private WidgetX get_widgetX() {
* return build_widgetX();
* }
* private WidgetX build_widgetX() {
* widget = GWT.create(WidgetX.class);
* widget.setStyleName("css");
* return widgetX;
* }
*
* Notice that there's no field and the getter just fallback to the builder.
*
*
* Example for widgets called more than once:
*
* private WidgetX widgetX;
* private WidgetX get_widgetX() {
* return widgetX;
* }
* private WidgetX build_widgetX() {
* widget = GWT.create(WidgetX.class);
* widget.setStyleName("css");
* return widgetX;
* }
*
* Notice that the getter just returns the field. The builder is called in
* the Widgets ctor.
*
*/
void writeFieldDefinition(IndentedWriter w, TypeOracle typeOracle,
OwnerField ownerField, DesignTimeUtils designTime, int getterCount,
boolean useLazyWidgetBuilders)
throws UnableToCompleteException;
}