Source code: com/virtuosotechnologies/asaph/modelutils/DataTransferUtils.java
1 /*
2 ================================================================================
3
4 FILE: DataTransferUtils.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 API that includes data transfer tools for songs and parts of songs
13
14 PROGRAMMERS:
15
16 Daniel Azuma (DA) <dazuma@kagi.com>
17
18 COPYRIGHT:
19
20 Copyright (C) 2003 Daniel Azuma (dazuma@kagi.com)
21
22 This program is free software; you can redistribute it and/or
23 modify it under the terms of the GNU General Public License as
24 published by the Free Software Foundation; either version 2
25 of the License, or (at your option) any later version.
26
27 This program is distributed in the hope that it will be useful,
28 but WITHOUT ANY WARRANTY; without even the implied warranty of
29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 GNU General Public License for more details.
31
32 You should have received a copy of the GNU General Public
33 License along with this program; if not, write to
34 Free Software Foundation, Inc.
35 59 Temple Place, Suite 330
36 Boston, MA 02111-1307 USA
37
38 ================================================================================
39 */
40
41
42 package com.virtuosotechnologies.asaph.modelutils;
43
44
45 import java.awt.datatransfer.Transferable;
46 import java.awt.datatransfer.DataFlavor;
47 import java.awt.datatransfer.UnsupportedFlavorException;
48 import java.util.Collection;
49 import javax.swing.event.UndoableEditListener;
50
51 import com.virtuosotechnologies.asaph.model.SongLine;
52 import com.virtuosotechnologies.asaph.model.StringSongLineMember;
53 import com.virtuosotechnologies.asaph.model.ChordSet;
54 import com.virtuosotechnologies.asaph.model.Song;
55 import com.virtuosotechnologies.asaph.model.Variation;
56 import com.virtuosotechnologies.asaph.model.SongBlock;
57 import com.virtuosotechnologies.asaph.modelutils.impl.LineFragmentData;
58 import com.virtuosotechnologies.asaph.modelutils.impl.LineListData;
59 import com.virtuosotechnologies.asaph.modelutils.impl.BlockListData;
60
61
62 /**
63 * API that includes data transfer tools for songs and parts of songs
64 */
65 public interface DataTransferUtils
66 {
67 /**
68 * The name of this API.
69 */
70 public static final String API_NAME =
71 "com.virtuosotechnologies.asaph.modelutils.DataTransferUtils";
72
73
74 /**
75 * DataFlavor for a list of blocks
76 */
77 public static final DataFlavor BLOCKLIST_FLAVOR =
78 new DataFlavor(BlockListData.class, "Block List");
79
80 /**
81 * DataFlavor for a list of lines
82 */
83 public static final DataFlavor LINELIST_FLAVOR =
84 new DataFlavor(LineListData.class, "Line List");
85
86 /**
87 * DataFlavor for a part of a line
88 */
89 public static final DataFlavor LINEFRAGMENT_FLAVOR =
90 new DataFlavor(LineFragmentData.class, "Line Fragment");
91
92
93 /**
94 * Set the current system clipboard contents.
95 *
96 * @param transfer Transferable to set
97 */
98 public void setClipboardContents(
99 Transferable transfer);
100
101
102 /**
103 * Get the current system clipboard contents. If the last call to setClipboardContents
104 * was given a Transferable obtained by one of the methods of this API (i.e. it is a
105 * TransferableImpl), and the clipboard contents haven't changed, then this will
106 * return a TransferableImpl.
107 *
108 * @return Transferable
109 */
110 public Transferable getClipboardContents();
111
112
113 /**
114 * Create a Transferable for a fragment of a line
115 *
116 * @param line the containing SongLine
117 * @param startMember the starting line member, or null to specify
118 * the start of the line
119 * @param startPos position within the starting line member
120 * @param endMember the ending line member, or null to specify
121 * the end of the line
122 * @param endPos position within the ending line member
123 * @param currentSet current ChordSet
124 * @param remove true to remove the data from the line
125 * @param undoListener listener for undo records. Ignored if remove is false.
126 * @return a Transferable that provides LINEFRAGMENT_FLAVOR
127 * @exception IllegalArgumentException
128 */
129 public Transferable createLineFragmentTransferable(
130 SongLine line,
131 StringSongLineMember startMember,
132 int startPos,
133 StringSongLineMember endMember,
134 int endPos,
135 ChordSet currentSet,
136 boolean remove,
137 UndoableEditListener undoListener);
138
139
140 /**
141 * Create a Transferable for an ordered collection of lines in a song
142 *
143 * @param song the song containing the blocks.
144 * @param lines ordered Collection of Line objects.
145 * @param currentSet current ChordSet
146 * @param remove true to remove the lines from the song
147 * @param undoListener listener for undo records. Ignored if remove is false.
148 * @return a Transferable that provides LINELIST_FLAVOR
149 * @exception IllegalArgumentException some lines are defunct or are not from the
150 * given song.
151 */
152 public Transferable createLineListTransferable(
153 Song song,
154 Collection lines,
155 ChordSet currentSet,
156 boolean remove,
157 UndoableEditListener undoListener);
158
159
160 /**
161 * Create a Transferable for an ordered collection of blocks in a song
162 *
163 * @param song the song containing the blocks.
164 * @param blocks ordered Collection of Block objects.
165 * @param currentSet current ChordSet
166 * @param variation Variation to remove blocks from
167 * @param remove true to remove the blocks from the song
168 * @param undoListener listener for undo records. Ignored if remove is false.
169 * @return a Transferable that provides BLOCKLIST_FLAVOR
170 * @exception IllegalArgumentException some blocks are defunct or are not from the
171 * given song.
172 */
173 public Transferable createBlockListTransferable(
174 Song song,
175 Collection blocks,
176 ChordSet currentSet,
177 Variation variation,
178 boolean remove,
179 UndoableEditListener undoListener);
180
181
182 /**
183 * Create a Transferable given a string. Interprets the string into lines, and
184 * generates either LINFRAGMENT_FLAVOR or LINELIST_FLAVOR.
185 *
186 * @param str string to examine
187 * @return a Transferable
188 */
189 public Transferable createTransferableForString(
190 String str);
191
192
193 /**
194 * Get the flavor of the given transferable. If the given preferred flavor is
195 * available in the transferable, returns that flavor, otherwise, returns the "best"
196 * flavor out of LINFRAGMENT_FLAVOR, LINELIST_FLAVOR, BLOCKLIST_FLAVOR and stringFlavor.
197 * Returns null if none of those flavors is available.
198 *
199 * @param transferable transferable to examine
200 * @param preferred the preferred flavor, or null for no preference.
201 * @return the DataFlavor to use for pasting.
202 */
203 public DataFlavor getFlavorOf(
204 Transferable transferable,
205 DataFlavor preferred);
206
207
208 /**
209 * Get the type of object that would be pasted given a transferable and a context.
210 *
211 * @param transferable transferable to examine
212 * @param pasteContext the DataFlavor indicating where the user is pasting. Must be
213 * LINFRAGMENT_FLAVOR, LINELIST_FLAVOR or BLOCKLIST_FLAVOR.
214 * @return a DataFlavor indicating the type of pasted object
215 * @exception CannotPasteException the transferable doesn't provide a suitable flavor
216 */
217 public DataFlavor getPasteType(
218 Transferable transferable,
219 DataFlavor pasteContext)
220 throws
221 CannotPasteException;
222
223
224 /**
225 * Paste the given transferable in the given position.
226 *
227 * @param transferable transferable to paste
228 * @param line line to paste into
229 * @param member member containing the paste position. Null to paste at the beginning
230 * @param pos position within the member
231 * @param chordSet ChordSet to use for the transferable's primary chords
232 * if the destination song is not the same as the source song.
233 * @param variation variation to add blocks to, or null for the default variation.
234 * @param undoListener listener for undo records, or null to not generate edits
235 * @exception CannotPasteException the transferable doesn't provide a suitable flavor
236 */
237 public void pasteTransferable(
238 Transferable transferable,
239 SongLine line,
240 StringSongLineMember member,
241 int pos,
242 ChordSet chordSet,
243 Variation variation,
244 UndoableEditListener undoListener)
245 throws
246 CannotPasteException;
247
248
249 /**
250 * Paste the given transferable, replacing the given range.
251 *
252 * @param transferable transferable to paste
253 * @param line line to paste into
254 * @param startMember Start of the range to replace. Null for the beginning of the line
255 * @param startPos position within startMember
256 * @param endMember End of the range to replace. Null for the end of the line
257 * @param endPos position within endMember
258 * @param chordSet ChordSet to use for the transferable's primary chords
259 * if the destination song is not the same as the source song.
260 * @param variation variation to add blocks to, or null for the default variation.
261 * @param undoListener listener for undo records, or null to not generate edits
262 * @exception CannotPasteException the transferable doesn't provide a suitable flavor
263 */
264 public void pasteTransferable(
265 Transferable transferable,
266 SongLine line,
267 StringSongLineMember startMember,
268 int startPos,
269 StringSongLineMember endMember,
270 int endPos,
271 ChordSet chordSet,
272 Variation variation,
273 UndoableEditListener undoListener)
274 throws
275 CannotPasteException;
276
277
278 /**
279 * Paste the given transferable after the given line.
280 *
281 * @param transferable transferable to paste
282 * @param block block to paste into
283 * @param line line to paste after, or null to paste at beginning
284 * @param chordSet ChordSet to use for the transferable's primary chords
285 * if the destination song is not the same as the source song.
286 * @param variation variation to add blocks to, or null for the default variation.
287 * @param undoListener listener for undo records, or null to not generate edits
288 * @exception CannotPasteException the transferable doesn't provide a suitable flavor
289 */
290 public void pasteTransferableAfter(
291 Transferable transferable,
292 SongBlock block,
293 SongLine line,
294 ChordSet chordSet,
295 Variation variation,
296 UndoableEditListener undoListener)
297 throws
298 CannotPasteException;
299
300
301 /**
302 * Paste the given transferable after the given block.
303 *
304 * @param transferable transferable to paste
305 * @param song song to paste into
306 * @param block block to paste after, or null to paste at beginning
307 * @param chordSet ChordSet to use for the transferable's primary chords
308 * if the destination song is not the same as the source song.
309 * @param variation variation to add blocks to, or null for the default variation.
310 * @param undoListener listener for undo records, or null to not generate edits
311 * @exception CannotPasteException the transferable doesn't provide a suitable flavor
312 */
313 public void pasteTransferableAfter(
314 Transferable transferable,
315 Song song,
316 SongBlock block,
317 ChordSet chordSet,
318 Variation variation,
319 UndoableEditListener undoListener)
320 throws
321 CannotPasteException;
322 }