<html>
<head>
  <title>Clipboard handling</title>
</head>
<body bgcolor="white" text="black">
<h1 align="center">Clipboard handling</h1>

<p>The clipboard protocol (Acorn application note 240) is implemented in the file 'c.Task'. It will require that you put <code>EMsg_ClaimEntity</code> and <code>EMsg_DataRequest</code> in the list of messages accepted by your application.</p>

<p>The clipboard is an arbitrary data structure managed independently from
your documents data and the task framework will handle most of the work,
including the exchange of messages between you and other clipboard aware
applications. However there are 4 operations that the framework cannot do
itself:</p>

<ul>
  <li>memory allocation/copy of the data into the clipboard</li>
  <li>memory deallocation/destruction of the data contained into the clipboard when the clipboard is released to another application or when new data is going to be put into the clipboard</li>
  <li>determination of the format (filetype) into which the data will be delivered to other applications.</li>
  <li>transfer of the clipboard data to another application.</li>
</ul>

<p>For the framework to work correctly you will have to define a <code>ClipboardHandler</code> structure composed of 4 pointers to the functions the framework will have to call to do the job:</p>

<ul>
  <li>The <code>Clipboard_FillContents</code> type function is called within Clipboard_Claim: it receives a pointer to the description of the data to copy into the clipboard, should allocate the required memory, copy the data and return a pointer to the allocated data.</li>
  <li>The <code>Clipboard_FreeContents</code> type function is called within Clipboard_Release: it receives the pointer to the clipboard data returned by the <code>Clipboard_FillContents</code> type function and should free all the allocated memory.</li>
  <li>The <code>XFer_SetSaveType</code> type function is called when someone ask the contents of the clipboard to be returned in one of a given list of formats, it should return one of the format from the list that it supports or when it don't support any format from the list its own preferred format.</li>
  <li>The <code>XFer_SendProc</code> type function is called when someone ask the contents of the clipboard and should return the pointer and size of the next data chunk to transfer (see the XFer documentation for details).</li>
</ul>

<h2 align="left">Interface description<h2>

<h3 align="left">Clipboard_Claim</h3>

<p>To put some data into the clipboard you just call Clipboard_Claim giving as parameter pointers to a ClipboardHandler structure and to the data to copy into the clipboard.</p>

<ul>
<li>It tells other tasks that they don't own the clipboard anymore,</li>
<li>clears the contents of the clipboard if the task already owned it,</li>
<li>fill the contents of the clipboard with the new data.</li>
</ul>

<h3 align="left">Clipboard_Paste</h3>

<p>This function asks the clipboard owner to send us the contents of the clipboard in one of the formats from the given list. The contents is sent via a simulated DataSave protocol.</p>

<ul>
<li>It broadcasts a message requesting the clipboard owner to initiate a data save via Message_DataSave to a given window, icon (or user handle), mouse position and one of the formats from the list.</li>
<li>It returns the reference of our message as the Message_DataSave replied by the clipboard owner will use this reference.</li>
</ul>

<p>The window handler for the given window will receive the Message_DataSave and can treat it as usually unless the icon field was used to put a user handle in which case it will have to check for non-zero references in the message to distinguish clipboard generated messages from normal ones.</p>

<h3 align="left">Clipboard_AllowPaste</h3>

<p>Checks that there is some data available in the appropriate format into the clipboard. If our task owns the clipboard this call sends a Message_DataRequest and Wimp_Polls for the answer. This leads to problems while processing a Message_MenuWarning because the Wimp expects you to open the submenu before the next Wimp_Poll. To go around this, call Clipboard_AllowPaste before opening the main menu with send = true to let the framework memorise the return value when the clipboard is owned by another task. Then on Message_MenuWarning only call Clipboard_AllowPaste with send = false which will return the memorised value if you don't own the clipboard (the value will be updated correctly if you choose Cut/Copy in the menu with a right button click and became owner of the clipboard inbetween the successive displays of the submenu).</p>

<h3 align="left">Clipboard_Release</h3>

<p>Clears the contents of the clipboard if we owned it. Normally only used by the framework.</p>

<h3 align="left">Clipboard_ClaimCaret/ClaimSelection</h3>

<p>Informs the other tasks that we claim the caret/selection so that they can hide (or shade) their representation of carets and selections. I have never used that part of the protocol.</p>

</body>
</html>