import java.io.Serializable;
import com.vaadin.event.Transferable;
+import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
/**
- * TODO Javadoc
+ * DragAndDropEvent wraps information related to drag and drop operation. It is
+ * passed by terminal implementation for
+ * {@link DropHandler#drop(DragAndDropEvent)} and
+ * {@link AcceptCriterion#accepts(DragAndDropEvent)} methods.
+ * <p>
+ * DragAndDropEvent instances contains both the dragged data in
+ * {@link Transferable} (generated by {@link DragSource} and details about the
+ * current drop event in {@link DropTargetDetails} (generated by
+ * {@link DropTarget}.
*
* @since 6.3
*
this.dropTargetDetails = dropTargetDetails;
}
+ /**
+ * @return the Transferable instance representing the data dragged in this
+ * drag and drop event
+ */
public Transferable getTransferable() {
return transferable;
}
+ /**
+ * @return the DropTargetDetails containing drop target related details of
+ * drag and drop operation
+ */
public DropTargetDetails getDropTargetDetails() {
return dropTargetDetails;
}
*/
package com.vaadin.event.dd;
-import java.io.Serializable;
import java.util.Map;
import com.vaadin.event.Transferable;
+import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
+import com.vaadin.ui.Component;
+import com.vaadin.ui.Tree;
/**
- * TODO Javadoc
+ * DragSource is a {@link Component} that builds a {@link Transferable} for a
+ * drag and drop operation.
+ * <p>
+ * In Vaadin the drag and drop operation practically starts from client side
+ * component. The client side component initially defines the data that will be
+ * present in {@link Transferable} object on server side. If the server side
+ * counterpart of the component implements this interface, terminal
+ * implementation lets it create the {@link Transferable} instance from the raw
+ * client side "seed data". This way server side implementation may translate or
+ * extend the data that will be available for {@link DropHandler}.
*
* @since 6.3
*
*/
-public interface DragSource extends Serializable {
+public interface DragSource extends Component {
/**
- * DragSource may convert client side variables to meaningful values on
- * server side. For example Tree converts item identifiers to generated
- * string keys for the client side. Translators in Selects should convert
- * them back to item identifiers.
+ * DragSource may convert data added by client side component to meaningful
+ * values for server side developer or add other data based on it.
*
* <p>
- * Translator should remove variables it handled from rawVariables. All non
- * handled variables are added to Transferable automatically by terminal.
- * </p>
- *
+ * For example Tree converts item identifiers to generated string keys for
+ * the client side. Vaadin developer don't and can't know anything about
+ * these generated keys, only about item identifiers. When tree node is
+ * dragged client puts that key to {@link Transferable}s client side
+ * counterpart. In {@link Tree#getTransferable(Map)} the key is converted
+ * back to item identifier that the server side developer can use.
* <p>
*
* @since 6.3
* @param rawVariables
- * @return the drag source related transferable
+ * the data that client side initially included in
+ * {@link Transferable}s client side counterpart.
+ * @return the {@link Transferable} instance that will be passed to
+ * {@link DropHandler} (and/or {@link AcceptCriterion})
*/
public Transferable getTransferable(Map<String, Object> rawVariables);
import com.vaadin.event.dd.acceptCriteria.AcceptAll;
import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
+import com.vaadin.event.dd.acceptCriteria.ServerSideCriterion;
/**
- * TODO Javadoc
+ * DropHandlers contain the actual business logic for drag and drop operations.
+ * <p>
+ * The {@link #drop(DragAndDropEvent)} method is used to receive the transferred
+ * data and the #getAcceptCriterion()} method contains the (possibly client side
+ * verifiable) criterion whether the dragged data will be handled at all.
*
* @since 6.3
*
*/
public interface DropHandler extends Serializable {
+ /**
+ * Drop method is called when the end user has finished the drag operation
+ * on a {@link DropTarget} and {@link DragAndDropEvent} has passed
+ * {@link AcceptCriterion} defined by {@link #getAcceptCriterion()} method.
+ * The actual business logic of drag and drop operation is implemented into
+ * this method.
+ *
+ * @param event
+ * the event related to this drop
+ */
public void drop(DragAndDropEvent event);
/**
* Returns the {@link AcceptCriterion} used to evaluate whether the
- * {@link Transferable} will be handed over to {@link DropHandler}. If
- * client side can't verify the {@link AcceptCriterion}, the same criteria
- * may be tested also prior to actual drop - during the drag operation.
+ * {@link Transferable} will be handed over to
+ * {@link DropHandler#drop(DragAndDropEvent)} method. If client side can't
+ * verify the {@link AcceptCriterion}, the same criteria may be tested also
+ * prior to actual drop - during the drag operation.
+ * <p>
+ * Based on information from {@link AcceptCriterion} components may display
+ * some hints for the end user whether the drop will be accepted or not.
+ * <p>
+ * Vaadin contains a variety of criteria built in that can be composed to
+ * more complex criterion. If the build in criteria are not enough,
+ * developer can use a {@link ServerSideCriterion} or build own custom
+ * criterion with client side counterpart.
* <p>
- * If everything is accepted developer can return {@link AcceptAll}
- * instance.
+ * If developer wants to handle everything in the
+ * {@link #drop(DragAndDropEvent)} method, {@link AcceptAll} instance can be
+ * returned.
*
* @return the {@link AcceptCriterion}
*/
*/
public interface DropTarget extends Component {
+ /**
+ * @return the drop hanler that will receive the dragged data or null if
+ * drops are not currently accepted
+ */
public DropHandler getDropHandler();
/**
- * Called before a drop operation to translate the drop target details
- * provided by the client widget (drop target). Should return a DropData
- * implementation with the new values. If null is returned the terminal
- * implementation will automatically create a {@link DropTargetDetails} with
- * all the client variables.
+ * Called before the {@link DragAndDropEvent} is passed to
+ * {@link DropHandler}. Implementation may for exmaple translate the drop
+ * target details provided by the client side (drop target) to meaningful
+ * server side values. If null is returned the terminal implementation will
+ * automatically create a {@link DropTargetDetails} with raw client side
+ * data.
+ *
+ * @see DragSource#getTransferable(Map)
*
* @param rawVariables
- * Parameters passed from the client side widget.
+ * data passed from the DropTargets client side counterpart.
* @return A DropTargetDetails object with the translated data or null to
* use a default implementation.
*/
import java.io.Serializable;
+import com.vaadin.ui.Tree.TreeDropTargetDetails;
+
/**
- * TODO Javadoc
+ * DropTargetDetails wraps drop target related information about
+ * {@link DragAndDropEvent}.
+ * <p>
+ * When a DropTargetDetails object is used in {@link DropHandler} it is often
+ * preferable to cast the DropTargetDetail to an implementation provided by
+ * DropTarget like {@link TreeDropTargetDetails}. They often provide better
+ * typed, drop target specific API.
*
* @since 6.3
*
*/
public interface DropTargetDetails extends Serializable {
+ /**
+ * Gets target data associated to given string key
+ *
+ * @param key
+ * @return
+ */
public Object getData(String key);
- public Object setData(String key, Object value);
-
+ /**
+ * @return the drop target on which the {@link DragAndDropEvent} happened.
+ */
public DropTarget getTarget();
}
import java.util.HashMap;
import java.util.Map;
-import com.vaadin.terminal.gwt.server.DragAndDropService;
-
/**
- * TODO Javadoc
+ * A HashMap backed implementation of {@link DropTargetDetails} for terminal
+ * implementation and for extension.
*
* @since 6.3
*
*/
public class DropTargetDetailsImpl implements DropTargetDetails {
+ private static final long serialVersionUID = -5099462771593036776L;
private HashMap<String, Object> data = new HashMap<String, Object>();
+ private DropTarget dropTarget;
- public DropTargetDetailsImpl(Map<String, Object> rawDropData) {
+ protected DropTargetDetailsImpl(Map<String, Object> rawDropData) {
data.putAll(rawDropData);
}
+ public DropTargetDetailsImpl(Map<String, Object> rawDropData,
+ DropTarget dropTarget) {
+ this(rawDropData);
+ this.dropTarget = dropTarget;
+ }
+
public Object getData(String key) {
return data.get(key);
}
}
public DropTarget getTarget() {
- return (DropTarget) data.get(DragAndDropService.DROPTARGET_KEY);
+ return dropTarget;
}
}
\ No newline at end of file
* Sets the component currently being dragged or from which the transferable
* is created (eg. a tree which node is dragged).
* <p>
- * The server side counterpart of the componennt may implement
+ * The server side counterpart of the component may implement
* {@link DragSource} interface if it wants to translate or complement the
* server side instance of this Transferable.
*
import java.io.PrintWriter;
import java.util.Map;
-import com.vaadin.event.TransferableImpl;
import com.vaadin.event.Transferable;
+import com.vaadin.event.TransferableImpl;
import com.vaadin.event.dd.DragAndDropEvent;
import com.vaadin.event.dd.DragSource;
import com.vaadin.event.dd.DropHandler;
private static final long serialVersionUID = -4745268869323400203L;
- public static final String DROPTARGET_KEY = "target";
-
private int lastVisitId;
private int currentEventId;
if (dropData == null) {
// Create a default DragDropDetails with all the raw variables
- dropData = new DropTargetDetailsImpl(rawDragDropDetails);
+ dropData = new DropTargetDetailsImpl(rawDragDropDetails, dropTarget);
}
- dropData.setData(DROPTARGET_KEY, dropTarget);
-
return dropData;
}
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
+import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Collection;
for (Html5File html5File : files2) {
String fileName = html5File.getFileName();
// int bytes = html5File.getFileSize();
- final ByteArrayOutputStream bas = new ByteArrayOutputStream();
+ final ByteArrayOutputStream bas = new ByteArrayOutputStream() {
+ @Override
+ public void close() throws IOException {
+ super.close();
+ }
+ };
Receiver receiver = new Receiver() {
public OutputStream receiveUpload(String filename,
projects / vaadin-framework.git / commitdiff