com.virtuosotechnologies.asaph.modelutils
Interface DataTransferUtils

public interface DataTransferUtils

API that includes data transfer tools for songs and parts of songs.

This API is thread-safe and may be called from any thread.

Field Summary

static DataFlavor	BLOCKLIST_FLAVOR DataFlavor for a list of blocks
static DataFlavor	LINEFRAGMENT_FLAVOR DataFlavor for a part of a line
static DataFlavor	LINELIST_FLAVOR DataFlavor for a list of lines

Method Summary

Transferable	createBlockListTransferable(Song song, Collection blocks, ChordSet currentSet, Variation variation, boolean remove, UndoableEditListener undoListener) Create a Transferable for an ordered collection of blocks in a song
Transferable	createLineFragmentTransferable(SongLine line, TextString startMember, int startPos, TextString endMember, int endPos, ChordSet currentSet, boolean remove, UndoableEditListener undoListener) Create a Transferable for a fragment of a line
Transferable	createLineListTransferable(Song song, Collection lines, ChordSet currentSet, boolean remove, UndoableEditListener undoListener) Create a Transferable for an ordered collection of lines in a song
Transferable	createTransferableForString(String str) Create a Transferable given a string.
Transferable	getClipboardContents() Get the current system clipboard contents.
DataFlavor	getFlavorOf(Transferable transferable, DataFlavor preferred) Get the flavor of the given transferable.
DataFlavor	getPasteType(Transferable transferable, DataFlavor pasteContext) Get the type of object that would be pasted given a transferable and a context.
void	pasteTransferable(Transferable transferable, SongLine line, TextString member, int pos, ChordSet chordSet, Variation variation, UndoableEditListener undoListener) Paste the given transferable in the given position.
void	pasteTransferable(Transferable transferable, SongLine line, TextString startMember, int startPos, TextString endMember, int endPos, ChordSet chordSet, Variation variation, UndoableEditListener undoListener) Paste the given transferable, replacing the given range.
void	pasteTransferableAfter(Transferable transferable, SongBlock block, SongLine line, ChordSet chordSet, Variation variation, UndoableEditListener undoListener) Paste the given transferable after the given line.
void	pasteTransferableAfter(Transferable transferable, Song song, SongBlock block, ChordSet chordSet, Variation variation, UndoableEditListener undoListener) Paste the given transferable after the given block.
void	setClipboardContents(Transferable transfer) Set the current system clipboard contents.

Field Detail

BLOCKLIST_FLAVOR

public static final DataFlavor BLOCKLIST_FLAVOR

DataFlavor for a list of blocks

LINELIST_FLAVOR

public static final DataFlavor LINELIST_FLAVOR

DataFlavor for a list of lines

LINEFRAGMENT_FLAVOR

public static final DataFlavor LINEFRAGMENT_FLAVOR

DataFlavor for a part of a line

Method Detail

setClipboardContents

public void setClipboardContents(Transferable transfer)

Set the current system clipboard contents.

Parameters:

transfer - Transferable to set

getClipboardContents

public Transferable getClipboardContents()

Get the current system clipboard contents. If the last call to setClipboardContents was given a Transferable obtained by one of the methods of this API (i.e. it is a TransferableImpl), and the clipboard contents haven't changed, then this will return a TransferableImpl.

Returns:

Transferable

createLineFragmentTransferable

public Transferable createLineFragmentTransferable(SongLine line,
                                                   TextString startMember,
                                                   int startPos,
                                                   TextString endMember,
                                                   int endPos,
                                                   ChordSet currentSet,
                                                   boolean remove,
                                                   UndoableEditListener undoListener)

Create a Transferable for a fragment of a line

Parameters:

line - the containing SongLine

startMember - the starting line member, or null to specify the start of the line

startPos - position within the starting line member

endMember - the ending line member, or null to specify the end of the line

endPos - position within the ending line member

currentSet - current ChordSet

remove - true to remove the data from the line

undoListener - listener for undo records. Ignored if remove is false.

Returns:

a Transferable that provides LINEFRAGMENT_FLAVOR

Throws:

IllegalArgumentException

createLineListTransferable

public Transferable createLineListTransferable(Song song,
                                               Collection lines,
                                               ChordSet currentSet,
                                               boolean remove,
                                               UndoableEditListener undoListener)

Create a Transferable for an ordered collection of lines in a song

Parameters:

song - the song containing the blocks.

lines - ordered Collection of Line objects.

currentSet - current ChordSet

remove - true to remove the lines from the song

undoListener - listener for undo records. Ignored if remove is false.

Returns:

a Transferable that provides LINELIST_FLAVOR

Throws:

IllegalArgumentException - some lines are defunct or are not from the given song.

createBlockListTransferable

public Transferable createBlockListTransferable(Song song,
                                                Collection blocks,
                                                ChordSet currentSet,
                                                Variation variation,
                                                boolean remove,
                                                UndoableEditListener undoListener)

