1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-8C94EE15-82EA-4A95-9044-C3404F95BD51" xml:lang="en"><title>Using

    13 Clipboard</title><shortdesc>Clipboard allows applications to read and write data to and from

    14 a shared clipboard. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    15 <context>       <p>The clipboard is implemented as a direct file store, as

    16 defined in the File Store API. Data placed on the clipboard is in streams.

    17 Every data type placed on the clipboard is identified by a UID. The store

    18 has a stream dictionary to allow an application to retrieve the data by specifying

    19 its UID. </p> <p>The clipboard class, <xref href="GUID-9C1E9536-01E8-3C0E-B1C5-F0A597ED0CA3.dita"><apiname>CClipboard</apiname></xref>, provides

    20 operations to get the clipboard file store and stream dictionary. Applications

    21 then read or write data using the standard store and stream interfaces. It

    22 also provides special support for copying and pasting a <codeph>TReal</codeph> to

    23 and from the clipboard. </p> <p>To place data on the clipboard, construct

    24 a <codeph>CClipboard</codeph> object and prepare it for the data to be written,

    25 using the <codeph>NewForWritingLC()</codeph> static member function as illustrated

    26 in the following code fragment: </p> <codeblock id="GUID-9A1E8DF1-2BA9-5DFE-BFEA-749592A35E84" xml:space="preserve">CClipboard* cb = CClipboard::NewForWritingLC( fsSession );</codeblock> <p>The function requires a file server session. </p> <p>The file associated

    27 with the clipboard's store may or may not exist. If it already exists, any

    28 existing content is discarded; if the file does not exist, it is created.

    29 In either event, <codeph>NewForWritingLC()</codeph> results in an empty clipboard. </p> <p>Once

    30 the <codeph>CClipboard</codeph> object has been created, data is stored into

    31 the clipboard 's store. Both the store (<codeph>CStreamStore</codeph>) and

    32 the stream dictionary (<codeph>CStreamDictionary</codeph>), which the example

    33 needs to access, are encapsulated by <codeph>CClipboard</codeph>. The class,

    34 therefore, provides the <codeph>Store()</codeph> and <codeph>StreamDictionary()</codeph> member

    35 functions to return suitable references. </p>      </context>

    36 <steps-unordered>

    37 <step id="GUID-4A467DE0-7F8F-4F49-BFA6-90A6BA1DCF73"><cmd><b>Creating the

    38 data for the clipboard</b>.</cmd>

    39 <substeps id="GUID-D2D6C0A3-9B55-4CBC-8650-9CAB416C5C38">

    40 <substep id="GUID-B6BE715A-6282-4161-93AF-1E5B9CCC09E0"><cmd>Prepare a new

    41 stream for writing using the <codeph>CreateLC()</codeph> member function of <codeph>RStoreWriteStream</codeph>. </cmd>

    42 <info><p>The CClipboard's store is to contain the new stream and so <codeph>cb-&gt;Store()</codeph> is

    43 passed as a parameter to <codeph>CreateLC()</codeph>. The item object is externalised.

    44 The stream is committed.   The resulting <codeph>streamId</codeph> and the <codeph>UID</codeph>,

    45 which identifies the data type, i.e. stid and <codeph>KExampleClipUid</codeph>,

    46 respectively, are placed in the stream dictionary using the stream dictionary's <codeph>AssignL()</codeph> member

    47 function.  </p></info>

    48 </substep>

    49 <substep id="GUID-513EA674-9E19-4020-AA8F-5C7E88221400"><cmd>Conclude by calling <codeph>CClipboard's

    50 CommitL()</codeph> member function to store the dictionary store as the root

    51 stream of the store and to commit all changes to the store.</cmd>

    52 <info><p>Deleting the <codeph>CClipboard</codeph> object causes the file associated

    53 with the clipboard's store to be closed, allowing other applications to access

    54 it.  </p></info>

    55 </substep>

    56 </substeps>

    57 </step>

    58 <step id="GUID-2F30C4DD-1601-4D67-B18B-50F52DD211C0"><cmd><b>Pasting the data

    59 from clipboard </b></cmd>

    60 <info><p>To attempt to retrieve data from the clipboard, construct a <codeph>CClipboard</codeph> object

    61 and prepare it for reading using either <codeph>NewForReadingL()</codeph> or <codeph>NewForReadingLC()</codeph>.</p><codeblock xml:space="preserve">// Create clipboard object

    62 TRAPD( ret,cb=CClipboard::NewForReadingL( fsSession ) );

    63 CleanupStack::PushL( cb );

    64 _LIT( KNoPaste,"Nothing to paste" );

    65 if ( ret!=KErrNone )

    66     {

    67     doShow( KNoPaste,NULL );

    68     User::Leave( ret );

    69     }

    70 // Get stream from store

    71 TStreamId stid = ( cb->StreamDictionary() ).At( KExampleClipUid );

    72 if ( stid == KNullStreamId )

    73     {

    74     doShow( KNoPaste,NULL );

    75     User::Leave( 0 );

    76     }

    77 // Read stream

    78 RStoreReadStream stream;

    79 stream.OpenLC( cb->Store(),stid );

    80 stream &gt;&gt; *item;</codeblock></info>

    81 </step>

    82 <step id="GUID-0780BA8D-A141-4061-B5D1-BE9F73C3B349"><cmd><b>Copying and pasting

    83 real numbers</b> </cmd>

    84 <info><p>Use <codeph>CopyToL( TReal )</codeph> to place a <codeph>TReal</codeph> on

    85 the clipboard and use <codeph>PasteFromL( TReal&amp; )</codeph> to fetch a <codeph>TReal</codeph> from

    86 the clipboard, if there is any data.</p><p> Applications that use these functions

    87 to copy and paste <codeph>TReal</codeph> objects need not concern themselves

    88 with the UID used to identify the corresponding stream in the clipboard store.</p><p> It

    89 must be noted that applications which use <codeph>CopyToL( TReal )</codeph>,

    90 must still call <codeph>CClipboard's CommitL()</codeph> member function before

    91 deleting the <codeph>CClipboard</codeph> object.  </p></info>

    92 </step>

    93 </steps-unordered>

    94 <example><p>Following is an example on how to create data for clipboard. In

    95 this example, the data to be placed on the clipboard's store is a single object

    96 item:</p><codeblock xml:space="preserve">RStoreWriteStream  stream;

    97 TStreamId stid = stream.CreateLC( cb->Store() );

    98 stream << *item;

    99 stream.CommitL();

   100 ( cb->StreamDictionary() ).AssignL( KExampleClipUid,stid );

   101 CleanupStack::PopAndDestroy(); // stream

   102 cb->CommitL();

   103 CleanupStack::PopAndDestroy(); // cb</codeblock></example>

   104 </taskbody></task>