Common Application Features

From Apache OpenOffice Wiki
Jump to: navigation, search



Clipboard

This chapter introduces the usage of the clipboard service com.sun.star.datatransfer.clipboard.SystemClipboard. The clipboard serves as a data exchange mechanism between Apache OpenOffice custom components, or between custom components and external applications. It is usually used for copy and paste operations.

Documentation note.png Note: The architecture of the Apache OpenOffice clipboard service is strongly conforming to the Java clipboard specification.

Different platforms use different methods for describing data formats available on the clipboard. Under Windows, clipboard formats are identified by unique numbers, for example, under X11, a clipboard format is identified by an ATOM. To have a platform independent mechanism, the Apache OpenOffice clipboard supports the concept of DataFlavors. Each instance of a DataFlavor represents the opaque concept of a data format as it would appear on a clipboard. A DataFlavor defined in com.sun.star.datatransfer.DataFlavor has three members:

Members of com.sun.star.datatransfer.DataFlavor
MimeType A string that describes the data. This string must conform to Rfc2045 and Rfc2046 with one exception. The quoted parameter may contain spaces. In section Apache OpenOffice Clipboard Data Formats, a list of common DataFlavors supported by Apache OpenOffice is provided.
HumanPresentableName The human presentable name for the data format that this DataFlavor represents.
DataType The type of the data. In section Apache OpenOffice Clipboard Data Formats there is a list of common DataFlavors supported by Apache OpenOffice and their corresponding DataType.

The carrier of the clipboard data is a transferable object that implements the interface com.sun.star.datatransfer.XTransferable. A transferable object offers one or many different DataFlavors.

Using the Clipboard

Pasting Data

The following Java example demonstrates the use of the clipboard service to paste from the clipboard.

  import com.sun.star.datatransfer.*;
  import com.sun.star.datatransfer.clipboard.*;
  import com.sun.star.uno.AnyConverter;
  ...
 
  // instantiate the clipboard service
 
  Object oClipboard =
          xMultiComponentFactory.createInstanceWithContext(
          "com.sun.star.datatransfer.clipboard.SystemClipboard", 
          xComponentContext);
 
  // query for the interface XClipboard 
 
  XClipboard xClipboard = (XClipboard)
          UnoRuntime.queryInterface(XClipboard.class, oClipboard);
 
  //---------------------------------------------------
  // get a list of formats currently on the clipboard
  //---------------------------------------------------
 
  XTransferable xTransferable = xClipboard.getContents();
 
  DataFlavor[] aDflvArr = xTransferable.getTransferDataFlavors();
 
  // print all available formats
 
  System.out.println("Reading the clipboard...");
  System.out.println("Available clipboard formats:");
 
  DataFlavor aUniFlv = null;
 
  for (int i=0;i<aDflvArr.length;i++)
  {
          System.out.println( "MimeType: " + 
                  aDflvArr[i].MimeType + 
                  " HumanPresentableName: " + 
                  aDflvArr[i].HumanPresentableName );    
 
          // if there is the format unicode text on the clipboard save the
          // corresponding DataFlavor so that we can later output the string
 
          if (aDflvArr[i].MimeType.equals("text/plain;charset=utf-16"))
          {     
                  aUniFlv = aDflvArr[i];
          }
  }
 
  System.out.println("");
 
  try 
  {
          if (aUniFlv != null)
          {
                  System.out.println("Unicode text on the clipboard...");
                  Object aData = xTransferable.getTransferData(aUniFlv);      
 
  System.out.println(AnyConverter.toString(aData));
          }
  }
  catch(UnsupportedFlavorException ex)
  {
          System.err.println( "Requested format is not available" );
  }
 
  ...
Copying Data

To copy to the clipboard, implement a transferable object that supports the interface com.sun.star.datatransfer.XTransferable. The transferable object offers arbitrary formats described by DataFlavors.

