| 97 | | == General things == |
| | 98 | * A new package org.sophie2.base.dnd will be created. |
| | 99 | * The following new classes will be defined: |
| | 100 | * ClipboardManager - a Singleton class used to wrap the functionality for Cut/Copy/Paste operations with data and the work with the Clipboard. the System Clipboard will be used for now, but the abstraction allows to add special Clipboard functionality later (e.g. multiple custom clipboards created by name, allowing to switch between them) |
| | 101 | * DnDData hierarchy - wraps the data needing serialization/deserialization along with information about the wanted DataFlavor (DataFlavor usage is hidden from the client code). |
| | 102 | * DnDTransferable - contains the different representaions in which data could be serialized/deserialized, including its supported types. Implements the actual mapping data to DataFlavor. |
| | 103 | * TransferableConverter - a Utility class providing functionality to convert from DnDTransferable to Transferable and vice-versa. |
| | 104 | * DnDDataProvider interface and its implementor SimpleDnDDataProvider - defines Sophie extension for creation of DnDData objects. |
| | 105 | [[Image(source:/branches/private/vlado/sophie2-platform/doc/uml-design-diagrams/DnDDesign.png@2814)]] |
| 99 | | * Drag and Drop should be able to transfer things from Source to Target. |
| 100 | | * Both Source and Target should be able to export and import different types of data, called !DataFlavor. |
| 101 | | * As of Java 1.4, dragging and dropping things is done through the so called !TransferHandler. |
| 102 | | * it is responsible for initiating a drag, accepting a drop and changing the UI correspondingly (changing the mouse cursor depending on the action performed - COPY, MOVE, LINK.) |
| 103 | | * the !TransferHandler need a JComponent in order to detect drag and drop gestures. It is usually enough for a simple Java application, since it transfers text, images, files etc. almost on the fly. |
| 104 | | * the drag and drop mechanism in Java is quite complicated since it can be done in two ways which is sometimes misleading. |
| 105 | | * We need to define three things in order to be able to perform Drad and Drop. The things below are enough to create a library that can provide drag and drop. |
| 106 | | * SophieTransferHandler |
| 107 | | * Transferable |
| 108 | | * DataFlavor |
| | 107 | * The following operations are supported: |
| | 108 | * Copy |
| | 109 | * Workflow |
| | 110 | * A specific Logic receives Copy(or DragOut) notification. |
| | 111 | * A List of DnDData is generated using the DnDDataProvider and the event data. |
| | 112 | * A DnDTransferable is created and set as content to the ClipboardManager. |
| | 113 | * It converts DnDTransferable to Transferable through the TransferableConverter class. |
| | 114 | * The Java Transferable is sent to the Clipboard for serialization of the data. |
| | 115 | * Usability. |
| | 116 | * Can be initiated(fired) from: |
| | 117 | * 'Edit' -> 'Copy' menu item |
| | 118 | * Keyboard shortcuts as specified in Analysis#Overview |
| | 119 | * Supported Copy locations |
| | 120 | * Scene |
| | 121 | * Right Flap -> Resources |
| | 122 | * Left Flap -> Pages |
| | 123 | * LeftFlap -> Books |
| | 124 | * Outside Sophie2 |
| | 125 | * Paste |
| | 126 | * Workflow |
| | 127 | * A specific Logic receives Paste(or Drop) notification. |
| | 128 | * Logic asks ClipboardManager for the current DnD contents (represented as DnDTransferable) |
| | 129 | * ClipboardManager asks Clipboard for the current data contents (represented as Transferable) |
| | 130 | * Transferable is acquired from the Clipboard after deserialization of the data. |
| | 131 | * ClipboardManager converts Transferable to DnDTransferable through the TransferableConverter class. |
| | 132 | * Logic receives DnDTransferable. |
| | 133 | * DnDTransferable is asked for DnDData object corresponding to the first of the possible classes which the target of the Paste operation supports. |
| | 134 | * Logic updates the model with the DnDData content. |
| | 135 | * Usability. |
| | 136 | * Can be initiated(fired) from: |
| | 137 | * 'Edit' -> 'Paste' menu item |
| | 138 | * Keyboard shortcuts as specified in Analysis#Overview |
| | 139 | * Supported Copy locations |
| | 140 | * Scene |
| | 141 | * Right Flap -> Resources |
| | 142 | * Left Flap -> Pages |
| | 143 | * LeftFlap -> Books |
| | 144 | * Outside Sophie2 |
| | 145 | * Cut - implemented as Copy + Delete (which is the typical behavior) |
| | 146 | [[Image(source:/branches/private/vlado/sophie2-platform/doc/uml-design-diagrams/DnDActivity.png@2814)]] |
| 110 | | == SophieTransferHandler == |
| 111 | | * a class representing a !TransferHandler similar to the one described above. It can wrap the one in Java and use part of the methods. |
| 112 | | * It will be responsible for: |
| 113 | | * initiating a drag. |
| 114 | | * accepting a drop. |
| 115 | | * changing the cursor. |
| 116 | | * dropping something. |
| 117 | | * Wrapping the !TransferHandler in Java will help us with the cursor and the drag and drop gestures. |
| 118 | | * We need to following methods to perform a drag and drop operation: |
| 119 | | * protected abstract boolean canDropIn(Transferable transferable); - should tell whether a drop is acceptable provided a Transferable with a !DataFlavor. |
| 120 | | * protected abstract boolean dropIn(Transferable transferable, DropLocation dropLocation, int dropAction); - should perform the actual drop. The Data is contained in the Transferable. |
| 121 | | * protected abstract Transferable createTransferable(); - creates the actual Transferable. |
| 122 | | * protected abstract void transferDone(Transferable data, int action); - invoked after the transfer has been performed. |
| 123 | | * The !SophieTransferHandler should be provided a JComponent and set such so that Drad and Drop gestures are recognized from it. |
| 124 | | * Transferring of data will be done by creating Transferables. |
| 125 | | * !SophieTransferHandler should be extended and defined for most UI components that support drag and drop (Palettes, BookDesktop etc.) - for example in an inner class and an !AutoProperty that depends on the JComponent of a Palette one can create a handler and latter change the Palette's model if a drop operation is performed. |
| 127 | | [[Image(source:/trunk/sophie2-platform/doc/uml-design-diagrams/SophieTransferHandler.png@1805)]] |
| 128 | | |
| 129 | | == Transferables == |
| 130 | | * provides information about the drag operation. |
| 131 | | * type of data transferred - through !DataFlavor constants. |
| 132 | | * may provide more than one type of data, depending on the number of !DataFlavors supported. |
| 133 | | * contains the data transferred - obtained through the !DataFlavor. |
| 134 | | * We should define several Transferables: |
| 135 | | * !FileTransferable - responsible for Transferring of files. Transferring of files between the OS and Sophie will not create such but it will be useful for transferring inside Sophie. |
| 136 | | * !ResourceTransferable - it should have some implementing classes for pages, frames etc. |
| 137 | | * we may later need to define more. |
| 138 | | |
| 139 | | == DataFlavor == |
| 140 | | * Used to unify the types of data a drag and drop operation should deal with. |
| 141 | | * There are some !DataFlavors defined in the Java library. |
| 142 | | * For some things we need to define !DataFlavors. |
| 143 | | * !FrameResources. |
| 144 | | * !BookResources. |
| 145 | | * and other depending on what other drag and drop operations will be implemented. |
| 146 | | |
| 147 | | ''' Note: Some !DataFlavors are not created properly in different platforms despite the idea of being so. For example dragging and dropping of files works fine on windows (the system uses the DataFlavor.javaFileListFlavor flavor) while it does not in gnome (creating different flavor usually with text/uri-list mime type). So be careful when using the Transferables and !DataFlavors.''' |
