Using Clipboard

Clipboard allows applications to read and write data to and from a shared clipboard.

Context

The clipboard is implemented as a direct file store, as defined in the File Store API. Data placed on the clipboard is in streams. Every data type placed on the clipboard is identified by a UID. The store has a stream dictionary to allow an application to retrieve the data by specifying its UID.

The clipboard class, CClipboard, provides operations to get the clipboard file store and stream dictionary. Applications then read or write data using the standard store and stream interfaces. It also provides special support for copying and pasting a TReal to and from the clipboard.

To place data on the clipboard, construct a CClipboard object and prepare it for the data to be written, using the NewForWritingLC() static member function as illustrated in the following code fragment:

CClipboard* cb = CClipboard::NewForWritingLC( fsSession );

The function requires a file server session.

The file associated with the clipboard's store may or may not exist. If it already exists, any existing content is discarded; if the file does not exist, it is created. In either event, NewForWritingLC() results in an empty clipboard.

Once the CClipboard object has been created, data is stored into the clipboard 's store. Both the store (CStreamStore) and the stream dictionary (CStreamDictionary), which the example needs to access, are encapsulated by CClipboard. The class, therefore, provides the Store() and StreamDictionary() member functions to return suitable references.

Steps

Creating the data for the clipboard.
1. Prepare a new stream for writing using the CreateLC() member function of RStoreWriteStream.
  
  The CClipboard's store is to contain the new stream and so cb->Store() is passed as a parameter to CreateLC(). The item object is externalised. The stream is committed. The resulting streamId and the UID, which identifies the data type, i.e. stid and KExampleClipUid, respectively, are placed in the stream dictionary using the stream dictionary's AssignL() member function.
2. Conclude by calling CClipboard's CommitL() member function to store the dictionary store as the root stream of the store and to commit all changes to the store.
  
  Deleting the CClipboard object causes the file associated with the clipboard's store to be closed, allowing other applications to access it.

Pasting the data from clipboard

To attempt to retrieve data from the clipboard, construct a CClipboard object and prepare it for reading using either NewForReadingL() or NewForReadingLC().

// Create clipboard object
TRAPD( ret,cb=CClipboard::NewForReadingL( fsSession ) );
CleanupStack::PushL( cb );
_LIT( KNoPaste,"Nothing to paste" );
if ( ret!=KErrNone )
    {
    doShow( KNoPaste,NULL );
    User::Leave( ret );
    }
// Get stream from store
TStreamId stid = ( cb->StreamDictionary() ).At( KExampleClipUid );
if ( stid == KNullStreamId )
    {
    doShow( KNoPaste,NULL );
    User::Leave( 0 );
    }
// Read stream
RStoreReadStream stream;
stream.OpenLC( cb->Store(),stid );
stream >> *item;

Copying and pasting real numbers

Use CopyToL( TReal ) to place a TReal on the clipboard and use PasteFromL( TReal& ) to fetch a TReal from the clipboard, if there is any data.
Applications that use these functions to copy and paste TReal objects need not concern themselves with the UID used to identify the corresponding stream in the clipboard store.
It must be noted that applications which use CopyToL( TReal ), must still call CClipboard's CommitL() member function before deleting the CClipboard object.

Example

Following is an example on how to create data for clipboard. In this example, the data to be placed on the clipboard's store is a single object item:

RStoreWriteStream  stream;
TStreamId stid = stream.CreateLC( cb->Store() );
stream << *item;
stream.CommitL();
( cb->StreamDictionary() ).AssignL( KExampleClipUid,stid );
CleanupStack::PopAndDestroy(); // stream
cb->CommitL();
CleanupStack::PopAndDestroy(); // cb