The Clipboard: 3.5 Using The Clipboard: Handling Paste

ClipboardRequestItemFormat(), MSG_META_CLIPBOARD_PASTE

The Paste operation pulls data off the Clipboard and places it at the insertion point in the application's data. The Clipboard remains unchanged throughout the operation; the data is simply duplicated and passed on to the application.

The steps in handling a MSG_META_CLIPBOARD_PASTE are simple; each is enumerated below, and a sample method for pasting is shown in MSG_META_CLIPBOARD_PASTE .

Query the Clipboard
First, you must make sure that you have exclusive access to the clipboard item. To this end call ClipboardQueryItem() . You should also call ClipboardRequestItemFormat() to make sure that the present clipboard item is pasteable.
Allocate memory if necessary
If necessary, allocate the memory into which the transfer item will be duplicated. You can not simply reference handles to the transfer item in the clipboard because the transfer item may be changed by another thread at any time.
Lock the Transfer VM File and grab the transfer item
Lock the Transfer VM File with a call to ClipboardRequestItemFormat() . Finally, copy the transfer item into your pre-allocated memory.
Unlock the Transfer VM File
By calling ClipboardDoneWithItem() , relinquish your exclusive access to the Transfer VM File and to the clipboard item itself. The Paste operation can then be completed entirely by your application by assimilating the pasted data and displaying it properly.

Code Display 7-9 MSG_META_CLIPBOARD_PASTE

/* This message handler goes through the necessary steps to grab the transfer item
 * from the Clipboard and copy it into application's memory. This example uses a
 * single global variable called textHandle, a memory handle of the only data block
 * owned by the application. The memory block contains text.
 * MSG_META_CLIPBOARD_PASTE has no parameters and requires no return value. */

@method ClipSampProcessClass, MSG_META_CLIPBOARD_PASTE {
    ClipboardQueryArgs				query;		/* returned by
						 * ClipboardQueryItem() */
    ClipboardRequestArgs 				request;		/* returned by
						 * ClipboardRequestItemFormat() */
    TextTransferBlockHeader				*dataBlock		/* pointer to block header */
    MemHandle				dataBlockMemHandle; /* handle of locked block */
    word				charsAvail;		/* number of chars in block */
    int				textLength;		/* length of text */
    word				transferFlags = 0; /* flags for the transfer
						 * (normal transfer) */

	    /* Call ClipboardQueryItem() to be sure that a normal
	     * transfer item exists in the Clipboard. */
    ClipboardQueryItem(transferFlags, &query);
					/* Fills ClipboardQueryArgs structure */

	    /* If a transfer item exists, check for a CIF_TEXT
	     * version, the only format we support. */
    if (query.CQA_numFormats) {				/* if more than zero formats available */
       if (ClipboardTestItemFormat(query.CQA_header,
					FormatIDFromManufacturerAndType(
							MANUFACTURER_ID_ME,
							CIF_TEXT))) {

	/* A CIF_TEXT version exists. Now we grab that transfer item by calling
	 * ClipboardRequestItemFormat(). This routine fills ClipboardRequestArgs,
	 * which contains information about the Transfer VM File and the
	 * ClipboardItemHeader block in that file. */

	    ClipboardRequestItemFormat(FormatIDFromManufacturerAndType(
					MANUFACTURER_ID_ME, CIF_TEXT),
					query.CQA_header, &request);

	/* Now we have the VM file handle of the Transfer VM File and the VM block
	 * handle of the ClipboardItemHeader structure. From this we can get the
	 * data in the data block. To speed things up, we will copy the transfer
	 * text directly into our already-allocated memory block; the handle to our
	 * memory block is in textHandle. */

	dataBlock = (TextTransferBlockHeader *)VMLock(
				request.CRA_file,
				VMCHAIN_GET_VM_BLOCK(request.CRA_data),
				&dataBlockMemHandle);
	textHugeArray = VMCHAIN_GET_VM_BLOCK(dataBlock->TTBH_text);
	VMUnlock(dataBlockMemHandle);

	/* Since the data is CIF_TEXT, we know the data block is in the format of
	 * TextTransferBlockHeader. We get the text by cycling through the
	 * format's HugeArray. This code has been taken out of this example for
	 * simplicity; you can look at the ClipSamp sample application source
	 * code for it. */
    }

    /* After copying the text into our block, we signal we're done with the
     * transfer file. We do this by calling ClipboardDoneWithItem(). After
     * that, we update our view and return. */

    ClipboardDoneWithItem(query.CQA_header);
    ResetViewArea();				/* Routine defined in ClipSamp. */
}

GEOS SDK TechDocs |

3.4 Handling Cut and Copy | Next:

3.6 Unregistering with the Clipboard