The following Java example demonstrates the implementation of a transferable object. This transferable object contains only one format, unicode text.

  //--------------------------------------- 
  // A simple transferable containing only 
  // one format, unicode text 
  //--------------------------------------- 
  public class TextTransferable implements XTransferable 
  {  
         public TextTransferable(String aText)  
         {   
                 text = aText;  
         }
 
         // XTransferable methods
         public Object getTransferData(DataFlavor aFlavor) throws UnsupportedFlavorException 
         {   
                 if ( !aFlavor.MimeType.equalsIgnoreCase( UNICODE_CONTENT_TYPE ) )
                        throw new UnsupportedFlavorException();
                 return text;
         }
         public DataFlavor[] getTransferDataFlavors()  
         {   
                DataFlavor[] adf = new DataFlavor[1];  
                DataFlavor uniflv = new DataFlavor(
                        UNICODE_CONTENT_TYPE,
                        "Unicode Text",
                        new Type(String.class) );
                adf[0] = uniflv;
 
                return adf;
         }
         public boolean isDataFlavorSupported(DataFlavor aFlavor)  
         {   
                return aFlavor.MimeType.equalsIgnoreCase(UNICODE_CONTENT_TYPE);
         }   
 
         // members  
         private final String text;  
         private final String UNICODE_CONTENT_TYPE = "text/plain;charset=utf-16"; 
  }

Everyone providing data to the clipboard becomes a clipboard owner. A clipboard owner is an object that implements the interface com.sun.star.datatransfer.clipboard.XClipboardOwner. If the current clipboard owner loses ownership of the clipboard, it receives a notification from the clipboard service. The clipboard owner can use this notification to destroy the transferable object that was formerly on the clipboard. If the transferable object is a self-destroying object, destroying clears all references to the object. If the clipboard service is the last client, clearing the reference to the transferable object leads to destruction.

All data types except for text have to be transferred as byte array. The next example shows this for a bitmap.

  public class BmpTransferable implements XTransferable
  {
      public BmpTransferable(byte[] aBitmap)
      {
          mBitmapData = aBitmap;
      }
 
      // XTransferable methods
      public Object getTransferData(DataFlavor aFlavor) throws UnsupportedFlavorException
      {
          if ( !aFlavor.MimeType.equalsIgnoreCase(BITMAP_CONTENT_TYPE ) )
              throw new UnsupportedFlavorException();
 
          return mBitmapData;
      }
      public DataFlavor[] getTransferDataFlavors()
      {
          DataFlavor[] adf = new DataFlavor[1];
          DataFlavor bmpflv= new DataFlavor(
              BITMAP_CONTENT_TYPE,
              "Bitmap",
              new Type(byte[].class) );
          adf[0] = bmpflv;
 
          return adf;
      }
      public boolean isDataFlavorSupported(DataFlavor aFlavor)
      {
          return aFlavor.MimeType.equalsIgnoreCase(BITMAP_CONTENT_TYPE);
      }
 
      // members
      private byte[] mBitmapData;
      private final String BITMAP_CONTENT_TYPE = "application/x-openoffice;windows_formatname="Bitmap"";
  }

The following Java example shows an implementation of the interface com.sun.star.datatransfer.clipboard.XClipboardOwner.

  ...
 
  //----------------------------------------
  // A simple clipboard owner implementation
  //----------------------------------------
 
  public class ClipboardOwner implements XClipboardOwner
  { 
          public void lostOwnership( 
                  XClipboard xClipboard, 
                  XTransferable xTransferable )
          {
                  System.out.println("");
                  System.out.println( "Lost clipboard ownership..." );
                  System.out.println("");
 
                  isowner = false;
          }
 
          public boolean isClipboardOwner()
          {
                  return isowner;
          }
 
          private boolean isowner = true;
  }
 
  ...

The last two samples combined show how it is possible to copy data to the clipboard as demonstrated in the following Java example.

  import com.sun.star.datatransfer.*; 
  import com.sun.star.datatransfer.clipboard.*; 
  import com.sun.star.uno.AnyConverter;
  ... 
  // instantiate the clipboard service
 
  Object oClipboard =
          xMultiComponentFactory.createInstanceWithContext(
          "com.sun.star.datatransfer.clipboard.SystemClipboard", 
          xComponentContext);
 
  // query for the interface XClipboard  
  XClipboard xClipboard = (Xclipboard)UnoRuntime.queryInterface(XClipboard.class, oClipboard);
  //--------------------------------------------------- 
  // becoming a clipboard owner 
  //---------------------------------------------------
  System.out.println("Becoming a clipboard owner..."); 
  System.out.println("");
  ClipboardOwner aClipOwner = new ClipboardOwner();  
 
  xClipboard.setContents(new TextTransferable("Hello World!"), aClipOwner);
  while (aClipOwner.isClipboardOwner()) 
  {  
          System.out.println("Still clipboard owner...");  
          Thread.sleep(1000); 
  }
  ...
