| /* |
| * Copyright 2010 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.cell.client; |
| |
| import com.google.gwt.dom.client.Element; |
| import com.google.gwt.dom.client.NativeEvent; |
| import com.google.gwt.safehtml.shared.SafeHtmlBuilder; |
| |
| import java.util.Set; |
| |
| /** |
| * A light weight representation of a renderable object. |
| * |
| * <p> |
| * <h3>Example</h3> |
| * {@example com.google.gwt.examples.cell.CellExample} |
| * </p> |
| * |
| * @param <C> the type that this Cell represents |
| */ |
| public interface Cell<C> { |
| |
| /** |
| * Contains information about the context of the Cell. |
| */ |
| public static class Context { |
| |
| private final int column; |
| private final int index; |
| private final Object key; |
| |
| /** |
| * Create a new {@link Context}. |
| * |
| * @param index the absolute index of the value |
| * @param column the column index of the cell, or 0 |
| * @param key the unique key that represents the row value |
| */ |
| public Context(int index, int column, Object key) { |
| this.index = index; |
| this.column = column; |
| this.key = key; |
| } |
| |
| /** |
| * Get the column index of the cell. If the view only contains a single |
| * column, this method returns 0. |
| * |
| * @return the column index of the cell |
| */ |
| public int getColumn() { |
| return column; |
| } |
| |
| /** |
| * Get the absolute index of the value. |
| * |
| * @return the index |
| */ |
| public int getIndex() { |
| return index; |
| } |
| |
| /** |
| * Get the key that uniquely identifies the row object. |
| * |
| * @return the unique key |
| */ |
| public Object getKey() { |
| return key; |
| } |
| } |
| |
| /** |
| * Check if this cell depends on the selection state. |
| * |
| * @return true if dependent on selection, false if not |
| */ |
| boolean dependsOnSelection(); |
| |
| /** |
| * Get the set of events that this cell consumes. The container that uses this |
| * cell should only pass these events to |
| * {@link #onBrowserEvent(Context, Element, Object, NativeEvent, ValueUpdater)} |
| * when the event occurs. |
| * |
| * <p> |
| * The returned value should not be modified, and may be an unmodifiable set. |
| * Changes to the return value may not be reflected in the cell. |
| * </p> |
| * |
| * @return the consumed events, or null if no events are consumed |
| */ |
| Set<String> getConsumedEvents(); |
| |
| /** |
| * Check if this cell handles selection. If the cell handles selection, then |
| * its container should not automatically handle selection. |
| * |
| * @return true if the cell handles selection, false if not |
| */ |
| boolean handlesSelection(); |
| |
| /** |
| * Returns true if the cell is currently editing the data identified by the |
| * given element and key. While a cell is editing, widgets containing the cell |
| * may choose to pass keystrokes directly to the cell rather than using them |
| * for navigation purposes. |
| * |
| * @param context the {@link Context} of the cell |
| * @param parent the parent Element |
| * @param value the value associated with the cell |
| * @return true if the cell is in edit mode |
| */ |
| boolean isEditing(Context context, Element parent, C value); |
| |
| /** |
| * Handle a browser event that took place within the cell. The default |
| * implementation returns null. |
| * |
| * @param context the {@link Context} of the cell |
| * @param parent the parent Element |
| * @param value the value associated with the cell |
| * @param event the native browser event |
| * @param valueUpdater a {@link ValueUpdater}, or null if not specified |
| */ |
| void onBrowserEvent(Context context, Element parent, C value, |
| NativeEvent event, ValueUpdater<C> valueUpdater); |
| |
| /** |
| * Render a cell as HTML into a {@link SafeHtmlBuilder}, suitable for passing |
| * to {@link Element#setInnerHTML(String)} on a container element. |
| * |
| * <p> |
| * Note: If your cell contains natively focusable elements, such as buttons or |
| * input elements, be sure to set the tabIndex to -1 so that they do not steal |
| * focus away from the containing widget. |
| * </p> |
| * |
| * @param context the {@link Context} of the cell |
| * @param value the cell value to be rendered |
| * @param sb the {@link SafeHtmlBuilder} to be written to |
| */ |
| void render(Context context, C value, SafeHtmlBuilder sb); |
| |
| /** |
| * Reset focus on the Cell. This method is called if the cell has focus when |
| * it is refreshed. |
| * |
| * @param context the {@link Context} of the cell |
| * @param parent the parent Element |
| * @param value the value associated with the cell |
| * @return true if focus is taken, false if not |
| */ |
| boolean resetFocus(Context context, Element parent, C value); |
| |
| /** |
| * This method may be used by cell containers to set the value on a single |
| * cell directly, rather than using {@link Element#setInnerHTML(String)}. See |
| * {@link AbstractCell#setValue(Context, Element, Object)} for a default |
| * implementation that uses {@link #render(Context, Object, SafeHtmlBuilder)}. |
| * |
| * @param context the {@link Context} of the cell |
| * @param parent the parent Element |
| * @param value the value associated with the cell |
| */ |
| void setValue(Context context, Element parent, C value); |
| } |