Clipboard

Typedefs
typedef BentleyStatus(*	ClipboardFunc_Changed )(int *numResponses, ClipboardResponse *clipboardResponseP, ClipboardFormatInfo *clipboardInfoP, int numFormats)
	UserFunction called for events related to the windows clipboard. More...

Functions
static ClipboardFunc_Changed	SetPasteFunction (ClipboardFunc_Changed newCallback)
	An MDL application can use this to set a function to be called when the windows clipboard changes. More...
static ClipboardFunc_Changed	SetCutFunction (ClipboardFunc_Changed newCallback)
	An MDL application can use this to set a function to be called when a MicroStation user clicks on the Edit menu option. More...
static ClipboardFunc_Changed	SetCopyFunction (ClipboardFunc_Changed newCallback)
	An MDL application can use this to set a function to be called when a MicroStation user clicks on the Edit menu option. More...
void *	mdlClipboard_getClipboardData (UInt32 format)
	The mdlClipboard_getClipboardData function retrieves a data handle or buffer to the current clipboard data having a specified format. More...
UInt	mdlClipboard_getClipboardFormatName (UInt wFormat, WStringR clipboardFormatName)
	The mdlClipboard_getClipboardFormatName function retrieves from the clipboard the name of the specified registered format. More...
StatusInt	mdlClipboard_emptyClipboard ()
	The mdlClipboard_emptyClipboard function empties the clipboard. More...
UInt	mdlClipboard_registerClipboardFormat (WCharCP clipboardFormatName)
	The mdlClipboard_registerClipboardFormat function registers a new clipboard format name. More...
void *	mdlClipboard_setClipboardData (UInt32 clipboardFormat, void const *clipboardData, size_t clipboardDataLen)
	The mdlClipboard_setClipboardData function adds or replaces the specified data format to the clipboard. More...
UInt	mdlClipboard_openClipboard ()
	mdlClipboard_openClipboard opens the Windows clipboard for examination by your application and prevents other applications from changing the clipboard contents. More...
UInt	mdlClipboard_closeClipboard ()
	mdlClipboard_closeClipboard releases your MDL application's exclusive lock on the Windows Clipboard. More...

Detailed Description

Typedef Documentation

typedef BentleyStatus(* ClipboardFunc_Changed)(int *numResponses, ClipboardResponse *clipboardResponseP, ClipboardFormatInfo *clipboardInfoP, int numFormats)

UserFunction called for events related to the windows clipboard.

See also

ClipboardCallback::SetPasteFunctionC ClipboardCallback::SetCutFunctionC ClipboardCallback::SetCopyFunctionC

Function Documentation

UInt mdlClipboard_closeClipboard

(

)

mdlClipboard_closeClipboard releases your MDL application's exclusive

lock on the Windows Clipboard.

You must call this function after each call to mdlClipboard_openClipboard.

Returns

mdlClipboard_openClipboard and mdlClipboard_closeClipboard return SUCCESS if they are successful or ERROR if an error occurs.

See also

mdlClipboard_emptyClipboard mdlClipboard_setClipboardData

Remarks

Required Library: mdlbltin.lib

StatusInt mdlClipboard_emptyClipboard

(

)

The mdlClipboard_emptyClipboard function empties the clipboard.

All data objects in the clipboard are discarded. This function is typically called before one or more mdlClipboard_setClipboardData functions are called. It is bad practice to add data to the clipboard without first clearing the existing contents of the clipboard.

Returns

mdlClipboard_emptyClipboard returns SUCCESS if the functions is successful or ERROR if an error occurs.

See also

mdlClipboard_openClipboard mdlClipboard_closeClipboard mdlClipboard_setClipboardData

Remarks

Required Library: mdlbltin.lib

void* mdlClipboard_getClipboardData

(

UInt32

format

)

The mdlClipboard_getClipboardData function retrieves a data handle or

buffer to the current clipboard data having a specified format.

The clipboard must have been opened previously.

Parameters

[in]

format

Clipboard format number

Remarks

It is the responsibility of the programmer to ensure that the memory allocated by this function is eventually freed.

Returns

mdlClipboard_getClipboardData returns a pointer to a data buffer or NULL if an errors occurs of the specified data format is unavailable.

See also

userClipboard_copyProcess userClipboard_cutProcess userClipboard_pasteProcess

Remarks

Required Library: mdlbltin.lib

UInt mdlClipboard_getClipboardFormatName	(	UInt	wFormat,
		WStringR	clipboardFormatName
	)

The mdlClipboard_getClipboardFormatName function retrieves from the

