[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Widget Writer's Guide

XmeStandardConvert

A toolkit function that converts selections to standard targets

Format

#include <Xm/TransferP.h>
void XmeStandardConvertWidget
widgetXtPointer
ignoreXmConvertCallbackStruct
*call_data

DESCRIPTION

XmeStandardConvert converts a selection to one of a set of standard targets. This function can be called only from an XmNconvertCallback procedure or from a convertProc trait method.

The target to which this routine tries to convert the selection is the target member of the XmConvertCallbackStruct passed in the call_data argument. If XmeStandardConvert converts the selection to that target, it fills in the value, type, format, and length members of the XmConvertCallbackStruct. Otherwise, it does not alter the callback struct.

Note that XmeStandardConvert does not alter the status member of the XmConvertCallbackStruct. The routine that calls XmeStandardConvert is responsible for looking at the value parameter and determining whether or not the conversion succeeded. If the value parameter contains NULL, then the conversion did not succeed.

Following are the targets to which XmeStandardConvert converts selections:

BACKGROUND
The routine sets the value member of the XmConvertCallbackStruct to the value of widget widget's XmNbackground resource. The routine sets the format member to 32, the length member to 1, and the type member to PIXEL.

CLASS
The routine finds the first shell in the widget widget's hierarchy that has a WM_CLASS property. The properties of this shell determine the value, format, length, and type members of the XmConvertCallbackStruct.

CLIENT_WINDOW
The routine finds the first shell in the widget widget's hierarchy. The routine sets the value member of the XmConvertCallbackStruct to the widget ID of this shell. This routine sets the format member to 32, the length member to 1, and the Vype member to WINDOW.

COLORMAP
The routine sets the value member of the XmConvertCallbackStruct to the value of widget widget's XmNcolormap resource (or to the value of the XmNcolormap resource of widget widget's parent, if widget is a gadget). This routine sets the format member to 32, the length member to 1, and the type member to COLORMAP.

FOREGROUND
The routine sets the value member of the XmConvertCallbackStruct to the value of widget widget's XmNforeground resource. The routine sets the format member to 32, the length member to 1, and the type member to PIXEL.

NAME
The routine finds the first shell in widget widget's hierarchy that has a WM_NAME property. The properties of this shell determine the Vvalue. This routine sets the format member to 8, the length member to the number of characters in value, and the type member to the current locale.

TARGETS
The routine sets the value member of the XmConvertCallbackStruct to the list of targets returned by XmeStandardTargets. This routine sets the format member to 32, the length member to the number of targets in the list, and the type member to ATOM.

_MOTIF_RENDER_TABLE
The routine sets the value member of the XmConvertCallbackStruct to the value of the widget widget's XmNrenderTable resource if it exists, or else the default text render table. More precisely, the value member will hold a string of characters representing the render table. This routine sets the format member to 8, the length member to the number of characters in the value member, and the type member to STRING.

_MOTIF_ENCODING_REGISTRY
The routine transfers the widget's encoding registry. The routine sets the value member of the XmConvertCallbackStruct to a list of NULL-separated items in the form of tag encoding pairs. This target symbolizes the transfer target for the Motif Segment Encoding Registry. Widgets and applications can use this Registry to register text encoding formats for specified render table tags. Applications access this Registry by calling XmRegisterSegmentEncoding and XmMapSegmentEncoding. This routine sets the format member to 8, the length member to the number of characters in the value member, and the type member to STRING.

Following are the arguments to this function:

widget
Specifies the reference widget for the conversion.

ignore
This argument is ignored. Its value should always be NULL.

call_data
Specifies a pointer to the XmConvertCallbackStruct to be modified. XmeStandardConvert modifies the following members of the structure only. (For details on XmConvertCallbackStruct, see XmPrimitive(3) in the Motif Programmer's Reference.)

value
An XtPointer parameter that contains any data that XmeStandardConvert produces as a result of the conversion. XmeStandardConvert sets value to NULL if it cannot convert the target.

type
An Atom parameter that indicates the type of the data in the value member.

format
An int parameter that specifies whether the data in value should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities.

length
An unsigned long parameter that specifies the number of elements of data in value, where each element has the number of bits specified by format.

RELATED

XmQTtransfer(3), XmTransferDone(3), XmTransferValue(3), XmeClipboardSink(3), XmeClipboardSource(3), XmeConvertMerge(3), XmeDragSource(3), XmeDropSink(3), XmeGetEncodingAtom(3), XmePrimarySink(3), XmePrimarySource(3), XmeSecondarySink(3), XmeSecondarySource(3), XmeSecondaryTransfer(3), XmeStandardTargets(3), and XmeTransferAddDoneProc(3).

[ Previous | Next | Contents | Glossary | Home | Search ]