ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
NAME
ExmStringTransfer - The StringTransfer widget class
SYNOPSIS
#include <Exm/StringTrans.h>
VERSION
This page documents Motif 2.1.
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:
o XmNdestinationCallback, which allows applications to
intercede a data transfer on behalf of the destination
widget.
o 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.
Page 1 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
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.
Page 2 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
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:
1. _MOTIF_COMPOUND_STRING
2. TEXT
3. COMPOUND_TEXT
4. The encoding of the locale
5. 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:
Page 3 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
1. _MOTIF_COMPOUND_STRING
2. COMPOUND_TEXT
3. 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
Page 4 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
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
Page 5 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
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.
o When the selection is PRIMARY, possible
values are XmMOVE, XmCOPY, and XmLINK.
o When the selection is CLIPBOARD, possible
values are XmCOPY and XmLINK.
o 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
Page 6 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
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_datais 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()
Page 7 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
: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 Referencefor
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
Page 8 (printed 7/20/06)
ExmStringTransfer(3X) UNIX System V ExmStringTransfer(3X)
becomes the new value of the
ExmNcompoundStringresource.
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 ExmNcompoundStringresource.
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).
Page 9 (printed 7/20/06)
