| /* |
| * 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; |
| } |