O'Reilly logo

Java AWT Reference by John Zukowski

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

20

java.awt.datatransfer Reference

20.1 Clipboard images

Description

The Clipboard class is a repository for a Transferable object and can be used for cut, copy, and paste operations. The system clipboard can be accessed by calling Toolkit.getDefaultToolkit().getSystemClipboard(). You can use this technique if you are interested in exchanging data between your application and other applications (Java or non-Java) running on the system. In addition, Clipboard can be instantiated directly, if “private” clipboards are needed.

Class Definition

public class java.awt.datatransfer.Clipboard
   extends java.lang.Object {

  // Variables
  protected Transferable contents;
  protected ClipboardOwner owner;

  // Constructors
  public Clipboard (String name);

  // Instance Methods
  public synchronized Transferable getContents (Object requestor);
  public String getName();
  public synchronized void setContents (Transferable contents, ClipboardOwner owner);
}

Variables

contents

protected Transferable contents

The object that the Clipboard contains, i.e., the object that has been cut or copied.

owner

protected ClipboardOwner owner

The object that owns the contents. When something else is placed on the clipboard, owner is notified via lostOwnership().

Constructors

Clipboard

public Clipboard (String name)
Parameters name The name for this Clipboard.
Description Constructs a Clipboard object with the given name.

Instance Methods

getContents

public synchronized Transferable getContents (Object
requestor)
Parameters requestor The object asking for the contents.
Returns An object that implements the Transferable interface.
Description Returns the current contents of the Clipboard. You could use this method to paste data from the clipboard into your application.

getName

public String getName()
Returns Clipboard's name.
Description Returns the name used when this clipboard was constructed. Toolkit.getSystemClipboard() returns a Clipboard named “System”.

setContents

public synchronized void setContents (Transferable
contents, ClipboardOwner owner)
Parameters contents New contents.
owner Owner of the new contents.
Description Changes the contents of the Clipboard. You could use this method to cut or copy data from your application to the clipboard.

See Also

ClipboardOwner, Toolkit, Transferable

20.2 ClipboardOwner images

Description

ClipboardOwner is implemented by classes that want to be notified when someone else sets the contents of a clipboard.

Interface Definition

public abstract interface java.awt.datatransfer.ClipboardOwner {

  // Interface Methods
  public abstract void lostOwnership (Clipboard clipboard, Transferable contents);
}

Interface Methods

lostOwnership

public abstract void lostOwnership (Clipboard clipboard,
Transferable contents)
Parameters clipboard The clipboard whose contents have changed.
contents The contents that this owner originally put on the clipboard.
Description Tells the ClipboardOwner that the contents it placed on the given clipboard are no longer there.

See Also

Clipboard, StringSelection, Transferable

20.3 DataFlavor images

Description

The DataFlavor class encapsulates information about data formats.

Class Definition

public class java.awt.datatransfer.DataFlavor
   extends java.lang.Object {

  // Class Variables
  public static DataFlavor plainTextFlavor;
  public static DataFlavor stringFlavor;

  // Constructors
  public DataFlavor (Class representationClass,
    String humanPresentableName);
  public DataFlavor (String MIMEType, String humanPresentableName);

  // Instance Methods
  public boolean equals (DataFlavor dataFlavor);
  public String getHumanPresentableName();
  public String getMIMEType();
  public Class getRepresentationClass();
  public boolean isMIMETypeEqual (String MIMEType);
  public final boolean isMIMETypeEqual (DataFlavor dataFlavor);
  public void setHumanPresentableName (String humanPresentableName);

  // Protected Instance Methods
  protected String normalizeMIMEType (String MIMEType);
  protected String normalizeMIMETypeParameter (String parameterName,
    String parameterValue);
}

Class Variables

plainTextFlavor

public static DataFlavor plainTextFlavor

A preset DataFlavor object representing plain text.

stringFlavor

public static DataFlavor stringFlavor

A preset DataFlavor object representing a Java String.

Constructors

DataFlavor

public DataFlavor (Class representationClass, String
humanPresentableName)
Parameters representationClass
The Java class that represents data in this flavor.
humanPresentableName
A name for this flavor that humans will recognize.
Description Constructs a DataFlavor object with the given characteristics. The MIME type for this DataFlavor is application/xjava-serialized-object <Java ClassName>*.
public DataFlavor (String MIMEType, String humanPresentableName)
Parameters MIMEType The MIME type string this DataFlavor represents.
humanPresentableName
A name for this flavor that humans will recognize.
Description Constructs a DataFlavor object with the given characteristics. The representation class used for this DataFlavor is java.io.InputStream.

Instance Methods

equals

public boolean equals (DataFlavor dataFlavor)
Parameters dataFlavor The flavor to compare.
Returns true if dataFlavor is equivalent to this DataFlavor, false otherwise.
Description Compares two different DataFlavor instances for equivalence.

getHumanPresentableName

public String getHumanPresentableName()
Returns The name of this flavor.

getMIMEType

public String getMIMEType()
Returns The MIME type string for this flavor.

getRepresentationClass

public Class getRepresentationClass()
Returns The Java class that will be used to represent data in this flavor.

isMIMETypeEqual

public boolean isMIMETypeEqual (String MIMEType)
Parameters MIMEType The type to compare.
Returns true if the given MIME type is the same as this DataFlavor's MIME type; false otherwise.
Description Compares two different DataFlavor MIME types for equivalence.
public final boolean is MIME TypeEqual (DataFlavor dataFlavor)
Parameters dataFlavor The flavor to compare.
Returns true if DataFlavor's MIME type is the same as this DataFlavor's MIME type; false otherwise.
Description Compares two different DataFlavor MIME types for equivalence.

