/**
* 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 org.waveprotocol.wave.client.editor.content;
import com.google.gwt.dom.client.Element;
import org.waveprotocol.wave.model.document.util.Property;
/**
* Renderer that creates the DOM implementation for a node.
*
* @author danilatos@google.com (Daniel Danilatos)
*/
public interface Renderer {
/**
* View of an element consisting of methods relevant to rendering.
*/
interface Renderable {
/**
* @return the element's tag name. This is the only piece of state made
* available to the renderer, as it is immutable. If the renderer
* relied on any other information such as attributes or children,
* then it would be disobeying the contract of creating a *blank*
* html implementation, making things less predictable.
*/
String getTagName();
/**
* Optionally call this to specify a default attach point for children. It
* may be the same as the dom impl nodelet, a descendant of the dom impl
* nodelet, or null. If null, child html implementations will not be
* automatically attached during mutations. If not null, it must not contain
* any children of its own to start with, as they will all be removed.
*
* If this method is not called, the value default to null and no automatic
* behaviour occurs.
*
* @param containerNodelet
* @return its input, for convenience (useful when used as the last line in
* {@link Renderer#createDomImpl(Renderable)} where the container
* nodelet is the same as the dom impl nodelet)
*/
// TODO(danilatos): Abolish container nodelet by providing equivalent
// functionality in a utility implementation of node mutation handler,
// so that renderers desiring that behaviour may use it instead.
Element setAutoAppendContainer(Element containerNodelet);
/**
* Optionally sets a transient properties on the element.
*
* An example use of this method is to assign a reference to a specific
* widget view interface for use by other handlers.
*
* @param <T>
* @param property
* @param value
*/
// TODO(danilatos): A mechanism to allow handlers to clean up after themselves
<T> void setProperty(Property<T> property, T value);
}
/**
* Creates a blank DOMImpl corresponding this node.
*
* @param element the implementor of this method may optionally call some of
* the setters
*/
Element createDomImpl(Renderable element);
}