<!-- $XConsortium: DragIcon.sgm /main/9 1996/09/08 20:39:59 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->

<RefEntry Id="CDEMMA.MAN207.rsml.1">
<RefMeta>
<RefEntryTitle>XmDragIcon</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Classname>XmDragIcon</Classname></RefName>
<RefPurpose>The DragIcon widget class
<IndexTerm>
<Primary>XmDragIcon</Primary>
</IndexTerm><IndexTerm>
<Primary>widget class</Primary>
<Secondary>DragIcon</Secondary>
</IndexTerm></RefPurpose>
</RefNameDiv>
<!-- -->
<!-- @OSF_COPYRIGHT@-->
<!-- COPYRIGHT NOTICE-->
<!-- Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.-->
<!-- ALL RIGHTS RESERVED (MOTIF). See the file named COPY.MOTIF.DOC for-->
<!-- the full copyright text.-->
<!-- -->
<!-- HISTORY-->
<!-- -->
<!-- **-->
<!-- **-->
<!-- **  (c) Copyright 1991, 1992 by Open Software Foundation, Inc.-->
<!-- **      All Rights Reserved.-->
<!-- **-->
<!-- **  (c) Copyright 1991 by Hewlett-Packard Company-->
<!-- **-->
<!-- **-->
<RefSynopsisDiv>
<Synopsis>&npzwc;#include &lt;Xm/DragDrop.h>
</Synopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>A DragIcon is a component of the visual used to represent the source
data in a drag and drop transaction. During a drag operation, a real
or simulated X cursor provides drag-over visuals consisting of a
static portion that represents the object being dragged, and dynamic
cues that provide visual feedback during the drag operation. The
visual is attained by blending together various <Symbol>XmDragIcons</Symbol>
specified in the <Classname>XmDragContext</Classname> associated with the drag
operation.
</Para>
<Para>The static portion of the drag-over visual is the graphic
representation that identifies the drag source. For example,
when a user drags several items within a list, a DragIcon depicting a
list might be supplied as the visual. The <Classname>XmDragContext</Classname>
resources, <SystemItem Class="Resource">XmNsourceCursorIcon</SystemItem> or <SystemItem Class="Resource">XmNsourcePixmapIcon</SystemItem>,
specify a DragIcon to use for the static portion of the visual.
</Para>
<Para>A drag-over visual incorporates dynamic cues in order to provide
visual feedback in response to the user's actions. For instance,
the drag-over visual might use different indicators to identify
the type of operation (copy, link, or move) being performed. Dynamic
cues could also alert the user that a drop site is valid or invalid
as the pointer traverses the drop site. The <SystemItem Class="Resource">XmNoperationCursorIcon</SystemItem>
and <SystemItem Class="Resource">XmNstateCursorIcon</SystemItem> resources of <Classname>XmDragContext</Classname> specify
DragIcons for dynamic cues.
</Para>
<Para>A drag-over visual typically consists of a source, operation and
state DragIcon. The <SystemItem Class="Resource">XmNblendModel</SystemItem> resource of <Classname>XmDragContext</Classname>
offers several options that determine which icons are blended
to produce the drag-over visual. DragIcon resources control
the relative position of the operation and state icons (if used).
If a particular DragIcon is not specified, the toolkit uses the
<Classname>XmScreen</Classname> default DragIcons.
</Para>
<Para>An application initializes a DragIcon with the function
<Function>XmCreateDragIcon</Function> or through entries in the resource
database. If a pixmap and its mask (optional) are specified
in the resource database, the toolkit converts the
values in the X11 Bitmap file format and assigns values to
the corresponding resources.
</Para>
<RefSect2>
<Title>Classes</Title>
<Para>DragIcon inherits behavior and a resource from <Classname>Object</Classname>.
</Para>
<Para>The class pointer is <Symbol Role="Globalvar">xmDragIconObjectClass</Symbol>.
</Para>
<Para>The class name is <Classname>XmDragIcon</Classname>.
</Para>
</RefSect2>
<RefSect2>
<Title>New Resources</Title>
<Para>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 <Filename>.Xdefaults</Filename> file, remove the <SystemItem Class="Constant">XmN</SystemItem> or <SystemItem Class="Constant">XmC</SystemItem> prefix and use
the remaining letters. To specify one of the defined values for a
resource in a <Filename>.Xdefaults</Filename> file, remove the <SystemItem Class="Constant">Xm</SystemItem> 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 <Function>XtSetValues</Function> (S), retrieved by using
<Function>XtGetValues</Function> (G), or is not applicable (N/A).
</Para>
<Para><!-- --><!-- @OSF_COPYRIGHT@--><!-- COPYRIGHT NOTICE--><!-- Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.--><!-- ALL RIGHTS RESERVED (MOTIF). See the file named COPY.MOTIF.DOC for--><!-- the full copyright text.--><!-- --><!-- HISTORY--><!-- --></Para>
<InformalTable Frame="All" Remap="center" Orient="Port">
<TGroup Cols="5">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="1">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="2">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="3">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="4">
<ColSpec Rowsep="1" Align="Left" Colname="5">
<TBody>
<Row>
<Entry Align="Center" Nameend="5" Namest="1"><Literal>XmDragIcon Resource Set</Literal></Entry>
</Row>
<Row>
<Entry Rowsep="1"><Literal>Name</Literal></Entry>
<Entry Rowsep="1"><Literal>Class</Literal></Entry>
<Entry Rowsep="1"><Literal>Type</Literal></Entry>
<Entry Rowsep="1"><Literal>Default</Literal></Entry>
<Entry Rowsep="1"><Literal>Access</Literal></Entry>
</Row>
<Row>
<Entry>XmNattachment</Entry>
<Entry>XmCAttachment</Entry>
<Entry>unsigned char</Entry>
<Entry>XmATTACH_NORTH_WEST</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNdepth</Entry>
<Entry>XmCDepth</Entry>
<Entry>int</Entry>
<Entry>1</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNheight</Entry>
<Entry>XmCHeight</Entry>
<Entry>Dimension</Entry>
<Entry>0</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNhotX</Entry>
<Entry>XmCHot</Entry>
<Entry>Position</Entry>
<Entry>0</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNhotY</Entry>
<Entry>XmCHot</Entry>
<Entry>Position</Entry>
<Entry>0</Entry>
<Entry>CSG
<!-- WARNING: ghost column #6:  --></Entry>
</Row>
<Row>
<Entry>XmNmask</Entry>
<Entry>XmCPixmap</Entry>
<Entry>Pixmap</Entry>
<Entry>XmUNSPECIFIED_PIXMAP</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNoffsetX</Entry>
<Entry>XmCOffset</Entry>
<Entry>Position</Entry>
<Entry>0</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNoffsetY</Entry>
<Entry>XmCOffset</Entry>
<Entry>Position</Entry>
<Entry>0</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNpixmap</Entry>
<Entry>XmCPixmap</Entry>
<Entry>Pixmap</Entry>
<Entry>XmUNSPECIFIED_PIXMAP</Entry>
<Entry>CSG</Entry>
</Row>
<Row>
<Entry>XmNwidth</Entry>
<Entry>XmCWidth</Entry>
<Entry>Dimension</Entry>
<Entry>0</Entry>
<Entry>CSG</Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<VariableList>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNattachment</SystemItem></Term>
<ListItem>
<Para>Specifies a relative location on the source icon for the attachment of
the state or operation icon. The origin of the state and operation
icons is aligned with the specified compass point on the source icon.
The <SystemItem Class="Resource">XmNoffsetX</SystemItem> and <SystemItem Class="Resource">XmNoffsetY</SystemItem> resources can be used to further
refine the icon positions. The possible values are
</Para>
<VariableList>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_NORTH_WEST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the northwest
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_NORTH</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the north
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_NORTH_EAST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the northeast
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_EAST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the east
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_SOUTH_EAST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the southeast
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_SOUTH</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the south
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_SOUTH_WEST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the southwest
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_WEST</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the west
point on the source icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_CENTER</SystemItem></Term>
<ListItem>
<Para>Attaches the origin of the state or operation icon to the
center of the source icon. The <SystemItem Class="Resource">XmNoffsetX</SystemItem> and <SystemItem Class="Resource">XmNoffsetY</SystemItem>
resources may be used to center the attached icon.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Constant">XmATTACH_HOT</SystemItem></Term>
<ListItem>
<Para>Attaches the hotspot coordinates of a state or operation DragIcon to
an x,y position on the source icon. The x,y coordinate
is taken from the event passed to the <Function>XmDragStart</Function> function,
and made relative to the widget passed as an argument to the same
function.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNdepth</SystemItem></Term>
<ListItem>
<Para>Specifies the depth of the pixmap.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNheight</SystemItem></Term>
<ListItem>
<Para>Specifies the height of the pixmap.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNhotX</SystemItem></Term>
<ListItem>
<Para>Specifies the x-coordinate of the hotspot of a cursor DragIcon
in relation to the origin of the pixmap bounding box.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNhotY</SystemItem></Term>
<ListItem>
<Para>Specifies the y-coordinate of the hotspot of a cursor DragIcon
in relation to the origin of the pixmap bounding box.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNmask</SystemItem></Term>
<ListItem>
<Para>Specifies a pixmap of depth 1 to use as the DragIcon mask
pixmap.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNoffsetX</SystemItem></Term>
<ListItem>
<Para>Specifies a horizontal offset (in pixels) of the origin of the state
or operation icon relative to the attachment point on the source icon.
A positive offset value moves the origin to the right; a negative value
moves the origin to the left.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNoffsetY</SystemItem></Term>
<ListItem>
<Para>Specifies a vertical offset (in pixels) of the origin of the state or
operation icon relative to the attachment point on the source icon. A
positive offset value moves the origin down; a negative value moves the
origin up.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNpixmap</SystemItem></Term>
<ListItem>
<Para>Specifies a pixmap to use as the DragIcon pixmap.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><SystemItem Class="Resource">XmNwidth</SystemItem></Term>
<ListItem>
<Para>Specifies the width of the pixmap.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect2>
<RefSect2>
<Title>Inherited Resources</Title>
<Para>DragIcon inherits behavior and a resource from <Classname>Object</Classname>.
For a complete description of this resource, refer to the
<Classname>Object</Classname> reference page.
</Para>
<Para><!-- --><!-- @OSF_COPYRIGHT@--><!-- COPYRIGHT NOTICE--><!-- Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.--><!-- ALL RIGHTS RESERVED (MOTIF). See the file named COPY.MOTIF.DOC for--><!-- the full copyright text.--><!-- --><!-- HISTORY--><!-- --></Para>
<InformalTable Frame="All" Remap="center" Orient="Port">
<TGroup Cols="5">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="1">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="2">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="3">
<ColSpec Rowsep="1" Colsep="1" Align="Left" Colname="4">
<ColSpec Rowsep="1" Align="Left" Colname="5">
<TBody>
<Row>
<Entry Align="Center" Nameend="5" Namest="1"><Literal>Object Resource Set</Literal></Entry>
</Row>
<Row>
<Entry Rowsep="1"><Literal>Name</Literal></Entry>
<Entry Rowsep="1"><Literal>Class</Literal></Entry>
<Entry Rowsep="1"><Literal>Type</Literal></Entry>
<Entry Rowsep="1"><Literal>Default</Literal></Entry>
<Entry Rowsep="1"><Literal>Access</Literal></Entry>
</Row>
<Row>
<Entry>XmNdestroyCallback</Entry>
<Entry>XmCCallback</Entry>
<Entry>XtCallbackList</Entry>
<Entry>NULL</Entry>
<Entry>C</Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>RELATED INFORMATION</Title>
<Para>&cdeman.Object;,
&cdeman.XmCreateDragIcon;,
&cdeman.XmDisplay;,
&cdeman.XmDragContext;,
&cdeman.XmDropSite;,
&cdeman.XmDropTransfer;, and
&cdeman.XmScreen;.
</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.09 7/2/95-->
