DwtClipboardRegisterFormat(3Dwt)

Name

DwtClipboardRegisterFormat − Registers the length of the data for formats not specified by ICCCM conventions.

Syntax

int DwtClipboardRegisterFormat(display, format_name,
                                  format_length)
     Display *display;
     char * format_name;
     unsigned long format_length;

Arguments

displaySpecifies a pointer to the Display structure that was returned in a previous call to XOpenDisplay. For information on XOpenDisplay and the Display structure, see the Guide to the Xlib Library: C Language Binding.

format_name
Specifies a name string for the format. See the table of Data Format Names for the formats defined by ICCCM conventions.

format_length
Specifies the format length in bits: 8, 16, or 32.

Description

The DwtClipboardRegisterFormat function allows an application to register the data length for formats not specified by the ICCCM conventions. Failure to register the length of the data results in applications being incompatible across platforms that have different byte-swapping orders.

The following table lists the formats defined by the conventions:

Format Name	Format Length	Description
TARGETS	32	List of valid target atoms
MULTIPLE	32	Look in the ConvertSelection property
TIMESTAMP	32	Timestamping used to acquire selection
STRING	8	ISO Latin 1 (+TAB+NEWLINE) text
TEXT	8	Text in owner’s encoding
LIST_LENGTH	32	Number of disjoint parts of selection
PIXMAP	32	Pixmap ID
DRAWABLE	32	Drawable ID
BITMAP	32	Bitmap ID
FOREGROUND	32	Pixel value
BACKGROUND	32	Pixel value
COLORMAP	32	Colormap ID
ODIF	8	ISO Office Document Interchange Format
OWNER_OS	8	Operating system of owner
FILE_NAME	8	Full path name of a file
HOST_NAME	8	See WM_CLIENT_MACHINE
CHARACTER_POSITION	32	Start and end of selection in bytes
LINE_NUMBER	32	Start and end line numbers
COLUMN_NUMBER	32
LENGTH	32	Number of bytes in selection
USER	8	Name of user running owner
PROCEDURE	8	Name of selected procedure
MODULE	8	Name of selected module
PROCESS	32 or 8	Process ID of owner
TASK	32 or 8	Task ID of owner
CLASS	8	Class of owner−See WM_CLASS
NAME	8	Name of owner−See WM_NAME
CLIENT_WINDOW	32	Top-level window of owner

For information on the built-in selection property names WM_CLIENT_MACHINE, WM_CLASS, and WM_NAME, see the Guide to the Xlib Library: C Language Binding.

Return Value

This function returns one of these status return constants:

ClipboardSuccess	The function is successful.
ClipboardLocked	The function failed because the clipboard was locked by another application. The application can continue to call the function with the same parameters until the clipboard is unlocked. Optionally, the application can ask if the user wants to keep trying or to give up on the operation.
ClipboardBadFormat	The function failed because the format_name or format_length was inappropriate. A NULL format_name or a format_length other than 8, 16, or 32, for example, would be inappropriate.
ClipboardFail	The function failed because the application tried to redefine a predefined format. See the table of Data Format Names for the predefined formats.