Create a Transferable for an ordered collection of blocks in a song

Parameters:

song - the song containing the blocks.

blocks - ordered Collection of Block objects.

currentSet - current ChordSet

variation - Variation to remove blocks from

remove - true to remove the blocks from the song

undoListener - listener for undo records. Ignored if remove is false.

Returns:

a Transferable that provides BLOCKLIST_FLAVOR

Throws:

IllegalArgumentException - some blocks are defunct or are not from the given song.

createTransferableForString

public Transferable createTransferableForString(String str)

Create a Transferable given a string. Interprets the string into lines, and generates either LINFRAGMENT_FLAVOR or LINELIST_FLAVOR.

Parameters:

str - string to examine

Returns:

a Transferable

getFlavorOf

public DataFlavor getFlavorOf(Transferable transferable,
                              DataFlavor preferred)

Get the flavor of the given transferable. If the given preferred flavor is available in the transferable, returns that flavor, otherwise, returns the "best" flavor out of LINFRAGMENT_FLAVOR, LINELIST_FLAVOR, BLOCKLIST_FLAVOR and stringFlavor. Returns null if none of those flavors is available.

Parameters:

transferable - transferable to examine

preferred - the preferred flavor, or null for no preference.

Returns:

the DataFlavor to use for pasting.

getPasteType

public DataFlavor getPasteType(Transferable transferable,
                               DataFlavor pasteContext)
                        throws CannotPasteException

Get the type of object that would be pasted given a transferable and a context.

Parameters:

transferable - transferable to examine

pasteContext - the DataFlavor indicating where the user is pasting. Must be LINFRAGMENT_FLAVOR, LINELIST_FLAVOR or BLOCKLIST_FLAVOR.

Returns:

a DataFlavor indicating the type of pasted object

Throws:

CannotPasteException - the transferable doesn't provide a suitable flavor

pasteTransferable

public void pasteTransferable(Transferable transferable,
                              SongLine line,
                              TextString member,
                              int pos,
                              ChordSet chordSet,
                              Variation variation,
                              UndoableEditListener undoListener)
                       throws CannotPasteException

Paste the given transferable in the given position.

Parameters:

transferable - transferable to paste

line - line to paste into

member - member containing the paste position. Null to paste at the beginning

pos - position within the member

chordSet - ChordSet to use for the transferable's primary chords if the destination song is not the same as the source song.

variation - variation to add blocks to, or null for the default variation.

undoListener - listener for undo records, or null to not generate edits

Throws:

CannotPasteException - the transferable doesn't provide a suitable flavor

pasteTransferable

public void pasteTransferable(Transferable transferable,
                              SongLine line,
                              TextString startMember,
                              int startPos,
                              TextString endMember,
                              int endPos,
                              ChordSet chordSet,
                              Variation variation,
                              UndoableEditListener undoListener)
                       throws CannotPasteException

Paste the given transferable, replacing the given range.

Parameters:

transferable - transferable to paste

line - line to paste into

startMember - Start of the range to replace. Null for the beginning of the line

startPos - position within startMember

endMember - End of the range to replace. Null for the end of the line

endPos - position within endMember

chordSet - ChordSet to use for the transferable's primary chords if the destination song is not the same as the source song.

variation - variation to add blocks to, or null for the default variation.

undoListener - listener for undo records, or null to not generate edits

Throws:

CannotPasteException - the transferable doesn't provide a suitable flavor

pasteTransferableAfter

public void pasteTransferableAfter(Transferable transferable,
                                   SongBlock block,
                                   SongLine line,
                                   ChordSet chordSet,
                                   Variation variation,
                                   UndoableEditListener undoListener)
                            throws CannotPasteException

Paste the given transferable after the given line.

Parameters:

transferable - transferable to paste

block - block to paste into

line - line to paste after, or null to paste at beginning

chordSet - ChordSet to use for the transferable's primary chords if the destination song is not the same as the source song.

variation - variation to add blocks to, or null for the default variation.

undoListener - listener for undo records, or null to not generate edits

Throws:

CannotPasteException - the transferable doesn't provide a suitable flavor

pasteTransferableAfter

public void pasteTransferableAfter(Transferable transferable,
                                   Song song,
                                   SongBlock block,
                                   ChordSet chordSet,
                                   Variation variation,
                                   UndoableEditListener undoListener)
                            throws CannotPasteException

Paste the given transferable after the given block.

Parameters:

transferable - transferable to paste

song - song to paste into

block - block to paste after, or null to paste at beginning

chordSet - ChordSet to use for the transferable's primary chords if the destination song is not the same as the source song.

variation - variation to add blocks to, or null for the default variation.

undoListener - listener for undo records, or null to not generate edits

Throws:

CannotPasteException - the transferable doesn't provide a suitable flavor