setHumanPresentableName

public void setHumanPresentableName (String
humanPresentableName)
Parameters humanPresentableName
A name for this flavor that humans will recognize.
Description Changes the name of the DataFlavor.

Protected Instance Methods

normalizeMIMEType

protected String normalizeMIMEType (String MIMEType)
Parameters MIMEType The MIME type string to normalize.
Returns Normalized MIME type string.
Description This method is called for each MIME type string. Subclasses can override this method to add default parameter/value pairs to MIME strings.

normalizeMIMETypeParameter

protected String normalizeMIMETypeParameter (String
parameterName, String parameterValue)
Parameters parameterName
The MIME type parameter to normalize.
parameterValue
The corresponding value.
Returns Normalized MIME type parameter string.
Description This method is called for each MIME type parameter string. Subclasses can override this method to handle special parameters, such as those that are case-insensitive.

See Also

Class, String

20.4 StringSelection images

Description

StringSelection is a “convenience” class that can be used for copy and paste operations on Unicode text strings. For example, you could place a string on the system's clipboard with the following code:

Clipboard c =
  Toolkit.getDefaultToolkit().getSystemClipboard();
StringSelection s = new StringSelection(

  "Be safe when you cut and paste.");
c.setContents(s, s);

Class Definition

public class java.awt.datatransfer.StringSelection
   extends java.lang.Object
   implements java.awt.datatransfer.ClipboardOwner,
         java.awt.datatransfer.Transferable {

   // Constructor
   public StringSelection(String data);

   // Instance Methods
public synchronized Object getTransferData (DataFlavor flavor)
     throws UnsupportedFlavorException, IOException;
   public synchronized DataFlavor[] getTransferDataFlavors();
   public boolean isDataFlavorSupported (DataFlavor flavor);
   public void lostOwnership (Clipboard clipboard, Transferable contents);
}

Constructors

StringSelection

public StringSelection (String data)
Parameters data The string to be placed in a clipboard.
Description Constructs a StringSelection object from the given string.

Instance Methods

getTransferData

public synchronized Object getTransferData (DataFlavor
flavor) throws UnsupportedFlavorException, IOException
Parameters flavor The requested flavor for the returned data, which can be either DataFlavor.stringFlavor or DataFlavor.plainTextFlavor.
Returns The string that the StringSelection was constructed with. This is returned either as a String object or a Reader object, depending on the flavor requested.
Throws UnsupportedFlavorException
If the requested flavor is not supported.
IOException If a Reader representing the string could not be created.
Implements Transferable.getTransferData(DataFlavor)
Description Returns the string this StringSelection represents. This is returned either as a String object or a Reader object, depending on the flavor requested.

getTransferDataFlavors

public synchronized DataFlavor[] getTransferDataFlavors()
Returns An array of the data flavors the StringSelection supports.
Implements Transferable.getTransferDataFlavors()
Description DataFlavor.stringFlavor and DataFlavor.plainTextFlavor are returned.

isDataFlavorSupported

public boolean isDataFlavorSupported (DataFlavor flavor)
Parameters flavor The flavor in question.
Returns true if flavor is supported; false otherwise.
Implements Transferable.isDataFlavorSupported(DataFlavor)

lostOwnership

public void lostOwnership (Clipboard clipboard,
Transferable contents)
Parameters clipboard The clipboard whose contents are changing.
contents The contents that were on the clipboard.
Implements ClipboardOwner.lostOwnership(Clipboard, Transferable)
Description Does nothing.

See Also

Clipboard, ClipboardOwner, DataFlavor, String, Transferable

20.5 Transferable images

Description

The Transferable interface is implemented by objects that can be placed on Clipboards.

Interface Definition

public abstract interface Transferable {

  // Instance Methods
  public abstract Object getTransferData (DataFlavor flavor)
    throws UnsupportedFlavorException, IOException;
  public abstract DataFlavor[] getTransferDataFlavors();
  public abstract boolean isDataFlavorSupported (DataFlavor flavor);
}

Interface Methods

getTransferData

public abstract Object getTransferData (DataFlavor flavor)
throws UnsupportedFlavorException, IOException
Parameters flavor The requested flavor for the returned data.
Returns The data represented by this Transferable object, in the requested flavor.
Throws UnsupportedFlavorException
If the requested flavor is not supported.
IOException If a Reader representing the data could not be created.
Description Returns the data this Transferable object represents. The class of object returned depends on the flavor requested.

getTransferDataFlavors

public abstract DataFlavor[] getTransferDataFlavors()
Returns An array of the supported data flavors.
Description The data flavors should be returned in order, sorted from most to least descriptive.

isDataFlavorSupported

public abstract boolean isDataFlavorSupported (DataFlavor
flavor)
Parameters flavor The flavor in question.
Returns true if flavor is supported; false otherwise.

See Also

Clipboard, DataFlavor, Reader, StringSelection, Transferable

20.6 UnsupportedFlavorException images

Description

This exception is thrown from Transferable.getTransferData(DataFlavor) to indicate that the DataFlavor requested is not available.

Class Definition

public class java.awt.datatransfer.UnsupportedFlavorException
   extends java.lang.Exception {

  // Constructor
  public UnsupportedFlavorException (DataFlavor flavor);
}

Constructors

UnsupportedFlavorException

public UnsupportedFlavorException (DataFlavor flavor)
Parameters flavor The flavor that caused the exception.

See Also

DataFlavor, Exception, Transferable

* The type name changed to x-java-serialized-object in the 1.1.1 release.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required