Becoming a Clipboard Viewer

It is useful to listen to clipboard changes. User interface controls may change their visible appearance depending on the current clipboard content. To avoid polling on the clipboard, the clipboard service supports an asynchronous notification mechanism. Every client that needs notification about clipboard changes implements the interface com.sun.star.datatransfer.clipboard.XClipboardListener and registers as a clipboard listener. Implementing the interface com.sun.star.datatransfer.clipboard.XClipboardListener is simple as the next Java example demonstrates.

  //---------------------------- 
  // A simple clipboard listener 
  //----------------------------
  public class ClipboardListener implements XClipboardListener 
  {   
          public void disposing(EventObject event)  
          {
          }   
 
          public void changedContents(ClipboardEvent event)  
          {   
                  System.out.println(""); 
                  System.out.println("Clipboard content has changed!");
                  System.out.println("");  
           }
  }

If the interface was implemented by the object, it registers as a clipboard listener. A clipboard listener deregisters if clipboard notifications are no longer necessary. Both aspects are demonstrated in the next example.

  // instantiate the clipboard service
  Object oClipboard =  
          xMultiComponentFactory.createInstanceWithContext(  
          "com.sun.star.datatransfer.clipboard.SystemClipboard",
          xComponentContext);
  // query for the interface XClipboard 
  XClipboard xClipboard = (XClipboard)  
          UnoRuntime.queryInterface(XClipboard.class, oClipboard);
  //--------------------------------------------------- 
  // registering as clipboard listener 
  //---------------------------------------------------
  XClipboardNotifier xClipNotifier = (XClipboardNotifier)  
          UnoRuntime.queryInterface(XClipboardNotifier.class, oClipboard);
  ClipboardListener aClipListener= new ClipboardListener();
  xClipNotifier.addClipboardListener(aClipListener);
  ...
  //--------------------------------------------------- 
  // unregistering as clipboard listener 
  //---------------------------------------------------
  xClipNotifier.removeClipboardListener(aClipListener);
  ...

Apache OpenOffice Clipboard Data Formats

This section describes common clipboard data formats that Apache OpenOffice supports and their corresponding DataType.

As previously mentioned, data formats are described by DataFlavors. The important characteristics of a DataFlavor are the MimeType and DataType. The Apache OpenOffice clipboard service uses a standard MimeType for different data formats if there is one registered at Iana. For example, for HTML text, the MimeType "text/html" is used, Rich Text uses the MimeType "text/richtext", and text uses "text/plain". If there is no corresponding MimeType registered at Iana, Apache OpenOffice defines a private MimeType. Private Apache OpenOffice MimeType always has the MimeType "application/x-openoffice". Each private Apache OpenOffice MimeType has a parameter "windows_formatname" identifying the clipboard format name used under Windows. The used Windows format names are the format names used with older Apache OpenOffice versions. Common Windows format names are "Bitmap", "GDIMetaFile", "FileName", "FileList", and "DIF". The DataType of a DataFlavor identifies how the data are exchanged. There are only two DataTypes that can be used. The DataType for Unicode text is a string, and in Java, String.class, For all other data formats, the DataType is a sequence of bytes in Java byte[].class.

The following table lists common data formats, and their corresponding MimeType and DataTypes:

Form MimeType DataType (in Java) Description
Unicode Text text/plain;charset=utf-16 String.class Unicode Text
Richtext text/richtext byte[].class Richtext
Bitmap application/x-openoffice;windows_formatname="Bitmap" byte[].class A bitmap in OpenOffice bitmap format.
HTML Text text/html byte[].class HTML Text
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages