CLIPBOARD statement  

Purpose

Copy data to/from the Windows ClipBoard.

Syntax

CLIPBOARD GET BITMAP  TO ClipVar [, ClipResult]

CLIPBOARD GET OEMTEXT TO AnsiStrgVar [, ClipResult]

CLIPBOARD GET TEXT    TO StrgVar [, ClipResult]

CLIPBOARD GET UNICODE TO StrgVar [, ClipResult]

CLIPBOARD RESET [, ClipResult]

CLIPBOARD SET BITMAP  ClipHndl [, ClipResult]

CLIPBOARD SET OEMTEXT StrgExpr [, ClipResult]

CLIPBOARD SET TEXT    StrgExpr [, ClipResult]

CLIPBOARD SET UNICODE StrgExpr [, ClipResult]

ClipHndl

A Long Integer or Dword value which specifies the 32-bit handle of a GRAPHIC BITMAP passed to the clipboard.

ClipResult

A Long Integer or Dword variable which receives a true result (-1) if the operation was successful, or a false result (0) if it failed.

ClipVar

A Long Integer or Dword variable which receives a 32-bit handle of a newly created GRAPHIC BITMAP.

StrgExpr

A string expression which specifies data to be passed to the clipboard.

StrgVar

A string variable which receives string data from the clipboard.

Remarks

The Windows ClipBoard provides support for the transfer of various types of data between applications, or even different parts of a single application.  The concept is simple -- save some data on the ClipBoard and retrieve it later.  In most cases, it's just used to transfer plain text, so the PowerBASIC CLIPBOARD statement concentrates on the common data formats.  With text transfer, you can just read or write a string. With bitmaps, a GRAPHIC BITMAP is used for this purpose.

When you retrieve data using CLIPBOARD, the original copy always remains in the CLIPBOARD, so the operation can be repeated any number of times.  When you store data on the CLIPBOARD, your original copy remains unchanged.  The data is copied, with no change of ownership.

The clipboard can hold multiple data items, but only one of each data format at a time.  Generally speaking, multiple data items are only used to store a single piece of data in multiple formats to ensure it can be retrieved successfully later.  However, you should note that Windows automatically converts string data between TEXT, OEMTEXT, and UNICODE. When you store data in one of those forms, it's not necessary to repeat it with the others.

You must execute a CLIPBOARD RESET to empty the clipboard before storing new data items.

Each form of the CLIPBOARD statement offers an optional ClipResult variable.  If the requested operation is deemed successful by Windows, this variable is assigned the value TRUE (-1).  If it fails, the value FALSE (0) is assigned instead.  You should note that the success test is not a comprehensive one.  It tests only the operation, not the validity of the data.

There are nine general forms of the CLIPBOARD statement:

CLIPBOARD GET BITMAP TO ClipVar [, ClipResult]

A new GRAPHIC BITMAP is automatically created.  A Bitmap is copied from the ClipBoard and stored in this newly created GRAPHIC BITMAP.  The handle of the new GRAPHIC BITMAP is assigned to the ClipVar, a DWord or Long Integer variable.  If the operation is not successful, the value zero (0) is assigned instead.

CLIPBOARD GET OEMTEXT TO AnsiStrgVar [, ClipResult]

A text string is retrieved from the CLIPBOARD, and assigned to the ANSI string variable specified by AnsiStrgVar.  If necessary, it is converted to OEM Text format, the format used by the Windows Console.  If no text can be retrieved, a nul (zero-length) string is assigned instead.

CLIPBOARD GET TEXT TO StrgVar [, ClipResult]

A text string is retrieved from the CLIPBOARD, and assigned to the string variable specified by StrgVar, which may be ANSI or WIDE format.  If necessary, the text is automatically converted to match the format of the target variable.  If no text can be retrieved, a nul (zero-length) string is assigned instead.

CLIPBOARD RESET [, ClipResult]

The contents of the CLIPBOARD are deleted.

CLIPBOARD SET BITMAP  ClipHndl [, ClipResult]

A GRAPHIC BITMAP, specified by ClipHndl, is stored on the CLIPBOARD. The GRAPHIC BITMAP may be a GRAPHIC WINDOW or GRAPHIC BITMAP.

CLIPBOARD SET OEMTEXT StrgExpr [, ClipResult]

A text string, specified by StrExpr, is stored on the CLIPBOARD. The string data is assumed to use characters in the OEM character set.

CLIPBOARD SET TEXT StrgExpr [, ClipResult]

A text string, specified by StrExpr, is stored on the CLIPBOARD. The string data may be in either ANSI or WIDE format.

The following two functions, with UNICODE options, were specifically designed for older versions of PowerBASIC which did not support wide Unicode strings.  They may only be used with legacy programs which must store wide characters in an ANSI string variable.  They should be converted to the TEXT option with wide string variables as soon as possible, as these forms of CLIPBOARD will not be supported in future versions of PowerBASIC.

 

CLIPBOARD GET UNICODE TO AnsiStrgVar [, ClipResult]

A text string is retrieved from the CLIPBOARD, and assigned to the ANSI string variable specified by AnsiStrgVar.  Even though the string variable uses 1-byte ANSI characters, the data is represented as 2-byte wide Unicode characters.  If no text can be retrieved, a nul (zero-length) string is assigned instead.

CLIPBOARD SET UNICODE AnsiStrgExpr [, ClipResult]

A UniCode text string, stored in ANSI variables and constants, is stored on the CLIPBOARD.