clipboard the name of the specified registered format.

The function copies the name to the specified buffer.

Parameters

[in]	wFormat	specifies the type of format to be retrieved. This parameter must not specify any of the predefined clipboard formats.
[out]	clipboardFormatName	The WString that receives the format name.

Returns

SUCCESS or ERROR if the requested format does not exist or is predefined.

Remarks

Required Library: mdlbltin.lib

UInt mdlClipboard_openClipboard

(

)

mdlClipboard_openClipboard opens the Windows clipboard for examination

by your application and prevents other applications from changing the clipboard contents.

Your application should call mdlClipboard_closeClipboard after it is finished processing the clipboard.

Returns

mdlClipboard_openClipboard and mdlClipboard_closeClipboard return SUCCESS if they are successful or ERROR if an error occurs.

See also

mdlClipboard_emptyClipboard mdlClipboard_setClipboardData

Remarks

Required Library: mdlbltin.lib

UInt mdlClipboard_registerClipboardFormat

(

WCharCP

clipboardFormatName

)

The mdlClipboard_registerClipboardFormat function registers a new clipboard

format name.

The registered format can be used in subsequent clipboard functions as a valid format in which to render or retrieve data. It is this name that other applications can identify the various data formats within the clipboard.

Parameters

[in]

clipboardFormatName

points to a NULL-terminated string that names the new format.

Remarks

The following table lists the standard Windows NT clipboard formats. These formats are predefined need not be registered.

Symbolic Name	Value	Meaning
CF_TEXT	1	Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A NULL character signals the end of the data.
CF_BITMAP	2	A handle of a bitmap.
CF_METAFILEPICT	3	Handle of a metafile picture format as defined by the METAFILEPICT structure.
CF_SYLK	4	Microsoft Symbolic Link (SYLK) format.
CF_DIF	5	The data is in Software Arts' Data Interchange Format.
CF_TIFF	6	Tag image file format (TIFF).
CF_OEMTEXT	7	Text format containing characters in the OEM character set. Each line ends with a carriage return/linefeed (CR-LF) combination. A NULL character signals the end of the data.
CF_DIB	8	The data is a memory block containing a BITMAPINFO structure followed by the bitmap data.
CF_PALETTE	9	Handle of a color palette. Whenever an application places data in the clipboard that depends on or assumes a color palette, it should place the palette in the clipboard as well. If the clipboard contains data in the CF_PALETTE (logical color palette) format, the application should select and realize any other data in the clipboard against that logical palette. When displaying clipboard data, Windows Clipboard always uses as its current palette any object on the clipboard that is in the CF_PALETTE format.
CF_PENDATA	10	Data for the pen extensions to the Windows operating system.
CF_RIFF	11	Represents audio data more complex than can be represented in a CF_WAVE standard wave format.
CF_WAVE	12	Represents audio data in one of the standard wave formats, such as 11 kHz or 22 kHz PCM.
CF_UNICODETEXT	13	Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A NULL character signals the end of the data.
CF_ENHMETAFILE	14	A handle of an enhanced metafile (HENHMETAFILE).

The following format numbers are defined for completeness but are not used for clipboard aware MDL applications:.

Symbolic Name	Value	Meaning
CF_OWNERDISPLAY	0x0080	Owner display format. The clipboard owner must display and update the clipboard viewer window, and receive the WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD and WM_VSCROLLCLIPBOARD messages. The data parameter must be NULL. This is not valid for MDL applications.
CF_DSPTEXT	0x0081	Text display format associated with a private format. The data is a handle of data that can be displayed in text format in lieu of the privately formatted data.
CF_DSPBITMAP	0x0082	Bitmap display format associated with a private format. The data parameter must be a handle of data that can be displayed in bitmap format in lieu of the privately formatted data.
CF_DSPMETAFILEPICT	0x0083	Metafile-picture display format associated with a private format. The value is a handle of data that can be displayed in metafile-picture format in lieu of the privately formatted data.
CF_DSPENHMETAFILE	0x008E	Enhanced metafile display format associated with a private format. The data must be a handle of data that can be displayed in enhanced metafile format in lieu of the privately formatted data.
CF_PRIVATELAST CF_PRIVATEFIRST	0x02FF 0x0200	Range of integer values for private clipboard formats. Handles associated with private clipboard formats are not freed automatically; the clipboard owner must free such handles. This format is not valid for MDL applications.

Remarks

