Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

ExmStringTransfer

The StringTransfer widget class

Format

#include <Exm/StringTrans.h>

DESCRIPTION

ExmStringTransfer is a demonstration widget. OSF provides this widget solely to teach programmers how to write their own Motif widgets. OSF does not support this widget in any way.

ExmStringTransfer is a subclass of ExmString. ExmStringTransfer inherits all the visuals of ExmString; therefore, ExmStringTransfer displays one compound string. Unlike ExmString, ExmStringTransfer supports data transfer. That is, a user can transfer data into or out of an ExmStringTransfer widget. In fact, the purpose of this widget is to demonstrate how to implement UTM data transfer in a widget.

ExmStringTransfer is an instantiable widget and can also used as a superclass for other widgets.

The ExmStringTransfer class installs the XmQTtransfer trait and implements this trait's convertProc and destinationProc trait methods.

ExmStringTransfer supports two callbacks:

XmNdestinationCallback, which allows applications to intercede a data transfer on behalf of the destination widget.

XmNconvertCallback, which allows applications to intercede a data transfer on behalf of the source widget. This resource is inherited from XmPrimitive.

Data Transfer Behavior

ExmStringTransfer can be the source or destination of a primary, clipboard, or drag and drop transfer. ExmStringTransfer does not support secondary transfers.

Unlike more sophisticated widgets such as XmText, a user cannot copy selected portions of an ExmStringTransfer. Instead, a user can only copy the entire compound string held by ExmNcompoundString, not a subset of it. Similarly, when an ExmStringTransfer is the destination, any text copied into it will overwrite all of the previous contents.

As a source of data, ExmStringTransfer supports the following targets and associated conversions of data to these targets:

locale

If the locale target matches the widget's locale, the widget transfers ExmNcompoundString in the encoding of the locale.

COMPOUND_TEXT

The widget transfers ExmNcompoundString as type COMPOUND_TEXT.

STRING

The widget transfers ExmNcompoundString as type STRING.

TEXT

If ExmNcompoundString is fully convertible to the encoding of the locale, the widget transfers the value as text in the encoding of the locale. Otherwise, the widget transfers the value as type COMPOUND_TEXT.

_MOTIF_CLIPBOARD_TARGETS

The widget transfers, as type ATOM, a list of the targets it supports for immediate transfer for the CLIPBOARD selection. These include _MOTIF_COMPOUND_STRING. If ExmNcompoundString is fully convertible to STRING, these also include STRING; otherwise, they also include COMPOUND_TEXT.

_MOTIF_COMPOUND_STRING

The widget transfers ExmNcompoundString as a compound string in byte stream format.

_MOTIF_EXPORT_TARGETS

The widget transfers, as type ATOM, a list of the targets to be used as the value of the DragContext's XmNexportTargets in a drag-and-drop transfer. These include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT, the encoding of the locale, STRING, TEXT, BACKGROUND, and FOREGROUND.

As a source of data, ExmStringTransfer also supports the following standard Motif targets:

BACKGROUND

The widget transfers XmNbackground as type PIXEL.

CLASS

The widget finds the first shell in the widget hierarchy that has a WM_CLASS property and transfers the contents as text in the current locale.

CLIENT_WINDOW

The widget finds the first shell in the widget hierarchy and transfers its window as type WINDOW.

COLORMAP

The widget transfers XmNcolormap as type COLORMAP.

FOREGROUND

The widget transfers XmNforeground as type PIXEL.

NAME

The widget finds the first shell in the widget hierarchy that has a WM_NAME property and transfers the contents as text in the current locale.

TARGETS

The widget transfers, as type ATOM, a list of the targets it supports. These include the standard targets in this list. These also include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT, the encoding of the locale, STRING, and TEXT.

TIMESTAMP

The widget transfers the timestamp used to acquire the selection as type INTEGER.

_MOTIF_RENDER_TABLE

The widget transfers XmNrenderTable if it exists, or else the default text render table, as type STRING.

As a destination for data, when ExmStringTransfer receives data that can be converted to a compound string, it sets ExmNcompoundString to the transferred compound string.

As a destination, ExmStringTransfer chooses a target and requests conversion of the selection to that target. If the encoding of the locale is present in the list of available targets, ExmStringTransfer chooses a requested target from the available targets in the following order of preference:

_MOTIF_COMPOUND_STRING

TEXT

COMPOUND_TEXT

