From c1fee1ce305961af5576ea434685b392adc728b1 Mon Sep 17 00:00:00 2001 From: Henri Sara Date: Fri, 12 Mar 2010 14:38:39 +0000 Subject: [PATCH] Some drag'n'drop javadoc improvements and a new method in DataBoundTransferable. svn changeset:11831/svn branch:6.3 --- .../vaadin/event/DataBoundTransferable.java | 44 +++++++++++++++++++ src/com/vaadin/event/dd/DropTarget.java | 2 +- .../dd/acceptCriteria/AcceptCriterion.java | 36 ++++++++++----- .../acceptCriteria/ClientSideCriterion.java | 5 +++ .../acceptCriteria/ServerSideCriterion.java | 16 ++++++- src/com/vaadin/ui/Table.java | 11 ++++- src/com/vaadin/ui/Tree.java | 7 ++- .../vaadin/tests/dd/AcceptAnythingWindow.java | 4 +- tests/src/com/vaadin/tests/dd/DDTest2.java | 6 +-- tests/src/com/vaadin/tests/dd/DDTest6.java | 3 +- .../HorizontalLayoutSortableWithWrappers.java | 2 +- 11 files changed, 111 insertions(+), 25 deletions(-) diff --git a/src/com/vaadin/event/DataBoundTransferable.java b/src/com/vaadin/event/DataBoundTransferable.java index 75263b2dac..edef4c4427 100644 --- a/src/com/vaadin/event/DataBoundTransferable.java +++ b/src/com/vaadin/event/DataBoundTransferable.java @@ -5,8 +5,22 @@ package com.vaadin.event; 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, @@ -14,8 +28,38 @@ public abstract class DataBoundTransferable extends TransferableImpl { 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; + } + } } diff --git a/src/com/vaadin/event/dd/DropTarget.java b/src/com/vaadin/event/dd/DropTarget.java index 7bd3efa8ee..1d032c42e4 100644 --- a/src/com/vaadin/event/dd/DropTarget.java +++ b/src/com/vaadin/event/dd/DropTarget.java @@ -10,7 +10,7 @@ import com.vaadin.ui.Component; /** * 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 */ diff --git a/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java index 4b9ce0fe18..d65c64d81e 100644 --- a/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java +++ b/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java @@ -15,20 +15,36 @@ import com.vaadin.terminal.PaintException; 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(); @@ -46,11 +62,11 @@ public interface AcceptCriterion extends Serializable { 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. *

- * 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 diff --git a/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java index 849f25bc0a..e406535958 100644 --- a/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java +++ b/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java @@ -13,6 +13,11 @@ import com.vaadin.terminal.PaintTarget; * 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, diff --git a/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java index 8011586950..e4a6956141 100644 --- a/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java +++ b/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java @@ -5,15 +5,27 @@ package com.vaadin.event.dd.acceptCriteria; 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, diff --git a/src/com/vaadin/ui/Table.java b/src/com/vaadin/ui/Table.java index 71ceb3a230..c0ac21b274 100644 --- a/src/com/vaadin/ui/Table.java +++ b/src/com/vaadin/ui/Table.java @@ -3340,7 +3340,15 @@ public class Table extends AbstractSelect implements Action.Container, 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 rawVariables) { super(Table.this, rawVariables); @@ -3357,6 +3365,7 @@ public class Table extends AbstractSelect implements Action.Container, @Override public Object getPropertyId() { + // FIXME incorrect implementation, drag can also concern a cell return getItemCaptionPropertyId(); } diff --git a/src/com/vaadin/ui/Tree.java b/src/com/vaadin/ui/Tree.java index 4c1c7136fb..9f3649ebe9 100644 --- a/src/com/vaadin/ui/Tree.java +++ b/src/com/vaadin/ui/Tree.java @@ -1220,11 +1220,14 @@ public class Tree extends AbstractSelect implements Container.Hierarchical, } /** - * 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 rawVariables) { diff --git a/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java b/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java index c07051ef32..38ecc308b5 100644 --- a/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java +++ b/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java @@ -62,9 +62,7 @@ public class AcceptAnythingWindow extends Window { } else { // we have a component that is been dragged, add - // it - // to - // this + // it to this layout.addComponent(component); } diff --git a/tests/src/com/vaadin/tests/dd/DDTest2.java b/tests/src/com/vaadin/tests/dd/DDTest2.java index 929542b175..3a3fad5d54 100644 --- a/tests/src/com/vaadin/tests/dd/DDTest2.java +++ b/tests/src/com/vaadin/tests/dd/DDTest2.java @@ -139,10 +139,10 @@ public class DDTest2 extends TestBase { 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(); diff --git a/tests/src/com/vaadin/tests/dd/DDTest6.java b/tests/src/com/vaadin/tests/dd/DDTest6.java index 39d1f1fb7b..6df55917fa 100644 --- a/tests/src/com/vaadin/tests/dd/DDTest6.java +++ b/tests/src/com/vaadin/tests/dd/DDTest6.java @@ -37,7 +37,6 @@ import com.vaadin.ui.Tree; 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 { @@ -311,7 +310,7 @@ 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); } diff --git a/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java b/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java index 95011ffd42..fbaf70b276 100644 --- a/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java +++ b/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java @@ -96,7 +96,7 @@ public class HorizontalLayoutSortableWithWrappers extends Window { }; 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(); -- 2.39.5