Difference between revisions of "Documentation/DevGuide/OfficeDev/Common Application Features"
m (1 revision(s)) |
m |
||
Line 36: | Line 36: | ||
The following Java example demonstrates the use of the clipboard service to paste from the clipboard. <!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | The following Java example demonstrates the use of the clipboard service to paste from the clipboard. <!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | ||
− | + | <source lang="java"> | |
import com.sun.star.datatransfer.*; | import com.sun.star.datatransfer.*; | ||
import com.sun.star.datatransfer.clipboard.*; | import com.sun.star.datatransfer.clipboard.*; | ||
Line 103: | Line 103: | ||
... | ... | ||
− | + | </source> | |
===== Copying Data ===== | ===== Copying Data ===== | ||
Line 110: | Line 110: | ||
The following Java example demonstrates the implementation of a transferable object. This transferable object contains only one format, unicode text. | The following Java example demonstrates the implementation of a transferable object. This transferable object contains only one format, unicode text. | ||
<!--[SOURCE:OfficeDev/Clipboard/TextTransferable.java]--> | <!--[SOURCE:OfficeDev/Clipboard/TextTransferable.java]--> | ||
− | + | <source lang="java"> | |
//--------------------------------------- | //--------------------------------------- | ||
// A simple transferable containing only | // A simple transferable containing only | ||
Line 149: | Line 149: | ||
private final String UNICODE_CONTENT_TYPE = "text/plain;charset=utf-16"; | private final String UNICODE_CONTENT_TYPE = "text/plain;charset=utf-16"; | ||
} | } | ||
− | + | </source> | |
Everyone providing data to the clipboard becomes a clipboard owner. A clipboard owner is an object that implements the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardOwner</idl>. 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. | Everyone providing data to the clipboard becomes a clipboard owner. A clipboard owner is an object that implements the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardOwner</idl>. 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. | All data types except for text have to be transferred as byte array. The next example shows this for a bitmap. | ||
− | + | <source lang="java"> | |
public class BmpTransferable implements XTransferable | public class BmpTransferable implements XTransferable | ||
{ | { | ||
Line 189: | Line 189: | ||
private final String BITMAP_CONTENT_TYPE = "application/x-openoffice;windows_formatname="Bitmap""; | private final String BITMAP_CONTENT_TYPE = "application/x-openoffice;windows_formatname="Bitmap""; | ||
} | } | ||
− | + | </source> | |
The following Java example shows an implementation of the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardOwner</idl>. | The following Java example shows an implementation of the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardOwner</idl>. | ||
<!--[SOURCE:OfficeDev/Clipboard/ClipboardOwner.java]--> | <!--[SOURCE:OfficeDev/Clipboard/ClipboardOwner.java]--> | ||
− | + | <source lang="java"> | |
... | ... | ||
Line 221: | Line 221: | ||
... | ... | ||
− | + | </source> | |
The last two samples combined show how it is possible to copy data to the clipboard as demonstrated in the following Java example. | The last two samples combined show how it is possible to copy data to the clipboard as demonstrated in the following Java example. | ||
<!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | <!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | ||
− | + | <source lang="java"> | |
import com.sun.star.datatransfer.*; | import com.sun.star.datatransfer.*; | ||
import com.sun.star.datatransfer.clipboard.*; | import com.sun.star.datatransfer.clipboard.*; | ||
Line 252: | Line 252: | ||
} | } | ||
... | ... | ||
− | + | </source> | |
===== Becoming a Clipboard Viewer ===== | ===== 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 <idl>com.sun.star.datatransfer.clipboard.XClipboardListener</idl> and registers as a clipboard listener. Implementing the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardListener</idl> is simple as the next Java example demonstrates. | 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 <idl>com.sun.star.datatransfer.clipboard.XClipboardListener</idl> and registers as a clipboard listener. Implementing the interface <idl>com.sun.star.datatransfer.clipboard.XClipboardListener</idl> is simple as the next Java example demonstrates. | ||
<!--[SOURCE:OfficeDev/Clipboard/ClipboardListener.java]--> | <!--[SOURCE:OfficeDev/Clipboard/ClipboardListener.java]--> | ||
− | + | <source lang="java"> | |
//---------------------------- | //---------------------------- | ||
// A simple clipboard listener | // A simple clipboard listener | ||
Line 274: | Line 274: | ||
} | } | ||
} | } | ||
− | + | </source> | |
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. | 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. | ||
<!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | <!--[SOURCE:OfficeDev/Clipboard/Clipboard.java]--> | ||
− | + | <source lang="java"> | |
// instantiate the clipboard service | // instantiate the clipboard service | ||
Object oClipboard = | Object oClipboard = | ||
Line 300: | Line 300: | ||
xClipNotifier.removeClipboardListener(aClipListener); | xClipNotifier.removeClipboardListener(aClipListener); | ||
... | ... | ||
− | + | </source> | |
==== {{PRODUCTNAME}} Clipboard Data Formats ==== | ==== {{PRODUCTNAME}} Clipboard Data Formats ==== | ||
Revision as of 17:19, 24 March 2008
- Common Application Features
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 OpenOffice.org custom components, or between custom components and external applications. It is usually used for copy and paste operations.
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 OpenOffice.org 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 OpenOffice.org Clipboard Data Formats, a list of common DataFlavors supported by OpenOffice.org is provided. |
HumanPresentableName | The human presentable name for the data format that this DataFlavor represents. |
DataType | The type of the data. In section OpenOffice.org Clipboard Data Formats there is a list of common DataFlavors supported by OpenOffice.org 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); ...
OpenOffice.org Clipboard Data Formats
This section describes common clipboard data formats that OpenOffice.org 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 OpenOffice.org 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, OpenOffice.org defines a private MimeType. Private OpenOffice.org MimeType always has the MimeType "application/x-openoffice
". Each private OpenOffice.org 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 OpenOffice.org 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). |