The encoding of the locale

STRING

If the encoding of the locale is not present in the list of available targets, ExmStringTransfer chooses a requested target from the available targets in the following order of preference:

_MOTIF_COMPOUND_STRING

COMPOUND_TEXT

STRING

Classes

ExmStringTransfer inherits behavior and resources from Core, XmPrimitive, ExmSimple, and ExmString.

The class pointer is exmStringTransferWidgetClass.

The class name is ExmStringTransfer.

New Resources

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN, ExmN, XmC or ExmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm or Exm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the "Access" column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).

ExmStringTransfer Resource Set
Name	Class	Type	Default	Access
XmNdestinationCallback	XmCCallback	XtCallbackList	NULL	C

XmNdestinationCallback

Specifies a list of callbacks called when the widget is the destination of a transfer operation. The type of the structure whose address is passed to these callbacks is XmDestinationCallbackStruct. The reason is XmCR_OK.

Inherited Resources

ExmStringTransfer inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the reference page for that superclass.

ExmString Resource Set
Name	Class	Type	Default	Access
ExmNcompoundString	ExmCCompoundString	XmString	NULL	CSG
XmNalignment	XmCAlignment	unsigned char	XmALIGNMENT_CENTER	CSG
XmNrecomputeSize	XmCRecomputeSize	Boolean	True	CSG
XmNrenderTable	XmCRenderTable	XmRenderTable	dynamic	CSG

ExmSimple Resource Set
Name	Class	Type	Default	Access
ExmNsimpleShape	ExmCSimpleShape	unsigned char	ExmSHAPE_OVAL	CSG
XmNmarginHeight	XmCMarginHeight	Dimension	4	CSG
XmNmarginWidth	XmCMarginWidth	Dimension	4	CSG

XmPrimitive Resource Set
Name	Class	Type	Default	Access
XmNbottomShadowColor	XmCBottomShadowColor	Pixel	dynamic	CSG
XmNbottomShadowPixmap	XmCBottomShadowPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNconvertCallback	XmCCallback	XtCallbackList	NULL	C
XmNforeground	XmCForeground	Pixel	dynamic	CSG
XmNhelpCallback	XmCCallback	XtCallbackList	NULL	C
XmNhighlightColor	XmCHighlightColor	Pixel	dynamic	CSG
XmNhighlightOnEnter	XmCHighlightOnEnter	Boolean	False	CSG
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNhighlightThickness	XmCHighlightThickness	Dimension	2	CSG
XmNlayoutDirection	XmCLayoutDirection	XmDirection	dynamic	CG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmNONE	CSG
XmNpopupHandlerCallback	XmCCallback	XtCallbackList	NULL	C
XmNshadowThickness	XmCShadowThickness	Dimension	2	CSG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	True	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG

Core Resource Set
Name	Class	Type	Default	Access
XmNaccelerators	XmCAccelerators	XtAccelerators	dynamic	CSG
XmNancestorSensitive	XmCSensitive	Boolean	dynamic	G
XmNbackground	XmCBackground	Pixel	dynamic	CSG
XmNbackgroundPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderColor	XmCBorderColor	Pixel	XtDefaultForeground	CSG
XmNborderPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderWidth	XmCBorderWidth	Dimension	0	CSG
XmNcolormap	XmCColormap	Colormap	dynamic	CG
XmNdepth	XmCDepth	int	dynamic	CG
XmNdestroyCallback	XmCCallback	XtCallbackList	NULL	C
XmNheight	XmCHeight	Dimension	dynamic	CSG
XmNinitialResourcesPersistent	XmCInitialResourcesPersistent	Boolean	True	C
XmNmappedWhenManaged	XmCMappedWhenManaged	Boolean	True	CSG
XmNscreen	XmCScreen	Screen *	dynamic	CG
XmNsensitive	XmCSensitive	Boolean	True	CSG
XmNtranslations	XmCTranslations	XtTranslations	dynamic	CSG
XmNwidth	XmCWidth	Dimension	dynamic	CSG
XmNx	XmCPosition	Position	0	CSG
XmNy	XmCPosition	Position	0	CSG

Callback Information

A pointer to the following callback structure is passed to the XmNdestinationCallback procedures:

