ExmStringTransfer — The StringTransfer widget class
#include <Exm/StringTrans.h> |
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.
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
ExmStringTransfer inherits behavior and resources from Core, XmPrimitive, ExmSimple, and ExmString.
The class pointer is exmStringTransferWidgetClass.
The class name is ExmStringTransfer.
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. |
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 |
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.
| |||||||
| flags | Indicates whether or not the destination widget is also the source of the data to be transferred. Following are the possible values:
| |||||||
| 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. |
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() |
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. |
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3).
Core(3), ExmSimple(3), ExmString(3), XmPrimitive(3), and XmQTtransfer(3).