/*
* 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.
* <p>
* 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".)
* <p>
* 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.
*
* <pre>
* HTMLPanel panel = new HTMLPanel(
* "<span id='someId' class='someclass'></span>...");
*
* // 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());
* </pre>
*/
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:
*
* <pre>
* WidgetX widgetX = GWT.create(WidgetX.class);
*
* // statement section.
* widgetX.setStyleName("someCss");
* widgetX.setVisible(true);
* </pre>
*/
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 <b>really</b> 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 <b>Widgets</b> inner class. There are 3
* possible situations:
*
* <dl>
* <dt>getter never called</dt>
* <dd>write builder only if there's a ui:field associated</dd>
* <dt>getter called only once</dt>
* <dd>don't need to write the builder since the getter fallback to the
* builder when called</dd>
* <dt>getter called more than once</dt>
* <dd>in this case a field class is created, the builder is written
* and the getter returns the field class</dd>
* </dl>
*
* {@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.
*
* <p>
* <b>Example for widgets called only once:</b>
* <pre>
* private WidgetX get_widgetX() {
* return build_widgetX();
* }
* private WidgetX build_widgetX() {
* widget = GWT.create(WidgetX.class);
* widget.setStyleName("css");
* return widgetX;
* }
* </pre>
* Notice that there's no field and the getter just fallback to the builder.
* </p>
*
* <p><b>Example for widgets called more than once:</b>
* <pre>
* private WidgetX widgetX;
* private WidgetX get_widgetX() {
* return widgetX;
* }
* private WidgetX build_widgetX() {
* widget = GWT.create(WidgetX.class);
* widget.setStyleName("css");
* return widgetX;
* }
* </pre>
* Notice that the getter just returns the field. The builder is called in
* the Widgets ctor.
* </p>
*/
void writeFieldDefinition(IndentedWriter w, TypeOracle typeOracle,
OwnerField ownerField, DesignTimeUtils designTime, int getterCount,
boolean useLazyWidgetBuilders)
throws UnableToCompleteException;
}