typedef struct
{
        int                                                                                                                                                                                                                                       
reason;
        XEvent                                                                                                                                                                                                                                    *                                                                                                                                                                                                                                                 
event;
        Atom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
selection;
        XtEnum                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      
operation;
        int                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         
flags;
        XtPointer                                                                                                                                                                                                                                 
transfer_id;
        XtPointer                                                                                                                                                                                                                                 
destination_data;
        XtPointer                                                                                                                                                                                                                                 
location_data;
        Time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
time;
} XmDestinationCallbackStruct;

reason

Indicates why the callback was invoked.

event

Points to the XEvent that triggered the callback. It can be NULL.

selection

Indicates the selection for which data transfer is being requested. Possible values are CLIPBOARD, PRIMARY, and _MOTIF_DROP.

operation

Indicates the type of transfer operation requested.

When the selection is PRIMARY, possible values are XmMOVE, XmCOPY, and XmLINK.

When the selection is CLIPBOARD, possible values are XmCOPY and XmLINK.

When the selection is _MOTIF_DROP, possible values are XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of XmOTHER means that the callback procedure must get further information from the XmDropProcCallbackStruct in the destination_data member.

flags

Indicates whether or not the destination widget is also the source of the data to be transferred. Following are the possible values:

XmCONVERTING_NONE

The destination widget is not the source of the data to be transferred.

XmCONVERTING_SAME

The destination widget is the source of the data to be transferred.

transfer_id

Serves as a unique ID to identify the transfer transaction.

destination_data

Contains information about the destination. When the selection is _MOTIF_DROP, the callback procedures are called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. Otherwise, destination_data is NULL.

location_data

Contains information about the location where data is to be transferred. The value is always NULL when the selection is SECONDARY or CLIPBOARD. If the value is NULL, the data is to be inserted at the widget's cursor position. The value of location_data is only valid for the duration of a transfer. Once transfer done procedures start to be called, location_data will no longer be stable.

time

Indicates the time when the transfer operation began.

Translations

ExmStringTransfer provides the following translations:

EnterWindow:

PrimitiveEnter()

LeaveWindow:

PrimitiveLeave()

c <Btn1Down>:

ExmStringTransferMoveFocus()

Btn1Down:

ExmStringTransferMoveFocus() ExmStringTransferCopyPrimary()

Btn2Down:

ExmStringTransferProcessDrag()

:<Key>osfPaste:

ExmStringTransferPasteClipboard()

:<Key>osfCut:

ExmStringTransferCopyClipboard()

:s <Key>osfInsert:

ExmStringTransferPasteClipboard()

:s <Key>osfDelete:

ExmStringTransferCopyClipboard()

:<Key>osfActivate:

PrimitiveParentActivate()

:<Key>osfCancel:

PrimitiveParentCancel()

:<Key>osfHelp:

PrimitiveHelp()

~s ~m ~a <Key>Return:XS

PrimitiveParentActivate()

Action Routines

All the actions that begin with the Primitive prefix are defined by the XmPrimitive widget. (See the XmPrimitive(3) reference page of the Motif Programmer's Reference for details.) The actions defined by ExmStringTransfer are as follows:

ExmStringTransferCopyClipboard() :

If this widget owns the primary selection, this action copies the contents of ExmNcompoundString to the clipboard. This action calls the XmNconvertCallback procedures, possibly multiple times, for the CLIPBOARD selection.

ExmStringTransferCopyPrimary() :

Calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmCOPY operation. It calls the selection owner's XmNconvertCallback procedures, possibly multiple times, for the PRIMARY selection.

ExmStringTransferMoveFocus() :

Causes the widget to take keyboard focus, without activating the widget. This action does not change the selection; it merely changes the keyboard focus.

ExmStringTransferPasteClipboard() :

Pastes the contents of the clipboard into the widget, overwriting any text that was previously displayed. This action calls any XmNdestinationCallback procedures registered, passing CLIPBOARD in the selection member of the XmDestinationCallbackStruct. The pasted text becomes the new value of the ExmNcompoundString resource.

ExmStringTransferPastePrimary() :

Pastes the primary selection into the specified widget. This action overwrites any text that was previously displayed. The pasted text becomes the new value of the ExmNcompoundString resource.

ExmStringTransferProcessDrag() :

Drags the contents of the ExmNcompoundString resource. This action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures, possibly multiple times, for the _MOTIF_DROP selection.

Virtual Bindings

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

RELATED

Core(3), ExmSimple(3), ExmString(3), XmPrimitive(3), and XmQTtransfer(3).