Windows supports three clipboard formats for text: CF_UNICODETEXT, CF_TEXT and CF_OEMTEXT. Specify CF_TEXT for ANSI text, CF_UNICODETEXT for Unicode text, and CF_OEMTEXT for text in the OEM character set. If any of the three text formats is placed on the clipboard, all three can be retrieved by using the mdlClipboard_getClipboardData function. If necessary, Windows automatically converts data in an available text format to the requested format. An application can place more than one text format on the clipboard if it does so at one time (between the same calls to mdlClipboard_openClipboard and mdlClipboard_closeClipboard).

Windows supports two clipboard formats for metafiles: CF_ENHMETAFILE and CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and CF_METAFILEPICT for Windows metafiles. If either of the two metafile formats is placed on the clipboard, both can be retrieved by mdlGetClipboardData. If necessary, Windows automatically converts data in the available metafile format to the requested format. An application can place both metafile formats on the clipboard if it does so at one time (between the same calls to mdlClipboard_openClipboard and mdlClipboard_closeClipboard).

Returns

If the function succeeds, the return value identifies the registered clipboard format; otherwise, it is zero. If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format.

Remarks

Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF.

See also

mdlClipboard_setClipboardData mdlClipboard_getClipboardData

Remarks

Required Library: mdlbltin.lib

void* mdlClipboard_setClipboardData	(	UInt32	clipboardFormat,
		void const *	clipboardData,
		size_t	clipboardDataLen
	)

The mdlClipboard_setClipboardData function adds or replaces the specified

data format to the clipboard.

The clipboard must have been opened previously.

Parameters

[in]	clipboardFormat	specifies the format of the data. It can be any one of the system- defined clipboard formats, or a format registered by the mdlClipboard_registerClipboardFormat function.
[in]	clipboardData	specifies the data to be placed into the clipboard. This parameter must not be NULL and will be rejected if it is. If your application manages its own handle memory, you may place a handle to the data in this parameter.
[in]	clipboardDataLen	specifies the length in bytes of the above data buffer. If this parameter is -1 then the value of pClipboardData is treated as a handle and not an address. When this value is positive, the data buffer is copied into an allocated data handle.

Remarks

Private data formats in the range of CF_PRIVATEFIRST to CF_PRIVATELAST are not automatically freed when the data is deleted from the clipboard.

If the Windows clipboard application is running, it will not update its window to show the data placed in the clipboard by the SetClipboardData until after the mdlClipboard_closeClipboard function is called.

Returns

mdlClipboard_setClipboardData returns a pointer to a data buffer or NULL if an errors occurs of the specified data format is unavailable.

See also

userClipboard_copyProcess userClipboard_cutProcess userClipboard_pasteProcess mdlClipboard_closeClipboard mdlClipboard_openClipboard mdlClipboard_getClipboardData mdlClipboard_registerClipboardFormat

Remarks

Required Library: mdlbltin.lib

static ClipboardFunc_Changed SetCopyFunction ( ClipboardFunc_Changed  newCallback )

static

An MDL application can use this to set a function to be called when a MicroStation user clicks on the Edit menu option.

The specified function will be called synchronously.

Parameters

[in]

newCallback

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, or NULL.

Remarks

Once registered, the function will be called in all of the following circumstances:

When any MDL application registers a clipboard strategy routine.
When any MDL application unregistered a clipboard strategy routine.
When any MDL application that has a registered clipboard strategy routine is unloaded.
When a MicroStation user clicks on the Edit menu option.

See also

ClipboardFunc_Changed

static ClipboardFunc_Changed SetCutFunction ( ClipboardFunc_Changed  newCallback )

static

An MDL application can use this to set a function to be called when a MicroStation user clicks on the Edit menu option.

The specified function will be called synchronously.

Parameters

[in]

newCallback

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, or NULL.

Remarks

Once registered, the function will be called in all of the following circumstances:

When any MDL application registers a clipboard strategy routine.
When any MDL application unregistered a clipboard strategy routine.
When any MDL application that has a registered clipboard strategy routine is unloaded.
When a MicroStation user clicks on the Edit menu option.

See also

ClipboardFunc_Changed

static ClipboardFunc_Changed SetPasteFunction ( ClipboardFunc_Changed  newCallback )

static

An MDL application can use this to set a function to be called when the windows clipboard changes.

The specified function will be called synchronously.

Parameters

[in]

newCallback

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, or NULL.

Remarks

Once registered, the function will be called in all of the following circumstances:

When any MDL application registers a clipboard strategy routine.
When any MDL application unregistered a clipboard strategy routine.
When any MDL application that has a registered clipboard strategy routine is unloaded.
When the Windows clipboard changes (i.e., when a user copies or cuts something into the clipboard).

See also

ClipboardFunc_Changed