import java.util.Map;
+import com.vaadin.data.Container;
import com.vaadin.ui.Component;
+/**
+ * Parent class for {@link Transferable} implementations that have a Vaadin
+ * container as a data source. The transfer is associated with an item
+ * (identified by its Id) and optionally also a property identifier (e.g. a
+ * table column identifier when transferring a single table cell).
+ *
+ * The component must implement the interface {@link Container.Viewer}.
+ *
+ * In most cases, receivers of data transfers should depend on this class
+ * instead of its concrete subclasses.
+ *
+ * @since 6.3
+ */
public abstract class DataBoundTransferable extends TransferableImpl {
public DataBoundTransferable(Component sourceComponent,
super(sourceComponent, rawVariables);
}
+ /**
+ * Returns the identifier of the item being transferred.
+ *
+ * @return item identifier
+ */
public abstract Object getItemId();
+ /**
+ * Returns the optional property identifier that the transfer concerns.
+ *
+ * This can be e.g. the table column from which a drag operation originated.
+ *
+ * @return property identifier
+ */
public abstract Object getPropertyId();
+ /**
+ * Returns the container data source from which the transfer occurs.
+ *
+ * {@link Container.Viewer#getContainerDataSource()} is used to obtain the
+ * underlying container of the source component.
+ *
+ * @return Container
+ */
+ public Container getSourceContainer() {
+ Component sourceComponent = getSourceComponent();
+ if (sourceComponent instanceof Container.Viewer) {
+ return ((Container.Viewer) sourceComponent)
+ .getContainerDataSource();
+ } else {
+ // this should not happen
+ return null;
+ }
+ }
}
/**
* DropTarget is an interface for components supporting drop operations. A
* component that wants to receive drop events should implement this interface
- * and provide a DropHandler which will handle the actual drop event.
+ * and provide a {@link DropHandler} which will handle the actual drop event.
*
* @since 6.3
*/
import com.vaadin.terminal.PaintTarget;
/**
- * TODO Javadoc
+ * Criterion that can be used create policy to accept/discard dragged content
+ * (presented by {@link Transferable}).
*
- * @since 6.3
+ * The drag and drop mechanism will verify the criteria returned by
+ * {@link DropHandler#getAcceptCriterion()} before calling
+ * {@link DropHandler#drop(DragAndDropEvent)}.
+ *
+ * The criteria can be evaluated either on the client (browser - see
+ * {@link ClientSideCriterion}) or on the server (see
+ * {@link ServerSideCriterion}). If no constraints are needed, an
+ * {@link AcceptAll} can be used.
+ *
+ * In addition to accepting or rejecting a possible drop, criteria can provide
+ * additional hints for client side painting.
*
+ * @see DropHandler
+ * @see ClientSideCriterion
+ * @see ServerSideCriterion
+ *
+ * @since 6.3
*/
public interface AcceptCriterion extends Serializable {
/**
- * Criterion that can be used create policy to accept/discard dragged
- * content (presented by {@link Transferable}).
+ * Returns whether the criteria can be checked on the client or whether a
+ * server request is needed to check the criteria.
*
- * May depend on state, like in OR or AND, so to be really
- * ClientSideVerifiable needs to return true here (instead of just
- * implementing marker interface).
+ * This requirement may depend on the state of the criterion (e.g. logical
+ * operations between criteria), so this cannot be based on a marker
+ * interface.
*/
public boolean isClientSideVerifiable();
public void paintResponse(PaintTarget target) throws PaintException;
/**
- * Validates the data in event to be approriate for
+ * Validates the data in event to be appropriate for
* {@link DropHandler#drop(com.vaadin.event.dd.DropEvent)} method.
* <p>
- * Note, that event if your criterion is matched on client side, it is a
- * very good manner to validate the data on server side too.
+ * Note that even if your criterion is matched on client side, it is a very
+ * good manner to validate the data on server side too.
*
* @param dragEvent
* @return
* All classes that provide criteria that can be completely validated on client
* side should extend this class.
*
+ * It is recommended that subclasses of ClientSideCriterion re-validate the
+ * condition on the server side in
+ * {@link AcceptCriterion#accepts(com.vaadin.event.dd.DragAndDropEvent)} after
+ * the client side validation has accepted a transfer.
+ *
* @since 6.3
*/
public abstract class ClientSideCriterion implements Serializable,
import java.io.Serializable;
+import com.vaadin.event.Transferable;
import com.vaadin.terminal.PaintException;
import com.vaadin.terminal.PaintTarget;
import com.vaadin.terminal.gwt.client.ui.dd.VServerAccept;
/**
- * TODO Javadoc
+ * Parent class for criteria that are verified on the server side during a drag
+ * operation to accept/discard dragged content (presented by
+ * {@link Transferable}).
*
- * @since 6.3
+ * Subclasses should implement the
+ * {@link AcceptCriterion#accepts(com.vaadin.event.dd.DragAndDropEvent)} method.
+ *
+ * As all server side state can be used to make a decision, this is more
+ * flexible than {@link ClientSideCriterion}. However, this does require
+ * additional requests from the browser to the server during a drag operation.
*
+ * @see AcceptCriterion
+ * @see ClientSideCriterion
+ *
+ * @since 6.3
*/
@ClientCriterion(VServerAccept.class)
public abstract class ServerSideCriterion implements Serializable,
requestRepaint();
}
- class TableTransferable extends DataBoundTransferable {
+ /**
+ * Concrete implementation of {@link DataBoundTransferable} for data
+ * transferred from a table.
+ *
+ * @see {@link DataBoundTransferable}.
+ *
+ * @since 6.3
+ */
+ protected class TableTransferable extends DataBoundTransferable {
public TableTransferable(Map<String, Object> rawVariables) {
super(Table.this, rawVariables);
@Override
public Object getPropertyId() {
+ // FIXME incorrect implementation, drag can also concern a cell
return getItemCaptionPropertyId();
}
}
/**
- * TODO Javadoc!
+ * Concrete implementation of {@link DataBoundTransferable} for data
+ * transferred from a tree.
+ *
+ * @see {@link DataBoundTransferable}.
*
* @since 6.3
*/
- public class TreeTransferable extends DataBoundTransferable {
+ protected class TreeTransferable extends DataBoundTransferable {
public TreeTransferable(Component sourceComponent,
Map<String, Object> rawVariables) {
} else {
// we have a component that is been dragged, add
- // it
- // to
- // this
+ // it to this
layout.addComponent(component);
}
DataBoundTransferable tr = (DataBoundTransferable) event
.getTransferable();
Object itemId = tr.getItemId();
- Container sourceContainer = (Container) tr.getSourceComponent();
- if (sourceContainer != tree1) {
+ Container sourceContainer = tr.getSourceContainer();
+ if (tr.getSourceComponent() != tree1) {
// if the source is from table (not from tree1 itself),
- // transfer Name property and use it as an indentifier in
+ // transfer Name property and use it as an identifier in
// tree1
String name = sourceContainer.getItem(itemId)
.getItemProperty("Name").toString();
import com.vaadin.ui.AbsoluteLayout.ComponentPosition;
import com.vaadin.ui.Tree.TreeDragMode;
import com.vaadin.ui.Tree.TreeDropTargetDetails;
-import com.vaadin.ui.Tree.TreeTransferable;
public class DDTest6 extends TestBase {
// dragged something from tree to the folder shown
- File draggedFile = (File) ((TreeTransferable) dropEvent
+ File draggedFile = (File) ((DataBoundTransferable) dropEvent
.getTransferable()).getItemId();
DDTest6.get().setParent(draggedFile, folder);
}
};
public HorizontalLayoutSortableWithWrappers() {
- setCaption("Horizontally sortable layout via (ddwrappers):Try sorting blocks by draggin them");
+ setCaption("Horizontally sortable layout via (ddwrappers): Try sorting blocks by dragging them");
DragAndDropWrapper pane = new DragAndDropWrapper(layout);
setContent(pane);
pane.setSizeFull();
projects / vaadin-framework.git / commitdiff